Effects Overview#

In ScopeSim, Effects are the building blocks of an optical system simulation. Each Effect object represents a single physical phenomenon – atmospheric seeing, mirror reflectivity, filter transmission, detector noise, and so on. An OpticalTrain collects all the effects from an instrument package and applies them in sequence to transform a Source (the on-sky light distribution) into a realistic detector readout.

Effects are typically defined in YAML instrument configuration files, but can also be created and added programmatically. Each effect implements an apply_to(obj) method that receives an object at a specific stage of the simulation pipeline and returns the modified object.

Listing Effects in an Optical Train#

To see all effects loaded in an optical train, use the .effects attribute:

import scopesim as sim

opt = sim.load_example_optical_train()
opt.effects

Table length=19

element	name	class	included
str16	str22	str29	bool
basic_atmosphere	atmospheric_radiometry	AtmosphericTERCurve	True
basic_telescope	psf	SeeingPSF	True
basic_telescope	telescope_reflection	TERCurve	True
basic_instrument	static_surfaces	SurfaceList	True
basic_instrument	filter_wheel : [J]	FilterWheel	True
basic_instrument	slit_wheel : [narrow]	SlitWheel	False
basic_instrument	image_slicer	ApertureList	False
basic_detector	detector_window	DetectorWindow	True
basic_detector	detector_3d	DetectorList3D	False
basic_detector	qe_curve	QuantumEfficiencyCurve	True
basic_detector	exposure_integration	ExposureIntegration	True
basic_detector	dark_current	DarkCurrent	True
basic_detector	shot_noise	ShotNoise	True
basic_detector	detector_linearity	LinearityCurve	True
basic_detector	readout_noise	PoorMansHxRGReadoutNoise	True
basic_detector	source_fits_keywords	SourceDescriptionFitsKeywords	True
basic_detector	effects_fits_keywords	EffectsMetaKeywords	True
basic_detector	config_fits_keywords	SimulationConfigFitsKeywords	True
basic_detector	extra_fits_keywords	ExtraFitsKeywords	True

The Simulation Pipeline#

ScopeSim processes effects in a strict order determined by each effect’s z_order — a numerical priority that maps to a specific pipeline stage. Effects with lower z_order values run first. Each effect’s z_order can contain multiple values, allowing it to participate in more than one stage (e.g., setup and application).

The pipeline has three main phases:

        %%{init: {"theme": "dark"} }%%
flowchart LR
    subgraph Setup ["Setup Phase"]
        direction TB
        S1["FOV Setup<br/>z = 200..299"]
        S2["Image Plane Setup<br/>z = 300..399"]
        S3["Detector Setup<br/>z = 400..499"]
        S1 --> S2 --> S3
    end
    subgraph Observe ["observe() Phase"]
        direction TB
        O1["Source Effects<br/>z = 500..599<br/><i>TER curves, filters</i>"]
        O2["FOV Effects<br/>z = 600..699<br/><i>PSFs, spectral traces, shifts</i>"]
        O3["Image Plane Effects<br/>z = 700..799<br/><i>Vibration, flat fields</i>"]
        O1 --> O2 --> O3
    end
    subgraph Readout ["readout() Phase"]
        direction TB
        R1["Detector Effects<br/>z = 800..899<br/><i>Noise, dark current, QE</i>"]
        R2["Detector Array Effects<br/>z = 900..999<br/><i>Exposure integration</i>"]
        R3["FITS Header Effects<br/>z = 1000+"]
        R1 --> R2 --> R3
    end
    S3 --> O1
    O3 --> R1

Z-Order Reference#

