empyrean.StateSensitivities

class StateSensitivities(table, **kwargs)

Bases: Table

Per-(orbit, epoch) state-transition matrices and tensors.

One row per output epoch; rows are grouped contiguously by orbit_id (matching propagation’s orbit-major output). Filter to one chain with quivr’s standard select before calling the per-chain accessors:

chain = sens.select("orbit_id", "2020 CD3")
t = Epochs.from_mjd([60750.0], scale="tdb")
phi = chain.stms_array()[chain.index_at(t)]

Notes

Matrices are stored row-major flattened in LargeListColumn s:

• stm is the 6×6 STM Φ flattened to length 36 (stm[6·r + c] = Φ[r, c]). None per row when the propagation did not trace an STM for that row — which is the case for a sampling method, and for an analytic method on an orbit with neither an input covariance nor compute_stm set.

• stt is the 6×6×6 STT Ψ flattened to length 216 (stt[36·k + 6·a + b] = Ψ[k, a, b]). None when the propagation method did not carry STTs (anything other than UncertaintyMethod.SECOND_ORDER).

The accessors below operate on whatever rows are present — typically a single chain after select("orbit_id", oid), but work on the full table too when shapes are uniform.

Methods

__init__(table, **kwargs)
apply_mask(mask)	Return a new table with rows filtered to match a boolean mask.
as_column([nullable, metadata])	Embed the Table as a column in another Table.
attributes()	Return a dictionary of the table's attributes.
chunk_counts()	Returns the number of discrete memory chunks that make up each of the Table's underlying arrays.
column(column_name)	Returns the column with the given name as a raw pyarrow ChunkedArray.
drop_duplicates([subset, keep])	Drop duplicate rows from a ~quivr.Table.
empty(**kwargs)	Create an empty instance of the table.
flattened_table()	Completely flatten the Table's underlying Arrow table, taking into account any nested structure, and return the data table itself.
fragmented()	Returns true if the Table has any fragmented arrays.
from_csv(input_file[, validate])	Read a table from a CSV file.
from_dataframe(df[, validate])	Load a DataFrame into the Table.
from_feather(path[, validate])	Read a table from a Feather file.
from_flat_dataframe(df[, validate])	Load a flattened DataFrame into the Table.
from_kwargs([validate, permit_nulls])	Create a Table instance from keyword arguments.
from_parquet(path[, memory_map, ...])	Read a table from a Parquet file.
from_pyarrow(table[, validate, permit_nulls])	Create a new table from a pyarrow Table.
index_at(epoch, *[, atol])	Row index at the given epoch.
invalid_mask()	Return a boolean mask indicating which rows are invalid.
is_valid()	Validate the table against the schema.
kappa(cov_in, *[, i])	Jet2 nonlinearity diagnostic κ.
null_mask()	Return a boolean mask indicating which rows of the entire table are null.
nulls(size, **kwargs)	Create a table with nulls.
orbit_ids_unique()	Unique orbit_id values, in first-seen order.
propagate_covariance(cov_in, *[, i, order])	Forward-propagate a covariance through the chain.
select(column_name, value)	Select from the table by exact match, returning a new Table which only contains rows for which the value in column_name equals value.
separate_invalid()	Separates rows that have invalid data from those that have valid data.
set_column(name, data)	Return a copy of the table with a particular column replaced with new data.
sort_by(by)	Sorts the Table by the given column name (or multiple columns).
stms_array()	Reshape stm to (n_t, 6, 6).
stts_array()	Reshape stt to (n_t, 6, 6, 6).
take(row_indices)	Return a new Table with only the rows at the given indices.
to_csv(path[, attribute_columns])	Write the table to a CSV file.
to_dataframe([flatten, attr_handling])	Returns self as a pandas DataFrame.
to_feather(path, **kwargs)	Write the table to a Feather file.
to_parquet(path, **kwargs)	Write the table to a Parquet file.
to_structarray()	Returns self as a StructArray.
unique_indices([subset, keep])	Get the indices of the first or last occurrence of each unique row in the table.
up_to(epoch)	Subset including rows with epoch_mjd_tdb ≤ the target.
validate()	Validate the table against the schema, raising an exception if invalid.
where(expr)	Return a new table with rows filtered to match an expression.
with_table(table)

