Math

math

HermiteEndpoint

A position/velocity/acceleration triple at a single grid endpoint.

Used as the input to quintic_hermite. All three components share a consistent time-derivative chain: velocity is the time derivative of position and acceleration is the time derivative of velocity. Units are not enforced; the units returned by quintic_hermite are inherited from the units used here.

Attributes:

Name	Type	Description
position	tuple[float, float, float]	Position at the endpoint [any spatial unit].
velocity	tuple[float, float, float]	Velocity at the endpoint [position unit / s].
acceleration	tuple[float, float, float]	Acceleration at the endpoint [position unit / s²].

acceleration property writable

Acceleration at the endpoint [position unit / s²].

position property writable

Position at the endpoint [any spatial unit].

velocity property writable

Velocity at the endpoint [position unit / s].

__init__(position, velocity, acceleration)

Creates a HermiteEndpoint from position, velocity, and acceleration.

Parameters:

Name	Type	Description	Default
position	tuple[float, float, float]	Position at the endpoint [any spatial unit].	required
velocity	tuple[float, float, float]	Velocity at the endpoint [position unit / s].	required
acceleration	tuple[float, float, float]	Acceleration at the endpoint [position unit / s²].	required

actan(y, x)

Four-quadrant arctangent wrapped into [0, 2π).

Equivalent to wrap_angle(atan2(y, x)) but avoids the modulo: atan2 returns (−π, π], so a single conditional +2π suffices. Matches the ACTAN convention used by SGP4-family reference implementations, which keep orbital angles in [0, 2π) rather than (−π, π].

Parameters:

Name	Type	Description	Default
y	float	Ordinate [any unit].	required
x	float	Abscissa [same unit as y].	required

Returns:

Type	Description
float	atan2(y, x) mapped into [0, 2π) [rad].

apply_4pt_coefficients(coeffs, ys)

Applies four barycentric coefficients to four function values.

Computes the weighted sum c0·y0 + c1·y1 + c2·y2 + c3·y3. The coefficients must come from get_4pt_barycentric_coefficients for the same set of nodes.

Parameters:

Name	Type	Description	Default
coeffs	tuple[float, float, float, float]	Normalized barycentric coefficients [dimensionless].	required
ys	tuple[float, float, float, float]	Function values at the four nodes [any unit].	required

Returns:

Type	Description
float	Interpolated value [same unit as ys].

cubic_hermite(p0, v0, p1, v1, h, tau)

Cubic Hermite interpolation using position and velocity at both endpoints.

Achieves O(h⁴) position accuracy and O(h³) velocity accuracy by satisfying four conditions: position and velocity at tau = 0 and tau = 1. The returned vectors inherit the units of the inputs.

Parameters:

Name	Type	Description	Default
p0	tuple[float, float, float]	Position at tau = 0 [any spatial unit].	required
v0	tuple[float, float, float]	Velocity at tau = 0 [spatial unit / s].	required
p1	tuple[float, float, float]	Position at tau = 1 [same unit as p0].	required
v1	tuple[float, float, float]	Velocity at tau = 1 [same unit as v0].	required
h	float	Step duration [s; must be non-zero].	required
tau	float	Fractional position within the step [dimensionless; 0..=1].	required

Returns:

Type	Description
tuple[float, float, float]	(position, velocity) interpolated at tau in the same units as
tuple[float, float, float]	the inputs.

get_4pt_barycentric_coefficients(x, xs, weights)

Computes the four normalized barycentric coefficients at x.

Uses the precomputed weights returned by get_4pt_barycentric_weights. If x coincides exactly with a node, the corresponding coefficient is set to 1.0 and all others to 0.0 (exact passthrough, no division).

Parameters:

Name	Type	Description	Default
x	float	Query point [same unit as xs].	required
xs	tuple[float, float, float, float]	The four interpolation nodes used to compute weights [same unit as x].	required
weights	tuple[float, float, float, float]	Barycentric weights from get_4pt_barycentric_weights.	required

Returns:

Type	Description
float	Four normalized coefficients (c0, c1, c2, c3) that sum to 1.0
float	[dimensionless].

get_4pt_barycentric_weights(xs)

Computes the four barycentric weights for four interpolation nodes.

The weights are the reciprocals of the node-to-node products: w_i = 1 / ∏_{j≠i} (x_i − x_j). Precomputing them once and reusing them across many get_4pt_barycentric_coefficients calls avoids repeated division.

Parameters:

Name	Type	Description	Default
xs	tuple[float, float, float, float]	Four strictly distinct interpolation nodes (x0, x1, x2, x3) [any unit; must be distinct].	required

Returns:

Type	Description
float	Four barycentric weights (w0, w1, w2, w3) [inverse of the unit of
float	xs cubed].

get_fractional_modulo(a, b)

Returns the truncated-division remainder a − trunc(a / b) × b.

