Utils API

class rubin_scheduler.utils.HalfSpace(vector, length)

Bases: object

HalfSpaces are circles on the unit sphere defined by intersecting a plane with the unit sphere. They are specified by the unit vector pointing to their center on the unit sphere and the distance from the center of the unit sphere to the plane along that unit vector.

See Section 3.1 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

Note that the specifying distance can be negative. In this case, the halfspace is defined as the larger of the two regions on the unit sphere divided by the circle where the plane of the halfspace intersects the unit sphere.

contains_many_pts(pts)

Parameters:

• the (pts is a numpy array in which each row is a point on)

• (note (unit sphere)

Returns:

• numpy array of booleans indicating which of pts are contained

• by this HalfSpace

contains_pt(pt, tol=None)

pt is a cartesian point (not necessarily on the unit sphere). The method returns True if the projection of that point onto the unit sphere is contained in the halfspace; False otherwise.

contains_trixel(tx)

tx is a Trixel.

Return “full” if the Trixel is fully contained by this halfspace.

Return “partial” if the Trixel is only partially contained by this halfspace

Return “outside” if no part of the Trixel is contained by this halfspace.

See section 4.1 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

property dd

The distance along the Half Space’s vector that defines the extent of the Half Space.

find_all_trixels(level)

Find the HTMIDs of all of the trixels filling the half space

Parameters:

grid (level is an integer denoting the resolution of the trixel)

Returns:

• A list of tuples. Each tuple gives an inclusive range of HTMIDs

• corresponding to trixels within the HalfSpace

intersects_bounding_circle(tx)

tx is a Trixel. Return True if this halfspace intersects the bounding circle of the trixel; False otherwise.

See the discussion around equation 4.2 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

intersects_circle(center, radius_rad)

Does this Half Space intersect a circle on the unit sphere

center is the unit vector pointing to the center of the circle

radius_rad is the radius of the circle in radians

Returns a bool

intersects_edge(pt1, pt2)

pt1 and pt2 are two unit vectors; the edge goes from pt1 to pt2. Return True if the edge intersects this halfspace; False otherwise.

see equation 4.8 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

static join_trixel_bound_sets(b1, b2)

Take two sets of trixel bounds as returned by HalfSpace.find_all_trixels and return a set of trixel bounds that represents the intersection of the original sets of bounds

static merge_trixel_bounds(bounds)

Take a list of trixel bounds as returned by HalfSpace.find_all_trixels and merge any tuples that should be merged

Parameters:

• by (bounds is a list of trixel bounds as returned)

• HalfSpace.find_all_trixels

Return type:

A new, equivalent list of trixel bounds

property phi

The angular radius of the Half Space on the surface of the sphere in radians.

property vector

The unit vector from the origin to the center of the Half Space.

class rubin_scheduler.utils.LsstCameraFootprint(units='degrees', footprint_file=None)

Bases: object

Identify point on the sky within an LSST camera footprint.

Parameters:

• units (str, opt) – Units for the object RA/Dec and boresight RA/Dec/rotation values. Default ‘degrees’. If not degrees, assumes incoming values are in radians.

• footprint_file (str or None, opt) – Location for the camera footprint map. Default None loads the default map from $RUBIN_SIM_DATA_DIR/maf/fov_map.npz

__call__(obj_ra, obj_dec, boresight_ra, boresight_dec, boresight_rot_sky_pos)

Determine which observations are within the actual camera footprint for a series of observations.

Parameters:

• obj_ra (np.ndarray) – RA values for the objects (in the field of view?)

• obj_dec (np.ndarray) – Dec values for the objects

• boresight_ra (float) – RA value for the pointing

• boresight_dec (float) – Dec value for the pointing

• boresight_rot_sky_pos (float) – RotSkyPos value for the pointing.

Returns:

indices – Returns the indexes of the numpy array of the object observations which are inside the fov and land on a science chip. Applying this to the input array (e.g. obj_ra[indices]) indicates the positions of the objects which fell onto active silicon.

Return type:

np.ndarray

class rubin_scheduler.utils.Site(name=None, longitude=None, latitude=None, height=None, temperature=None, pressure=None, humidity=None, lapse_rate=None)

Bases: object

This class will store site information for use in Catalog objects.

Defaults values are LSST site values taken from the Observatory System Specification document https://docushare.lsstcorp.org/docushare/dsweb/ImageStoreViewer/LSE-30 on 4 January 2016

Parameters:

• name (str, opt) – The name of the observatory. Set to ‘LSST’ for other parameters to default to LSST values.

• longitude (float, opt) – Longitude of the site in degrees.

• latitude (float, opt) – Latitude of the site in degrees.

• height (float, opt) – Height of the site in meters.

• temperature (float, opt) – Mean temperature in Centigrade

• pressure (float, opt) – Pressure for the site in millibars.

• humidity (float, opt) – Relative humidity (range 0-1).

• lapse_rate (float, opt) – Change in temperature in Kelvins per meter

property height

height in meters

property humidity

mean humidity in the range 0-1

property lapse_rate

temperature lapse rate (in Kelvin per meter)

property latitude

observatory latitude in degrees

property latitude_rad

observatory latitude in radians

property longitude

observatory longitude in degrees

property longitude_rad

observatory longitude in radians

property name

observatory name

property pressure

mean pressure in millibars

property temperature

mean temperature in centigrade

property temperature_kelvin

mean temperature in Kelvin

class rubin_scheduler.utils.SysEngVals

Bases: object

Object to store values calculated in sys-eng

generated from notebook in: lsst-pst/syseng_throughputs

class rubin_scheduler.utils.Trixel(present_htmid, present_corners)

Bases: object

A trixel is a single triangle in the Hierarchical Triangular Mesh (HTM) tiling scheme. It is defined by its three corners on the unit sphere.

Instantiating this class directly is a bad idea. __init__() does nothing to ensure that the parameters you give it are self-consistent. Instead, use the trixel_from_htmid() or get_all_trixels() methods in this module to instantiate trixels.

property bounding_circle

The circle on the unit sphere that bounds this trixel.

See equation 4.2 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

Returns:

Zeroth element is the unit vector pointing at the center of the bounding circle

First element is the distance from the center of the unit sphere to the plane of the bounding circle (i.e. the dot product of the zeroth element with the most distant corner of the trixel).

Second element is the half angular extent of the bounding circle.

Return type:

A tuple

contains(ra, dec)

Returns True if the specified RA, Dec are inside this trixel; False if not.

RA and Dec are in degrees.

contains_pt(pt)

pt is either a single Cartesian point or an array of Cartesian points (pt[0] is the zeroth point, pt[1] is the first point, etc.).

Return a bool or array of booleans denoting whether this point(s) projected onto the unit sphere is/are contained within the current trixel.

property corners

A numpy array containing the unit vectors pointing to the corners of this trixel. corners[0] is the zeroth corner, corners[1] is the first corner, etc.

property cross01

The cross product of the unit vectors defining the zeroth and first corners of this trixel.

property cross12

The cross product of the unit vectors defining the first and second corners of this trixel.

property cross20

The cross product of the unit vectors defining the second and zeroth corners of this trixel.

get_center()

Return the RA, Dec of the center of the circle bounding this trixel (RA, Dec both in degrees)

get_child(dex)

Return a specific child trixel of this trixel.

dex is an integer in the range [0,3] denoting which child to return

See Figure 1 of

Kunszt P., Szalay A., Thakar A. (2006) in “Mining The Sky”, Banday A, Zaroubi S, Bartelmann M. eds. ESO Astrophysics Symposia https://www.researchgate.net/publication/ 226072008_The_Hierarchical_Triangular_Mesh

for an explanation of which trixel corresponds to whic index.

get_children()

Return a list of all of the child trixels of this trixel.

get_radius()

Return the angular radius in degrees of the circle bounding this trixel.

property htmid

The unique integer identifying this trixel.

property level

Return the level of subdivision for this trixel. A higher level means a finer subdivision of the unit sphere and smaller trixels. What we refer to as ‘level’ is denoted by ‘d’ in equation 2.5 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

For a given level == ell, there are 8*4**(ell-1) trixels in the entire unit sphere.

The htmid values of trixels with level==ell will consist of 4 + 2*(ell-1) bits

property t0

The zeroth child trixel of this trixel.

See Figure 2 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

property t1

The first child trixel of this trixel.

See Figure 2 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

property t2

The second child trixel of this trixel.

See Figure 2 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

property t3

The third child trixel of this trixel.

See Figure 2 of

Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164

property w_arr

An array of vectors needed to define the child trixels of this trixel. See equation (3) of

Kunszt P., Szalay A., Thakar A. (2006) in “Mining The Sky”, Banday A, Zaroubi S, Bartelmann M. eds. ESO Astrophysics Symposia httpd://www.researchgate.net/publication/ 226072008_The_Hierarchical_Triangular_Mesh

class rubin_scheduler.utils.ZernikePolynomialGenerator

Bases: object

A class to generate and evaluate the Zernike polynomials. Definitions of Zernike polynomials are taken from https://en.wikipedia.org/wiki/Zernike_polynomials

evaluate(r, phi, n, m)

Evaluate a Zernike polynomial in polar coordinates

r is the radial coordinate (a scalar or an array)

phi is the angular coordinate in radians (a scalar or an array)

n is the radial order of the polynomial

m is the angular order of the polynomial

Return the value(s) of the polynomial at r, phi (returns np.NaN if r>1.0)

evaluate_xy(x, y, n, m)

Evaluate a Zernike polynomial at a point in Cartesian space.

x and y are the Cartesian coordinaes (either scalars or arrays)

n is the radial order of the polynomial

m is the angular order of the polynomial

Return the value(s) of the polynomial at x, y (returns np.NaN if sqrt(x**2+y**2)>1.0)

norm(n, m)

Return the normalization of the n, m Zernike polynomial

n is the radial order

m is the angular order

rubin_scheduler.utils.angular_separation(long1, lat1, long2, lat2)

Angular separation between two points in degrees

Parameters:

• degrees (lat2 is the second latitudinal coordinate in)

• degrees

• degrees

• degrees

Return type:

The angular separation between the two points in degrees

rubin_scheduler.utils.approx_alt_az2_ra_dec(alt, az, lat, lon, mjd, lmst=None)

Convert alt, az to RA, Dec without taking into account aberration, precession, diffraction, etc.

Parameters:

• alt (numpy.array) – Altitude, same length as ra and dec. Degrees.

• az (numpy.array) – Azimuth, same length as ra and dec. Must be same length as alt. Degrees.

• lat (float) – Latitude of the observatory in degrees.

• lon (float) – Longitude of the observatory in degrees.

• mjd (float) – Modified Julian Date.

• lmst (float (None)) – The local mean sidereal time (computed if not given). (hours)

Returns:

• ra (array_like) – RA, in degrees.

• dec (array_like) – Dec, in degrees.

rubin_scheduler.utils.approx_altaz2pa(alt_deg, az_deg, latitude_deg)

A fast calculation of parallactic angle.

Parameters:

• alt_rad (float) – Altitude (degrees)

• az_rad (float) – Azimuth (degrees)

• latitude_rad (float) – The latitude of the observatory (degrees)

Returns:

pa – Parallactic angle (degrees)

Return type:

float

rubin_scheduler.utils.approx_ra_dec2_alt_az(ra, dec, lat, lon, mjd, lmst=None)

Convert Ra,Dec to Altitude and Azimuth.

Coordinate transformation is killing performance. Just use simple equations to speed it up and ignore aberration, precession, nutation, nutrition, etc.

Parameters:

• ra (array_like) – RA, in degrees.

• dec (array_like) – Dec, in degrees. Must be same length as ra.

• lat (float) – Latitude of the observatory in degrees.

• lon (float) – Longitude of the observatory in degrees.

• mjd (float) – Modified Julian Date.

• lmst (float (None)) – The local mean sidereal time (computed if not given). (hours)

Returns:

• alt (numpy.array) – Altitude, same length as ra and dec. degrees.

• az (numpy.array) – Azimuth, same length as ra and dec. degrees.

rubin_scheduler.utils.arcsec_from_degrees(value)

Convert an angle in degrees to arcseconds

Note: if you input None, you will get None back

rubin_scheduler.utils.arcsec_from_radians(value)

Convert an angle in radians to arcseconds

Note: if you input None, you will get None back

rubin_scheduler.utils.bearing(lon1, lat1, lon2, lat2)

Bearing between two points all radians

rubin_scheduler.utils.calc_lmst(mjd, longitude_rad)

Calculate the LMST for a location based on: jhaupt/Sidereal-Time-Calculator blob/master/SiderealTimeCalculator.py which uses: http://aa.usno.navy.mil/faq/docs/JD_Formula.php http://aa.usno.navy.mil/faq/docs/GAST.php and

Parameters:

• mjd (float) – is the universal time (ut1) expressed as an MJD. This can be a numpy array or a single value.

• long_rad (float) – is the longitude in radians (positive east of the prime meridian) This can be numpy array or a single value. If a numpy array, should have the same length as mjd. In that case, each long_rad will be applied only to the corresponding mjd.

Returns:

lst – The local sidereal time in hours

Return type:

float

rubin_scheduler.utils.calc_lmst_astropy(mjd, long_rad)

calculates local mean sidereal time

Parameters:

• mjd (float) – is the universal time (ut1) expressed as an MJD. This can be a numpy array or a single value.

• long_rad (float) – is the longitude in radians (positive east of the prime meridian) This can be numpy array or a single value. If a numpy array, should have the same length as mjd. In that case, each long_rad will be applied only to the corresponding mjd.

Returns:

lmst – is the local mean sidereal time in hours

Return type:

float

rubin_scheduler.utils.calc_season(ra, mjd, mjd_start=None, calc_diagonal=False)

Calculate the season (of visibility) in the survey for a series of ra/time values of an observation.

Based only on the RA of the point on the sky, it calculates the ‘season’ based on when the sun passes through this RA (this marks the start of a ‘season’).

Parameters:

• ra (float or np.ndarray (N,)) – The RA (in degrees) of the point(s) on the sky

• mjd (np.ndarray, (M,)) – The times of the observations, in MJD days

• mjd_start (float, optional) – The time of the start of the survey. Default None will use rubin_scheduler.utils.survey_start_mjd().

• calc_diagonal (bool, optional) – If True AND if len(mjd) == len(ra), ONLY the ‘diagonal’ elements of the seasons will be calculated. That is: RA and mjd are assumed to be paired and the resulting seasons will be a 1-d np.array of dimension (N,).

Returns:

seasons – The season values, as either a 1-d or 2-d array, depending on the value passed for ra and calc_diagonal.

Return type:

np.array, (M,) or np.array (N, M)

Notes

Seasons should be calculated using the RA of a fixed point on the sky, such as the slice_point[‘ra’] if calculating season values for a series of opsim pointings on the sky, rather than the value for each visit.

To convert to integer seasons, use np.floor(seasons).

“Season 0” will be the first (full) season after the RA value becomes visible for the first time after mjd_start. This induces a “discontinuity” in the resulting season values, corresponding to the RA where the survey started – like the international dateline (in this case, where season goes from ‘past season’ to ‘new season’).

The scheduler season_calc routine computes “season” independently, and may have a 90 degree offset in the location of this ‘skip’/zeropoint, plus requires different calculation of offset values to account for location on the sky.

rubin_scheduler.utils.cartesian_from_spherical(longitude, latitude)

Transforms between spherical and Cartesian coordinates.

Parameters:

• longitude (Unknown) – is a numpy array or a number in radians

• latitude (Unknown) – is a numpy array or number in radians

• a (Unknown) – numpy array of the (three-dimensional) cartesian coordinates on a unit sphere.

• arrays (if inputs are numpy)

• point (output[i][2] will be the z-coordinate of the ith)

• point

• point

• radians (All angles are in)

• Also

• xyz_from_ra_dec(). (look at)

rubin_scheduler.utils.ddf_locations()

Return the DDF locations as as dict. RA and dec in degrees.

rubin_scheduler.utils.degrees_from_arcsec(value)

Convert an angle in arcseconds to degrees

Note: if you input None, you will get None back

rubin_scheduler.utils.dest_latlon(dist, bearing, lat1, lon1)

Destination lat and lon given a distance, bearing and starting position all radians

rubin_scheduler.utils.find_htmid(ra, dec, max_level)

Find the htmid (the unique integer identifying each trixel) of the trixel containing a given RA, Dec pair.

Parameters:

• array) (dec in degrees (either a number or a numpy)

• array)

