# -*- coding: utf-8 -*-

# Licensed under a 3-clause BSD style license - see LICENSE.rst

"""

The astropy.time package provides functionality for manipulating times and

dates. Specific emphasis is placed on supporting time scales (e.g. UTC, TAI,

UT1) and time representations (e.g. JD, MJD, ISO 8601) that are used in

astronomy.

"""

import copy

import operator

from datetime import datetime, timedelta

import numpy as np

from ..utils.compat import NUMPY_LT_1_11_2

from .. import units as u, constants as const

from .. import _erfa as erfa

from ..units import UnitConversionError

from ..utils import ShapedLikeNDArray

from ..utils.compat.misc import override__dir__

from ..utils.data_info import MixinInfo, data_info_factory

from .utils import day_frac

from .formats import (TIME_FORMATS, TIME_DELTA_FORMATS,

TimeJD, TimeUnique, TimeAstropyTime, TimeDatetime)

# Import TimeFromEpoch to avoid breaking code that followed the old example of

# making a custom timescale in the documentation.

from .formats import TimeFromEpoch # pylint: disable=W0611

__all__ = ['Time', 'TimeDelta', 'TIME_SCALES', 'STANDARD_TIME_SCALES', 'TIME_DELTA_SCALES',

'ScaleValueError', 'OperandTypeError', 'TimeInfo']

STANDARD_TIME_SCALES = ('tai', 'tcb', 'tcg', 'tdb', 'tt', 'ut1', 'utc')

LOCAL_SCALES = ('local',)

TIME_TYPES = dict((scale, scales) for scales in (STANDARD_TIME_SCALES, LOCAL_SCALES) for scale in scales)

TIME_SCALES = STANDARD_TIME_SCALES + LOCAL_SCALES

MULTI_HOPS = {('tai', 'tcb'): ('tt', 'tdb'),

('tai', 'tcg'): ('tt',),

('tai', 'ut1'): ('utc',),

('tai', 'tdb'): ('tt',),

('tcb', 'tcg'): ('tdb', 'tt'),

('tcb', 'tt'): ('tdb',),

('tcb', 'ut1'): ('tdb', 'tt', 'tai', 'utc'),

('tcb', 'utc'): ('tdb', 'tt', 'tai'),

('tcg', 'tdb'): ('tt',),

('tcg', 'ut1'): ('tt', 'tai', 'utc'),

('tcg', 'utc'): ('tt', 'tai'),

('tdb', 'ut1'): ('tt', 'tai', 'utc'),

('tdb', 'utc'): ('tt', 'tai'),

('tt', 'ut1'): ('tai', 'utc'),

('tt', 'utc'): ('tai',),

}

GEOCENTRIC_SCALES = ('tai', 'tt', 'tcg')

BARYCENTRIC_SCALES = ('tcb', 'tdb')

ROTATIONAL_SCALES = ('ut1',)

TIME_DELTA_TYPES = dict((scale, scales)

for scales in (GEOCENTRIC_SCALES, BARYCENTRIC_SCALES,

ROTATIONAL_SCALES, LOCAL_SCALES) for scale in scales)

TIME_DELTA_SCALES = GEOCENTRIC_SCALES + BARYCENTRIC_SCALES + ROTATIONAL_SCALES + LOCAL_SCALES

# For time scale changes, we need L_G and L_B, which are stored in erfam.h as

# /* L_G = 1 - d(TT)/d(TCG) */

# define ERFA_ELG (6.969290134e-10)

# /* L_B = 1 - d(TDB)/d(TCB), and TDB (s) at TAI 1977/1/1.0 */

# define ERFA_ELB (1.550519768e-8)

# These are exposed in erfa as erfa.ELG and erfa.ELB.

# Implied: d(TT)/d(TCG) = 1-L_G

# and d(TCG)/d(TT) = 1/(1-L_G) = 1 + (1-(1-L_G))/(1-L_G) = 1 + L_G/(1-L_G)

# scale offsets as second = first + first * scale_offset[(first,second)]

