harv.models.parameterizations package

Model parameterizations subpackage.

Import alias: from harv.models import parameterizations as p.

class harv.models.parameterizations.AbstractParameterization

Bases: Module

Abstract base for model parameterizations.

Subclasses must implement params() (returning all parameter descriptors). The nonlinear_params() and linear_params() convenience methods are derived automatically.

Concrete parameterizations are also expected to override default_prior() with a type-narrow signature describing their required scale arguments.

__init__()
Return type:

None

static __new__(cls, *args, **kwargs)
Parameters:
Return type:

TypeVar(_ModuleT, bound= Module)

default_prior(**kwargs)

Build a HarvPrior with sensible defaults.

Each concrete parameterization overrides this with its own type-narrow signature for the required scale arguments (e.g. sigma_K0 for RV, sigma_a0 for astrometry). The base implementation raises NotImplementedError; default_prior is not declared @abstractmethod because subclass signatures legitimately differ.

Parameters:

**kwargs (Any) – Parameterization-specific keyword arguments (scale arguments and per-parameter prior overrides).

Returns:

A prior whose nonlinear_priors and linear_prior entries match the names declared by self.params().

Return type:

HarvPrior

linear_log_prior_correction(linear_map)

Optional log-prior correction added to the marginal log-likelihood.

Called with the conditional-mean linear-parameter values (unit-stripped, in the model’s observation units) after Gaussian marginalization. Returns None (no correction) by default.

Non-trivial only when the parameterization’s linear parameters are not the natural physical parameters — for example, Thiele-Innes constants (A, B, F, G) instead of the Campbell elements (a_0, ω, Ω, cos i). In that case the Jacobian of the change of variables must be applied to recover the correct posterior when priors are specified in the physical (Campbell) space.

Parameters:

linear_map (dict[str, Array]) – Conditional-mean values of the marginalized linear parameters, keyed by parameter name.

Returns:

Scalar log-correction to add to the marginal log-likelihood, or None if no correction is needed.

Return type:

Array or None

linear_params()

Return only the linear parameters.

Return type:

tuple[ParamInfo, ...]

nonlinear_params()

Return only the nonlinear parameters.

Return type:

tuple[ParamInfo, ...]

abstractmethod params()

All parameters declared by this parameterization (nonlinear first).

Return type:

tuple[ParamInfo, ...]

class harv.models.parameterizations.EcoswEsinwRV

Bases: AbstractParameterization

Alternative RV parameterization using e*cos(w) and e*sin(w).

Replaces the (eccentricity, arg_peri) pair with (ecosw, esinw) = (e*cos(omega), e*sin(omega)), which often has better sampling geometry for low eccentricities:

  • Nonlinear:

    • period - the orbital period

    • ecosw - the eccentricity times cosine of argument of periastron

    • esinw - the eccentricity times sine of argument of periastron

    • phase_peri - the phase at which the mean anomaly is zero (i.e. periastron passage), using a time system relative to the data’s reference time

  • Linear:

    • rv_semiamp - sometimes called “K”, the RV semi-amplitude

    • v_sys - the systemic velocity

Examples

>>> from harv.models.parameterizations.rv import EcoswEsinwRV
>>> p = EcoswEsinwRV()
>>> [pi.name for pi in p.params()]
['period', 'ecosw', 'esinw', 'phase_peri', 'rv_semiamp', 'v_sys']
__init__()
Return type:

None

static __new__(cls, *args, **kwargs)
Parameters:
Return type:

TypeVar(_ModuleT, bound= Module)

default_prior(*, period_min=None, period_max=None, sigma_K0=None, sigma_v0=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), **kwargs)

Build a HarvPrior with sensible defaults.

Nonlinear priors:

  • period: log-uniform on [period_min, period_max].

  • ecosw: Uniform(-1, 1).

  • esinw: Uniform(-1, 1).

  • phase_peri: Uniform(0, 1).

Linear priors are the same as StandardRV.default_prior().

Independent Uniform(-1, 1) priors on ecosw and esinw do not match the implicit prior under e ~ Beta(0.867, 3.03) with omega ~ Uniform(0, 2*pi). This is the simplest sensible default for this parameterization; for a matched prior, sample with StandardRV and convert.

Parameters:
Return type:

HarvPrior

design_matrix(sin_f, cos_f, nl_values)

Build (n_obs, 2) design matrix from ecosw/esinw.

Parameters:

  • sin_f (Array) – Sine of true anomaly (unit-stripped).

  • cos_f (Array) – Cosine of true anomaly (unit-stripped).

  • nl_values (dict[str, Any]) – Must contain "ecosw" and "esinw" (dimensionless scalars). The eccentricity and arg_peri are derived internally.

Return type:

Array

Returns:

Design matrix block, shape (n_obs, 2).

eccentricity(nl_values)

Return the orbital eccentricity derived from ecosw/esinw.

Parameters:

nl_values (dict[str, Any])

Return type:

Any

linear_log_prior_correction(linear_map)

Optional log-prior correction added to the marginal log-likelihood.

Called with the conditional-mean linear-parameter values (unit-stripped, in the model’s observation units) after Gaussian marginalization. Returns None (no correction) by default.

Non-trivial only when the parameterization’s linear parameters are not the natural physical parameters — for example, Thiele-Innes constants (A, B, F, G) instead of the Campbell elements (a_0, ω, Ω, cos i). In that case the Jacobian of the change of variables must be applied to recover the correct posterior when priors are specified in the physical (Campbell) space.

Parameters:

linear_map (dict[str, Array]) – Conditional-mean values of the marginalized linear parameters, keyed by parameter name.

Returns:

Scalar log-correction to add to the marginal log-likelihood, or None if no correction is needed.

Return type:

Array or None

linear_params()

Return only the linear parameters.

Return type:

tuple[ParamInfo, ...]

nonlinear_params()

Return only the nonlinear parameters.

Return type:

tuple[ParamInfo, ...]

params()

All parameters declared by this parameterization (nonlinear first).

Return type:

tuple[ParamInfo, ...]