• level (max_level is an integer denoting the mesh)

• found (of the trixel you want)

Return type:

An int (the htmid) or an array of ints

rubin_scheduler.utils.get_all_trixels(level)

Return a dict of all of the trixels up to a given mesh level. The dict is keyed on htmid, unique integer identifying each trixel on the unit sphere. This method is efficient at generating many trixels at once.

rubin_scheduler.utils.get_package_dir(package)

Return the path to a package

rubin_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.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.utils.half_space_from_points(pt1, pt2, pt3)

Return a Half Space defined by two points on a Great Circle and a third point contained in the Half Space.

Parameters:

• pt1

• (RA (pt3 -- a tuple containing)

• of (Dec) in degrees)

• Space (contained in the Half)

• (RA

• point (Dec) in degrees of a)

• Space

Return type:

A Half Space

rubin_scheduler.utils.half_space_from_ra_dec(ra, dec, radius)

Take an RA, Dec and radius of a circular field of view and return a HalfSpace

Parameters:

• degrees (radius in)

• degrees

• degrees

Return type:

HalfSpace corresponding to the circular field of view

rubin_scheduler.utils.haversine(long1, lat1, long2, lat2)

DEPRECATED; use angular_separation() instead

Return the angular distance between two points in radians

Parameters:

• long1 (Unknown) – is the longitude of point 1 in radians

