API Reference

class pyEDITH.astrophysical_scene.AstrophysicalScene

Bases: object

A class representing an astrophysical scene for exoplanet observation simulations.

This class encapsulates various astrophysical parameters and methods to calculate zodi and exozodi fluxes for a set of target stars and their potential exoplanets.

Parameters:

• dist (float) – Distance to stars in parsecs

• vmag (float) – Stellar magnitudes at V band

• mag (ndarray) – Stellar magnitudes at desired wavelengths

• stellar_angular_diameter_arcsec (float) – Angular diameter of stars in arcseconds

• nzodis (float) – Amount of exozodi around target stars in “zodis”

• ra (float) – Right ascension of target stars in degrees

• dec (float) – Declination of target stars in degrees

• separation (float) – Separation of planets in arcseconds

• xp (float) – X-coordinate of planets in arcseconds

• yp (float) – Y-coordinate of planets in arcseconds

• deltamag (ndarray) – Magnitude difference between planets and host stars

• min_deltamag (float) – Brightest planet to resolve at the IWA

• F0V (float) – Flux zero point for V band

• F0 (ndarray) – Flux zero points for prescribed wavelengths

• M_V (float) – Absolute V band magnitudes of target stars

• Fzodi_list (ndarray) – Zodiacal light fluxes

• Fexozodi_list (ndarray) – Exozodiacal light fluxes

• Fbinary_list (ndarray) – Binary star fluxes (currently ignored)

• Fp_over_Fs (ndarray) – Flux of planets

calculate_zodi_exozodi(parameters: dict) → None

Calculate zodiacal and exozodiacal light fluxes for the given observation.

This method computes the flux zero points, zodiacal light fluxes, and exozodiacal light fluxes for the target stars based on the provided observation parameters.

Parameters:

parameters (dict) – A dictionary containing simulation parameters including target star parameters, planet parameters, and observational parameters. Must include a “wavelength” key containing the wavelength array

Return type:

None

Raises:

• AttributeError – If the scene has not been properly configured (missing required attributes)

• KeyError – If parameters dictionary is missing required keys

load_configuration(parameters: dict) → None

Load configuration parameters for the simulation from a dictionary.

This method initializes various attributes of the AstrophysicalScene object using the provided parameters dictionary.

Parameters:

parameters (dict) – A dictionary containing simulation parameters including target star parameters, planet parameters, and observational parameters.

Return type:

None

Raises:

ValueError – If a required parameter is missing from the input dictionary.

regrid_spectra(parameters, observation)

function to re-grid onto a new wavelength grid if the user specified this option

validate_configuration()

Check that mandatory variables are there and have the right format. There can be other variables, but they are not needed for the calculation.

pyEDITH.astrophysical_scene.calc_exozodi_flux(M_V: Quantity, vmag: Quantity, nexozodis: Quantity, lambd: Quantity, lambdmag: Quantity) → Quantity

Calculate the exozodiacal light flux for given stellar and observational parameters.

This function computes the exozodiacal light flux for a set of stars, taking into account their absolute and apparent magnitudes, the number of exozodis, and the observational wavelengths.

Parameters:

• M_V (Quantity) – V band absolute magnitude of stars.

• vmag (Quantity) – V band apparent magnitude of stars.

• nexozodis (Quantity) – Number of exozodis for each star.

• lambd (Quantity) – Wavelength in microns (vector of length nlambd).

• lambdmag (Quantity) – Apparent magnitude of stars at each lambd (array nlambd).

• F0lambd (Quantity) – Flux zero point at wavelength lambd (vector of length nlambd).

Returns:

Exozodi surface brightness in units of photons s^-1 cm^-2 arcsec^-2 nm^-1 / F0. This is equivalent to 10^(-0.4*magOmega_EZ).

Return type:

Quantity

pyEDITH.astrophysical_scene.calc_flux_zero_point(lambd: Quantity, output_unit: str = 'pcgs', perlambd: bool = False, AB: bool = False) → Quantity

Calculate the flux zero point for given wavelengths.

This function calculates the flux zero point for a given set of wavelengths. By default, it returns Johnson zero points. If the ‘AB’ flag is set, it will return AB flux zero points.

Parameters:

• lambd (astropy.units.Quantity) – Wavelengths. Must be in units of length.

• output_unit (str, optional) – Output unit type. Possible values are: - “jy” for output in Jy - “cgs” for output in erg s^-1 cm^-2 Hz^-1 - “pcgs” for output in photons s^-1 cm^-2 Hz^-1 Default is “pcgs”.

• perlambd (bool, optional) – If True, convert all output values to per wavelength instead of per frequency. Default is False.

• AB (bool, optional) – If True, use AB magnitude system instead of Johnson. Default is False.

Returns:

Flux zero points for the given wavelengths in the specified units.

Return type:

astropy.units.Quantity

Raises:

ValueError – If output_unit is not specified or is invalid, or if incompatible options are selected.

pyEDITH.astrophysical_scene.calc_zodi_flux(dec: Quantity, ra: Quantity, lambd: Quantity, F0: Quantity) → Quantity

Calculate the zodiacal light flux for given celestial coordinates and wavelengths.

This function computes the zodiacal light flux based on the target’s position in the sky, observation wavelengths, and whether a starshade is used. It uses the model from Leinert et al. (1998) to calculate the zodiacal light intensity.

Parameters:

• dec (Quantity) – Declination of targets in degrees (J2000 equatorial coordinate).

• ra (Quantity) – Right ascension of targets in degrees (J2000 equatorial coordinate).

• lambd (Quantity) – Wavelengths in microns (vector of length nlambd).

• F0 (Quantity) – Flux zero points at wavelengths lambd (vector of length nlambd).

Returns:

Zodi surface brightness in units of photons s^-1 cm^-2 arcsec^-2 nm^-1 / F0. This is equivalent to 10^(-0.4*magOmega_ZL). - Multiply by F0 to get photons s^-1 cm^-2 arcsec^-2 nm^-1 - Multiply by energy of photons to get erg s^-1 cm^-2 arcsec^-2 nm^-1 The output array has dimensions (nlambd, nstars).

Return type:

np.ndarray

Raises:

ValueError – If F0 and lambd have different lengths, or if starshade mode is inconsistent with ss_elongation.

Note

• The function uses the zodiacal light model from Leinert et al. (1998).

• For coronagraph mode, it assumes observations near solar longitude of 135 degrees.

• Starshade functionality is currently not fully implemented.

References:

Leinert, C., et al. (1998). The 1997 reference of diffuse night sky brightness. Astronomy and Astrophysics Supplement Series, 127(1), 1-99.

class pyEDITH.observation.Observation

Bases: object

A class representing an astronomical observation.

This class encapsulates various parameters and methods related to astronomical observations, including target star properties, planet characteristics, observational settings, telescope specifications, instrument details, and detector parameters.

Parameters:

• wavelength (np.ndarray) – Wavelength array (in microns).

• nlambd (int) – Number of wavelength points.

• SNR (np.ndarray) – Signal-to-noise ratio array.

• tp (ndarray) – Exposure time of every planet (nmeananom x norbits x ntargs array).

• exptime (ndarray) – Exposure time for each target and wavelength.

• fullsnr (ndarray) – Signal-to-noise ratio for each target and wavelength.

• td_limit (float) – Limit placed on exposure times.

load_configuration(parameters: dict) → None

Load configuration parameters for the observation from a dictionary.

This method initializes various observation parameters from the provided dictionary, including wavelength arrays, signal-to-noise ratios, and aperture settings. For IFS mode, it can calculate or regrid the wavelength grid based on specified parameters.

Parameters:

parameters (dict) – A dictionary containing observation parameters including wavelengths, SNR values, aperture settings, and observation mode settings. Must include ‘observing_mode’, ‘wavelength’, ‘snr’.

Raises:

KeyError – If required parameters are missing or if regridding is requested without necessary parameters

set_output_arrays()

Initialize arrays for storing observation results.

This method creates and initializes the arrays that will store the calculated exposure times and signal-to-noise ratios for each wavelength point in the observation.

validate_configuration()

Validate that all required observation parameters are present and correctly formatted.

This method checks that all mandatory attributes exist on the observation object and that they have the expected types and units.

Raises:

• TypeError – If an attribute has an incorrect type

• ValueError – If a Quantity attribute has incorrect units

class pyEDITH.observatory.Observatory

Bases: ABC

Abstract base class for various astronomical observatories.

This class defines the basic structure for modeling astronomical observatories used in performance calculations. It includes abstract methods that must be implemented by concrete subclasses and provides common functionality for calculating optical throughput, thermal properties, and component validation.

Parameters:

• telescope (Telescope) – The telescope component of the observatory

• detector (Detector) – The detector component of the observatory

• coronagraph (Coronagraph) – The coronagraph component of the observatory

• optics_throughput (np.ndarray) – Optical throughput of the telescope and coronagraph system

• epswarmTrcold (np.ndarray) – Warm emissivity times cold transmission factor for thermal noise

• total_throughput (np.ndarray) – Combined optical and detector throughput

• observing_mode (str) – Observing mode (‘IFS’ or ‘IMAGER’)

• PRESETS (dict) – Dictionary of predefined observatory configurations

• TOY_MODEL_COMPONENTS (dict) – Default component definitions for toy model simulations

create_observatory(config: str | dict) → object

Create an observatory based on the given configuration.

This method creates an Observatory instance with telescope, coronagraph, and detector components as specified in the configuration. The configuration can be either a preset name or a custom configuration dictionary.

Preset usage:

observatory = create_observatory(“ToyModel”) observatory = create_observatory(“EAC5”)

Custom config dict:

‘telescope_type’: ‘EAC5’ or ‘ToyModel’ ‘coronagraph_type’: str or yippy.Coronagraph, path/keyword/pre-constructed object ‘detector_type’: ‘EAC5’ or ‘ToyModel’

For remote coronagraphs, use yippy first:

from yippy import fetch_yip coro_path = fetch_yip(‘remote_name’)

Parameters:

config (Union[str,dict]) – Either a preset name or a custom configuration dictionary

Returns:

A configured Observatory object

Return type:

object

Raises:

ValueError – If the config is invalid or a component is not found

load_configuration(parameters: dict, observation: object, scene: object) → None

Load and configure all observatory components.

This method initializes all observatory components (coronagraph, telescope, detector) with the provided parameters and calculates derived quantities like throughputs and thermal factors. Creates a mediator for component communication and sets the observing mode.

Parameters:

• parameters (dict) – Configuration parameters dictionary containing observatory settings

• observation (Observation) – Observation object containing observational parameters

• scene (AstrophysicalScene) – Scene object containing target and environmental parameters

validate_configuration() → None

Validate that all observatory components and parameters are correctly configured.

This method validates all sub-components (telescope, detector, coronagraph) and checks that required observatory-level attributes exist with correct types and units. Observatory-related parameters include total_throughput, optics_throughput, and epswarmTrcold.

Raises:

• AttributeError – If required attributes are missing from the observatory or its components

• TypeError – If an attribute has an incorrect type

• ValueError – If a Quantity attribute has incorrect units

calculate_optics_throughput(parameters: dict, mediator: object) → None

Calculate the optical throughput of the observatory system.

This method computes the optical throughput by either using a provided total optical throughput value (T_optical) from parameters, or by multiplying the telescope and coronagraph throughputs. For IFS mode, an additional IFS efficiency factor is applied. If optics_throughput is a scalar and wavelength array has multiple elements, the throughput is expanded to match the wavelength array length.

Parameters:

• parameters (dict) – Configuration parameters dictionary that may contain ‘T_optical’, ‘observing_mode’, and ‘IFS_eff’ keys

• mediator (ObservatoryMediator) – Mediator object providing access to observation parameters including wavelength array

calculate_warmemissivity_coldtransmission(parameters: dict, mediator: object) → None

Calculate the warm emissivity times cold transmission factor.

This method computes the factor used for thermal noise calculations. It either uses a provided ‘epswarmTrcold’ value from parameters, or calculates it as (1 - optics_throughput).

Parameters:

• parameters (dict) – Configuration parameters dictionary that may contain ‘epswarmTrcold’ key

• mediator (ObservatoryMediator) – Mediator object providing access to observation parameters including wavelength array

calculate_total_throughput() → None

Calculate the total system throughput.

This method computes the combined optical and detector throughput by multiplying the optics throughput with the detector quantum efficiency (QE), detector QE, and telescope contamination factor. This total throughput is used as a multiplicative factor in noise calculations.

class pyEDITH.observatory.ObservatoryMediator(observatory: object, observation: object, scene: object)

Bases: object

Mediator class facilitating communication between observatory components.

This class provides a centralized interface for accessing parameters from different components (observatory, observation, scene) without creating direct dependencies between them. It implements the mediator design pattern to decouple component interactions.

Parameters:

• observatory (Observatory) – The observatory object

• observation (Observation) – The observation object containing observational parameters

• scene (AstrophysicalScene) – The scene object containing target and environmental parameters

get_telescope_parameter(param_name: str)

Retrieve a parameter from the telescope object.

Parameters:

param_name (str) – Name of the parameter to retrieve

Returns:

The parameter value if it exists, None otherwise

Return type:

Any or None

get_coronagraph_parameter(param_name: str)

Retrieve a parameter from the coronagraph object.

Parameters:

param_name (str) – Name of the parameter to retrieve

Returns:

The parameter value if it exists, None otherwise

Return type:

Any or None

get_detector_parameter(param_name: str)

Retrieve a parameter from the detector object.

Parameters:

param_name (str) – Name of the parameter to retrieve

Returns:

The parameter value if it exists, None otherwise

Return type:

Any or None

get_observation_parameter(param_name: str)

Retrieve a parameter from the observation object.

Parameters:

param_name (str) – Name of the parameter to retrieve

Returns:

The parameter value if it exists, None otherwise

Return type:

Any or None

get_scene_parameter(param_name: str)

Retrieve a parameter from the scene object.

Parameters:

param_name (str) – Name of the parameter to retrieve

Returns:

The parameter value if it exists, None otherwise

Return type:

Any or None

class pyEDITH.components.telescopes.Telescope

Bases: ABC

A class representing a telescope for astronomical observations.

This class provides methods to initialize and configure a telescope for simulating observations of exoplanets and their host stars.

Parameters:

• diameter (float) – Circumscribed diameter of the telescope aperture in meters.

• Area (float) – Effective collecting area of the telescope in square meters.

• toverhead_fixed (float) – Fixed overhead time in seconds.

• toverhead_multi (float) – Multiplicative overhead time.

• telescope_optical_throughput (numpy.ndarray) – Array of throughput values.

• temperature (float) – Temperature of the warm optics.

• T_contamination (float) – Effective throughput factor to budget for contamination.

abstractmethod load_configuration()

Load configuration parameters for the telescope.

This abstract method must be implemented by subclasses to define how telescope configuration parameters are loaded and processed.

validate_configuration()

Check that mandatory variables are present and have the correct format.

This method validates that all required attributes exist on the telescope object and that they have the expected types and units. Additional variables may be present but are not required for calculations.

Raises:

• AttributeError – If a required attribute is missing

• TypeError – If an attribute has an incorrect type

• ValueError – If a Quantity attribute has incorrect units

class pyEDITH.components.telescopes.ToyModelTelescope(path: str = None, keyword: str = None)

Bases: Telescope

A toy model telescope class that extends the base Telescope class.

This class represents a simplified telescope model for use in simulations where users can specify telescope parameters manually rather than using predefined models from configuration files.

Parameters:

• path (str, optional) – Path to configuration files (not used in toy model)

• keyword (str, optional) – Keyword for configuration selection (not used in toy model)

load_configuration(parameters: dict, mediator: object) → None

Load configuration parameters for the toy model telescope simulation.

This method initializes various attributes of the Telescope object using the provided parameters dictionary or default values. It calculates the effective collecting area of the telescope based on the diameter and unobscured area parameters.

Parameters:

• parameters (dict) – A dictionary containing simulation parameters including telescope specifications and observational parameters

• mediator (ObservatoryMediator) – Mediator object providing access to other simulation components

class pyEDITH.components.telescopes.EACTelescope(path: str = None, keyword: str = None)

Bases: Telescope

An EAC telescope class that extends the base Telescope class.

This class represents a telescope model that loads parameters from EAC YAML configuration files through the module EACy, supporting both imaging and IFS (Integral Field Spectroscopy) observing modes.

Parameters:

• path (str, optional) – Path to configuration files (not used directly)

• keyword (str) – Keyword identifying the specific telescope model to load from EACy files

load_configuration(parameters: dict, mediator: object) → None

Load configuration parameters from the YAML files using EACy.

This method initializes telescope attributes using parameters from EAC YAML configuration files. It handles both IMAGER and IFS observing modes, loading appropriate telescope characteristics including diameter and optical throughput. For IMAGER mode, parameters are averaged over the specified wavelength range, while for IFS mode, parameters are interpolated onto the observation wavelength grid.

Parameters:

• parameters (dict) – A dictionary containing simulation parameters including observing mode and telescope specifications

• mediator (ObservatoryMediator) – Mediator object providing access to observation and coronagraph parameters

Raises:

KeyError – If the observing mode is not ‘IMAGER’ or ‘IFS’

pyEDITH.components.coronagraphs.generate_radii(numx: int, numy: int = 0) → ndarray

Generate a 2D distribution of radii from the center of a matrix.

This function creates a 2D numpy array representing the radial distance from the center for each element. The origin is assumed to be in the center of the matrix. Radii are calculated assuming 1 pixel = 1 unit. The number of pixels can be odd or even.

Parameters:

• numx (int) – Number of pixels in the x direction.

• numy (int, optional) – Number of pixels in the y direction. If 0 (default), it is set equal to numx.

Returns:

A 2D numpy array of shape (numy, numx) containing the radial distances from the center for each pixel.

Return type:

np.ndarray

Note

• The function handles both odd and even dimensions.

• Formerly in rgen.pro

class pyEDITH.components.coronagraphs.Coronagraph

Bases: ABC

A base class representing a generic coronagraph.

This class defines the basic structure and methods common to all coronagraphs. Specific coronagraph models should inherit from this class and implement their own generate_secondary_parameters method. Right now, there are two coronagraph sub-classes:

-> ToyModelCoronagraph This is a simplistic coronagraph setup where the user can specify all coronagraph parameters. Use this for testing coronagraph parameters not defined by a Yield Input Package (files containing models of realistic coronagraph responses).

-> CoronagraphYIP This is a coronagraph setup that is defined by a Yield Input Package (YIP), which contains models of realistic coronagraph responses. User this for testing specific coronagraph cases. Requires a path to a YIP.

Parameters:

• Istar (np.ndarray) – Star intensity distribution.

• noisefloor (np.ndarray) – Noise floor of the coronagraph.

• photometric_aperture_throughput (np.ndarray) – Photometric aperture throughput.

• omega_lod (np.ndarray) – Solid angle of the photometric aperture in λ/D units.

• skytrans (np.ndarray) – Sky transmission.

• pixscale (float) – Pixel scale in λ/D units.

• npix (int) – Number of pixels in the image.

• xcenter (float) – X-coordinate of the image center.

• ycenter (float) – Y-coordinate of the image center.

• bandwidth (float) – Bandwidth of the coronagraph.

• stellar_angular_diameter (np.ndarray) – Angular diameters of the target objects.

• photometric_aperture_radius (float) – Photometric aperture radius (in units of lambda/D).

• psf_trunc_ratio (np.ndarray) – PSF truncation ratio.

• npsfratios (int) – Number of PSF ratios.

• nrolls (int) – Number of roll angles.

• nchannels (int) – Number of channels.

• minimum_IWA (float) – Minimum Inner Working Angle (lambd/D)

• maximum_OWA (float) – Maximum Outer Working Angle (lambd/D)

• coronagraph_optical_throughput (np.ndarray) – Throughput for all coronagraph optics in the optical path

abstractmethod load_configuration() → None

Load configuration parameters for the coronagraph.

This abstract method must be implemented by subclasses to define how coronagraph configuration parameters are loaded and processed.

validate_configuration() → None

Check that mandatory variables are present and have the correct format.

This method validates that all required attributes exist on the coronagraph object and that they have the expected types and units. It specifically verifies that either photometric_aperture_radius or psf_trunc_ratio is defined but not necessarily both. :raises AttributeError: If a required attribute is missing :raises TypeError: If an attribute has an incorrect type :raises ValueError: If a Quantity attribute has incorrect units

class pyEDITH.components.coronagraphs.ToyModelCoronagraph(path: str = None)

Bases: Coronagraph

A toy model coronagraph class that extends the base Coronagraph class.

This class implements a simplified coronagraph model with basic functionality for generating secondary parameters and setting up coronagraph characteristics. It allows users to specify all coronagraph parameters manually rather than using predefined models from Yield Input Packages.

Parameters:

path (str, optional) – Path to configuration files (not used in toy model)

load_configuration(parameters: dict, mediator: object) → None

Load configuration parameters for the toy model coronagraph simulation.

This method sets up all coronagraph parameters using either user-provided values or default configurations. It calculates derived parameters such as pixel coordinates, radial separations, and throughput maps based on the specified inner and outer working angles.

Parameters:

• parameters (dict) – A dictionary containing simulation parameters including coronagraph specifications, observational parameters, and noise characteristics

• mediator (ObservatoryMediator) – Mediator object providing access to observation and scene parameters

class pyEDITH.components.coronagraphs.CoronagraphYIP(path: str = None, yippy_coro: Coronagraph = None)

Bases: Coronagraph

A coronagraph class that uses a Yield Input Package (YIP) for realistic modeling.

This class implements a coronagraph simulation based on Yield Input Package files that contain pre-computed coronagraph responses, stellar intensity distributions, and off-axis PSFs. It combines coronagraph optical throughput from HWO yaml files with detailed coronagraph response data from YIP files.

Parameters:

path (str, optional) – Path to the YIP files containing coronagraph response data

load_configuration(parameters, mediator)

Load configuration parameters from YIP files and user specifications.

This method loads coronagraph parameters from multiple sources: EACy YAML files for optical throughput, YIP files for detailed coronagraph response including stellar intensity and PSF data, and user-provided parameters. It handles both imaging and IFS observing modes with appropriate wavelength averaging or interpolation.

Parameters:

• parameters (dict) – A dictionary containing simulation parameters including observing mode, bandwidth specifications, and coronagraph overrides

• mediator (ObservatoryMediator) – Mediator object providing access to observation and scene parameters including wavelength, PSF truncation ratios, and stellar properties