Z-Order Range	Pipeline Stage	Applied To	OpticsManager Property
200–299	FOV setup	`FovVolumeList`	`fov_setup_effects`
300–399	Image plane setup	`FovVolumeList`	`image_plane_setup_effects`
400–499	Detector setup	`FovVolumeList`	`detector_setup_effects`
500–599	Source effects	`Source`	`source_effects`
600–699	FOV effects	`FieldOfView`	`fov_effects`
700–799	Image plane effects	`ImagePlane`	`image_plane_effects`
800–899	Detector effects	`Detector`	`detector_effects`
900–999	Detector array effects	`Detector`	`detector_array_effects`
1000+	FITS header effects	`HDUList`	`fits_header_effects`

YAML Configuration#

Effects are typically defined in YAML instrument packages. Each effect entry specifies the class name and configuration parameters:

effects:
  - name: detector_qe_curve
    description: Quantum efficiency of the battery of detectors
    class: QuantumEfficiencyCurve
    kwargs:
      filename: QE_detector_H2RG.dat

  - name: dark_current
    description: Detector dark current
    class: DarkCurrent
    kwargs:
      value: 0.1       # electrons/s/pixel

  - name: filter_wheel
    class: FilterWheel
    kwargs:
      current_filter: "!OBS.filter_name"
      filter_names: [J, H, Ks]
      filename_format: "filters/TC_filter_{}.dat"

Parameters prefixed with ! (called bang strings) are resolved dynamically from the simulation configuration at runtime. For example, !OBS.filter_name reads the current filter selection from the observation commands.

Note

For real-world examples of YAML effect configurations, browse the instrument packages in the Instrument Reference Database (IRDB). If you have instrument packages installed locally, you can also look inside the inst_pkgs/ folder in your ScopeSim data directory (see scopesim.rc.__config__["!SIM.file.local_packages_path"]).

Interacting with Effects at Runtime#

Effects can be accessed, toggled, and modified after the optical train is loaded.

Enabling and disabling effects#

# Turn off an effect
opt["detector_linearity"].include = False
print("detector_linearity included:", opt["detector_linearity"].include)

# Turn it back on
opt["detector_linearity"].include = True

detector_linearity included: False

Inspecting effect metadata#

opt["dark_current"].meta

