Utils

class rubin_scheduler.scheduler.utils.BasePixelEvolution(period=365.25, rise=1.0, t_start=0.0)

Bases: object

Helper class that can be used to describe the time evolution of a HEALpix in a footprint.

class rubin_scheduler.scheduler.utils.ConstantFootprint(nside=32, filters=None)

Bases: Footprint

class rubin_scheduler.scheduler.utils.CurrentAreaMap(nside=32, dust_limit=0.199, smoothing_cutoff=0.45, smoothing_beam=10, lmc_ra=80.89386, lmc_dec=-69.756126, lmc_radius=6, smc_ra=13.186588, smc_dec=-72.828599, smc_radius=4, scp_dec_max=-60, gal_long1=335, gal_long2=25, gal_lat_width_max=23, center_width=12, end_width=4, gal_dec_max=12, low_dust_dec_min=-70, low_dust_dec_max=15, adjust_halves=12, dusty_dec_min=-90, dusty_dec_max=15, eclat_min=-10, eclat_max=10, eclip_dec_min=0, nes_glon_limit=45.0, virgo_ra=186.75, virgo_dec=12.717, virgo_radius=8.75, euclid_contour_file=None)

Bases: Phase3AreaMap

Useful pointer so whatever the current standard footprint is.

class rubin_scheduler.scheduler.utils.EuclidOverlapFootprint(euclid_contour_file=None, lmc_radius=6, smc_radius=4, **kwargs)

Bases: SkyAreaGeneratorGalplane

Generate survey footprint maps in each filter. This uses a bulgy coverage in the galactic plane, plus small Euclid footprint extension to the low-dust WFD.

Parameters:

• nside (int) – Healpix nside

• dust_limit (float) – E(B-V) limit for dust extinction. Default of 0.199.

• smoothing_cutoff (float) – We apply a smoothing filter to the defined dust-free region to avoid sharp edges. Larger values = less area, but guaranteed less dust extinction. Reflects the value to cut at, after smoothing.

• smoothing_beam (float) – The size of the smoothing filter, in degrees.

• lmc_ra (float, float) – RA and Dec locations of the LMC, in degrees.

• lmc_dec (float, float) – RA and Dec locations of the LMC, in degrees.

• lmc_radius (float) – The radius to use around the LMC, in degrees.

• smc_ra (float, float) – RA and Dec locations for the center of the SMC, in degrees.

• smc_dec (float, float) – RA and Dec locations for the center of the SMC, in degrees.

• smc_radius (float) – The radius to use around the SMC, degrees.

• scp_dec_max (float) – Maximum declination for the south celestial pole region, degrees.

• gal_long1 (float) – Longitude at which to start the GP region, in degrees.

• gal_long2 (float) – Longitude at which to stop the GP region, degrees. Order matters for gal_long1 / gal_long2!

• gal_lat_width_max (float) – Max width of the galactic plane, in degrees.

• center_width (float) – Width at the center of the galactic plane region, in degrees.

• end_width (float) – Width at the remainder of the galactic plane region, in degrees.

• gal_dec_max (float) – Maximum declination for the galactic plane region, degrees.

• dusty_dec_min (float) – The minimum dec for the dusty plane region, in degrees.

• dusty_dec_max (float) – The maximum dec for the dusty plane, degrees.

• eclat_min (float) – Ecliptic latitutde minimum for the NES, degrees.

• eclat_max (float) – Ecliptic latitude maximum for the NES, degrees.

• eclip_dec_min (float) – Declination minimum for the NES, degrees.

• nes_glon_limit (float) – Galactic longitude limit for the NES, degrees.

• virgo_ra (float, float) – RA and Dec values for the Virgo coverage center, in degrees.

• virgo_dec (float, float) – RA and Dec values for the Virgo coverage center, in degrees.

• virgo_radius (float) – Radius for the virgo coverage, in degrees.

• euclid_contour_file (str) – File containing a Euclid footprint contour file. Default of none uses the file in rubin_sim_data/scheduler.

add_euclid_overlap(filter_ratios, label='euclid_overlap')

Define a small extension (few degrees) to the low-dust WFD to accomodate the Euclid footprint. Updates self.healmaps and self.pix_labels.

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

return_maps(magellenic_clouds_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9}, low_dust_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9}, virgo_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9}, scp_ratios={'g': 0.15, 'i': 0.15, 'r': 0.08, 'u': 0.08, 'y': 0.06, 'z': 0.08}, nes_ratios={'g': 0.23, 'i': 0.33, 'r': 0.33, 'z': 0.23}, bulge_ratios={'g': 0.57, 'i': 1.05, 'r': 1.15, 'u': 0.19, 'y': 0.57, 'z': 0.78}, dusty_plane_ratios={'g': 0.13, 'i': 0.28, 'r': 0.28, 'u': 0.07, 'y': 0.18, 'z': 0.25}, euclid_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9})

Return the survey sky maps and labels.

Parameters:

• magellanic_clouds_ratios (dict {str: float}) – Magellanic clouds filter ratios.

• scp_ratios (dict {str: float}) – SCP filter ratios.

• nes_ratios (dict {str: float}) – NES filter ratios

• dusty_plane-ratios (dict {str: float}) – dusty plane filter ratios

• low_dust_ratios (dict {str: float}) – Low Dust WFD filter ratios.

• bulge_ratios (dict {str: float}) – Bulge region filter ratios (note this is the ‘bulgy’ bulge).

• virgo_ratios (dict {str: float}) – Virgo cluster coverage filter ratios.

• euclid_ratios (dict {str: float}) – Euclid footprint overlap ratios.

Returns:

self.healmaps, self.pix_labels – HEALPix target survey maps for ugrizy, and string labels for each healpix to indicate the “region”.

Return type:

np.ndarray, (N,), np.ndarray, (N,)

Notes

Each healpix point can only belong to one region. Which region it is assigned to first will be used for its definition, thus order matters within this method. The region defines the filter ratios.