Raises:

• KeyError – If neither psf_trunc_ratio nor photometric_aperture_radius are specified

• AssertionError – If stellar angular diameter is outside valid bounds (0 <= diameter < 1 λ/D)

class pyEDITH.components.detectors.Detector

Bases: ABC

A class representing a detector for astronomical observations.

This class manages detector-specific parameters and configurations used in astronomical simulations and observations.

Parameters:

• pixscale_mas (float) – Detector pixel scale in milliarcseconds.

• npix_multiplier (ndarray) – Number of detector pixels per image plane “pixel”.

• DC (ndarray) – Dark current in counts per pixel per second.

• RN (ndarray) – Read noise in counts per pixel per read.

• tread (ndarray) – Read time in seconds.

• CIC (ndarray) – Clock-induced charge in counts per pixel per photon count.

• dQE (ndarray) – Quantum efficiency of detector

• QE (ndarray) – Effective QE due to degradation, cosmic ray effects, readout inefficiencies

abstractmethod load_configuration()

Load configuration parameters for the detector.

This abstract method must be implemented by subclasses to define how detector configuration parameters are loaded and processed.

validate_configuration()

Check that mandatory variables are present and have the correct format.

This method validates that all required attributes exist on the detector object and that they have the expected types and units. Additional variables may be present but are not required for calculations.

Raises:

• AttributeError – If a required attribute is missing

• TypeError – If an attribute has an incorrect type

• ValueError – If a Quantity attribute has incorrect units

class pyEDITH.components.detectors.ToyModelDetector(path: str = None, keyword: str = None)

Bases: Detector

A toy model detector class that extends the base Detector class.

This class represents a simplified detector model for use in simulations where users can specify all detector parameters manually rather than using predefined models from configuration files.

Parameters:

• path (str, optional) – Path to configuration files (not used in toy model)

• keyword (str, optional) – Keyword for configuration selection (not used in toy model)

load_configuration(parameters: dict, mediator: object) → None

Load configuration parameters for the toy model detector simulation.

This method initializes various attributes of the Detector object using the provided parameters dictionary. It calculates the default detector pixel scale based on telescope parameters and handles wavelength-dependent detector properties by expanding single values to arrays when multiple wavelengths are specified.

Parameters:

• parameters (dict) – A dictionary containing simulation parameters including detector specifications and observational parameters

• mediator (ObservatoryMediator) – Mediator object providing access to telescope and observation parameters

class pyEDITH.components.detectors.EACDetector(path: str = None, keyword: str = None)

Bases: Detector

An EAC detector class that extends the base Detector class.

This class represents a detector model that loads parameters from the EAC YAML configuration files through the module EACy, supporting both imaging and IFS (Integral Field Spectroscopy) observing modes.

Parameters:

• path (str, optional) – Path to configuration files (not used in EAC detector)

• keyword (str, optional) – Keyword for configuration selection (not used in EAC detector)

load_configuration(parameters: dict, mediator: object) → None

Load configuration parameters from the YAML files using EACy.

This method initializes detector attributes using parameters from EAC YAML detector configuration files. It handles both IMAGER and IFS observing modes, loading appropriate detector characteristics including dark current, read noise, and quantum efficiency. The method automatically selects VIS or NIR detector parameters based on the observing wavelength.

Parameters:

• parameters (dict) – A dictionary containing simulation parameters including observing mode, detector specifications, and observational parameters

• mediator (ObservatoryMediator) – Mediator object providing access to observation, telescope, and coronagraph parameters including wavelength arrays and bandwidth specifications

Raises:

• KeyError – If the observing mode is not ‘IMAGER’ or ‘IFS’

• AssertionError – If the QE array contains NaN values after processing

pyEDITH.exposure_time_calculator.calculate_CRp(F0: Quantity, Fs_over_F0: Quantity, Fp_over_Fs: Quantity, area: Quantity, Upsilon: Quantity, throughput: Quantity, dlambda: Quantity, nchannels: int) → Quantity

Calculate the planet count rate.

This function computes the detected count rate from a planet based on the stellar and planetary flux, telescope characteristics, and coronagraph performance parameters.

Parameters:

• F0 (u.Quantity) – Flux zero point [photons / (s * cm^2 * nm)]

• Fs_over_F0 (u.Quantity) – Stellar flux [dimensionless]

• Fp_over_Fs (u.Quantity) – Planet flux relative to star [dimensionless]

• area (u.Quantity) – Collecting area of the telescope [cm^2]

• Upsilon (u.Quantity) – Core throughput of the coronagraph [dimensionless]

• throughput (u.Quantity) – Throughput of the system (includes QE) [electrons/photons]

• dlambda (u.Quantity) – Bandwidth [um]

• nchannels (int) – Number of channels

Returns:

Planet count rate [electrons / s]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.calculate_CRbs(F0: Quantity, Fs_over_F0: Quantity, Istar: Quantity, area: Quantity, pixscale: Quantity, throughput: Quantity, dlambda: Quantity, nchannels: int) → Quantity

Calculate the stellar leakage count rate.

This function computes the detected count rate from stellar leakage based on the stellar flux, coronagraph performance, and telescope parameters.

Parameters:

• F0 (u.Quantity) – Flux zero point [photons / (s * cm^2 * nm)]

• Fs_over_F0 (u.Quantity) – Stellar flux [dimensionless]

• Istar (u.Quantity) – Stellar intensity at the given pixel [dimensionless]

• area (u.Quantity) – Collecting area of the telescope [cm^2]

• pixscale (u.Quantity) – Pixel scale of the detector [lambda/D]

• throughput (u.Quantity) – Throughput of the system (includes QE) [electrons/photons]

• dlambda (u.Quantity) – Bandwidth [um]

• nchannels (int) – Number of channels

Returns:

Stellar leakage count rate [electrons / s]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.calculate_CRbz(F0: Quantity, Fzodi: Quantity, lod_arcsec: Quantity, skytrans: Quantity, area: Quantity, throughput: Quantity, dlambda: Quantity, nchannels: int) → Quantity

Calculate the local zodiacal light count rate.

This function computes the detected count rate from local zodiacal light based on the zodiacal intensity, sky transmission, and telescope parameters.

Parameters:

• F0 (u.Quantity) – Flux zero point [photons / (s * cm^2 * nm)]

• Fzodi (u.Quantity) – Zodiacal light flux [dimensionless]

• lod_arcsec (u.Quantity) – Lambda/D in arcseconds [arcsec]

• skytrans (u.Quantity) – Sky transmission [dimensionless]

• area (u.Quantity) – Collecting area of the telescope [cm^2]

• throughput (u.Quantity) – Throughput of the system (includes QE) [electrons/photons]

• dlambda (u.Quantity) – Bandwidth [um]

• nchannels (int) – Number of channels

Returns:

Local zodiacal light count rate [electrons / s]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.calculate_CRbez(F0: Quantity, Fexozodi: Quantity, lod_arcsec: Quantity, skytrans: Quantity, area: Quantity, throughput: Quantity, dlambda: Quantity, nchannels: int, dist: Quantity, sp: Quantity) → Quantity

Calculate the exozodiacal light count rate.

This function computes the detected count rate from exozodiacal light based on the exozodiacal intensity, system geometry, and telescope parameters. It scales the exozodiacal intensity based on the distance to the star and the angular separation.

Parameters:

• F0 (u.Quantity) – Flux zero point [photons / (s * cm^2 * nm)]

• Fexozodi (u.Quantity) – Exozodiacal light flux at reference position [dimensionless]

• lod_arcsec (u.Quantity) – Lambda/D in arcseconds [arcsec]

