MultiFilterOD#

class MultiFilterOD(filters: list, global_param_names: List[str], global_apriori_cov: ndarray | None = None, subtract_arc_priors: bool = True)#

Bases: object

Multi-arc orbit determination combining N independent FilterOD instances.

Each arc has its own propagator, measurements, settings, and filter type (SRIF, LKF, LSB, SRIFB, or any FilterOD subclass). The class runs all arcs to convergence and then fuses their estimates of any parameters designated as global (shared across arcs) using the NAPEOS partitioned normal-equation formulation with Schur-complement reduction.

Algorithm overview

The full state vector of arc \(i\) is partitioned into arc-local parameters \(\mathbf{a}_i\) and global (shared) parameters \(\mathbf{g}\):

\[\begin{split}\mathbf{x}_i = \begin{bmatrix} \mathbf{a}_i \\ \mathbf{g} \end{bmatrix}\end{split}\]

Step 1 — Per-arc convergence. Each arc filter is run to inner convergence independently, yielding a state deviation \(\delta\mathbf{x}_{0,i}\) and covariance \(P_{0,i}\) referred to the arc’s initial epoch \(t_0\).

The row used is the one the arc correction is built from: the first smoothed epoch when the arc was smoothed, otherwise the last filtered epoch \(t_r\). Every filter type, batch (LSB, SRIFB) included, stores its rows at their own epoch, so the row is mapped back with the cumulative state-transition matrix \(\Phi\):

\[M = \Phi(t_0)\,\Phi(t_r)^{-1}, \qquad \delta\mathbf{x}_{0,i} = M\,\delta\mathbf{x}_{r,i}, \qquad P_{0,i} = M\,P_{r,i}\,M^T\]

Step 2 — Normal equations. The information matrix and right-hand side for arc \(i\) are

\[N_i = P_{0,i}^{-1}, \qquad \mathbf{b}_i = N_i\,\delta\mathbf{x}_{0,i}\]

When subtract_arc_priors=True the arc’s own apriori information is removed so it is counted only once via global_apriori_cov:

\[N_i \leftarrow N_i - P_{\mathrm{apr},i}^{-1}\]

Step 3 — Partitioning and Schur complement. The normal matrix is split into local and global blocks:

\[\begin{split}N_i = \begin{bmatrix} N_{a,i} & N_{ag,i} \\ N_{ag,i}^T & N_{g,i} \end{bmatrix}, \qquad \mathbf{b}_i = \begin{bmatrix} \mathbf{b}_{a,i} \\ \mathbf{b}_{g,i} \end{bmatrix}\end{split}\]

Local parameters are eliminated via the Schur complement:

\[ \begin{align}\begin{aligned}\tilde{N}_{g,i} = N_{g,i} - N_{ag,i}^T N_{a,i}^{-1} N_{ag,i}\\\tilde{\mathbf{b}}_{g,i} = \mathbf{b}_{g,i} - N_{ag,i}^T N_{a,i}^{-1} \mathbf{b}_{a,i}\end{aligned}\end{align} \]

Step 4 — Global combination. An arbitrary reference \(\bar{\mathbf{g}}\) (arc-0 absolute estimate) is used to form the combined information and normal vector:

\[ \begin{align}\begin{aligned}\Lambda = P_{\mathrm{prior}}^{-1} + \sum_{i=1}^{N} \tilde{N}_{g,i}\\\hat{\mathbf{n}} = \sum_{i=1}^{N} \Bigl( \tilde{\mathbf{b}}_{g,i} + \tilde{N}_{g,i}\, (\mathbf{x}_{G,i} - \bar{\mathbf{g}}) \Bigr)\end{aligned}\end{align} \]

giving the combined global estimate and covariance:

\[\hat{P}_G = \Lambda^{-1}, \qquad \hat{\mathbf{x}}_G = \bar{\mathbf{g}} + \hat{P}_G\,\hat{\mathbf{n}}\]

The solution is insensitive to the choice of \(\bar{\mathbf{g}}\).

Step 5 — Local back-substitution. With \(\hat{P}_G\) known, the arc-local correction is recovered by a second Schur inversion:

\[ \begin{align}\begin{aligned}\hat{P}_{a,i} = \bigl( N_{a,i} - N_{ag,i}\,\hat{P}_G\,N_{ag,i}^T \bigr)^{-1}\\\Delta\mathbf{x}_{a,i} = \hat{P}_{a,i}\, \bigl( \mathbf{b}_{a,i} - N_{ag,i}\,\hat{P}_G\,\hat{\mathbf{n}} \bigr)\end{aligned}\end{align} \]

Step 6 — Reinitialization. Each arc is restarted from the corrected reference trajectory \(\mathbf{x}_{\mathrm{ref}} + [\Delta\mathbf{x}_{a,i};\,\Delta\mathbf{x}_G]\) and the outer loop repeats until the relative RMS change in \(\hat{\mathbf{x}}_G\) falls below convergence_threshold, or the relative change of the total weighted cost \(J/n\) falls below convergence_threshold_cost (see convergence_criterion).

Parameters:
filterslist of FilterOD

One filter per arc, fully configured (propagator, measurements, settings). All filters must estimate the same set of global parameters (matching base names) plus their own arc-local parameters.

global_param_nameslist of str

Base names of parameters shared across arcs (e.g. ["gm", "cnm_2_0"]). Every arc must estimate at least one such parameter.

global_apriori_covnp.ndarray of shape (n_G, n_G), optional

Apriori covariance for the global parameter vector. Enters as \(P_{\mathrm{prior}}^{-1}\) in the global combination step. Set to None (default) to omit (improper prior).

subtract_arc_priorsbool, optional