SCALE_OFFSETS = {('tt', 'tai'): None,

('tai', 'tt'): None,

('tcg', 'tt'): -erfa.ELG,

('tt', 'tcg'): erfa.ELG / (1. - erfa.ELG),

('tcg', 'tai'): -erfa.ELG,

('tai', 'tcg'): erfa.ELG / (1. - erfa.ELG),

('tcb', 'tdb'): -erfa.ELB,

('tdb', 'tcb'): erfa.ELB / (1. - erfa.ELB)}

# triple-level dictionary, yay!

SIDEREAL_TIME_MODELS = {

'mean': {

'IAU2006': {'function': erfa.gmst06, 'scales': ('ut1', 'tt')},

'IAU2000': {'function': erfa.gmst00, 'scales': ('ut1', 'tt')},

'IAU1982': {'function': erfa.gmst82, 'scales': ('ut1',)}},

'apparent': {

'IAU2006A': {'function': erfa.gst06a, 'scales': ('ut1', 'tt')},

'IAU2000A': {'function': erfa.gst00a, 'scales': ('ut1', 'tt')},

'IAU2000B': {'function': erfa.gst00b, 'scales': ('ut1',)},

'IAU1994': {'function': erfa.gst94, 'scales': ('ut1',)}}}

class TimeInfo(MixinInfo):

"""

Container for meta information like name, description, format. This is

required when the object is used as a mixin column within a table, but can

be used as a general way to store meta information.

"""

attrs_from_parent = set(['unit']) # unit is read-only and None

attr_names = MixinInfo.attr_names | {'serialize_method'}

_supports_indexing = True

# The usual tuple of attributes needed for serialization is replaced

# by a property, since Time can be serialized different ways.

_represent_as_dict_extra_attrs = ('format', 'scale', 'precision',

'in_subfmt', 'out_subfmt', 'location',

'_delta_ut1_utc', '_delta_tdb_tt')

mask_val = np.ma.masked

@property

def _represent_as_dict_attrs(self):

method = self.serialize_method[self._serialize_context]

if method == 'formatted_value':

out = ('value',)

elif method == 'jd1_jd2':

out = ('jd1', 'jd2')

else:

raise ValueError("serialize method must be 'formatted_value' or 'jd1_jd2'")

return out + self._represent_as_dict_extra_attrs

def __init__(self, bound=False):

super().__init__(bound)

# If bound to a data object instance then create the dict of attributes

# which stores the info attribute values.

if bound:

# Specify how to serialize this object depending on context.

# If ``True`` for a context, then use formatted ``value`` attribute

# (e.g. the ISO time string). If ``False`` then use float jd1 and jd2.

self.serialize_method = {'fits': 'jd1_jd2',

'ecsv': 'formatted_value',

'hdf5': 'jd1_jd2',

'yaml': 'jd1_jd2',

None: 'jd1_jd2'}

@property

def unit(self):

return None

info_summary_stats = staticmethod(

data_info_factory(names=MixinInfo._stats,

funcs=[getattr(np, stat) for stat in MixinInfo._stats]))

# When Time has mean, std, min, max methods:

# funcs = [lambda x: getattr(x, stat)() for stat_name in MixinInfo._stats])

def _construct_from_dict_base(self, map):

if 'jd1' in map and 'jd2' in map:

format = map.pop('format')

map['format'] = 'jd'

map['val'] = map.pop('jd1')

map['val2'] = map.pop('jd2')

else:

format = map['format']

map['val'] = map.pop('value')

out = self._parent_cls(**map)

out.format = format

return out

def _construct_from_dict(self, map):

delta_ut1_utc = map.pop('_delta_ut1_utc', None)

delta_tdb_tt = map.pop('_delta_tdb_tt', None)

out = self._construct_from_dict_base(map)

if delta_ut1_utc is not None:

out._delta_ut1_utc = delta_ut1_utc

if delta_tdb_tt is not None:

out._delta_tdb_tt = delta_tdb_tt

return out

def new_like(self, cols, length, metadata_conflicts='warn', name=None):

"""

Return a new Time instance which is consistent with the input Time objects

``cols`` and has ``length`` rows.

This is intended for creating an empty Time instance whose elements can

be set in-place for table operations like join or vstack. It checks

that the input locations and attributes are consistent. This is used

when a Time object is used as a mixin column in an astropy Table.

Parameters

----------

cols : list

List of input columns (Time objects)

length : int

Length of the output column object

metadata_conflicts : str ('warn'|'error'|'silent')

How to handle metadata conflicts

name : str

Output column name

Returns

-------

col : Time (or subclass)

Empty instance of this class consistent with ``cols``

"""

