uk.ac.starlink.ast

Class TimeMap

java.lang.Object

uk.ac.starlink.ast.AstObject

uk.ac.starlink.ast.Mapping

uk.ac.starlink.ast.TimeMap

public class TimeMap
extends Mapping

Java interface to the AST TimeMap class - sequence of time coordinate conversions. A TimeMap is a specialised form of 1-dimensional Mapping which can be used to represent a sequence of conversions between standard time coordinate systems.

When a TimeMap is first created, it simply performs a unit (null) Mapping. Using the astTimeAdd function, a series of coordinate conversion steps may then be added. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of a set of building blocks.

For details of the individual coordinate conversions available, see the description of the astTimeAdd function.

Licence

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public Licence as published by the Free Software Foundation; either version 2 of the Licence, or (at your option) any later version.

This program is distributed in the hope that it will be useful,but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public Licence for more details.

You should have received a copy of the GNU General Public Licence along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street,Fifth Floor, Boston, MA 02110-1301, USA

See Also:

AST TimeMap

Nested Class Summary

Nested classes/interfaces inherited from class uk.ac.starlink.ast.Mapping

Mapping.Interpolator, Mapping.Spreader

Field Summary

Fields inherited from class uk.ac.starlink.ast.Mapping

LINEAR_INTERPOLATOR, LINEAR_SPREADER, NEAREST_INTERPOLATOR, NEAREST_SPREADER

Fields inherited from class uk.ac.starlink.ast.AstObject

AST__BAD, AST__TUNULL, pointer

Constructor Summary

Constructors

Constructor and Description
TimeMap() Create a TimeMap.
TimeMap(int flags) Create a TimeMap.

Method Summary

Modifier and Type	Method and Description
void	timeAdd(String cvt, double[] args) Add a time coordinate conversion to a TimeMap.

Methods inherited from class uk.ac.starlink.ast.Mapping

decompose, getInvert, getNin, getNout, getReport, getTranForward, getTranInverse, invert, linearApprox, mapBox, mapSplit, rate, rebin, rebinD, rebinF, rebinI, resample, resampleB, resampleD, resampleF, resampleI, resampleL, resampleS, setInvert, setReport, simplify, tran1, tran2, tranGrid, tranN, tranP

Methods inherited from class uk.ac.starlink.ast.AstObject

annul, clear, copy, delete, equals, finalize, getAstConstantI, getB, getC, getD, getF, getI, getID, getIdent, getL, getNobject, getObjSize, getRefCount, hashCode, isThreaded, reportVersions, sameObject, set, setB, setC, setD, setF, setI, setID, setIdent, setL, show, test, tune

Methods inherited from class java.lang.Object

clone, getClass, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

TimeMap

public TimeMap()

Create a TimeMap.

TimeMap

public TimeMap(int flags)

Create a TimeMap. This function creates a new TimeMap and optionally initialises its attributes.

A TimeMap is a specialised form of 1-dimensional Mapping which can be used to represent a sequence of conversions between standard time coordinate systems.

When a TimeMap is first created, it simply performs a unit (null) Mapping. Using the astTimeAdd function, a series of coordinate conversion steps may then be added. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of a set of building blocks.

For details of the individual coordinate conversions available, see the description of the astTimeAdd function.

Notes

- The nature and units of the coordinate values supplied for the first input (i.e. the time input) of a TimeMap must be appropriate to the first conversion step applied by the TimeMap. For instance, if the first conversion step is "MJDTOBEP" (Modified Julian Date to Besselian epoch) then the coordinate values for the first input should be date in units of days. Similarly, the nature and units of the coordinate values returned by a TimeMap will be determined by the last conversion step applied by the TimeMap.
- A null Object pointer (AST__NULL) will be returned if this function is invoked with the AST error status set, or if it should fail for any reason.

Parameters:

flags - This parameter is reserved for future use and should currently always be set to zero.

Throws:

AstException - if an error occurred in the AST library

Method Detail

timeAdd

public void timeAdd(String cvt,
                    double[] args)

Add a time coordinate conversion to a TimeMap. This function adds one of the standard time coordinate system conversions listed below to an existing TimeMap.

When a TimeMap is first created (using astTimeMap), it simply performs a unit (null) Mapping. By using astTimeAdd (repeatedly if necessary), one or more coordinate conversion steps may then be added, which the TimeMap will perform in sequence. This allows multi-step conversions between a variety of time coordinate systems to be assembled out of the building blocks provided by this class.

Normally, if a TimeMap's Invert attribute is zero (the default), then its forward transformation is performed by carrying out each of the individual coordinate conversions specified by astTimeAdd in the order given (i.e. with the most recently added conversion applied last).

This order is reversed if the TimeMap's Invert attribute is non-zero (or if the inverse transformation is requested by any other means) and each individual coordinate conversion is also replaced by its own inverse. This process inverts the overall effect of the TimeMap. In this case, the first conversion to be applied would be the inverse of the one most recently added.

