;+
; NAME:
; BJD2UTC
; PURPOSE:
; Converts a BJD in Barycentric Dynamical Time Time (BJD_TDB) to a JD in
; Universal Coordinate Time (JD_UTC) with an accuracy of ~1 us.
;
; Since the ephemeris files on which the corrections are based use
; Terestial Time (TT), which we're trying to compute, we must
; iteratively call UTC2BJD to converge on the UTC that produces the
; input TDB. Iterates ~3 times.
;
; *** SEE UTC2BJD.PRO FOR IMPORTANT NOTES ON ACCURACY AND
; CLARIFICATION ON THE DIFFERENCE BETWEEN BJD AND TDB ***
;
; If you make use of this program, please cite our paper:
; http://adsabs.harvard.edu/abs/2010PASP..122..935E
;
; INPUTS:
; BJD_TDB - A scalar or array of BJDs (in TDB). Must be double
; precision.
; RA/DEC - A scalar specifying the Right Ascension and
; Declinatoin of the object, in decimal degrees. J2000
; is assumed unless /B1950 is set
;
; OPTIONAL INPUTS:
; TOL - The tolerance, in days. The iterative procedure will
; stop after the agreement is better than this.
; Default = 1d-11 (1 us).
; SPACEOBS - A string input to HORIZONS specifying the space based
; observatory. Can be anything for which HORIZONS can
; generate an ephemeris. If set,
; EARTHOBS/LAT/LON/ELEVATION are ignored.
; http://www-int.stsci.edu/~sontag/spicedocs/req/naif_ids.html
; The name must be unique, or the telnet session will fail.
; NOTE: a file called SPACEOBS.bary.eph will be generated.
; EARTHOBS - A string input to OBSERVATORY.PRO that specifies an
; observatory. If set, LAT/LON/ELEVATION are ignored.
; LAT/LON - The latitude and longitude of the observatory, in
; decimal degrees. Positive longitude is *East*. If
; LAT/LON and OBSNAME are not specified, the geocenter
; will be assumed and the resultant accuracy will be
; ~20 ms. If OBSNAME is set, these are ignored.
; ELEVATION - The elevation of the observatory, in meters. If
; LAT/LON are not set, or if OBSNAME is set, this will
; be ignored. Sea level is assumed if not given.
; TARGET - A string input to HORIZONS specifying the Solar
; System target of observation. Can be anything for
; which HORIZONS can generate an ephemeris. If set,
; RA/DEC are ignored.
; The name must be unique, or the telnet session will fail.
; NOTE: a file called TARGET.bary.eph will be generated.
; PATH - The path to the ephemeris files generated by
; HORIZONS. Current directory assumed if not specified.
; TBASE - A scalar or n_elements(JD) vector that is the
; baseline subtracted from the input JDs. For highest
; precision, TBASE = floor(jd) is recommended
; BIPMFILE - The name of a file containing the BIPM-TAI
; offsets from ftp://tai.bipm.org/TFG/TT%28BIPM%29/
; Note that the previous year's file should be
; downloaded, and the .ext file should be concatenated
; at the end. As of 2010, this would be the TTBIPM.09
; and TTBIPM09.ext files. This is only necessary for
; 30 us precision.
; DISTANCE - The distance to the target, in Parsecs. If given,
; this will apply the second order term to the roemer
; delay which is accurate to at least 10^-14 seconds
; for any object outside the Solar System. The plane
; parallel approximation is accurate to at least 1 ms
; for any object outside the SS.
;
; OPTIONAL KEYWORDS:
; B1950 - If set, the input coordinates are assumed to be in equinox
; B1950 coordinates. Default is the J2000 equinox.
; TIME_DIFF - To return the difference in seconds instead (either
; to have the offset or for higher precision), use this
; keyword.
; TDB = jd_utc + utc2bjd(jd_utc,ra,dec,/time_diff)/86400.d0
; TT_IN - Set this keyword to use JD_TT as an input
; instead. This will skip the check for leap second
; updates and assume you have done this already
; USE_EOP - Use EOP data for high precision nutation angles. This
; is required for times more precise than 1 us. If set,
; you must have Craig Markwardt's EOPDATA, retrieve
; this file:
; ftp://maia.usno.navy.mil/ser7/finals.all
; and save it as $ASTRO_DATA/iers_final_a.dat
; This file must be kept up-to-date.
;
; OUTPUTS:
; JD_UTC - The JD in UTC for each BJD_TDB
;
; DEPENDENCIES:
; See utc2bjd.pro
;
; REVISION HISTORY:
; 2009/12/1: Written by Jason Eastman (OSU)
; 2013/08/26: Fixed bug with TBASE when using multiple observations
; separated by >~ 2 months (Thanks Eric Wu)
function bjd2utc, bjd_tdb, ra, dec, B1950=b1950, DISTANCE=distance,$
SPACEOBS=spaceobs, EARTHOBS=earthobs, TARGET=target, $
LAT=lat, LON=lon, ELEVATION=elevation,STEPSIZE=stepsize,$
TBASE=tbase, TIME_DIFF=time_diff,$
bipmfile=bipmfile,USE_EOP=USE_EOP,PATH=path, tol=tol
if n_elements(tol) eq 0 then tol = 1d-11 ;1 us
;; required for convergence (otherwise double precision isn't enough)
if n_elements(tbase) eq 0 then tbase = 0
base = floor(bjd_tdb[0])
tdbfloor = bjd_tdb - base
tbasetot = tbase + base
utc = tdbfloor - utc2bjd(tdbfloor, ra, dec, B1950=b1950, DISTANCE=distance,$
SPACEOBS=spaceobs, EARTHOBS=earthobs, TARGET=target, $
LAT=lat, LON=lon, ELEVATION=elevation,STEPSIZE=stepsize,$
bipmfile=bipmfile,USE_EOP=USE_EOP,PATH=path, tbase=tbasetot, $
/time_diff)/86400.d0
;; iterative process to find the UTC that corresponds to the TDB
;; completes in ~3 iterations
repeat begin
tdb_new = utc2bjd(utc,ra, dec, B1950=b1950, DISTANCE=distance,$
SPACEOBS=spaceobs, EARTHOBS=earthobs, TARGET=target, $
LAT=lat, LON=lon, ELEVATION=elevation,STEPSIZE=stepsize,$
bipmfile=bipmfile,USE_EOP=USE_EOP,PATH=path,tbase=tbasetot)
diff = tdbfloor-tdb_new
utc += diff
endrep until max(abs(diff)) lt tol
;; return the difference in seconds, if desired (high precision)
if keyword_set(time_diff) then begin
return, -utc2bjd(utc, ra, dec, B1950=b1950, DISTANCE=distance,$
SPACEOBS=spaceobs, EARTHOBS=earthobs, TARGET=target, $
LAT=lat, LON=lon, ELEVATION=elevation,STEPSIZE=stepsize,$
bipmfile=bipmfile,USE_EOP=USE_EOP,PATH=path, tbase=tbasetot, /time_diff)
endif
;; return UTC - TBASE (add my baseline back in)
return, utc + base
end