Trajectories

Trajectory utilities for microJAX.

class microjax.trajectory.EarthOrbitalParallaxProjector(eph: HeliocentricEphemeris, RA_deg, Dec_deg, tref, *, use_HJD: bool = True, light_time_iters: int = 5, au_c_day: float = 0.005775518331436995)

Bases: object

Map heliocentric Earth ephemeris to sky-plane offsets.

Applies optional light-time correction (HJD) and stores reference position and velocity at tref to separate annual parallax from linear motion.

tree_flatten()
classmethod tree_unflatten(aux, children)
class microjax.trajectory.HeliocentricEphemeris(t: Array, r: Array, v: Array)

Bases: object

Uniform heliocentric ephemeris.

t

Absolute times (JD TDB) on a uniform grid.

Type:

jax.Array, shape (N,)

r

Heliocentric position in AU.

Type:

jax.Array, shape (N, 3)

v

Heliocentric velocity in AU/day.

Type:

jax.Array, shape (N, 3)

Notes

t must be uniformly spaced for interp_uniform_linear to apply.

static from_horizons_vectors_table(table_np: ndarray) → HeliocentricEphemeris
tree_flatten()
classmethod tree_unflatten(aux, children)
microjax.trajectory.circular_orbital_motion_3d(t: float | Array, s0: float, alpha0: float, w1: float = 0.0, w2: float = 0.0, w3: float = 0.0, tref: float = 0.0) → Tuple[Array, Array, Array]

Evaluate circular 3D orbital motion (VBBinaryLensing parameterization).

This follows the same circular-orbit mapping used in VBBinaryLensing::BinaryLightCurveOrbital. The input velocity-like parameters are the standard VBBinaryLensing definitions:

  • w1 = (1/s) * ds/dt

  • w2 = d(alpha)/dt

  • w3 = (1/s) * ds_z/dt

where s is projected separation and s_z is the line-of-sight separation component.

Notes

For strict compatibility with the current VBBinaryLensing implementation, w3 is internally floored to a small positive value in the full 3D branch (w1^2 + w3^2 > 0), matching the original C++ guard.

Parameters:

  • t (float or Array) – Time(s) at which to evaluate the model.

  • s0 (float) – Projected binary separation at tref.

  • alpha0 (float) – Lens-axis angle at tref in radians.

  • w1 (float, optional) – Fractional projected-separation rate (1/s) ds/dt.

  • w2 (float, optional) – Position-angle rate d(alpha)/dt in radians per unit time.

  • w3 (float, optional) – Fractional line-of-sight-separation rate (1/s) ds_z/dt.

  • tref (float, optional) – Reference time at which s=s0 and alpha=alpha0.

Returns:

  • s_t (Array) – Projected separation at each time.

  • alpha_t (Array) – Projected lens-axis angle (radians).

  • sz_t (Array) – Line-of-sight separation component s_z at each time.

microjax.trajectory.circular_orbital_motion_3d_jit(t: float | Array, s0: float, alpha0: float, w1: float = 0.0, w2: float = 0.0, w3: float = 0.0, tref: float = 0.0) → Tuple[Array, Array, Array]

Evaluate circular 3D orbital motion (VBBinaryLensing parameterization).

This follows the same circular-orbit mapping used in VBBinaryLensing::BinaryLightCurveOrbital. The input velocity-like parameters are the standard VBBinaryLensing definitions:

  • w1 = (1/s) * ds/dt

  • w2 = d(alpha)/dt

  • w3 = (1/s) * ds_z/dt

where s is projected separation and s_z is the line-of-sight separation component.

Notes

For strict compatibility with the current VBBinaryLensing implementation, w3 is internally floored to a small positive value in the full 3D branch (w1^2 + w3^2 > 0), matching the original C++ guard.

Parameters:

  • t (float or Array) – Time(s) at which to evaluate the model.

  • s0 (float) – Projected binary separation at tref.

  • alpha0 (float) – Lens-axis angle at tref in radians.

  • w1 (float, optional) – Fractional projected-separation rate (1/s) ds/dt.

  • w2 (float, optional) – Position-angle rate d(alpha)/dt in radians per unit time.

  • w3 (float, optional) – Fractional line-of-sight-separation rate (1/s) ds_z/dt.

  • tref (float, optional) – Reference time at which s=s0 and alpha=alpha0.

