Spacecraft Dynamics — Robotics/Spacecraft Dynamics

Spacecraft Dynamics

Robotics / Spacecraft Dynamics

Integrates a spacecraft's orbit and attitude together, coupled by gravity, from a body-axis force and moment:

r′ = v
v′ = R(q)·F/m + g(r)
q′ = ½ Ω(w) q, renormalised every substep
w′ = I⁻¹(M + 3μ/|r|⁵ (r_b × I r_b) − w × I w)

Thirteen states, integrated by the same fixed-step RK4 the rest of the Equations of Motion family uses.

⚠ Both halves already exist in this library and neither can do this. Orbit Propagator Kepler is closed form and takes no force at all; Attitude Dynamics takes the position on a port rather than integrating it. So the two can be wired together for a coasting spacecraft and cannot represent a thrusting one – and thrust is what makes the coupling run both ways, because the force is applied in body axes and so depends on the attitude, while the gravity-gradient torque depends on the position.

Ports

• F – the applied force in body axes, [3,1], newtons. ⚠ Body axes, not inertial: a thruster is bolted to the spacecraft.
• M – the applied moment in body axes, [3,1], newton metres.
• r – position in ICRF, [3,1], metres.
• v – velocity in ICRF, [3,1], metres per second.
• q – the attitude quaternion, [4,1], scalar first, taking body vectors to ICRF. It is renormalised every substep, so it stays unit length for as long as the run does.
• w – the body angular rate, [3,1], degrees per second.

Parameters

• Mass (kg) – positive. It divides the force and nothing else: the mass is fixed, so it does not enter the rotation.
• Inertia – the body inertia tensor, a 3×3, kg·m². It must be invertible; it need not be diagonal or symmetric, and the block does not symmetrise it.
• Initial Position / Initial Velocity – the ICRF state at t = 0, three entries each, metres and metres per second.
• Initial Attitude – the quaternion at t = 0, four entries, scalar first. It is normalised at load.
• Initial Attitude Rate – the body rate at t = 0, three entries, in degrees per second.
• Gravity Model – Point-mass or None. See Notes for why those two and not the other two.
• Gravity Gradient – on or off. With it on the attitude feels the torque the position generates, which is the coupling that makes this one block rather than two.
• Central Body – Earth (μ = 3.986004418×10¹⁴ m³/s²), Moon, Mercury, Venus, Mars, Jupiter, Saturn, Uranus, Neptune, Sun or Custom. The same measured table Attitude Dynamics and the Orbit Propagator carry.
• Custom Gravitational Parameter – μ in m³/s², read only when Central Body is Custom.
• Integration Substeps – RK4 substeps per sample, 1 to 100000, default 100. This is how the block integrates a sample; the Simulink block is continuous and has no counterpart, so it does not cross the bridge.
• Sampling Time (s) – zero or less inherits the solver's rate; a positive value runs the block at that period.

Code export

All ten targets: Python, MATLAB, Java, Rust, C, C++, VHDL, Verilog, SystemVerilog and PLC Structured Text, from one description of the derivative, so every target runs the same arithmetic in the same order as the simulation. The state is carried across samples; each sample is Integration Substeps classical RK4 steps with the inputs held, which is the map Simulink's fixed-step ode4 runs.

The three HDL targets are simulation-only real arithmetic, quantized at the port, and a Q16.16 port cannot carry this block's position or velocity at all: it saturates past about 32767, while a low Earth orbit is around 6.9 million metres. No configuration escapes that, because this state is SI metres by the definition of the Simulink block it mirrors, and a 32 km orbit is not one — measured, the three HDL cores return the position gate as zero, a residual of 100%. The real arithmetic itself is correct, so a hardware export remains meaningful for the quaternion and body-rate outputs; the suite reports the three HDL targets as not comparable and gives that reason, rather than counting them red.

Simulink bridge

Import and export, mapped to Aerospace Blockset's aerolibsatdyn/Spacecraft Dynamics, with the shape fixed to the subset below. Every parameter above crosses one for one: Mass (kg) → mass, Inertia → inertia, Initial Position → inertialPosition, Initial Velocity → inertialVelocity, Initial Attitude → attitude, Initial Attitude Rate → attitudeRate, Gravity Model → gravityModel, Gravity Gradient → useGravGrad, Central Body → centralBody, Custom Gravitational Parameter → customMu; every option list is Simulink's own spelling, so lossless. Always written: stateFormatNum ICRF state vector, attitudeFrame and outportFrame ICRF, attitudeFormat Quaternion, massType Fixed, forcesIn and momentsIn on, accelIn, dateOut, outputAccel, outputAngAccel and outputFuelStatus off, units Metric (m/s) and angleUnits Degrees – which is what every measurement behind this block was taken at. Integration Substeps does not cross, because it is how this block integrates a sample and the Simulink block is continuous with no counterpart. That block defines no SampleTime, so the rate stays on the ICore side – measured.

Notes

• ⚠ THE FORCE IS IN BODY AXES. With gravity off, v′ is R(q)·F/m and not F/m – measured, the body reading matches to 1e-9 where the inertial one is out by 80 %. A force applied in ICRF is the user's to rotate.
• ⚠ Only two of the four gravity models, and the reason is a measurement. Point-mass reproduces the Simulink block to the measurement's own error. Oblate ellipsoid (J2) does not match the classic −1.5 J₂μR_e²/r⁵ form – the best fit is 4.3e-6 relative, where point-mass fits at 5e-8 – so its form is something else and shipping a guess would have been worse than refusing it. Spherical harmonics is EGM2008, a coefficient set no export target can carry. Both are refused with that reason rather than approximated.
• ⚠ The quaternion is renormalised after EVERY substep, and that is not a tidy-up. It is the term that makes the block match: integrating q′ alone leaves the state 2.2e-8 from Simulink's after 10000 substeps, normalising only the output gets 6e-14, and normalising every substep gets one ulp.
• The rate is in degrees per second at the port and radians inside. The initial rate is read in degrees too.
• The inertia is not symmetrised. An asymmetric tensor is integrated as given, which is what the Simulink block does; if that is not what you meant, it is your tensor that is wrong.
• No state space: the dynamics are nonlinear, so model reduction correctly declines the block.
• ⚠ This block does not replace Orbit Propagator Kepler, which is closed form and therefore exact and cheap for a coasting orbit. Reach for this one when there is a force.