# Get merged info attributes like shape, dtype, format, description, etc.

attrs = self.merge_cols_attributes(cols, metadata_conflicts, name,

('meta', 'description'))

attrs.pop('dtype') # Not relevant for Time

col0 = cols[0]

# Check that location is consistent for all Time objects

for col in cols[1:]:

# This is the method used by __setitem__ to ensure that the right side

# has a consistent location (and coerce data if necessary, but that does

# not happen in this case since `col` is already a Time object). If this

# passes then any subsequent table operations via setitem will work.

try:

col0._make_value_equivalent(slice(None), col)

except ValueError:

raise ValueError('input columns have inconsistent locations')

# Make a new Time object with the desired shape and attributes

shape = (length,) + attrs.pop('shape')

jd2000 = 2451544.5 # Arbitrary JD value J2000.0 that will work with ERFA

jd1 = np.full(shape, jd2000, dtype='f8')

jd2 = np.zeros(shape, dtype='f8')

tm_attrs = {attr: getattr(col0, attr)

for attr in ('scale', 'location',

'precision', 'in_subfmt', 'out_subfmt')}

out = self._parent_cls(jd1, jd2, format='jd', **tm_attrs)

out.format = col0.format

# Set remaining info attributes

for attr, value in attrs.items():

setattr(out.info, attr, value)

return out

class TimeDeltaInfo(TimeInfo):

_represent_as_dict_extra_attrs = ('format', 'scale')

def _construct_from_dict(self, map):

return self._construct_from_dict_base(map)

class Time(ShapedLikeNDArray):

"""

Represent and manipulate times and dates for astronomy.

A `Time` object is initialized with one or more times in the ``val``

argument. The input times in ``val`` must conform to the specified

``format`` and must correspond to the specified time ``scale``. The

optional ``val2`` time input should be supplied only for numeric input

formats (e.g. JD) where very high precision (better than 64-bit precision)

is required.

The allowed values for ``format`` can be listed with::

>>> list(Time.FORMATS)

['jd', 'mjd', 'decimalyear', 'unix', 'cxcsec', 'gps', 'plot_date',

'datetime', 'iso', 'isot', 'yday', 'fits', 'byear', 'jyear', 'byear_str',

'jyear_str']

Parameters

----------

val : sequence, ndarray, number, str, bytes, or `~astropy.time.Time` object

Value(s) to initialize the time or times. Bytes are decoded as ascii.

val2 : sequence, ndarray, or number; optional

Value(s) to initialize the time or times. Only used for numerical

input, to help preserve precision.

format : str, optional

Format of input value(s)

scale : str, optional

Time scale of input value(s), must be one of the following:

('tai', 'tcb', 'tcg', 'tdb', 'tt', 'ut1', 'utc')

precision : int, optional

Digits of precision in string representation of time

in_subfmt : str, optional

Subformat for inputting string times

out_subfmt : str, optional

Subformat for outputting string times

location : `~astropy.coordinates.EarthLocation` or tuple, optional

If given as an tuple, it should be able to initialize an

an EarthLocation instance, i.e., either contain 3 items with units of

length for geocentric coordinates, or contain a longitude, latitude,

and an optional height for geodetic coordinates.

Can be a single location, or one for each input time.

copy : bool, optional

Make a copy of the input values

"""

SCALES = TIME_SCALES

"""List of time scales"""

FORMATS = TIME_FORMATS

"""Dict of time formats"""

# Make sure that reverse arithmetic (e.g., TimeDelta.__rmul__)

# gets called over the __mul__ of Numpy arrays.

__array_priority__ = 20000

# Declare that Time can be used as a Table column by defining the

# attribute where column attributes will be stored.

_astropy_column_attrs = None

def __new__(cls, val, val2=None, format=None, scale=None,

precision=None, in_subfmt=None, out_subfmt=None,

location=None, copy=False):

if isinstance(val, cls):

self = val.replicate(format=format, copy=copy)

else:

self = super().__new__(cls)

return self

def __getnewargs__(self):

return (self._time,)

def __init__(self, val, val2=None, format=None, scale=None,

precision=None, in_subfmt=None, out_subfmt=None,

location=None, copy=False):

