API Reference¶
The simplest possible simulation involves initializing a simulator and simulating one exposure, for example:
import specsim.simulator
simulator = specsim.simulator.Simulator('desi')
simulator.simulate()
In this example, the entire simulation is configured by the contents of the file
specsim/data/config/desi.yaml. To use a different configuration, either
copy and edit this file or else change parameters programmatically before
initializing the simulator, for example:
import specsim.config
import specsim.simulator
config = specsim.config.load_config('desi')
config.atmosphere.airmass = 1.5
config.source.filter_name = 'sdss2010-r'
config.source.ab_magnitude_out = 22.5
simulator = specsim.simulator.Simulator(config)
simulator.simulate()
Many parameters can also be changed via an initialized simulator, without repeating the initialization step, for example:
import specsim.simulator
simulator = specsim.simulator.Simulator('desi')
simulator.simulate()
simulator.atmosphere.airmass = 1.5
simulator.observation.exposure_time = 20 * u.min
simulator.source.update_out(filter_name='sdss2010-r', ab_magnitude_out=21.0)
simulator.simulate()
specsim.config Module¶
Manage simulation configuration data.
Configuration data is normally loaded from a yaml file. Some standard configurations are included with this package and can be loaded by name, for example:
>>> test_config = load_config('test')
Otherwise any filename with extension .yaml can be loaded:
my_config = load_config('path/my_config.yaml')
Configuration data is accessed using attribute notation to specify a sequence of keys:
>>> test_config.name
'Test Simulation'
>>> test_config.atmosphere.airmass
1.0
Use Configuration.get_constants() to parse values with dimensions and
Configuration.load_table() to load and interpolate tabular data.
Functions¶
is_string(x) |
Test if x is a string type. |
load_config(name[, config_type]) |
Load configuration data from a YAML file. |
parse_quantity(quantity[, dimensions]) |
Parse a string containing a numeric value with optional units. |
Classes¶
Configuration(config) |
Configuration parameters container and utilities. |
Node(value[, path]) |
A single node of a configuration data structure. |
specsim.atmosphere Module¶
Model atmospheric emission and absorption for spectroscopic simulations.
The atmosphere model is responsible for calculating the spectral flux density arriving at the telescope given a source flux entering the atmosphere. The calculation is either performed as:
if extinct_emission is False, or else as:
where \(s(\lambda)\) is the source flux entering the atmosphere, \(e(\lambda)\) is the zenith extinction, \(X\) is the airmass, \(a\) is the fiber entrance face area, and \(b(\lambda)\) is the sky emission surface brightness. The sky brightness can optionally include a scattered moonlight component.
An atmosphere model is usually initialized from a configuration used to create
a simulator and then accessible via its atmosphere attribute, for example:
>>> import specsim.simulator
>>> simulator = specsim.simulator.Simulator('test')
>>> simulator.atmosphere.airmass
1.0
See API Reference for examples of changing model parameters defined in the configuration. Certain parameters can also be changed after a model has been initialized, for example:
>>> simulator.atmosphere.airmass = 1.5
>>> simulator.atmosphere.moon.moon_phase = 0.25
>>> simulator.atmosphere.moon.moon_zenith = 25 * u.deg
See Atmosphere and Moon for details.
Functions¶
initialize(config) |
Initialize the atmosphere model from configuration parameters. |
krisciunas_schaefer(obs_zenith, moon_zenith, …) |
Calculate the scattered moonlight surface brightness in V band. |
plot_lunar_brightness(moon_zenith, …[, …]) |
Create a polar plot of the scattered moon brightness in V band. |
Classes¶
Atmosphere(wavelength, …) |
Model atmospheric surface brightness and extinction. |
Moon(wavelength, moon_spectrum, …) |
Model of scattered moonlight. |
specsim.instrument Module¶
Model an instrument response for spectroscopic simulations.
An instrument model is usually initialized from a configuration used to create
a simulator and then accessible via its instrument attribute, for example:
>>> import specsim.simulator
>>> simulator = specsim.simulator.Simulator('test')
>>> print(np.round(simulator.instrument.fiber_diameter, 1))
107.0 um
See API Reference for examples of changing model parameters defined in the configuration. No attributes can be changed after a simulator has been created. File a github issue if you would like to change this.
An Instrument includes one or more
Cameras.
Functions¶
initialize(config[, camera_output]) |
Initialize the instrument model from configuration parameters. |
Classes¶
Instrument(name, wavelength, …) |
Model the instrument response of a fiber spectrograph. |
specsim.camera Module¶
Model a fiber spectrograph camera for spectroscopic simulations.
Cameras belong to an Instrument and
are usually initialized from a configuration used to create
a simulator and then accessible via its instrument.cameras attribute,
for example:
>>> import specsim.simulator
>>> simulator = specsim.simulator.Simulator('test')
>>> print(np.round(simulator.instrument.cameras[0].read_noise, 1))
2.9 electron / pix2
See API Reference for examples of changing model parameters defined in the configuration. No attributes can be changed after a simulator has been created. File a github issue if you would like to change this.
specsim.source Module¶
Model an astronomical source for spectroscopic simulations.
An source model is usually initialized from a configuration used to create
a simulator and then accessible via its source attribute, for example:
>>> import specsim.simulator
>>> simulator = specsim.simulator.Simulator('test')
>>> print(simulator.source.name)
Constant flux density test source
After initialization, all aspects of a source can be modified at runtime.
Functions¶
initialize(config) |
Initialize the source model from configuration parameters. |
specsim.observation Module¶
Model an astronomical observation for spectroscopic simulations.
An observation is usually initialized from a configuration used to create
a simulator and then accessible via its observation attribute, for example:
>>> import specsim.simulator
>>> simulator = specsim.simulator.Simulator('test')
>>> print(simulator.observation.exposure_time)
1000.0 s
Functions¶
initialize(config) |
Initialize the observation from configuration parameters. |
Classes¶
Observation(location, exposure_time, …) |
Model the parameters describing a single spectroscopic observation. |
specsim.fiberloss Module¶
Calculate fiberloss fractions.
Fiberloss fractions are computed as the overlap between the light profile illuminating a fiber and the on-sky aperture of the fiber.
Functions¶
calculate_fiber_acceptance_fraction(focal_x, …) |
Calculate the acceptance fraction for a single fiber. |
Classes¶
GalsimFiberlossCalculator(fiber_diameter, …) |
Initialize a fiberloss calculator that uses GalSim. |
specsim.simulator Module¶
Top-level manager for spectroscopic simulation.
For an overview of using a Simulator, see the
examples notebook.
A simulator is usually initialized from a configuration, for example:
>>> simulator = Simulator('test', num_fibers=500)
See API Reference for examples of changing model parameters defined in the configuration. Certain parameters can also be changed after a model has been initialized, for example:
>>> simulator.atmosphere.airmass = 1.5
>>> simulator.observation.exposure_time = 1200 * u.s
See source, atmosphere and instrument for details.
The positions and properties of individual sources in an exposure can be
specified using optional array arguments to the simulate method.
Functions¶
plot_simulation(simulated, camera_output[, …]) |
Plot simulation output tables for a single fiber. |
specsim.transform Module¶
Implement transformations between sky and focal plane coordinate systems.
The sky_to_altaz() and altaz_to_sky() functions use the
atmospheric refraction model implemented in astropy.coordinates.AltAz,
based on that implemented in ERFA, which
is fast but becomes inaccurate at low altitudes (high airmass). The table
below (from this notebook) gives the round-trip altitude
errors for converting from (alt,az) to (ra,dec) and back to (alt,az):
| Altitude (deg) | Error (arcsec) |
|---|---|
| 10.0 | -15.175 |
| 15.0 | -1.891 |
| 20.0 | -0.425 |
| 25.0 | -0.130 |
| 30.0 | -0.048 |
| 35.0 | -0.020 |
| 40.0 | -0.009 |
| 45.0 | -0.004 |
The sky_to_altaz() and altaz_to_sky() issue a warning when using
altitude angles (and a non-zero atmospheric pressure) below 20 degrees. The
value of this threshold can be read and changed programmatically via the
low_altitude_threshold module attribute.
Attributes¶
- observatories : dict
- Dictionary of predefined observing locations represented as
astropy.coordinates.EarthLocationobjects. - low_altitude_threshold :
astropy.coordinates.Angle - The atmospheric refraction model becomes inaccurate for altitude angles
below this threshold, so
sky_to_altaz()andaltaz_to_sky()will issue aUserWarningif they encounter a lower value, unless refraction has been disabled by specifying zero pressure.
Functions¶
adjust_time_to_hour_angle(nominal_time, …) |
Adjust a time to a specified target hour angle. |
altaz_to_focalplane(alt, az, alt0, az0[, …]) |
Convert local (alt,az) coordinates to focal plane (x,y) coordinates. |
altaz_to_sky(alt, az, observing_model[, frame]) |
Convert (alt,az) to sky coordinates for specified observing conditions. |
create_observing_model(where, when, wavelength) |
Create a model for observations through the atmosphere. |
focalplane_to_altaz(x, y, alt0, az0[, …]) |
Convert focal plane (x,y) coordinates to local (alt,az) coordinates. |
sky_to_altaz(sky_coords, observing_model) |
Convert sky coordinates to (alt,az) for specified observing conditions. |