Configuration¶

Configuration of the system is handled by the confParse module, that reads the simulation parameters from a given configuration file. This file should be a YAML file, which contains groups for each simulation sub-module. Where a sub-module may consist of multiple components i.e. Wave-front sensors, each WFS must be specified seperately, with an integer index, for example:

WFS:
        0:
                GSMag: 0
                GSPosition: (0, 0)
        1:
                GSMag: 1
                GSPosition: (1, 0)

Example configuration files can be found in the conf directory of the soapy package. (Note: Previously, a Python file was used for configuration. This format is still supported but can lead to messy configuration files! There are still examples of these in the source repository if you prefer.)

Below is a list of all possible simulation parameters. Parameters which have a description ending in ** can be altered while the simulation is running. When others are changed and aoinit must be run before they will take effect and they may break a running simulation.

Simulation Parameters¶

class soapy.confParse.SimConfig(N=None)[source]¶

Configuration parameters relavent for the entire simulation. These should be held at the beginning of the parameter file with no indendation.

Required:

Parameter	Description
`pupilSize`	int: Number of phase points across the simulation pupil
`nIters`	int: Number of iteration to run simulation
`loopTime`	float: Time between simulation frames (1/framerate)

Optional:

Parameter	Description	Default
`nGS`	int: Number of Guide Stars and WFS	`0`
`nDM`	int: Number of deformable Mirrors	`0`
`nSci`	int: Number of Science Cameras	`0`
`reconstructor`	str: name of reconstructor class to use. See `reconstructor` module for available reconstructors.	`"MVM"`
`simName`	str: directory name to store simulation data	`None`
`wfsMP`	bool: Each WFS uses its own process	`False`
`verbosity`	int: debug output for the simulation ranging from 0 (no-ouput) to 3 (all debug output)	`2`
`logfile`	str: name of file to store logging data,	`None`
`learnIters`	int: Number of learn iterations for Learn & Apply reconstructor	`0`
`learnAtmos`	str: if `random`, then random phase screens used for learn	`random`
`simOversize`	float: The fraction to pad the pupil size with to reduce edge effects	`1.2`
`loopDelay`	int: loop delay in integer count of `loopTime`	`0`
`threads`	int: Number of threads to use for multithreaded operations	`1`
`photometric_zp`	float: Photometric zeropoint - number of photons/meter/second from a magnitude 0 star	`2e9`

Data Saving (all default to False):

Parameter	Description
`saveSlopes`	Save all WFS slopes. Accessed from sim with `sim.allSlopes`
`saveDmCommands`	Saves all DM Commands. Accessed from sim with `sim.allDmCommands`
`saveWfsFrames`	Saves all WFS pixel data. Saves to disk a after every frame to avoid using too much memory
`saveStrehl`	Saves the science camera Strehl Ratio. Accessed from sim with `sim.longStrehl` and `sim.instStrehl`
`saveWfe`	Saves the science camera wave front error. Accessed from sim with `sim.WFE`.
`saveSciPsf`	Saves the science PSF.
`saveInstPsf`	Saves the instantenous science PSF.
`saveInstScieField`	Saves the instantaneous electric field at focal plane.
`saveSciRes`	Save Science residual phase

Telescope Parameters¶

class soapy.confParse.TelConfig(N=None)[source]¶

Configuration parameters characterising the Telescope. These should be held in the Telescope group in the parameter file.

Required:

Parameter	Description
`telDiam`	float: Diameter of telescope pupil in metres

Optional:

Parameter	Description	Default
`obsDiam`	float: Diameter of central obscuration	`0`
`mask`	str: Shape of pupil (only accepts `circle` currently)	`circle`

Atmosphere Parameters¶

class soapy.confParse.AtmosConfig(N=None)[source]¶

Configuration parameters characterising the atmosphere. These should be held in the Atmosphere group in the parameter file.

Required:

Parameter	Description
`scrnNo`	int: Number of turbulence layers
`scrnHeights`	list, int: Phase screen heights in metres
`scrnStrength`	list, float: Relative layer scrnStrength
`windDirs`	list, float: Wind directions in degrees.
`windSpeeds`	list, float: Wind velocities in m/s
`r0`	float: integrated seeing strength (metres at 500nm)

