Bplane#

class Bplane(epoch: EpochArray | float, bplane_name: str, bplane_spice_id: int | str, sc_name: str, sc_spice_id: int | str, target_name: str, target_spice_id: int | str, fk_file: str | Path, v_hat: bool = True, new_bplane: bool = True, scenario_kernel_dir: str | Path | None = None)#

Bases: object

B-plane and B-vector definition and targeting.

The B-plane is a plane passing through the centre of a target body, perpendicular to the incoming hyperbolic asymptote of the approach trajectory. The B-vector is the vector from the target-body centre to the point where the asymptote pierces that plane, and its components \(B \cdot T\) and \(B \cdot R\) are the primary targeting parameters used in planetary-flyby and encounter design.

B-plane geometry

The B-plane is defined at a reference epoch by three right-handed orthonormal vectors:

\[\begin{split}\hat{S} &= \frac{\mathbf{v}_\infty}{\|\mathbf{v}_\infty\|} \quad\text{(incoming asymptote direction)}\\ \hat{T} &= \frac{\hat{k} \times \hat{S}}{\|\hat{k} \times \hat{S}\|} \quad\text{(in B-plane, perpendicular to S)}\\ \hat{R} &= \hat{S} \times \hat{T}\end{split}\]

where \(\hat{k}\) is the ecliptic north pole and \(\mathbf{v}_\infty\) is the hyperbolic excess velocity vector.

The B-vector is the perpendicular from the target-body centre to the incoming asymptote:

\[\mathbf{B} = B_T\,\hat{T} + B_R\,\hat{R}, \qquad |\mathbf{B}| = \sqrt{B_T^2 + B_R^2}\]

For a hyperbolic flyby with gravitational parameter \(\mu\), the periapsis distance is

\[r_p = \frac{\mu}{v_\infty^2} \left(\sqrt{1 + \frac{v_\infty^2\,|\mathbf{B}|^2}{\mu^2}} - 1\right)\]

Targeting

target() minimizes \(\|\mathbf{b}_{target} - \mathbf{b}_{ref}\|\) by solving for the \(\Delta v\) correction at a specified maneuver epoch, where \(\mathbf{b}_{target} = [B\cdot T_{target},\;B\cdot R_{target},\;\mathrm{LTOF}_{target}]\).

Parameters:
epochEpochArray | datetime.datetime | float

Reference epoch for the B-plane frame. Floats are interpreted as J2000 ephemeris seconds (ET); datetime objects are converted automatically.

bplane_namestr

Name of the B-plane SPICE frame (e.g. 'BPLANE_EUROPA').

bplane_spice_idint or str

SPICE numeric frame ID for the B-plane frame.

sc_namestr

Human-readable spacecraft name (used for labelling only).

sc_spice_idint or str

SPICE body ID (name string or integer) for the spacecraft.

target_namestr

Human-readable target-body name; must match a key in scarabaeus.Constants that exposes a mu entry.

target_spice_idint or str

SPICE body ID (name string or integer) for the target body.

fk_filestr or pathlib.Path

Path to the frames-kernel (.tf) file. If new_bplane is True the file is created here; otherwise it is loaded from this path.

v_hatbool, optional

When True (default) the secondary axis of the B-plane frame is aligned with the +Y direction; False flips it to -Y.

new_bplanebool, optional

True (default) creates and furnishes a new FK file. False loads an existing kernel from fk_file.

scenario_kernel_dirstr or pathlib.Path, optional

Directory into which the FK file is written. Defaults to <cwd>/data/Kernels.

Attributes:
bt_ref, br_refArrayWUnits

Reference B-plane targeting parameters \(B \cdot T\) and \(B \cdot R\) [km].

ltof_refArrayWUnits

Reference linearised time-of-flight [s].

time_close_approach_refArrayWUnits

Estimated close-approach epoch [ET seconds].

bpar_refArrayWUnits

Concatenated reference vector \([B \cdot T, B \cdot R, \mathrm{ltof}]\).

Methods

compute_hyperbolic_parameters(sc_rel_state_j2000)

