layup.convert

Attributes

`logger`
`ORBIT_FIT_COLS`
`degree_columns`
`element_order`
`MJD_TO_JD`
`INPUT_READERS`
`_HELIOCENTRIC_INPUT`
`_COV_EQ_TO_ECL`
`_COV_ECL_TO_EQ`
`_covariance_keplerian_xyz_batch`
`_covariance_cometary_xyz_batch`

Functions

`_scale_degree_cov`(arr, fmt, factor[, mask])	Congruence-scale the flattened 6x6 covariance of a structured array.
`_subtract_sun`(coords, vels, sun)	Shift a barycentric equatorial state to heliocentric by subtracting the Sun.
`_to_ecliptic`(coords, vels)	Rotate an equatorial (coords, vels) state pair into ecliptic coordinates.
`get_output_column_names_and_types`(...)	Get the output column names and types for the converted data.
`_rotate_batch`(rot_mat, states)	Column-stacked (3, N) form of sorcha's per-vector rotations.
`_sun_states_by_epoch`(ephem, epochs_mjd)	Sun equatorial state as a (6, N) array, evaluating the ephemeris once per
`_parse_to_bcart_eq`(data, gm_sun, gm_total, sun)	Vectorized `parse_orbit_row`: any input FORMAT -> equatorial barycentric
`_bcart_eq_to_elements`(mu, coords, vels, epoch_mjd, ...)	Vectorized ecliptic Cartesian -> Keplerian/cometary elements.
`_parse_cov_to_bcart_eq`(data, gm_sun, gm_total)	Vectorized `parse_covariance_row_to_CART`: each row's flattened input
`_apply_convert_vectorized`(data, convert_to, ephem, ...)	Vectorized `_apply_convert` for all input/output formats.
`_apply_convert`(data, convert_to[, cache_dir, ...])	Apply the appropriate conversion function to the data
`_apply_convert_rowwise`(data, convert_to, ephem, ...)	Reference per-row implementation of `_apply_convert`.
`convert`(data, convert_to[, num_workers, cache_dir, ...])	Convert a structured numpy array to a different orbital format with support for parallel processing.
`convert_cli`(input, output_file_stem, convert_to[, ...])	Convert an orbit file from one format to another with support for parallel processing.

Module Contents

logger[source]

ORBIT_FIT_COLS = [('csq', 'f8'), ('ndof', 'i4'), ('niter', 'i4'), ('method', 'O'), ('flag', 'i4')][source]

degree_columns[source]

element_order[source]

_scale_degree_cov(arr, fmt, factor, mask=None)[source]

Congruence-scale the flattened 6x6 covariance of a structured array.

Applies diag(s) C diag(s) where s is factor on each of fmt’s degree columns and 1 elsewhere – i.e. the covariance transform for rescaling those state elements by factor. Pass factor = 180/pi when the matching state values were just converted radians->degrees, or pi/180 for the inverse. Restricted to rows in mask when given, else applied to the whole column.

Relies on the invariant that element_order[fmt] indexes the cov_i_j rows/cols (see element_order; guarded by test_element_order_matches_degree_columns).

MJD_TO_JD = 2400000.5[source]

_subtract_sun(coords, vels, sun)[source]: Shift a barycentric equatorial state to heliocentric by subtracting the Sun.

_to_ecliptic(coords, vels)[source]: Rotate an equatorial (coords, vels) state pair into ecliptic coordinates.

INPUT_READERS[source]

get_output_column_names_and_types(primary_id_column_name, has_covariance, extra_cols_to_keep)[source]

Get the output column names and types for the converted data.

Parameters:

primary_id_column_name (str) – The name of the column in the data that contains the primary ID of the object.
has_covariance (bool) – Whether the data has covariance information.
extra_cols_to_keep (list) – List of tuples containing extra column names and dtypes to keep in the output data.

Returns:

A tuple containing two elements: - A dictionary mapping orbit formats to the required column names for that format. - A list of default column dtypes for the output data.

Return type:

tuple

_HELIOCENTRIC_INPUT = ('COM', 'KEP', 'CART')[source]

_rotate_batch(rot_mat, states)[source]

Column-stacked (3, N) form of sorcha’s per-vector rotations.

equatorial_to_ecliptic/ecliptic_to_equatorial use the v @ rot_mat convention (row vectors); for a state stacked as columns that is rot_mat.T @ states.

_sun_states_by_epoch(ephem, epochs_mjd)[source]: Sun equatorial state as a (6, N) array, evaluating the ephemeris once per unique epoch (mirrors parse_orbit_row’s per-epoch sun_dict cache).

_parse_to_bcart_eq(data, gm_sun, gm_total, sun)[source]

Vectorized parse_orbit_row: any input FORMAT -> equatorial barycentric Cartesian (coords, vels), each a (3, N) array.

Mirrors sorcha.ephemeris.simulation_parsing.parse_orbit_row element for element. universal_cartesian solves Kepler’s equation with a numba (non- jax) Halley iteration, so element inputs are converted per row; Cartesian and BCART_EQ inputs are fully vectorized.