if location is not None:

from ..coordinates import EarthLocation

if isinstance(location, EarthLocation):

self.location = location

else:

self.location = EarthLocation(*location)

else:

self.location = None

if isinstance(val, self.__class__):

# Update _time formatting parameters if explicitly specified

if precision is not None:

self._time.precision = precision

if in_subfmt is not None:

self._time.in_subfmt = in_subfmt

if out_subfmt is not None:

self._time.out_subfmt = out_subfmt

self.SCALES = TIME_TYPES[self.scale]

if scale is not None:

self._set_scale(scale)

else:

self._init_from_vals(val, val2, format, scale, copy,

precision, in_subfmt, out_subfmt)

self.SCALES = TIME_TYPES[self.scale]

if self.location is not None and (self.location.size > 1 and

self.location.shape != self.shape):

try:

# check the location can be broadcast to self's shape.

self.location = np.broadcast_to(self.location, self.shape,

subok=True)

except Exception:

raise ValueError('The location with shape {0} cannot be '

'broadcast against time with shape {1}. '

'Typically, either give a single location or '

'one for each time.'

.format(self.location.shape, self.shape))

def _init_from_vals(self, val, val2, format, scale, copy,

precision=None, in_subfmt=None, out_subfmt=None):

"""

Set the internal _format, scale, and _time attrs from user

inputs. This handles coercion into the correct shapes and

some basic input validation.

"""

if precision is None:

precision = 3

if in_subfmt is None:

in_subfmt = '*'

if out_subfmt is None:

out_subfmt = '*'

# Coerce val into an array

val = _make_array(val, copy)

# If val2 is not None, ensure consistency

if val2 is not None:

val2 = _make_array(val2, copy)

try:

np.broadcast(val, val2)

except ValueError:

raise ValueError('Input val and val2 have inconsistent shape; '

'they cannot be broadcast together.')

if scale is not None:

if not (isinstance(scale, str) and

scale.lower() in self.SCALES):

raise ScaleValueError("Scale {0!r} is not in the allowed scales "

"{1}".format(scale,

sorted(self.SCALES)))

# If either of the input val, val2 are masked arrays then

# find the masked elements and fill them.

mask, val, val2 = _check_for_masked_and_fill(val, val2)

# Parse / convert input values into internal jd1, jd2 based on format

self._time = self._get_time_fmt(val, val2, format, scale,

precision, in_subfmt, out_subfmt)

self._format = self._time.name

# If any inputs were masked then masked jd2 accordingly. From above

# routine ``mask`` must be either Python bool False or an bool ndarray

# with shape broadcastable to jd2.

if mask is not False:

mask = np.broadcast_to(mask, self._time.jd2.shape)

self._time.jd2[mask] = np.nan

def _get_time_fmt(self, val, val2, format, scale,

precision, in_subfmt, out_subfmt):

"""

Given the supplied val, val2, format and scale try to instantiate

the corresponding TimeFormat class to convert the input values into

the internal jd1 and jd2.

If format is `None` and the input is a string-type or object array then

guess available formats and stop when one matches.

"""

if format is None and val.dtype.kind in ('S', 'U', 'O'):

formats = [(name, cls) for name, cls in self.FORMATS.items()

if issubclass(cls, TimeUnique)]

err_msg = ('any of the formats where the format keyword is '

'optional {0}'.format([name for name, cls in formats]))

# AstropyTime is a pseudo-format that isn't in the TIME_FORMATS registry,

# but try to guess it at the end.

formats.append(('astropy_time', TimeAstropyTime))

elif not (isinstance(format, str) and

format.lower() in self.FORMATS):

if format is None:

raise ValueError("No time format was given, and the input is "

"not unique")

else:

raise ValueError("Format {0!r} is not one of the allowed "

"formats {1}".format(format,

sorted(self.FORMATS)))

else:

formats = [(format, self.FORMATS[format])]

err_msg = 'the format class {0}'.format(format)

for format, FormatClass in formats:

try:

return FormatClass(val, val2, scale, precision, in_subfmt, out_subfmt)

except UnitConversionError:

raise

except (ValueError, TypeError):

pass

else:

raise ValueError('Input values did not match {0}'.format(err_msg))