Compute classical hyperbolic B-plane parameters from a Cartesian state.

compute_jacobian(sc_rel_state_j2000)

Finite-difference Jacobian of the B-plane parameters w.r.t.

compute_parameters(sc_rel_state_j2000)

Compute the linear B-plane parameters from a spacecraft state.

linear_targeting(sc_rel_state_j2000[, err, ...])

Compute a trajectory-correction manoeuvre (TCM) via linear targeting.

nonlinear_targeting(sc_rel_state_j2000[, err])

Compute a TCM via nonlinear optimisation (Nelder-Mead).

piecewise_targeting(trajectory, tcm_epochs)

Compute TCMs at multiple epochs along a trajectory and (optionally) generate a corrected SPK ephemeris file.

propagate_covariance_to_close_approach(...)

Propagate a state covariance to the close-approach epoch.

target_covariance(sc_cov, sc_rel_state_j2000)

Map a spacecraft state covariance to B-plane parameter covariance.

target_spacecraft_covariance(sc_targ_cov, ...)

Map a joint spacecraft-and-target covariance to B-plane parameter covariance.

See also

scarabaeus.Trajectory

Trajectory container used as input to compute the B-plane.

scarabaeus.EpochArray

Epoch representation for the B-plane reference epoch.

compute_hyperbolic_parameters(sc_rel_state_j2000: ArrayWUnits) → ArrayWUnits#

Compute classical hyperbolic B-plane parameters from a Cartesian state.

This routine evaluates the full conic geometry of the approach trajectory and derives the B-vector components \(B \cdot T\) and \(B \cdot R\) from the asymptote direction and the orbit’s semi-latus rectum. For elliptic trajectories (eccentricity < 1) the B-plane is undefined and the corresponding output entries are set to NaN.

Parameters:
sc_rel_state_j2000ArrayWUnits, shape (6,) or (N, 6)

Relative state(s) in J2000 with units convertible to km and km/s.

Returns:
ArrayWUnits, shape (3,) or (N, 3)

\([B \cdot T, B \cdot R, \mathrm{ltof}]\), in km, km and s.

Warning

The T-vector construction becomes degenerate when S is nearly parallel to the z-axis (i.e. the approach asymptote nearly coincides with the north pole direction).

  • The computation of beta = arccos(1/ecc) is only valid for hyperbolic or parabolic cases.

  • The construction of Tvec as [-Sy, Sx, 0] becomes degenerate when the projection of Svec onto the xy-plane is near zero.

  • If ecc == 1 exactly, the semimajor/seminor-axis expressions may become numerically delicate.

  • gm is retrieved from scarabaeus.constants using self.target_name.

Notes

The B-plane convention follows Kizner (1961):

  • S – unit vector along the incoming asymptote.

  • T – perpendicular to S lying in the target equatorial plane (constructed as T = [-Sy, Sx, 0] / |[-Sy, Sx, 0]|).

  • \(\mathbf{R} = \mathbf{S} \times \mathbf{T}\).

  • \(\mathbf{B} = b\,(\mathbf{S} \times \hat{\mathbf{h}})\), with \(b\) the semi-minor axis.

compute_jacobian(sc_rel_state_j2000: ArrayWUnits) → ArrayWUnits#

Finite-difference Jacobian of the B-plane parameters w.r.t. velocity.

Computes the (3, 3) matrix \(\partial [B \cdot T, B \cdot R, \mathrm{ltof}] / \partial [v_x, v_y, v_z]\) via forward finite differences with perturbation size chosen as sqrt(eps_machine) * max(1, |v_i|).

Parameters:
sc_rel_state_j2000ArrayWUnits, shape (6,)

Current relative state in J2000.

Returns:
jacobianArrayWUnits, shape (3, 3)

Jacobian matrix with units [km/(km/s), km/(km/s), s/(km/s)] i.e. [s, s, s^2/km] per column.

compute_parameters(sc_rel_state_j2000: ArrayWUnits) → ArrayWUnits#

Compute the linear B-plane parameters from a spacecraft state.

