Introduction

Pyxel [1] is a novel, open-source, modular Python software framework designed to host and pipeline models (analytical, numerical, statistical) simulating different types of detector effects on images produced by Charge-Coupled Devices ( CCD ), Monolithic, and Hybrid CMOS imaging sensors.

Users can provide one or more input images to Pyxel, set the detector and model parameters via a user interface (configuration file) and select which effects to simulate: cosmic rays, detector Point Spread Function (PSF), electronic noises, Charge Transfer Inefficiency (CTI), persistence, dark current, charge diffusion, optical effects, etc. The output is one or more images including the simulated detector effects combined.

Examples of output images created using Pyxel. Left: original image; centre: tracks of cosmic ray protons have been added; right: in addition to the cosmic ray protons tracks the effects of lower full well capacity and charge transfer inefficiency have been added.

On top of its model hosting capabilities, the framework also provides a set of basic image analysis tools and an input image generator as well. It also features a parametric mode to perform parametric and sensitivity analysis, and a model calibration mode to find optimal values of its parameters based on a target dataset the model should reproduce.

A majority of Pyxel users are expected to be detector scientists and engineers working with instruments - using detectors - built for astronomy and Earth observation, who need to perform detector simulations, for example to understand laboratory data, to derive detector design specifications for a particular application, or to predict instrument and mission performance based on existing detector measurements.

One of the main purposes of this new tool is to share existing resources and avoid duplication of work. For instance, detector models developed for a certain project could be reused by other projects as well, making knowledge transfer easier.

Quickstart Setup

The best way to get started and learn Pyxel are the Tutorials and examples.

🚀 Recommended Quickstart Setup using uv 🚀

1. Install uv

The quickest way to install and start Pyxel is to use uv, an extremely fast Python package and project manager.

Warning

This installation method does not support Pyxel’s Calibration Mode feature on Windows or MacOS. For this, use the ‘miniconda’ installation method detailed below.

‘uv’ eliminated the need to manually download Python, set up a Python virtual environment, and to install Pyxel on it. It handled everything for you automatically.

To get started, install uv using the official standalone installer (see instructions here)

macOS and Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows

powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

After installation, restart or open a new command line terminal.

Tip

To update uv, run the following command:

$ uv self update

2. Verify Pyxel installation with uv

Check the current version of the latest Pyxel release by entering:

$ uvx pyxel-sim --version
pyxel-sim, version 2.5.1
Python (CPython) 3.11.9

3. Download the Tutorial Notebooks

Then you can download the Pyxel Tutorial Notebooks into the pyxel-examples folder with the following commands:

$ uvx pyxel-sim download-examples
Downloading examples: 388MB [00:08, 47.9MB/s]
Done in folder /../pyxel-examples.

4. Run Pyxel with Jupyter lab

Then you can start a Jupyter Lab server with the latest version of Pyxel:

$ cd pyxel-examples
$ uvx --with pyxel-sim[model] --from jupyterlab jupyter-lab

Alternatively, start Jupyter Lab server with a specific version of Pyxel and Python:

$ cd pyxel-examples
$ uvx --python 3.11 --with "pyxel-sim[model]==2.5.1" --from jupyterlab jupyter-lab

Note

You can also run Pyxel with Spyder IDE:

$ cd pyxel-examples
$ uvx --with pyxel-sim[model] spyder

or with IPython:

$ cd pyxel-examples
$ uvx --with pyxel-sim[model] ipython

or directly from the command line:

$ cd pyxel-examples
$ cd tutorial
$ uvx pyxel-sim run exposure.yaml

🐌 Quickstart Setup with ‘normal’ installation with Miniconda 🐌

For convenience we provide a pre-defined conda environment file, so you can get additional useful packages together with Pyxel in a virtual isolated environment.

First install Miniconda and then just execute the following commands in the terminal:

Tip

Alternatively, you can use Mamba. Mamba is an alternative package manager that support most of conda’s command but offers higher installation speed and more reliable environment solutions. To install mamba in the Conda base environment:

conda install mamba -n base -c conda-forge

then you can replace command conda by mamba.

Linux, MacOS, Windows (WSL)

curl -O https://esa.gitlab.io/pyxel/doc/latest/pyxel-2.5.1-environment.yaml
conda env create -f pyxel-2.5.1-environment.yaml

Windows (Powershell)

wget https://esa.gitlab.io/pyxel/doc/latest/pyxel-2.5.1-environment.yaml -outfile "pyxel-2.5.1-environment.yaml"
conda env create -f pyxel-2.5.1-environment.yaml

Once the conda environment has been created you can active it using:

conda activate pyxel-2.5.1

You can now proceed to download the Pyxel tutorial notebooks. The total size to download is ~200 MB.

Select the location where you want to install the tutorials and datasets and proceed with the following command to download them in folder pyxel-examples:

pyxel download-examples

You can run Pyxel as a package if running it as a script does not work:

python -m pyxel download-examples

Finally start a notebook server by executing:

cd pyxel-examples
jupyter lab

Now, you can skip the installation guide Installation and go directly to the tutorials and explore the examples in Tutorials and examples to learn how to use Pyxel.

Getting started

Are you new to Pyxel ? This is the place to start !

1. Start with installation guide in Installation.

2. Once ready you can learn how to run Pyxel in Running Pyxel.

3. Don’t forget to take a look at Get Help page.

4. Follow the tutorials and explore the examples in Tutorials and examples to learn how to use Pyxel.