Attitude

The attitude stage turns a propagated trajectory and pointing policy into a spacecraft-orientation timeline. Use it to answer:

• which pointing mode was active?
• where were the body axes directed?
• how much usable time was lost to slew and settling?
• what panel or payload orientation should downstream models use?

flowchart LR STATE["Propagated state"] --> COMMAND["Pointing command"] COMMAND --> REALIZE["Instantaneous or finite-slew realization"] REALIZE --> ATT["Quaternion, body axes, and availability"] ATT --> MISSION["Mission and communications"] ATT --> POWER["Power generation and loads"]

Pointing Modes

Mode	Behavior
nadir	Points body +Z toward Earth center.
sun_pointing	Aligns a selected body vector with the analytic Sun direction.
fixed	Uses an explicit request quaternion.
nadir_sun	Maintains nadir pointing and uses the in-plane Sun projection to select yaw.
sat_track	Tracks another satellite while the configured contact conditions are met.
nadir_isl	Maintains nadir while steering an in-plane axis toward another satellite.

adcs.default_mode provides the baseline. attitude_mode_set, schedule policy, and mission behavior can create mode changes over time. Tracking modes have fallback behavior when their target or contact condition is unavailable.

adcs:
  default_mode: nadir_sun
  attitude_mode_set: sat_track_emphasis
  sat_track:
    contact_gate: geometry
    fallback_mode: nadir
    max_range_km: 2500
  sun_tracking_body_vector: [1.0, 0.0, 0.0]
  isl_tracking_body_vector: [1.0, 0.0, 0.0]

The resolved mode and Sun-incidence history share the simulation timeline, so the geometric consequences of a pointing policy can be reviewed directly.

Instantaneous And Finite-Slew Realization

The default instantaneous mode applies each commanded orientation without an acquisition delay. Use slew_envelope when transition time should reduce usable mission time:

imports:
  - profiles/spacecraft.yaml

adcs:
  default_mode: nadir_sun
  realization:
    mode: slew_envelope
    profile_id: customer_reaction_wheel

The mobility profile supplies maximum angular rate, maximum angular acceleration, settling time, and provenance. Astraeus follows the shortest quaternion path with a symmetric rate/acceleration envelope. It is a reduced-order acquisition model rather than a controller or rigid-body simulation.

pointing_available_fraction preserves partial availability within each simulation interval. By default, the realized orientation and available fraction affect communications, observation/payload activity, and power. Geometric line of sight itself is unchanged; the availability determines how much of that geometry is operationally usable.

Consumer coupling can be disabled under adcs.realization.coupling for bounded diagnostic comparisons. Such an opt-out is a partial-fidelity case rather than a normal physical operating mode.

Outputs

Artifact	Contents
attitude/timeline_attitude.parquet	realized quaternion, body axes, mode, and Sun-incidence timeline
attitude/attitude_summary.json	dimensions, mode counts, realization settings, and availability summary
attitude/attitude_modes.json	stable mode-code definitions
attitude/timeline_attitude_commanded.parquet	commanded orientation for finite-slew runs
attitude/timeline_attitude_realization.parquet	slew/settling state and interval availability
attitude/attitude_transitions.parquet	transition timing, angle, and analytic/calibrated provenance

The last three are emitted for finite-slew realization. The Console uses these artifacts for mode, incidence, transition, and pointing-availability views.

Packaged Example

Run:

astraeus run astraeus-resources/examples/user/finite-slew-attitude.yaml

This case follows six satellites and three regional observation targets for 12 hours with a 30-second cadence. It is intended to show the difference between requested and achievable pointing, not just a static attitude mode.

For an integrated observation, transport, activity, and power case, use astraeus-resources/examples/user/observation-to-delivery.yaml.

Model Resolution

• The finite-slew model resolves commanded-to-realized pointing and calibrated transition timing. Rigid-body dynamics, control loops, actuator saturation, momentum management, disturbances, sensors, and estimation error require higher-fidelity models.
• Mobility calibration changes transition timing only inside its declared applicability; otherwise the analytic envelope is used.
• Pointing commands and availability share the simulation cadence. A coarse step can hide short transitions or reduce timing precision.
• Some attitude modes map to the same downstream power load bucket even though their geometric orientation remains different.

For exact fields, see the RunSpec reference.