Returns:

  • s_t (Array) – Projected separation at each time.

  • alpha_t (Array) – Projected lens-axis angle (radians).

  • sz_t (Array) – Line-of-sight separation component s_z at each time.

microjax.trajectory.circular_orbital_motion_3d_state(t: float | Array, w: complex | Array, s0: float, alpha0: float, w1: float = 0.0, w2: float = 0.0, w3: float = 0.0, tref: float = 0.0) → Tuple[Array, Array, Array, Array]

Evaluate circular 3D orbital motion and rotate trajectory to lens frame.

Parameters:

  • t (float or Array) – Time(s) corresponding to w.

  • w (complex or Array) – Source-plane coordinates in a fixed sky frame.

  • s0 (float) – Projected binary separation at tref.

  • alpha0 (float) – Lens-axis angle at tref (radians).

  • w1 (float, optional) – Circular 3D orbital-motion rates in VBBinaryLensing convention.

  • w2 (float, optional) – Circular 3D orbital-motion rates in VBBinaryLensing convention.

  • w3 (float, optional) – Circular 3D orbital-motion rates in VBBinaryLensing convention.

  • tref (float, optional) – Reference time where s=s0 and alpha=alpha0.

Returns:

  • w_lens (Array) – Coordinates rotated into the instantaneous lens frame.

  • s_t (Array) – Projected separation as a function of time.

  • alpha_t (Array) – Time-dependent projected lens-axis angle.

  • sz_t (Array) – Time-dependent line-of-sight separation component.

microjax.trajectory.circular_orbital_motion_3d_state_jit(t: float | Array, w: complex | Array, s0: float, alpha0: float, w1: float = 0.0, w2: float = 0.0, w3: float = 0.0, tref: float = 0.0) → Tuple[Array, Array, Array, Array]

Evaluate circular 3D orbital motion and rotate trajectory to lens frame.

Parameters:

  • t (float or Array) – Time(s) corresponding to w.

  • w (complex or Array) – Source-plane coordinates in a fixed sky frame.

  • s0 (float) – Projected binary separation at tref.

  • alpha0 (float) – Lens-axis angle at tref (radians).

  • w1 (float, optional) – Circular 3D orbital-motion rates in VBBinaryLensing convention.

  • w2 (float, optional) – Circular 3D orbital-motion rates in VBBinaryLensing convention.

  • w3 (float, optional) – Circular 3D orbital-motion rates in VBBinaryLensing convention.

  • tref (float, optional) – Reference time where s=s0 and alpha=alpha0.

Returns:

  • w_lens (Array) – Coordinates rotated into the instantaneous lens frame.

  • s_t (Array) – Projected separation as a function of time.

  • alpha_t (Array) – Time-dependent projected lens-axis angle.

  • sz_t (Array) – Time-dependent line-of-sight separation component.

microjax.trajectory.compute_parallax(t: float | Array, piEN: float, piEE: float, parallax_params: Tuple[Array, Array, Array, Array, Array, float, float, float, float]) → Tuple[Array, Array]

Keplerian annual parallax offsets at times t.

Parameters:

  • t (float or jax.Array) – Time(s) in JD-2450000 at which to evaluate the parallax signal.

  • piEN (float) – Parallax amplitude projected in the north direction.

  • piEE (float) – Parallax amplitude projected in the east direction.

  • parallax_params (tuple) – Output of set_parallax().

Returns:

  • dtn (jax.Array) – Offset to add to the dimensionless time coordinate(s) tau; shape (N,) matching the number of time samples.

  • dum (jax.Array) – Offset to add to the impact parameter coordinate(s) u; shape (N,).

Notes

The linear term from the local velocity (vne0) is subtracted so the returned offsets represent purely annual parallax about tref.

microjax.trajectory.compute_parallax_ephem(t: float | Array, piEN: float, piEE: float, projector: EarthOrbitalParallaxProjector, *, times_are_absolute: bool = False) → Tuple[Array, Array]