• lat1 (Unknown) – is the latitude of point 1 in radians

• long2 (Unknown) – is the longitude of point 2 in radians

• lat2 (Unknown) – is the latitude of point 2 in radians

• the (Unknown) – angular separation between points 1 and 2 in radians

rubin_scheduler.utils.healbin(ra, dec, values, nside=128, reduce_func=<function mean>, dtype=<class 'float'>, fill_val=-1.6375e+30)

Take arrays of ra’s, dec’s, and value and bin into healpixels. Like numpy.hexbin but for bins on a sphere.

Parameters:

• ra (np.array) – RA positions of the data points. Degrees.

• dec (np.array) – Dec positions of the data points. Degrees.

• values (np.array) – The values at each ra,dec position.

• nside (int) – Healpixel nside resolution. Must be a value of 2^N.

• reduce_func (function (numpy.mean)) – A function that will return a single value given a subset of values.

• dtype (dtype ('float')) – Data type of the resulting mask

• fill_val (float (hp.UNSEEN)) – Value to fill in with healpixels that have no value. Default is the healpy mask value.

Returns:

mapVals – A numpy array that is a valid Healpixel map.

Return type:

np.array

rubin_scheduler.utils.hp_grow_argsort(in_map, ignore_nan=True)

Find the maximum of a healpix map, then orders healpixels by selecting the maximum bordering the selected area.

