scenarioRoboticGrappling

Overview

This scenario demonstrates effector branching through a docking and berthing maneuver. See Advanced: Effector Module Branching for the conceptual background on attaching dynamic effectors onto state effectors. A chaser spacecraft carries a C++ Module: linearTranslationOneDOFStateEffector arm; a C++ Module: constraintDynamicEffector is attached as a dynamic effector of the arm (branched attachment) and to a separate target spacecraft, modeling a rigid grapple at the arm tip.

The scenario runs in three phases:

1. Free-flight approach: the chaser starts one meter from the target docking point and drifts toward it with the grappling constraint disabled. A Basilisk event monitors the tip-to-target separation and engages the constraint when the grapple enters the capture tolerance.

2. Capture / settle: the arm is extended at its initial length with the constraint engaged. The two vehicles relax to a constraint-consistent state.

3. Berthing retraction: the arm reference length is driven to zero through a prescribed motion profile. The arm retracts and pulls the target spacecraft in along with it via the branched constraint, producing a hard-docked configuration.

Throughout the simulation both spacecraft are integrated simultaneously with synchronized RKF45 integrators.

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

python3 scenarioRoboticGrappling.py

Note that the C++ Module: constraintDynamicEffector requires gain tuning, addressed in scenarioConstrainedDynamicsManeuverAnalysis. Here the damping gains are set for critical damping at the reduced mass of the pair and the smallest target inertia, since the default damping rings once the off-axis grapple couples the position constraint into the attitude constraint.

Illustration of Simulation Results

The default run() invocation reproduces the configuration presented in the companion journal article (citation pending publication), at dynRateSeconds = 1e-4. The pytest wrapper in src/tests uses a 0.01 s step and 25% linear constraint damping to reduce runtime, with differences in the capture transient. Direct execution retains the default settings.

The hub-separation plot tracks the inertial distance between the two vehicles through the free-flight approach, holds near 3.2 m after capture, and draws down to about 2.2 m as the arm retracts. Both exceed the arm length because the grapple point sits on the rim of the target’s Marman ring, offset from its axis. The arm extension plot rings briefly at capture and again as retraction ends, as the arm’s spring-damper joint absorbs the load delivered through the branched constraint, and otherwise shows the smoothed bang-bang retraction profile commanded to the C++ Module: prescribedLinearTranslation profiler. The position-constraint plot shows the constraint effector pulling the violation down to numerical zero on engagement, plotted from the grapple event onward because the constraint is inactive before it. The attitude-constraint plot stays at numerical zero throughout because the two vehicles start aligned and no torques perturb them.

class scenarioRoboticGrappling.SimBaseClass(dynRate=0.0001)

Bases: SimBaseClass

scenarioRoboticGrappling.annotateEventLine(ax, xVal, label, color, linestyle)

Draw vertical event line with rotated text label at bottom-right.

scenarioRoboticGrappling.annotateEvents(ax, captureTimeMin, retractionStartMin)

Draw the grapple and berth event lines with vertical labels.

scenarioRoboticGrappling.captureCondition(scSim)

Return True when the arm tip is close enough to the target dock.

scenarioRoboticGrappling.computeDockingDistance(scSim)

Compute the inertial separation between the arm tip and target dock.

scenarioRoboticGrappling.defineInitialConditions(scSim)

Place the vehicles collinear with a one-meter free-flight capture gap.

scenarioRoboticGrappling.engageConstraint(scSim)

Enable the grapple constraint and record the capture state.

scenarioRoboticGrappling.run(show_plots, gain, dynRateSeconds=0.0001, approachGapMeters=1.0, settleDurationSeconds=30.0, berthDurationSeconds=90.0, constraintLinearDampingScale=1.0)

Parameters:

• show_plots (bool) – Whether to display plots interactively.

• gain (float) – Constraint effector Baumgarte gain (alpha = beta).

• dynRateSeconds (float) – integration step. Default defaultDynRate (1e-4 s) is the journal-paper configuration. The test wrapper uses 0.01 s with reduced linear constraint damping for faster execution.

• approachGapMeters (float) – free-flight separation at simulation start. Default 1.0 m matches the journal-paper configuration. The test harness passes a smaller value to compress phase 1 wall time.

• settleDurationSeconds (float) – hold time after capture before commanding arm retraction. Default 30 s.

• berthDurationSeconds (float) – time after the retraction command before simulation stop. Default 90 s gives ample post-retraction settle; the test harness passes a shorter value covering only the active retraction segment plus a brief hold.

• constraintLinearDampingScale (float) – multiplier [-] for the linear constraint damping. Default 1.0 preserves the original damping; the pytest wrapper uses 0.25. Angular damping and stiffness are unaffected.

scenarioRoboticGrappling.setUpCaptureEvent(scSim)

Create an event that engages the grapple inside the capture tolerance.