adam_core.orbits package

class adam_core.orbits.Ephemeris(table: Table, **kwargs: int | float | str)[source]

Bases: Table

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.

alpha

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.

light_time

A column for storing 64-bit floating point numbers.

Link these ephemerides back to the observers that generated them. This is useful if you want or need to use the observer’s position as part of any computation for any given set of ephemerides.

Not all propagators will return ephemerides exactly at the time of the input observers. As an example, PYOORB stores times as a single MJD, when converting from two integers to this singular float there will be a loss of precision. To mitigate this, the user may optionally define the precision to which would like to link back to observers. Times for both the ephemerides and observers will be rounded to this precision before linking.

Parameters:
  • observers (~adam_core.observers.observers.Observers (N)) – Observers that generated the ephemerides.

  • precision (str, optional) – Precision to which to link back to observers, by default “ns”.

Returns:

  • ~qv.MultiKeyLinkage[ – `~adam_core.orbits.ephemeris.Ephemeris, `~adam_core.observers.observersObservers

  • ]` – Linkage between ephemerides and observers.

object_id

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

orbit_id

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

predicted_magnitude_v

A column for storing 64-bit floating point numbers.

schema: ClassVar[pa.Schema] = orbit_id: large_string not null object_id: large_string 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 predicted_magnitude_v: double alpha: double light_time: double 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
class adam_core.orbits.NonGravitationalParameters(table: Table, **kwargs: int | float | str)[source]

Bases: Table

Non-gravitational parameters attached to an orbit solution.

Only the Marsden-style radial/transverse/normal accelerations (A1, A2, A3) are supported as fitted parameters, stored in au / d^2. Their uncertainties and cross covariances with the orbital state live in the orbit’s coordinate covariance, which is extended to 9x9 for orbits with a non-gravitational solution (see ~adam_core.coordinates.covariances.CoordinateCovariances).

The Marsden g(r) constants (ALN, NK, NM, NN, R0; R0 in au, the rest dimensionless) are fixed model constants, not fitted parameters: they carry no uncertainty and are not covariance dimensions, but they select the force law under which A1/A2/A3 were fit and must be fed to the propagator. Null constants mean the standard asteroid convention g(r) = (1 au / r)^2.

A1

A column for storing 64-bit floating point numbers.

A2

A column for storing 64-bit floating point numbers.

A3

A column for storing 64-bit floating point numbers.

ALN

A column for storing 64-bit floating point numbers.

NK

A column for storing 64-bit floating point numbers.

NM

A column for storing 64-bit floating point numbers.

NN

A column for storing 64-bit floating point numbers.

R0

A column for storing 64-bit floating point numbers.

has_values() bool[source]

Return True if any row has a non-zero non-gravitational acceleration value (A1, A2, A3).

Parameters that are explicitly solved to zero are treated as absent: they exert no force, so a gravity-only propagation of such an orbit is still exact. The g(r) constants are not considered: without a non-zero acceleration they select a force law that is never applied.

marsden_constants_array() ndarray[tuple[Any, ...], dtype[float64]][source]

Return the g(r) constants as an (N, 5) array in (ALN, NK, NM, NN, R0) order, with nulls replaced by the standard asteroid convention (g(r) = (1 au / r)^2).

classmethod nulls(length: int) NonGravitationalParameters[source]

Create a table with nulls.

Parameters:
  • size – The number of rows to create.

  • **kwargs – Additional keyword arguments to set the Table’s attributes.

Even for tables which do not permit nulls in their columns, it is possible to create a table with nulls in the context of SubTableColumn. So for both of these cases, we need a method to populate tables with null values for all columns, while also setting the Table’s attributes.

schema: ClassVar[pa.Schema] = source: large_string A1: double A2: double A3: double ALN: double NK: double NM: double NN: double R0: double
source

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

to_array() ndarray[tuple[Any, ...], dtype[float64]][source]

Return the acceleration values as an (N, 3) array in (A1, A2, A3) order, with nulls replaced by 0.0 (no force).

class adam_core.orbits.Orbits(table: Table, **kwargs: int | float | str)[source]

Bases: Table

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.

coordinates_to(representation_out: type[CartesianCoordinates | KeplerianCoordinates | CometaryCoordinates | SphericalCoordinates], *, frame_out: Literal['ecliptic', 'equatorial', 'itrf93'] | None = None, origin_out: OriginCodes | None = None)[source]

Transform this orbit’s coordinates to another representation, frame, and/or origin. Covariances – including the non-gravitational block for orbits with a non-gravitational solution – are transformed alongside the coordinates.

dynamical_class() ndarray[tuple[Any, ...], dtype[str]][source]

Compute dynamical classes of orbits. Currently limited to asteroid dynamical classes.

Returns:

dynamical_classes – Dynamical classes of orbits.

Return type:

~numpy.ndarray

group_by_orbit_id() Iterable[Tuple[str, Orbits]][source]

Group orbits by orbit ID and yield them.

Yields:
  • orbit_id (str) – Orbit ID.

  • orbits (~adam_core.orbits.orbits.Orbits) – Orbits belonging to this orbit ID.

has_non_gravitational_parameters() bool[source]

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

Parameters that are explicitly solved to zero are treated as absent: they exert no force, so a gravity-only propagation of such an orbit is still exact.

has_non_gravitational_solution() bool[source]

Return True if any orbit carries a non-gravitational solution: either a non-zero parameter value or a non-gravitational block in the coordinate covariance (a zero-mean parameter can still carry uncertainty).

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.

object_id

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

orbit_id

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

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.

preview(propagator: Propagator) None[source]

For a single orbit, render a plotly plot of the orbit.

schema: ClassVar[pa.Schema] = orbit_id: large_string not null object_id: large_string 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
to_cometary() CometaryCoordinates[source]
to_keplerian() KeplerianCoordinates[source]
to_spherical() SphericalCoordinates[source]
without_non_gravitational_parameters() Orbits[source]

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

class adam_core.orbits.Trajectory(table: Table, **kwargs: int | float | str)[source]

Bases: Table

A set of validity-bounded orbit segments (rows are segments).

Segments belonging to the same object_id must have non-overlapping coverage windows; gaps between them are allowed and are treated as “no valid state” (fail closed) rather than silently extrapolated.

coverage_end

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.

coverage_end_mjd() ndarray[tuple[Any, ...], dtype[float64]][source]

Coverage-window end times as TDB MJD.

coverage_start

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.

coverage_start_mjd() ndarray[tuple[Any, ...], dtype[float64]][source]

Coverage-window start times as TDB MJD.

epoch_mjd() ndarray[tuple[Any, ...], dtype[float64]][source]

Anchor-state epochs as TDB MJD.

is_maneuver_boundary

A column for storing booleans.

max_propagation_days

A column for storing 64-bit floating point numbers.

object_id

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

object_ids() list[str][source]

Distinct object ids, in first-seen order.

orbit

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.

schema: ClassVar[pa.Schema] = object_id: large_string not null segment_id: large_string not null coverage_start: struct<days: int64, nanos: int64>   child 0, days: int64   child 1, nanos: int64 coverage_end: struct<days: int64, nanos: int64>   child 0, days: int64   child 1, nanos: int64 orbit: struct<orbit_id: large_string, object_id: large_string, coordinates: struct<x: double, y: double, z: (... 459 chars omitted)   child 0, orbit_id: large_string   child 1, object_id: large_string   child 2, 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   child 3, 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   child 4, 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 source: large_string source_version: large_string max_propagation_days: double is_maneuver_boundary: bool
segment_for(time_mjd_tdb: float, object_id: str | None = None) Trajectory | None[source]

Return the single segment whose coverage window contains time.

Coverage windows are half-open [coverage_start, coverage_end). Returns None when no segment covers the time (a gap; fail closed). Raises ValueError when more than one segment matches (an invalid, overlapping trajectory) or when the trajectory holds multiple objects and object_id was not supplied.

segment_id

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

source

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

source_version

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

validate_coverage() Trajectory[source]

Check structural invariants; raise ValueError on violation.

Enforces, per object: coverage_end strictly after coverage_start, each anchor epoch inside its own coverage window, and non-overlapping coverage windows (touching endpoints are allowed because windows are half-open [start, end)).

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

Bases: Table

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.

alpha

A column for storing 64-bit floating point numbers.

collapse(ephemeris: Ephemeris) Ephemeris[source]

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[source]

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[source]

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.

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.

light_time

A column for storing 64-bit floating point numbers.

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]

object_id

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

orbit_id

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

predicted_magnitude_v

A column for storing 64-bit floating point numbers.

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
variant_id

A column for storing large strings (over 231 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.

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

Bases: Table

collapse(orbits: Orbits) Orbits[source]

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[source]

Collapse the variant orbits into a mean and covariance matrix.

Returns:

collapsed_orbits – The collapsed orbits.

Return type:

~adam_core.orbits.orbits.Orbits

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.

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[source]

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’

has_non_gravitational_parameters() bool[source]

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

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]

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.

object_id

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

orbit_id

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

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.

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
variant_id

A column for storing large strings (over 231 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.

without_non_gravitational_parameters() VariantOrbits[source]

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

Subpackages

Submodules