Optional:

Parameter	Description	Default
`scrnNames`	list, string: filenames of phase if loading from fits files. If `None` will make new screens.	`None`
`subHarmonics`	bool: Use sub-harmonic screen generation algorithm for better tip-tilt statistics - useful for small phase screens.	`False`
`L0`	list, float: Outer scale of each layer. Kolmogorov turbulence if `None`.	`None`
`randomScrns`	bool: Use a random set of phase phase screens for each loop iteration?	`False`
`infinite`	bool: Use infinite phase screens?	`False`
`tau0`	float: Turbulence coherence time, if set wind speeds are scaled.	`None`
`wholeScrnSize`	int: Size of the phase screens to store in the `atmosphere` object. Required if large screens used.	`None`

Wave-front Sensor Parameters¶

class soapy.confParse.WfsConfig(N=None)[source]¶

Configuration parameters characterising Wave-front Sensors. These should be held in the WFS group in the parameter file. Each WFS is specified by first specifying an index, then the WFS parameters. Any entries above sim.nGS will be ignored.

Required:

Parameter	Description
`GSPosition`	tuple: position of GS on-sky in arc-secs
`wavelength`	float: wavelength of GS light in metres
`nxSubaps`	int: number of SH sub-apertures

Optional:

Parameter	Description	Default
`type`	string: Which WFS object to load from WFS.py?	`ShackHartmann`
`GSMag`	float: Apparent magnitude of the guide star	`0`
`photonNoise`	bool: Include photon (shot) noise.	`False`
`eReadNoise`	float: Electrons of read noise	`0`
`throughput`	float: Throughput of the entire optical and electronic system from guide star photons to recorded WFS detector counts. Includes atmospheric effects, the optical train and detector gain.	`1.`
`propagationMode`	string: Mode of light propogation from GS. Can be “Physical” or “Geometric”**.	`"Geometric"`
`subapFieldStop`	bool: if True, add a field stop to the wfs to prevent spots wandering into adjacent sub-apertures. if False, oversample subap FOV by a factor of 2 to allow into adjacent subaps.	`False`
`removeTT`	bool: if True, remove TT signal from WFS slopes before reconstruction.**	`False`
`fftOversamp`	int: Multiplied by the number of of phase points required for FOV to increase fidelity from FFT.	`3`
`GSHeight`	float: Height of GS beacon. `0` if at infinity.	`0`
`subapThreshold`	float: How full should subap be to be used for wavefront sensing?	`0.5`
`lgs`	bool: is WFS an LGS?	`False`
`centMethod`	string: Method used for Centroiding. Can be `centreOfGravity`, `brightestPxl`, or `correlation`.**	`centreOfGravity`
`referenceImage`	array: Reference images used in the correlation centroider. Full image plane image, each subap has a separate reference image	`None`
`angleEquivNoise`	float: width of gaussian noise added to slopes measurements in arc-secs	`0`
`centThreshold`	float: Centroiding threshold as a fraction of the max subap value.**	`0.1`
`exposureTime`	float: Exposure time of the WFS camera - must be higher than loopTime. If None, will be set to loopTime.	`None`
`wvlBandWidth`	float: Width of wavelength band sent to WFS in nm	`100`
`extendedObject`	ndarray or str: The object used as extended source for WFS, of size 2fftOversamppxlsPerSubap. The FOV of the object should be twice the FOV of the sub-aperture.	`None`
`fftwThreads`	int: number of threads for fftw to use. If `0`, will use system processor number.	`1`
`fftwFlag`	str: Flag to pass to FFTW when preparing plan.	`FFTW_PATIENT`
`pxlsPerSubap`	int: number of pixels per sub-apertures	`10`
`subapFOV`	float: Field of View of sub-aperture in arc-secs	`5`
`correlationFFTPad`	int: Padding for correlation WFS	`None`
`nx_guard_pixels`	int: Guard Pixels between Shack-Hartmann sub-apertures (Not currently operational)	`0`

Laser Guide Star Parameters¶

class soapy.confParse.LgsConfig(N=None)[source]¶

