Functions

Every function available for the user to interact with to form the basis of an atmospheric dispersion analysis is presented below.

class atmosphyre.dispersion.sim(**kwargs)

This is the class for the module’s atmospheric dispersion simulations.

Parameters:

  • telescope_diameter (float) – Telescope diameter, in metres. Default = 39m.

  • wavefront_outer_scale (float) – Characteristic wavefront outer scale. Default = 46m.

  • seeing (float) – Seeing for the observation, in arcsec. Default = 0.68 arcsec.

  • seeing_wl (float) – Wavelength of the given seeing measurement for the observation, in micrometers. Default = 0.5um.

  • simulation_scale (float) – Pixel scale of the simulation, in arcsec/pixel. Default = 0.01 arcsec/pixel, which shows high accuracy.

  • simulation_intervals (int) – Number of intervals in the observation to simulate for and calculate transmission. Default = 21.

  • latitude (float) – Latitude of the telescope, in degrees. Default = -24.63 degrees.

  • temperature (float) – Environment temperature at the telescope, in degrees celsius. Default = 10 degC.

  • humidity (float) – Environment relative humidity at the telescope, in %. Default = 14.5%

  • pressure (float) – Environment pressure at the telescope, in mBa. Default = 750mBa.

  • centring (float) – The time of the observation at which the position of the apertures is determined by. Either 0.5 for halfway (default), or if an integer this will be the index of the simulation intervals.

  • relative_plate_PA_angle (float) – Relative angle of the apertures/focal plate and the North Celestial Pole direction, in degrees. For the aperture semi-major axis to be pointed along the NCP direction, set to 90 degrees. Default = 0 degrees.

To create the target class and run functions:

from atmosphyre import dispersion

simulation = dispersion.sim(**kwargs)
simulation.chosen_function(parameters=parameter_values)
load_wavelengths(wavelengths=[])

Input the desired wavelengths for the analysis. Shifts and transmissions will be calculated for these.

Parameters:

wavelengths (list of float) – Wavelengths to calculate transmission for, units of micrometers (um).

load_observation(observation_start=0, observation_end=1, declination=-30)

Input the observation/target details. This calculates the airmasses and parallatic angles for the observation.

Parameters:

  • observation_start (float) – Start of the observation in terms of hour angles, default = 0h.

  • observation_end (float) – End of the observation in terms of hour angles, default = 1h.

  • declination (float) – Declination of the observation target, in degrees. Default = -30 deg.

calculate_integration_shifts(guide_wavelength=0.8, aperture_wavelength=0.8)

Calculates the shift for each wavelength during an integration based on the observation details.

This is dependent on two reference wavelengths:

  1. the guide wavelength - the wavelength the telescope guides on, which remains fixed on the focal plane.

  2. the aperture wavelength - the wavelength of the dispersed light that the aperture centre is positioned on.

Shifts are calculated using the Fillipenko 1982 model.

This function must come after load_wavelengths and load_observation

Parameters:

  • guide_wavelength (float) – The observation’s guide wavelength, in units of micrometers. Default = 0.8um.

  • aperture_wavelength – The wavelength of the dispersed light that the aperture centre is positioned on, in units of micrometers - by default this refers to the dispersion half-way through the observation. Default = 0.8um.

load_aperture(aperture_major_axis=0.6, aperture_type='circle', hexagon_radius=1)

Define the spectrograph aperture.

Parameters:

  • aperture_major_axis (float) – Length of the aperture’s major axis, units of arcseconds. Default = 0.6 arcsec.

  • aperture_type (string) – Aperture shape to use in the simulation. Currently can be one of “hexagons”, “circle”, (WIP: slit, square). Default = “circle”.

  • hexagon_radius (int) – If aperture is “hexagons”, the number of rings in the hexagonally packed array. Default = 1.

load_PSFs(PSF_type='moffat', moffat_beta=2.5)

Define and generate the PSFs. These will be generated with airmass and wavelength dependences and are needed for the transmission calculations.

This function must come after load_wavelengths, load_observation, load_aperture, and calculate_integration_shifts.

Parameters:

  • PSF_type (string) – PSF form to use in the simulations. Can be one of “moffat”, “gaussian”. Default = “moffat”

  • moffat_beta (float) – Power value of the moffat PSF. Default = 2.5

calculate_integration_transmissions()

Numerically calculates the transmissions values.

This function must come after load_wavelengths, load_observation, load_aperture, calculate_integration_shifts, and load_PSFs.

integration_plots(y_axis='relative', track_indexes=[0, -1])
Illustrates simulation results with two graphs:

  1. Transmission vs wavelength curves for individual fibres and entire bundle.

  2. Track plot of monochromatic spot PSFs on the aperture over an integration.

This function must come after calculate_integration_transmissions

Parameters:

  • y_axis (string) – The y-axis of the transmission plot can be relative to either raw transmissions or no atmospheric-dispersion transmissions. Options are “raw” or “relative” respectively. Default = “relative”.

  • track_indexes (list of int) – indexes of the wavelengths to use for the track plot. Default = [0,-1].

run(observation_start=0, observation_end=1, declination=-30, wavelengths=[], aperture_major_axis=[], guide_wavelength=0, aperture_wavelength=0, **kwargs)

A simple in-built (but limited) atmospheric dispersion simulation.

The guide and aperture will be optimised to the nearest 0.1um if values are not input. The simulation in this setup is a circular fibre with atmopsheric moffat PSFs.

Parameters:

  • observation_start (float) – Start of the observation in terms of hour angles, default = 0h.

  • observation_end (float) – End of the observation in terms of hour angles, default = 1h.

  • declination (float) – Declination of the observation target, in degrees. Default = -30 deg.

  • wavelengths (list of float) – Wavelengths to calculate transmission for, units of micrometers (um).

  • aperture_major_axis (float) – Length of the aperture’s major axis, units of arcseconds. Default = 0.6 arcsec.

  • guide_wavelength (float) – The observation’s guide wavelength, in units of micrometers. Default = 0 - automatically optimised.

  • aperture_wavelength – The wavelength of the dispersed light that the aperture centre is positioned on, in units of micrometers - by default this refers to the dispersion half-way through the observation. Default = 0: automatically optimised.

optimise_integration(guide_options=[], aperture_options=[], guide_aperture='equal')

Optimise the aperture and guide wavelengths. The metric optimised is the transmission curve’s minimum multiplied by the throughput squared.

This function must come after load_wavelengths, load_observation, and load_aperture

Parameters:

  • guide_wavelength (list of float) – The possible observation’s guide wavelengths, in units of micrometers.

  • aperture_wavelength – The possible wavelengths of the dispersed light that the aperture centre is positioned on, in units of micrometers - by default this refers to the dispersion half-way through the observation.

  • guide_aperture (string) – Determines whether the guide and aperture wavelengths are independent or are set to be equal, options are “independent” or “equal” respectively. Default = “equal”

load_ZA(ZA_range=[])
calculate_snapshot_shifts(aperture_wavelength)
calculate_snapshot_transmissions()
snapshot_plots(y_axis='relative')