The filter ratios contain information about the ratio of visits in that region (compared to some reference point in the entire map) in each particular filter. By convention, the low_dust_wfd ratio in r band is set to “1” and all other values are then in reference to that.

For example: if scp_ratios[‘u’] = 0.1 and the low_dust_wfd[‘r’] = 1, then when the low-dust WFD has 10 visits in r band, the SCP should have obtained 1 visits in u band (per pixel).

class rubin_scheduler.scheduler.utils.Footprint(mjd_start, sun_ra_start=0, nside=32, filters=None, period=365.25, step_func=None)

Bases: object

An object to compute the desired survey footprint at a given time

Parameters:

• mjd_start (float) – The MJD the survey starts on

• sun_ra_start (float) – The RA of the sun at the start of the survey (radians)

__call__(mjd, norm=True)

Parameters:

• mjd (float) – Current MJD.

• norm (bool) – If normalized, the footprint retains the same range of values over time.

Returns:

current_footprints – A numpy structured array with the updated normalized number of observations that should be requested at each Healpix. Multiply by the number of HEALpix observations (all filter), to convert to the number of observations desired.

Return type:

np.ndarray, (6, N)

arr2struc(inarr)

Take an array and convert it to labeled struc array

estimate_counts(mjd, nvisits=2200000.0, fov_area=9.6)

Estimate the counts we’ll get after some time and visits

class rubin_scheduler.scheduler.utils.Footprints(footprint_list)

Bases: Footprint

An object to combine multiple Footprint objects.

class rubin_scheduler.scheduler.utils.HpInComcamFov(nside=None, side_length=0.7, scale=100000.0)

Bases: object

Return the healpixels within a ComCam pointing. Simple camera model with no chip gaps.

__call__(ra, dec, rotSkyPos=0.0)

Parameters:

• ra (float) – RA in radians

• dec (float) – Dec in radians

• rotSkyPos (float) – The rotation angle of the camera in radians

Returns:

indx – The healpixels that are within the FoV

Return type:

numpy array

class rubin_scheduler.scheduler.utils.HpInLsstFov(nside=None, fov_radius=1.75, scale=100000.0)

Bases: object

Return the healpixels in an underlying healpix grid that overlap an observation/pointing.

This uses a very simple circular LSST camera model with no chip/raft gaps.

Parameters:

• nside (int, optional) – Nside to match for the healpix array. Default None uses set_default_nside.

• fov_radius (float, optional) – Radius of the field of view in degrees. Default 1.75 covers the inscribed circle.

• scale (float, optional) – How many sig figs to round when considering matches to healpixels. Useful for ensuring identical results cross-ploatform where float precision can vary.

Examples

Set up the class, then call to convert pointings to indices in the healpix array. Note that RA and dec should be in RADIANS.

` >>> ra = np.radians(30) >>> dec = np.radians(-20) >>> pointing2indx = HpInLsstFov() >>> indices = pointing2indx(ra, dec) >>> indices [8138, 8267] `

__call__(ra, dec, **kwargs)

Parameters:

• ra (float, array) – RA in radians

• dec (float, array) – Dec in radians

Returns:

indx – The healpixels that are within the FoV

Return type:

numpy array

class rubin_scheduler.scheduler.utils.HpmapCross(nside=32, radius=1.75, radius_search=1.75)

Bases: object

Find the cross-correlation of a healpix map and a bunch of rotated pointings

__call__(x, return_pointings_map=False)

Parameters:

• x[0] (float) – Amount to rotate the fields in RA (radians)

• ra_rot (float) – Amount to rotate the fields in RA (radians)

• x[1] (float) – Amount to rotate the fields in Dec (radians)

• dec_rot (float) – Amount to rotate the fields in Dec (radians)

• x[2] (float) – Initial rotation to apply to fields (radians)

• im_rot (float) – Initial rotation to apply to fields (radians)

• return_pointings_map (bool (False)) – If set, return the overlapping fields and the resulting observing helpix map

Returns:

cross_corr – If return_pointings_map is False, return the sum of the pointing map multipled with the

Return type:

float

minimize(ra_delta=1.0, dec_delta=1.0, rot_delta=30.0)

Let’s find the minimum of the cross correlation.

set_map(inmap)

Set the map that will be cross correlated

class rubin_scheduler.scheduler.utils.IntRounded(inval, scale=100000.0)

Bases: object

Class to help force comparisons be made on scaled up integers, preventing machine precision issues cross-platforms

Note that casting a NaN to an int can have different behaviours cross-platforms, so will throw an error if attempted.

Parameters:

• inval (number-like thing) – Some number that we want to compare

• scale (float (1e5)) – How much to scale inval before rounding and converting to an int.

class rubin_scheduler.scheduler.utils.Phase3AreaMap(nside=32, dust_limit=0.199, smoothing_cutoff=0.45, smoothing_beam=10, lmc_ra=80.89386, lmc_dec=-69.756126, lmc_radius=6, smc_ra=13.186588, smc_dec=-72.828599, smc_radius=4, scp_dec_max=-60, gal_long1=335, gal_long2=25, gal_lat_width_max=23, center_width=12, end_width=4, gal_dec_max=12, low_dust_dec_min=-70, low_dust_dec_max=15, adjust_halves=12, dusty_dec_min=-90, dusty_dec_max=15, eclat_min=-10, eclat_max=10, eclip_dec_min=0, nes_glon_limit=45.0, virgo_ra=186.75, virgo_dec=12.717, virgo_radius=8.75, euclid_contour_file=None)

Bases: EuclidOverlapFootprint

add_bulgy(filter_ratios, label='bulgy')

Define a bulge region, where the ‘bulge’ is a series of circles set by points defined to match as best as possible the map requested by the SMWLV working group on galactic plane coverage. Implemented in v3.0. Updates self.healmaps and self.pix_labels.

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