Parameters:

• in_map (np.array) – A valid HEALpix array

• ignore_nan (bool (True)) – If true, ignores values that are NaN

Returns:

ordered_hp – The indices that put in_map in the correct order

Return type:

int array

rubin_scheduler.utils.hpid2_ra_dec(nside, hpids, **kwargs)

Correct for healpy being silly and running dec from 0-180.

Parameters:

• nside (int) – Must be a value of 2^N.

• hpids (np.array) – Array (or single value) of healpixel IDs.

Returns:

• raRet (float (or np.array)) – RA positions of the input healpixel IDs. In degrees.

• decRet (float (or np.array)) – Dec positions of the input healpixel IDs. In degrees.

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

Like scipy.binned_statistic, but for unique integer ids.

Parameters:

• ids (array-like of ints) – The integer ID for each value

• values (array-like) – The values to be combined

• statistic (function (np.mean)) – Function to run on the values that have matching ids.

Return type:

unique ids, binned values

rubin_scheduler.utils.intersect_half_spaces(hs1, hs2)

Parameters:

• hs1

• Spaces (hs2 are Half)

Returns:

• A list of the cartesian points where the Half Spaces intersect.

• Note (if the Half Spaces are identical, then this list will be)

• empty.

• Based on section 3.5 of

• Szalay A. et al. (2007)

