Photon Collection models#

Photon generation models are used to add and manipulate data in Photon array inside the Detector object. If the scene generation model group is used, a model like Simple collection needs to be enabled in the pipeline to make the conversion from Scene to Photon. Otherwise, models like Simple illumination or Load image need to be enabled to initialize the Photon array. Multiple photon generation models can be linked together one after another. The values in the Photon array represent photon flux, i.e. number of photons per pixel area per second. The time scale of the incoming flux can be changed in the model arguments.

Create and Store a detector#

The models Save detector and Load detector can be used respectively to create and to store a Detector to/from a file.

These models can be used when you want to store or to inject a Detector into the current Pipeline.

Save detector#

This model saves the current Detector into a file. Accepted file formats are .h5, .hdf5, .hdf and .asdf.

- name: save_detector
  func: pyxel.models.save_detector
  enabled: true
  arguments:
    filename: my_detector.h5
pyxel.models.save_detector(detector, filename)[source]#

Save the current detector into a file.

Load detector#

This model loads a Detector from a file and injects it in the current pipeline. Accepted file formats are .h5, .hdf5, .hdf and .asdf.

- name: load_detector
  func: pyxel.models.load_detector
  enabled: true
  arguments:
    filename: my_detector.h5
pyxel.models.load_detector(detector, filename)[source]#

Load a new detector from a file.

Raises:

TypeError – If the loaded detector has not the same type of the current detector.

Simple collection#

Note

This model operates with both multi-wavelength and monochromatic photons.

ScenePhoton

Converts scene to photon using a given aperture. Initially, a xarray Dataset is extracted from the Scene for a selected wavelength band. The filter_band input represents the wavelength range of the selected filter band. By default, the filter_band argument in nm is None, and the information is retrieved from the detector properties in the YAML configuration file, where cut_on and cut_off wavelengths can be defined in the Environment. However, you can override this property by providing the filter_band as a model argument.

This model supports both monochromatic or multi-wavelength modes, generating a 2D Photon array or 3D Photon array as output, whereas the 3D Photon array includes the wavelength dimension. When integrate_wavelength is set to true (default) the monochromatic mode is selected, where the flux of objects in the scene is integrated across the wavelength band. The integrated flux in photon/(scm2) is then converted to photon/(spixel). When integrate_wavelength set to false, the photons are represented with dimensions “wavelength”, “y”, and “x”.

The objects are projected onto the detector, with object coordinates converted from arcsec to detector coordinates (pixel) using the pixel_scale in arseconds/pixel. By default pixel_scale is None, and the model retrieves the pixel_scale defined in the Geometry. However, it is possible to override this property by providing pixel_scale as model argument.

- name : simple_collection
 func: pyxel.models.photon_collection.simple_collection
 enabled: true
 arguments:
   aperture: 126.70e-3 #m
   filter_band: [400, 500] #nm
   pixel_scale: 1.65 #arcsec/pixel
   integrate_wavelength: true
pyxel.models.photon_collection.simple_collection(detector, aperture, filter_band=None, resolution=None, pixel_scale=None, integrate_wavelength=True)[source]#

Convert scene in ph/(cm2 nm s) to photon in ph/nm s or ph s.

Parameters:
  • detector (Detector) – Pyxel detector object.

  • aperture (float) – Collecting area of the telescope. Unit: m.

  • filter_band (Union[tuple[float, float], None]) – Wavelength range of selected filter band, default is None. Unit: nm.

  • resolution (Optional[int]) – Resolution of provided wavelength range in filter band. Unit: nm.

  • pixel_scale (float, optional) – Pixel scale of detector, default is None. Unit: arcsec/pixel.

  • integrate_wavelength (bool) – If true, integrates along the wavelength else multiwavelength, default is True.

Load image#

PhotonPhoton

With this model you can add photons to Detector by loading an image from a file. Accepted file formats are .npy, .fits, .txt, .data, .jpg, .jpeg, .bmp, .png and .tiff. Use argument position to set the offset from the (0,0) pixel and set where the input image is placed onto detector. You can preset positions with argument align. Values outside of the detector shape will be cropped. Read more about placement in the documentation of function fit_into_array(). With multiplier you can multiply the photon number by a custom float, and time_scale is to set the time scale of the incoming photons, default is 1 second. By setting convert_to_photons to true together with bit_resolution, the model converts the values of loaded image array from ADU to photon numbers for each pixel using the Photon Transfer Function. PTF=quantum_efficiencycharge_to_voltage_conversionpre_amplificationadc_factor.

ADC conversion factor in this case is max(characteristicsvoltage_range)2bit_resolution.

Example of the configuration file:

- name: load_image
  func: pyxel.models.photon_collection.load_image
  enabled: true
  arguments:
    image_file: data/HorseHead.fits
    position: [0,0]
    convert_to_photons: true
    bit_resolution: 16