@classmethod

def now(cls):

"""

Creates a new object corresponding to the instant in time this

method is called.

.. note::

"Now" is determined using the `~datetime.datetime.utcnow`

function, so its accuracy and precision is determined by that

function. Generally that means it is set by the accuracy of

your system clock.

Returns

-------

nowtime

A new `Time` object (or a subclass of `Time` if this is called from

such a subclass) at the current time.

"""

# call `utcnow` immediately to be sure it's ASAP

dtnow = datetime.utcnow()

return cls(val=dtnow, format='datetime', scale='utc')

info = TimeInfo()

@property

def writeable(self):

return self._time.jd1.flags.writeable & self._time.jd2.flags.writeable

@writeable.setter

def writeable(self, value):

self._time.jd1.flags.writeable = value

self._time.jd2.flags.writeable = value

@property

def format(self):

"""

Get or set time format.

The format defines the way times are represented when accessed via the

``.value`` attribute. By default it is the same as the format used for

initializing the `Time` instance, but it can be set to any other value

that could be used for initialization. These can be listed with::

>>> list(Time.FORMATS)

['jd', 'mjd', 'decimalyear', 'unix', 'cxcsec', 'gps', 'plot_date',

'datetime', 'iso', 'isot', 'yday', 'fits', 'byear', 'jyear', 'byear_str',

'jyear_str']

"""

return self._format

@format.setter

def format(self, format):

"""Set time format"""

if format not in self.FORMATS:

raise ValueError('format must be one of {0}'

.format(list(self.FORMATS)))

format_cls = self.FORMATS[format]

# If current output subformat is not in the new format then replace

# with default '*'

if hasattr(format_cls, 'subfmts'):

subfmt_names = [subfmt[0] for subfmt in format_cls.subfmts]

if self.out_subfmt not in subfmt_names:

self.out_subfmt = '*'

self._time = format_cls(self._time.jd1, self._time.jd2,

self._time._scale, self.precision,

in_subfmt=self.in_subfmt,

out_subfmt=self.out_subfmt,

from_jd=True)

self._format = format

def __repr__(self):

return ("<{0} object: scale='{1}' format='{2}' value={3}>"

.format(self.__class__.__name__, self.scale, self.format,

getattr(self, self.format)))

def __str__(self):

return str(getattr(self, self.format))

@property

def scale(self):

"""Time scale"""

return self._time.scale

def _set_scale(self, scale):

"""

This is the key routine that actually does time scale conversions.

This is not public and not connected to the read-only scale property.

"""

if scale == self.scale:

return

if scale not in self.SCALES:

raise ValueError("Scale {0!r} is not in the allowed scales {1}"

.format(scale, sorted(self.SCALES)))

# Determine the chain of scale transformations to get from the current

# scale to the new scale. MULTI_HOPS contains a dict of all

# transformations (xforms) that require intermediate xforms.

# The MULTI_HOPS dict is keyed by (sys1, sys2) in alphabetical order.

xform = (self.scale, scale)

xform_sort = tuple(sorted(xform))

multi = MULTI_HOPS.get(xform_sort, ())

xforms = xform_sort[:1] + multi + xform_sort[-1:]

# If we made the reverse xform then reverse it now.

if xform_sort != xform:

xforms = tuple(reversed(xforms))

# Transform the jd1,2 pairs through the chain of scale xforms.

jd1, jd2 = self._time.jd1, self._time.jd2_filled

for sys1, sys2 in zip(xforms[:-1], xforms[1:]):

# Some xforms require an additional delta_ argument that is

# provided through Time methods. These values may be supplied by

# the user or computed based on available approximations. The

# get_delta_ methods are available for only one combination of

# sys1, sys2 though the property applies for both xform directions.

args = [jd1, jd2]

for sys12 in ((sys1, sys2), (sys2, sys1)):

dt_method = '_get_delta_{0}_{1}'.format(*sys12)

try:

get_dt = getattr(self, dt_method)

except AttributeError:

pass

else:

args.append(get_dt(jd1, jd2))

break

conv_func = getattr(erfa, sys1 + sys2)

jd1, jd2 = conv_func(*args)

if self.masked:

jd2[self.mask] = np.nan

