harv.models.priors package

Model priors subpackage.

class harv.models.priors.HarvPrior

Bases: Module

Prior distribution for rejection sampling of Keplerian orbits.

This class encapsulates the prior distributions for both nonlinear and linear parameters. It is agnostic to data type - the sampler determines which parameters are required based on the provided data.

We recommend using the “default” factory constructors (e.g. default_rv(), default_gaia_astrometry(), etc.), which set up sensible priors for common use cases.

Nonlinear parameterization:

Parameter names in nonlinear_priors must match the field names of the parameterization, for example, period, eccentricity, phase_peri, etc. These parameters are sampled explicitly.

See the options available in harv.models.parameterizations.

Default parameterizations:

Radial Velocity:

  • Nonlinear: period, eccentricity, phase_peri, arg_peri

  • Linear: rv_semiamp, v_sys

Astrometry:

  • Nonlinear: period, eccentricity, phase_peri, cos_i, arg_peri, lon_asc_node

  • Linear params: ra0, dec0, pmra, pmdec, parallax, semi_major_axis

Parameters:

  • nonlinear_priors (dict[str, Distribution | QuantityDistribution]) – Mapping from parameter name to its prior distribution (a bare dist.Distribution for dimensionless parameters, or a harv.distributions.QuantityDistribution wrapper for parameters with physical units).

  • linear_priors (dict[str, Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal]]) –

    Per-parameter priors for linear parameters. Each entry is classified:

    • dist.Normal or QD(Normal) – Gaussian, can be analytically marginalized.

    • LinearPriorCallable – called with nonlinear params to produce a Normal, can be marginalized.

    • dist.HalfNormal, dist.Delta, etc. – non-Gaussian, sampled explicitly alongside nonlinear params.

    When using default_rv() with offsets, the non-reference offset priors are automatically included as linear parameters.

  • extension_priors (dict[str, Distribution | QuantityDistribution]) – Priors for extension parameters declared via extra_params().

__init__(nonlinear_priors, linear_priors, extension_priors=<factory>)
Parameters:
Return type:

None

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

TypeVar(_ModuleT, bound= Module)

classmethod from_parameterization(parameterization, **kwargs)

Build a default prior for any supported parameterization.

Delegates to parameterization.default_prior(**kwargs). Each concrete parameterization declares its own required scale arguments (e.g. sigma_K0 for RV, sigma_a0 for astrometry).

Parameters:
Return type:

HarvPrior

Examples

>>> from unxt import Q
>>> from harv.models.parameterizations.rv import EcoswEsinwRV
>>> from harv.samplers import HarvPrior
>>> prior = HarvPrior.from_parameterization(
...     EcoswEsinwRV(),
...     period_min=Q(2.0, "day"),
...     period_max=Q(1000.0, "day"),
...     sigma_K0=Q(30.0, "km/s"),
...     sigma_v0=Q(50.0, "km/s"),
... )
>>> sorted(prior.nonlinear_priors.keys())
['ecosw', 'esinw', 'period', 'phase_peri']
sample_nonlinear(key, n_samples)

Sample nonlinear parameters from priors.

Parameters:

  • key (Array) – Random key for sampling.

  • n_samples (int) – Number of samples to draw.

Return type:

dict[str, Any]

Returns:

Dictionary mapping each parameter name to an array of shape (n_samples,). Values are bare JAX arrays regardless of whether the distribution is wrapped in QuantityDistribution.

Examples