strip_nl_for_design(nl_values)

Return nl_values with units stripped for design_matrix.

Parameters:

nl_values (dict[str, Any])

Return type:

dict[str, Any]

class harv.models.parameterizations.StandardGaiaAstrometry

Bases: AbstractParameterization

Standard Gaia astrometry parameterization.

The default harv parameterization for Gaia epoch astrometry modeling uses the following parameters:

  • Nonlinear:

    • period - orbital period

    • eccentricity - orbital eccentricity

    • phase_peri - phase at which the mean anomaly is zero (i.e. periastron passage), using a time system relative to the data’s reference time

    • arg_peri - argument of periastron

    • lon_asc_node - longitude of the ascending node

    • cos_i - cosine of the inclination

  • Linear:

    • ra0 - right ascension at the reference epoch

    • dec0 - declination at the reference epoch

    • pmra - proper motion in right ascension

    • pmdec - proper motion in declination

    • parallax - parallax

    • semi_major_axis - semi-major axis

The design matrix has shape (n_obs, 6) with columns [ra0, dec0, pmra, pmdec, parallax, a_orbit].

Parameters are defined in the Gaia local-plane coordinate (LPC) convention from Lindegren & Bastian (GAIA-C3-TN-LU-LL-061-08).

Examples

>>> from harv.models.parameterizations.gaia import StandardGaiaAstrometry
>>> p = StandardGaiaAstrometry()
>>> [pp.name for pp in p.nonlinear_params()]
['period', 'eccentricity', 'phase_peri', 'arg_peri', 'lon_asc_node', 'cos_i']
__init__()
Return type:

None

static __new__(cls, *args, **kwargs)
Parameters:
Return type:

TypeVar(_ModuleT, bound= Module)

default_prior(*, period_min=None, period_max=None, sigma_a0=None, sigma_parallax=None, sigma_pos=None, sigma_vtan=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), **kwargs)

Build a HarvPrior with sensible defaults.

Same defaults as harv.samplers.HarvPrior.default_gaia_astrometry() (and default_gaia_astrometry is a thin wrapper around this method).

Parameters:

  • period_min (Real[Quantity[PhysicalType('time')], ''] | None)

  • period_max (Real[Quantity[PhysicalType('time')], ''] | None)

  • sigma_a0 (Real[Quantity[PhysicalType('length')], ''] | None)

  • sigma_parallax (Real[Quantity[PhysicalType('angle')], ''] | None)

  • sigma_pos (Real[Quantity[PhysicalType('angle')], ''] | None)

  • sigma_vtan (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None)

  • P0 (Real[Quantity[PhysicalType('time')], ''])

  • kwargs (Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal])

Return type:

HarvPrior

design_matrix(sin_f, cos_f, dt, sin_psi, cos_psi, parallax_factor, nl_values)

Build (n_obs, 6) along-scan design matrix.

Columns: [ra0, dec0, pmra, pmdec, parallax, semi_major_axis].

Parameters:

  • sin_f (Array) – Sine of true anomaly (unit-stripped).

  • cos_f (Array) – Cosine of true anomaly (unit-stripped).

  • dt (Array) – Time elapsed since reference epoch (unit-stripped, in internal time unit, typically years).

  • sin_psi (Array) – Sine of scan angle.

  • cos_psi (Array) – Cosine of scan angle.

  • parallax_factor (Array) – Parallax factor (unit-stripped).

  • nl_values (dict[str, Any]) – Must contain "eccentricity", "arg_peri", "lon_asc_node", "cos_i" (unit-stripped scalars).

Return type:

Array

Returns:

Design matrix block, shape (n_obs, 6).

linear_log_prior_correction(linear_map)

Optional log-prior correction added to the marginal log-likelihood.

Called with the conditional-mean linear-parameter values (unit-stripped, in the model’s observation units) after Gaussian marginalization. Returns None (no correction) by default.

Non-trivial only when the parameterization’s linear parameters are not the natural physical parameters — for example, Thiele-Innes constants (A, B, F, G) instead of the Campbell elements (a_0, ω, Ω, cos i). In that case the Jacobian of the change of variables must be applied to recover the correct posterior when priors are specified in the physical (Campbell) space.

Parameters:

linear_map (dict[str, Array]) – Conditional-mean values of the marginalized linear parameters, keyed by parameter name.

Returns:

Scalar log-correction to add to the marginal log-likelihood, or None if no correction is needed.

Return type:

Array or None

linear_params()

Return only the linear parameters.

Return type:

tuple[ParamInfo, ...]

nonlinear_params()

Return only the nonlinear parameters.

Return type:

tuple[ParamInfo, ...]

params()

All parameters declared by this parameterization (nonlinear first).

Return type:

tuple[ParamInfo, ...]

sky_orbit(times, nl_values, linear_values)

Sky-plane orbital offsets (dRA, dDec) from the photocentre orbit.

Computes (dRA, dDec) = a_0 * (B*X + G*Y, A*X + F*Y) using the same kepler primitives (thiele_innes_ABFG(), mean_anomaly(), true_anomaly_from_mean()) that the design matrix uses. Returns bare JAX arrays in the same unit as the scalar linear_values["semi_major_axis"] (unit-agnostic by construction).

Parameters:
Return type:

tuple[Array, Array]

class harv.models.parameterizations.StandardRV

Bases: AbstractParameterization

Standard RV parameterization.

The default harv parameterization for radial velocity modeling uses the following Keplerian parameters:

  • Nonlinear:

    • period - orbital period

    • eccentricity - orbital eccentricity

    • phase_peri - phase at which the mean anomaly is zero (i.e. periastron passage), using a time system relative to the data’s reference time

    • arg_peri - argument of periastron

  • Linear:

    • rv_semiamp - sometimes called “K”, the RV semi-amplitude

    • v_sys - systemic velocity

The design matrix has shape (n_obs, 2) with columns [zd(t), 1] where zd(t) = cos(omega + f(t)) + e * cos(omega) is the RV shape function.

Examples