pyxel.models.photon_collection.load_image(detector, image_file, include_header=False, header_section_index=None, position=(0, 0), align=None, convert_to_photons=False, multiplier=1.0, time_scale=1.0, bit_resolution=None)[source]#

Load FITS file as a numpy array and add to the detector as input image.

Parameters:
  • detector (Detector)

  • image_file (str) – Path to image file.

  • include_header (bool, optional.) – If True, extract header metadata from the image file. This parameter is provisional and may be removed.

  • header_section_index (int or str or None, optional) – Section index or name of the header data to load if include_header is enabled. This parameter is provisional and may be removed.

  • position (tuple) – Indices of starting row and column, used when fitting image to detector.

  • align (Literal) – Keyword to align the image to detector. Can be any from: (“center”, “top_left”, “top_right”, “bottom_left”, “bottom_right”)

  • convert_to_photons (bool) – If True, the model converts the values of loaded image array from ADU to photon numbers for each pixel using the Photon Transfer Function: PTF=quantum_efficiencycharge_to_voltage_conversionpre_amplificationadc_factor.

  • multiplier (float) – Multiply photon array level with a custom number.

  • time_scale (float) – Time scale of the photon flux, default is 1 second. 0.001 would be ms.

  • bit_resolution (int) – Bit resolution of the loaded image.

Notes

The image array is cropped and aligned based on the shape and position parameters and is scaled by the multiplier and time_scale before being added to the detector.