self._time = self.FORMATS[self.format](jd1, jd2, scale, self.precision,

self.in_subfmt, self.out_subfmt,

from_jd=True)

@property

def precision(self):

"""

Decimal precision when outputting seconds as floating point (int

value between 0 and 9 inclusive).

"""

return self._time.precision

@precision.setter

def precision(self, val):

del self.cache

if not isinstance(val, int) or val < 0 or val > 9:

raise ValueError('precision attribute must be an int between '

'0 and 9')

self._time.precision = val

@property

def in_subfmt(self):

"""

Unix wildcard pattern to select subformats for parsing string input

times.

"""

return self._time.in_subfmt

@in_subfmt.setter

def in_subfmt(self, val):

del self.cache

if not isinstance(val, str):

raise ValueError('in_subfmt attribute must be a string')

self._time.in_subfmt = val

@property

def out_subfmt(self):

"""

Unix wildcard pattern to select subformats for outputting times.

"""

return self._time.out_subfmt

@out_subfmt.setter

def out_subfmt(self, val):

del self.cache

if not isinstance(val, str):

raise ValueError('out_subfmt attribute must be a string')

self._time.out_subfmt = val

@property

def shape(self):

"""The shape of the time instances.

Like `~numpy.ndarray.shape`, can be set to a new shape by assigning a

tuple. Note that if different instances share some but not all

underlying data, setting the shape of one instance can make the other

instance unusable. Hence, it is strongly recommended to get new,

reshaped instances with the ``reshape`` method.

Raises

------

AttributeError

If the shape of the ``jd1``, ``jd2``, ``location``,

``delta_ut1_utc``, or ``delta_tdb_tt`` attributes cannot be changed

without the arrays being copied. For these cases, use the

`Time.reshape` method (which copies any arrays that cannot be

reshaped in-place).

"""

return self._time.jd1.shape

@shape.setter

def shape(self, shape):

del self.cache

# We have to keep track of arrays that were already reshaped,

# since we may have to return those to their original shape if a later

# shape-setting fails.

reshaped = []

oldshape = self.shape

# In-place reshape of data/attributes. Need to access _time.jd1/2 not

# self.jd1/2 because the latter are not guaranteed to be the actual

# data, and in fact should not be directly changeable from the public

# API.

for obj, attr in ((self._time, 'jd1'),

(self._time, 'jd2'),

(self, '_delta_ut1_utc'),

(self, '_delta_tdb_tt'),

(self, 'location')):

val = getattr(obj, attr, None)

if val is not None and val.size > 1:

try:

val.shape = shape

except AttributeError:

for val2 in reshaped:

val2.shape = oldshape

raise

else:

reshaped.append(val)

def _shaped_like_input(self, value):

out = value

if not self._time.jd1.shape and not np.ma.is_masked(value):

out = value.item()

return out

@property

def jd1(self):

"""

First of the two doubles that internally store time value(s) in JD.

"""

jd1 = self._time.mask_if_needed(self._time.jd1)

return self._shaped_like_input(jd1)

@property

def jd2(self):

"""

Second of the two doubles that internally store time value(s) in JD.

"""

jd2 = self._time.mask_if_needed(self._time.jd2)

return self._shaped_like_input(jd2)

@property

def value(self):

"""Time value(s) in current format"""

# The underlying way to get the time values for the current format is:

# self._shaped_like_input(self._time.to_value(parent=self))

# This is done in __getattr__. By calling getattr(self, self.format)

# the ``value`` attribute is cached.

return getattr(self, self.format)

@property

def masked(self):

return self._time.masked

@property

def mask(self):

return self._time.mask

def _make_value_equivalent(self, item, value):

"""Coerce setitem value into an equivalent Time object"""

# If there is a vector location then broadcast to the Time shape

# and then select with ``item``

if self.location is not None and self.location.shape:

self_location = np.broadcast_to(self.location, self.shape, subok=True)[item]

else:

self_location = self.location

if isinstance(value, Time):

# Make sure locations are compatible. Location can be either None or

# a Location object.

if self_location is None and value.location is None:

match = True

elif ((self_location is None and value.location is not None) or

(self_location is not None and value.location is None)):

match = False

else:

match = np.all(self_location == value.location)

if not match:

raise ValueError('cannot set to Time with different location: '

'expected location={} and '

'got location={}'

.format(self_location, value.location))