return_maps(magellenic_clouds_ratios={'g': 0.65, 'i': 1.1, 'r': 1.1, 'u': 0.65, 'y': 0.35, 'z': 0.34}, scp_ratios={'g': 0.175, 'i': 0.135, 'r': 0.1, 'u': 0.1, 'y': 0.047, 'z': 0.046}, nes_ratios={'g': 0.255, 'i': 0.33, 'r': 0.33, 'z': 0.23}, dusty_plane_ratios={'g': 0.26, 'i': 0.26, 'r': 0.26, 'u': 0.093, 'y': 0.093, 'z': 0.26}, low_dust_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.35, 'y': 0.9, 'z': 0.9}, bulge_ratios={'g': 0.93, 'i': 0.98, 'r': 0.98, 'u': 0.17, 'y': 0.21, 'z': 0.93}, virgo_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.35, 'y': 0.9, 'z': 0.9}, euclid_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.35, 'y': 0.9, 'z': 0.9})

Return the survey sky maps and labels.

Parameters:

• magellanic_clouds_ratios (dict {str: float}) – Magellanic clouds filter ratios.

• scp_ratios (dict {str: float}) – SCP filter ratios.

• nes_ratios (dict {str: float}) – NES filter ratios

• dusty_plane-ratios (dict {str: float}) – dusty plane filter ratios

• low_dust_ratios (dict {str: float}) – Low Dust WFD filter ratios.

• bulge_ratios (dict {str: float}) – Bulge region filter ratios (note this is the ‘bulgy’ bulge).

• virgo_ratios (dict {str: float}) – Virgo cluster coverage filter ratios.

• euclid_ratios (dict {str: float}) – Euclid footprint overlap ratios.

Returns:

self.healmaps, self.pix_labels – HEALPix target survey maps for ugrizy, and string labels for each healpix to indicate the “region”.

Return type:

np.ndarray, (N,), np.ndarray, (N,)

Notes

Each healpix point can only belong to one region. Which region it is assigned to first will be used for its definition, thus order matters within this method. The region defines the filter ratios.

The filter ratios contain information about the ratio of visits in that region (compared to some reference point in the entire map) in each particular filter. By convention, the low_dust_wfd ratio in r band is set to “1” and all other values are then in reference to that.

For example: if scp_ratios[‘u’] = 0.1 and the low_dust_wfd[‘r’] = 1, then when the low-dust WFD has 10 visits in r band, the SCP should have obtained 1 visits in u band (per pixel).

class rubin_scheduler.scheduler.utils.Pointings2hp(nside, radius=1.75)

Bases: object

Convert a list of telescope pointings and convert them to a pointing map

__call__(ra, dec, stack=True)

similar to utils.hp_in_lsst_fov, but can take a arrays of ra,dec.

Parameters:

• ra (array_like) – RA in radians

• dec (array_like) – Dec in radians

Returns:

result – The number of times each healpxel is observed by the given pointings

Return type:

healpy map

class rubin_scheduler.scheduler.utils.SchemaConverter

Bases: object

Record how to convert an observation array to the standard opsim schema

obs2opsim(obs_array, filename=None, info=None, delete_past=False, if_exists='append')

Convert an array of observations into a pandas dataframe with Opsim schema. :type obs_array: :param obs_array: Numpy array with OpSim observations. :type obs_array: np.array :type filename: default: None :param filename: Name of the database file to write to. :type filename: str, optional :type info: default: None :param info: Numpy array with database info. :type info: np.array, optional :type delete_past: default: False :param delete_past: Delete past observations (default=False)? :type delete_past: bool :type if_exists: default: 'append' :param if_exists: Flag to pass to to_sql when writting to the

database to control strategy when the database already exists.

Returns:

Either the converted dataframe or None, if filename is provided.

Return type:

pd.DataFrame or None

opsim2obs(filename)

convert an opsim schema dataframe into an observation array.

Parameters:

filename (str) – Sqlite file containing opsim output observations.

opsimdf2obs(df)

convert an opsim schema dataframe into an observation array.

Parameters:

df (pd.DataFrame) – Data frame containing opsim output observations.

Returns:

obs – Numpy array with OpSim observations.

Return type:

np.recarray

class rubin_scheduler.scheduler.utils.SimTargetooServer(targeto_o_list)

Bases: object

Wrapper to deliver a targetoO object at the right time

class rubin_scheduler.scheduler.utils.SkyAreaGenerator(nside=32, dust_limit=0.199, smoothing_cutoff=0.45, smoothing_beam=10, lmc_ra=80.89386, lmc_dec=-69.756126, lmc_radius=8, smc_ra=13.186588, smc_dec=-72.828599, smc_radius=5, scp_dec_max=-60, gal_long1=335, gal_long2=25, gal_lat_width_max=23, center_width=12, end_width=4, gal_dec_max=12, low_dust_dec_min=-70, low_dust_dec_max=15, adjust_halves=12, dusty_dec_min=-90, dusty_dec_max=15, eclat_min=-10, eclat_max=10, eclip_dec_min=0, nes_glon_limit=45.0, virgo_ra=186.75, virgo_dec=12.717, virgo_radius=8.75)

Bases: object

Generate survey footprint maps in each filter.

Parameters:

• nside (int) – Healpix nside

• dust_limit (float) – E(B-V) limit for dust extinction. Default of 0.199.

• smoothing_cutoff (float) – We apply a smoothing filter to the defined dust-free region to avoid sharp edges. Larger values = less area, but guaranteed less dust extinction. Reflects the value to cut at, after smoothing.

• smoothing_beam (float) – The size of the smoothing filter, in degrees.

• lmc_ra (float, float) – RA and Dec locations of the LMC, in degrees.

• lmc_dec (float, float) – RA and Dec locations of the LMC, in degrees.

• lmc_radius (float) – The radius to use around the LMC, in degrees.

• smc_ra (float, float) – RA and Dec locations for the center of the SMC, in degrees.

• smc_dec (float, float) – RA and Dec locations for the center of the SMC, in degrees.

• smc_radius (float) – The radius to use around the SMC, degrees.

• scp_dec_max (float) – Maximum declination for the south celestial pole region, degrees.

• gal_long1 (float) – Longitude at which to start the GP region, in degrees.

