@spec covariance_from_jacobian([[number()]], number()) ::
  {:ok, [[float()]]} | {:error, atom()}

Fitted parameter covariance directly from a converged solve's design matrix and cost.

Scales (J^T J)^-1 by the post-fit reduced chi-square 2 * cost / (m - n), the same scale scipy.optimize.curve_fit applies to its pcov. jacobian is the m-by-n design matrix and cost the optimum 0.5 * dot(r, r). The redundancy comes from the Jacobian's dimensions, so no residual or parameter vectors are needed. Requires positive redundancy m > n.

Returns {:ok, covariance_rows} or {:error, :singular_jacobian | :invalid_input}.

@spec eci_to_rtn6(mat6(), state()) :: {:ok, mat6()} | {:error, term()}

Transform a 6x6 inertial ECI state covariance to RTN at state.

@spec error_ellipse_2x2([[number()]], number()) ::
  {:ok,
   %{
     confidence: float(),
     chi_square_scale: float(),
     semi_major: float(),
     semi_minor: float(),
     orientation_rad: float()
   }}
  | {:error, atom()}

Confidence ellipse from an arbitrary 2x2 covariance block.

The semi-axes are scaled by the two-degree-of-freedom chi-square quantile -2 ln(1 - confidence) applied to the eigenvalues of the symmetrized block. Returns {:ok, %{confidence:, chi_square_scale:, semi_major:, semi_minor:, orientation_rad:}} or {:error, reason}.

@spec extract_pos_cov([float()]) :: {:ok, mat3()} | {:error, String.t()}

Extract a 3x3 position covariance matrix from a 6-element lower triangle (RTN). Expected order: CR_R (0,0), CT_R (1,0), CT_T (1,1), CN_R (2,0), CN_T (2,1), CN_N (2,2).

@spec from_diagonal6([number()]) :: {:ok, mat6()} | {:error, atom()}

Build a 6x6 covariance matrix from six diagonal variances.

@spec hessian_trace([[number()]]) :: float()

Trace of the Gauss-Newton Hessian approximation J^T J, i.e. the sum of the squared column norms of jacobian. No inverse is formed.

@spec interpolate_psd6(mat6(), mat6(), number()) :: {:ok, mat6()} | {:error, atom()}

PSD-preserving interpolation between two 6x6 covariance matrices.

@spec km_to_m6(mat6()) :: {:ok, mat6()} | {:error, atom()}

Convert a 6x6 state covariance from kilometre units to metre units.

@spec m_to_km6(mat6()) :: {:ok, mat6()} | {:error, atom()}

Convert a 6x6 state covariance from metre units to kilometre units.

@spec normal_covariance([[number()]], number()) ::
  {:ok, [[float()]]} | {:error, atom()}

Parameter covariance variance_scale * (J^T J)^-1 from a design (Jacobian) matrix.

jacobian is an m-by-n matrix (a list of m rows of n numbers) with m >= n. The covariance is formed from the thin SVD of J directly, the same quantity (and construction) scipy.optimize.curve_fit reports as pcov: pass the post-fit reduced chi-square as variance_scale for the fitted covariance, or 1.0 for the bare (J^T J)^-1 cofactor.

Returns {:ok, covariance_rows} or {:error, :singular_jacobian | :invalid_input}.

@spec positive_semidefinite?(mat3()) :: boolean()

Check if a 3x3 matrix is symmetric and positive semidefinite (PSD).

A symmetric 3x3 matrix is PSD if all its principal minors are non-negative.

@spec rtn_to_eci6(mat6(), state()) :: {:ok, mat6()} | {:error, term()}

Transform a 6x6 RTN state covariance to inertial ECI at state.

@spec rtn_to_eci(mat3(), vec3(), vec3()) :: {:ok, mat3()} | {:error, String.t()}

Transform a 3x3 RTN covariance matrix to ECI.

@spec symmetric?(any()) :: boolean()

Check if a matrix is symmetric.

@spec transport_segments6(mat6(), [map()], keyword()) ::
  {:ok, [mat6()]} | {:error, term()}

Transport a 6x6 covariance through precomputed state-transition segments.

@spec valid_matrix?(any()) :: boolean()

Validate that the input is a 3x3 numeric matrix.

@spec validate6(mat6()) ::
  {:ok, %{symmetric: boolean(), positive_semidefinite: boolean()}}
  | {:error, atom()}

Validate a 6x6 covariance matrix for symmetry and positive semidefiniteness.