>>> from harv.models.parameterizations.rv import StandardRV
>>> p = StandardRV()
>>> [pp.name for pp in p.params()]
['period', 'eccentricity', 'phase_peri', 'arg_peri', 'rv_semiamp', 'v_sys']
__init__()
Return type:

None

static __new__(cls, *args, **kwargs)
Parameters:
Return type:

TypeVar(_ModuleT, bound= Module)

default_prior(*, period_min=None, period_max=None, sigma_K0=None, sigma_v0=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), **kwargs)

Build a HarvPrior with sensible defaults.

Same defaults as harv.samplers.HarvPrior.default_rv() (and default_rv is a thin wrapper around this method).

Parameters:

  • period_min (Real[Quantity[PhysicalType('time')], ''] | None) – Log-uniform period bounds.

  • period_max (Real[Quantity[PhysicalType('time')], ''] | None) – Log-uniform period bounds.

  • sigma_K0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – RV semi-amplitude scale at reference period P0.

  • sigma_v0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – Systemic-velocity prior scale.

  • P0 (Real[Quantity[PhysicalType('time')], '']) – Reference period for the period-dependent rv_semiamp prior.

  • **kwargs (Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal]) – Per-parameter prior overrides or extension priors.

Return type:

HarvPrior

design_matrix(sin_f, cos_f, nl_values)

Build (n_obs, 2) design matrix: columns [rv_shape, 1].

Parameters:

  • sin_f (Array) – Sine of true anomaly (unit-stripped).

  • cos_f (Array) – Cosine of true anomaly (unit-stripped).

  • nl_values (dict[str, Any]) – Must contain "eccentricity" and "arg_peri" (both unit-stripped scalars).

Return type:

Array

Returns:

Design matrix block, shape (n_obs, 2).

eccentricity(nl_values)

Return the orbital eccentricity from nonlinear values.

Parameters:

nl_values (dict[str, Any])

Return type:

Any

linear_log_prior_correction(linear_map)

Optional log-prior correction added to the marginal log-likelihood.

Called with the conditional-mean linear-parameter values (unit-stripped, in the model’s observation units) after Gaussian marginalization. Returns None (no correction) by default.

Non-trivial only when the parameterization’s linear parameters are not the natural physical parameters — for example, Thiele-Innes constants (A, B, F, G) instead of the Campbell elements (a_0, ω, Ω, cos i). In that case the Jacobian of the change of variables must be applied to recover the correct posterior when priors are specified in the physical (Campbell) space.

Parameters:

linear_map (dict[str, Array]) – Conditional-mean values of the marginalized linear parameters, keyed by parameter name.

Returns:

Scalar log-correction to add to the marginal log-likelihood, or None if no correction is needed.

Return type:

Array or None

linear_params()

Return only the linear parameters.

Return type:

tuple[ParamInfo, ...]

nonlinear_params()

Return only the nonlinear parameters.

Return type:

tuple[ParamInfo, ...]

params()

All parameters declared by this parameterization (nonlinear first).

Return type:

tuple[ParamInfo, ...]

strip_nl_for_design(nl_values)

Return nl_values with units stripped for design_matrix.

Parameters:

nl_values (dict[str, Any])

Return type:

dict[str, Any]

class harv.models.parameterizations.ThieleInnesGaiaAstrometry

Bases: AbstractParameterization

Thiele-Innes parameterization for Gaia epoch astrometry.

Replaces the four Campbell orientation parameters (arg_peri, lon_asc_node, cos_i, semi_major_axis) with the four Thiele-Innes constants (ti_A, ti_B, ti_F, ti_G), which enter the along-scan model linearly. This reduces the nonlinear parameter space from 6-D to 3-D.

The along-scan measurement model is:

\[w = (\alpha_{*,0} + \mu_\alpha \Delta t)\sin\psi + (\delta_0 + \mu_\delta \Delta t)\cos\psi + \varpi \cdot pf + (B X + G Y)\sin\psi + (A X + F Y)\cos\psi\]

  • Nonlinear: period, eccentricity, phase_peri (3 params)

  • Linear: ra0, dec0, pmra, pmdec, parallax, ti_A, ti_B, ti_F, ti_G (9 params)

A flat prior on the Thiele-Innes constants is not the same as a flat prior on the physical Campbell elements \((a_0, \omega, \Omega, \cos i)\), so a Jacobian correction is needed to recover the correct posterior. The zeroth-order correction (evaluated at the conditional-mean TI constants) multiplies the marginal likelihood by \((a_0 + \delta_a)^{-m}(\sin^2 i + \delta_{s})^{-1}\), where \(m = 3\) (uniform prior in \(a_0\)) or \(m = 4\) (log-uniform), and \(\delta_a\), \(\delta_s\) are numerical floors that prevent singularities near face-on orbits or zero semi-major axis.

The default is ``apply_jacobian_correction=False`` because the floors require sensible data-driven values that the bare constructor cannot infer. The recommended way to construct this class with the correction enabled is via from_data(), which sets a_floor = med(sigma_AL) / sqrt(N) automatically. Without the correction, the marginal likelihood can be dominated by spurious long-period configurations where the orbital signal is absorbed into proper motion – this is especially severe when the data baseline is shorter than the orbital period. For sub-orbit data baselines, prefer ``ThieleInnesGaiaAstrometry.from_data(data)`` (or the Standard parameterization).

Parameters:

  • a_floor (float or None, optional) – Floor on \(a_0\) (in the same angular units as the astrometric data, e.g. mas) used to regularize the Jacobian correction near zero semi-major axis. Required (non-None) when apply_jacobian_correction=True; must be None when it is False.

  • sin2i_floor (float or None, optional) – Floor on \(\sin^2 i\) for the Jacobian denominator. Falls back to 0.01 when None. Must be None when apply_jacobian_correction=False.

  • log_uniform_in_a (bool or None, optional) – If True, assume a log-uniform (Jeffreys) prior on \(a_0\) (uses \(m = 4\)). Falls back to False (uniform in \(a_0\), \(m = 3\)) when None. Must be None when apply_jacobian_correction=False.

  • apply_jacobian_correction (bool, optional) – Whether to apply the Jacobian correction. Default False. To enable with sensible floors, use from_data().