Projects the relative state onto the B-plane and returns the intersection coordinates together with the linearised time-of-flight.

Parameters:
sc_rel_state_j2000ArrayWUnits, shape (6,)

Relative Cartesian state [x, y, z, vx, vy, vz] of the spacecraft with respect to the target body, expressed in J2000.

Returns:
bparArrayWUnits, shape (3,)

\([B \cdot T, B \cdot R, \mathrm{ltof}]\) where \(B \cdot T\) and \(B \cdot R\) are in km and ltof is in seconds.

linear_targeting(sc_rel_state_j2000: ArrayWUnits, err: float = 1e-08, max_iterations: int = 100) → ArrayWUnits#

Compute a trajectory-correction manoeuvre (TCM) via linear targeting.

Iterates a Newton-style correction loop using the local Jacobian until the residual in B-plane parameter space drops below err.

Parameters:
sc_rel_state_j2000ArrayWUnits, shape (6,)

Perturbed relative state in J2000 at the manoeuvre epoch.

errfloat, optional

Convergence threshold on the L2 norm of the B-plane residual.

max_iterationsint, optional

Maximum number of Newton iterations before raising an error.

Returns:
DV_totArrayWUnits, shape (3,)

Velocity increment vector \([\Delta V_x, \Delta V_y, \Delta V_z]\) in km/s.

Raises:
RuntimeError

If the iteration does not converge within max_iterations steps.

nonlinear_targeting(sc_rel_state_j2000: ArrayWUnits, err: float = 1e-10) → ArrayWUnits#

Compute a TCM via nonlinear optimisation (Nelder-Mead).

Minimises the squared L2 norm of the B-plane residual \(\lVert [B \cdot T, B \cdot R, \mathrm{ltof}]_{\mathrm{ref}} - [B \cdot T, B \cdot R, \mathrm{ltof}] \rVert^2\) over the three velocity components at the manoeuvre epoch.

Parameters:
sc_rel_state_j2000ArrayWUnits, shape (6,)

Perturbed relative state in J2000 at the manoeuvre epoch.

errfloat, optional

Tolerance passed to scipy.optimize.minimize.

Returns:
DV_totArrayWUnits, shape (3,)

Velocity increment vector \([\Delta V_x, \Delta V_y, \Delta V_z]\) in km/s.

piecewise_targeting(trajectory: Trajectory, tcm_epochs: list, method: str = 'linear', err: float = 1e-08, max_iterations: int = 100, spk_output_path: str | Path | None = None) → list[ArrayWUnits]#

Compute TCMs at multiple epochs along a trajectory and (optionally) generate a corrected SPK ephemeris file.

The algorithm proceeds segment-by-segment:

  1. Evaluate the current relative state at tcm_epoch[i].

  2. Solve for the \(\Delta V\) that corrects the B-plane parameters to the reference values using the chosen method.

  3. Apply the \(\Delta V\) to the state, propagate to the next TCM epoch (or to close approach for the last segment), and write the resulting arc to the SPK file.

Parameters:
trajectoryTrajectory

A scarabaeus.Trajectory object that exposes at minimum:

  • get_state(epoch) returns the ArrayWUnits relative state in J2000.

  • propagate(state, epoch_start, epoch_end) returns the updated Trajectory segment.

  • write_spk(filepath) generates a SPICE SPK kernel.

tcm_epochslist of EpochArray | datetime | float

Ordered sequence of epochs at which TCMs are to be computed. Must be in chronological order.

method{‘linear’, ‘nonlinear’}, optional

Targeting algorithm. 'linear' uses the Newton iteration (linear_targeting()); 'nonlinear' uses Nelder-Mead (nonlinear_targeting()).

errfloat, optional

Convergence tolerance forwarded to the chosen targeting method.

max_iterationsint, optional

Maximum Newton iterations (linear method only).

spk_output_pathstr or pathlib.Path, optional

If provided, a SPICE SPK file covering the full corrected trajectory is written to this path after all TCMs have been applied.

Returns:
dv_listlist of ArrayWUnits