If include_header is enabled, the header metadata is extracted from image_file and store in the detector`s header storage.

Usaf illumination#

PhotonPhoton

With this model you can load a standard USAF-1951 illumination pattern to test your detector with. It uses the above-mentioned load_image model to load a .png version of the pattern stored in the pyxel-data repository. You can check the arguments specification in Load image for more information on setting up the model.

Example of the configuration file:

- name: usaf_illumination
  func: pyxel.models.photon_collection.usaf_illumination
  enabled: true
  arguments:
    position: [0,0]
    convert_to_photons: true
    bit_resolution: 16
pyxel.models.photon_collection.usaf_illumination(detector, position=(0, 0), align=None, convert_to_photons=False, multiplier=1.0, time_scale=1.0, bit_resolution=None)[source]#

Apply USAF-1951 illumination pattern.

Parameters:
  • detector (Detector)

  • position (tuple) – Indices of starting row and column, used when fitting image to detector.

  • align (Literal) – Keyword to align the image to detector. Can be any from: (“center”, “top_left”, “top_right”, “bottom_left”, “bottom_right”)

  • convert_to_photons (bool) – If True, the model converts the values of loaded image array from ADU to photon numbers for each pixel using the Photon Transfer Function: PTF=quantum_efficiencycharge_to_voltage_conversionpre_amplificationadc_factor.

  • multiplier (float) – Multiply photon array level with a custom number.

  • time_scale (float) – Time scale of the photon flux, default is 1 second. 0.001 would be ms.

  • bit_resolution (int) – Bit resolution of the loaded image.

Simple illumination#

PhotonPhoton

With this model you can create different simple photon distributions: uniform, elliptical/circular or rectangular, by setting the argument type. The calculated photon count will be added to the Photon array. User can specify the brightness of the object with the argument level. If the distribution is not uniform, then the user also has to provide object_size, a list of tho integers, which are the diameters of the object in vertical and horizontal directions. Object position can be changed with the argument object_position, a list of two integers specifying offset of the object center from pixel (0,0), again in vertical and horizontal direction. Use the argument time_scale to set the time scale of the incoming photon flux.

Example of the configuration file for a circular object:

- name: illumination
  func: pyxel.models.photon_collection.illumination
  enabled: true
  arguments:
      level: 500
      object_center: [250,250]
      object_size: [15,15]
      option: "elliptic"
pyxel.models.photon_collection.illumination(detector, level, option='uniform', object_size=None, object_center=None, time_scale=1.0)[source]#

Generate photon uniformly over the entire array or over an elliptic or rectangular object.

Parameters:
  • detector (Detector) – Pyxel Detector object.

  • level (float) – Flux of photon per pixel.

  • option (str) – A string indicating the type of illumination:

    • uniform: Uniformly fill the entire array with photon. (Default)

    • elliptic: Mask with elliptic object.

    • rectangular: Mask with rectangular object.

  • object_size (list or tuple, optional) – List or tuple of length 2, integers defining the diameters of the elliptic or rectangular object in vertical and horizontal directions.

  • object_center (list or tuple, optional) – List or tuple of length 2, two integers (row and column number), defining the coordinates of the center of the elliptic or rectangular object.

  • time_scale (float) – Time scale of the photon flux, default is 1 second. 0.001 would be ms.

Stripe pattern#

PhotonPhoton

With this model you can add a two-dimensional square signal - a stripe pattern to the Photon array. User can specify amplitude with argument level, the period of the square signal in unit of pixels and the angle of stripes. The period should be a multiple of 2 and equal or larger than 2. Argument startwith is used to flip zero and non-zero values.

Example of the configuration file:

- name: stripe_pattern
  func: pyxel.models.photon_collection.stripe_pattern
  enabled: true
  arguments:
    level: 1000
    period: 10
    startwith: 0
    angle: 5
pyxel.models.photon_collection.stripe_pattern(detector, period=10, level=1.0, angle=0, startwith=0, time_scale=1.0)[source]#

Stripe pattern model.

Parameters:
  • detector (Detector) – Detector object.

  • period (int) – Period of the periodic pattern in pixels.

  • level (float) – Amplitude of the periodic pattern.

  • angle (int) – Angle of the pattern in degrees.

  • startwith (int) – 1 to start with high level or 0 for 0.

  • time_scale (float) – Time scale of the photon flux, default is 1 second. 0.001 would be ms.

Shot noise#

PhotonPhoton

Use this model to add shot noise to the Photon array. By default (no arguments provided), the model uses the Poisson distribution (numpy.random.poisson). User can also set the argument type to "normal" for normal distribution (numpy.random.normal). As known, for large photon counts N the Poisson distribution approaches the normal distribution with standard deviation N, which is fixed in the model. It is also possible to set the seed of the random generator with the argument seed.

Example of the configuration file:

- name: shot_noise
  func: pyxel.models.photon_collection.shot_noise
  enabled: true
  arguments:
    type: "poisson"  # optional
pyxel.models.photon_collection.shot_noise(detector, type='poisson', seed=None)[source]#

Add shot noise to the flux of photon per pixel. It can be either Poisson noise or Gaussian.

Parameters:
  • detector (Detector) – Pyxel Detector object.

  • type (str, optional) – Choose either ‘poisson’ or ‘normal’. Default is Poisson noise.

  • seed (int, optional) – Random seed.

Physical Optics Propagation in PYthon (POPPY)#

Note

This model operates with both multi-wavelength and monochromatic photons.

PhotonPhoton

POPPY (Physical Optics Propagation in PYthon) model wrapper.

POPPY [10] simulated physical optical propagation including diffraction. It implements a flexible framework for modeling Fraunhofer and Fresnel diffraction and point spread function formation, particularly in the context of astronomical telescopes.

POPPY calculates the optical Point Spread Function of an optical system and applies the convolution. It requires the Field of View (FOV) in arcsec (fov_arcsec) and the optical_system as arguments. By default, the model uses pixel_scale in arseconds/pixel and wavelength in nm, which are extracted from the detector properties in the YAML configuration file. However, you can override these properties by providing them as model arguments.

The wavelength input can either be a float for a monochromatic PSF or a tuple for a multi-wavelength PSF calculations. Additionally, the ThinLens optical parameter offers an optional argument reference_wavelength, which, if provided, overrides the input wavelength for a single float or calculates the middle wavelength for a range.

When apply_jitter is set to true (default is false), pointing jitter will be applied using a Gaussian kernel to convolve with the PSF. The width of the jitter kernel is defined by jitter sigma in arcsec per axis, with a default value of 0.007 arcsec.

See details about POPPY Optical Element classes: https://poppy-optics.readthedocs.io/en/stable/available_optics.html

Poppy

POPPY (Physical Optics Propagation in Python), Credit: STScI#

Supported optical elements:

  • CircularAperture

  • SquareAperture

  • RectangularAperture

  • HexagonAperture

  • MultiHexagonalAperture

  • ThinLens

  • SecondaryObscuration

  • ZernikeWFE

  • SineWaveWFE

Example of the configuration file:

- name: optical_psf
  func: pyxel.models.photon_collection.optical_psf
  enabled: true
  arguments:
    fov_arcsec: 5               # FOV in arcseconds
    wavelength: 600             # wavelength in nanometer
    apply_jitter: true
    jitter_sigma: 0.5
    optical_system:
      - item: CircularAperture
        radius: 3.0             # radius in meters
    optical_system:
      - item: CircularAperture
        radius: 1.5             # radius in meters
      - item: ThinLens
        radius: 1.2             # radius in meters
        nwaves: 1
        reference_wavelength: 600  # wavelength in nanometer
      - item: ZernikeWFE
        radius: 0.8             # radius in meters
        coefficients: [0.1e-6, 3.e-6, -3.e-6, 1.e-6, -7.e-7, 0.4e-6, -2.e-6]
        aperture_stop: false

Note

You can find examples of this model in these Jupyter Notebooks from Pyxel Data:

pyxel.models.photon_collection.optical_psf(detector, fov_arcsec, optical_system, wavelength=None, pixel_scale=None, apply_jitter=False, jitter_sigma=0.007, extract_psf=False)[source]#

Model function for poppy optics model: convolve photon array with psf.

Parameters:
  • detector (Detector) – Pyxel Detector object.

  • fov_arcsec (float) – Field Of View on detector plane in arcsec.

  • optical_system (list of dict) – List of optical elements before detector with their specific arguments.

  • wavelength (Union[float, tuple[float, float], None]) – Wavelength of incoming light in meters, default is None.

  • pixel_scale (float, Optional, default: None) – Pixel scale of detector in arcsec/pix.

  • apply_jitter (bool, default: False) – Defines whether jitter should be applied, default is False.

  • jitter_sigma (float) – Jitter sigma value in arcsec per axis, default is 0.007.

  • extract_psf (bool, default: False) – Copy the computed PSF into the data bucket detector.data['/photon_collection/optical_psf/[name of the model]/psf']

Notes

For more information, you can find examples here:

Load PSF#

PhotonPhoton

Load monochromatic PSF#

With this model you can load a Point Spread Function (PSF) from a file. The model will convolve the Photon array inside the Detector object with the loaded PSF, using the astropy.convolution.convolve_fft function.

Example of the configuration file:

- name: load_psf
  func: pyxel.models.photon_collection.load_psf
  enabled: true
  arguments:
    filename: "psf.npy"
    normalize_kernel: true  # optional

Note

You can find an example of this model used in this Jupyter Notebook Scene generation and projection from Pyxel Data.

pyxel.models.photon_collection.load_psf(detector, filename, normalize_kernel=True)[source]#

Load a point spread function from file and convolve the photon array with the PSF.

Parameters:
  • detector (Detector) – Pyxel Detector object.

  • filename (Path or str) – Input filename of the point spread function.

  • normalize_kernel (bool) – Normalize kernel.

Notes

For more information, you can find an example here: Scene generation and projection.

Load multi-wavelength PSF#

With this model you can load a Point Spread Function (PSF) from a file containing wavelength information. Currently, only .fits files are a valid input. The model will convolve the Photon array inside the Detector object with the loaded PSF, using the astropy.convolution.convolve_fft function.

Example of the configuration file:

- name: load_wavelength_psf
  func: pyxel.models.photon_collection.load_wavelength_psf
  enabled: true
  arguments:
    filename: "data/psf.fits"
    wavelength_col: "dim_0"
    x_col: "dim_2"
    y_col: "dim_1"
    wavelength_table_name: "waves"
    normalize_kernel: false  # optional
pyxel.models.photon_collection.load_wavelength_psf(detector, filename, wavelength_col, y_col, x_col, wavelength_table_name, normalize_kernel=True)[source]#

Read psf files depending on simulation and instrument parameters.

Parameters:
  • detector (Detector) – Pyxel Detector object.

  • filename (Path or str) – Input filename of the point spread function.

  • wavelength_col (str) – Dimension name in the file that contains the wavelength information.

  • y_col (str) – Dimension name in the file that contains the y information.

  • x_col (str) – Dimension name in the file that contains the x information.

  • wavelength_table_name (str) – Column name in the file that contains the wavelength information.

  • normalize_kernel (bool) – Normalize kernel.

Wavelength dependence AIRS#

Note

This model is specific for the CMOS detector.

PhotonPhoton

This model was specially developed for the ARIEL AIRS instrument. It generates the photon over the array according to a specific dispersion pattern loading the PSF from a file.

Example of the configuration file:

- name: wavelength_dependence_airs
  func: pyxel.models.photon_collection.wavelength_dependence_airs
  enabled: true
    psf_filename: "data/CH1_big_cube_PSFs.fits"
    target_filename: "data/target_flux_SED_00005.dat"
    telescope_diameter_m1: 1.1 #m
    telescope_diameter_m2: 0.7 #m
    expand_factor: 18
    time_scale:  1.0
pyxel.models.photon_collection.wavelength_dependence_airs(detector, psf_filename, target_filename, telescope_diameter_m1, telescope_diameter_m2, expand_factor, time_scale=1.0)[source]#

Generate the photon over the array according to a specific dispersion pattern (ARIEL-AIRS).

Parameters:
  • detector (Detector) – Pyxel Detector object.

  • psf_filename (string) – The location and the filename where the PSFs are located.

  • target_filename (string) – The location and the filename of the target file used in the simulation.

  • telescope_diameter_m1 (float) – Diameter of the M1 mirror of the TA in m.

  • telescope_diameter_m2 (float) – Diameter of the M2 mirror of the TA in m.

  • expand_factor (int) – Expansion factor used.

  • time_scale (float) – Time scale in seconds.