• ”Indexing the Sphere with the Hierarchical Triangular Mesh”

• arXiv (cs/0701164)

rubin_scheduler.utils.level_from_htmid(htmid)

Find the level of a trixel from its htmid. The level indicates how refined the triangular mesh is.

There are 8*4**(d-1) triangles in a mesh of level=d

(equation 2.5 of Szalay A. et al. (2007) “Indexing the Sphere with the Hierarchical Triangular Mesh” arXiv:cs/0701164)

Note: valid htmids have 4+2n bits with a leading bit of 1

rubin_scheduler.utils.m5_flat_sed(visit_filter, musky, fwhm_eff, exp_time, airmass, nexp=1, tau_cloud=0)

Calculate the m5 value, using photometric scaling. Note, does not include shape of the object SED.

Parameters:

• visit_filter (str) – One of u,g,r,i,z,y

• musky (float) – Surface brightness of the sky in mag/sq arcsec

• fwhm_eff (float) – The seeing effective FWHM (arcsec)

• exp_time (float) – Exposure time for each exposure in the visit.

• airmass (float) – Airmass of the observation (unitless)

• nexp (int, optional) – The number of exposures. Default 1. (total on-sky time = exp_time * nexp)

• tau_cloud (float (0.)) – Any extinction from clouds in magnitudes (positive values = more extinction)

