Documentation¶
Target format and Airmass¶
astrometry.py
- Astrometry calculations for telescope scheduling.
This package provides routines for finding the positions of astronomical bodies to reasonable precision. It can be used to calculate target uptime and sunrise, sunset and twilight times.
The code uses SLALIB for the heavy lifting. The rise/set/transit algorithms here are implementations of Astronomical Algorithms, Ch. 14 (Jean Meeus).
This package contains functions for creating a target dictionary and validating required fields for the supported target types. Supported targets include:
Ra/Dec target
Hour Angle/Dec target
Major Planet target
Minor Planet target
Comet target
Satellite target (a No-op target)
Examples
Get the airmass values during the observable interval of a target:
>>> from rise_set.angle import Angle
>>> from rise_set.visibility import Visibility
>>> from rise_set.astrometry import calculate_airmass_at_times
>>> visibility = Visibility(site, start_date, end_date, horizon, twilight='nautical')
>>> observable_intervals = visibility.get_observable_intervals(
>>> target, airmass=1.6, moon_distance=Angle(degrees=30)
>>> )
>>> night_chunks = []
>>> for interval in observable_intervals:
>>> night_chunks.extend(
>>> [interval[0] + timedelta(minutes=i) for i in range(
>>> 0, int(interval[1] - interval[0].total_seconds() / 60), 10
>>> )]
>>> )
>>> airmass_values = calculate_airmass_at_times(
>>> night_chunks, target, site['latitude'], site['longitude'], site['altitude']
>>> )
-
rise_set.astrometry.
calculate_airmass_at_times
(times, target, obs_latitude, obs_longitude, obs_height)¶ Returns the airmass values at each of the times passed in for the given target
Returns the airmass values for a target and observer specified at each time value in the input times list. This uses the speedier slalib aop quick function which caches the object lat/lon/height and refraction parameters.
- Parameters
times (list) – A list of datetimes during which to calculate the airmass of the target
target (dict) – A dictionary of target details in the rise-set library format
obs_latitude (Angle) – The site/observer latitude within a rise-set Angle
obs_longitude (Angle) – The site/observer longitude within a rise-set Angle
obs_height (float) – The site/observer altitude in meters
- Returns
A list of airmass values that correspond to the input list of datetimes
- Return type
list
-
rise_set.astrometry.
make_comet_target
(target_type, epoch, epochofperih, inclination, long_node, arg_perihelion, perihdist, eccentricity)¶ Creates a rise-set target for a MPC comet
Creates a dictionary rise-set formatted target that must have all the necessary coordinates of a MPC formatted comet.
- Parameters
target_type (str) – The string representation of this target type (‘MPC_COMET’)
epoch (float) – The epoch of the target ephemerites
epochofperih (float) – The epoch of perihelion
inclination (float) – The inclination of the target in degrees
long_node (float) – The longitude of the ascending node in degrees
arg_perihelion (float) – The argument of perihelion in degrees
perihdist (float) – The perihelion distance of the target
eccentricity (float) – The eccentricty of the target
- Returns
A dictionary of target details to use as input to other rise-set functions
- Return type
dict
-
rise_set.astrometry.
make_hour_angle_target
(hour_angle, dec, ra_proper_motion=None, dec_proper_motion=None, parallax=None, epoch=None)¶ Creates a rise-set target with an ha and dec
Creates a dictionary rise-set formatted target that must at least have an ha/dec, but can optionally have ra/dec proper motion, radial velocity, parallax, and epoch.
- Parameters
hour_angle (Angle) – A rise-set Angle for the target ha
dec (Angle) – A rise-set Angle for the target dec
ra_proper_motion (ProperMotion) – ra proper motion for the target
dec_proper_motion (ProperMotion) – dec proper motion for the target
parallax (float) – target parallax value
rad_vel (float) – target radial velocity value
epoch (float) – target coordinates epoch (2000 default)
- Returns
A dictionary of target details to use as input to other rise-set functions
- Return type
dict
-
rise_set.astrometry.
make_major_planet_target
(target_type, epochofel, inclination, long_node, arg_perihelion, semi_axis, eccentricity, mean_anomaly, dailymot)¶ Creates a rise-set target for a JPL major planet
Creates a dictionary rise-set formatted target that must have all the necessary coordinates of a JPL formatted major planet.
- Parameters
target_type (str) – The string representation of this target (‘JPL_MAJOR_PLANET’)
epochofel (float) – The epoch of elements
inclination (float) – The inclination of the target in degrees
long_node (float) – The longitude of the ascending node in degrees
arg_perihelion (float) – The argument of perihelion in degrees
semi_axis (float) – The semi-axis of the target
eccentricity (float) – The eccentricty of the target
mean_anomaly (float) – The mean anomaly of the target in degrees
dailymot (float) – The daily motion of the target in degrees
- Returns
A dictionary of target details to use as input to other rise-set functions
- Return type
dict
-
rise_set.astrometry.
make_minor_planet_target
(target_type, epoch, inclination, long_node, arg_perihelion, semi_axis, eccentricity, mean_anomaly)¶ Creates a rise-set target for a MPC minor planet
Creates a dictionary rise-set formatted target that must have all the necessary coordinates of a MPC formatted minor planet.
- Parameters
target_type (str) – The string representation of this target type (‘MPC_MINOR_PLANET’)
epoch (float) – The epoch of the target ephemerites
inclination (float) – The inclination of the target in degrees
long_node (float) – The longitude of the ascending node in degrees
arg_perihelion (float) – The argument of perihelion in degrees
semi_axis (float) – The semi-axis of the target
eccentricity (float) – The eccentricty of the target
mean_anomaly (float) – The mean anomaly of the target in degrees
- Returns
A dictionary of target details to use as input to other rise-set functions
- Return type
dict
-
rise_set.astrometry.
make_ra_dec_target
(ra, dec, ra_proper_motion=None, dec_proper_motion=None, parallax=None, rad_vel=None, epoch=None)¶ Creates a rise-set target with an ra and dec
Creates a dictionary rise-set formatted target that must at least have an ra/dec, but can optionally have ra/dec proper motion, radial velocity, parallax, and epoch.
- Parameters
ra (Angle) – A rise-set Angle for the target ra
dec (Angle) – A rise-set Angle for the target dec
ra_proper_motion (ProperMotion) – ra proper motion for the target
dec_proper_motion (ProperMotion) – dec proper motion for the target
parallax (float) – target parallax value
rad_vel (float) – target radial velocity value
epoch (float) – target coordinates epoch (2000 default)
- Returns
A dictionary of target details to use as input to other rise-set functions
- Return type
dict
-
rise_set.astrometry.
make_satellite_target
(alt, az, diff_alt_rate, diff_az_rate, diff_alt_accel, diff_az_accel, diff_epoch_rate)¶ Creates a rise-set target for a Satellite
Creates a dictionary rise-set formatted target that must have all the necessary coordinates of a Satellite target. Satellite targets act as a noop / passthrough, since no rise/set calculation is performed on them. Instead, when a visibility function is called on a satellite target, it just returns the entire visible night for that telescope within the interval.
- Parameters
target_type (str) – The string representation of this target type (‘MPC_COMET’)
alt (float) – The altitude of the target in meters
az (float) – The azimuth of the target
diff_alt_rate (float) – The differential altitude rate (velocity) of the target
diff_az_rate (float) – The differential azimuth rate (velocity) of the target
diff_alt_accel (float) – The differential altitude acceleration of the target in meters
diff_az_accel (float) – The differential azimuth acceleration of the target
diff_epoch_rate (float) – The differential epoch rate
- Returns
A dictionary of target details to use as input to other rise-set functions
- Return type
dict
Visibility API and Example Usage¶
visibility.py
- Visibility class for calculating the observable intervals.
Examples
Get the observable intervals of a target:
>>> from rise_set.angle import Angle
>>> from rise_set.visibility import Visibility
>>> visibility = Visibility(
>>> site_details, start_date, end_date, horizon, twilight='nautical'
>>> )
>>> observable_intervals = visibility.get_observable_intervals(
>>> target, airmass=1.6, moon_distance=Angle(degrees=30), moon_phase=0.9
>>> )
-
class
rise_set.visibility.
Visibility
(site, start_date, end_date, horizon=0, twilight='sunrise', ha_limit_neg=- 4.9, ha_limit_pos=4.9, zenith_blind_spot=0)¶ The Visibility class is used to calculate target visibilities for a given site.
The Visibility class is instantiated with a given site and time range. It can be used repeatedly with different targets to get those targets observable intervals at the given site. It takes ha_limits, horizon limits, airmass limits, moon angular distance limits, and zenith blind spot limits into account when computing over all observable intervals for a target.
- Parameters
site (dict) – Dictionary of site properties. Should contain Angles for latitude and longitude
start_date (datetime) – Start datetime over which you want to calculate intervals
end_date (datetime) – End datetime over which you want to calculate intervals
horizon (float) – Horizon angle in degrees for the site
twilight (str) – Type of twilight to use for rise/set calculation. Can be one of sunrise, sunset, civil, nautical, astronomical
ha_limit_neg (float) – The hour angle negative limit for the telescope
ha_limit_pos (float) – The hour angle positive limit ror the telescope
zenith_blind_spot (float) – blind spot angle in degrees over which the telescope cannot observe
- Raises
rise_set.exceptions.InvalidHourAngleLimit – If the positive or negative hour angles provided are out of the possible range.
-
get_dark_intervals
()¶ Returns the dark intervals for the site.
Returns the night time dark intervals for the given site and date range set in this visibility object.
- Returns
A list of tuples of start/end datetime pairs that make up the dark intervals for this site.
- Return type
list
-
get_ha_intervals
(target)¶ Returns the hour angle intervals for the given target.
Returns the hour anle intervals for the given target and given site and date range set in this visibility object. The hour angle intervals are uninterupted chunks of time that the target is within the hour angle limits of the telescope.
- Parameters
target (dict) – A dictionary of target details in the rise-set library format
- Returns
A list of tuples of start/end datetime pairs that make up the intervals over which this target is within HA limits.
- Return type
list
-
get_moon_dark_intervals
()¶ Returns the dark moon intervals for the site.
Returns the dark moon intervals (moon is not visible) for the given site and date range set in this visibility object.
- Returns
A list of tuples of start/end datetime pairs that make up the dark moon intervals for this site.
- Return type
list
-
get_moon_distance_intervals
(target, target_intervals, moon_distance=Angle(30 degrees), chunk_size=datetime.timedelta(seconds=1800))¶ Returns the moon distance intervals for the given target.
Returns the intervals for which the given target is greater than the angular moon distance away from the moon at the given site and date range set in this visibility object.
- Parameters
target (dict) – A dictionary of target details in the rise-set library format
target_intervals (list) – A list of datetime tuples that represent the above horizon intervals for the target. Returned by get_target_intervals()
moon_distance (Angle) – The minimum angular moon distance that the target must be away from the moon
chunk_size (timedelta) – The time delta over which to calculate if the target intervals are out of range of the zenith.
- Returns
A list of tuples of start/end datetime pairs that make up the intervals over which this target is greater than angular moon distance away from moon.
- Return type
list
-
get_moon_phase_intervals
(target_intervals, max_moon_phase=1.0, chunk_size=datetime.timedelta(seconds=1800))¶ Returns the intervals in which the target is visible and the moon phase does not exceed moon_phase
- Parameters
target_intervals (list) – A list of datetime tuples that represent the above horizon intervals for the target. Returned by get_target_intervals()
moon_phase (float) – max allowablable fractional moon phase from 0 to 1 (full moon).
chunk_size (timedelta) – The time delta over which to calculate if the target intervals are out of range of the zenith.
- Returns
A list of tuples of start/end datetime pairs that make up the intervals over which this target is visible and the moon phase is less than max_moon_phase
- Return type
list
-
get_observable_intervals
(target, airmass=None, moon_distance=Angle(30 degrees), moon_phase=1.0)¶ Returns the observable intervals for the given target.
Returns the observable intervals for the given target and given site and date range set in this visibility object. The observable intervals are the intersections of the dark intervals at the site, the above horizon target intervals, the moon distance intervals of the target, the hour angle intervals of the target, and the zenith blind spot intervals of the target.
- Parameters
target (dict) – A dictionary of target details in the rise-set library format
airmass (float) – The maximum acceptable airmass for this target to be observable in
moon_distance (Angle) – The minimum acceptable angular distance between the moon and the target
moon_phase (float) – The maximum acceptable moon phase fraction from 0 to 1 (full moon)
- Returns
A list of tuples of start/end datetime pairs that make up the intervals over which this target is observable.
- Return type
list
- Raises
rise_set.exceptions.RiseSetError – If there was a problem calculating the rise/set/transfer times of the target
-
get_target_intervals
(target, up=True, airmass=None)¶ Returns the above or below horizon intervals for the given target.
Returns the above (up=True) or below (up=False) horizon intervals for the given target and given site and date range set in this visibility object.
- Parameters
target (dict) – A dictionary of target details in the rise-set library format
airmass (float) – The maximum acceptable airmass for this target to be observable in
up (boolean) – True (default) if you want intervals above the horizon, False for below
- Returns
A list of tuples of start/end datetime pairs that make up the intervals over which this target is above/below the horizon.
- Return type
list
- Raises
rise_set.exceptions.RiseSetError – If there was a problem calculating the rise/set/transfer times of the target
-
get_zenith_distance_intervals
(target, target_intervals, chunk_size=datetime.timedelta(seconds=60))¶ Returns the zenith distance intervals for the given target.
Returns the intervals for which the given target is greater than zenith distance away from the zenith at the given site and date range set in this visibility object.
- Parameters
target (dict) – A dictionary of target details in the rise-set library format
target_intervals (list) – A list of datetime tuples that represent the above horizon intervals for the target. Returned by get_target_intervals()
chunk_size (timedelta) – The time delta over which to calculate if the target intervals are out of range of the zenith.
- Returns
A list of tuples of start/end datetime pairs that make up the intervals over which this target is greater than zenith distance away from zenith.
- Return type
list
Exceptions¶
Exceptions used throughout rise-set package
-
exception
rise_set.exceptions.
AngleConfigError
¶ Exception that is raised when invalid constructor arguments are given to the Angle class.
-
exception
rise_set.exceptions.
IncompleteTargetError
¶ Exception that is raised when a target is missing a key value (RA, Dec, etc.).
-
exception
rise_set.exceptions.
InvalidAngleError
¶ Exception that is raised when out-of-range angles are provided to the Angle class.
-
exception
rise_set.exceptions.
InvalidDateTimeError
¶ Exception that is raised when an invalid date is encountered.
-
exception
rise_set.exceptions.
InvalidHourAngleLimit
¶ Exception that is raised when an invalid hour angle limit is given.
-
exception
rise_set.exceptions.
MovingViolation
¶ Exception that is raised when moving object errors are encountered.
-
exception
rise_set.exceptions.
RatesConfigError
¶ Exception that is raised when invalid constructor arguments are provided to the ProperMotion class.
-
exception
rise_set.exceptions.
RiseSetError
¶ Exception that is raised when a target either never rises or never sets.