{'filename': None,
 'description': '',
 'history': [],
 'name': 'dark_current',
 'image_plane_id': 0,
 'temperature': -230,
 'dit': '!OBS.dit',
 'ndit': '!OBS.ndit',
 'width': 1024,
 'height': 1024,
 'x': 0,
 'y': 0,
 'element_name': 'basic_detector',
 'value': 0.1,
 'include': True,
 'cmds': CurrObs contents:

CurrSys contents:
├─OBS:
│ ├─instrument: basic_instrument
│ ├─psf_fwhm: 1.5
│ ├─modes: ['imaging']
│ ├─dit: 60
│ ├─ndit: 1
│ ├─slit_name: narrow
│ ├─wavelen: 2.1
│ ├─include_slit: False
│ ├─include_slicer: False
│ ├─include_det_window: True
│ ├─include_det_3d: False
│ └─filter_name: J
├─ATMO:
│ ├─background:
│ │ ├─filter_name: J
│ │ ├─value: 16.6
│ │ └─unit: mag
│ └─element_name: basic_atmosphere
├─TEL:
│ ├─telescope: Basic Telescope
│ ├─temperature: 0
│ ├─element_name: basic_telescope
│ ├─area: 0.19634954084936207 m2
│ └─etendue: 0.007853981633974483 arcsec2 m2
├─INST:
│ ├─temperature: -190
│ ├─pixel_scale: 0.2
│ ├─plate_scale: 20
│ └─element_name: basic_instrument
└─DET:
  ├─image_plane_id: 0
  ├─temperature: -230
  ├─dit: !OBS.dit
  ├─ndit: !OBS.ndit
  ├─width: 1024
  ├─height: 1024
  ├─x: 0
  ├─y: 0
  └─element_name: basic_detector

SystemDict contents:
├─SIM:
│ ├─spectral:
│ │ ├─wave_min: 0.3
│ │ ├─wave_mid: 2.2
│ │ ├─wave_max: 20
│ │ ├─wave_unit: um
│ │ ├─spectral_bin_width: 0.0001
│ │ ├─spectral_resolution: 5000
│ │ ├─minimum_throughput: 1e-06
│ │ └─minimum_pixel_flux: 1
│ ├─sub_pixel:
│ │ ├─flag: False
│ │ └─fraction: 1
│ ├─random:
│ │ └─seed: None
│ ├─computing:
│ │ ├─chunk_size: 2048
│ │ ├─max_segment_size: 16777217
│ │ ├─oversampling: 1
│ │ ├─spline_order: 1
│ │ ├─flux_accuracy: 0.001
│ │ ├─preload_field_of_views: False
│ │ └─nan_fill_value: 0.0
│ ├─file:
│ │ ├─example_data:
│ │ │ ├─suburl: example_data
│ │ │ └─hash_file: example_data_registry.txt
│ │ ├─psfs:
│ │ │ ├─suburl: psfs
│ │ │ └─hash_file: psfs_registry.txt
│ │ ├─atmo:
│ │ │ ├─suburl: atmo
│ │ │ └─hash_file: atmo_registry.txt
│ │ ├─local_packages_path: /home/docs/checkouts/readthedocs.org/user_builds/scopesim/checkouts/docs-effects-documentation/scopesim/tests/mocks
│ │ ├─server_base_url: https://scopesim.univie.ac.at/InstPkgSvr/
│ │ ├─retries: 3
│ │ ├─use_cached_downloads: False
│ │ ├─search_path: ['./inst_pkgs/', './']
│ │ └─error_on_missing_file: False
│ ├─reports:
│ │ ├─ip_tracking: False
│ │ ├─verbose: False
│ │ ├─rst_path: ./reports/rst/
│ │ ├─latex_path: ./reports/latex/
│ │ ├─image_path: ./reports/images/
│ │ ├─image_format: png
│ │ └─preamble_file: None
│ └─tests:
│   ├─run_integration_tests: True
│   └─run_skycalc_ter_tests: True
├─OBS:
├─TEL:
│ ├─etendue: 0
│ └─area: 0
└─INST:
  ├─pixel_scale: 0
  ├─plate_scale: 0
  └─decouple_detector_from_sky_headers: False}

Modifying parameters#

# Change the dark current value
opt["dark_current"].meta["value"] = 0.5
print("New dark current:", opt["dark_current"].meta["value"])

New dark current: 0.5

For more tips on interacting with effects, see:

Effect Categories#

Transmission, Emission, and Reflection (TER) Curves#

TER curves describe how optical surfaces transmit, emit, and reflect light as a function of wavelength. They are the most common type of effect and model everything from mirror coatings to atmospheric transmission to detector quantum efficiency.

Class	Description
`TERCurve`	Base wrapper for spectral transmission/emission/reflection curves
`SurfaceList`	Combines multiple optical surfaces into a system-level TER curve
`AtmosphericTERCurve`	Atmospheric transmission and emission
`SkycalcTERCurve`	Atmospheric TER from ESO’s SkyCalc service
`QuantumEfficiencyCurve`	Detector quantum efficiency vs wavelength
`FilterCurve`	Bandpass filter transmission from file
`TopHatFilterCurve`	Rectangular (top-hat) filter transmission
`FilterWheel`	A wheel of selectable filters
`TopHatFilterWheel`	A wheel of selectable top-hat filters
`SpanishVOFilterCurve`	Filters from the Spanish Virtual Observatory
`DownloadableFilterCurve`	Filters downloadable from remote servers
`PupilTransmission`	Pupil plane transmission curves
`PupilMaskWheel`	Wheel of pupil masks
`ADCWheel`	Atmospheric Dispersion Corrector wheel

Apertures and Field Masks#

Aperture effects define the on-sky field geometry — imaging windows, spectrograph slits, and IFU fields.

