harv.simulate package¶

Simulation tools.

harv.simulate.simulate_gaia_epoch_astrometry(times=None, scan_angle=None, parallax_factor=None, baseline=None, n_obs=50, period=None, eccentricity=None, t_peri=None, arg_peri=None, lon_asc_node=None, inclination=None, semi_major_axis=None, alpha0=None, delta0=None, mu_alpha=None, mu_delta=None, parallax=None, al_error=None, t_ref=None, seed=42)¶

Simulate Gaia-like along-scan epoch astrometry.

This function generates synthetic Gaia astrometry data including both 5-parameter astrometry and Keplerian orbital motion. Random values are drawn for any parameters not specified.

Parameters:

times (Real[Quantity[PhysicalType('time')], '*batch'] | None) – Observation times. Default: 100 times evenly spaced over 5 years.
scan_angle (Real[Quantity[PhysicalType('angle')], '*batch'] | None) – Gaia scan angles at each observation.
parallax_factor (Float[Array, '*batch'] | Real[Quantity[PhysicalType('dimensionless')], '*batch'] | None) – Pre-computed parallax factors.
baseline (Real[Quantity[PhysicalType('time')], ''] | None) – Time baseline for observations. Default: 5 years.
n_obs (int) – Number of observations to simulate (used if times/scan_angle/parallax_factor are None).
period (Real[Quantity[PhysicalType('time')], ''] | None) – Orbital period. If None, randomly drawn from [0, 3] years.
eccentricity (float | None) – Orbital eccentricity. If None, randomly drawn from [0, 0.9].
t_peri (Real[Quantity[PhysicalType('time')], ''] | None) – Time of periastron passage. If None, randomly drawn from [0, period].
arg_peri (Real[Quantity[PhysicalType('angle')], ''] | None) – Argument of periastron omega. If None, randomly drawn from [0, 2pi].
lon_asc_node (Real[Quantity[PhysicalType('angle')], ''] | None) – Longitude of ascending node Omega. If None, randomly drawn from [0, 2pi].
inclination (Real[Quantity[PhysicalType('angle')], ''] | None) – Orbital inclination. If None, randomly drawn from cos(i) ~ U(-1, 1).
semi_major_axis (Real[Quantity[PhysicalType('angle')], ''] | None) – Semi-major axis in angular units. If None, randomly drawn from [0.5, 50] mas.
alpha0 (Real[Quantity[PhysicalType('angle')], ''] | None) – Small RA offset from reference position at t_ref. Default: 0 mas. This is a linear parameter, not the absolute RA.
delta0 (Real[Quantity[PhysicalType('angle')], ''] | None) – Small Dec offset from reference position at t_ref. Default: 0 mas. This is a linear parameter, not the absolute Dec.
mu_alpha (Real[Quantity[PhysicalType({'angular frequency', 'angular speed', 'angular velocity'})], ''] | None) – Proper motion in RA. If None, randomly drawn ~ N(0, 10 mas/yr).
mu_delta (Real[Quantity[PhysicalType({'angular frequency', 'angular speed', 'angular velocity'})], ''] | None) – Proper motion in Dec. If None, randomly drawn ~ N(0, 10 mas/yr).
parallax (Real[Quantity[PhysicalType('angle')], ''] | None) – Parallax. If None, randomly drawn from Exp(10 mas).
al_error (Real[Quantity[PhysicalType('angle')], ''] | None) – Along-scan measurement errors (1-sigma). If None, randomly drawn from U(0.02, 0.1) mas for each observation.
t_ref (Real[Quantity[PhysicalType('time')], ''] | None) – Reference time for astrometry. If None, randomly chosen.
seed (int) – Random seed for reproducibility. Default: 42.

Return type:

tuple[GaiaAstrometryData, dict[str, Any]]

Returns:

data – Simulated Gaia astrometry data container.
true_params – Dictionary of true parameter values used in simulation, including: period, eccentricity, semi_major_axis, t_peri, alpha0, delta0, mu_alpha, mu_delta, parallax, A, B, F, G (Thiele-Innes), arg_peri, lon_asc_node, inclination.