Raises:

ValueError – If apply_jacobian_correction=True but a_floor is None, or if apply_jacobian_correction=False but any of a_floor, sin2i_floor, or log_uniform_in_a is supplied.

Examples

>>> from harv.models.parameterizations.gaia import ThieleInnesGaiaAstrometry
>>> p = ThieleInnesGaiaAstrometry(a_floor=0.01)
>>> [pp.name for pp in p.nonlinear_params()]
['period', 'eccentricity', 'phase_peri']
>>> [pp.name for pp in p.linear_params()]
['ra0', 'dec0', 'pmra', 'pmdec', 'parallax', 'ti_A', 'ti_B', 'ti_F', 'ti_G']

Disable the Jacobian correction (no floor parameters needed):

>>> p = ThieleInnesGaiaAstrometry(apply_jacobian_correction=False)
>>> p.linear_log_prior_correction({}) is None
True
__init__(a_floor=None, sin2i_floor=None, log_uniform_in_a=None, apply_jacobian_correction=False)
Parameters:
Return type:

None

static __new__(cls, *args, **kwargs)
Parameters:
Return type:

TypeVar(_ModuleT, bound= Module)

a_floor: float | None = None
apply_jacobian_correction: bool = False
default_prior(*, period_min=None, period_max=None, sigma_a0=None, sigma_parallax=None, sigma_pos=None, sigma_vtan=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), **kwargs)

Build a HarvPrior with sensible defaults.

Nonlinear priors:

  • period: log-uniform on [period_min, period_max].

  • eccentricity: Kipping (2013) Beta prior.

  • phase_peri: Uniform(0, 1).

Linear priors:

The Jacobian correction (linear_log_prior_correction(), active when apply_jacobian_correction=True) restores the correct posterior under a flat-Campbell-elements prior.

Parameters:

  • period_min (Real[Quantity[PhysicalType('time')], ''] | None)

  • period_max (Real[Quantity[PhysicalType('time')], ''] | None)

  • sigma_a0 (Real[Quantity[PhysicalType('length')], ''] | None)

  • sigma_parallax (Real[Quantity[PhysicalType('angle')], ''] | None)

  • sigma_pos (Real[Quantity[PhysicalType('angle')], ''] | None)

  • sigma_vtan (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None)

  • P0 (Real[Quantity[PhysicalType('time')], ''])

  • kwargs (Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal])

Return type:

HarvPrior

design_matrix(sin_f, cos_f, dt, sin_psi, cos_psi, parallax_factor, nl_values)

Build (n_obs, 9) along-scan design matrix.

Columns: [ra0, dec0, pmra, pmdec, parallax, ti_A, ti_B, ti_F, ti_G].

Parameters:

  • sin_f (Array, shape (n_obs,)) – Sine of true anomaly (unit-stripped).

  • cos_f (Array, shape (n_obs,)) – Cosine of true anomaly (unit-stripped).

  • dt (Array, shape (n_obs,)) – Time elapsed since reference epoch (unit-stripped).

  • sin_psi (Array, shape (n_obs,)) – Sine of scan angle.

  • cos_psi (Array, shape (n_obs,)) – Cosine of scan angle.

  • parallax_factor (Array, shape (n_obs,)) – Parallax factor (unit-stripped).

  • nl_values (dict) – Must contain "eccentricity" (unit-stripped scalar).

Return type:

Array, shape (n_obs, 9)

classmethod from_data(data, sin2i_floor=None, log_uniform_in_a=None, *, apply_jacobian_correction=True)

Construct with a_floor = med(sigma_AL) / sqrt(N) from the data.

Parameters:

  • data (GaiaAstrometryData) – Along-scan epoch astrometry data.

  • sin2i_floor (float or None, optional) – Floor on \(\sin^2 i\). Falls back to 0.01 when None.

  • log_uniform_in_a (bool or None, optional) – Use log-uniform prior on \(a_0\). Falls back to False when None.

  • apply_jacobian_correction (bool, optional) – Whether to apply the Jacobian correction. Default True. When False, a_floor is not derived and sin2i_floor / log_uniform_in_a must be left as None.

Return type:

ThieleInnesGaiaAstrometry

Examples

>>> import jax.numpy as jnp
>>> from unxt import Q
>>> from harv.data import GaiaAstrometryData
>>> from harv.models.parameterizations.gaia import ThieleInnesGaiaAstrometry
>>> data = GaiaAstrometryData(
...     time=Q([0.0, 100.0, 200.0], "day"),
...     al_position=Q([0.1, -0.2, 0.05], "mas"),
...     al_position_err=Q([0.05, 0.06, 0.04], "mas"),
...     scan_angle=Q([0.5, 1.2, 2.8], "rad"),
...     parallax_factor=jnp.array([0.3, -0.1, 0.4]),
... )
>>> p = ThieleInnesGaiaAstrometry.from_data(data)
>>> p.a_floor > 0
True
linear_log_prior_correction(linear_map)

Zeroth-order Jacobian correction for the Thiele-Innes change of variables.

Returns None (no correction) when apply_jacobian_correction=False. Otherwise evaluates \(-m \ln(a_0 + \delta_a) - \ln(\sin^2 i + \delta_s)\) at the conditional-mean Thiele-Innes constants, where \(a_0\) and \(\sin^2 i\) are derived from the standard identities:

\[\begin{split}u &= \tfrac{1}{2}(A^2 + B^2 + F^2 + G^2) \\ v &= AG - BF \\ a_0 &= \sqrt{u + \sqrt{\max(u^2 - v^2, 0)}} \\ \sin^2 i &= 1 - v^2 / a_0^4\end{split}\]
Parameters:

linear_map (dict[str, Array]) – Conditional-mean values of the marginalized linear parameters. Must contain keys "ti_A", "ti_B", "ti_F", "ti_G" when the correction is enabled (ignored when it is disabled).

Returns:

Scalar log-correction, or None when the correction is disabled.

Return type:

Array or None

