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:

  1. Ra/Dec target

  2. Hour Angle/Dec target

  3. Major Planet target

  4. Minor Planet target

  5. Comet target

  6. 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.