Integrator API

BiDirectionalInterpolator

Bases: BatchableObject

Dense interpolator with forward and backward coverage from one reference epoch.

Parameters:

Name	Type	Description	Default
t0_jd1	Float[Array, ...]	Reference epoch in split Julian Date form.	required
t0_jd2	Float[Array, ...]	Reference epoch in split Julian Date form.	required
t_min_jd1	Float[Array, ...]	Lower bound of the covered epoch range, in split Julian Date form.	required
t_min_jd2	Float[Array, ...]	Lower bound of the covered epoch range, in split Julian Date form.	required
t_max_jd1	Float[Array, ...]	Upper bound of the covered epoch range, in split Julian Date form.	required
t_max_jd2	Float[Array, ...]	Upper bound of the covered epoch range, in split Julian Date form.	required
sol_fwd	Solution	Dense forward solution from the reference epoch toward later times.	required
sol_bwd	Solution	Dense backward solution from the reference epoch toward earlier times.	required

Notes

The interpolator stores two dense solutions. Evaluation picks sol_fwd for epochs at or after the reference epoch, and sol_bwd for earlier epochs.

shape property

Batch shape of the interpolator.

is_covered(jd1, jd2, grid=False)

Check whether epochs are inside the covered range.

Parameters:

Name	Type	Description	Default
jd1	Float[Array, ...]	Query epochs in split Julian Date form.	required
jd2	Float[Array, ...]	Query epochs in split Julian Date form.	required
grid	bool	If True, use the Cartesian product of the interpolator batch and the time batch. If False, use point-wise broadcasting.	False

Returns:

Type	Description
Bool[Array, ...]	Coverage mask for the queried epochs.

Notes

Vectorize :func:difforb.integrator.integrator._is_covered_scalar.

evaluate(jd1, jd2, grid=False)

Evaluate the interpolated state at the requested epochs.

Parameters:

Name	Type	Description	Default
jd1	Float[Array, ...]	Query epochs in split Julian Date form.	required
jd2	Float[Array, ...]	Query epochs in split Julian Date form.	required
grid	bool	If True, use the Cartesian product of the interpolator batch and the time batch. If False, use point-wise broadcasting.	False

Returns:

Type	Description
tuple[Float[Array, '... 3'], Float[Array, '... 3']]	Interpolated Cartesian position and velocity in au and au / day.

Notes

Vectorize :func:difforb.integrator.integrator._evaluate_scalar.

__call__(jd1, jd2, grid=False)

Evaluate the interpolated state at the requested epochs.

Parameters:

Name	Type	Description	Default
jd1	Float[Array, ...]	Query epochs in split Julian Date form.	required
jd2	Float[Array, ...]	Query epochs in split Julian Date form.	required
grid	bool	If True, use the Cartesian product of the interpolator batch and the time batch. If False, use point-wise broadcasting.	False

Returns:

Type	Description
tuple[Float[Array, '... 3'], Float[Array, '... 3']]	Interpolated Cartesian position and velocity in au and au / day.

Notes

This is a thin alias of :evaluate.

NumericalIntegrator(method='IAS15', tol=1e-09, max_steps=4096, *, rtol=None, atol=None, initial_step=1e-06, ias15_adaptive_mode=2, ias15_safety_factor=0.25, ias15_min_step=0.0)

Bases: Module

Numerical propagator for orbit integration.

This wrapper provides a compact user-facing API around the underlying diffrax solvers and the custom IAS15 implementation. It builds the solver object, the step-size controller, and return the bidirectional dense-output integrator :class:BiDirectionalInterpolator.

Notes

The current implementation always enables dense output and uses forward-mode differentiation internally. These behaviors are part of the runtime contract of :meth:__call__ and are therefore not exposed as constructor options.

Create a numerical integrator with method-specific adaptive controls.

Parameters:

Name	Type	Description	Default
method	(IAS15, DOPRI8, DOPRI5)	Integration method name. The value is case-insensitive and is normalized to upper case internally. "IAS15": the complete implementation of IAS15 under the diffrax framework. "DOPRI8": 8th-order Dormand-Prince solver from diffrax. "DOPRI5": 5th-order Dormand-Prince solver from diffrax.	"IAS15"
tol	float or None	Compatibility shorthand tolerance. For "DOPRI8" and "DOPRI5", this acts as the fallback value used to fill missing rtol or atol: if only tol is given, then rtol = atol = tol; if tol and rtol are given, then atol = tol; if tol and atol are given, then rtol = tol. For "IAS15", only the absolute tolerance is meaningful, so tol is interpreted as the fallback value for atol.	1e-9
max_steps	int	Maximum number of adaptive steps allowed in each forward or backward solve.	4096
rtol	float or None	Relative tolerance for "DOPRI8" and "DOPRI5". If both rtol and atol are provided, they are used directly. If only rtol is provided, then tol must also be provided so that atol can be inferred. This option is invalid for "IAS15" and will raise ValueError.	None
atol	float or None	Absolute tolerance used by the adaptive step controller. For "DOPRI8" and "DOPRI5", this is the absolute component of diffrax.PIDController. For "IAS15", this is the only effective error threshold and is passed to :class:IAS15StepSizeController. If omitted, the value is inferred from tol.	None
initial_step	float	Absolute value of the initial trial step size, in days. The propagator always starts the forward solve with +initial_step and the backward solve with -initial_step. This parameter only controls the first trial step; subsequent step sizes are chosen adaptively by the selected controller.	1e-6
ias15_adaptive_mode	(1, 2)	Adaptive step-size formula used by "IAS15". 1 selects the Rein & Spiegel (2015)-style error ratio. 2 selects the PRS23-based timescale heuristic currently used as the project default. This option is only valid when method="IAS15".	1
ias15_safety_factor	float	Acceptance threshold and growth limiter for the IAS15 adaptive controller. Larger values make the controller more conservative. This option is only valid when method="IAS15".	0.25
ias15_min_step	float	Lower bound for the next proposed IAS15 step size, in days. Use 0.0 to keep the current unrestricted behavior. This option is only valid when method="IAS15".	0.0

Raises:

Type	Description
ValueError	Raised when the integration method is unknown, when tolerance combinations are incomplete or incompatible with the selected method, or when a numeric option violates its valid range.

Notes

Method-specific options are validated eagerly during construction. In particular, IAS15-only options are rejected for non-IAS15 methods instead of being silently ignored.

__call__(force_model, y0, t0_jd1, t0_jd2, t_start_jd1, t_start_jd2, t_end_jd1, t_end_jd2, grid=False)

Integrate the orbit and build dense interpolators.

Parameters:

Name	Type	Description	Default
force_model	ForceModel	Force model or batch of force models used by the ODE right-hand side.	required
y0	Float[ArrayLike, '... 6']	Initial Cartesian state or batch of states at the reference epoch, with position first and velocity second.	required
t0_jd1	Float[ArrayLike, ...]	Reference epoch or batch of reference epochs in split Julian Date form.	required
t0_jd2	Float[ArrayLike, ...]	Reference epoch or batch of reference epochs in split Julian Date form.	required
t_start_jd1	Float[ArrayLike, ...]	One end of the covered interval, in split Julian Date form.	required
t_start_jd2	Float[ArrayLike, ...]	One end of the covered interval, in split Julian Date form.	required
t_end_jd1	Float[ArrayLike, ...]	The other end of the covered interval, in split Julian Date form.	required
t_end_jd2	Float[ArrayLike, ...]	The other end of the covered interval, in split Julian Date form.	required
grid	bool	If False, use point-wise broadcasting. If True, use the Cartesian product of the input batches.	False

Returns:

Type	Description
BiDirectionalInterpolator	Dense interpolator or batch of interpolators for the requested propagation spans.

Notes

The returned interpolator covers the full closed interval between t_start and t_end, even when the reference epoch lies inside that interval. Forward propagation covers epochs at or after t0. Backward propagation covers epochs before t0.