Python Module: arcLineHoldRef

Auxiliary Files

• Unit tests

Executive Summary

arcLineHoldRef publishes a time-varying inertial translation reference for a specific arc-to-line-to-hold maneuver. The reference follows a circular arc in a plane tilted 45 degrees out of the inertial x-y plane, blends smoothly onto the inertial y axis, moves along that axis to a final position, and then remains stationary. The module publishes position, velocity, and acceleration; it does not calculate control forces or move a spacecraft.

The radius, phase durations, blend endpoint, and final position are configurable. The path topology, circle plane, line axis, and terminal hold are fixed. This is not a general-purpose trajectory generator.

Message Connection Descriptions

The following diagram and table list the module output messages.

Module I/O Messages

Msg Variable Name	Msg Type	Description
transRefOutMsg	TransRefMsgPayload	Output inertial reference position, velocity, and acceleration.

Module Assumptions and Limitations

The arc satisfies \(r_x=r_z\), fixing its plane at 45 degrees out of the inertial x-y plane. The subsequent straight segment changes only \(r_y\). Both blendEndPosition and finalPosition must therefore be finite three-component vectors with exactly zero inertial x and z components. Reset() rejects incompatible endpoints with BSK_ERROR (a BasiliskError in Python), rather than allowing a position jump at the blend-to-line or line-to-hold boundary.

radius, tCircle, tTransition, and tLinear must all be finite. Reset() rejects NaN and positive or negative infinity with BSK_ERROR (a BasiliskError in Python) before computing trajectory boundary states. It also requires tTransition > 0, tLinear > 0, and tCircle + tTransition > 0. For the intended arc-then-blend sequence, configure a nonnegative tCircle and a positive radius. The latter two conditions are recommendations, not additional checks performed by the module.

The phase clock is the absolute simulation time, measured from simulation time zero. Calling Reset() at a later time does not restart the maneuver. All parameters should be set before Reset(): it precomputes the blend boundary states, so changing configuration while the module is running can make adjacent segments inconsistent.

The last moving segment is a quintic curve confined to the y axis with zero terminal velocity and acceleration. For arbitrary choices of the two y endpoints and phase duration, the intermediate motion is not guaranteed to be monotonic or to slow down at every instant.

Mathematical Modeling

Let \(R\) be radius, \(t_c\) be tCircle, \(T_b\) be tTransition, and \(T_l\) be tLinear. The angular rate of the initial arc is

\[\omega = \frac{\pi}{t_c + T_b}.\]

For \(0 \leq t < t_c\), the inertial reference position is

\[\begin{split}\boldsymbol{r}_R(t) = R \begin{bmatrix} \sin(\omega t)/\sqrt{2} \\ \cos(\omega t) \\ \sin(\omega t)/\sqrt{2} \end{bmatrix}.\end{split}\]

The module evaluates its analytic first and second time derivatives for the velocity and acceleration references. In particular, \(\boldsymbol{a}_R=-\omega^2\boldsymbol{r}_R\) on the arc.

For \(t_c \leq t < t_c+T_b\), a separate quintic polynomial in each coordinate joins the arc to the line. At its start, position, velocity, and acceleration equal the arc states at \(t_c\). At its end, they are

\[\boldsymbol{r}_b = [0,\,y_b,\,0]^\mathsf{T},\qquad \boldsymbol{v}_b = [0,\,\omega R,\,0]^\mathsf{T},\qquad \boldsymbol{a}_b = \boldsymbol{0},\]

where \(y_b\) is the y component of blendEndPosition. Matching all three states at both ends makes the reference continuous through acceleration at the arc-to-blend and blend-to-line boundaries.

During the final moving segment, let \(\tau=t-t_c-T_b\), \(\Delta y=y_f-y_b\), and \(v_b=\omega R\), where \(y_f\) is the y component of finalPosition. For \(0 \leq \tau < T_l\), the reference has \(r_x=r_z=0\) and

\[\begin{split}y(\tau) &= y_b + v_b\tau + a_3\tau^3 + a_4\tau^4 + a_5\tau^5, \\ a_3 &= \frac{10\Delta y-6v_bT_l}{T_l^3}, \\ a_4 &= \frac{-15\Delta y+8v_bT_l}{T_l^4}, \\ a_5 &= \frac{6\Delta y-3v_bT_l}{T_l^5}.\end{split}\]

