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. A value of 36 aligns the simulation with the last consecutive time period of the clouds.

• 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:

cloud_value – 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.CloudMap(nside_out=32, time_limit=20.0, max_frames=2000)

Bases: object

A class to hold cloud maps over time

Parameters:

• nside_out (int) – The nside to output maps as. Default to DEFAULT_NSIDE (probably 32).

• time_limit (float) – Do not return a cloud map if there is nothing within the time limit. Default 20 (minutes).

add_frame(input_cloud_extinction, mjd, nested=False, uncert=None)

Add a frame. Will be converted to ring order if needed and set to the self.nside_out resolution.

Parameters:

• input_cloud_extinction (np.array) – HEALpix array with extinction in mags.

• mjd (float) – The MJD of the cloud frame

• nested (bool) – If True, converts the incoming map to ring order. Default False

• uncert (np.array) – HEALpix array with uncertainty in extinction magnitudes.

extinction_closest(mjd, hpid=None, uncert=False)

Return the closest map

Parameters:

• mjd (float) – MJD of the desired extinction map.

• hpid (int) – If only a subset of the HEALpix array is needed, can specify index.

• uncert (bool) – Also return the uncertainty map with the extinction map.

Return type:

Healpix array in ring order with cloud extinction in magnitudes.

extinction_forecast(mjd, hpid=None, max_history=5, max_extrapolate_min=10.0)

Return a projected cloud extinction map for a future mjd.

Tracks the recent motion of the cloud field by computing an extinction-weighted centroid (RA/Dec) of each of the last few stored frames, fitting a linear velocity to that centroid track, and advecting the most recent frame backward along that velocity to build a forecast map for the requested time. This is a simple translation (no growth/decay) model.

Parameters:

• mjd (float) – MJD to forecast the extinction map for. Must be after the most recently added frame.

• hpid (int) – If only a subset of the HEALpix array is needed, can specify index.

• max_history (int) – Number of trailing frames to use for the velocity fit. Default 5.

• max_extrapolate_min (float) – Do not extrapolate more than this many minutes past the most recent frame; beyond that the linear-motion assumption is unreliable and we fall back to extinction_closest. Default 10.

Returns:

• Healpix array in ring order with projected cloud extinction

• in magnitudes (falls back to extinction_closest if there

• is not enough history, or the forecast fails, or the

• requested mjd is not far enough in the future).

class rubin_scheduler.site_models.CloudModel(nside_out=32, max_history=5, max_extrapolate_min=10.0)

Bases: object

LSST cloud calculations for predictive cloud extinction.

Converts a short window of recent DREAM cloud-extinction frames into a delivered extinction map projected forward to a requested time.

Parameters:

• nside_out (int) – The nside to output maps as. Default DEFAULT_NSIDE (probably 32).

• max_history (int) – Number of trailing frames (out of whatever is in dream_history) to use for the velocity fit. Default 5.

• max_extrapolate_min (float) – Do not extrapolate more than this many minutes past the most recent frame in dream_history; beyond that the linear-motion assumption is unreliable and we fall back to the most recently observed frame, unmodified. Default 10.

• same (self.efd_requirements and self.map_requirements follow the)

• site_models (convention as the other)

• str (of time history required; map_requirements is a list of)

• amount (float) naming the DREAM/EFD columns and the)

• str

• dict. (naming the columns required in the target map)

__call__(dream_history, mjd)

Deliver a projected cloud extinction map for mjd.

Parameters:

• dream_history (dict or object with mjds /) –

  cloud_extinction_hparrays attributes (e.g. a CloudMap-like buffer works directly). A short recent window of DREAM frames: dream_history[“mjd”] : np.array

  MJDs of the recent frames, oldest to newest.

  dream_history[“extinction”]list [np.array]

  HEALpix extinction maps (ring order, nside_out) for each of those MJDs, same order.

• mjd (float) – The time to deliver the extinction map for. Must be after the most recent frame in dream_history.

Returns:

{“extinction”: healpix array in ring order, magnitudes}. Falls back to the most recently observed frame, unmodified, if there isn’t enough history, the forecast fails, or mjd is not far enough in the future to be worth extrapolating (see max_extrapolate_min).

Return type:

dict of np.ndarray

config_info()

Deprecated. Report configuration parameters and version information.

configure(config=None)

Deprecated. Configure through the init method.

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(band_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', filter_list=None)

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:

• band_list (list [str], opt) – List of the band 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

• filter_list (list [str], opt) – Deprecated version of band_list

__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 <band><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 band 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

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

Bases: UnscheduledDowntimeData

make_data(end_of_start=380)

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 band 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

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