• gal_long2 (float) – Longitude at which to stop the GP region, degrees. Order matters for gal_long1 / gal_long2!

• gal_lat_width_max (float) – Max width of the galactic plane, in degrees.

• center_width (float) – Width at the center of the galactic plane region, in degrees.

• end_width (float) – Width at the remainder of the galactic plane region, in degrees.

• gal_dec_max (float) – Maximum declination for the galactic plane region, degrees.

• dusty_dec_min (float) – The minimum dec for the dusty plane region, in degrees.

• dusty_dec_max (float) – The maximum dec for the dusty plane, degrees.

• eclat_min (float) – Ecliptic latitutde minimum for the NES, degrees.

• eclat_max (float) – Ecliptic latitude maximum for the NES, degrees.

• eclip_dec_min (float) – Declination minimum for the NES, degrees.

• nes_glon_limit (float) – Galactic longitude limit for the NES, degrees.

• virgo_ra (float, float) – RA and Dec values for the Virgo coverage center, in degrees.

• virgo_dec (float, float) – RA and Dec values for the Virgo coverage center, in degrees.

• virgo_radius (float) – Radius for the virgo coverage, in degrees.

add_bulge(filter_ratios, label='bulge')

Define a bulge region, where the ‘bulge’ is a large “diamond” centered on the galactic center. Updates self.healmaps and self.pix_labels.

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

add_dusty_plane(filter_ratios, label='dusty_plane')

Define high-dust region of the map. Updates self.healmaps and self.pix_labels.

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

add_lowdust_wfd(filter_ratios, label='lowdust')

Define a low-dust WFD region. Updates self.healmaps and self.pix_labels.

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

add_magellanic_clouds(filter_ratios, label='LMC_SMC')

Define circular regions around the Magellanic Clouds. Updates self.healmaps and self.pix_labels.

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

add_nes(filter_ratios, label='nes')

Define a North Ecliptic Plane region. Updates self.healmaps and self.pix_labels.

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

add_scp(filter_ratios, label='scp')

Define a south celestial pole cap region. Updates self.healmaps and self.pix_labels.

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

add_virgo_cluster(filter_ratios, label='virgo')

Define a circular region around the Virgo Cluster. Updates self.healmaps and self.pix_labels

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

estimate_visits(nvis_total, fov_area=9.6, **kwargs)

Convience method for converting relative maps into number of visits

Parameters:

• nvis_total (int) – The total number of visits in the survey

• fov_area (float) – The area of a single visit (sq degrees)

• **kwargs – Gets passed to self.return_maps if one wants to change the default ratios.

Returns:

• result (np.array, (N,)) – array with filtername dtypes that have HEALpix arrays with the number of expected visits of each HEALpix center

• sum_map (np.array, (N,)) – The number of visits summed over all the filters

• labels (np.ndarray, (N,)) – Array string labels for each HEALpix

estimate_visits_per_label(nvis_total, **kwargs)

Estimate how many visits would be used for each region

Parameters:

• nvis_total (int) – The total number of visits in the survey

• **kwargs – Gets passed to self.return_maps if one wants to change the default ratios.

Returns:

result – Dictionary with keys that are label names and values that are the expected number of visits for that region if nvis_total is reached.

Return type:

dict

read_dustmap(dustmap_file=None)

Read the dustmap from rubin_scheduler, in the appropriate resolution.

return_maps(magellenic_clouds_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9}, scp_ratios={'g': 0.1, 'i': 0.1, 'r': 0.1, 'u': 0.1, 'y': 0.1, 'z': 0.1}, nes_ratios={'g': 0.28, 'i': 0.4, 'r': 0.4, 'z': 0.28}, dusty_plane_ratios={'g': 0.28, 'i': 0.28, 'r': 0.28, 'u': 0.1, 'y': 0.1, 'z': 0.28}, low_dust_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9}, bulge_ratios={'g': 1.0, 'i': 1.05, 'r': 1.05, 'u': 0.18, 'y': 0.23, 'z': 1.0}, virgo_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9})

Return the survey sky maps and labels.

Parameters:

• magellanic_clouds_ratios (dict {str: float}) – Magellanic clouds filter ratios.

• scp_ratios (dict {str: float}) – SCP filter ratios.

• nes_ratios (dict {str: float}) – NES filter ratios

• dusty_plane-ratios (dict {str: float}) – dusty plane filter ratios

• low_dust_ratios (dict {str: float}) – Low Dust WFD filter ratios.

• bulge_ratios (dict {str: float}) – Bulge region filter ratios.

• virgo_ratios (dict {str: float}) – Virgo cluster coverage filter ratios.

Returns:

self.healmaps, self.pix_labels – HEALPix target survey maps for ugrizy, and string labels for each healpix to indicate the “region”.

Return type:

np.ndarray, (N,), np.ndarray, (N,)

Notes

Each healpix point can only belong to one region. Which region it is assigned to first will be used for its definition, thus order matters within this method. The region defines the filter ratios.

The filter ratios contain information about the ratio of visits in that region (compared to some reference point in the entire map) in each particular filter. By convention, the low_dust_wfd ratio in r band is set to “1” and all other values are then in reference to that.

For example: if scp_ratios[‘u’] = 0.1 and the low_dust_wfd[‘r’] = 1, then when the low-dust WFD has 10 visits in r band, the SCP should have obtained 1 visits in u band (per pixel).

class rubin_scheduler.scheduler.utils.SkyAreaGeneratorGalplane(lmc_ra=89.0, lmc_dec=-70, **kwargs)

Bases: SkyAreaGenerator

Generate survey footprint maps in each filter. Adds a ‘bulgy’ galactic plane coverage map.

Parameters:

• nside (int) – Healpix nside

• dust_limit (float) – E(B-V) limit for dust extinction. Default of 0.199.

• smoothing_cutoff (float) – We apply a smoothing filter to the defined dust-free region to avoid sharp edges. Larger values = less area, but guaranteed less dust extinction. Reflects the value to cut at, after smoothing.