The velocity and acceleration are the analytic derivatives of this polynomial. At \(t=t_c+T_b+T_l\), the output switches to the final hold: \(\boldsymbol{r}_R=[0,\,y_f,\,0]^\mathsf{T}\) and \(\boldsymbol{v}_R=\boldsymbol{a}_R=\boldsymbol{0}\).

User Guide

This section is to outline the steps needed to setup the arcLineHoldRef module in Python using Basilisk.

1. Import the module:

   from Basilisk.fswAlgorithms import arcLineHoldRef
   

2. Create an instance:

   module = arcLineHoldRef.ArcLineHoldRef()
   

3. Set the arc radius and the three phase durations:

   module.setRadius(20.0)  # [m]
   module.setTCircle(5.0 * 3600.0)  # [s]
   module.setTTransition(1.0 * 3600.0)  # [s]
   module.setTLinear(110.0 * 60.0)  # [s]
   

4. Set the blend endpoint and final hold position. Their inertial x and z components must be zero:

   module.setBlendEndPosition([0.0, -16.0, 0.0])  # [m]
   module.setFinalPosition([0.0, -5.0, 0.0])  # [m]
   

5. Add the module to a task at the rate needed by the reference consumer:

   sim.AddModelToTask(taskName, module)
   

These example values are also the module defaults, so steps 3 and 4 can be omitted when those values are desired. The arc begins at \([0,R,0]^\mathsf{T}\) at simulation time zero. The blend starts at tCircle, the straight segment starts at tCircle + tTransition, and the stationary hold starts at tCircle + tTransition + tLinear.

---

Fixed-family translation reference with an arc, line, and final hold.

The reference consists of a circular arc with equal inertial x and z components, producing a 45-degree out-of-plane trajectory. A quintic segment connects that arc to a line, followed by a deceleration constrained to the inertial y axis and a final stationary hold. Radius, timing, and endpoint values are configurable; the trajectory topology, circle orientation, and deceleration axis are intentionally fixed. The blend endpoint and final hold must both lie on the inertial y axis.

class arcLineHoldRef.ArcLineHoldRef(*args, **kwargs)

Bases: SysModel

Generate the fixed circular-to-line tracking maneuver.

The circular path uses r_x = r_z and is therefore fixed at 45 degrees out of the inertial x-y plane. The final segment only changes the inertial y position. This module is not a general-purpose trajectory generator: it does not support arbitrary circle planes, path topologies, or deceleration directions.

blendStates(elapsedTime)

Evaluate the quintic circle-to-line transition.

Parameters:

elapsedTime – Time since transition start in seconds.

Returns:

Position, velocity, and acceleration reference vectors.

circleStates(currentTime)

Evaluate the circular portion of the trajectory.

Parameters:

currentTime – Elapsed trajectory time in seconds.

Returns:

Position, velocity, and acceleration reference vectors.

decelStates(elapsedTime)

Evaluate the final inertial-y-axis deceleration segment.

Parameters:

elapsedTime – Time since deceleration start in seconds.

Returns:

Position, velocity, and acceleration reference vectors.

setBlendEndPosition(blendEndPosition)

Set the position at the end of the circle-to-line transition.

The following deceleration occurs only along the inertial y axis, so the inertial x and z components must be zero.

Parameters:

blendEndPosition – Transition end position in meters.

setFinalPosition(finalPosition)

Set the final stationary reference position.

The inertial x and z components must be zero.

Parameters:

finalPosition – Final position in meters.

setRadius(radius)

Set the radius of the fixed 45-degree out-of-plane circular arc.

Parameters:

radius – Circular-trajectory radius in meters.

setTCircle(tCircle)

Set the circular-trajectory duration.

Parameters:

tCircle – Circular-trajectory duration in seconds.

setTLinear(tLinear)

Set the deceleration-segment duration.

Parameters:

tLinear – Deceleration duration in seconds.

setTTransition(tTransition)

Set the circle-to-line transition duration.

Parameters:

tTransition – Transition duration in seconds.