• skytrans (u.Quantity) – Sky transmission [dimensionless]

• area (u.Quantity) – Collecting area of the telescope [cm^2]

• throughput (u.Quantity) – Throughput of the system (includes QE) [electrons/photons]

• dlambda (u.Quantity) – Bandwidth [um]

• nchannels (int) – Number of channels

• dist (u.Quantity) – Distance to the star [pc]

• sp (u.Quantity) – Separation of the planet [arcsec]

Returns:

Exozodiacal light count rate [electrons / s]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.calculate_CRbbin(F0: Quantity, Fbinary: Quantity, skytrans: Quantity, area: Quantity, throughput: Quantity, dlambda: Quantity, nchannels: int) → Quantity

Calculate the count rate from neighboring stars.

This function computes the detected count rate from binary or neighboring stars based on their flux, sky transmission, and telescope parameters.

Parameters:

• F0 (u.Quantity) – Flux zero point [photons / (s * cm^2 * nm)]

• Fbinary (u.Quantity) – Flux from neighboring stars [dimensionless]

• skytrans (u.Quantity) – Sky transmission [dimensionless]

• area (u.Quantity) – Collecting area of the telescope [cm^2]

• throughput (u.Quantity) – Throughput of the system (includes QE) [electrons/photons]

• dlambda (u.Quantity) – Bandwidth [um]

• nchannels (int) – Number of channels

Note

IMPORTANT: Currently Fbinary is 0 by default, so this term is zero. It will need to be checked again in the future.

Returns:

Count rate from neighboring stars [electrons / s]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.calculate_CRbth(lam: Quantity, area: Quantity, dlambda: Quantity, temp: Quantity, lod_rad: Quantity, emis: Quantity, QE: Quantity, dQE: Quantity) → Quantity

Calculate background thermal count rate.

This function computes the detected count rate from thermal emission of the telescope and instrument components based on their temperature, emissivity, and other system parameters. It uses a blackbody radiation model to calculate the thermal photon flux.

Parameters:

• lam (u.Quantity) – Wavelength of observation [um]

• area (u.Quantity) – Collecting area of the telescope [cm^2]

• dlambda (u.Quantity) – Bandwidth [um]

• temp (u.Quantity) – Telescope mirror temperature [K]

• lod_rad (u.Quantity) – Lambda/D in radians [rad]

• emis (u.Quantity) – Effective emissivity for the observing system [dimensionless]

• QE (u.Quantity) – Quantum efficiency [electron/photon]

• dQE (u.Quantity) – Effective QE due to degradation [dimensionless]

Returns:

Count rate from thermal background [electrons / s]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.calculate_t_photon_count(det_npix: Quantity, det_CR: Quantity) → Quantity

Calculate the photon counting time.

This function computes the average time needed to detect one photon per pixel based on the detector count rate and number of pixels.

Parameters:

• det_npix (u.Quantity) – Number of detector pixels [pix]

• det_CR (u.Quantity) – Detector count rate [photons / s]

Returns:

Photon counting time (average time to detect one photon per pixel) [s * pixel / ph]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.calculate_CRbd(det_npix: Quantity, det_DC: Quantity, det_RN: Quantity, det_tread: Quantity, det_CIC: Quantity, t_photon_count: Quantity) → Quantity

Calculate the detector noise count rate.

This function computes the total detector noise count rate by combining contributions from dark current, read noise, and clock-induced charge.

Parameters:

• det_npix (u.Quantity) – Number of detector pixels [pix]

• det_DC (u.Quantity) – Dark current [electron / pix / s]

• det_RN (u.Quantity) – Read noise [electron / pix / read]

• det_tread (u.Quantity) – Read time [s]

• det_CIC (u.Quantity) – Clock-induced charge [electron / pix / photon]

• t_photon_count (u.Quantity) – Photon counting time [pix * s / electron]

Returns:

Detector noise count rate [electrons / s]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.calculate_CRnf(F0: Quantity, Fs_over_F0: Quantity, area: Quantity, pixscale: Quantity, throughput: Quantity, dlambda: Quantity, nchannels: int, SNR: Quantity, noisefloor: Quantity) → Quantity

Calculate the noise floor count rate.

This function computes the count rate corresponding to the noise floor based on the stellar flux, telescope parameters, and the specified noise floor level. The noise floor represents the limiting systematic noise that cannot be reduced through longer integration times.

Parameters:

• F0 (u.Quantity) – Flux zero point [photons / (s * cm^2 * nm)]

• Fs_over_F0 (u.Quantity) – Stellar flux [dimensionless]

• area (u.Quantity) – Collecting area of the telescope [cm^2]

• pixscale (u.Quantity) – Pixel scale of the detector [lambda/D]

• throughput (u.Quantity) – Throughput of the system [dimensionless]

• dlambda (u.Quantity) – Bandwidth [um]

• nchannels (int) – Number of channels

• SNR (float) – Signal-to-noise ratio

• noisefloor (u.Quantity) – Noise floor level [dimensionless]

Returns:

Noise floor count rate [photons / s]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.calculate_CRnf_ez(CRbez: Quantity, SNR: Quantity, ez_PPF: Quantity) → Quantity

Calculate the exozodi noise floor count rate.

This function computes the noise floor contribution from exozodiacal light when it cannot be subtracted to the Poisson noise limit. It accounts for post-processing capabilities through the ez_PPF factor.

Parameters:

• CRbez (u.Quantity) – Count rate of the exozodi [photons / s]

• SNR (float) – Signal-to-noise ratio

• ez_PPF (u.Quantity) – Post-processing factor for exozodi [dimensionless]

Returns:

Exozodi noise floor count rate [photons / s]

Return type:

u.Quantity

pyEDITH.exposure_time_calculator.measure_coronagraph_performance_at_IWA(photometric_aperture_throughput: Quantity, Istar_interp: Quantity, skytrans: Quantity, omega_lod: Quantity, npix: int, xcenter: Quantity, ycenter: Quantity, oneopixscale_arcsec: Quantity) → Tuple[Quantity, Quantity, Quantity, Quantity, Quantity, Quantity]

Measure the performance of the coronagraph at the Inner Working Angle (IWA).

This function determines the IWA and calculates various coronagraph performance parameters at that point. It identifies the IWA by finding where the photometric aperture throughput falls to half its maximum value and then measures stellar intensity, sky transmission, and other parameters in a 2-pixel annulus at the IWA.

Parameters:

• photometric_aperture_throughput (u.Quantity) – Photometric aperture fractions [dimensionless]

• Istar_interp (u.Quantity) – Interpolated stellar intensity [dimensionless]

• skytrans (u.Quantity) – Sky transmission [dimensionless]

• omega_lod (u.Quantity) – Solid angle of photometric aperture [(lambda/D)^2]

• npix (int) – Number of pixels in each dimension

• xcenter (u.Quantity) – X-coordinate of the center [pixel]

• ycenter (u.Quantity) – Y-coordinate of the center [pixel]

• oneopixscale_arcsec (u.Quantity) – Inverse of pixel scale [1/arcsec]

Returns:

det_sep_pix: Separation at the IWA [pixel] det_sep: Separation at the IWA [arcsec] det_Istar: Maximum stellar intensity at the IWA [dimensionless] det_skytrans: Maximum sky transmission at the IWA [dimensionless] det_photometric_aperture_throughput: Maximum photometric aperture fraction at the IWA [dimensionless] det_omega_lod: Solid angle corresponding to max photometric_aperture_throughput at the IWA [(lambda/D)^2]

Return type:

Tuple[u.Quantity, u.Quantity, u.Quantity, u.Quantity, u.Quantity, u.Quantity]

