adam_core.orbits.variants module

class adam_core.orbits.variants.VariantOrbits(table: Table, **kwargs: int | float | str)

Bases: Table

orbit_id

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

object_id

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

variant_id

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

weights

A column for storing 64-bit floating point numbers.

weights_cov

A column for storing 64-bit floating point numbers.

coordinates

A column which represents an embedded quivr table.

Parameters:

• table_type – The type of the table to embed.

• nullable – Whether the column can contain null values.

• metadata – A dictionary of metadata to attach to the column.

physical_parameters

A column which represents an embedded quivr table.

Parameters:

• table_type – The type of the table to embed.

• nullable – Whether the column can contain null values.

• metadata – A dictionary of metadata to attach to the column.

non_gravitational_parameters

A column which represents an embedded quivr table.

Parameters:

• table_type – The type of the table to embed.

• nullable – Whether the column can contain null values.

• metadata – A dictionary of metadata to attach to the column.

has_non_gravitational_parameters() → bool

Return True if any variant carries a non-zero non-gravitational parameter value.

without_non_gravitational_parameters() → VariantOrbits

Return a copy with the non-gravitational parameters nulled and the coordinate covariance reduced to its 6x6 coordinate block.

classmethod create(orbits: Orbits, method: Literal['auto', 'sigma-point', 'monte-carlo'] = 'auto', num_samples: int = 10000, alpha: float = 1, beta: float = 0, kappa: float = 0, seed: int | None = None, include_nongrav: bool = True) → VariantOrbits

Sample and create variants for the given orbits by sampling the covariance matrices. There are three supported methods: - sigma-point: Sample the covariance matrix using sigma points. This is the fastest method, but can be inaccurate if the covariance matrix is not well behaved. - monte-carlo: Sample the covariance matrix using a monte carlo method. This is the slowest method, but is the most accurate. 10k samples are drawn. - auto: Automatically select the best method based on the covariance matrix. If the covariance matrix is well behaved then sigma-point sampling will be used. If the covariance matrix is not well behaved then monte-carlo sampling will be used.

When sampling with monte-carlo, 10k samples are drawn. Sigma-point sampling draws 13 samples for 6-dimensional coordinates. Orbits whose coordinate covariance carries the non-gravitational (A1, A2, A3) block are jointly sampled in the full 9-dimensional state, in which case sigma-point sampling draws 19 samples per orbit.

Parameters:

• orbits ('~adam_core.orbits.orbits.Orbits') – The orbits for which to create variant orbits.

• method ({'sigma-point', 'monte-carlo', 'auto'}, optional) – The method to use for sampling the covariance matrix. If ‘auto’ is selected then the method will be automatically selected based on the covariance matrix. The default is ‘auto’.

• num_samples (int, optional) – The number of samples to draw when sampling with monte-carlo.

• alpha (float, optional) – Spread of the sigma points between 1e^-2 and 1.

• beta (float, optional) – Prior knowledge of the distribution when generating sigma points usually set to 2 for a Gaussian.

• kappa (float, optional) – Secondary scaling parameter when generating sigma points usually set to 0.

• seed (int, optional) – Seed for reproducible monte-carlo sampling. Each orbit receives an independent child seed spawned from this value.

• include_nongrav (bool, optional) – If True (default), orbits whose coordinate covariance carries the non-gravitational (A1, A2, A3) block are jointly sampled in the full 9-dimensional state. If False, the non-gravitational parameters are stripped and only the 6x6 coordinate covariance block is sampled.

Returns:

variants_orbits – The variant orbits. When the input mixes orbits with and without the non-gravitational covariance block, variants for the orbits with the block are returned first, so row order does not necessarily follow the input orbit order.

Return type:

‘~adam_core.orbits.variants.VariantOrbits’

link_to_orbits(orbits: Orbits) → MultiKeyLinkage[Orbits, VariantOrbits]

Link variants to the orbits from which they were generated.

Parameters:

orbits (~adam_core.orbits.orbits.Orbits) – Orbits from which the variants were generated.

Returns:

linkage – Linkage between variants and orbits.

Return type:

~quivr.MultiKeyLinkage[Orbits, VariantOrbits]

collapse(orbits: Orbits) → Orbits

Collapse the variants and recalculate the covariance matrix for each each orbit at each epoch. The mean state is taken from the orbits class and is not calculated from the variants.

Parameters:

orbits (~adam_core.orbits.orbits.Orbits) – Orbits from which the variants were generated.

Returns:

collapsed_orbits – The collapsed orbits.

Return type:

~adam_core.orbits.orbits.Orbits

collapse_by_object_id() → Orbits

Collapse the variant orbits into a mean and covariance matrix.

Returns:

collapsed_orbits – The collapsed orbits.

Return type:

~adam_core.orbits.orbits.Orbits