If True (default), each arc’s own apriori covariance \(P_{\mathrm{apr},i}\) is subtracted from \(N_i\) before combination, preventing the prior from being counted once per arc. Set to False to retain the classic behaviour in which every arc contributes its full posterior information matrix including the prior.

Methods

fit([max_outer_iters, max_inner_iters, ...])

Run multi-arc orbit determination.

Raises:
ValueError

If any arc filter has flag_sequence=True (multi-leg arcs are not supported).

ValueError

If any arc filter estimates no parameter whose name appears in global_param_names.

See also

scarabaeus.FilterOD

Base filter class used per-arc.

scarabaeus.LKF

Sequential covariance-form filter.

scarabaeus.SRIF

Sequential square-root information filter.

scarabaeus.LSB

Batch least-squares estimator.

scarabaeus.SRIFB

Batch square-root information estimator.

Notes

  • Multi-leg (sequence) arcs are not supported; each arc must be a single-leg filter.

  • All arcs must estimate the same set of global parameters (matched by base name); the dimension \(n_G\) must be consistent across arcs.

  • The outer loop reinitializes arcs after each global combination; the number of outer iterations required is typically 2–4 for well-posed problems.

  • If no global_apriori_cov is supplied, the combined problem has an improper prior and the solution is determined solely by the arc data.

References

[1]

French, A. S., Leonard, J. M., Geeraert, J. L., Page, B. R., Antreasian, P. G., Moreau, M. C., McMahon, J. W., Scheeres, D. J., & the OSIRIS-REx Team. “Multi-Arc Filtering During the Navigation Campaign of the OSIRIS-REx Mission.” KinetX / NASA GSFC / University of Colorado. (Primary reference for the partitioned normal-equation and Schur-complement multi-arc formulation implemented here.)

[2]

European Space Operations Centre (2009). “NAPEOS — Navigation Package for Earth Orbiting Satellites,” May 2009, pp. 1–150.

[3]

Tapley, B. D., Schutz, B. E., & Born, G. H. (2004). Statistical Orbit Determination. Elsevier Academic Press. ISBN 978-0-12-683630-1.

[4]

Bierman, G. J. (1977). Factorization Methods for Discrete Sequential Estimation. Academic Press.

fit(max_outer_iters: int = 5, max_inner_iters: int = 10, convergence_threshold: float = 1e-06, convergence_threshold_cost: float = 0.001, convergence_criterion: str = 'any', if_sequential_smooth: bool = False, traj_name: str | None = None, verbose: bool = True, callback: Callable | None = None) → List[SolutionOD]#

Run multi-arc orbit determination.

Parameters:
max_outer_itersint

Maximum outer (global-combination) iterations.

max_inner_itersint

Maximum inner (per-arc) iterations per outer step.

convergence_thresholdfloat

Relative RMS convergence threshold for both inner and outer loops.

convergence_threshold_costfloat

Threshold on the relative change of the normalised weighted cost \(J/n = \sum_i (r_i/\sigma_i)^2 / n\) between iterations. In the outer loop the cost is summed over all arcs. Weakly observable global parameters keep drifting between outer iterations without improving the fit; this test declares convergence in that case.

convergence_criterionstr

How the RMS and cost tests are combined, for both loops: 'any' (default), 'deviation', 'cost', or 'both'. See fit().

if_sequential_smoothbool

Apply smoothing to each arc after inner convergence.

traj_namestr, optional

Base name for trajectory files; arc index and outer iteration number are appended automatically.

verbosebool

Print progress banners.

callbackcallable, optional

Called as callback(multi_filter, outer, arc_solutions) after every outer iteration, with this object, the outer iteration number and the solution of each arc in the order of filters. It runs once the outer convergence test is done (the first outer iteration has none) and before the arcs are reinitialised for the next one. Its return value is ignored. It is the place to reweight or edit the data between outer iterations, as the callback of fit() is between the iterations of one filter: a sigma set on an arc’s model (set_measurement_sigmas(), or model.sigma = ...) or an outlier flagged through MeasurementSpec.flag takes effect when that arc’s datasets are rebuilt for the next outer iteration, so one made after the last outer iteration does nothing within this call. The inner fit of each arc runs without a callback. Defaults to None.

Returns:
list[SolutionOD]

One solution per arc from the final outer iteration. Each solution’s multi_arc_global attribute contains:

  • x_G — (n_G,) combined absolute estimate

  • P_G — (n_G, n_G) combined covariance

  • global_param_names — sorted list of global parameter names

  • arc_global_abs — per-arc absolute estimates

  • n_outer — outer iterations performed

  • converged — True if outer loop converged

  • criterion — convergence criterion used

  • cost — total weighted cost of the last outer step

  • cost_normalized — that cost divided by n_residuals

  • cost_relative_change — its relative change vs. the previous step

  • n_residuals — residuals contributing to cost

Raises:
ConvergenceCriterionError

If convergence_criterion is not one of the accepted values.

Notes

Reweighting the data from callback changes the scale of the cost, so the cost test of the next outer iteration compares two differently weighted costs; prefer convergence_criterion='deviation' across a change of sigmas.

Examples

>>> # Loosen the range sigma of every arc after the first outer iteration
>>> def reweight(multi, outer, arc_solutions):
...     if outer == 1:
...         for filt in multi.filters:
...             filt.set_measurement_sigmas({"GS1 Range": ArrayWUnits(5.0, m)})
>>> arc_solutions = multi.fit(callback=reweight)
exception ArcSolutionError#

Bases: ValueError

Raised when an arc solution lacks the histories needed at t_0.

exception ConvergenceCriterionError#

Bases: ValueError

Raised when an unknown convergence criterion is requested.