>>> import jax
>>> from unxt import Q
>>> from harv.samplers import HarvPrior
>>> sorted(
...     HarvPrior.default_rv(
...         period_min=Q(2.0, "day"),
...         period_max=Q(1000.0, "day"),
...         sigma_K0=Q(30.0, "km/s"),
...         sigma_v0=Q(50.0, "km/s"),
...     ).sample_nonlinear(jax.random.key(0), 10).keys()
... )
['arg_peri', 'eccentricity', 'period', 'phase_peri']
>>> HarvPrior.default_rv(
...     period_min=Q(2.0, "day"),
...     period_max=Q(1000.0, "day"),
...     sigma_K0=Q(30.0, "km/s"),
...     sigma_v0=Q(50.0, "km/s"),
... ).sample_nonlinear(jax.random.key(0), 10)["period"].shape
(10,)
nonlinear_priors: dict[str, Distribution | QuantityDistribution]
linear_priors: dict[str, Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal]]
extension_priors: dict[str, Distribution | QuantityDistribution]
harv.models.priors.default_sb2_prior(*, period_min=None, period_max=None, sigma_K0=None, sigma_v0=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), component_names=('primary', 'secondary'), **kwargs)

Create default prior for SB2 (double-lined) radial velocity data.

SB2 is a joint composition of two StandardRV components, not a single parameterization, so this lives as a module-level factory rather than a classmethod on HarvPrior. It pairs naturally with harv.models.JointModel.for_sb2() (JointModel.for_sb2(prior=...)).

Both semi-amplitudes use the same period-dependent scaling as HarvPrior.default_rv(). The systemic velocity prior is a fixed Gaussian.

The default names for the two components are “primary” and “secondary”, which means the linear priors for the semi-amplitudes must be keyed as “primary.rv_semiamp” and “secondary.rv_semiamp”. You can customize the component names via the component_names argument, but the linear prior keys must always be {component_name}.rv_semiamp.

Parameters:

  • period_min (Real[Quantity[PhysicalType('time')], ''] | None) – Lower bound for the log-uniform period prior.

  • period_max (Real[Quantity[PhysicalType('time')], ''] | None) – Upper bound for the log-uniform period prior.

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

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

  • P0 (Real[Quantity[PhysicalType('time')], '']) – Reference period for the K prior scaling. Default: 1 yr.

  • component_names (tuple[str, str]) – Names of the two components. These are used to construct the linear prior keys for the semi-amplitudes (e.g. “primary.rv_semiamp” and “secondary.rv_semiamp”).

  • **kwargs (Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal]) – Override any default nonlinear or linear prior by name.

Returns:

Prior configured for SB2 RV data.

Return type:

HarvPrior

Examples

>>> from unxt import Q
>>> from harv.samplers import default_sb2_prior
>>> sorted(
...     default_sb2_prior(
...         period_min=Q(2.0, "day"),
...         period_max=Q(1000.0, "day"),
...         sigma_K0=Q(30.0, "km/s"),
...         sigma_v0=Q(50.0, "km/s"),
...     ).nonlinear_priors.keys()
... )
['arg_peri', 'eccentricity', 'period', 'phase_peri']
>>> sorted(
...     default_sb2_prior(
...         period_min=Q(2.0, "day"),
...         period_max=Q(1000.0, "day"),
...         sigma_K0=Q(30.0, "km/s"),
...         sigma_v0=Q(50.0, "km/s"),
...     ).linear_priors
... )
['primary.rv_semiamp', 'secondary.rv_semiamp', 'v_sys']
class harv.models.priors.ParallaxDependentProperMotionPrior

Bases: Module

Parallax-dependent proper-motion prior for astrometry.

The std dev of the Gaussian prior on proper motion scales with parallax so that the prior is fixed in transverse velocity rather than in angular proper motion:

\[\sigma_\mu(\varpi) = \sigma_{v,0}\;\varpi \;/\; (1\,\text{AU})\]

where \(\sigma_{v,0}\) is a velocity dispersion scale (e.g. km/s) and the division by 1 AU converts velocity x parallax to angular speed. Numerically, \(\sigma_{v,0}\) is first converted to AU/yr, and then \(\sigma_\mu = \sigma_{v,0}[\text{AU/yr}] \times \varpi\).

Parameters:

sigma_v0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], '']) – Transverse-velocity dispersion scale (e.g. km/s).

Notes