\(\Delta V\) vectors \([\Delta V_x, \Delta V_y, \Delta V_z]\) [km/s] at each TCM epoch.

Raises:
ValueError

If method is not 'linear' or 'nonlinear'.

propagate_covariance_to_close_approach(sc_cov: ndarray, sc_rel_state_j2000: ArrayWUnits, process_noise: TypeAliasForwardRef('numpy.ndarray') | None = None) → ArrayWUnits#

Propagate a state covariance to the close-approach epoch.

Note

Not yet implemented. A correct implementation requires a state transition matrix (STM) \(\Phi\) from the manoeuvre epoch to close approach, so that:

P_ca = Phi @ P @ Phi.T + Q

where Q is the process-noise covariance. The mapped B-plane covariance is then obtained via _map_covariance() evaluated at the close-approach state. Implement once the Trajectory class exposes get_stm(epoch_start, epoch_end) -> ndarray.

Raises:
NotImplementedError

Always.

target_covariance(sc_cov: ndarray, sc_rel_state_j2000: ArrayWUnits) → ArrayWUnits#

Map a spacecraft state covariance to B-plane parameter covariance.

Uses the analytical linearisation of the B-plane projection to propagate a (6, 6) Cartesian covariance (in J2000) into the (3, 3) space \([B \cdot T, B \cdot R, \mathrm{ltof}]\).

Assumes no cross-correlation between the B-plane position components and the linearised time-of-flight.

Parameters:
sc_covarray-like, shape (6, 6)

Full covariance matrix of the spacecraft state in J2000 (position–velocity).

sc_rel_state_j2000ArrayWUnits, shape (6,)

Relative Cartesian state in J2000 at the close-approach epoch.

Returns:
P_bplaneArrayWUnits, shape (3, 3)

B-plane parameter covariance with units [[km^2, km^2, km*s], [km^2, km^2, km*s], [km*s, km*s, s^2]].

target_spacecraft_covariance(sc_targ_cov: ndarray, sc_rel_state_j2000: ArrayWUnits) → ArrayWUnits#

Map a joint spacecraft-and-target covariance to B-plane parameter covariance.

Accounts for uncertainty in both the spacecraft and the target body by first forming the relative covariance via the (6, 12) subtraction matrix, then propagating as in target_covariance().

Parameters:
sc_targ_covarray-like, shape (12, 12)

Joint covariance matrix of the spacecraft and target states in J2000, ordered as [sc_pos, sc_vel, tgt_pos, tgt_vel].

sc_rel_state_j2000ArrayWUnits, shape (6,)

Relative Cartesian state sc - target in J2000 at close approach.

Returns:
P_bplaneArrayWUnits, shape (3, 3)

B-plane parameter covariance (same units as target_covariance()).

property bplane_name: str#

SPICE frame name of the B-plane.

property bplane_spice_id: int#

SPICE numeric frame ID of the B-plane.

property br_ref: ArrayWUnits#

Reference \(B \cdot R\) component of the B-vector [km].

property bt_ref: ArrayWUnits#

Reference \(B \cdot T\) component of the B-vector [km].

property epoch: EpochArray#

Reference epoch as an EpochArray.

property fk_file: Path#

Absolute path to the B-plane frames kernel file.

property new_bplane: bool#

Whether a new FK file was created by this instance.

property rot_to_bplane: ArrayWUnits#

Rotation matrix (DCM) from J2000 to the B-plane frame.

property rot_to_j2000: ArrayWUnits#

Rotation matrix (DCM) from the B-plane frame to J2000.

property rotmat_to_bplane: ArrayWUnits#

Alias for rot_to_bplane.

property rotmat_to_j2000: ArrayWUnits#

Alias for rot_to_j2000.

property sc_name: str#

Human-readable spacecraft name.

property sc_spice_id: int | str#

Resolved SPICE body identifier for the spacecraft.

property target_name: str#

Human-readable target-body name.

property target_spice_id: int | str#

Resolved SPICE body identifier for the target.

property v_hat: bool#

Secondary-axis orientation flag (True gives +Y, False gives -Y).