linear_params()

Return only the linear parameters.

Return type:

tuple[ParamInfo, ...]

log_uniform_in_a: bool | None = None
nonlinear_params()

Return only the nonlinear parameters.

Return type:

tuple[ParamInfo, ...]

params()

All parameters declared by this parameterization (nonlinear first).

Return type:

tuple[ParamInfo, ...]

sin2i_floor: float | None = None
sky_orbit(times, nl_values, linear_values)

Sky-plane orbital offsets (dRA, dDec) from the TI constants.

Mirrors the design-matrix construction (dRA = ti_B * X + ti_G * Y, dDec = ti_A * X + ti_F * Y) at arbitrary times. Returns bare JAX arrays in the same unit as the scalar TI constants in linear_values.

Parameters:
Return type:

tuple[Array, Array]

Submodules

harv.models.parameterizations.gaia module

Parameterizations for Gaia epoch-astrometry models.

A parameterization is an eqx.Module subclass that declares the names, units, and roles (linear / nonlinear) of parameters and knows how to build the corresponding design matrix.

final class harv.models.parameterizations.gaia.StandardGaiaAstrometry

Bases: AbstractParameterization

Standard Gaia astrometry parameterization.

The default harv parameterization for Gaia epoch astrometry modeling uses the following parameters:

  • Nonlinear:

    • period - orbital period

    • eccentricity - orbital eccentricity

    • phase_peri - phase at which the mean anomaly is zero (i.e. periastron passage), using a time system relative to the data’s reference time

    • arg_peri - argument of periastron

    • lon_asc_node - longitude of the ascending node

    • cos_i - cosine of the inclination

  • Linear:

    • ra0 - right ascension at the reference epoch

    • dec0 - declination at the reference epoch

    • pmra - proper motion in right ascension

    • pmdec - proper motion in declination

    • parallax - parallax

    • semi_major_axis - semi-major axis

The design matrix has shape (n_obs, 6) with columns [ra0, dec0, pmra, pmdec, parallax, a_orbit].

Parameters are defined in the Gaia local-plane coordinate (LPC) convention from Lindegren & Bastian (GAIA-C3-TN-LU-LL-061-08).

Examples

>>> from harv.models.parameterizations.gaia import StandardGaiaAstrometry
>>> p = StandardGaiaAstrometry()
>>> [pp.name for pp in p.nonlinear_params()]
['period', 'eccentricity', 'phase_peri', 'arg_peri', 'lon_asc_node', 'cos_i']
params()

All parameters declared by this parameterization (nonlinear first).

Return type:

tuple[ParamInfo, ...]

design_matrix(sin_f, cos_f, dt, sin_psi, cos_psi, parallax_factor, nl_values)

Build (n_obs, 6) along-scan design matrix.

Columns: [ra0, dec0, pmra, pmdec, parallax, semi_major_axis].

Parameters:

  • sin_f (Array) – Sine of true anomaly (unit-stripped).

  • cos_f (Array) – Cosine of true anomaly (unit-stripped).

  • dt (Array) – Time elapsed since reference epoch (unit-stripped, in internal time unit, typically years).

  • sin_psi (Array) – Sine of scan angle.

  • cos_psi (Array) – Cosine of scan angle.

  • parallax_factor (Array) – Parallax factor (unit-stripped).

  • nl_values (dict[str, Any]) – Must contain "eccentricity", "arg_peri", "lon_asc_node", "cos_i" (unit-stripped scalars).

Return type:

Array

Returns:

Design matrix block, shape (n_obs, 6).

sky_orbit(times, nl_values, linear_values)

Sky-plane orbital offsets (dRA, dDec) from the photocentre orbit.

Computes (dRA, dDec) = a_0 * (B*X + G*Y, A*X + F*Y) using the same kepler primitives (thiele_innes_ABFG(), mean_anomaly(), true_anomaly_from_mean()) that the design matrix uses. Returns bare JAX arrays in the same unit as the scalar linear_values["semi_major_axis"] (unit-agnostic by construction).

Parameters:
Return type:

tuple[Array, Array]

default_prior(*, period_min=None, period_max=None, sigma_a0=None, sigma_parallax=None, sigma_pos=None, sigma_vtan=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), **kwargs)

Build a HarvPrior with sensible defaults.

Same defaults as harv.samplers.HarvPrior.default_gaia_astrometry() (and default_gaia_astrometry is a thin wrapper around this method).

Parameters:

  • period_min (Real[Quantity[PhysicalType('time')], ''] | None)

  • period_max (Real[Quantity[PhysicalType('time')], ''] | None)

  • sigma_a0 (Real[Quantity[PhysicalType('length')], ''] | None)

  • sigma_parallax (Real[Quantity[PhysicalType('angle')], ''] | None)

  • sigma_pos (Real[Quantity[PhysicalType('angle')], ''] | None)

  • sigma_vtan (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None)

  • P0 (Real[Quantity[PhysicalType('time')], ''])

  • kwargs (Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal])

Return type:

HarvPrior

__init__()
Return type:

None

static __new__(cls, *args, **kwargs)
Parameters:
Return type:

TypeVar(_ModuleT, bound= Module)

linear_log_prior_correction(linear_map)

Optional log-prior correction added to the marginal log-likelihood.

Called with the conditional-mean linear-parameter values (unit-stripped, in the model’s observation units) after Gaussian marginalization. Returns None (no correction) by default.

Non-trivial only when the parameterization’s linear parameters are not the natural physical parameters — for example, Thiele-Innes constants (A, B, F, G) instead of the Campbell elements (a_0, ω, Ω, cos i). In that case the Jacobian of the change of variables must be applied to recover the correct posterior when priors are specified in the physical (Campbell) space.

Parameters:

linear_map (dict[str, Array]) – Conditional-mean values of the marginalized linear parameters, keyed by parameter name.

Returns:

Scalar log-correction to add to the marginal log-likelihood, or None if no correction is needed.

Return type:

Array or None

linear_params()

Return only the linear parameters.

Return type:

tuple[ParamInfo, ...]