This class implements the LinearPriorCallable protocol and is the default linear_prior for pmra and pmdec returned by default_gaia_astrometry().

The params struct must have a .parallax field (Quantity with angular units). parallax is available because it is classified as an explicit (non-marginalized) linear parameter by default.

Examples

>>> from unxt import Q
>>> from harv.models.priors.custom_priors import ParallaxDependentProperMotionPrior
>>> prior = ParallaxDependentProperMotionPrior(sigma_v0=Q(50.0, "km/s"))
>>> prior.sigma_v0.unit
Unit("km / s")
__init__(sigma_v0)
Parameters:

sigma_v0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''])

Return type:

None

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

TypeVar(_ModuleT, bound= Module)

sigma_v0: Real[Quantity[PhysicalType({'speed', 'velocity'})], '']
class harv.models.priors.PeriodDependentSemiMajorAxisPrior

Bases: Module

Period- and parallax-dependent semi-major axis prior for astrometry.

The std dev of the Gaussian prior on the astrometric semi-major axis scales with orbital period and parallax so that it remains approximately constant in companion mass at fixed primary mass:

\[\sigma_a(P, \varpi) = \sigma_{a,0} \left(\frac{P}{P_0}\right)^{2/3} \varpi\]

where \(\sigma_{a,0}\) is in physical length units (e.g. AU) and \(\varpi\) is the parallax in mas. Since 1 AU at 1 mas parallax subtends 1 mas, the product gives the angular semi-major axis in mas.

Parameters:

  • sigma_a0 (Real[Quantity[PhysicalType('length')], '']) – Semi-major axis scale in physical units (e.g. AU) at the reference period P0. Converted to angular size via the parallax.

  • P0 (Real[Quantity[PhysicalType('time')], '']) – Reference period.

Notes

This class implements the LinearPriorCallable protocol and is the default linear_prior for semi_major_axis returned by default_gaia_astrometry().

The params struct must have .period, .eccentricity, and .parallax fields. parallax is available because it is classified as an explicit (non-marginalized) linear parameter by default.

Examples

>>> from unxt import Q
>>> from harv.models.priors.custom_priors import PeriodDependentSemiMajorAxisPrior
>>> prior = PeriodDependentSemiMajorAxisPrior(
...     sigma_a0=Q(5.0, "AU"), P0=Q(1.0, "yr"),
... )
>>> prior.sigma_a0.unit
Unit("AU")
__init__(sigma_a0, P0)
Parameters:

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

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

Return type:

None

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

TypeVar(_ModuleT, bound= Module)

sigma_a0: Real[Quantity[PhysicalType('length')], '']
P0: Real[Quantity[PhysicalType('time')], '']

Submodules

harv.models.priors.custom_priors module

Custom prior distributions and callables that produce numpyro distributions.

class harv.models.priors.custom_priors.ParallaxDependentProperMotionPrior

Bases: Module

Parallax-dependent proper-motion prior for astrometry.

The std dev of the Gaussian prior on proper motion scales with parallax so that the prior is fixed in transverse velocity rather than in angular proper motion:

\[\sigma_\mu(\varpi) = \sigma_{v,0}\;\varpi \;/\; (1\,\text{AU})\]

where \(\sigma_{v,0}\) is a velocity dispersion scale (e.g. km/s) and the division by 1 AU converts velocity x parallax to angular speed. Numerically, \(\sigma_{v,0}\) is first converted to AU/yr, and then \(\sigma_\mu = \sigma_{v,0}[\text{AU/yr}] \times \varpi\).

Parameters:

sigma_v0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], '']) – Transverse-velocity dispersion scale (e.g. km/s).

Notes

This class implements the LinearPriorCallable protocol and is the default linear_prior for pmra and pmdec returned by default_gaia_astrometry().

The params struct must have a .parallax field (Quantity with angular units). parallax is available because it is classified as an explicit (non-marginalized) linear parameter by default.

Examples