Returns:

m5 – The five-sigma limiting depth of a point source observed in he given conditions.

Return type:

float

rubin_scheduler.utils.m5_scale(exp_time, nexp, airmass, fwhm_eff, musky, dark_sky_mag, cm, d_cm_infinity, k_atm, tau_cloud=0, base_exp_time=15)

Return m5 (scaled) value for all filters.

Parameters:

• exp_time (float) – Exposure time (in seconds) for each exposure

• nexp (int) – Number of exposures

• airmass (float) – Airmass of the observation

• fwhm_eff (np.ndarray or pd.DataFrame) – FWHM (in arcseconds) per filter

• musky (np.ndarray or pd.DataFrame) – Sky background (in magnitudes/sq arcsecond) per filter of the observation

• dark_sky_mag (np.ndarray or pd.DataFrame) – Dark Sky, zenith magnitude/sq arcsecond - to scale musky. per filter

• cm (np.ndarray or pd.DataFrame) – cm value for the throughputs per filter

• d_cm_infinity (np.ndarray or pd.DataFrame) – d_cm_infinity values for the throughputs, per filter

• k_atm (np.ndarray or pd.DataFrame) – Atmospheric extinction values, per filter

• tau_cloud (float, optional) – Extinction due to clouds

• base_exp_time (float, optional) – The exposure time used to calculate cm / d_cm_infinity. Used to scale exp_time. This is the individual exposure exposure time.

Returns:

• np.ndarray or pd.DataFrame – m5 values scaled for the visit conditions

• Note (The columns required as input for m5_scale can be)

• calculated using the makeM5 function in lsst.syseng.throughputs.

rubin_scheduler.utils.moc2array(data, uniq, nside=128, reduce_func=<function sum>, density=True, fill_val=0.0)

Convert a Multi-Order Coverage Map to a single nside HEALPix array. Useful for converting maps output by LIGO alerts. Expect that future versions of healpy or astropy will be able to replace this functionality. Note that this is a convienence function that will probably degrade portions of the MOC that are sampled at high resolution.

Details of HEALPix Mulit-Order Coverage map: http://ivoa.net/documents/MOC/20190404/PR-MOC-1.1-20190404.pdf

Parameters:

• data (np.array) – Data values for the MOC map

• uniq (np.array) – The UNIQ values for the MOC map

• nside (int (128)) – The output map nside

• reduce_func (function (np.sum)) – The function to use to combine data into single healpixels.

• density (bool (True)) – If True, multiplies data values by pixel area before applying reduce_func, and divides the final array by the output pixel area. Should be True if working on a probability density MOC.

• fill_val (float (0.)) – Value to fill empty HEALPixels with. Good choices include 0 (default), hp.UNSEEN, and np.nan.

Returns:

np.array – the input map as processed by reduce_func.

Return type:

HEALpy array of nside. Units should be the same as

rubin_scheduler.utils.point_to_line_distance(lon1, lat1, lon2, lat2, lon3, lat3)

All radians points 1 and 2 define an arc segment, this finds the distance of point 3 to the arc segment.

rubin_scheduler.utils.ra_dec2_hpid(nside, ra, dec, **kwargs)

Assign ra,dec points to the correct healpixel.

Parameters:

• nside (int) – Must be a value of 2^N.

• ra (np.array) – RA values to assign to healpixels. Degrees.

