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.

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) → 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.

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.

Returns:

variants_orbits – The variant orbits.

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

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