>>> from unxt import Q
>>> from harv.models.priors.custom_priors import ParallaxDependentProperMotionPrior
>>> prior = ParallaxDependentProperMotionPrior(sigma_v0=Q(50.0, "km/s"))
>>> prior.sigma_v0.unit
Unit("km / s")
sigma_v0: Real[Quantity[PhysicalType({'speed', 'velocity'})], '']
__init__(sigma_v0)
Parameters:

sigma_v0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''])

Return type:

None

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

TypeVar(_ModuleT, bound= Module)

class harv.models.priors.custom_priors.PeriodDependentKPrior

Bases: Module

Period-dependent RV semi-amplitude prior matching The Joker’s default.

The std dev of the Gaussian prior on the RV semi-amplitude scales with orbital period and eccentricity so that it remains approximately constant in companion mass at fixed primary mass:

\[\sigma_K(P, e) = \sigma_{K,0} \left(\frac{P}{P_0}\right)^{-1/3} \left(1 - e^2\right)^{-1/2}\]
Parameters:

  • sigma_K0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], '']) – RV semi-amplitude scale (km/s) at the reference period P0. Default: 30 km/s – appropriate for stellar binary searches.

  • P0 (Real[Quantity[PhysicalType('time')], '']) – Numeric value of the reference period in units of P0_unit.

Notes

This class implements the LinearPriorCallable protocol and is the default linear_prior returned by default_rv().

References

Price-Whelan et al. (2017) — The Joker: A Custom Monte Carlo Sampler for Binary-star and Exoplanet Radial Velocity Data.

Examples

>>> from unxt import Q
>>> from harv.models.priors.custom_priors import PeriodDependentKPrior
>>> prior = PeriodDependentKPrior(sigma_K0=Q(30.0, "km/s"), P0=Q(1.0, "yr"))
>>> prior.sigma_K0.unit
Unit("km / s")

Used as the default linear_prior for rv_semiamp in default_rv(). Called with a param struct to condition on nonlinear parameters:

>>> qd = prior(params)
sigma_K0: Real[Quantity[PhysicalType({'speed', 'velocity'})], '']
P0: Real[Quantity[PhysicalType('time')], '']
__init__(sigma_K0, P0)
Parameters:

  • sigma_K0 (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''])

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

Return type:

None

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

TypeVar(_ModuleT, bound= Module)

class harv.models.priors.custom_priors.PeriodDependentSemiMajorAxisPrior

Bases: Module

Period- and parallax-dependent semi-major axis prior for astrometry.

The std dev of the Gaussian prior on the astrometric semi-major axis scales with orbital period and parallax so that it remains approximately constant in companion mass at fixed primary mass:

\[\sigma_a(P, \varpi) = \sigma_{a,0} \left(\frac{P}{P_0}\right)^{2/3} \varpi\]

where \(\sigma_{a,0}\) is in physical length units (e.g. AU) and \(\varpi\) is the parallax in mas. Since 1 AU at 1 mas parallax subtends 1 mas, the product gives the angular semi-major axis in mas.

Parameters:

  • sigma_a0 (Real[Quantity[PhysicalType('length')], '']) – Semi-major axis scale in physical units (e.g. AU) at the reference period P0. Converted to angular size via the parallax.

  • P0 (Real[Quantity[PhysicalType('time')], '']) – Reference period.

Notes

This class implements the LinearPriorCallable protocol and is the default linear_prior for semi_major_axis returned by default_gaia_astrometry().

The params struct must have .period, .eccentricity, and .parallax fields. parallax is available because it is classified as an explicit (non-marginalized) linear parameter by default.

Examples

>>> from unxt import Q
>>> from harv.models.priors.custom_priors import PeriodDependentSemiMajorAxisPrior
>>> prior = PeriodDependentSemiMajorAxisPrior(
...     sigma_a0=Q(5.0, "AU"), P0=Q(1.0, "yr"),
... )
>>> prior.sigma_a0.unit
Unit("AU")
sigma_a0: Real[Quantity[PhysicalType('length')], '']
P0: Real[Quantity[PhysicalType('time')], '']
__init__(sigma_a0, P0)
Parameters:

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

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