Ephemeris-based parallax offsets matching compute_parallax signature.

microjax.trajectory.earth_orbital_parallax_offsets(t, piEN, piEE, P: EarthOrbitalParallaxProjector)

Ephemeris-based Δtau and Δbeta offsets (JAX differentiable).

microjax.trajectory.earth_orbital_parallax_offsets_jit(t, piEN, piEE, P: EarthOrbitalParallaxProjector)

Ephemeris-based Δtau and Δbeta offsets (JAX differentiable).

microjax.trajectory.elliptic_orbital_motion_3d(t: float | Array, s0: float, alpha0: float, w1: float = 0.0, w2: float = 0.0, w3: float = 0.0, szs: float = 0.0, ar: float = 1.0, tref: float = 0.0, kepler_newton_iter: int = 10) → Tuple[Array, Array, Array]

Evaluate Keplerian 3D orbital motion (VBBinaryLensing compatible).

This matches the orbital geometry used by VBBinaryLensing::BinaryLightCurveKepler and returns projected separation, projected lens-axis angle, and line-of-sight separation.

Parameters:

  • t (float or Array) – Time(s) where the orbit is evaluated.

  • s0 (float) – Projected binary separation parameter used by VBBinaryLensing Kepler model.

  • alpha0 (float) – Baseline angle parameter used in VBBinaryLensing Kepler model.

  • w1 (float, optional) – Orbital-motion rates as defined by VBBinaryLensing.

  • w2 (float, optional) – Orbital-motion rates as defined by VBBinaryLensing.

  • w3 (float, optional) – Orbital-motion rates as defined by VBBinaryLensing.

  • szs (float, optional) – Line-of-sight separation ratio parameter used by VBBinaryLensing.

  • ar (float, optional) – Keplerian shape parameter used by VBBinaryLensing.

  • tref (float, optional) – Reference epoch equivalent to VBBinaryLensing t0_par.

  • kepler_newton_iter (int, optional) – Number of fixed Newton iterations for Kepler’s equation.

Returns:

  • s_t (Array) – Projected separation as a function of time.

  • alpha_t (Array) – Projected lens-axis angle as a function of time.

  • sz_t (Array) – Line-of-sight separation component as a function of time.

microjax.trajectory.elliptic_orbital_motion_3d_jit(t: float | Array, s0: float, alpha0: float, w1: float = 0.0, w2: float = 0.0, w3: float = 0.0, szs: float = 0.0, ar: float = 1.0, tref: float = 0.0, kepler_newton_iter: int = 10) → Tuple[Array, Array, Array]

Evaluate Keplerian 3D orbital motion (VBBinaryLensing compatible).

This matches the orbital geometry used by VBBinaryLensing::BinaryLightCurveKepler and returns projected separation, projected lens-axis angle, and line-of-sight separation.

Parameters:

  • t (float or Array) – Time(s) where the orbit is evaluated.

  • s0 (float) – Projected binary separation parameter used by VBBinaryLensing Kepler model.

  • alpha0 (float) – Baseline angle parameter used in VBBinaryLensing Kepler model.

  • w1 (float, optional) – Orbital-motion rates as defined by VBBinaryLensing.

  • w2 (float, optional) – Orbital-motion rates as defined by VBBinaryLensing.

  • w3 (float, optional) – Orbital-motion rates as defined by VBBinaryLensing.

  • szs (float, optional) – Line-of-sight separation ratio parameter used by VBBinaryLensing.

  • ar (float, optional) – Keplerian shape parameter used by VBBinaryLensing.

  • tref (float, optional) – Reference epoch equivalent to VBBinaryLensing t0_par.

  • kepler_newton_iter (int, optional) – Number of fixed Newton iterations for Kepler’s equation.

Returns:

  • s_t (Array) – Projected separation as a function of time.

  • alpha_t (Array) – Projected lens-axis angle as a function of time.

  • sz_t (Array) – Line-of-sight separation component as a function of time.