pyEDITH.exposure_time_calculator.calculate_exposure_time_or_snr(observation: Observation, scene: AstrophysicalScene, observatory: Observatory, ETC_validation: bool = False, mode: str = 'exposure_time') → None

Calculate exposure time or signal-to-noise ratio for an observation.

This function performs detailed calculations of exposure time or signal-to-noise ratio for each wavelength in an observation, accounting for multiple noise sources, coronagraph performance, and detector characteristics. The function handles both ‘exposure_time’ mode (calculating required exposure time for a given SNR) and ‘signal_to_noise’ mode (calculating achievable SNR for a given exposure time). The function stores calculated photon counts, exposure times or SNR values directly in the observation object. For planets outside the working angle range or below the noise floor, infinity values are assigned.

Parameters:

• observation (Observation) – Observation object containing observation parameters including wavelength, target SNR or exposure time, and bandwidth information

• scene (AstrophysicalScene) – AstrophysicalScene object containing scene parameters including planet contrast, stellar properties, and zodiacal light levels

• observatory (Observatory) – Observatory object containing telescope, detector, and coronagraph parameters

• ETC_validation (bool, optional) – If True, use specific parameter values for validation against the ETC, default is False

• mode (str, optional) – Calculation mode, either ‘exposure_time’ (to calculate required exposure time for a given SNR) or ‘signal_to_noise’ (to calculate achievable SNR for a given exposure time), default is ‘exposure_time’

Raises:

ValueError – If an invalid mode is specified or if the observing_mode is not ‘IMAGER’ or ‘IFS’

pyEDITH.cli.main()

Main entry point for the py-E.D.I.T.H. command-line interface.

This function sets up the argument parser and handles the execution of different subcommands: etc (Exposure Time Calculator), snr (Signal-to-Noise Ratio), and etc2snr (Exposure Time to Signal-to-Noise Ratio).

The function reads configuration from .edith files and calls the appropriate calculation functions based on the subcommand.

Raises:

• SyntaxError – If required command-line arguments are missing

• TypeError – If multiple wavelengths are provided for primary lambda in etc2snr mode

• ValueError – If secondary parameters are not specified in etc2snr mode or if the returned exposure time is infinity

pyEDITH.cli.calculate_texp(parameters: dict, ETC_validation: bool = False) → array

Calculate exposure time for a planet observation with specified parameters.

This function initializes Observation, AstrophysicalScene, and Observatory objects with the provided parameters, then calculates the required exposure time to achieve the specified signal-to-noise ratio at each wavelength.

Parameters:

• parameters (dict) – Dictionary containing all input parameters for the calculation

• ETC_validation (bool, optional) – If True, use specific parameter values for validation against the ETC, default is False

Returns:

A tuple containing:

observation.exptimenumpy.ndarray

Exposure time in hours for each wavelength

observation.validation_variablesdict

Validation variables containing intermediate calculation results

Return type:

tuple

pyEDITH.cli.calculate_snr(parameters: dict, reference_texp: float)

Calculate signal-to-noise ratio for a given exposure time.

This function initializes Observation, AstrophysicalScene, and Observatory objects with the provided parameters, then calculates the achievable signal-to-noise ratio for the specified exposure time at each wavelength.

Parameters:

• parameters (dict) – Dictionary containing all input parameters for the calculation

• reference_texp (float) – Reference exposure time in seconds

Returns:

A tuple containing:

observation.fullsnrnumpy.ndarray

Signal-to-noise ratio for each wavelength

observation.validation_variablesdict

Validation variables containing intermediate calculation results

Return type:

tuple

pyEDITH.units.lambda_d_to_radians(value_lod: Quantity, wavelength: Quantity, diameter: Quantity) → Quantity

Convert a λ/D value to radians.

This function converts an angular measurement in units of λ/D (diffraction limited resolution elements) to radians based on the provided wavelength and telescope diameter.

Parameters:

• value_lod (u.Quantity) – The λ/D value (dimensionless)

• wavelength (u.Quantity) – The wavelength

• diameter (u.Quantity) – The telescope diameter

Returns:

The angle in radians

Return type:

u.Quantity

pyEDITH.units.radians_to_lambda_d(angle: Quantity, wavelength: Quantity, diameter: Quantity) → Quantity

Convert an angle in radians to λ/D.

This function converts an angular measurement in radians to units of λ/D (diffraction limited resolution elements) based on the provided wavelength and telescope diameter.

Parameters:

• angle (u.Quantity) – The angle in radians

• wavelength (u.Quantity) – The wavelength

• diameter (u.Quantity) – The telescope diameter

Returns:

The value in λ/D (dimensionless)

Return type:

Quantity

pyEDITH.units.lambda_d_to_arcsec(value_lod: Quantity, wavelength: Quantity, diameter: Quantity) → Quantity

Convert λ/D to arcseconds.

This function converts an angular measurement in units of λ/D (diffraction limited resolution elements) to arcseconds based on the provided wavelength and telescope diameter.

Parameters:

• value_lod (u.Quantity) – The λ/D value (dimensionless)

• wavelength (u.Quantity) – Wavelength

• diameter (u.Quantity) – Telescope diameter

Returns:

Angular size in arcseconds

Return type:

u.Quantity

pyEDITH.units.arcsec_to_lambda_d(angle: Quantity, wavelength: Quantity, diameter: Quantity) → Quantity

Convert arcseconds to λ/D.

This function converts an angular measurement in arcseconds to units of λ/D (diffraction limited resolution elements) based on the provided wavelength and telescope diameter.

Parameters:

• angle (u.Quantity) – Angle in arcseconds

• wavelength (u.Quantity) – Wavelength

• diameter (u.Quantity) – Telescope diameter

Returns:

Angular size in λ/D

Return type:

u.Quantity

pyEDITH.units.arcsec_to_au(angle: Quantity, distance: Quantity) → Quantity

Convert an angle in arcseconds to a distance in AU.

This function converts an angular separation in arcseconds to a projected physical separation in astronomical units, given a distance to the system.

Parameters:

• angle (u.Quantity) – The angle in arcseconds

• distance (u.Quantity) – The distance in parsecs

Returns:

The corresponding distance in AU

Return type:

u.Quantity

pyEDITH.units.to_arcsec(quantity: Quantity, observer_distance: Quantity) → float

Convert a physical size to an angular size in arcseconds.

This function converts a physical length to a projected angular size in arcseconds as seen from a given distance. Important: quantity and observer_distance must have the same units!

Parameters:

• quantity (u.Quantity) – The physical size to be converted to arcsec

• observer_distance (u.Quantity) – The distance to the object

Returns:

The corresponding angular size in arcsec

Return type:

float

pyEDITH.utils.average_over_bandpass(params: dict, wavelength_range: list) → dict

Calculate the average of array parameters within a specified wavelength range.

This function takes a dictionary of parameters and computes the mean value of all numpy array parameters (except wavelength) within the specified wavelength boundaries. The wavelength array is expected to be stored under the key “lam” in the params dictionary.

Parameters:

• params (dict) – Dictionary containing parameters where numpy arrays represent wavelength-dependent quantities. Must include a “lam” key containing the wavelength array. These parameters come from EACy and follow that formatting.

• wavelength_range (list) – Two-element list containing the lower and upper wavelength boundaries for averaging, expected to have astropy units

Returns:

Modified parameters dictionary with array values replaced by their mean values within the specified wavelength range

Return type:

dict

pyEDITH.utils.interpolate_over_bandpass(params: dict, wavelengths: list) → dict

Interpolate array parameters onto a new wavelength grid.

