Using the Calculator

After the package has been successfully installed and verified, the following workflow describes how to setup and perform sensitivity or integration time calculations given weather, telescope and instrumentation settings and either a required sensitivity (to calculate on source integration time) or an integration time (to calculate sensitivity).

Basic usage

After installing the package and creating the conda environment, follow these commands to import the calculator and required packages and run simple time and sensitivity calculations for a given set of weather, telescope and instrument parameters.

First, import the calculator package to interact with the calculator classes and methods:

from atlast_sc.calculator import Calculator

Since the sensitivity calculator depends on parameters being specified with units, you will also find it useful to import astropy.units as this package is required for defining the user inputs:

import astropy.units as u

Next, initialise the calculator object. The Calculator class is the main interface to the sensitivity calculator, and provides a single point of access to all of the calculator’s functionality. Initializing a calculator object at the beginning of your python session ensures that your changes to setup parameters are used consistently throughout.

calculator = Calculator()

The Sensitivity Calculator is pre-configured with default values for all user input parameters. See here for information on the calculation input parameters and their default values.

You may also initialize the calculator with your own input values. This is described in the section Using the Calculator. To see what values have already been set, you can use:

calculator.user_input.show()

All input parameters can be updated manually, using the parameter names listed from calculator.user_input.show(). For example, to set the bandwidth after initializing the calculator:

calculator.user_input.bandwidth = 150*u.MHz

All input parameters are validated by the calculator. You will see an error if the values you provide are invalid (e.g., are out of a specified range or have invalid units), and the calculator will warn you if (or when) the input parameters force it into a configuration that mandates a different instrument.

With all of the input parameters set to meet your required calculation, including integration time, call the calculate_sensitivity method to obtain the sensitivity (in mJy):

calculated_sensitivity = calculator.calculate_sensitivity()

Alternatively, to obtain the integration time required having specified a sensitivity, call calculate_t_integration:

calculated_t_int = calculator.calculate_t_integration()

If the calculated integration time or sensitivity is outside the permitted range of values, the calculator will report a warning and the calculated value will not be stored in the Calculator object.

Checking the parameters stored by the calculator

The calculator stores the user input parameters, instrument, telescope and environment setup parameters, and any further derived parameters calculated from other inputs. You can output these parameters to the console as follows:

# Check the user input parameters
>>> calculator.user_input.show()
bandwidth: 100.0 MHz
elevation: 45.0 deg
n_pol: 2.0
obs_freq: 406.0 GHz
sensitivity: 3.0 mJy
t_int: 100.0 s
weather: 25.0

# Check the telescope and environment parameters
>>> calculator.telescope_and_environment.show()
T_amb: 270.0 K
T_cmb: 2.726 K
dish_radius: 25.0 m
eta_block: 0.94
eta_eff: 0.95
eta_ill: 0.8
eta_pol: 0.995
eta_spill: 0.95
surface_rms: 25.0 micron

# Check the derived parameters
>>> calculator.derived_parameters.show()
T_atm: 243.8202986577273 K
T_sky: 48.57281962348794 K
T_sys: 205.82149141522652 K
eta_a: 0.5931321480347472
eta_s: 0.99
sefd: 4.88003172682879e-24 J / m2
transmittance: 0.8008347287626261

The user input and derived parameters can be output to a file as described in the writing parameters to a file section.

Resetting the calculator

You can reset the user input parameters stored in the calculator to their initial values using the reset method:

# initialize the calculator with its default values
calculator = Calculator.calculator

# change the value of one of the parameters
calculator.user_input.bandwidth = 150*u.MHz

# reset the calculator
calculator.reset()

# check the bandwidth value stored in the calculator
print('bandwidth', calculator.user_input.bandwidth)
# expected output
# bandwidth 100.0 MHz

Initializing the Calculator with a dictionary

The Calculator object accepts a dictionary as input. First, create a dictionary with the input data you wish to use:

input_data = {
    't_int': {'value': 120, 'unit': 's'},
    'sensitivity': {'value': 0.01, 'unit': 'mJy'},
    'bandwidth': {'value': 7.5, 'unit': 'GHz'},
    'obs_freq': {'value': 200, 'unit': 'GHz'},
    'n_pol': {'value': 2},
    'weather': {'value': 25},
    'elevation': {'value': 25, 'unit': 'deg'}
}

Next, create a new Calculator object, passing the input_data dictionary.

calculator = Calculator(input_data).calculator

All values must be numeric (integer or float), and units (when required) must be presented as astropy units. The Calculator will throw an error if any of the input parameter names are incorrect. If any of the parameters have not been manually set via the input data dictionary, the calculator will use the appropriate default values and units.

The dictionary can be generated from an input file as described in Reading data from an input file.

Instrument selection

The AtLAST sensitivity calculator supports a range of instruments as described in the instrument overview. The calculator will automatically pick an appropriate instrument based on the observing frequency and bandwidth. The user will be notified whenever the instrument changes. For example:

>>> calculator.user_input.obs_freq = 270*u.GHz
Instrument has been changed from Sepia to Finer.

The currently selected instrument can be checked using:

>>> calculator.chosen_instrument

The instrument can also be changed using the following (case insensitive) command:

>>> calculator.chosen_instrument = 'finer'

Choosing an instrument that is not appropriate for the current observing frequency and bandwidth will result in an error, and a request for the user to either chose a different instrument or update the observing frequency and/or bandwidth.

The observing frequency and bandwidth ranges for the instruments can be checked with:

>>> calculator.list_instruments()