microjax.trajectory.elliptic_orbital_motion_3d_state(t: float | Array, w: complex | Array, s0: float, alpha0: float, w1: float = 0.0, w2: float = 0.0, w3: float = 0.0, szs: float = 0.0, ar: float = 1.0, tref: float = 0.0, kepler_newton_iter: int = 10) → Tuple[Array, Array, Array, Array]

Evaluate Keplerian 3D orbital motion and rotate trajectory to lens frame.

microjax.trajectory.elliptic_orbital_motion_3d_state_jit(t: float | Array, w: complex | Array, s0: float, alpha0: float, w1: float = 0.0, w2: float = 0.0, w3: float = 0.0, szs: float = 0.0, ar: float = 1.0, tref: float = 0.0, kepler_newton_iter: int = 10) → Tuple[Array, Array, Array, Array]

Evaluate Keplerian 3D orbital motion and rotate trajectory to lens frame.

microjax.trajectory.getpsi(phi: float | Array, ecc: float) → Array

Solve Kepler’s equation psi - e * sin(psi) = phi for psi.

Uses 5 fixed Newton iterations with an empirical initial guess; JAX differentiable for scalars or arrays.

Parameters:

  • phi (float or jax.Array) – Mean anomaly in radians. May be scalar or array-like.

  • ecc (float) – Orbital eccentricity, 0 <= ecc < 1.

Returns:

psi – Eccentric anomaly in radians, with the same broadcasted shape as phi.

Return type:

jax.Array

Notes

  • The initial guess is phi + sign(sin(phi)) * 0.85 * ecc which works well for moderate eccentricities without branching.

  • The iteration count is fixed to keep control-flow JIT friendly.

microjax.trajectory.linear_orbital_motion(t: float | Array, s0: float, alpha0: float, ds_dt: float = 0.0, dalpha_dt: float = 0.0, tref: float = 0.0) → Tuple[Array, Array]

Evaluate linear orbital-motion parameters at time t.

Parameters:

  • t (float or Array) – Time(s) at which to evaluate the model.

  • s0 (float) – Binary separation at reference time tref.

  • alpha0 (float) – Lens-axis angle at reference time tref (radians).

  • ds_dt (float, optional) – Time derivative of the separation.

  • dalpha_dt (float, optional) – Time derivative of the lens-axis angle (radians per unit time).

  • tref (float, optional) – Reference time where s = s0 and alpha = alpha0.

Returns:

  • s_t (Array) – Separation evaluated at t.

  • alpha_t (Array) – Lens-axis angle evaluated at t.

microjax.trajectory.linear_orbital_motion_jit(t: float | Array, s0: float, alpha0: float, ds_dt: float = 0.0, dalpha_dt: float = 0.0, tref: float = 0.0) → Tuple[Array, Array]

Evaluate linear orbital-motion parameters at time t.

Parameters:

  • t (float or Array) – Time(s) at which to evaluate the model.

  • s0 (float) – Binary separation at reference time tref.

  • alpha0 (float) – Lens-axis angle at reference time tref (radians).

  • ds_dt (float, optional) – Time derivative of the separation.

  • dalpha_dt (float, optional) – Time derivative of the lens-axis angle (radians per unit time).

  • tref (float, optional) – Reference time where s = s0 and alpha = alpha0.

Returns:

  • s_t (Array) – Separation evaluated at t.

  • alpha_t (Array) – Lens-axis angle evaluated at t.

microjax.trajectory.linear_orbital_motion_state(t: float | Array, w: complex | Array, s0: float, alpha0: float, ds_dt: float = 0.0, dalpha_dt: float = 0.0, tref: float = 0.0) → Tuple[Array, Array, Array]

Evaluate linear orbital motion and rotate a trajectory to lens frame.

Parameters:

  • t (float or Array) – Time(s) corresponding to w.

  • w (complex or Array) – Source-plane coordinates in a fixed sky frame.

  • s0 (float) – Binary separation at reference time tref.

  • alpha0 (float) – Lens-axis angle at reference time tref (radians).

  • ds_dt (float, optional) – Time derivative of separation.

  • dalpha_dt (float, optional) – Time derivative of lens-axis angle (radians per unit time).

  • tref (float, optional) – Reference time where s = s0 and alpha = alpha0.

