scopesim.optics.optical_train.OpticalTrain

scopesim.optics.optical_train.OpticalTrain#

class scopesim.optics.optical_train.OpticalTrain(cmds=None)#

Bases: object

The main class for controlling a simulation.

Parameters:

cmds (UserCommands, str) – If the name of an instrument is passed, OpticalTrain tries to find the instrument package, and internally creates the UserCommands object

Examples

Create an optical train:

>>> import scopesim as im
>>> cmd = sim.UserCommands("MICADO")
>>> opt = sim.OpticalTrain(cmd)

Observe a Source object:

>>> src = sim.source.source_templates.empty_sky()
>>> opt.observe(src)
>>> hdus = opt.readout()

If no Source is specified, an empty field is observe, so that the following is equivalent to the commands above:

>>> opt.observe()
>>> hdus = opt.readout()

List the effects modelled in an OpticalTrain:

>>> print(opt.effects)

Effects can be accessed by using the name of the effect:

>>> print(opt["dark_current"])

To include or exclude an effect during a simulation run, use the .include attribute of the effect:

>>> opt["dark_current"].include = False

Data used by an Effect object is contained in the .data attribute, while other information is contained in the .meta attribute:

>>> opt["dark_current"].data
>>> opt["dark_current"].meta

Meta data values can be set by either using the .meta attribute directly:

>>> opt["dark_current"].meta["value"] = 0.5

or by passing a dictionary (with one or multiple entries) to the OpticalTrain object:

>>> opt["dark_current"] = {"value": 0.75, "dit": 30}
__init__(cmds=None)#

Methods

__init__([cmds])

load(user_commands)

(Re)Load an OpticalTrain with a new set of UserCommands.

observe([orig_source, update])

Main controlling method for observing Source objects.

prepare_source(source)

Prepare source for observation.

readout([filename, reset])

Produce detector readouts for the observed image.

report()

shutdown()

Shut down the instrument.

update(**kwargs)

Update the user-defined parameters and remake main internal classes.

write_header(hdulist)

Write meaningful header to simulation product.

Attributes

effects

load(user_commands)#

(Re)Load an OpticalTrain with a new set of UserCommands.

Parameters:

user_commands (UserCommands or str)

observe(orig_source=None, update=True, **kwargs)#

Main controlling method for observing Source objects.

Parameters:

  • orig_source (Source)

  • update (bool) – Reload optical system

  • kwargs (expanded dict) – Any keyword-value pairs from a config file

Notes

When orig_source is None (e.g. when writing opt.observe()), an empty field is observed (internally created with empty_sky()).

How the list of Effects is split between the 5 main tasks:

  • Make a FOV list - z_order = 0..99

  • Make a image plane - z_order = 100..199

  • Apply Source altering effects - z_order = 200..299

  • Apply FOV specific (3D) effects - z_order = 300..399

  • Apply FOV-independent (2D) effects - z_order = 400..499

  • [Apply detector plane (0D, 2D) effects - z_order = 500..599]

Todo

List is out of date - update

prepare_source(source)#

Prepare source for observation.

The method is currently applied to cube fields only. The source data are converted to internally used units (PHOTLAM). The source data are interpolated to the waveset used by the FieldOfView This is necessary when the source data are sampled on a coarser grid than used internally, or if the source data are sampled on irregular wavelengths. For cube fields, the method assumes that the wavelengths at which the cube is sampled is provided explicitely as attribute wave of the cube ImageHDU.

readout(filename=None, reset=True, **kwargs)#

Produce detector readouts for the observed image.

Parameters:

  • filename (str, optional) – Where to save the FITS file

  • kwargs

Returns:

hdu

Return type:

fits.HDUList

Notes

  • Apply detector plane (0D, 2D) effects - z_order = 500..599

shutdown()#

Shut down the instrument.

This method closes all open file handles and should be called when the optical train is no longer needed.

update(**kwargs)#

Update the user-defined parameters and remake main internal classes.

Parameters:

kwargs (expanded dict) – Any keyword-value pairs from a config file

write_header(hdulist)#

Write meaningful header to simulation product.

Contents