Class	Description
`ApertureMask`	Defines on-sky window coordinates (imaging, slit, IFU, MOS)
`RectangularApertureMask`	Rectangular aperture variant
`ApertureList`	Container for multiple apertures
`SlitWheel`	A wheel of selectable slits

Point Spread Functions (PSFs)#

PSF effects model the spatial blurring of point sources due to diffraction, atmospheric seeing, and optical aberrations.

Class	Description
`Vibration`	Wavelength-independent Gaussian vibration kernel
`SeeingPSF`	Atmospheric seeing as a Gaussian kernel
`GaussianDiffractionPSF`	Diffraction-limited PSF (Gaussian approximation)
`NonCommonPathAberration`	NCPA PSF from wavefront error maps
`AnisocadoConstPSF`	SCAO PSF from AnisoCADO at a given Strehl ratio
`FieldConstantPSF`	Field-constant PSF loaded from a FITS file
`FieldVaryingPSF`	Field-varying PSF loaded from a FITS file

Shifts and Atmospheric Dispersion#

Shift effects apply wavelength-dependent positional offsets to the light distribution.

Class	Description
`Shift3D`	Base class for wavelength-dependent positional shifts
`AtmosphericDispersion`	Wavelength-dependent atmospheric refraction
`AtmosphericDispersionCorrection`	ADC correction for atmospheric dispersion

Spectral Traces#

Spectral trace effects map 3D spectral data cubes onto the 2D detector plane for spectrographic modes.

Class	Description
`SpectralTraceList`	Maps spectral cubes to detector plane via trace geometries
`SpectralTraceListWheel`	A wheel of selectable spectral trace configurations
`SpectralEfficiency`	Grating/dispersion efficiency (blaze function)

Detector Geometry#

Detector geometry effects define the physical layout of detector chips on the focal plane.

Class	Description
`DetectorList`	Detector chip positions, sizes, pixel scale, and rotation
`DetectorWindow`	A sub-region readout window on a detector
`DetectorList3D`	3D detector array definition for spectroscopic modes

Electronic and Noise Effects#

These effects model the detector electronics and noise sources that affect the final readout.

Class	Description
`ShotNoise`	Poissonian photon noise
`DarkCurrent`	Thermal dark current
`Bias`	Constant bias level
`BasicReadoutNoise`	Generic readout noise
`PoorMansHxRGReadoutNoise`	Simplified HAWAII detector readout noise model
`LinearityCurve`	Detector linearity and saturation
`ADConversion`	Analog-to-digital conversion (electrons to ADU)
`PixelResponseNonUniformity`	Per-pixel gain variations (flat field)
`InterPixelCapacitance`	Inter-pixel capacitance crosstalk kernel

Exposure and Readout#

Exposure effects handle integration time, auto-exposure, and readout formatting.

Class	Description
`AutoExposure`	Auto-determines DIT/NDIT from saturation limits
`ExposureIntegration`	Integrates signal over the exposure time
`ExposureOutput`	Formats the readout output
`DetectorModePropertiesSetter`	Sets mode-specific detector parameters (MINDIT, FULL_WELL, RON)

Detector Pixel Effects#

Class	Description
`BinnedImage`	Equal pixel binning
`UnequalBinnedImage`	Non-uniform pixel binning
`ReferencePixelBorder`	Masks reference pixels at detector edges
`Rotate90CCD`	Rotates CCD by integer multiples of 90 degrees

Observing Strategies#

Class	Description
`ChopNodCombiner`	Combines 4 chop/nod positions (AA, AB, BA, BB)

FITS Header Effects#

Class	Description
`ExtraFitsKeywords`	Adds custom FITS keywords to output headers
`EffectsMetaKeywords`	Adds effect metadata to FITS headers
`SourceDescriptionFitsKeywords`	Adds source description keywords
`SimulationConfigFitsKeywords`	Adds simulation configuration keywords

Other#

Class	Description
`Shutter`	Simulates a closed shutter (zeros all pixels)

Effects Overview

Contents