Examples

>>> from unxt import Q
>>> from harv.simulate import simulate_gaia_epoch_astrometry
>>> data, true_params = simulate_gaia_epoch_astrometry(
...     seed=42,
...     n_obs=50,
...     period=Q(100.0, "day"),
...     eccentricity=0.3,
...     semi_major_axis=Q(2.0, "mas"),
... )
>>> data.time.shape
(50,)
>>> "period" in true_params
True

harv.simulate.fake_parallax_factor(time, ra, dec, scan_angle)¶

Mock, super simplified parallax factor for a star at (ra, dec).

This is a simplified analytical model for the parallax factor, assuming Earth’s orbit is circular and using a sinusoidal approximation. For real Gaia data, use the actual parallax factors from the epoch data.

Parameters:

time (Real[Quantity[PhysicalType('time')], '*batch']) – Observation times.
ra (Real[Quantity[PhysicalType('angle')], '']) – Right ascension of the source.
dec (Real[Quantity[PhysicalType('angle')], '']) – Declination of the source.
scan_angle (Real[Quantity[PhysicalType('angle')], '*batch']) – Gaia scan angle at each observation.

Return type:

AbstractQuantity

Returns:

Dimensionless parallax factor for each observation.

Examples

>>> from unxt import Q
>>> from harv.simulate.astrometry import fake_parallax_factor
>>> pf = fake_parallax_factor(
...     time=Q([0.0, 0.5, 1.0], "yr"),
...     ra=Q(180.0, "deg"),
...     dec=Q(45.0, "deg"),
...     scan_angle=Q([0.0, 1.0, 2.0], "rad"),
... )

harv.simulate.simulate_rv_multisurv_data(instruments, seed=42, n_obs_per_instrument=30, baseline=None, period=None, eccentricity=None, t_peri=None, arg_peri=None, rv_semiamp=None, v_sys=None, rv_err=None, t_ref=None)¶

Simulate multi-survey RV data with per-instrument zero-point offsets.

Generates a SourceData containing one RVData per instrument, all sharing the same orbital solution but with different per-instrument zero-point offsets.

Parameters:

instruments (dict[str, Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None]) –
Mapping from instrument name to its zero-point offset. Pass None for the reference instrument (offset = 0). Example:
```
{"keck": None, "espresso": Q(3.5, "km/s")}
```
seed (int) – Random seed. Default: 42.
n_obs_per_instrument (int) – Number of observations per instrument. Default: 30.
baseline (Real[Quantity[PhysicalType('time')], ''] | None) – Total time baseline. Default: 5 years.
period (Real[Quantity[PhysicalType('time')], ''] | None) – Orbital period. Randomly drawn if None.
eccentricity (float | None) – Orbital eccentricity. Randomly drawn if None.
t_peri (Real[Quantity[PhysicalType('time')], ''] | None) – Time of periastron passage. Randomly drawn if None.
arg_peri (Real[Quantity[PhysicalType('angle')], ''] | None) – Argument of periastron. Randomly drawn if None.
rv_semiamp (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – RV semi-amplitude. Randomly drawn if None.
v_sys (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – Systemic velocity of the reference instrument. Randomly drawn if None.
rv_err (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – Measurement uncertainty (same for all instruments and observations). Randomly drawn if None.
t_ref (Real[Quantity[PhysicalType('time')], ''] | None) – Reference epoch. Randomly drawn if None.

Return type:

tuple[SourceData, dict[str, Any]]

Returns:

source_data – Multi-instrument RV data container.
true_params – True parameter values: period, eccentricity, t_peri, arg_peri, rv_semiamp, v_sys, and one entry per non-reference instrument named "offset_{name}".

Examples

>>> from unxt import Q
>>> from harv.simulate import simulate_rv_multisurv_data
>>> source_data, true_params = simulate_rv_multisurv_data(
...     instruments={"keck": None, "espresso": Q(3.5, "km/s")},
...     seed=0,
...     n_obs_per_instrument=20,
...     period=Q(200.0, "day"),
...     rv_semiamp=Q(15.0, "km/s"),
... )
>>> list(source_data.keys())
['keck', 'espresso']
>>> source_data["keck"].time.shape
(20,)

harv.simulate.simulate_rv_sb1_data(seed=42, n_obs=50, baseline=None, period=None, eccentricity=None, t_peri=None, arg_peri=None, rv_semiamp=None, v_sys=None, rv_err=None, t_ref=None, instrument='default')¶

Simulate radial velocity data for a single-lined binary (SB1).

This function generates synthetic RV measurements following the model:: RV(t) = K*[cos(omega + f(t)) + e*cos(omega)] + v_0

where f(t) is the true anomaly computed via Kepler’s equation.

Parameters:

seed (int) – Random seed for reproducibility. Default: 42.
n_obs (int) – Number of observations. Default: 50.
baseline (Real[Quantity[PhysicalType('time')], ''] | None) – Time baseline for observations. Default: 5 years.
period (Real[Quantity[PhysicalType('time')], ''] | None) – Orbital period. If None, randomly drawn from [10, 1000] days.
eccentricity (float | None) – Orbital eccentricity. If None, randomly drawn from [0, 0.7].
t_peri (Real[Quantity[PhysicalType('time')], ''] | None) – Time of periastron passage. If None, randomly drawn from [0, period].
arg_peri (Real[Quantity[PhysicalType('angle')], ''] | None) – Argument of periastron omega. If None, randomly drawn from [0, 2pi].
rv_semiamp (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – RV semi-amplitude. If None, randomly drawn from [1, 50] km/s.
v_sys (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – Systemic velocity. If None, randomly drawn ~ N(0, 20) km/s.
rv_err (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – RV measurement uncertainties (1-sigma). If None, randomly drawn from U(0.01, 0.5) km/s for each observation.
t_ref (Real[Quantity[PhysicalType('time')], ''] | None) – Reference time. If None, randomly chosen.
instrument (str) – Instrument name for the observations. Default: “default”.

Return type:

tuple[RVData, dict[str, Any]]

Returns:

data – Simulated RV data container.
true_params – Dictionary of true parameter values used in simulation.

Examples

>>> from unxt import Q
>>> from harv.simulate import simulate_rv_sb1_data
>>> data, true_params = simulate_rv_sb1_data(
...     seed=42,
...     n_obs=30,
...     period=Q(100.0, "day"),
...     eccentricity=0.3,
...     rv_semiamp=Q(10.0, "km/s"),
... )
>>> data.time.shape
(30,)
>>> "rv_semiamp" in true_params
True

Submodules¶

harv.simulate.astrometry module¶

Simulate Gaia-like epoch astrometry data.

This module provides utilities for generating synthetic along-scan astrometry measurements similar to Gaia DR3/DR4 epoch data. The simulated data includes: - Along-scan positions with realistic noise - Scan angles - Parallax factors - Measurement uncertainties

The astrometric model includes: - 5-parameter astrometry (a0, d0, mu_a, mu_d, parallax) - Keplerian orbital motion parameterized by Thiele-Innes constants

harv.simulate.astrometry.simulate_gaia_epoch_astrometry(times=None, scan_angle=None, parallax_factor=None, baseline=None, n_obs=50, period=None, eccentricity=None, t_peri=None, arg_peri=None, lon_asc_node=None, inclination=None, semi_major_axis=None, alpha0=None, delta0=None, mu_alpha=None, mu_delta=None, parallax=None, al_error=None, t_ref=None, seed=42)¶

Simulate Gaia-like along-scan epoch astrometry.

This function generates synthetic Gaia astrometry data including both 5-parameter astrometry and Keplerian orbital motion. Random values are drawn for any parameters not specified.

Parameters:

times (Real[Quantity[PhysicalType('time')], '*batch'] | None) – Observation times. Default: 100 times evenly spaced over 5 years.
scan_angle (Real[Quantity[PhysicalType('angle')], '*batch'] | None) – Gaia scan angles at each observation.
parallax_factor (Float[Array, '*batch'] | Real[Quantity[PhysicalType('dimensionless')], '*batch'] | None) – Pre-computed parallax factors.
baseline (Real[Quantity[PhysicalType('time')], ''] | None) – Time baseline for observations. Default: 5 years.
n_obs (int) – Number of observations to simulate (used if times/scan_angle/parallax_factor are None).
period (Real[Quantity[PhysicalType('time')], ''] | None) – Orbital period. If None, randomly drawn from [0, 3] years.
eccentricity (float | None) – Orbital eccentricity. If None, randomly drawn from [0, 0.9].
t_peri (Real[Quantity[PhysicalType('time')], ''] | None) – Time of periastron passage. If None, randomly drawn from [0, period].
arg_peri (Real[Quantity[PhysicalType('angle')], ''] | None) – Argument of periastron omega. If None, randomly drawn from [0, 2pi].
lon_asc_node (Real[Quantity[PhysicalType('angle')], ''] | None) – Longitude of ascending node Omega. If None, randomly drawn from [0, 2pi].
inclination (Real[Quantity[PhysicalType('angle')], ''] | None) – Orbital inclination. If None, randomly drawn from cos(i) ~ U(-1, 1).
semi_major_axis (Real[Quantity[PhysicalType('angle')], ''] | None) – Semi-major axis in angular units. If None, randomly drawn from [0.5, 50] mas.
alpha0 (Real[Quantity[PhysicalType('angle')], ''] | None) – Small RA offset from reference position at t_ref. Default: 0 mas. This is a linear parameter, not the absolute RA.
delta0 (Real[Quantity[PhysicalType('angle')], ''] | None) – Small Dec offset from reference position at t_ref. Default: 0 mas. This is a linear parameter, not the absolute Dec.
mu_alpha (Real[Quantity[PhysicalType({'angular frequency', 'angular speed', 'angular velocity'})], ''] | None) – Proper motion in RA. If None, randomly drawn ~ N(0, 10 mas/yr).
mu_delta (Real[Quantity[PhysicalType({'angular frequency', 'angular speed', 'angular velocity'})], ''] | None) – Proper motion in Dec. If None, randomly drawn ~ N(0, 10 mas/yr).
parallax (Real[Quantity[PhysicalType('angle')], ''] | None) – Parallax. If None, randomly drawn from Exp(10 mas).
al_error (Real[Quantity[PhysicalType('angle')], ''] | None) – Along-scan measurement errors (1-sigma). If None, randomly drawn from U(0.02, 0.1) mas for each observation.
t_ref (Real[Quantity[PhysicalType('time')], ''] | None) – Reference time for astrometry. If None, randomly chosen.
seed (int) – Random seed for reproducibility. Default: 42.

Return type:

tuple[GaiaAstrometryData, dict[str, Any]]

Returns:

data – Simulated Gaia astrometry data container.
true_params – Dictionary of true parameter values used in simulation, including: period, eccentricity, semi_major_axis, t_peri, alpha0, delta0, mu_alpha, mu_delta, parallax, A, B, F, G (Thiele-Innes), arg_peri, lon_asc_node, inclination.

Examples

>>> from unxt import Q
>>> from harv.simulate import simulate_gaia_epoch_astrometry
>>> data, true_params = simulate_gaia_epoch_astrometry(
...     seed=42,
...     n_obs=50,
...     period=Q(100.0, "day"),
...     eccentricity=0.3,
...     semi_major_axis=Q(2.0, "mas"),
... )
>>> data.time.shape
(50,)
>>> "period" in true_params
True

harv.simulate.astrometry.fake_parallax_factor(time, ra, dec, scan_angle)¶

Mock, super simplified parallax factor for a star at (ra, dec).

Parameters:

time (Real[Quantity[PhysicalType('time')], '*batch']) – Observation times.
ra (Real[Quantity[PhysicalType('angle')], '']) – Right ascension of the source.
dec (Real[Quantity[PhysicalType('angle')], '']) – Declination of the source.
scan_angle (Real[Quantity[PhysicalType('angle')], '*batch']) – Gaia scan angle at each observation.

Return type:

AbstractQuantity

Returns:

Dimensionless parallax factor for each observation.

Examples

>>> from unxt import Q
>>> from harv.simulate.astrometry import fake_parallax_factor
>>> pf = fake_parallax_factor(
...     time=Q([0.0, 0.5, 1.0], "yr"),
...     ra=Q(180.0, "deg"),
...     dec=Q(45.0, "deg"),
...     scan_angle=Q([0.0, 1.0, 2.0], "rad"),
... )

harv.simulate.rv module¶

Simulate radial velocity data.

This module provides utilities for generating synthetic RV measurements for single-lined (SB1) and double-lined (SB2) spectroscopic binaries.

harv.simulate.rv.simulate_rv_multisurv_data(instruments, seed=42, n_obs_per_instrument=30, baseline=None, period=None, eccentricity=None, t_peri=None, arg_peri=None, rv_semiamp=None, v_sys=None, rv_err=None, t_ref=None)¶

Simulate multi-survey RV data with per-instrument zero-point offsets.

Generates a SourceData containing one RVData per instrument, all sharing the same orbital solution but with different per-instrument zero-point offsets.

Parameters:

instruments (dict[str, Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None]) –
Mapping from instrument name to its zero-point offset. Pass None for the reference instrument (offset = 0). Example:
```
{"keck": None, "espresso": Q(3.5, "km/s")}
```
seed (int) – Random seed. Default: 42.
n_obs_per_instrument (int) – Number of observations per instrument. Default: 30.
baseline (Real[Quantity[PhysicalType('time')], ''] | None) – Total time baseline. Default: 5 years.
period (Real[Quantity[PhysicalType('time')], ''] | None) – Orbital period. Randomly drawn if None.
eccentricity (float | None) – Orbital eccentricity. Randomly drawn if None.
t_peri (Real[Quantity[PhysicalType('time')], ''] | None) – Time of periastron passage. Randomly drawn if None.
arg_peri (Real[Quantity[PhysicalType('angle')], ''] | None) – Argument of periastron. Randomly drawn if None.
rv_semiamp (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – RV semi-amplitude. Randomly drawn if None.
v_sys (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – Systemic velocity of the reference instrument. Randomly drawn if None.
rv_err (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – Measurement uncertainty (same for all instruments and observations). Randomly drawn if None.
t_ref (Real[Quantity[PhysicalType('time')], ''] | None) – Reference epoch. Randomly drawn if None.

Return type:

tuple[SourceData, dict[str, Any]]

Returns:

source_data – Multi-instrument RV data container.
true_params – True parameter values: period, eccentricity, t_peri, arg_peri, rv_semiamp, v_sys, and one entry per non-reference instrument named "offset_{name}".

Examples

>>> from unxt import Q
>>> from harv.simulate import simulate_rv_multisurv_data
>>> source_data, true_params = simulate_rv_multisurv_data(
...     instruments={"keck": None, "espresso": Q(3.5, "km/s")},
...     seed=0,
...     n_obs_per_instrument=20,
...     period=Q(200.0, "day"),
...     rv_semiamp=Q(15.0, "km/s"),
... )
>>> list(source_data.keys())
['keck', 'espresso']
>>> source_data["keck"].time.shape
(20,)

harv.simulate.rv.simulate_rv_sb1_data(seed=42, n_obs=50, baseline=None, period=None, eccentricity=None, t_peri=None, arg_peri=None, rv_semiamp=None, v_sys=None, rv_err=None, t_ref=None, instrument='default')¶

Simulate radial velocity data for a single-lined binary (SB1).

This function generates synthetic RV measurements following the model:: RV(t) = K*[cos(omega + f(t)) + e*cos(omega)] + v_0

where f(t) is the true anomaly computed via Kepler’s equation.

Parameters:

seed (int) – Random seed for reproducibility. Default: 42.
n_obs (int) – Number of observations. Default: 50.
baseline (Real[Quantity[PhysicalType('time')], ''] | None) – Time baseline for observations. Default: 5 years.
period (Real[Quantity[PhysicalType('time')], ''] | None) – Orbital period. If None, randomly drawn from [10, 1000] days.
eccentricity (float | None) – Orbital eccentricity. If None, randomly drawn from [0, 0.7].
t_peri (Real[Quantity[PhysicalType('time')], ''] | None) – Time of periastron passage. If None, randomly drawn from [0, period].
arg_peri (Real[Quantity[PhysicalType('angle')], ''] | None) – Argument of periastron omega. If None, randomly drawn from [0, 2pi].
rv_semiamp (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – RV semi-amplitude. If None, randomly drawn from [1, 50] km/s.
v_sys (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – Systemic velocity. If None, randomly drawn ~ N(0, 20) km/s.
rv_err (Real[Quantity[PhysicalType({'speed', 'velocity'})], ''] | None) – RV measurement uncertainties (1-sigma). If None, randomly drawn from U(0.01, 0.5) km/s for each observation.
t_ref (Real[Quantity[PhysicalType('time')], ''] | None) – Reference time. If None, randomly chosen.
instrument (str) – Instrument name for the observations. Default: “default”.

Return type:

tuple[RVData, dict[str, Any]]

Returns:

data – Simulated RV data container.
true_params – Dictionary of true parameter values used in simulation.

Examples

>>> from unxt import Q
>>> from harv.simulate import simulate_rv_sb1_data
>>> data, true_params = simulate_rv_sb1_data(
...     seed=42,
...     n_obs=30,
...     period=Q(100.0, "day"),
...     eccentricity=0.3,
...     rv_semiamp=Q(10.0, "km/s"),
... )
>>> data.time.shape
(30,)
>>> "rv_semiamp" in true_params
True

harv.simulate.scanlaw module¶

Gaia scanning law simulation utilities.

class harv.simulate.scanlaw.AbstractGaiaScanLaw¶

Bases: Module

Abstract base class for Gaia scanning laws.

__init__()¶

Return type:: None

static __new__(cls, *args, **kwargs)¶

Parameters:

cls (type[TypeVar(_ModuleT, bound= Module)])
args (object)
kwargs (object)

Return type:

TypeVar(_ModuleT, bound= Module)

class harv.simulate.scanlaw.GaiaReducedCommandedScanLaw¶

Bases: AbstractGaiaScanLaw

A simple, reduced version of the Gaia commanded scan law.

This class provides an interface to query a reduced version of the Gaia commanded scanning law. The commanded scan law provides the times, pointings, and parallax factors for the two fields of view of the Gaia spacecraft sampled at a ~10 second cadence. The “reduced” version of the scan law groups samples by sky location (into healpix pixels) and treats each transit of a healpix pixel as a single scan of that pixel.

Parameters:

dr (Any) – Data release identifier (e.g., “dr3”, “dr4”, etc.) specifying which version of the scan law data to use. This mainly affects the time span covered by the scan law.
random_downsample_fraction (Any)
random_seed (Any)

dr: str¶

random_downsample_fraction: float = 0.0¶

random_seed: int | None = None¶

property file_path: Path¶: Get the path to the cached scan law file, download if necessary.

read_metadata()¶

Read and return the metadata from the scan law file.

Return type:: dict[str, Any]

load_scans_for_healpix(healpix_pixel)¶

Load the scan data for a specific healpix pixel.

Parameters:: healpix_pixel (int) – Healpix pixel for which to load the scan data.
Return type:: ndarray
Returns:: Structured array containing the scan data for the specified healpix pixel.

query(ra, dec)¶

Query the scan data for a specific sky location.

Parameters:

ra (Real[Quantity[PhysicalType('angle')], '']) – Right ascension of the sky location.
dec (Real[Quantity[PhysicalType('angle')], '']) – Declination of the sky location.

Return type:

ndarray

Returns:

Structured array containing the scan data for the specified sky location.

__init__(dr, random_downsample_fraction=0.0, random_seed=None)¶

Parameters:

dr (Any)
random_downsample_fraction (Any)
random_seed (Any)

Return type:

None

static __new__(cls, *args, **kwargs)¶

Parameters:

cls (type[TypeVar(_ModuleT, bound= Module)])
args (object)
kwargs (object)

Return type:

TypeVar(_ModuleT, bound= Module)