MultiFilterOD#
- class MultiFilterOD(filters: list, global_param_names: List[str], global_apriori_cov: ndarray | None = None, subtract_arc_priors: bool = True)#
Bases:
objectMulti-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
FilterODsubclass). 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=Truethe arc’s own apriori information is removed so it is counted only once viaglobal_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 belowconvergence_threshold_cost(seeconvergence_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 toFalseto 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.FilterODBase filter class used per-arc.
scarabaeus.LKFSequential covariance-form filter.
scarabaeus.SRIFSequential square-root information filter.
scarabaeus.LSBBatch least-squares estimator.
scarabaeus.SRIFBBatch 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_covis 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'. Seefit().- 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 offilters. 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 thecallbackoffit()is between the iterations of one filter: a sigma set on an arc’s model (set_measurement_sigmas(), ormodel.sigma = ...) or an outlier flagged throughMeasurementSpec.flagtakes 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_globalattribute contains:x_G— (n_G,) combined absolute estimateP_G— (n_G, n_G) combined covarianceglobal_param_names— sorted list of global parameter namesarc_global_abs— per-arc absolute estimatesn_outer— outer iterations performedconverged— True if outer loop convergedcriterion— convergence criterion usedcost— total weighted cost of the last outer stepcost_normalized— that cost divided byn_residualscost_relative_change— its relative change vs. the previous stepn_residuals— residuals contributing tocost
- Raises:
- ConvergenceCriterionError
If
convergence_criterionis not one of the accepted values.
Notes
Reweighting the data from
callbackchanges the scale of the cost, so the cost test of the next outer iteration compares two differently weighted costs; preferconvergence_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:
ValueErrorRaised when an arc solution lacks the histories needed at t_0.
- exception ConvergenceCriterionError#
Bases:
ValueErrorRaised when an unknown convergence criterion is requested.