• smoothing_beam (float) – The size of the smoothing filter, in degrees.

• lmc_ra (float, float) – RA and Dec locations of the LMC, in degrees.

• lmc_dec (float, float) – RA and Dec locations of the LMC, in degrees.

• lmc_radius (float) – The radius to use around the LMC, in degrees.

• smc_ra (float, float) – RA and Dec locations for the center of the SMC, in degrees.

• smc_dec (float, float) – RA and Dec locations for the center of the SMC, in degrees.

• smc_radius (float) – The radius to use around the SMC, degrees.

• scp_dec_max (float) – Maximum declination for the south celestial pole region, degrees.

• gal_long1 (float) – Longitude at which to start the GP region, in degrees.

• gal_long2 (float) – Longitude at which to stop the GP region, degrees. Order matters for gal_long1 / gal_long2!

• gal_lat_width_max (float) – Max width of the galactic plane, in degrees.

• center_width (float) – Width at the center of the galactic plane region, in degrees.

• end_width (float) – Width at the remainder of the galactic plane region, in degrees.

• gal_dec_max (float) – Maximum declination for the galactic plane region, degrees.

• dusty_dec_min (float) – The minimum dec for the dusty plane region, in degrees.

• dusty_dec_max (float) – The maximum dec for the dusty plane, degrees.

• eclat_min (float) – Ecliptic latitutde minimum for the NES, degrees.

• eclat_max (float) – Ecliptic latitude maximum for the NES, degrees.

• eclip_dec_min (float) – Declination minimum for the NES, degrees.

• nes_glon_limit (float) – Galactic longitude limit for the NES, degrees.

• virgo_ra (float, float) – RA and Dec values for the Virgo coverage center, in degrees.

• virgo_dec (float, float) – RA and Dec values for the Virgo coverage center, in degrees.

• virgo_radius (float) – Radius for the virgo coverage, in degrees.

add_bulgy(filter_ratios, label='bulgy')

Define a bulge region, where the ‘bulge’ is a series of circles set by points defined to match as best as possible the map requested by the SMWLV working group on galactic plane coverage. Implemented in v3.0. Updates self.healmaps and self.pix_labels.

Parameters:

• filter_ratios (dict {str: float}) – Dictionary of weights per filter for the footprint.

• label (str, optional) – Label to apply to the resulting footprint

return_maps(magellenic_clouds_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9}, low_dust_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9}, virgo_ratios={'g': 0.4, 'i': 1.0, 'r': 1.0, 'u': 0.32, 'y': 0.9, 'z': 0.9}, scp_ratios={'g': 0.15, 'i': 0.15, 'r': 0.08, 'u': 0.08, 'y': 0.06, 'z': 0.08}, nes_ratios={'g': 0.23, 'i': 0.33, 'r': 0.33, 'z': 0.23}, bulge_ratios={'g': 0.57, 'i': 1.05, 'r': 1.15, 'u': 0.19, 'y': 0.57, 'z': 0.78}, dusty_plane_ratios={'g': 0.13, 'i': 0.28, 'r': 0.28, 'u': 0.07, 'y': 0.18, 'z': 0.25})

Return the survey sky maps and labels.

Parameters:

• magellanic_clouds_ratios (dict {str: float}) – Magellanic clouds filter ratios.

• scp_ratios (dict {str: float}) – SCP filter ratios.

• nes_ratios (dict {str: float}) – NES filter ratios

• dusty_plane-ratios (dict {str: float}) – dusty plane filter ratios

• low_dust_ratios (dict {str: float}) – Low Dust WFD filter ratios.

• bulge_ratios (dict {str: float}) – Bulge region filter ratios (note this is the ‘bulgy’ bulge).

• virgo_ratios (dict {str: float}) – Virgo cluster coverage filter ratios.

Returns:

self.healmaps, self.pix_labels – HEALPix target survey maps for ugrizy, and string labels for each healpix to indicate the “region”.

Return type:

np.ndarray, (N,), np.ndarray, (N,)

Notes

Each healpix point can only belong to one region. Which region it is assigned to first will be used for its definition, thus order matters within this method. The region defines the filter ratios.

The filter ratios contain information about the ratio of visits in that region (compared to some reference point in the entire map) in each particular filter. By convention, the low_dust_wfd ratio in r band is set to “1” and all other values are then in reference to that.

For example: if scp_ratios[‘u’] = 0.1 and the low_dust_wfd[‘r’] = 1, then when the low-dust WFD has 10 visits in r band, the SCP should have obtained 1 visits in u band (per pixel).

class rubin_scheduler.scheduler.utils.StepLine(period=365.25, rise=1.0, t_start=0.0)

Bases: BasePixelEvolution

class rubin_scheduler.scheduler.utils.StepSlopes(period=365.25, rise=1.0, t_start=0.0)

Bases: BasePixelEvolution

class rubin_scheduler.scheduler.utils.TargetoO(tooid, footprint, mjd_start, duration, ra_rad_center=None, dec_rad_center=None)

Bases: object

Class to hold information about a target of opportunity object

Parameters:

• tooid (int) – Unique ID for the ToO.

• footprints (np.array) – np.array healpix maps. 1 for areas to observe, 0 for no observe.

• mjd_start (float) – The MJD the ToO starts

• duration (float) – Duration of the ToO (days).

• ra_rad_center (float) – RA of the estimated center of the event (radians).

• dec_rad_center (float) – Dec of the estimated center of the event (radians).

rubin_scheduler.scheduler.utils.calc_norm_factor(goal_dict, radius=1.75)

Calculate how to normalize a Target_map_basis_function. This is basically: the area of the fov / area of a healpixel / the sum of all of the weighted-healpix values in the footprint.

Parameters:

• goal_dict (dict of healpy maps) – The target goal map(s) being used

• radius (float (1.75)) – Radius of the FoV (degrees)

Return type:

Value to use as Target_map_basis_function norm_factor kwarg

rubin_scheduler.scheduler.utils.calc_norm_factor_array(goal_map, radius=1.75)