This function takes a dictionary of parameters and interpolates all numpy array parameters (except the wavelength array itself) onto a new set of wavelength points using 1D linear interpolation. The original wavelength array is expected to be stored under the key “lam” in the params dictionary.

Parameters:

• params (dict) – Dictionary containing parameters where numpy arrays represent wavelength-dependent quantities. Must include a “lam” key containing the original wavelength array. These parameters come from EACy and follow that formatting.

• wavelengths (list) – New wavelength points onto which to interpolate the parameter arrays

Returns:

Modified parameters dictionary with array values interpolated onto the new wavelength grid specified by the wavelengths parameter

Return type:

dict

pyEDITH.utils.fill_parameters(class_obj: object, parameters: dict, default_parameters: dict) → None

Populate class object attributes with user parameters or default values.

This function sets attributes on a class object by loading user-provided parameters or falling back to default values. It handles both regular values and astropy Quantity objects with units, ensuring proper unit consistency when dealing with physical quantities.

Parameters:

• class_obj (object) – Class instance whose attributes will be set

• parameters (dict) – Dictionary of user-provided parameter values

• default_parameters (dict) – Dictionary of default parameter values with keys matching expected attribute names. Values can be regular types or astropy Quantities

pyEDITH.utils.convert_to_numpy_array(class_obj: object, array_params: list) → None

Convert specified class attributes to numpy arrays with proper dtype.

This function converts class attributes to numpy arrays with float64 dtype, while preserving astropy units for Quantity objects. Non-Quantity attributes are converted to plain numpy arrays, while Quantity attributes maintain their units but have their values converted to numpy arrays.

Parameters:

• class_obj (object) – Class instance whose attributes will be converted

• array_params (list) – List of attribute names to convert to numpy arrays

pyEDITH.utils.validate_attributes(obj: Any, expected_args: Dict[str, Any]) → None

Validate attributes of an object against expected types and units.

This function checks that an object has all the required attributes and that each attribute has the correct type or units. It supports validation of integer and float types as well as astropy Quantity objects with specific units.

Parameters:

• obj (object) – The object whose attributes are to be validated

• expected_args (dict) – A dictionary where keys are attribute names and values are expected types or units

Raises:

• AttributeError – If a required attribute is missing

• TypeError – If an attribute has an incorrect type

• ValueError – If a Quantity attribute has incorrect units or if there’s an unexpected type specification

pyEDITH.utils.print_array_info(file: object, name: str, arr: ndarray, mode: str = 'full_info') → None

Write detailed information about an array or variable to a file.

This function writes comprehensive information about a given array or variable to a specified file, including its shape, data type, units (if applicable), and statistical properties such as minimum and maximum values. The output format depends on the specified mode.

Parameters:

• file (object) – Open file object to write the information to

• name (str) – Name or identifier of the variable/array being described

• arr (np.ndarray) – The array or variable to analyze and describe. Can be a numpy array, an array-like object, or a scalar with or without astropy units

• mode (str, optional) – Output mode that determines the level of detail in the description. Default is “full_info” which provides comprehensive information. Other modes provide more concise output

pyEDITH.utils.print_all_variables(observation: object, scene: object, observatory: object, deltalambda_nm: ndarray, lod: ndarray, lod_rad: ndarray, lod_arcsec: ndarray, area_cm2: ndarray, detpixscale_lod: ndarray, stellar_diam_lod: ndarray, pixscale_rad: ndarray, oneopixscale_arcsec: ndarray, det_sep_pix: ndarray, det_sep: ndarray, det_Istar: ndarray, det_skytrans: ndarray, det_photometric_aperture_throughput: ndarray, det_omega_lod: ndarray, det_CRp: ndarray, det_CRbs: ndarray, det_CRbz: ndarray, det_CRbez: ndarray, det_CRbbin: ndarray, det_CRbth: ndarray, det_CR: ndarray, ix: int, iy: int, sp_lod: float, CRp: ndarray, CRnf: ndarray, CRbs: ndarray, CRbz: ndarray, CRbez: ndarray, CRbbin: ndarray, t_photon_count: ndarray, CRbd: ndarray, CRbth: ndarray, CRb: ndarray) → None

Write comprehensive debug information to files for observation calculations.

This function outputs detailed information about all relevant parameters and calculated variables used in the observation simulation to both validation and full_info text files. It includes observation parameters, scene properties, observatory characteristics, and all intermediate calculations.

Parameters:

• observation (Observation) – Observation object containing observation-specific parameters

• scene (AstrophysicalScene) – Scene object containing astrophysical scene parameters

• observatory (Observatory) – Observatory object containing telescope, coronagraph, and detector parameters

• deltalambda_nm (np.ndarray) – Wavelength intervals in nanometers

• lod (np.ndarray) – Lambda over D values

• lod_rad (np.ndarray) – Lambda over D values in radians

• lod_arcsec (np.ndarray) – Lambda over D values in arcseconds

• area_cm2 (np.ndarray) – Telescope area in cm²

• detpixscale_lod (np.ndarray) – Detector pixel scale in λ/D units

• stellar_diam_lod (np.ndarray) – Stellar diameter in λ/D units

• pixscale_rad (np.ndarray) – Pixel scale in radians

• oneopixscale_arcsec (np.ndarray) – Single pixel scale in arcseconds

• det_sep_pix (np.ndarray) – Detector separation in pixels

• det_sep (np.ndarray) – Detector separation

• det_Istar (np.ndarray) – Detector stellar intensity

• det_skytrans (np.ndarray) – Detector sky transmission

• det_photometric_aperture_throughput (np.ndarray) – Detector photometric aperture throughput

• det_omega_lod (np.ndarray) – Detector solid angle in λ/D units

• det_CRp (np.ndarray) – Detector planet count rate

• det_CRbs (np.ndarray) – Detector background star count rate

• det_CRbz (np.ndarray) – Detector zodiacal background count rate

• det_CRbez (np.ndarray) – Detector exozodiacal background count rate

• det_CRbbin (np.ndarray) – Detector binary background count rate

• det_CRbth (np.ndarray) – Detector thermal background count rate

• det_CR (np.ndarray) – Total detector count rate

• ix (int) – X pixel coordinate

• iy (int) – Y pixel coordinate

• sp_lod (float) – Separation in λ/D units

• CRp (np.ndarray) – Planet count rate

• CRnf (np.ndarray) – Noise floor count rate

• CRbs (np.ndarray) – Background star count rate

• CRbz (np.ndarray) – Zodiacal background count rate

• CRbez (np.ndarray) – Exozodiacal background count rate

• CRbbin (np.ndarray) – Binary background count rate

• t_photon_count (np.ndarray) – Photon counting time

• CRbd (np.ndarray) – Detector background count rate

• CRbth (np.ndarray) – Thermal background count rate

• CRb (np.ndarray) – Total background count rate

pyEDITH.utils.synthesize_observation(snr_arr: ndarray, scene: object, random_seed: int = None, set_below_zero: float = nan) → tuple

Synthesize an observation using calculated SNRs for each wavelength bin.

This function generates a synthetic observation by adding noise to the planet-to-star flux ratio based on the provided signal-to-noise ratio array. The noise is drawn from a normal distribution and scaled according to the SNR values. This function requires that the ETC has been run in SNR mode with a given exposure time first.

Parameters:

• snr_arr (np.ndarray) – 1D array containing SNR for each spectral bin

• scene (AstrophysicalScene) – Scene object containing astrophysical parameters including Fp_over_Fs

• random_seed (int, optional) – Random seed for reproducible noise generation. Default is None

• set_below_zero (float, optional) – Value to assign to measurements below zero. Default is np.nan

Returns:

A tuple containing:

obsnp.ndarray

1D array, spectrum with added noise