• dec (np.array) – Dec values to assign to healpixels. Degrees.

Returns:

hpids – Healpixel IDs for the input positions.

Return type:

np.array

rubin_scheduler.utils.ra_dec_from_xyz(x, y, z)

Utility to convert x,y,z Cartesian coordinates to RA, dec positions in space.

Parameters:

• x (float or array) – The position on the x-axis of the given points on the unit sphere

• y (float or array) – The position on the y-axis of the given points on the unit sphere

• z (float or array) – The position on the z-axis of the given points on the unit sphere

Returns:

ra, dec – Ra and dec coordinates in degrees.

Return type:

floats or arrays

rubin_scheduler.utils.radians_from_arcsec(value)

Convert an angle in arcseconds to radians

Note: if you input None, you will get None back

rubin_scheduler.utils.rot_about_x(vec, theta)

Rotate a Cartesian vector an angle theta about the x axis. Theta is in radians. Positive theta rotates +y towards +z.

rubin_scheduler.utils.rot_about_y(vec, theta)

Rotate a Cartesian vector an angle theta about the y axis. Theta is in radians. Positive theta rotates +x towards -z.

rubin_scheduler.utils.rot_about_z(vec, theta)

Rotate a Cartesian vector an angle theta about the z axis. Theta is in radians. Positive theta rotates +x towards +y.

rubin_scheduler.utils.rotation_matrix_from_vectors(v1, v2)

Given two vectors v1,v2 calculate the rotation matrix for v1->v2 using the axis-angle approach

Parameters:

• v1 (Unknown) – Cartesian unit vectors (in three dimensions).

• v2 (Unknown) – Cartesian unit vectors (in three dimensions).

• rot (Unknown) – is the rotation matrix that rotates from one to the other

rubin_scheduler.utils.sample_patch_on_sphere(phi, theta, delta, size, seed=1)

Uniformly distributes samples on a patch on a sphere between phi pm delta, and theta pm delta on a sphere. Uniform distribution implies that the number of points in a patch of sphere is proportional to the area of the patch. Here, the coordinate system is the usual spherical coordinate system but with the azimuthal angle theta going from 90 degrees at the North Pole, to -90 degrees at the South Pole, through 0. at the equator.

This function is not equipped to handle wrap-around the ranges of theta phi and therefore does not work at the poles.

Parameters:

• phi (float,) – center of the spherical patch in ra with range, degrees

• theta (float) – degrees

• delta (float) – degrees

• size (int) – number of samples

• seed (int, optional, defaults to 1) – random Seed used for generating values

Returns:

phivals, thetavals – tuple of (phivals, thetavals) where phivals and thetavals are arrays of size size in degrees.

Return type:

np.ndarray, np.ndarray

rubin_scheduler.utils.spherical_from_cartesian(xyz)

Transforms between Cartesian and spherical coordinates

Parameters:

• xyz (Unknown) – is a numpy array of points in 3-D space. Each row is a different point.

• returns (Unknown) – longitude and latitude

• radians (All angles are in)

• Also

• ra_dec_from_xyz(). (look at)

rubin_scheduler.utils.survey_start_mjd()

A place to store the expected MJD start time of the survey.

rubin_scheduler.utils.trixel_from_htmid(htmid)

Return the trixel corresponding to the given htmid (htmid is the unique integer identifying each trixel).

Note: this method is not efficient for finding many trixels. It recursively generates trixels and their children until it finds the right htmid without remembering which trixels it has already generated. To generate many trixels, use the get_all_trixels() method, which efficiently generates all of the trixels up to a given mesh level.

Note: valid htmids have 4+2n bits with a leading bit of 1

rubin_scheduler.utils.uniform_sphere(npoints, seed=42)

Just make RA, dec points on a sphere

rubin_scheduler.utils.xyz_angular_radius(radius=1.75)

Convert an angular radius into a physical radius for a kdtree search.

Parameters:

radius (float) – Radius in degrees.

Returns:

radius

Return type:

float

rubin_scheduler.utils.xyz_from_ra_dec(ra, dec)

Utility to convert RA,dec positions in x,y,z space.

Parameters:

• ra (float or array) – RA in degrees

• dec (float or array) – Dec in degrees

Returns:

x,y,z – The position of the given points on the unit sphere.

Return type:

floats or arrays