Configuration parameters characterising the Laser Guide Stars. These should be held in the LGS sub-group of the WFS parameter group.

Optional:

Parameter	Description	Default
`uplink`	bool: Include LGS uplink effects	`False`
`pupilDiam`	float: Diameter of LGS launch aperture in metres.	`0.3`
`wavelength`	float: Wavelength of laser beam in metres	`600e-9`
`propagationMode`	str: Mode of light propogation from GS. Can be “Physical” or “Geometric”.	`"Phsyical"`
`height`	float: Height to use physical propogation of LGS (does not effect cone-effect) in metres	`90000`
`elongationDepth`	float: Depth of LGS elongation in metres	`0`
`elongationLayers`	int: Number of layers to simulate for elongation.	`10`
`launchPosition`	tuple: The launch position of the LGS in units of the pupil radii, where `(0,0)` is the centre launched case, and `(1,0)` is side-launched.	`(0,0)`
`fftwThreads`	int: number of threads for fftw to use. If `0`, will use system processor number.	`1`
`fftwFlag`	str: Flag to pass to FFTW when preparing plan.	`FFTW_PATIENT`
`naProfile`	list: The relative sodium layer strength for each elongation layer. If None, all equal.	`None`

Deformable Mirror Parameters¶

class soapy.confParse.DmConfig(N=None)[source]¶

Configuration parameters characterising Deformable Mirrors. These should be held in the DM sub-group of the parameter file. Each DM is specified seperately, by first specifying an index, then the DM parameters. Any entries above sim.nGS will be ignored.

Required:

Parameter	Description
`type`	string: Type of DM. This must the name of a class in the `DM` module.
`nxActuators`	int: Number independent DM shapes. e.g., for stack-array DMs this is number of actuators in one dimension, for Zernike DMs this is number of Zernike modes.
`gain`	float: The loop gain for the DM.**
`svdConditioning`	float: The conditioning parameter used in the pseudo inverse of the interaction matrix. This is performed by numpy.linalg.pinv.

Optional:

Reconstructor Parameters¶

class soapy.confParse.ReconstructorConfig(N=None)[source]¶

Configuration parameters describing the reconstructor that will be used to calculate DM commands from WFS measurements. The type must be an object in the soapy.reconstruction module. Other parameters may be specific to this reconstructor

Optional:

Parameter	Description	Default
`type`	string: Type of reconstructor to use. Must be a class in reconstruction module.	`MVM`
`svdConditioning`	float: Conditioning parameter to be using in Least Squares reconstructor inversion SVD to cut off unwanted DM modes. See `numpy.linalg.pinv` for details about the inversion.	`0`
`gain`	float: Gain of the integrator loop.	`0.6`
`imat_noise`	bool: include WFS noise when making in interaction matrix	`True`

Science Camera Parameters¶

class soapy.confParse.SciConfig(N=None)[source]¶

Configuration parameters characterising Science Cameras.

These should be held in the Science of the parameter file. Each Science target is created seperately with an integer index. Any entries above sim.nSci will be ignored.

Required:

Parameter	Description
`position`	tuple: The position of the science camera in the field in arc-seconds
`FOV`	float: The field of fiew of the science detector in arc-seconds
`wavelength`	float: The wavelength of the science detector light
`pxls`	int: Number of pixels in the science detector

Optional:

Parameter	Description	Default
`pxlScale`	float: Pixel scale of science camera, in arcseconds. If set, overwrites `FOV`.	`None`
`type`	string: Type of science camera This must the name of a class in the `SCI` module.	`PSF`
`fftOversamp`	int: Multiplied by the number of of phase points required for FOV to increase fidelity from FFT.	`2`
`fftwThreads`	int: number of threads for fftw to use. If `0`, will use system processor number.	`1`
`fftwFlag`	str: Flag to pass to FFTW when preparing plan.	`FFTW_MEASURE`
`height`	float: Altitude of the object. 0 denotes infinity.	`0`
`propagationMode`	str: Mode of light propogation from object. Can be “Physical” or “Geometric”.	`"Geometric"`
`instStrehlWithTT`	bool: Whether or not to include tip/tilt in instantaneous Strehl calculations.	`False`