Return type:

None

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

TypeVar(_ModuleT, bound= Module)

harv.models.priors.defaults module

Default priors without a parameterization analog.

harv.models.priors.defaults.default_sb2_prior(*, period_min=None, period_max=None, sigma_K0=None, sigma_v0=None, P0=Quantity(Array(1., dtype=float32, weak_type=True), unit='yr'), component_names=('primary', 'secondary'), **kwargs)

Create default prior for SB2 (double-lined) radial velocity data.

SB2 is a joint composition of two StandardRV components, not a single parameterization, so this lives as a module-level factory rather than a classmethod on HarvPrior. It pairs naturally with harv.models.JointModel.for_sb2() (JointModel.for_sb2(prior=...)).

Both semi-amplitudes use the same period-dependent scaling as HarvPrior.default_rv(). The systemic velocity prior is a fixed Gaussian.

The default names for the two components are “primary” and “secondary”, which means the linear priors for the semi-amplitudes must be keyed as “primary.rv_semiamp” and “secondary.rv_semiamp”. You can customize the component names via the component_names argument, but the linear prior keys must always be {component_name}.rv_semiamp.

Parameters:

  • period_min (Real[Quantity[PhysicalType('time')], ''] | None) – Lower bound for the log-uniform period prior.

  • period_max (Real[Quantity[PhysicalType('time')], ''] | None) – Upper bound for the log-uniform period prior.

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

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

  • P0 (Real[Quantity[PhysicalType('time')], '']) – Reference period for the K prior scaling. Default: 1 yr.

  • component_names (tuple[str, str]) – Names of the two components. These are used to construct the linear prior keys for the semi-amplitudes (e.g. “primary.rv_semiamp” and “secondary.rv_semiamp”).

  • **kwargs (Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal]) – Override any default nonlinear or linear prior by name.

Returns:

Prior configured for SB2 RV data.

Return type:

HarvPrior

Examples

>>> from unxt import Q
>>> from harv.samplers import default_sb2_prior
>>> sorted(
...     default_sb2_prior(
...         period_min=Q(2.0, "day"),
...         period_max=Q(1000.0, "day"),
...         sigma_K0=Q(30.0, "km/s"),
...         sigma_v0=Q(50.0, "km/s"),
...     ).nonlinear_priors.keys()
... )
['arg_peri', 'eccentricity', 'period', 'phase_peri']
>>> sorted(
...     default_sb2_prior(
...         period_min=Q(2.0, "day"),
...         period_max=Q(1000.0, "day"),
...         sigma_K0=Q(30.0, "km/s"),
...         sigma_v0=Q(50.0, "km/s"),
...     ).linear_priors
... )
['primary.rv_semiamp', 'secondary.rv_semiamp', 'v_sys']

harv.models.priors.helpers module

Helper functions for building the default priors in Harv.

harv.models.priors.prior module

Prior distributions for rejection sampling of Keplerian orbits.

This module implements the HarvPrior class which manages prior distributions for both nonlinear and linear parameters in the rejection sampling algorithm.

The prior is agnostic to data type - it simply holds distributions for any/all parameters. The sampler validates which parameters are needed based on the data.

class harv.models.priors.prior.HarvPrior

Bases: Module

Prior distribution for rejection sampling of Keplerian orbits.

This class encapsulates the prior distributions for both nonlinear and linear parameters. It is agnostic to data type - the sampler determines which parameters are required based on the provided data.

We recommend using the “default” factory constructors (e.g. default_rv(), default_gaia_astrometry(), etc.), which set up sensible priors for common use cases.

Nonlinear parameterization:

Parameter names in nonlinear_priors must match the field names of the parameterization, for example, period, eccentricity, phase_peri, etc. These parameters are sampled explicitly.

