Site Models API

class rubin_scheduler.site_models.Almanac(mjd_start=None, kind='quadratic')

Bases: object

Class to load and return pre-computed information about the LSST site.

get_sun_moon_positions(mjd)

All angles in Radians. moonPhase between 0 and 100.

get_sunset_info(mjd=None, evening_date=None, longitude=None)

Returns a numpy array with mjds for various events (sunset, moonrise, sun at -12 degrees alt, etc.).

Parameters:

• mjd (float) – A UTC MJD that occurs during the desired night. Defaults to None.

• evening_date (str or datetime.date) – The local date of the evening of the night whose index is desired, in ISO8601 format (YYYY-MM-DD). Defaults to None.

• longitude (float or astropy.coordinates.angles.core.Angle) – If a float, then the value is interpreted as being in radians. Defaults to None.

Returns:

sunset_info –

A numpy object with dtype([

(‘night’, ‘<i8’), (‘sunset’, ‘<f8’), (‘sun_n12_setting’, ‘<f8’), (‘sun_n18_setting’, ‘<f8’), (‘sun_n18_rising’, ‘<f8’), (‘sun_n12_rising’, ‘<f8’), (‘sunrise’, ‘<f8’), (‘moonrise’, ‘<f8’), (‘moonset’, ‘<f8’)

])

Return type:

numpy.void

index_for_local_evening(evening_date, longitude)

The index of the night with sunset at a given local date.

Parameters:

• evening_date (str or datetime.date) – The local date of the evening of the night whose index i desired, in ISO8601 format (YYYY-MM-DD).

• longitude (float or astropy.coordinates.angles.core.Angle) – If a float, then the value is interpreted as being in radians.

Returns:

night_index – The index of the requested night.

Return type:

int

class rubin_scheduler.site_models.CloudData(start_time, cloud_db=None, offset_year=0, scale=1000000.0)

Bases: object

Handle the cloud information.

This class deals with the cloud information that was previously produced for OpSim version 3.

Parameters:

• start_time (astropy.time.Time) – The time of the start of the simulation. The cloud database will be assumed to start on Jan 01 of the same year.

• cloud_db (str, optional) – The full path name for the cloud database. Default None, which will use the database stored in the module (site_models/clouds_ctio_1975_2022.db).

• offset_year (float, optional) – Offset into the cloud database by ‘offset_year’ years. Default 0.

• scale (float (1e6)) – Enforce machine precision for cross-platform repeatability by scaling and rounding date values.

__call__(time)

Get the cloud for the specified time.

Parameters:

time (astropy.time.Time) – Time in the simulation for which to find the current cloud coverage. The difference between this time and the start_time, plus the offset, will be used to query the cloud database for the ‘current’ conditions.

Returns:

The fraction of the sky that is cloudy (measured in steps of 8ths) closest to the specified time.

Return type:

float

read_data()

Read the cloud data from disk.

The default behavior is to use the module stored database. However, an alternate database file can be provided. The alternate database file needs to have a table called Cloud with the following columns:

cloudId

int : A unique index for each cloud entry.

c_date

int : The time (units=seconds) since the start of the simulation for the cloud observation.

cloud

float : The cloud coverage (in steps of 8ths) of the sky.

class rubin_scheduler.site_models.CloudModel(cloud_column='cloud', altitude_column='altitude', azimuth_column='azimuth')

Bases: object

LSST cloud calculations for cloud extinction. Currently this actually only returns the cloud coverage of the sky, exactly as reported in the cloud database (thus the sky coverage, in fractions of 8ths).

Parameters:

• docstring (XXX--update)

• set. (self.efd_requirements and self.map_requirements are also)

• tuple (efd_requirements is a)

• and (This corresponds to the data columns required from the EFD)

• a (the amount of time history required. target_requirements is)

• the (list of str. This corresponds to the data columns required in)

• processed (target map dictionary passed when calculating the)

• values. (telemetry)

__call__(cloud_value, altitude)

Calculate the sky coverage due to clouds.

This is where we’d plug in Peter’s cloud transparency maps and predictions. We could also try translating cloud transparency into a cloud extinction. For now, we’re simply returning the cloud coverage that we already got from the database, but multiplied over the whole sky to provide a map.

Parameters:

• cloud_value (float or efdData dict) – The value to give the clouds (XXX-units?).