Returns:

  • w_lens (Array) – Coordinates rotated into the instantaneous lens frame.

  • s_t (Array) – Time-dependent separation.

  • alpha_t (Array) – Time-dependent lens-axis angle.

microjax.trajectory.linear_orbital_motion_state_jit(t: float | Array, w: complex | Array, s0: float, alpha0: float, ds_dt: float = 0.0, dalpha_dt: float = 0.0, tref: float = 0.0) → Tuple[Array, Array, Array]

Evaluate linear orbital motion and rotate a trajectory to lens frame.

Parameters:

  • t (float or Array) – Time(s) corresponding to w.

  • w (complex or Array) – Source-plane coordinates in a fixed sky frame.

  • s0 (float) – Binary separation at reference time tref.

  • alpha0 (float) – Lens-axis angle at reference time tref (radians).

  • ds_dt (float, optional) – Time derivative of separation.

  • dalpha_dt (float, optional) – Time derivative of lens-axis angle (radians per unit time).

  • tref (float, optional) – Reference time where s = s0 and alpha = alpha0.

Returns:

  • w_lens (Array) – Coordinates rotated into the instantaneous lens frame.

  • s_t (Array) – Time-dependent separation.

  • alpha_t (Array) – Time-dependent lens-axis angle.

microjax.trajectory.load_builtin_earth_ephemeris() → HeliocentricEphemeris

Load the bundled JPL Horizons Earth ephemeris (uniform JD TDB grid).

microjax.trajectory.load_horizons_vectors_file(path: str) → ndarray

Parse a JPL Horizons cartesian-state table.

Returns ndarray columns [t_jdtdb, x, y, z, vx, vy, vz] with times in JD TDB days, positions in AU, velocities in AU/day. Lines outside the $$SOE … $$EOE block are skipped; calendar date and LT/RG/RR fields are ignored.

microjax.trajectory.peri_vernal(tref: float | Array) → Tuple[Array, Array]

Return the perihelion and vernal-equinox epochs nearest to tref.

This utility selects, from pre-tabulated epochs, the perihelion time and the vernal equinox time that are closest to the provided reference time.

The function accepts both absolute Julian Date (JD) and JD-2450000. If the input is larger than 2_450_000, it is internally shifted by subtracting 2_450_000 so it can be compared against the tables below, which are in JD-2450000.

Parameters:

tref (float or array-like) – Reference time(s) in JD or JD-2450000.

Returns:

  • tperi (float) – Perihelion time (JD-2450000), closest to tref.

  • tvernal (float) – Vernal equinox time (JD-2450000), closest to tref.

Notes

  • The returned values are selected by nearest-neighbor search in the provided tables and are not interpolated.

  • If tref is an array, the nearest entry is found based on the array broadcasting rules of JAX, and a single pair is returned as JAX scalars.

Examples

>>> tperi, tvernal = peri_vernal(2458000.0)
>>> float(tperi) > 0 and float(tvernal) > 0
True
microjax.trajectory.prepare_projection_basis(rotaxis_deg: float, psi_offset: float, RA: float, Dec: float) → Tuple[Array, Array, Array]

Build orbital→equatorial rotation and sky-plane bases.

Constructs the rotation matrix from orbital coordinates to ICRS and the orthonormal tangent-plane basis vectors north and east at (RA, Dec).

Parameters:

  • rotaxis_deg (float) – Obliquity of the ecliptic (tilt between equatorial and ecliptic planes) in degrees.

  • psi_offset (float) – Eccentric-anomaly angle between perihelion and the vernal equinox in radians. This aligns the orbital x-axis with the vernal direction.

  • RA (float) – Right ascension of the target in degrees (ICRS).

  • Dec (float) – Declination of the target in degrees (ICRS).

Returns:

  • R (jax.Array, shape (3, 3)) – Rotation matrix from orbital coordinates to equatorial coordinates.

  • north (jax.Array, shape (3,)) – Unit vector pointing to celestial north on the tangent plane at the target position.

  • east (jax.Array, shape (3,)) – Unit vector pointing to celestial east on the tangent plane.