_bcart_eq_to_elements(mu, coords, vels, epoch_mjd, cometary)[source]

Vectorized ecliptic Cartesian -> Keplerian/cometary elements.

Closed-form counterpart of universal_keplerian / universal_cometary (validated to reproduce them to ~1e-11; see test_convert_vectorized_matches_rowwise). The closed form covers elliptic orbits; the rare e >= 1 rows are recomputed with the exact routine, which also carries the parabolic/hyperbolic branches.

_COV_EQ_TO_ECL[source]

_COV_ECL_TO_EQ[source]

_covariance_keplerian_xyz_batch[source]

_covariance_cometary_xyz_batch[source]

_parse_cov_to_bcart_eq(data, gm_sun, gm_total)[source]

Vectorized parse_covariance_row_to_CART: each row’s flattened input covariance -> equatorial Cartesian, as an (N, 6, 6) array.

Cartesian inputs are a batched rotation congruence; element inputs use the per-row (numba) parse_covariance_row_to_CART (its Jacobian goes through universal_cartesian, which is not jax-traceable). Assumes any degree-format input covariance has already been rescaled to radians by the caller.

_apply_convert_vectorized(data, convert_to, ephem, gm_sun, gm_total, primary_id_column_name, has_covariance, output_dtype, cols_to_keep)[source]

Vectorized _apply_convert for all input/output formats.

Numerically reproduces the per-row path (_apply_convert_rowwise; pinned by test_convert_vectorized_matches_rowwise) while avoiding the per-row jax dispatch, per-row ephemeris query and per-row struct-array build. ~250x for Cartesian/BCART_EQ inputs (the bulk case), ~30x for element inputs (bounded by the per-row universal_cartesian Kepler solve; element-input covariances likewise fall back to the per-row Jacobian).

_apply_convert(data, convert_to, cache_dir=None, primary_id_column_name=None, extra_cols_to_keep=None)[source]

Apply the appropriate conversion function to the data

Parameters:

data (numpy structured array) – The data to convert.
convert_to (str) – The orbital format to convert the data to. Must be one of: “BCART”, “BCART_EQ”, “BCOM”, “BKEP”, “CART”, “COM”, “KEP”
cache_dir (str, optional) – The base directory for downloaded files.
primary_id_column_name (str, optional) – The name of the column in the data that contains the primary ID of the object.
extra_cols_to_keep (list, optional) – List of tuples containing extra column names and dtypes to keep in the output data.

Returns:

data – The converted data

Return type:

numpy structured array

_apply_convert_rowwise(data, convert_to, ephem, gm_sun, gm_total, primary_id_column_name, has_covariance, output_dtype, cols_to_keep)[source]

Reference per-row implementation of _apply_convert.

Superseded in production by _apply_convert_vectorized (which reproduces it to ~1e-11); retained as the equivalence oracle for test_convert_vectorized_matches_rowwise.

convert(data, convert_to, num_workers=1, cache_dir=None, primary_id_column_name='ObjID', extra_cols_to_keep=None)[source]

Convert a structured numpy array to a different orbital format with support for parallel processing.

Parameters:

data (numpy structured array) – The data to convert.
convert_to (str) – The format to convert the data to. Must be one of: “BCART_EQ”, “BCOM”, “BKEP”, “CART”, “COM”, “KEP”
num_workers (int, optional (default=1)) – The number of workers to use for parallel processing.
cache_dir (str, optional) – The base directory for downloaded files.
primary_id_column_name (str, optional (default="ObjID")) – The name of the column in the data that contains the primary ID of the object.
extra_cols_to_keep (list, optional) – List of tuples containing additional column names and dtypes to keep in the output data.

Returns:

data – The converted data

Return type:

numpy structured array

convert_cli(input: str, output_file_stem: str, convert_to: Literal['BCART', 'BCART_EQ', 'BCOM', 'BKEP', 'CART', 'COM', 'KEP'], file_format: Literal['csv', 'hdf5'] = 'csv', chunk_size: int = 10000, num_workers: int = -1, cli_args: dict = None)[source]

Convert an orbit file from one format to another with support for parallel processing.

Note that the output file will be written in the caller’s current working directory.

Parameters:

input (str) – The path to the input file.
output_file_stem (str) – The stem of the output file.
convert_to (str) – The format to convert the input file to. Must be one of: “BCART”, “BCART_EQ”, “BCOM”, “BKEP”, “CART”, “COM”, “KEP”
file_format (str, optional (default="csv")) – The format of the output file. Must be one of: “csv”, “hdf5”
chunk_size (int, optional (default=10_000)) – The number of rows to read in at a time.
num_workers (int, optional (default=-1)) – The number of workers to use for parallel processing of the individual chunk. If -1, the number of workers will be set to the number of CPUs on the system.
cli_args (argparse, optional (default=None)) – The argparse object that was created when running from the CLI.