• altitude (float, np.array, or targetDict) – Altitude of the output (arbitrary).

Returns:

Cloud transparency map values.

Return type:

dict of np.ndarray

class rubin_scheduler.site_models.ConstantCloudData(cloud_fraction=0.0)

Bases: object

Generate constant cloud information.

Parameters:

cloud_fraction (float) – The fraction of the sky that is cloudy.

__call__(time)

Get the cloud for the specified time.

Parameters:

time (astropy.time.Time) – In principle, the time in the simulation for which to find the current cloud coverage. In practice, this argument is ignored.

Returns:

cloud_faction – The fraction of the sky that is cloudy.

Return type:

float

class rubin_scheduler.site_models.ConstantSeeingData(fwhm_500=0.7)

Bases: object

Parameters:

fwhm_500 (float, default: 0.7)

__call__(time)

A constant FWHM_500 value

Parameters:

time (astropy.time.Time) – It principle the time for which the seeing is returned, in practice this argumnet is ignored, and included for compatibility.

Returns:

fwhm_500 – The FWHM at 500nm, in arcseconds.

Return type:

float

class rubin_scheduler.site_models.ConstantWindData(wind_speed=0.0, wind_direction=0.0)

Bases: object

A source of constant wind values.

Parameters:

• wind_speed (float) – Wind speed (m/s).

• wind_direction (float) – Direction from which the wind originates. A direction of 0.0 degrees means the wind originates from the north and 90.0 degrees from the east (radians).

__call__(time)

A constant wind conditions

Parameters:

time (astropy.time.Time) – It principle the time for which the wind is returned, in practice this argument is ignored, and included for compatibility.

Returns:

wind_conditions – A named tuple with the wind speed (m/s) and originating direction (radians east of north)

Return type:

tuple (float, float)

class rubin_scheduler.site_models.DowntimeModel(sched_down_col='scheduled_downtimes', unsched_down_col='unscheduled_downtimes', time_col='time')

Bases: object

Downtime estimates, both scheduled and unscheduled.

Parameters:

• config (DowntimeModelConfig, optional) – A configuration class for the downtime model. This can be None, in which case the default DowntimeModelConfig is used. The user should set any non-default values for DowntimeModelConfig before configuration of the actual DowntimeModel.

• set. (self.efd_requirements and self.target_requirements are also)

• tuple (efd_requirements is a)

• and (This corresponds to the data columns required from the EFD)

• a (the amount of time history required. target_requirements is)

• the (list of str. This corresponds to the data columns required in)

• telemetry (target dictionary passed when calculating the processed)

• values.

__call__(efd_data, target_dict)

Calculate the sky coverage due to clouds.

Parameters:

• efd_data (dict) – Dictionary of input telemetry, typically from the EFD. This must contain columns self.efd_requirements. (work in progress on handling time history).

• target_dict (dict) – Dictionary of target values over which to calculate the processed telemetry. (e.g. mapDict = {‘ra’: [], ‘dec’: [], ‘altitude’: [], ‘azimuth’: [], ‘airmass’: []}) Here we use ‘time’, an astropy.time.Time, as we just need to know the time.

Returns:

Status of telescope (True = Down, False = Up) at time, time of expected end of downtime (~noon of the first available day), time of next scheduled downtime (~noon of the first available day).

Return type:

dict of bool, astropy.time.Time, astropy.time.Time

class rubin_scheduler.site_models.ScheduledDowntimeData(start_time, scheduled_downtime_db=None, start_of_night_offset=-0.34)

Bases: object

Read the scheduled downtime data.

This class deals with the scheduled downtime information that was previously produced for OpSim version 3.

Parameters:

• start_time (astropy.time.Time) – The time of the start of the simulation. The cloud database will be assumed to start on Jan 01 of the same year.

• cloud_db (str, optional) – The full path name for the cloud database. Default None, which will use the database stored in the module ($SIMS_CLOUDMODEL_DIR/data/cloud.db).

• start_of_night_offset (float, optional) – The fraction of a day to offset from MJD.0 to reach the defined start of a night (‘noon’ works). Default 0.16 (UTC midnight in Chile) - 0.5 (minus half a day) = -0.34

__call__()

Return the current (if any) and any future scheduled downtimes.

Parameters:

time (astropy.time.Time) – Time in the simulation for which to find the current downtime.

Returns:

downtime – The array of all unscheduled downtimes, with keys for ‘start’, ‘end’, ‘activity’, corresponding to astropy.time.Time, astropy.time.Time, and str.

Return type:

np.ndarray

read_data()

Read the scheduled downtime information from disk and translate to astropy.time.Times.

This function gets the appropriate database file and creates the set of scheduled downtimes from it. The default behavior is to use the module stored database. However, an alternate database file can be provided. The alternate database file needs to have a table called Downtime with the following columns:

nightint

The night (from start of simulation) the downtime occurs.

durationint

The duration (units=days) of the downtime.

activitystr

A description of the activity involved.

total_downtime()

Return total downtime (in days).

Returns:

total – Total number of downtime days.

Return type:

int

class rubin_scheduler.site_models.SeeingData(start_time, seeing_db=None, offset_year=0)

Bases: object

Read the seeing data from disk and return appropriate FWHM_500 value at a given time. This is for use in simulations only. Otherwise data would come from the EFD.

Parameters:

• start_time (astropy.time.Time) – The time of the start of the simulation. The seeing database will be assumed to start on Jan 01 of the same year.

• seeing_db (str or None, optional) – The name of the seeing database. If None (default), this will use the simsee_pachon_58777_13.db file in the ‘data’ directory of this package. Other available seeing databases from sims_seeingModel include: seeing.db (the original, less-variable, 3 year seeing database) simsee_pachon_58777_13.db (the current default, 10 year, seeing database) simsee_pachon_58777_16.db (a similar, but slightly offset, 13 year seeing database) For more info on simsee_pachon_58777_*, see lsst/sims_seeingModel#2

• offset_year (float, optional) – Offset into the cloud database by ‘offset_year’ years. Default 0.

__call__(time)

Get the FWHM_500 value for the specified time.

Parameters:

time (astropy.time.Time) – Time in the simulation for which to find the ‘current’ zenith seeing values. The difference between this time and the start_time, plus the offset, will be used to query the seeing database.

Returns:

The FWHM_500(”) closest to the specified time.

Return type:

float

config_info()

Report information about configuration of this data.

Return type:

OrderedDict

read_data()

Read the seeing information from disk.

The default behavior is to use the module stored database. However, an alternate database file can be provided. The alternate database file needs to have a table called Seeing with the following columns:

seeingId

int : A unique index for each seeing entry.

s_date

int : The time (in seconds) from the start of the simulation, for the seeing observation.

seeing

float : The FWHM of the atmospheric PSF (in arcseconds) at zenith.

class rubin_scheduler.site_models.SeeingModel(filter_list=['u', 'g', 'r', 'i', 'z', 'y'], eff_wavelens=None, telescope_seeing=0.25, optical_design_seeing=0.08, camera_seeing=0.3, raw_seeing_wavelength=500, efd_seeing='FWHM_500')

Bases: object

LSST FWHM calculations for FWHM_effective and FWHM_geometric.

Calculations of the delivered values are based on equations in Document-20160 (“Atmospheric and Delivered Image Quality in OpSim” by Bo Xin, George Angeli, Zeljko Ivezic) An example of the calculation of delivered image seeing from DIMM FWHM_500 is available in https://smtn-002.lsst.io/ #calculating-m5-values-in-the-lsst-operations-simulator

Parameters:

• filter_list (list [str], opt) – List of the filter bandpasses for which to calculate delivered FWHM_effective and FWHM_geometric Default [‘u’, ‘g’, ‘r’, ‘i’, ‘z’, ‘y’]

• eff_wavelens (list [float] or None, opt) – Effective wavelengths for those bandpasses, in nanometers. If None, loades from rubin_scheduler.utils.SysEngVals

• telescope_seeing (float, opt) – The contribution to the delivered FWHM from the telescope, in arcseconds. Default 0.25”

• optical_design_seeing (float, opt) – The contribution to the seeing from the optical design, in arcseconds. Default 0.08 arcseconds

• camera_seeing (float, opt) – The contribution to the seeing from the camera, in arcseconds. Default 0.30 arcseconds

• raw_seeing_wavelength (float, opt) – The wavelength of the DIMM-delivered equivalent FWHM, in nanometers. Default 500nm.