schema: ClassVar[pa.Schema] = orbit_id: large_string not null object_id: large_string variant_id: large_string weights: double weights_cov: double coordinates: struct<x: double, y: double, z: double, vx: double, vy: double, vz: double, time: struct<days: int64 (... 106 chars omitted)   child 0, x: double   child 1, y: double   child 2, z: double   child 3, vx: double   child 4, vy: double   child 5, vz: double   child 6, time: struct<days: int64, nanos: int64>       child 0, days: int64       child 1, nanos: int64   child 7, covariance: struct<values: large_list<item: double>>       child 0, values: large_list<item: double>           child 0, item: double   child 8, origin: struct<code: large_string>       child 0, code: large_string physical_parameters: struct<H_v: double, H_v_sigma: double, G: double, G_sigma: double, sigma_eff: double, chi2_red: doub (... 3 chars omitted)   child 0, H_v: double   child 1, H_v_sigma: double   child 2, G: double   child 3, G_sigma: double   child 4, sigma_eff: double   child 5, chi2_red: double non_gravitational_parameters: struct<source: large_string, A1: double, A2: double, A3: double, ALN: double, NK: double, NM: double (... 25 chars omitted)   child 0, source: large_string   child 1, A1: double   child 2, A2: double   child 3, A3: double   child 4, ALN: double   child 5, NK: double   child 6, NM: double   child 7, NN: double   child 8, R0: double

table: pa.Table

class adam_core.orbits.variants.VariantEphemeris(table: Table, **kwargs: int | float | str)

Bases: Table

orbit_id

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

object_id

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

variant_id

A column for storing large strings (over 2³¹ bytes long). Large string data is stored in variable-length chunks.

weights

A column for storing 64-bit floating point numbers.

weights_cov

A column for storing 64-bit floating point numbers.

coordinates

A column which represents an embedded quivr table.

Parameters:

• table_type – The type of the table to embed.

• nullable – Whether the column can contain null values.

• metadata – A dictionary of metadata to attach to the column.

aberrated_coordinates

A column which represents an embedded quivr table.

Parameters:

• table_type – The type of the table to embed.

• nullable – Whether the column can contain null values.

• metadata – A dictionary of metadata to attach to the column.

predicted_magnitude_v

A column for storing 64-bit floating point numbers.

alpha

A column for storing 64-bit floating point numbers.

light_time

A column for storing 64-bit floating point numbers.

link_to_ephemeris(ephemeris: Ephemeris) → MultiKeyLinkage[Ephemeris, VariantEphemeris]

Link variants to the ephemeris for which they were generated.

Parameters:

ephemeris (~adam_core.orbits.ephemeris.Ephemeris) – Ephemeris for which the variants were generated.

Returns:

linkage – Linkage between variants and ephemeris.

Return type:

~quivr.MultiKeyLinkage[Ephemeris, EphemerisVariants]

collapse(ephemeris: Ephemeris) → Ephemeris

Collapse the variants and recalculate the covariance matrix for each each ephemeris at each epoch. The mean state is taken from the ephemeris class and is not calculate from the variants.

Parameters:

ephemeris (~adam_core.orbits.ephemeris.Ephemeris) – Ephemeris for which the variants were generated.

Returns:

collapsed_ephemeris – The collapsed ephemeris (with covariance matrices calculated based on the samples).

Return type:

~adam_core.orbits.ephemeris.Ephemeris

collapse_by_object_id(*, aberration_mode: Literal['recompute', 'collapse', 'none'] = 'recompute', group_chunk_size: int = 200000) → Ephemeris

Collapse the variant ephemerides into mean ephemerides and covariance matrices grouped by object_id, time, and observatory (origin code).

Returns:

collapsed_ephemeris – The collapsed ephemeris.

Return type:

~adam_core.orbits.ephemeris.Ephemeris

collapse_sigma_points_orbit_major(*, n_times: int, n_variants: int = 13) → Ephemeris

Fast sigma-point collapse for the common layout produced by: VariantOrbits.create(method=”sigma-point”) + propagate_2body(variants, times).

Assumptions

• The variant ephemeris rows are ordered in base-variant-major blocks, where each base variant has a contiguous block of n_times rows in time order.

• Base variants are ordered in orbit-major order, with variant_id cycling as “0”..”n_variants-1” for each orbit.

This method avoids the expensive sort_by in collapse_by_object_id() and computes UT mean + covariance directly via reshaping and vectorized numpy operations.

schema: ClassVar[pa.Schema] = orbit_id: large_string not null object_id: large_string variant_id: large_string weights: double weights_cov: double coordinates: struct<rho: double, lon: double, lat: double, vrho: double, vlon: double, vlat: double, time: struct (... 118 chars omitted)   child 0, rho: double   child 1, lon: double   child 2, lat: double   child 3, vrho: double   child 4, vlon: double   child 5, vlat: double   child 6, time: struct<days: int64, nanos: int64>       child 0, days: int64       child 1, nanos: int64   child 7, covariance: struct<values: large_list<item: double>>       child 0, values: large_list<item: double>           child 0, item: double   child 8, origin: struct<code: large_string>       child 0, code: large_string aberrated_coordinates: struct<x: double, y: double, z: double, vx: double, vy: double, vz: double, time: struct<days: int64 (... 106 chars omitted)   child 0, x: double   child 1, y: double   child 2, z: double   child 3, vx: double   child 4, vy: double   child 5, vz: double   child 6, time: struct<days: int64, nanos: int64>       child 0, days: int64       child 1, nanos: int64   child 7, covariance: struct<values: large_list<item: double>>       child 0, values: large_list<item: double>           child 0, item: double   child 8, origin: struct<code: large_string>       child 0, code: large_string predicted_magnitude_v: double alpha: double light_time: double

table: pa.Table