else:

try:

value = self.__class__(value, scale=self.scale, location=self_location)

except Exception:

try:

value = self.__class__(value, scale=self.scale, format=self.format,

location=self_location)

except Exception as err:

raise ValueError('cannot convert value to a compatible Time object: {}'

.format(err))

return value

def __setitem__(self, item, value):

if not self.writeable:

if self.shape:

raise ValueError('{} object is read-only. Make a '

'copy() or set "writeable" attribute to True.'

.format(self.__class__.__name__))

else:

raise ValueError('scalar {} object is read-only.'

.format(self.__class__.__name__))

# Any use of setitem results in immediate cache invalidation

del self.cache

# Setting invalidates transform deltas

for attr in ('_delta_tdb_tt', '_delta_ut1_utc'):

if hasattr(self, attr):

delattr(self, attr)

if value in (np.ma.masked, np.nan):

self._time.jd2[item] = np.nan

return

value = self._make_value_equivalent(item, value)

# Finally directly set the jd1/2 values. Locations are known to match.

if self.scale is not None:

value = getattr(value, self.scale)

self._time.jd1[item] = value._time.jd1

self._time.jd2[item] = value._time.jd2

def light_travel_time(self, skycoord, kind='barycentric', location=None, ephemeris=None):

"""Light travel time correction to the barycentre or heliocentre.

The frame transformations used to calculate the location of the solar

system barycentre and the heliocentre rely on the erfa routine epv00,

which is consistent with the JPL DE405 ephemeris to an accuracy of

11.2 km, corresponding to a light travel time of 4 microseconds.

The routine assumes the source(s) are at large distance, i.e., neglects

finite-distance effects.

Parameters

----------

skycoord : `~astropy.coordinates.SkyCoord`

The sky location to calculate the correction for.

kind : str, optional

``'barycentric'`` (default) or ``'heliocentric'``

location : `~astropy.coordinates.EarthLocation`, optional

The location of the observatory to calculate the correction for.

If no location is given, the ``location`` attribute of the Time

object is used

ephemeris : str, optional

Solar system ephemeris to use (e.g., 'builtin', 'jpl'). By default,

use the one set with ``astropy.coordinates.solar_system_ephemeris.set``.

For more information, see `~astropy.coordinates.solar_system_ephemeris`.

Returns

-------

time_offset : `~astropy.time.TimeDelta`

The time offset between the barycentre or Heliocentre and Earth,

in TDB seconds. Should be added to the original time to get the

time in the Solar system barycentre or the Heliocentre.

"""

if kind.lower() not in ('barycentric', 'heliocentric'):

raise ValueError("'kind' parameter must be one of 'heliocentric' "

"or 'barycentric'")

if location is None:

if self.location is None:

raise ValueError('An EarthLocation needs to be set or passed '

'in to calculate bary- or heliocentric '

'corrections')

location = self.location

from ..coordinates import (UnitSphericalRepresentation, CartesianRepresentation,

HCRS, ICRS, GCRS, solar_system_ephemeris)

# ensure sky location is ICRS compatible

if not skycoord.is_transformable_to(ICRS()):

raise ValueError("Given skycoord is not transformable to the ICRS")

# get location of observatory in ITRS coordinates at this Time

try:

itrs = location.get_itrs(obstime=self)

except Exception:

raise ValueError("Supplied location does not have a valid `get_itrs` method")

with solar_system_ephemeris.set(ephemeris):

if kind.lower() == 'heliocentric':

# convert to heliocentric coordinates, aligned with ICRS

cpos = itrs.transform_to(HCRS(obstime=self)).cartesian.xyz

else:

# first we need to convert to GCRS coordinates with the correct

# obstime, since ICRS coordinates have no frame time

gcrs_coo = itrs.transform_to(GCRS(obstime=self))

# convert to barycentric (BCRS) coordinates, aligned with ICRS

cpos = gcrs_coo.transform_to(ICRS()).cartesian.xyz

# get unit ICRS vector to star

spos = (skycoord.icrs.represent_as(UnitSphericalRepresentation).

represent_as(CartesianRepresentation).xyz)

# Move X,Y,Z to last dimension, to enable possible broadcasting below.

cpos = np.rollaxis(cpos, 0, cpos.ndim)