nonlinear_params()

Return only the nonlinear parameters.

Return type:

tuple[ParamInfo, ...]

final class harv.models.parameterizations.gaia.ThieleInnesGaiaAstrometry

Bases: AbstractParameterization

Thiele-Innes parameterization for Gaia epoch astrometry.

Replaces the four Campbell orientation parameters (arg_peri, lon_asc_node, cos_i, semi_major_axis) with the four Thiele-Innes constants (ti_A, ti_B, ti_F, ti_G), which enter the along-scan model linearly. This reduces the nonlinear parameter space from 6-D to 3-D.

The along-scan measurement model is:

\[w = (\alpha_{*,0} + \mu_\alpha \Delta t)\sin\psi + (\delta_0 + \mu_\delta \Delta t)\cos\psi + \varpi \cdot pf + (B X + G Y)\sin\psi + (A X + F Y)\cos\psi\]

  • Nonlinear: period, eccentricity, phase_peri (3 params)

  • Linear: ra0, dec0, pmra, pmdec, parallax, ti_A, ti_B, ti_F, ti_G (9 params)

A flat prior on the Thiele-Innes constants is not the same as a flat prior on the physical Campbell elements \((a_0, \omega, \Omega, \cos i)\), so a Jacobian correction is needed to recover the correct posterior. The zeroth-order correction (evaluated at the conditional-mean TI constants) multiplies the marginal likelihood by \((a_0 + \delta_a)^{-m}(\sin^2 i + \delta_{s})^{-1}\), where \(m = 3\) (uniform prior in \(a_0\)) or \(m = 4\) (log-uniform), and \(\delta_a\), \(\delta_s\) are numerical floors that prevent singularities near face-on orbits or zero semi-major axis.

The default is ``apply_jacobian_correction=False`` because the floors require sensible data-driven values that the bare constructor cannot infer. The recommended way to construct this class with the correction enabled is via from_data(), which sets a_floor = med(sigma_AL) / sqrt(N) automatically. Without the correction, the marginal likelihood can be dominated by spurious long-period configurations where the orbital signal is absorbed into proper motion – this is especially severe when the data baseline is shorter than the orbital period. For sub-orbit data baselines, prefer ``ThieleInnesGaiaAstrometry.from_data(data)`` (or the Standard parameterization).

Parameters:

  • a_floor (float or None, optional) – Floor on \(a_0\) (in the same angular units as the astrometric data, e.g. mas) used to regularize the Jacobian correction near zero semi-major axis. Required (non-None) when apply_jacobian_correction=True; must be None when it is False.

  • sin2i_floor (float or None, optional) – Floor on \(\sin^2 i\) for the Jacobian denominator. Falls back to 0.01 when None. Must be None when apply_jacobian_correction=False.

  • log_uniform_in_a (bool or None, optional) – If True, assume a log-uniform (Jeffreys) prior on \(a_0\) (uses \(m = 4\)). Falls back to False (uniform in \(a_0\), \(m = 3\)) when None. Must be None when apply_jacobian_correction=False.

  • apply_jacobian_correction (bool, optional) – Whether to apply the Jacobian correction. Default False. To enable with sensible floors, use from_data().

Raises:

ValueError – If apply_jacobian_correction=True but a_floor is None, or if apply_jacobian_correction=False but any of a_floor, sin2i_floor, or log_uniform_in_a is supplied.

Examples

>>> from harv.models.parameterizations.gaia import ThieleInnesGaiaAstrometry
>>> p = ThieleInnesGaiaAstrometry(a_floor=0.01)
>>> [pp.name for pp in p.nonlinear_params()]
['period', 'eccentricity', 'phase_peri']
>>> [pp.name for pp in p.linear_params()]
['ra0', 'dec0', 'pmra', 'pmdec', 'parallax', 'ti_A', 'ti_B', 'ti_F', 'ti_G']

Disable the Jacobian correction (no floor parameters needed):

>>> p = ThieleInnesGaiaAstrometry(apply_jacobian_correction=False)
>>> p.linear_log_prior_correction({}) is None
True
a_floor: float | None = None
sin2i_floor: float | None = None
log_uniform_in_a: bool | None = None
apply_jacobian_correction: bool = False
classmethod from_data(data, sin2i_floor=None, log_uniform_in_a=None, *, apply_jacobian_correction=True)

Construct with a_floor = med(sigma_AL) / sqrt(N) from the data.

Parameters:

  • data (GaiaAstrometryData) – Along-scan epoch astrometry data.

  • sin2i_floor (float or None, optional) – Floor on \(\sin^2 i\). Falls back to 0.01 when None.

  • log_uniform_in_a (bool or None, optional) – Use log-uniform prior on \(a_0\). Falls back to False when None.

  • apply_jacobian_correction (bool, optional) – Whether to apply the Jacobian correction. Default True. When False, a_floor is not derived and sin2i_floor / log_uniform_in_a must be left as None.

Return type:

ThieleInnesGaiaAstrometry

Examples

>>> import jax.numpy as jnp
>>> from unxt import Q
>>> from harv.data import GaiaAstrometryData
>>> from harv.models.parameterizations.gaia import ThieleInnesGaiaAstrometry
>>> data = GaiaAstrometryData(
...     time=Q([0.0, 100.0, 200.0], "day"),
...     al_position=Q([0.1, -0.2, 0.05], "mas"),
...     al_position_err=Q([0.05, 0.06, 0.04], "mas"),
...     scan_angle=Q([0.5, 1.2, 2.8], "rad"),
...     parallax_factor=jnp.array([0.3, -0.1, 0.4]),
... )
>>> p = ThieleInnesGaiaAstrometry.from_data(data)
>>> p.a_floor > 0
True
params()

All parameters declared by this parameterization (nonlinear first).

Return type:

tuple[ParamInfo, ...]

design_matrix(sin_f, cos_f, dt, sin_psi, cos_psi, parallax_factor, nl_values)

Build (n_obs, 9) along-scan design matrix.

Columns: [ra0, dec0, pmra, pmdec, parallax, ti_A, ti_B, ti_F, ti_G].