Unlike Python's % operator, the result carries the sign of a for negative operands, matching the C/Fortran truncation semantics used by several astrodynamics reference implementations.

Parameters:

Name	Type	Description	Default
a	float	Dividend [any unit].	required
b	float	Divisor [same unit as a; must be non-zero].	required

Returns:

Type	Description
float	Remainder with the same sign as a [same unit as a].

linear_regression(t, y)

Ordinary least-squares fit of y = intercept + slope · t.

Minimizes the squared residuals of the supplied (t, y) samples; pairing is positional, so t and y must be the same length.

Parameters:

Name	Type	Description	Default
t	list[float]	Independent-variable samples [any units]; must match y in length.	required
y	list[float]	Dependent-variable samples [any units].	required

Returns:

Type	Description
tuple[float, float] | None	(intercept, slope) of the best-fit line — intercept in the
tuple[float, float] | None	units of y, slope in units of y per unit of t — or
tuple[float, float] | None	None when fewer than two samples are supplied, the lengths differ,
tuple[float, float] | None	or every t is identical (leaving the slope undetermined).

mean(values)

Arithmetic mean of a sequence of samples.

Parameters:

Name	Type	Description	Default
values	list[float]	Samples to average [any units].	required

Returns:

Type	Description
float | None	The mean in the units of values, or None when values is
float | None	empty.

median(values)

Median of a sequence of samples.

For an even-length input the median is the arithmetic mean of the two middle values. NaN values compare as equal to everything, so filter them out beforehand if the input may contain any.

Parameters:

Name	Type	Description	Default
values	list[float]	Samples [any units].	required

Returns:

Type	Description
float | None	The median in the units of values, or None when values is
float | None	empty.

quintic_hermite(start, end, h, tau)

Quintic Hermite interpolation using position, velocity, and acceleration.

Achieves O(h⁶) position accuracy and O(h⁵) velocity accuracy by satisfying six conditions: position, velocity, and acceleration at tau = 0 and tau = 1. The returned vectors inherit the units of the endpoint inputs.

Parameters:

Name	Type	Description	Default
start	HermiteEndpoint	State at tau = 0.	required
end	HermiteEndpoint	State at tau = 1. Must share units with start.	required
h	float	Step duration [s; must be non-zero].	required
tau	float	Fractional position within the step [dimensionless; 0..=1].	required

Returns:

Type	Description
tuple[float, float, float]	(position, velocity) interpolated at tau in the same units as
tuple[float, float, float]	the inputs.

rms(values)

Root-mean-square of a sequence of samples.

Computes sqrt(Σ xᵢ² / n). This is the canonical RMS used across the estimation stack — batch least squares, the EKF/UKF filters, the adaptive estimator, and the association reports.

Parameters:

Name	Type	Description	Default
values	list[float]	Samples [any units].	required

Returns:

Type	Description
float | None	The RMS in the units of values, or None when no samples are
float | None	supplied.

safe_acos(x)

Clamps x to [-1, 1] then takes acos.

Guards against NaN results when x strays just outside the valid acos domain due to floating-point rounding.

Parameters:

Name	Type	Description	Default
x	float	Argument [dimensionless; clamped to -1..1].	required

Returns:

Type	Description
float	acos(clamp(x, -1, 1)) [rad; 0..π].

safe_asin(x)

Clamps x to [-1, 1] then takes asin.

Guards against NaN results when x strays just outside the valid asin domain due to floating-point rounding.

Parameters:

Name	Type	Description	Default
x	float	Argument [dimensionless; clamped to -1..1].	required

Returns:

Type	Description
float	asin(clamp(x, -1, 1)) [rad; -π/2..π/2].

safe_ln(x)

Natural logarithm with a finite floor for non-positive arguments.

Prevents -inf or NaN from propagating through log-sum arithmetic (e.g. Bayesian evidence calculations) when an input is zero or negative because of underflow or numerical noise.

Parameters:

Name	Type	Description	Default
x	float	Argument [dimensionless].	required

Returns:

Type	Description
float	ln(x) when x > 0; ln(1e-300) otherwise [dimensionless].

wrap_angle(angle)

Wraps an angle into [0, 2π).

Parameters:

Name	Type	Description	Default
angle	float	Input angle [rad; any value].	required

Returns:

Type	Description
float	Equivalent angle in [0, 2π) [rad].

wrap_degrees(angle)

Wraps an angle in degrees into [0, 360).

Parameters:

Name	Type	Description	Default
angle	float	Input angle [deg; any value].	required

Returns:

Type	Description
float	Equivalent angle in [0, 360) [deg].

wrap_delta_angle(delta)

Wraps an angular difference into (−π, π].

Useful for computing the shortest signed arc between two angles.

Parameters:

Name	Type	Description	Default
delta	float	Angular difference [rad; any value].	required

Returns:

Type	Description
float	Equivalent difference in (−π, π] [rad].