empyrean.BuiltSystem

class BuiltSystem(force_model=ForceModelTier.STANDARD, frame=Frame.ECLIPTICJ2000, encounter_timescale_divisor=None)

Bases: object

A reusable pre-built force-model handle.

Construct with build_system() (or directly). See the module docstring for the identity guard and the cross-thread reuse story.

Parameters:

• force_model (ForceModelTier | str | int) – Force-model tier to freeze. Default ForceModelTier.STANDARD.

• frame (Frame | str | int) – Frame to freeze. Default Frame.ECLIPTICJ2000. For generate_ephemeris() the frame must be Frame.ECLIPTICJ2000 (the ephemeris integration frame).

• encounter_timescale_divisor (float | None) – Encounter-timescale divisor to freeze into the key. None (default) freezes the engine default.

Methods

__init__([force_model, frame, ...])
describe()	Return a full reproducibility summary of the frozen force model plus the kernel manifest captured at construction.
determine(observations[, initial_orbits, ...])	Run the full OD pipeline over every object, through the frozen force model.
evaluate(orbit, observations, *[, config])	Evaluate residuals for an orbit against observations, through the frozen force model.
generate_ephemeris(orbits, observers[, config])	Generate predicted ephemeris through the frozen force model.
propagate(orbits, epochs[, config, ...])	Propagate orbits to target epochs through the frozen force model.
refine(orbit, observations, *[, config])	Refine an orbit with new observations using a Bayesian prior, through the frozen force model.

Attributes

encounter_timescale_divisor	The frozen encounter-timescale divisor (engine default resolved).
force_model	The frozen force-model tier.
frame	The frozen integration/output frame.

property force_model: ForceModelTier

The frozen force-model tier.

property frame: Frame

The frozen integration/output frame.

property encounter_timescale_divisor: float

The frozen encounter-timescale divisor (engine default resolved).

propagate(orbits, epochs, config=None, *, tagged_covariance=False, thrust_arcs=None)

Propagate orbits to target epochs through the frozen force model.

Identical to empyrean.propagate() but reuses the pre-built force model. When config is omitted a default is built from this handle’s frozen force_model / frame so the call always matches the key. If you pass an explicit config whose force model or frame diverges from the frozen key, the identity guard raises — it never silently rebuilds. The result is bit-identical to the one-shot on the matching key.

Parameters:

• orbits (CartesianOrbits | KeplerianOrbits | CometaryOrbits | SphericalOrbits) – As empyrean.propagate(). config defaults to PropagationConfig(force_model=self.force_model, frame=self.frame).

• epochs (Epochs) – As empyrean.propagate(). config defaults to PropagationConfig(force_model=self.force_model, frame=self.frame).

• config (PropagationConfig | None) – As empyrean.propagate(). config defaults to PropagationConfig(force_model=self.force_model, frame=self.frame).

• tagged_covariance (bool) – As empyrean.propagate(). config defaults to PropagationConfig(force_model=self.force_model, frame=self.frame).

• thrust_arcs (Sequence[ThrustParams | None] | None) – As empyrean.propagate(). config defaults to PropagationConfig(force_model=self.force_model, frame=self.frame).

Return type:

PropagationResult

Returns:

PropagationResult

generate_ephemeris(orbits, observers, config=None)

Generate predicted ephemeris through the frozen force model.

Identical to empyrean.generate_ephemeris() but reuses the pre-built force model. The ephemeris pipeline integrates in EclipticJ2000, so this handle must be frozen at Frame.ECLIPTICJ2000 (the default) and the engine-default divisor; a handle frozen otherwise is rejected loudly by the identity guard rather than served under the wrong dynamics.

Parameters:

• orbits (CartesianOrbits | KeplerianOrbits | CometaryOrbits | SphericalOrbits) – As empyrean.generate_ephemeris(). config defaults to an EphemerisConfig carrying this handle’s frozen force_model / frame.

• observers (Observers) – As empyrean.generate_ephemeris(). config defaults to an EphemerisConfig carrying this handle’s frozen force_model / frame.

• config (EphemerisConfig | None) – As empyrean.generate_ephemeris(). config defaults to an EphemerisConfig carrying this handle’s frozen force_model / frame.

Return type:

EphemerisResult

Returns:

EphemerisResult

determine(observations, initial_orbits=None, *, radar=None, config=None)

Run the full OD pipeline over every object, through the frozen force model.

Identical to empyrean.determine(), which see for the batch semantics, the seeding rules, and the return shape. Results are bit-identical to that call on a matching handle.

Return type:

Any

Parameters:

• observations (Any)

• initial_orbits (Any)

• radar (Any)

• config (Any)

evaluate(orbit, observations, *, config=None)

Evaluate residuals for an orbit against observations, through the frozen force model.

Identical to empyrean.evaluate(); no fitting is performed.

Return type:

Any

Parameters:

• orbit (Any)

• observations (Any)

• config (Any)

refine(orbit, observations, *, config=None)

Refine an orbit with new observations using a Bayesian prior, through the frozen force model.

Identical to empyrean.refine(). This is the loop the whole surface exists for: assemble one handle, refine many times through it.

Return type:

Any

Parameters:

• orbit (Any)

• observations (Any)

• config (Any)

describe()

Return a full reproducibility summary of the frozen force model plus the kernel manifest captured at construction.

Every field of the returned SystemDescription is populated — nothing is defaulted.

Return type:

SystemDescription