Trajectories

Trajectory utilities for microJAX.

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

Compute annual parallax offsets at times t.

Produces the parallax-induced shifts to microlensing trajectory parameters: dtn should be added to the dimensionless time coordinate tau, and dum should be added to the impact parameter u (north–east frame).

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 mean linear motion around tref is removed using the precomputed velocity in parallax_params to isolate the purely annual parallax contribution.

microjax.trajectory.getpsi(phi: Union[float, Array], ecc: float) → Array

Solve Kepler’s equation for the eccentric anomaly psi.

The equation solved is psi - e * sin(psi) = phi using a fixed small number of Newton–Raphson iterations (5) with an empirical initial guess. This routine is differentiable under JAX and works with 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.peri_vernal(tref: Union[float, Array]) → Tuple[Array, Array]

Return perihelion and vernal-equinox times closest 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 rotation and on-sky projection bases.

Constructs the rotation matrix that maps the Sun–Earth orbital plane coordinates to the equatorial frame and returns the orthonormal basis vectors on the sky plane at the target direction: north and east.

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

The line-of-sight unit vector is derived from (RA, Dec). The returned east and north are orthonormal and orthogonal to the line of sight.

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

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

Computes the Sun-centered position of Earth in its (elliptical) orbit at time t using the eccentric anomaly and projects it onto the sky-plane basis defined by north and east.

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] where N is the number of time samples (N = 1 for scalar t).

Return type

jax.Array, shape (2, N)

Notes

The orbital coordinates are computed in the orbital frame with x-axis toward perihelion, then rotated to the equatorial frame and projected onto the tangent-plane basis.

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 parallax parameters at a reference epoch.

Precomputes quantities needed to evaluate the microlensing annual parallax signal around tref. This includes the on-sky Earth position at tref, a local linear velocity approximation (finite-difference over dt), and the projection/rotation bases.

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

The velocity is computed with a symmetric finite difference of width 2*dt to reduce truncation error and preserve JAX differentiability.