From d7795cbb4b0d7026b0cacd89578498e8a9312b71 Mon Sep 17 00:00:00 2001 From: Mauco03 <marco.gaibotti@skywarder.eu> Date: Wed, 19 Feb 2025 12:28:59 +0100 Subject: [PATCH] [documentation] Updated simulator documentation --- common | 2 +- simulator/README.md | 244 +++++++++++++------------------------------- 2 files changed, 73 insertions(+), 173 deletions(-) diff --git a/common b/common index 980f4165..1d057a42 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 980f4165e3b771afc96141ea1dadb033d5a42320 +Subproject commit 1d057a42688bd9d78885f61dd52b4bd3cb6495b1 diff --git a/simulator/README.md b/simulator/README.md index 13d7ce95..ab48bdc0 100644 --- a/simulator/README.md +++ b/simulator/README.md @@ -1,178 +1,76 @@ # simulator -This is a program developed in MATLAB for the simulation of 6 d.o.f. rocket dynamics during all phases of flight: thrust, coast, apogee and recovery. <br/> -It predicts 3D trajectory, apogee height, forces acting on the rockets, and various other aerodynamic values. <br/> -This simulator can also run stochastic simulations with multiple options. <br/> -More detailed information about the physical model of the simulator is available in [documentation.pdf](https://git.skywarder.eu/afd/msa/msa-toolkit/-/blob/master/documentation.pdf) - -## Usage - -#### Required files -The simulator requires aerodynamic coefficients as input, we compute them using Missile DATCOM 97, in the [`msa_toolkit/data/ROCKET_NAME`](https://git.skywarder.eu/afd/msa/msa-toolkit/-/tree/master/data) folder there must be one <code>.mat</code> file that contains the aerodynamic coefficients of the rocket. - -This file contains: (click on each item to learn more) - -<details> -<summary>Geometry (1x1 struct)</summary> - -- **Chord1:** length of fixed chord of the fins (double) [m] -- **Chord2:** length of free chord of the fins (double) [m] -- **Height:** radial distance from the body of the rocket to the tip of the fins (double) [m] -- **deltaXLE:** axial distance from beginning of fixed chord and beginning of free chord (double) [m] -- **C:** body diameter (Caliber) (double) [m] -- **Lnose:** length of the nosecone from tip to base (double) [m] -- **Lcenter:** length of the rocket's body (double) [m] -- **Npanel:** number of fins (int) -- **OgType:** type of nosecone (string) -- **xcg:** distance of the center of gravity from nosecone tip (double) [m] -- **boatL:** length of the boat tail (double) [m] -- **boatD:** diameter of the rear part of the boat tail (double) [m] -- **cMod:** c parameter of the modified haack nose cone shape (double) [-] -- **pMod:** p parameter of the modified haack nose cone shape (double) [-] -- **xcgf:** position of the wet center of gravity (rocket with propellant) from the nose cone base. (double) [m] -- **xcge:** position of the dry center of gravity (rocket without propellant) from the nose cone base. (double) [m] -</details> - -<details> - <summary>State (1x1 struct)</summary> - -- **Machs:** vector of mach numbers passed to datcom (double) -- **Alphas:** vector of alpha angles passed to datcom (double) -- **Betas:** vector of beta angles passed to datcom (double) -- **Altitude:** vector of altitudes passed to datcom (double) -- **hprot:** height of protuberances (airbrakes) passed to datcom (double) -- **xcgTime:** time vector for the relative xcgs (double) - -</details> - -<details> - <summary>CoeffsTot (7-D double)</summary><br/> -This matrix contains the aerodynamic coefficients computed for the input parameters, its indices are: - -1. Coefficient -2. Alphas -3. Machs -4. Betas -5. Altitudes -6. Airbrake value -7. Center of gravity position - -The first index contains 15 different coefficients in position 1-15 which respectivly are: <br/> - -1. **CA:** Axial force coefficient -2. **CYB:** Side force coefficient derivative with BETA -3. **CY:** Side force coefficient -4. **CNA:** Normal force coefficient derivative with ALPHA -5. **CN:** Normal force coefficient -6. **CL:** Lift coefficient -7. **Clp:** Rolling moment coefficient derivative with roll rate -8. **Cma:** Pitching moment coefficient derivative with ALPHA -9. **Cm:** Pitching moment coefficient -10. **Cmad:** Pitching moment coefficient due to rate of change of ALPHA -11. **Cmq:** Pitching moment coefficient derivative with pitch rate -12. **Cnb:** Yawing moment coefficient derivative with BETA angle -13. **Cn:** Yawing moment coefficient (body axis) -14. **Cnr:** Yawing moment coefficient derivative with yaw rate -15. **Cnp:** Yawing moment coefficient derivative with roll rate -</details> - -<br/> -The coefficient matrix is computed sampling the movement of the position of the center of gravity along the X axis (x.c.g.) during the engine burn (its position is constant when the engine is not firing) 5 times (but you can choose to do it more frequently or less in <code>autoMatricesProtub/configAutoMatProtub.m</code>) and aproximated linear between those 5 points. -<br/> <br/> -When the simulation needs a coefficient for some flight conditions that is not in the matrix it will choose the one that was computed using the nearest flight conditions to the one it needs. (nearest neighbor interpolation) <br/><br/> - -You will also need to have a .m file in the same [`msa_toolkit/data/ROCKET_NAME`](https://git.skywarder.eu/afd/msa/msa-toolkit/-/tree/master/data) folder called <code>simulationsData.m</code> in which you'll need to specify: - -* Rocket name -* Launch pad info: - * Launchpad Altitude [m] - * Distance from base of second pin [m] - * LaunchPad route (total available route) [m] - * Launchpad latitude [deg] - * Launchpad longitude [deg] - * Gravity costant at launch latitude and altitude - -* Engine data: - * Propellant Mass [kg] - * Burning time [s] - * Case mass [kg] - * Structural Mass [kg] - * Total Mass [kg] - * Nosecone Mass [kg] -* Geometry, mass, aerodynamic properties (length, mass, moments of inertia, reference surface etc..) - -* airbrakes control: - * time after which the airbrakes can be used [s] - * Maximum Mach number at which airbrakes can be used [-] - * Servo-motor angular velocity [rad/s] - * Block airbrakes opening coordinate [m] -* Parachute details: (for every parachute) - * Surface [m^2] - * Mass [kg] - * Parachute Drag Coefficient - * Parachute Lift Coefficient - * drogue opening delay [s] - * Final altitude of the parachute [m] - * Parachute Longitudinal Drag Coefficient - * Shock Chord Length [m] - * Shock Chord Elastic Constant [N/m^2] - * Shock Chord Dynamic Coefficient [Ns/m] - * Coefficient of the surface vs. time opening model [m^2/s] - * Adimensional Opening Time - * Expulsion Speed [m/s] -* Integration options -* Stochastic details options -* Landing point options - -#### Config Setup -Before starting the simulation, data and parameters to be used must be specified in `configSimulator.m` by changing the appropriate field in the `settings` variable, such as: - -* Launchpad data (Elevation, azimuth) -* Airbrakes data: -You can choose to have only one opening of the airbrakes to a specified percentage (0-50-100) and keep them opened like that for the rest of the flight or you can have multiple openings at different percentages one after the other, for the latter you'll need to set these variables as follows: - * **control:** [] in this array you'll need to put any number of integer values between 1 and 3, where 1 = 0% airbrakes opened (by surface area), 2 = 50%, 3 = 100%. <br/> The rocket will open the airbrakes following the values in the array, so for example [1 2 3 2 3] means that the rocket will open the airbrakes first at 0%, then at 50% then at 100%, then 50%, then 100% for the rest of the flight. - * **dtControl:** [] is an array in which the value in position x is the amount of time the rocket has the airbrakes opened in the <code>settings.control(x)</code> position. <br/> The length of dtControl is the length of control -1, because when the rocket has the airbrakes opened in the last position it will keep them like that until landing. - -* Wind model to be used (constant wind or atmoshwm wind model) -* Type of simulation to be performed (ascent phase + parachute descent, ballistic, stochastic, parachute failure etc..) -* Plot(s) settings - -The appropriate simulation is then started running `mainSimulator.m`. - -## Options - -The standard simulation is a 6 d.o.f. dynamics in the ascent phase and 3 d.o.f. descent with a parachute. However it is possible to simulate the descent phase using a 6 d.o.f. dynamics. <br/> -You can change this setting by setting the <code>settings.descent6DOF</code> variable true or false, if set to true the simulator will plot various data regarding the parachute such as drag force, chord elongation, chord tension and how its (S * Cd) / (S0 * Cd0) (S = surface area, Cd = drag coefficient) changes over time. -<br/> -**Note:** You can't use 6 D.o.F. descent dynamics for a stochastic simulation. - - -If you want a completely ballistic simulation with no parachutes you can have it by changing the <code>settings.ballistic</code> variable to true, it won't output the parachute data obviusly.<br/><br/> - -The simulator also allows for the possibility of a stochastic simulation (using multiple cores with the parallel computing toolbox) using different values of wind intensity and direction, in order to perform a stastistics analysis of the landing position. <br/> -Set this variable to the number of simulations you want to run: <code>settings.stoch.N</code><br/> -You will also need to change one of these parameters to perform a stochastic simulation: - -- Max/min launch pad elevation -- Max/min launch pad azimuth -- Wind: - - Max/min elevation (random wind model) - - Max/min azimuth (random wind model) - - Max/min intensity (random wind model) - - Wind intensity gradient with altitude (input wind model) - - Wind azimuth at each altitude (input wind model) -- Day of launch -- Hour of launch - -**A stochastic simulation will output the following data:** - -- Mean landing point (X,Y) -- Mean apogee altitude with its standard deviation -- Mean apogee time with its standard deviation -- Percentage of launch probability: a measure of the "safety" of the launches, it calculates if the rockets lands in a "safe ellipse" and if its apogee velocity with respect to the wind is below a certain value. +This program is developed in MATLAB for the simulation of 6 d.o.f. rocket dynamics during all phases of flight: thrust, coast, apogee, and recovery. It predicts 3D trajectory, apogee height, forces acting on the rocket, and various other aerodynamic values. This simulator can also run stochastic simulations with multiple options. More detailed information about the physical model of the simulator is available in [documentation.pdf](https://git.skywarder.eu/afd/msa/msa-toolkit/-/blob/master/documentation.pdf). + +--- + +## How to Use It + +1. **Configure the Settings:** The script `simulatorConfig.m` is where you set up the parameters for the simulation. You can configure: + * **Simulation Flags:** Choose the type of simulation (e.g., parafoil, ballistic). + * **Plot Preferences:** Decide if you want charts, text summaries, or to save the detailed results. + +2. **Run Script:** Execute the function `mainSimulator` to start the simulation process. You can optionally feed `Rocket`, `Environment`, and `Wind` objects to override config readings and use name-value arguments to change option flags. + + **Example Usage:** + ```matlab + mission = Mission(true); + rocket = Rocket(mission); + environment = Environment(mission, rocket.motor); + wind = WindCustom(mission); + + [ascent, descent] = mainSimulator(rocket, wind, environment, settings, ... + 'parafoil', true, 'ballistic', false, 'prints', true, 'plots', true); + ``` + +3. **Check Out the Results:** Once it's done running, you'll get: + * **Charts:** The tool makes graphs that show various flight parameters. + * **Text Summary:** The function prints the key simulation results. + +--- + +## Key Files + +* **`mainSimulator.m`:** The main function to run the simulation. It: + * Loads the necessary data and configurations. + * Runs the simulation for the ascent and descent phases. + * Generates charts, prints the text summary, and saves the results based on your settings. + +* **`simulatorConfig.m`:** The configuration script where you set up the parameters for the simulation. Key settings include: + * **Simulation Flags:** Choose the type of simulation (e.g., parafoil, ballistic). + * **Plot Preferences:** Decide if you want charts, text summaries, and if you want to save the data. + + **Example Settings Inside `simulatorConfig.m`:** + ```matlab + %% SIMULATION FLAGS + simulator.parafoil = true; % True if parafoil open loop descent needs to be performed + simulator.ballistic = false; % True to run a ballistic (without parachutes) simulation + + %% PLOTS + simulator.prints = false; % True to print data after simulation + simulator.plots = false; % True to plot data after simulation + simulator.landingMap = true; % True to run geoplots + simulator.satellite3D = false; % True to plot trajectory on 3D map + simulator.SMonly = true; % True to plot only SM (useful during design!) + ``` + +--- + +## Configuration Files + +The simulator requires several configuration files located under `common/missions/config`. These files include: + +* **`rocketConfig.m`:** Contains the rocket's geometric and mass properties. +* **`environmentConfig.m`:** Contains the launch site dependent variables. +* **`windConfig.m`:** Contains the wind model parameters. +* **`motorConfig.m`:** Contains the motor parameters. +* **`parachuteConfig.m`:** Contains the parachute parameters. + +--- ## Output -The simulator records and outputs in the Matlab console the following data: (for a stochastic simulation output look in the [Options](#Options) section) + +The simulator records and outputs in the Matlab console the following data: (for a stochastic simulation output look in the Options section) - Apogee altitude [m] - Total time of flight [s] @@ -192,7 +90,9 @@ The simulator records and outputs in the Matlab console the following data: (for - longitude of landing point [deg] - speed at apogee relative to wind velocity [m/s] -<br/> +Additionally, the `mainSimulator` function can return the ascent and descent data as a struct. + +--- #### Plots Data that can be plotted at each timestep: -- GitLab