Skip to content

User Manual

Jump to bottom
timeout187 edited this page Jul 9, 2026 · 1 revision

User Manual

A walkthrough of every page in the Streamlit lab (streamlit run src/gui/app.py) and every standalone script in examples/.

Table of contents

Launching the lab

pip install -r requirements.txt
streamlit run src/gui/app.py

Streamlit auto-discovers every file in src/gui/pages/ and lists them in the left sidebar, in the numeric order of their filename prefix (1_..., 2_..., etc.). Click any page to navigate — no reload needed, Streamlit keeps your session state (sidebar widget values) as you move between pages.

Home page

The landing page (src/gui/app.py) gives a one-screen orientation: what the project is, a two-column index of the ten lab pages, the required-reading citation, and an explicit callout about the Table 1 aerodynamic-coefficient caveat (see FAQ). Expand Professor Notes and Student Exercises here (and on every page) for teaching guidance — these are collapsible st.expander sections, closed by default.

1. Coordinate Frames

Interactive exploration of the body-to-geodetic direction cosine matrix L_BE. Three sliders control roll (φ), pitch (θ), yaw (ψ) in degrees; the page recomputes and displays the 3×3 L_BE matrix live, plus where a unit vector pointing along the rocket's nose maps to in North/East/Down coordinates. The kinematics-equation matrix and its gimbal-lock singularity (θ=±90°) are shown below with a warning callout.

Try this: set θ near 90° and watch the mapped vector — this is the gimbal-lock condition discussed in Assignment Exercise 5.

2. State Variables

A reference page, not a simulation — "variable cards" for every element of the 12-state vector plus the derived quantities (α, β, Mach number), each showing: symbol, physical meaning, where it comes from (which equation group produces its derivative), unit, and its effect on the solution. Use this as a glossary while reading the other pages.

3. Forces and Moments

An interactive single-flight-condition calculator: sliders for airspeed, altitude, angle of attack, and roll rate; the page computes Mach number, air density, dynamic pressure, and the resulting axial/normal force, roll moment, and pitch moment live, using the same AeroModel.forces_moments() call the full simulator uses. Good for building intuition about how each input independently affects the force/moment build-up before looking at a full time-history trajectory.

4. Equations of Motion

A static reference page rendering every equation (translational dynamics, Euler's rotational equations, kinematics, navigation, optional Earth- rotation term) as LaTeX, each followed by a plain-language "engineering meaning" paragraph. An expander lists the assumptions behind the equations. Pair this page with a live read of src/simulator/equations_of_motion.py to connect every line of code to its corresponding term.

5. Numerical Integrator

The most "hands-on" page. Controls: fixed-step dt (a select-slider from 0.2s down to 0.001s), elevation angle, and max simulation time. The page runs all three integrators (Euler, RK4, solve_ivp) at your chosen settings and overlays their altitude-vs-time curves on one plot, plus a metrics row showing each method's impact range.

If Euler has visibly diverged (huge or NaN altitude values), a red error banner appears explaining this is the expected instability discussed in docs/numerical-methods.md. A "Run convergence sweep" button computes impact-range error at five dt values against a fine-dt RK4 reference, letting you empirically observe Euler's roughly-linear error decay vs. RK4's much faster decay.

Recommended demo sequence: start at dt=0.01 (stable for both), then push toward dt=0.1 and above — Euler diverges first, and at high enough dt even RK4 eventually does too (a good discussion point on gyroscopic coning frequency near launch, per Assignment Exercise 3).

6. Atmosphere

Three side-by-side plots (temperature, density, sonic speed vs. altitude, 0–15 km) computed from src/simulator/atmosphere.py's standard-atmosphere model, plus a small Mach-number calculator (enter altitude and velocity, read off Mach number). Use this to understand why aerodynamic forces and Mach-dependent coefficients change so much over the course of a multi-kilometer-altitude trajectory.

7. Aerodynamics

Select any of the five tabulated coefficients (CA, CN_alpha, Cl_p, Cmq, Cm_alpha) from a dropdown to see it plotted against Mach number, plus a full data table of all five vs. Mach, and a markdown table explaining what each coefficient means physically and its role in stability. A warning banner at the top reiterates the Table 1 reconstruction caveat.

8. Sensitivity Analysis

Reproduces the paper's Table 2 dispersion study. Pick one of ten uncertainty parameters (launch pitch angle, rocket mass, propellant mass, burn time, thrust, air density, axial/lateral inertia, launch velocity, launch spin rate) from a dropdown, set a sample count and nominal elevation angle, then click "Run sensitivity sweep" to re-simulate the trajectory at each sampled parameter value and plot the resulting range/drift/radial impact error — directly comparable to the paper's Figs. 10–21. A table of all ten parameters' published uncertainty ranges (from Table 2) is shown below.

Note: each sweep runs n_samples full trajectory simulations, so larger sample counts take proportionally longer (a 20-sample sweep typically takes a few seconds).

9. Visualization

The "put it all together" page. Uses the shared sidebar rocket-parameter controls (see below) to run one trajectory, then shows:

  • A 3D trajectory plot (color-mapped by altitude).
  • Tabs for Altitude & Range, Velocity, Acceleration, Angular Rates, Euler Angles, and Aerodynamic Angles vs. time — reproducing the shapes of the paper's Figs. 2–9.
  • A short conceptual note on how dispersion emerges from perturbing many such trajectories (linking to the Sensitivity Analysis page).

10. Simulation Results

Also uses the shared sidebar controls. Shows summary output metrics (time of flight, summit altitude and time, impact range/drift, max speed) — directly comparable to the paper's Fig. 1 "Output Parameters" box and its Sec. 3.3 reported numbers. Below that, a (downsampled) table of the full 12-state time history, with a Download CSV button for further analysis in your own notebook or spreadsheet.

Using the sidebar rocket parameters

Pages 9 and 10 share a sidebar control panel (common.default_rocket_sidebar()): elevation angle, total mass, mean thrust, burn time, muzzle velocity, muzzle spin rate, cross-wind speed, integrator choice, and timestep. Changing any value re-runs the simulation (results are cached per unique parameter combination via st.cache_data, so revisiting a previous setting is instant).

Standalone example scripts

No Streamlit required — plain Python scripts under examples/:

Script Purpose
run_nominal_trajectory.py Run the default rocket and print summary output parameters
timestep_sensitivity.py Print Euler vs. RK4 impact range across six timesteps (Exercise 3 starter)
rk4_vs_solve_ivp.py Compare fixed-step RK4 against adaptive solve_ivp (Exercise 2 starter)
dispersion_sweep.py "<Parameter Name>" Print a one-parameter dispersion sweep (Exercise 8 starter)

Interpreting a divergent trajectory

If you see enormous numbers (1e100+) or NaN in any state variable, the integrator has numerically diverged — usually from too large a fixed timestep relative to the fast gyroscopic "coning" oscillation near launch (see Model and Equations). This is not a bug to report; it's the exact phenomenon Assignment Exercise 3 asks you to characterize. Reduce dt (try halving it repeatedly) until the trajectory stabilizes, and note at what dt each integrator (Euler vs. RK4) becomes stable.

RocketDynamicsLab

Main repository Releases

Clone this wiki locally