Parameters:

  • sin_f (Array, shape (n_obs,)) – Sine of true anomaly (unit-stripped).

  • cos_f (Array, shape (n_obs,)) – Cosine of true anomaly (unit-stripped).

  • dt (Array, shape (n_obs,)) – Time elapsed since reference epoch (unit-stripped).

  • sin_psi (Array, shape (n_obs,)) – Sine of scan angle.

  • cos_psi (Array, shape (n_obs,)) – Cosine of scan angle.

  • parallax_factor (Array, shape (n_obs,)) – Parallax factor (unit-stripped).

  • nl_values (dict) – Must contain "eccentricity" (unit-stripped scalar).

Return type:

Array, shape (n_obs, 9)

sky_orbit(times, nl_values, linear_values)

Sky-plane orbital offsets (dRA, dDec) from the TI constants.

Mirrors the design-matrix construction (dRA = ti_B * X + ti_G * Y, dDec = ti_A * X + ti_F * Y) at arbitrary times. Returns bare JAX arrays in the same unit as the scalar TI constants in linear_values.

Parameters:
Return type:

tuple[Array, Array]

default_prior(*, period_min=None, period_max=None, sigma_a0=None, sigma_parallax=None, sigma_pos=None, sigma_vtan=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), **kwargs)

Build a HarvPrior with sensible defaults.

Nonlinear priors:

  • period: log-uniform on [period_min, period_max].

  • eccentricity: Kipping (2013) Beta prior.

  • phase_peri: Uniform(0, 1).

Linear priors:

The Jacobian correction (linear_log_prior_correction(), active when apply_jacobian_correction=True) restores the correct posterior under a flat-Campbell-elements prior.

Parameters:

  • period_min (Real[Quantity[PhysicalType('time')], ''] | None)

  • period_max (Real[Quantity[PhysicalType('time')], ''] | None)

  • sigma_a0 (Real[Quantity[PhysicalType('length')], ''] | None)

  • sigma_parallax (Real[Quantity[PhysicalType('angle')], ''] | None)

  • sigma_pos (Real[Quantity[PhysicalType('angle')], ''] | None)

  • sigma_vtan (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None)

  • P0 (Real[Quantity[PhysicalType('time')], ''])

  • kwargs (Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal])

Return type:

HarvPrior

linear_log_prior_correction(linear_map)

Zeroth-order Jacobian correction for the Thiele-Innes change of variables.

Returns None (no correction) when apply_jacobian_correction=False. Otherwise evaluates \(-m \ln(a_0 + \delta_a) - \ln(\sin^2 i + \delta_s)\) at the conditional-mean Thiele-Innes constants, where \(a_0\) and \(\sin^2 i\) are derived from the standard identities:

\[\begin{split}u &= \tfrac{1}{2}(A^2 + B^2 + F^2 + G^2) \\ v &= AG - BF \\ a_0 &= \sqrt{u + \sqrt{\max(u^2 - v^2, 0)}} \\ \sin^2 i &= 1 - v^2 / a_0^4\end{split}\]
Parameters:

linear_map (dict[str, Array]) – Conditional-mean values of the marginalized linear parameters. Must contain keys "ti_A", "ti_B", "ti_F", "ti_G" when the correction is enabled (ignored when it is disabled).

Returns:

Scalar log-correction, or None when the correction is disabled.

Return type:

Array or None

__init__(a_floor=None, sin2i_floor=None, log_uniform_in_a=None, apply_jacobian_correction=False)
Parameters:
Return type:

None

static __new__(cls, *args, **kwargs)
Parameters:
Return type:

TypeVar(_ModuleT, bound= Module)

linear_params()

Return only the linear parameters.

Return type:

tuple[ParamInfo, ...]

nonlinear_params()

Return only the nonlinear parameters.

Return type:

tuple[ParamInfo, ...]

harv.models.parameterizations.rv module

Parameterizations for radial-velocity (RV) models.

A parameterization is an eqx.Module subclass that declares:

  • The names, units, and roles (linear/nonlinear) of parameters.

  • How to build the design matrix from data and nonlinear parameter values.

Multiple parameterizations exist for the same physical observable when users want alternative coordinate choices (e.g. (K, omega) vs (e*cos(omega), e*sin(omega))).

final class harv.models.parameterizations.rv.EcoswEsinwRV

Bases: AbstractParameterization

Alternative RV parameterization using e*cos(w) and e*sin(w).

Replaces the (eccentricity, arg_peri) pair with (ecosw, esinw) = (e*cos(omega), e*sin(omega)), which often has better sampling geometry for low eccentricities:

  • Nonlinear:

    • period - the orbital period

    • ecosw - the eccentricity times cosine of argument of periastron

    • esinw - the eccentricity times sine of argument of periastron

    • phase_peri - the phase at which the mean anomaly is zero (i.e. periastron passage), using a time system relative to the data’s reference time

  • Linear:

    • rv_semiamp - sometimes called “K”, the RV semi-amplitude

    • v_sys - the systemic velocity

Examples

>>> from harv.models.parameterizations.rv import EcoswEsinwRV
>>> p = EcoswEsinwRV()
>>> [pi.name for pi in p.params()]
['period', 'ecosw', 'esinw', 'phase_peri', 'rv_semiamp', 'v_sys']
params()

All parameters declared by this parameterization (nonlinear first).

Return type:

tuple[ParamInfo, ...]

eccentricity(nl_values)

Return the orbital eccentricity derived from ecosw/esinw.

Parameters:

nl_values (dict[str, Any])

Return type:

Any

strip_nl_for_design(nl_values)

Return nl_values with units stripped for design_matrix.

Parameters:

nl_values (dict[str, Any])

Return type:

dict[str, Any]

design_matrix(sin_f, cos_f, nl_values)

Build (n_obs, 2) design matrix from ecosw/esinw.

Parameters:

  • sin_f (Array) – Sine of true anomaly (unit-stripped).

  • cos_f (Array) – Cosine of true anomaly (unit-stripped).

  • nl_values (dict[str, Any]) – Must contain "ecosw" and "esinw" (dimensionless scalars). The eccentricity and arg_peri are derived internally.