noisenp.ndarray

1D array, noise for each spectral bin

Return type:

tuple

pyEDITH.utils.wavelength_grid_fixed_res(x_min: float, x_max: float, res: float = -1) → tuple

Generate a wavelength grid at a fixed spectral resolution.

This function creates a wavelength grid with constant resolution across the specified wavelength range. The grid spacing increases logarithmically to maintain constant R = λ/Δλ.

Parameters:

• x_min (float) – Minimum wavelength

• x_max (float) – Maximum wavelength

• res (float, optional) – Spectral resolution R = λ/Δλ. Default is -1

Returns:

A tuple containing two 1D numpy arrays:

wavelengthnp.ndarray

Wavelength grid

delta_wavelengthnp.ndarray

Delta wavelength grid

Return type:

tuple

pyEDITH.utils.gen_wavelength_grid(x_min: list, x_max: list, res: list) → tuple

Generate a continuous wavelength grid for multiple spectral channels.

This function creates wavelength grids at fixed resolution for each spectral channel, then concatenates them to form a continuous wavelength grid covering all channels.

Parameters:

• x_min (list) – Minimum wavelength for each spectral channel

• x_max (list) – Maximum wavelength for each spectral channel

• res (list) – Spectral resolution for each spectral channel

Returns:

A tuple containing two 1D numpy arrays:

wavelength_gridnp.ndarray

Combined wavelength grid for all channels

delta_wavelength_gridnp.ndarray

Combined delta wavelength grid for all channels

Return type:

tuple

pyEDITH.utils.regrid_wavelengths(input_wls: ndarray, res: list, lam_low: list = None, lam_high: list = None) → tuple

Create a new wavelength grid with specified resolution and channel boundaries.

This function generates a new wavelength grid given the resolution and channel boundaries for each spectral channel. If no boundaries are provided, it uses the full range of the input wavelengths.

Parameters:

• input_wls (np.ndarray) – The wavelength grid supplied by the user

• res (list) – Array of desired resolutions for each channel. Should have length equal to the number of spectral channels. For example, for UV, VIS, and NIR channels: res = [R_UV, R_VIS, R_NIR], e.g. [7, 140, 40]

• lam_low (list, optional) – Array of the lower boundaries of spectral channels

• lam_high (list, optional) – Array of the upper boundaries of spectral channels

Returns:

A tuple containing two 1D numpy arrays:

wavelength_gridnp.ndarray

New wavelength grid

delta_wavelength_gridnp.ndarray

New delta wavelength grid

Return type:

tuple

pyEDITH.utils.regrid_spec_gaussconv(input_wls: ndarray, input_spec: ndarray, new_lam: ndarray, new_dlam: ndarray) → ndarray

Regrid a spectrum onto a new wavelength grid using Gaussian convolution.

This function regrids a spectrum by convolving with Gaussian kernels to account for the spectral resolution at each wavelength point. The convolution is performed in log-wavelength space for accurate spectral line handling.

Parameters:

• input_wls (np.ndarray) – The wavelength grid supplied by the user

• input_spec (np.ndarray) – The spectrum supplied by the user

• new_lam (np.ndarray) – The new wavelength grid calculated for the ETC

• new_dlam (np.ndarray) – The new delta wavelength grid calculated for the ETC

Returns:

1D array containing the regridded spectrum with original units preserved

Return type:

np.ndarray

pyEDITH.utils.regrid_spec_interp(input_wls: ndarray, input_spec: ndarray, new_lam: ndarray) → ndarray

(Legacy) Regrid a spectrum onto a new wavelength grid using 1D interpolation.

This function regrids a spectrum using simple linear interpolation between the original and new wavelength grids. This method is faster than Gaussian convolution but does not account for spectral resolution effects.

Parameters:

• input_wls (np.ndarray) – The wavelength grid supplied by the user

• input_spec (np.ndarray) – The spectrum supplied by the user

• new_lam (np.ndarray) – The new wavelength grid calculated for the ETC

Returns:

1D array containing the regridded spectrum with original units preserved

Return type:

np.ndarray

pyEDITH.parse_input.parse_input_file(file_path: Path | str, secondary_flag: bool) → Tuple[Dict, Dict]

Parse an input file and extract variables and secondary variables.

This function reads a configuration file, processes its contents line by line, and extracts primary and optional secondary variables. It handles various data types including arrays, strings, and numeric values, and performs special processing for IFS observing mode parameters. The function handles various data types including arrays, strings, and numbers. Comments in the input file should start with ‘;’.

Parameters:

• file_path (Union[Path, str]) – Path to the input file

• secondary_flag (bool) – Flag indicating whether secondary variables are expected

Returns:

A tuple containing two dictionaries:

variables: dict

Primary variables extracted from the file

secondary_variables: dict

Secondary variables extracted from the file (any non-specified variable will be the same as in the variables dictionary)

Return type:

Tuple[Dict, Dict]

Raises:

• KeyError – If secondary flag is True but no secondary variables are found in the input file, or if IMAGER mode is specified with multiple wavelengths

• FileNotFoundError – If a specified spectrum file cannot be found

• ValueError – If required parameters are missing or if there are issues with the spectrum file

pyEDITH.parse_input.parse_parameters(parameters: dict, nlambda: int = None) → dict

Parse and process input parameters for simulation.

This function handles various parameter types including wavelength-dependent parameters, target-specific parameters, and scalar values. It converts parameters to appropriate data types and ensures arrays have the correct dimensions based on the number of wavelength points.

Parameters:

• parameters (dict) – A dictionary of input parameters

• nlambda (int, optional) – Number of wavelength points, if not specified in parameters

Returns:

A dictionary of parsed and processed parameters, including: arrays of length nlambda (wavelength-dependent parameters), Scalar parameters, Coronagraph specifications.

Return type:

dict

Raises:

ValueError – If wavelength information is missing and nlambda is not provided, or if array parameters have incorrect dimensions

Note

The function assumes one target (ntargs = 1) for now. nmeananom and norbits are defaulted to 1.

pyEDITH.parse_input.read_configuration(input_file: Path | str, secondary_flag: bool = False) → Tuple[Dict, Dict]

Read and parse configuration from an input file.

This function reads the input file, extracts parameters, and then parses both the primary and secondary parameters. It serves as a high-level wrapper around parse_input_file() and parse_parameters().

Parameters:

• input_file (Union[Path, str]) – Path to the input configuration file

• secondary_flag (bool, optional) – Flag indicating whether secondary variables should be processed, default is False

Returns:

A tuple containing two dictionaries:

parsed_parameters: dict

Parsed primary parameters

parsed_secondary_parameters: dict

Parsed secondary parameters (empty if secondary_flag is False)

Return type:

Tuple[Dict, Dict]

pyEDITH.parse_input.get_observatory_config(parameters: Dict[str, str]) → str | Dict[str, str]

Generate observatory configuration from parameters.

This function extracts observatory configuration information from the parameters dictionary. It either returns a preset name if specified or constructs a custom configuration dictionary with telescope, coronagraph, and detector components.

Parameters:

parameters (Dict[str, str]) – Dictionary containing configuration parameters

Returns:

Either a string (if using a preset) or a dictionary (for custom configurations)

Return type:

Union[str, Dict[str, str]]

Raises:

ValueError – If any required component type is not specified

pyEDITH.parse_input.print_observatory_config(config: str | Dict[str, str]) → None

Print the observatory configuration to the terminal.

This function formats and displays the observatory configuration in a human-readable format, showing either the preset name or the individual component selections.

Parameters:

config (Union[str, Dict[str, str]]) – The observatory configuration, either as a string (preset) or a dictionary (custom configuration)