Notes

- When assembling a multi-stage conversion, it can sometimes be difficult to determine the most economical conversion path. A solution to this is to include all the steps which are (logically) necessary, but then to use astSimplify to simplify the resulting TimeMap. The simplification process will eliminate any steps which turn out not to be needed.
- This function does not check to ensure that the sequence of coordinate conversions added to a TimeMap is physically meaningful.

Available Conversions

The following strings (which are case-insensitive) may be supplied via the "cvt" parameter to indicate which time coordinate conversion is to be added to the TimeMap. Where arguments are needed by the conversion, they are listed in parentheses. Values for these arguments should be given, via the "args" array, in the order indicated. Units and argument names are described at the end of the list of conversions, and "MJD" means Modified Julian Date.

- "MJDTOMJD" (MJDOFF1,MJDOFF2): Convert MJD from one offset to another.
- "MJDTOJD" (MJDOFF,JDOFF): Convert MJD to Julian Date.
- "JDTOMJD" (JDOFF,MJDOFF): Convert Julian Date to MJD.
- "MJDTOBEP" (MJDOFF,BEPOFF): Convert MJD to Besselian epoch.
- "BEPTOMJD" (BEPOFF,MJDOFF): Convert Besselian epoch to MJD.
- "MJDTOJEP" (MJDOFF,JEPOFF): Convert MJD to Julian epoch.
- "JEPTOMJD" (JEPOFF,MJDOFF): Convert Julian epoch to MJD.
- "TAITOUTC" (MJDOFF): Convert a TAI MJD to a UTC MJD.
- "UTCTOTAI" (MJDOFF): Convert a UTC MJD to a TAI MJD.
- "TAITOTT" (MJDOFF): Convert a TAI MJD to a TT MJD.
- "TTTOTAI" (MJDOFF): Convert a TT MJD to a TAI MJD.
- "TTTOTDB" (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TT MJD to a TDB MJD.
- "TDBTOTT" (MJDOFF, OBSLON, OBSLAT, OBSALT): Convert a TDB MJD to a TT MJD.
- "TTTOTCG" (MJDOFF): Convert a TT MJD to a TCG MJD.
- "TCGTOTT" (MJDOFF): Convert a TCG MJD to a TT MJD.
- "TDBTOTCB" (MJDOFF): Convert a TDB MJD to a TCB MJD.
- "TCBTOTDB" (MJDOFF): Convert a TCB MJD to a TDB MJD.
- "UTTOGMST" (MJDOFF): Convert a UT MJD to a GMST MJD.
- "GMSTTOUT" (MJDOFF): Convert a GMST MJD to a UT MJD.
- "GMSTTOLMST" (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD.
- "LMSTTOGMST" (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD.
- "LASTTOLMST" (MJDOFF, OBSLON, OBSLAT): Convert a GMST MJD to a LMST MJD.
- "LMSTTOLAST" (MJDOFF, OBSLON, OBSLAT): Convert a LMST MJD to a GMST MJD.
- "UTTOUTC" (DUT1): Convert a UT1 MJD to a UTC MJD.
- "UTCTOUT" (DUT1): Convert a UTC MJD to a UT1 MJD.
- "LTTOUTC" (LTOFF): Convert a Local Time MJD to a UTC MJD.
- "UTCTOLT" (LTOFF): Convert a UTC MJD to a Local Time MJD.

The units for the values processed by the above conversions are as follows:

- Julian epochs and offsets: Julian years
- Besselian epochs and offsets: Tropical years
- Modified Julian Dates and offsets: days
- Julian Dates and offsets: days

The arguments used in the above conversions are the zero-points used by the astTransform function. The axis values supplied and returned by astTransform are offsets away from these zero-points:

- MJDOFF: The zero-point being used with MJD values.
- JDOFF: The zero-point being used with Julian Date values.
- BEPOFF: The zero-point being used with Besselian epoch values.
- JEPOFF: The zero-point being used with Julian epoch values.
- OBSLON: Observer longitude in radians (+ve westwards).
- OBSLAT: Observer geodetic latitude (IAU 1975) in radians (+ve northwards).
- OBSALT: Observer geodetic altitude (IAU 1975) in metres.
- DUT1: The UT1-UTC value to use.
- LTOFF: The offset between Local Time and UTC (in hours, positive for time zones east of Greenwich).

Parameters:

cvt - Pointer to a null-terminated string which identifies the time coordinate conversion to be added to the TimeMap. See the "Available Conversions" section for details of those available.

args - An array containing argument values for the time coordinate conversion. The number of arguments required, and hence the number of array elements used, depends on the conversion specified (see the "Available Conversions" section). This array is ignored and a NULL pointer may be supplied if no arguments are needed.

Throws:

AstException - if an error occurred in the AST library