Return type:

Array

Returns:

Design matrix block, shape (n_obs, 2).

default_prior(*, period_min=None, period_max=None, sigma_K0=None, sigma_v0=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), **kwargs)

Build a HarvPrior with sensible defaults.

Nonlinear priors:

  • period: log-uniform on [period_min, period_max].

  • ecosw: Uniform(-1, 1).

  • esinw: Uniform(-1, 1).

  • phase_peri: Uniform(0, 1).

Linear priors are the same as StandardRV.default_prior().

Independent Uniform(-1, 1) priors on ecosw and esinw do not match the implicit prior under e ~ Beta(0.867, 3.03) with omega ~ Uniform(0, 2*pi). This is the simplest sensible default for this parameterization; for a matched prior, sample with StandardRV and convert.

Parameters:
Return type:

HarvPrior

__init__()
Return type:

None

static __new__(cls, *args, **kwargs)
Parameters:
Return type:

TypeVar(_ModuleT, bound= Module)

linear_log_prior_correction(linear_map)

Optional log-prior correction added to the marginal log-likelihood.

Called with the conditional-mean linear-parameter values (unit-stripped, in the model’s observation units) after Gaussian marginalization. Returns None (no correction) by default.

Non-trivial only when the parameterization’s linear parameters are not the natural physical parameters — for example, Thiele-Innes constants (A, B, F, G) instead of the Campbell elements (a_0, ω, Ω, cos i). In that case the Jacobian of the change of variables must be applied to recover the correct posterior when priors are specified in the physical (Campbell) space.

Parameters:

linear_map (dict[str, Array]) – Conditional-mean values of the marginalized linear parameters, keyed by parameter name.

Returns:

Scalar log-correction to add to the marginal log-likelihood, or None if no correction is needed.

Return type:

Array or None

linear_params()

Return only the linear parameters.

Return type:

tuple[ParamInfo, ...]

nonlinear_params()

Return only the nonlinear parameters.

Return type:

tuple[ParamInfo, ...]

final class harv.models.parameterizations.rv.StandardRV

Bases: AbstractParameterization

Standard RV parameterization.

The default harv parameterization for radial velocity modeling uses the following Keplerian parameters:

  • Nonlinear:

    • period - orbital period

    • eccentricity - orbital eccentricity

    • phase_peri - phase at which the mean anomaly is zero (i.e. periastron passage), using a time system relative to the data’s reference time

    • arg_peri - argument of periastron

  • Linear:

    • rv_semiamp - sometimes called “K”, the RV semi-amplitude

    • v_sys - systemic velocity

The design matrix has shape (n_obs, 2) with columns [zd(t), 1] where zd(t) = cos(omega + f(t)) + e * cos(omega) is the RV shape function.

Examples

>>> from harv.models.parameterizations.rv import StandardRV
>>> p = StandardRV()
>>> [pp.name for pp in p.params()]
['period', 'eccentricity', 'phase_peri', 'arg_peri', 'rv_semiamp', 'v_sys']
params()

All parameters declared by this parameterization (nonlinear first).

Return type:

tuple[ParamInfo, ...]

eccentricity(nl_values)

Return the orbital eccentricity from nonlinear values.

Parameters:

nl_values (dict[str, Any])

Return type:

Any

strip_nl_for_design(nl_values)

Return nl_values with units stripped for design_matrix.

Parameters:

nl_values (dict[str, Any])

Return type:

dict[str, Any]

design_matrix(sin_f, cos_f, nl_values)

Build (n_obs, 2) design matrix: columns [rv_shape, 1].

Parameters:

  • sin_f (Array) – Sine of true anomaly (unit-stripped).

  • cos_f (Array) – Cosine of true anomaly (unit-stripped).

  • nl_values (dict[str, Any]) – Must contain "eccentricity" and "arg_peri" (both unit-stripped scalars).

Return type:

Array

Returns:

Design matrix block, shape (n_obs, 2).

default_prior(*, period_min=None, period_max=None, sigma_K0=None, sigma_v0=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), **kwargs)

Build a HarvPrior with sensible defaults.

Same defaults as harv.samplers.HarvPrior.default_rv() (and default_rv is a thin wrapper around this method).

Parameters:

  • period_min (Real[Quantity[PhysicalType('time')], ''] | None) – Log-uniform period bounds.

  • period_max (Real[Quantity[PhysicalType('time')], ''] | None) – Log-uniform period bounds.

  • sigma_K0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – RV semi-amplitude scale at reference period P0.

  • sigma_v0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – Systemic-velocity prior scale.

  • P0 (Real[Quantity[PhysicalType('time')], '']) – Reference period for the period-dependent rv_semiamp prior.

  • **kwargs (Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal]) – Per-parameter prior overrides or extension priors.

Return type:

HarvPrior

__init__()
Return type:

None

static __new__(cls, *args, **kwargs)
Parameters:
Return type:

TypeVar(_ModuleT, bound= Module)

linear_log_prior_correction(linear_map)

Optional log-prior correction added to the marginal log-likelihood.

Called with the conditional-mean linear-parameter values (unit-stripped, in the model’s observation units) after Gaussian marginalization. Returns None (no correction) by default.

Non-trivial only when the parameterization’s linear parameters are not the natural physical parameters — for example, Thiele-Innes constants (A, B, F, G) instead of the Campbell elements (a_0, ω, Ω, cos i). In that case the Jacobian of the change of variables must be applied to recover the correct posterior when priors are specified in the physical (Campbell) space.

Parameters:

linear_map (dict[str, Array]) – Conditional-mean values of the marginalized linear parameters, keyed by parameter name.

Returns:

Scalar log-correction to add to the marginal log-likelihood, or None if no correction is needed.

Return type:

Array or None

linear_params()

Return only the linear parameters.

Return type:

tuple[ParamInfo, ...]

nonlinear_params()

Return only the nonlinear parameters.

Return type:

tuple[ParamInfo, ...]