Notes

  • Right-handed convention: east = z_eq × los; north = los × east.

  • east and north are orthonormal and perpendicular to the LOS.

microjax.trajectory.project_earth_position(t: float | Array, tperi: float, period: float, ecc: float, R: Array, north: Array, east: Array) → Array

Project Earth’s heliocentric position onto the target tangent plane.

Parameters:

  • t (float or jax.Array) – Observation time(s) in JD-2450000; scalar or 1D array.

  • tperi (float) – Time of perihelion in JD-2450000.

  • period (float) – Orbital period in days (sidereal year).

  • ecc (float) – Orbital eccentricity, 0 <= ecc < 1.

  • R (jax.Array, shape (3, 3)) – Rotation matrix from orbital to equatorial frame.

  • north (jax.Array, shape (3,)) – North unit vector on the tangent plane.

  • east (jax.Array, shape (3,)) – East unit vector on the tangent plane.

Returns:

q – Stacked projected coordinates [q_north, q_east]; N = len(t).

Return type:

jax.Array, shape (2, N)

Notes

  • Orbital x-axis points to perihelion; z-axis to ecliptic north.

  • Positions are rotated to ICRS via R then dotted with north/east.

microjax.trajectory.set_parallax(tref: float, tperi: float, tvernal: float, RA: float, Dec: float, rotaxis_deg: float = 23.44, ecc: float = 0.0167, period: float = 365.25636, dt: float = 0.1) → Tuple[Array, Array, Array, Array, Array, float, float, float, float]

Precompute Keplerian parallax quantities at a reference epoch.

If either tperi or tvernal is passed as 0, both values are automatically inferred using peri_vernal() at tref.

Parameters:

  • tref (float) – Reference time in JD-2450000 at which the linearization is anchored.

  • tperi (float) – Perihelion time in JD-2450000, or 0 to auto-select.

  • tvernal (float) – Vernal equinox time in JD-2450000, or 0 to auto-select.

  • RA (float) – Target right ascension in degrees (ICRS).

  • Dec (float) – Target declination in degrees (ICRS).

  • rotaxis_deg (float, optional) – Obliquity of the ecliptic in degrees. Default is 23.44.

  • ecc (float, optional) – Orbital eccentricity of Earth. Default is 0.0167.

  • period (float, optional) – Orbital period (sidereal year) in days. Default is 365.25636.

  • dt (float, optional) – Time step (days) used to compute the finite-difference velocity.

Returns:

parallax_params – Tuple (qne0, vne0, R, north, east, tref, tperi, period, ecc) where each element is: - qne0: jax.Array, shape (2,), Earth position [north, east] at tref. - vne0: jax.Array, shape (2,), approximate velocity d[q_north, q_east]/dt at tref. - R: jax.Array, shape (3, 3), rotation matrix orbital→equatorial. - north: jax.Array, shape (3,), north basis vector. - east: jax.Array, shape (3,), east basis vector. - tref: float, the reference epoch. - tperi: float, perihelion epoch used. - period: float, orbital period used. - ecc: float, eccentricity used.

Return type:

tuple

Notes

Symmetric finite differencing over ±dt provides the local velocity used to remove linear motion when forming residual parallax offsets.

microjax.trajectory.set_parallax_ephem(tref: float, RA: float, Dec: float, *, eph: HeliocentricEphemeris | None = None, use_HJD: bool = True, light_time_iters: int = 5) → EarthOrbitalParallaxProjector

Create an ephemeris-based projector anchored at tref (JD-2450000).

microjax.trajectory.to_rotating_lens_frame(w: complex | Array, alpha: float | Array) → Array

Rotate source-plane coordinates into the instantaneous lens frame.

Parameters:

  • w (complex or Array) – Source-plane coordinates in a fixed sky frame.

  • alpha (float or Array) – Lens-axis angle(s) in the same frame (radians).

Returns:

Rotated coordinates w * exp(-1j * alpha) aligned with the lens axis.

Return type:

Array