spos = np.rollaxis(spos, 0, spos.ndim)

# calculate light travel time correction

tcor_val = (spos * cpos).sum(axis=-1) / const.c

return TimeDelta(tcor_val, scale='tdb')

def sidereal_time(self, kind, longitude=None, model=None):

"""Calculate sidereal time.

Parameters

---------------

kind : str

``'mean'`` or ``'apparent'``, i.e., accounting for precession

only, or also for nutation.

longitude : `~astropy.units.Quantity`, `str`, or `None`; optional

The longitude on the Earth at which to compute the sidereal time.

Can be given as a `~astropy.units.Quantity` with angular units

(or an `~astropy.coordinates.Angle` or

`~astropy.coordinates.Longitude`), or as a name of an

observatory (currently, only ``'greenwich'`` is supported,

equivalent to 0 deg). If `None` (default), the ``lon`` attribute of

the Time object is used.

model : str or `None`; optional

Precession (and nutation) model to use. The available ones are:

- {0}: {1}

- {2}: {3}

If `None` (default), the last (most recent) one from the appropriate

list above is used.

Returns

-------

sidereal time : `~astropy.coordinates.Longitude`

Sidereal time as a quantity with units of hourangle

""" # docstring is formatted below

from ..coordinates import Longitude

if kind.lower() not in SIDEREAL_TIME_MODELS.keys():

raise ValueError('The kind of sidereal time has to be {0}'.format(

' or '.join(sorted(SIDEREAL_TIME_MODELS.keys()))))

available_models = SIDEREAL_TIME_MODELS[kind.lower()]

if model is None:

model = sorted(available_models.keys())[-1]

else:

if model.upper() not in available_models:

raise ValueError(

'Model {0} not implemented for {1} sidereal time; '

'available models are {2}'

.format(model, kind, sorted(available_models.keys())))

if longitude is None:

if self.location is None:

raise ValueError('No longitude is given but the location for '

'the Time object is not set.')

longitude = self.location.lon

elif longitude == 'greenwich':

longitude = Longitude(0., u.degree,

wrap_angle=180.*u.degree)

else:

# sanity check on input

longitude = Longitude(longitude, u.degree,

wrap_angle=180.*u.degree)

gst = self._erfa_sidereal_time(available_models[model.upper()])

return Longitude(gst + longitude, u.hourangle)

if isinstance(sidereal_time.__doc__, str):

sidereal_time.__doc__ = sidereal_time.__doc__.format(

'apparent', sorted(SIDEREAL_TIME_MODELS['apparent'].keys()),

'mean', sorted(SIDEREAL_TIME_MODELS['mean'].keys()))

def _erfa_sidereal_time(self, model):

"""Calculate a sidereal time using a IAU precession/nutation model."""

from ..coordinates import Longitude

erfa_function = model['function']

erfa_parameters = [getattr(getattr(self, scale)._time, jd_part)

for scale in model['scales']

for jd_part in ('jd1', 'jd2_filled')]

sidereal_time = erfa_function(*erfa_parameters)

if self.masked:

sidereal_time[self.mask] = np.nan

return Longitude(sidereal_time, u.radian).to(u.hourangle)

def copy(self, format=None):

"""

Return a fully independent copy the Time object, optionally changing

the format.

If ``format`` is supplied then the time format of the returned Time

object will be set accordingly, otherwise it will be unchanged from the

original.

In this method a full copy of the internal time arrays will be made.

The internal time arrays are normally not changeable by the user so in

most cases the ``replicate()`` method should be used.

Parameters

----------

format : str, optional

Time format of the copy.

Returns

-------

tm : Time object

Copy of this object

"""

return self._apply('copy', format=format)

def replicate(self, format=None, copy=False):

"""

Return a replica of the Time object, optionally changing the format.

If ``format`` is supplied then the time format of the returned Time

object will be set accordingly, otherwise it will be unchanged from the

original.

If ``copy`` is set to `True` then a full copy of the internal time arrays

will be made. By default the replica will use a reference to the

original arrays when possible to save memory. The internal time arrays

are normally not changeable by the user so in most cases it should not

be necessary to set ``copy`` to `True`.

The convenience method copy() is available in which ``copy`` is `True`

by default.

Parameters

----------