See the options available in harv.models.parameterizations.

Default parameterizations:

Radial Velocity:

  • Nonlinear: period, eccentricity, phase_peri, arg_peri

  • Linear: rv_semiamp, v_sys

Astrometry:

  • Nonlinear: period, eccentricity, phase_peri, cos_i, arg_peri, lon_asc_node

  • Linear params: ra0, dec0, pmra, pmdec, parallax, semi_major_axis

Parameters:

  • nonlinear_priors (dict[str, Distribution | QuantityDistribution]) – Mapping from parameter name to its prior distribution (a bare dist.Distribution for dimensionless parameters, or a harv.distributions.QuantityDistribution wrapper for parameters with physical units).

  • linear_priors (dict[str, Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal]]) –

    Per-parameter priors for linear parameters. Each entry is classified:

    • dist.Normal or QD(Normal) – Gaussian, can be analytically marginalized.

    • LinearPriorCallable – called with nonlinear params to produce a Normal, can be marginalized.

    • dist.HalfNormal, dist.Delta, etc. – non-Gaussian, sampled explicitly alongside nonlinear params.

    When using default_rv() with offsets, the non-reference offset priors are automatically included as linear parameters.

  • extension_priors (dict[str, Distribution | QuantityDistribution]) – Priors for extension parameters declared via extra_params().

nonlinear_priors: dict[str, Distribution | QuantityDistribution]
linear_priors: dict[str, Distribution | QuantityDistribution | Callable[..., QuantityDistribution | Normal]]
extension_priors: dict[str, Distribution | QuantityDistribution]
sample_nonlinear(key, n_samples)

Sample nonlinear parameters from priors.

Parameters:

  • key (Array) – Random key for sampling.

  • n_samples (int) – Number of samples to draw.

Return type:

dict[str, Any]

Returns:

Dictionary mapping each parameter name to an array of shape (n_samples,). Values are bare JAX arrays regardless of whether the distribution is wrapped in QuantityDistribution.

Examples

>>> import jax
>>> from unxt import Q
>>> from harv.samplers import HarvPrior
>>> sorted(
...     HarvPrior.default_rv(
...         period_min=Q(2.0, "day"),
...         period_max=Q(1000.0, "day"),
...         sigma_K0=Q(30.0, "km/s"),
...         sigma_v0=Q(50.0, "km/s"),
...     ).sample_nonlinear(jax.random.key(0), 10).keys()
... )
['arg_peri', 'eccentricity', 'period', 'phase_peri']
>>> HarvPrior.default_rv(
...     period_min=Q(2.0, "day"),
...     period_max=Q(1000.0, "day"),
...     sigma_K0=Q(30.0, "km/s"),
...     sigma_v0=Q(50.0, "km/s"),
... ).sample_nonlinear(jax.random.key(0), 10)["period"].shape
(10,)
classmethod from_parameterization(parameterization, **kwargs)

Build a default prior for any supported parameterization.

Delegates to parameterization.default_prior(**kwargs). Each concrete parameterization declares its own required scale arguments (e.g. sigma_K0 for RV, sigma_a0 for astrometry).

Parameters:
Return type:

HarvPrior

Examples

>>> from unxt import Q
>>> from harv.models.parameterizations.rv import EcoswEsinwRV
>>> from harv.samplers import HarvPrior
>>> prior = HarvPrior.from_parameterization(
...     EcoswEsinwRV(),
...     period_min=Q(2.0, "day"),
...     period_max=Q(1000.0, "day"),
...     sigma_K0=Q(30.0, "km/s"),
...     sigma_v0=Q(50.0, "km/s"),
... )
>>> sorted(prior.nonlinear_priors.keys())
['ecosw', 'esinw', 'period', 'phase_peri']
__init__(nonlinear_priors, linear_priors, extension_priors=<factory>)
Parameters:
Return type:

None

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

TypeVar(_ModuleT, bound= Module)