Attributes

epoch_mjd_tdb	Output epoch (MJD TDB).
object_id	Object metadata label, if carried on the input orbit.
orbit_id	Orbit primary key (matches the input Orbits.orbit_id).
resolved_kind	Resolved covariance kind at this output epoch (CovarianceKind value: linear / second_order / …), or None if the propagation did not resolve a covariance for this row.
schema
stm	Row-major flattened 6×6 STM (length 36 per row), or None.
stt	Row-major flattened 6×6×6 STT (length 216 per row), or None.
table

Parameters:

• table (Table)

• kwargs (AttributeValueType)

orbit_id

Orbit primary key (matches the input Orbits.orbit_id).

object_id

Object metadata label, if carried on the input orbit.

epoch_mjd_tdb

Output epoch (MJD TDB).

stm

Row-major flattened 6×6 STM (length 36 per row), or None.

stt

Row-major flattened 6×6×6 STT (length 216 per row), or None.

resolved_kind

Resolved covariance kind at this output epoch (CovarianceKind value: linear / second_order / …), or None if the propagation did not resolve a covariance for this row.

orbit_ids_unique()

Unique orbit_id values, in first-seen order.

Return type:

list[str]

stms_array()

Reshape stm to (n_t, 6, 6).

Returns None when every row has a null STM. Null rows within an otherwise-populated chain are filled with NaN. Raises ValueError if the table holds more than one unique orbit_id — filter via select first.

Return type:

ndarray | None

stts_array()

Reshape stt to (n_t, 6, 6, 6).

Returns None when every row has a null STT. Raises ValueError if the table holds more than one unique orbit_id — filter via select first.

Return type:

ndarray | None

index_at(epoch, *, atol=1e-09)

Row index at the given epoch.

epoch is a length-1 Epochs in any time scale; it is converted to MJD TDB and matched within atol. Build one with Epochs.from_mjd([value], scale="tdb") (or scale="utc") — a bare float carries no time scale and is refused.

Raises ValueError if no row matches, or if the table holds more than one unique orbit_id — filter via select first.

Return type:

int

Parameters:

• epoch (Epochs)

• atol (float)

up_to(epoch)

Subset including rows with epoch_mjd_tdb ≤ the target.

epoch is a length-1 Epochs in any time scale.

Return type:

StateSensitivities

Parameters:

epoch (Epochs)

propagate_covariance(cov_in, *, i=None, order='auto')

Forward-propagate a covariance through the chain.

Filter to a single chain via select("orbit_id", oid) first — this method assumes the chain’s STMs share a common t₀.

Parameters:

• cov_in (ndarray) – Input 6×6 covariance at the chain’s start epoch.

• i (int | None) – Row index to evaluate at. None (default) returns the covariance at every chain epoch, shape (n_t, 6, 6).

• order (Literal[1, 2, 'auto']) – 1: linear (Σ = Φ Σ_0 Φᵀ, Δμ = 0). 2: Jet2 second-order Gaussian correction (requires STTs). "auto": order 2 when STTs are present, else order 1.

Return type:

tuple[ndarray, ndarray]

Returns:

(cov_out, delta_mu) ((np.ndarray, np.ndarray)) – (6, 6) / (6,) for scalar i; (n_t, 6, 6) / (n_t, 6) for i=None.

kappa(cov_in, *, i=None)

Jet2 nonlinearity diagnostic κ.

Approximates the departure of the true distribution from a Gaussian centered at the nominal state. Small κ (≲ 0.1) means first-order covariance is adequate; larger κ warrants Jet2 SOG or Gaussian-mixture splitting. Requires STTs. Filter to one chain first.

Return type:

float | ndarray

Parameters:

• cov_in (ndarray)

• i (int | None)

schema: ClassVar[Schema] = orbit_id: large_string not null object_id: large_string epoch_mjd_tdb: double not null stm: large_list<item: double>   child 0, item: double stt: large_list<item: double>   child 0, item: double resolved_kind: large_string