`CustomParameter`#

class CustomParameter(name: str, dimension: int = 1, units: Units | None = None, default=None, physical_type: str | None = None, partial=None, dynamics=None, partial_dynamics_by_param=None, partial_dynamics_by_position=None, partial_dynamics_by_velocity=None, step=None, register: bool = True)#

Bases: object

Declaration of a user-defined solve-for parameter of a custom force model.

A CustomParameter is the script-side counterpart of the built-in estimable parameters (eta_srp, gm, a_fogm, …): it names a new component that may be added to a StateArray, estimated by the orbit-determination filters, and read back inside the acceleration function of a CustomDynamicModel — all from a user script, with no change to the library source.

Constructing the object registers name with register_custom_parameter(), so the parameter passes state-vector validation from that point on.

Two flavours are supported:

static (dynamics=None, the default) — a constant to be estimated, e.g. a drag coefficient. The filter needs only \(\partial \mathbf{a} / \partial p\).
dynamic (dynamics supplied) — a parameter with its own equation of motion \(\dot p = f(\mathbf r, \mathbf v, p, t)\), integrated along with the state. The filter additionally needs \(\partial \dot p / \partial p\), \(\partial \dot p / \partial \mathbf r\) and \(\partial \dot p / \partial \mathbf v\).

Every Jacobian defaults to a central finite difference of the corresponding user function, so a working setup needs no hand-derived partials; supply the analytic callables when accuracy or speed matters.

Parameters:

namestr: State-component name, e.g. "drag_cd". Must be a plain identifier and must not collide with a built-in component name.
dimensionint, optional: Number of scalar elements. Defaults to 1.
unitsUnits, optional: Units of the parameter itself. Used for the state-vector physical-type check and to label the partial derivatives. None (default) means dimensionless / unchecked.
defaultfloat or array_like, optional: Fallback value used when the parameter is absent from the propagated state (i.e. when the model runs without estimating it). Defaults to zeros.
physical_typestr, optional: Unit-dimension name enforced on the state entry (e.g. "Acceleration"). Defaults to None, which skips the check.
partialcallable, optional: \(\partial \mathbf{a} / \partial p\), returning a (3, dimension) array. Defaults to a finite difference of the model’s acceleration.
dynamicscallable, optional: \(\dot p\), returning a (dimension,) array. Supplying it makes the parameter dynamic; it must then be added to the state with dynamics="dynamic".
partial_dynamics_by_paramcallable, optional: \(\partial \dot p / \partial p\), returning (dimension, dimension). Defaults to a finite difference of dynamics.
partial_dynamics_by_positioncallable, optional: \(\partial \dot p / \partial \mathbf r\), returning (dimension, 3). Defaults to a finite difference of dynamics.
partial_dynamics_by_velocitycallable, optional: \(\partial \dot p / \partial \mathbf v\), returning (dimension, 3). Defaults to a finite difference of dynamics.
stepfloat or array_like, optional: Absolute finite-difference step used for this parameter. Defaults to 1e-6 * max(|p|, 1) evaluated at each call.
registerbool, optional: Register the name with StateDefinition on construction. Defaults to True.

Attributes:

acceleration_partial_units: Units of \(\partial \mathbf a / \partial p\).
default: Fallback value used when the parameter is absent from the state.
dimension: Number of scalar elements of this parameter.
dynamics: User callable returning \(\dot p\), or None when static.
is_dynamic: True when the parameter carries its own equation of motion.
name: State-component name of this parameter.
partial: User callable returning \(\partial \mathbf a / \partial p\), or None.
partial_dynamics_by_param: User callable returning \(\partial \dot p / \partial p\), or None.
partial_dynamics_by_position: User callable returning \(\partial \dot p / \partial \mathbf r\), or None.
partial_dynamics_by_velocity: User callable returning \(\partial \dot p / \partial \mathbf v\), or None.
rate_units: Units of \(\dot p\).
units: Units of the parameter value, or None when dimensionless.

Methods

`finite_difference_step`(values)	Return the per-element finite-difference step for values.
`rate_partial_units`(with_respect_to)	Units of a Jacobian of \(\dot p\) w.r.t.
`resolve`(current_state, spice_id)	Read this parameter's current value out of the propagated state.

See also

scarabaeus.CustomDynamicModel: Force model that consumes these parameters.
scarabaeus.StateDefinition: State builder; see custom_param.

Notes

All user callables are called with keyword arguments drawn from the evaluation context; declare only the ones you need. See CustomDynamicModel for the available names.

Examples

A drag coefficient estimated as a constant:

import scarabaeus as scb

cd = scb.CustomParameter("drag_cd", default=2.2)

An exponentially decaying empirical scale factor:

tau = 3600.0
k = scb.CustomParameter(
    "emp_scale",
    default=1.0,
    dynamics=lambda params: -params["emp_scale"] / tau,
)

finite_difference_step(values: ndarray) → ndarray#

Return the per-element finite-difference step for values.

Parameters:

valuesnumpy.ndarray: Current parameter value.

Returns:

numpy.ndarray: Absolute step size for each element. Uses the explicit step given at construction, otherwise a relative step of 1e-6 * max(|p|, 1).

rate_partial_units(with_respect_to: str) → Units#

Units of a Jacobian of \(\dot p\) w.r.t. position or velocity.

Parameters:

with_respect_tostr: "position" or "velocity".

Returns:

Units: Units of the requested Jacobian block.

resolve(current_state: dict, spice_id) → ndarray#

Read this parameter’s current value out of the propagated state.

Parameters:

current_statedict: State mapping (name, spice_id) -> values handed to the force models on every right-hand-side evaluation.
spice_idint or None: SPICE ID of the body owning the parameter.

Returns:

numpy.ndarray: The estimated value when present in the state, otherwise default.

property acceleration_partial_units: Units#: Units of \(\partial \mathbf a / \partial p\).

property default: ndarray#: Fallback value used when the parameter is absent from the state.

property dimension: int#: Number of scalar elements of this parameter.

property dynamics#: User callable returning \(\dot p\), or None when static.

property is_dynamic: bool#: True when the parameter carries its own equation of motion.

property name: str#: State-component name of this parameter.

property partial#: User callable returning \(\partial \mathbf a / \partial p\), or None.

property partial_dynamics_by_param#: User callable returning \(\partial \dot p / \partial p\), or None.

property partial_dynamics_by_position#: User callable returning \(\partial \dot p / \partial \mathbf r\), or None.

property partial_dynamics_by_velocity#: User callable returning \(\partial \dot p / \partial \mathbf v\), or None.

property rate_units: Units#: Units of \(\dot p\).

property units: Units | None#: Units of the parameter value, or None when dimensionless.

exception DimensionError#

Bases: ValueError

Raised when a supplied value does not match the declared dimension.

CustomParameter#

`CustomParameter`#