scenarioBranchingVerification

Verification of the effector-branching extension along two complementary axes. Whereas the branching scenarios exercise the capability at production scale, this script reduces it to a hub, one moving-platform host state effector, and an extForceTorque dynamic effector branched onto the host’s tip segment in field-free space, where exact references exist to measure against. The effector applies a torque about the segment origin together with a force through each of the two channels a branching parent accepts, one resolved in the host segment frame and one in the inertial frame.

The first axis checks the impulse-momentum theorems at one fixed integration step. The simulator’s internally tracked angular and linear momentum about the system center of mass are compared against the integrated external impulse, and any drift away from machine precision indicates a defect in the equations of motion themselves: a wrong reference frame in the branched force or torque, a wrong moment arm, or a sign error in a Backsubstitution coupling matrix. The post-processing integrals use Simpson’s 1/3 rule so the residual reports the simulator’s error rather than the quadrature’s.

The second axis is the order-of-accuracy check standard in computational-physics code verification. The answer at a fixed final time is computed at successively halved step sizes, and the convergence rate of the differences is compared against the integrator’s formal order, which is four for the default RK4. This detects a defect class the first axis cannot: stage inconsistency, where the branched wrench is evaluated against the wrong intermediate Runge-Kutta state, leaving each step within tolerance whereas the effective order degrades across the run.

A correct implementation must satisfy both axes. Either alone is necessary but not sufficient.

Three host classes span the moving-platform effectors that support branching, each a chain with the dynamic effector branched onto its tip body: spinningBodyNDOF configured as three two-degree-of-freedom segments, nHingedRigidBody as three hinged panels, and linearTranslationNDOF as three translating bodies.

The script is found in the folder basilisk/examples and executed by:

python3 scenarioBranchingVerification.py

Illustration of Simulation Results

The default run() invocation reproduces the configuration presented in the companion journal article (citation pending publication). The pytest wrapper in src/tests drives a shortened step ladder and horizon to keep wall time low.

The impulse-momentum residuals show the random-walk character of pure floating-point rounding, about thirteen orders of magnitude below the momentum they bound. All three hosts are run and their peak residuals printed, and the figure shows the cascading-rotation and translating hosts. The step-size refinement places every host on a line of slope four, so all three inherit the integrator’s formal order through the branched code path.

class scenarioBranchingVerification.HostProps(totalMass, r_PcP_P, logAttr, segment)

Bases: object

Information needed for the post-processing impulse computation.

scenarioBranchingVerification.computeResiduals(case)

Per-component signed residual time histories.

Returns:

• times ((N,) array of seconds)

• resH ((N, 3) signed angular momentum residual,) – H_C(t) - H_C(0) - integral(tau_C dt') [N m s]

• resV ((N, 3) signed accumulated DV residual,) – v_C(t) - v_C(0) - integral(F/M dt') [m/s]

scenarioBranchingVerification.pairResiduals(runs, key)

Return ‖x(dt_i) − x(dt_{i+1})‖ for each adjacent pair.

scenarioBranchingVerification.run(show_plots, dtSweep=(0.05, 0.025, 0.0125, 0.00625, 0.003125), convergenceFinalTime=10.0, conservationDt=0.0001, conservationFinalTime=4.0)

Run both verification studies and return their figures and metrics.

Parameters:

• show_plots (bool) – display the figures interactively.

• dtSweep (tuple) – integration steps to refine over [s], halving between entries.

• convergenceFinalTime (float) – fixed final time for the refinement study [s].

• conservationDt (float) – fixed integration step for the residual study [s].

• conservationFinalTime (float) – duration of the residual study [s].

Returns:

figureList keyed by figure name, and a metrics dict holding the fitted convergence slopes and the peak impulse-momentum maxResiduals per host.

Return type:

tuple

scenarioBranchingVerification.runConservationStudy(dt=0.0001, finalTime=4.0)

Run the impulse-momentum residual study and render the conservation figure.

Parameters:

• dt (float) – fixed integration step [s].

• finalTime (float) – simulation duration [s].

Returns:

the conservation figure and the peak angular and linear residual per host.

Return type:

tuple

scenarioBranchingVerification.runConvergenceStudy(dtSweep=(0.05, 0.025, 0.0125, 0.00625, 0.003125), finalTime=10.0)

Run the step-size refinement study and render the convergence figure.

Parameters:

• dtSweep (tuple) – integration steps to refine over [s], halving between entries.

• finalTime (float) – fixed final time at which the states are compared [s].

Returns:

the convergence figure and the fitted order per host and observable.

Return type:

tuple

scenarioBranchingVerification.runToFinalState(stateEffFactory, dt, T)

Run one field-free sim with a branched extForceTorque on the host’s tip.

Returns the hub state at t = T extracted from scStateOutMsg.

scenarioBranchingVerification.setupLinearTranslationNDOF()

Three translating bodies in a chain. Tip = body 3.

scenarioBranchingVerification.setupNHingedRigidBody()

Three identical hinged panels in a chain. Tip = panel 3.

scenarioBranchingVerification.setupSpinningBodyNDOF()

3-segment, 2-DOF-per-segment spinning body. Tip = body 6.