Calculate how to normalize a Target_map_basis_function. This is basically: the area of the fov / area of a healpixel / the sum of all of the weighted-healpix values in the footprint.

Parameters:

• goal_map (recarray of healpy maps) – The target goal map(s) being used

• radius (float) – Radius of the FoV (degrees)

Return type:

Value to use as Target_map_basis_function norm_factor kwarg

rubin_scheduler.scheduler.utils.comcam_tessellate(side_length=0.7, overlap=0.11)

Tesselate the sphere with a square footprint

XXX–TODO: This really sucks at the poles, should add some different pole cap behavior.

Parameters:

• side_length (float (0.7)) – The length of a side of the square (degrees)

• overlap (float (0.11)) – How much overlap to have in pointings

Returns:

fields – With ‘RA’ and ‘dec’ keys that have the field positions in radians

Return type:

numpy array

rubin_scheduler.scheduler.utils.create_season_offset(nside, sun_ra_rad)

Make an offset map so seasons roll properly

rubin_scheduler.scheduler.utils.empty_observation(n=1)

Return a numpy array that could be a handy observation record

Parameters:

n (int) – Size of array to return. Default 1.

Returns:

• empty_observation (np.array)

• The numpy fields have the following labels. These fields are

• required to be set to be a valid observation the model observatory

• can execute.

• RA (float) – The Right Acension of the observation (center of the field) (Radians)

• dec (float) – Declination of the observation (Radians)

• mjd (float) – Modified Julian Date at the start of the observation (time shutter opens)

• exptime (float) – Total exposure time of the visit (seconds)

• filter (str) – The filter used. Should be one of u, g, r, i, z, y.

• rotSkyPos (float) – The rotation angle of the camera relative to the sky E of N (Radians). Will be ignored if rotTelPos is finite. If rotSkyPos is set to NaN, rotSkyPos_desired is used.

• rotTelPos (float) – The rotation angle of the camera relative to the telescope (radians). Set to np.nan to force rotSkyPos to be used.

• rotSkyPos_desired (float) – If both rotSkyPos and rotTelPos are None/NaN, then rotSkyPos_desired (radians) is used. If rotSkyPos_desired results in a valid rotTelPos, rotSkyPos is set to rotSkyPos_desired. If rotSkyPos and rotTelPos are both NaN, and rotSkyPos_desired results in an out of range value for the camera rotator, then rotTelPos_backup is used.

• rotTelPos_backup (float) – Rotation angle of the camera relative to the telescope (radians). Only used as a last resort if rotSkyPos and rotTelPos are set to NaN and rotSkyPos_desired results in an out of range rotator value.

• nexp (int) – Number of exposures in the visit.

• flush_by_mjd (float) – If we hit this MJD, we should flush the queue and refill it.

• scheduler_note (str (optional)) – Usually good to set the note field so one knows which survey object generated the observation.

• target_name (str (optional)) – A note about what target is being observed. This maps to target_name in the ConsDB. Generally would be used to identify DD, ToO or special targets.

• science_program (str (optional)) – Science program being executed. This maps to science_program in the ConsDB, although can be overwritten in JSON BLOCK. Generally would be used to identify a particular program for DM.

• observation_reason (str (optional)) – General ‘reason’ for observation, for DM purposes. (for scheduler purposes, use scheduler_note). This maps to observation_reason in the ConsDB, although could be overwritten in JSON BLOCK. Most likely this is just “science” or “FBS” when using the FBS.

• json_block (str (optional)) – The JSON BLOCK id to use to acquire observations. This is for use by the SchedulerCSC.

Notes

On the camera rotator angle. Order of priority goes: rotTelPos > rotSkyPos > rotSkyPos_desired > rotTelPos_backup where if rotTelPos is NaN, it checks rotSkyPos. If rotSkyPos is set, but not at an accessible rotTelPos, the observation will fail. If rotSkyPos is NaN, then rotSkyPos_desired is used. If rotSkyPos_desired is at an inaccessbile rotTelPos, the observation does not fail, but falls back to the value in rotTelPos_backup.

Lots of additional fields that get filled in by the model observatory when the observation is completed. See documentation at: https://rubin-scheduler.lsst.io/output_schema.html

rubin_scheduler.scheduler.utils.filter_count_ratios(target_maps)

Compute the desired ratio of observations per filter.

Given a goal map that includes multiple filters, sum the number of pixels in each map and return this per-filter, normalized so the sum across all filters is 1. If the map is constant over all healpixels, this is the ratio of filters at the max/constant value.

rubin_scheduler.scheduler.utils.generate_all_sky(nside=None, elevation_limit=20, mask=-1.6375e+30)

Set up a healpix map over the entire sky. Calculate RA & Dec, Galactic l & b, Ecliptic l & b, for all healpixels. Calculate max altitude, to define areas which LSST cannot reach.

This is intended to be a useful tool to use to set up target maps, beyond the standard maps provided in the various SkyArea generator maps. Masking based on RA, Dec, Galactic or Ecliptic lat and lon is easier.

Parameters:

• nside (int, optional) – Resolution for the healpix maps. Default None uses rubin_scheduler.scheduler.utils.set_default_nside to set default (often 32).

• elevation_limit (float, optional) – Elevation limit for map. Parts of the sky which do not reach this elevation limit will be set to mask.

• mask (float, optional) – Mask value for ‘unreachable’ parts of the sky, defined as elevation < 20.

Returns:

maps – A dictionary of map (the skymap healpix array, with mask values), ra, dec, eclip_lat`, eclip_lon, gal_lat, gal_lon values. All coordinates are in radians.

Return type:

dict {str: np.ndarray, (N,)}

rubin_scheduler.scheduler.utils.generate_dist_matrix(towns)

Generate the matrix for the distance between town i and j

Parameters:

towns (np.array) – The x,y positions of the towns

rubin_scheduler.scheduler.utils.generate_hulls(towns)

Given an array of x,y points, sort them into concentric hulls

Parameters:

towns (np.array (n,2)) – Array of town x,y positions

Return type:

list of lists of the indices of the concentric hulls

rubin_scheduler.scheduler.utils.get_current_footprint(nside)

Convenience method to return the current footprint.

This is primarily a way to help rubin-sim users keep up to date on footprint changes (as we have been moving to new subclasses).

Parameters:

nside (int) – The nside for the footprint map.

Returns:

footprint_arrays, label_array – HEALPix target survey maps for ugrizy, and array of string labels for each healpix to indicate the “region”.

Return type:

np.array, (N,), np.array, (N,)

rubin_scheduler.scheduler.utils.gnomonic_project_tosky(x, y, r_acen, deccen)

Calculate RA/dec on sky of object with x/y and RA/Cen of field of view. Returns Ra/dec in radians.

rubin_scheduler.scheduler.utils.gnomonic_project_toxy(ra1, dec1, r_acen, deccen)

Calculate x/y projection of ra1/dec1 in system with center at r_acen, deccen. Input radians. Grabbed from sims_selfcal

rubin_scheduler.scheduler.utils.hp_kd_tree(nside=None, leafsize=100, scale=100000.0)

Generate a KD-tree of healpixel locations

Parameters:

• nside (int) – A valid healpix nside

• leafsize (int (100)) – Leafsize of the kdtree

Returns:

tree

Return type:

scipy kdtree

rubin_scheduler.scheduler.utils.inrange(inval, minimum=-1.0, maximum=1.0)

Make sure values are within min/max

rubin_scheduler.scheduler.utils.int_binned_stat(ids, values, statistic=<function mean>)

Like scipy.binned_statistic, but for unique int ids

rubin_scheduler.scheduler.utils.make_rolling_footprints(fp_hp=None, mjd_start=60218.0, sun_ra_start=3.27717639, nslice=2, scale=0.8, nside=32, wfd_indx=None, order_roll=0, n_cycles=None, n_constant_start=2, n_constant_end=6, verbose=False, uniform=True)

Generate rolling footprints

Parameters:

• fp_hp (dict-like) – A dict with filtername keys and HEALpix map values

• mjd_start (float) – The starting date of the survey.

• sun_ra_start (float) – The RA of the sun at the start of the survey

• nslice (int) – How much to slice the sky up. Can be 2, 3, 4, or 6.

• scale (float) – The strength of the rolling, value of 1 is full power rolling. Zero is no rolling.

• wfd_indx (array of ints) – The indices of the HEALpix map that are to be included in the rolling.

• order_roll (int) – Change the order of when bands roll. Default 0.

• n_cycles (int) – Number of complete rolling cycles to attempt. If None, defaults to 3 full cycles for nslice=2, 2 cycles for nslice=3 or 4, and 1 cycle for nslice=6.

• n_constant_start (int) – The number of constant non-rolling seasons to start with. Anything less than 2 will start rolling too early near Y1. Defaults to 2.

• n_constant_end (int) – The number of constant seasons to end the survey with. Defaults to 6.

Return type:

Footprints object

rubin_scheduler.scheduler.utils.match_hp_resolution(in_map, nside_out, unseen2nan=True)

Utility to convert healpix map resolution if needed and change hp.UNSEEN values to np.nan.

Parameters:

• in_map (np.array) – A valie healpix map

• nside_out (int) – The desired resolution to convert in_map to

• unseen2nan (bool (True)) – If True, convert any hp.UNSEEN values to np.nan

rubin_scheduler.scheduler.utils.mean_azimuth(az, min_val=0.1)

Compute the mean azimuth value accounting for wrap

Parameters:

• az (array-like) – The azimuths to average. Radians

• min_val (float) – A min cutoff to just use pi as the mean. Default 0.1. Radians

rubin_scheduler.scheduler.utils.merge_hulls(indices_lists, dist_matrix)

Combine the hulls

Parameters:

• indices_list (list of lists with ints)

• dist_matrix (np.array)

rubin_scheduler.scheduler.utils.order_observations(lon, lat, optimize=False)

Use TSP solver to put observations in an order that minimizes angular distance traveled

Parameters:

• lon (float) – A longitude-like (RA, azimuth) angle (radians).

• lat (float) – A latitude-like (dec, altitude) angle (radians).

• scale (float) – A factor to scale and round projections to force same machine precision cross-platforms (1e6).

• optimize (bool) – If the TSP should run extra optimization steps, default False

rubin_scheduler.scheduler.utils.ra_dec_hp_map(nside=None)

Return all the RA,dec points for the centers of a healpix map, in radians.

rubin_scheduler.scheduler.utils.raster_sort(x0, order=['x', 'y'], xbin=1.0)

XXXX–depriciated, use tsp instead.

Do a sort to scan a grid up and down. Simple starting guess to traveling salesman.

Parameters:

• x0 (array)

• order (list) – Keys for the order x0 should be sorted in.

• xbin (float (1.)) – The bin_size to round off the first coordinate into

Return type:

array sorted so that it rasters up and down.

rubin_scheduler.scheduler.utils.restore_scheduler(observation_id, scheduler, observatory, in_obs, filter_sched=None, fast=True)

Put the scheduler and observatory in the state they were in. Handy for checking reward fucnction

Parameters:

• observation_id (int) – The ID of the last observation that should be completed

• scheduler (rubin_scheduler.scheduler.scheduler object) – Scheduler object.

• observatory (rubin_scheduler.scheduler.observatory.Model_observatory) – The observaotry object

• in_obs (np.array or str) – Array of observations (formated like rubin_scheduler.scheduler.empty_observation). If a string, assumed to be a file and SchemaConverter is used to load it.

• filter_sched (rubin_scheduler.scheduler.scheduler object) – The filter scheduler. Note that we don’t look up the official end of the previous night, so there is potential for the loaded filters to not match.

• fast (bool (True)) – If True, loads observations and passes them as an array to the add_observations_array method. If False, passes observations individually with add_observation method.

rubin_scheduler.scheduler.utils.rotate_ra_dec(ra, dec, ra_target, dec_target, init_rotate=0.0)

Rotate ra and dec coordinates to be centered on a new dec.

Rotates around the x-axis 1st, then to the dec, then ra.

Parameters:

• ra (float or np.array) – RA coordinate(s) to be rotated in radians

• dec (float or np.array) – Dec coordinate(s) to be rotated in radians

• ra_rotation (float) – RA distance to rotate in radians

• dec_target (float) – Dec distance to rotate in radians

• init_rotate (float (0.)) – The amount to rotate the points around the x-axis first (radians).

rubin_scheduler.scheduler.utils.route_length(town_indx, dist_matrix)

Find the length of a route

Parameters:

• town_indx (array of int) – The indices of the towns.

• dist_matrix (np.array) – The matrix where the (i,j) elements are the distance between the ith and jth town

rubin_scheduler.scheduler.utils.run_info_table(observatory, extra_info=None)

Make a little table for recording the information about a run

rubin_scheduler.scheduler.utils.scheduled_observation(n=1)

Make an array to hold pre-scheduling observations

Returns:

result

Return type:

np.array

Note

mjd_tolfloat

The tolerance on how early an observation can execute (days). Observation will be considered valid to attempt when mjd-mjd_tol < current MJD < flush_by_mjd (and other conditions below pass)

dist_tolfloat

The angular distance an observation can be away from the specified RA,Dec and still count as completing the observation (radians).

alt_minfloat

The minimum altitude to consider executing the observation (radians).

alt_maxfloat

The maximuim altitude to try observing (radians).

HA_maxfloat

Hour angle limit. Constraint is such that for hour angle running from 0 to 24 hours, the target RA,Dec must be greather than HA_max and less than HA_min. Set HA_max to 0 for no limit. (hours)

HA_minfloat

Hour angle limit. Constraint is such that for hour angle running from 0 to 24 hours, the target RA,Dec must be greather than HA_max and less than HA_min. Set HA_min to 24 for no limit. (hours)

sun_alt_maxfloat

The sun must be below sun_alt_max to execute. (radians)

moon_min_distancefloat

The minimum distance to demand the moon should be away (radians)

observedbool

If set to True, scheduler will probably consider this a completed observation and never attempt it.

rubin_scheduler.scheduler.utils.season_calc(night, offset=0, modulo=None, max_season=None, season_length=365.25, floor=True)

Compute what season a night is in with possible offset and modulo using convention that night -365 to 0 is season -1.

Parameters:

• night (int or array) – The night we want to convert to a season

• offset (float or array (0)) – Offset to be applied to night (days)

• modulo (int (None)) – If the season should be modulated (i.e., so we can get all even years) (seasons, years w/default season_length)

• max_season (int (None)) – For any season above this value (before modulo), set to -1

• season_length (float (365.25)) – How long to consider one season (nights)

• floor (bool (True)) – If true, take the floor of the season. Otherwise, returns season as a float

rubin_scheduler.scheduler.utils.set_default_nside(nside=None)

Utility function to set a default nside value across the scheduler.

XXX-there might be a better way to do this.

Parameters:

nside (int (None)) – A valid healpixel nside.

rubin_scheduler.scheduler.utils.slice_quad_galactic_cut(target_map, nslice=2, wfd_indx=None, ra_range=None)

Helper function for generating rolling footprints

Parameters:

• target_map (dict of HEALpix maps) – The final desired footprint as HEALpix maps. Keys are filter names

• nslice (int) – The number of slices to make, can be 2 or 3.

• wfd_indx (array of ints) – The indices of target_map that should be used for rolling. If None, assumes the rolling area should be where target_map[‘r’] == 1.

• ra_range (tuple of floats, optional) – If not None, then the indices are restricted to the given RA range in radians.

rubin_scheduler.scheduler.utils.slice_wfd_area_quad(target_map, nslice=2, wfd_indx=None)

Divide a healpix map in an intelligent way

Parameters:

• target_map (dict of HEALpix arrays) – The input map to slice

• nslice (int) – The number of slices to divide the sky into (gets doubled).

• wfd_indx (array of int) – The indices of the healpix map to consider as part of the WFD area that will be split. If set to None, the pixels where target_map[‘r’] == 1 are considered as WFD.

rubin_scheduler.scheduler.utils.slice_wfd_indx(target_map, nslice=2, wfd_indx=None)

simple map split

rubin_scheduler.scheduler.utils.smallest_signed_angle(a1, a2)

via https://stackoverflow.com/questions/1878907/ the-smallest-difference-between-2-angles

rubin_scheduler.scheduler.utils.three_opt(route, dist_matrix, cross_platform=True)

Iterates over all possible 3-optional transformations.

Parameters:

• route (list) – The indices of the route

• dist_matrix (np.array) – Distance matrix for the towns

• cross_platform (bool) – Use utils.intRounded to make sure results will be repeatable cross-platform. Default True

Returns:

• min_route (list) – The new route

• min_length (float) – The length of the new route

rubin_scheduler.scheduler.utils.tsp_convex(towns, optimize=False, niter=10)

Find a route through towns

Parameters:

• towns (np.array (shape n,2)) – The points to find a path through

• optimize (bool (False)) – Optional to run the 3-optional transformation to optimize route

• niter (int (10)) – Max number of iterations to run on optimize loop.

Return type:

indices that order towns.

rubin_scheduler.scheduler.utils.warm_start(scheduler, observations, mjd_key='mjd')

Replay a list of observations into the scheduler

Parameters:

• scheduler (scheduler object)

• observations (np.array) – An array of observation (e.g., from sqlite2observations)

rubin_scheduler.scheduler.utils.wrap_ra_dec(ra, dec)

Wrap RA into 0-2pi and Dec into +/0 pi/2.

Parameters:

• ra (numpy.ndarray) – RA in radians

• dec (numpy.ndarray) – Dec in radians

Returns:

Wrapped RA/Dec values, in radians.

Return type:

numpy.ndarray, numpy.ndarray