• efd_seeing (str, opt) – The name of the DIMM FWHM measurements in the efd / conditions object. Default FWHM_500

__call__(fwhm_z, airmass)

Calculate the seeing values FWHM_eff and FWHM_geom at the given airmasses, for the specified effective wavelengths, given FWHM_zenith (typically FWHM_500).

FWHM_geom represents the geometric size of the PSF; FWHM_eff represents the FWHM of a single gaussian which encloses the same number of pixels as N_eff (the number of pixels enclosed in the actual PSF – this is the value to use when calculating SNR).

FWHM_geom(”) = 0.822 * FWHM_eff(”) + 0.052”

The FWHM_eff includes a contribution from the system and from the atmosphere. Both of these are expected to scale with airmass^0.6 and with (500(nm)/wavelength(nm))^0.3. FWHM_eff = 1.16 * sqrt(FWHM_sys**2 + 1.04*FWHM_atm**2)

Parameters:

• fwhm_z (float, or efdData dict) – FWHM at zenith (arcsec).

• airmass (float, np.array, or targetDict dict) – Airmass (unitless).

Returns:

FWHMeff, FWHMGeom – FWHMeff, FWHMgeom: both are the same shape numpy.ndarray. If airmass is a single value, FWHMeff & FWHMgeom are 1-d arrays, with the same order as eff_wavelen (i.e. eff_wavelen[0] = u, then FWHMeff[0] = u). If airmass is a numpy array, FWHMeff and FWHMgeom are 2-d arrays, in the order of <filter><airmass> (i.e. eff_wavelen[0] = u, 1-d array over airmass range).

Return type:

dict of {numpy.ndarray, numpy.ndarray}

config_info()

Deprecated. Report configuration parameters and version information.

configure()

Deprecated. Configure through the init method.

static fwhm_eff_to_fwhm_geom(fwhm_eff)

Calculate FWHM_geom from FWHM_eff.

Parameters:

fwhm_eff (float or np.ndarray)

Returns:

FWHM_geom

Return type:

float or np.ndarray

static fwhm_geom_to_fwhm_eff(fwhm_geom)

Calculate FWHM_eff from FWHM_geom.

Parameters:

fwhm_geom (float or np.ndarray)

Returns:

FWHM_eff

Return type:

float or np.ndarray

class rubin_scheduler.site_models.UnscheduledDowntimeData(start_time, seed=1516231120, start_of_night_offset=-0.34, survey_length=7300)

Bases: object

Handle (and create) the unscheduled downtime information.

Parameters:

• start_time (astropy.time.Time) – The time of the start of the simulation. The cloud database will be assumed to start on Jan 01 of the same year.

• seed (int, optional) – The random seed for creating the random nights of unscheduled downtime. Default 1516231120.

• start_of_night_offset (float, optional) – The fraction of a day to offset from MJD.0 to reach the defined start of a night (‘noon’ works). Default 0.16 (UTC midnight in Chile) - 0.5 (minus half a day) = -0.34

• survey_length (int, optional) – The number of nights in the total survey. Default 3650*2.

__call__()

Return the array of unscheduled downtimes.

Parameters:

time (astropy.time.Time) – Time in the simulation for which to find the current downtime.

Returns:

downtime – The array of all unscheduled downtimes, with keys for ‘start’, ‘end’, ‘activity’, corresponding to astropy.time.Time, astropy.time.Time, and str.

Return type:

np.ndarray

make_data()

Configure the set of unscheduled downtimes.

This function creates the unscheduled downtimes based on a set of probabilities of the downtime type occurance.

The random downtime is calculated using the following probabilities:

minor event : remainder of night and next day = 5/365 days e.g. power supply failure intermediate : 3 nights = 2/365 days e.g. repair filter mechanism, rotator, hexapod, or shutter major event : 7 nights = 1/2*365 days catastrophic event : 14 nights = 1/3650 days e.g. replace a raft

total_downtime()

Return total downtime (in days).

Returns:

total – Total number of downtime days.

Return type:

int

rubin_scheduler.site_models.read_fields(filename=None)

Read in field positions.

Parameters:

filename (str (None)) – File to read. Defaults to icover.3.5292.23.0.txt origianlly from: http://neilsloane.com/icosahedral.codes/index.html

Returns:

ra, dec

Return type:

np.arrays of RA,dec values in degrees