diff --git a/README.md b/README.md index 0b56cb085def74a13abdd99f366def123fe7fb10..717fd2f3703183302e271a3c6c605f965ef2c9a2 100644 --- a/README.md +++ b/README.md @@ -1,54 +1,79 @@  # msa-toolkit -The ***MSA toolkit*** is the repository in which the code implemented by the Mission Analysis team is stored. It is composed by several folders. <br/> -In order to properly run the msa toolkit code in matlab you will need to install the following matlab add-ons: +The ***MSA toolkit*** is the repository in which the code implemented by the Mission Analysis team is stored. It is composed of several folders. -* Aerospace Toolbox -* Global Optimization Toolbox -* Mapping Toolbox -* Optimization Toolbox -* Parallel Computing Toolbox -* Statistics and Machine Learning Toolbox +In order to properly run the msa toolkit code in MATLAB, you will need to install the following MATLAB add-ons: + +* **Simulink** +* **Aerospace Blockset** +* **Aerospace Toolbox** +* **Deep Learning Toolbox** +* **Global Optimization Toolbox** +* **Mapping Toolbox** +* **Navigation Toolbox** +* **Optimization Toolbox** +* **Parallel Computing Toolbox** +* **Statistics and Machine Learning Toolbox** +* **Symbolic Math Toolbox** + +The repository itself contains the necessary tools, while the majority of the data is stored in the common folder, which is a *submodule* linked to the common repository. ### aerodynamicsOptimization -This program implements an aerodynamics optimization of the rocket. <br/> -The rocket is optimized to reach the highest apogee possible with the chosen set of fixed parameters. <br/> -The code uses a genetic algorithm to reach the goal. It may take some time to run. <br/> +This program implements an aerodynamics optimization of the rocket. The rocket is optimized to reach the highest apogee possible with the chosen set of fixed parameters using a genetic algorithm. It may take some time to run. + +**Example:** +```matlab +mainOptimization(rocket, wind, environment, settings); +``` ### apogeeAnalysis -This program is developed for a primary apogee -analysis with different engines when the structural mass -is only known with a degree of uncertainty. -The simulator computes the different apogees, maximum -accelerations and launchpad exit velocities for -different motors and different masses. +This program is developed for a primary apogee analysis with different engines when the structural mass is only known with a degree of uncertainty. The simulator computes the different apogees, maximum accelerations, and launchpad exit velocities for different motors and different masses. -### autoMatricesProtub -This program allows for an automatic computation of the rocket aerodynamic coefficients using Dissile MATCOM, for different airbrakes configuration. +**Example:** +```matlab +[standardResults, engineCutResults] = mainApogeeAnalysis(rocket, settings, analysis, plots); +``` -### commonFunctions -In this folder, the common functions employed in the code of the toolkit are stored. +### autoMatricesProtub +This program allows for an automatic computation of the rocket aerodynamic coefficients, for different airbrakes configurations. -### data -Folder with the flight data, rocket geometry and simulation parameters. +**Example:** +```matlab +[coeffsTot, coeffsTotHighAOA] = mainAutoMatProtub(rocket, environment, settings); +``` ### sensitivityAnalysis -This program implements a sensitivity analysis on the ascent phase of the rocket. Two types of analyses are available: deterministic and stochastic. <br/> -In the deterministic analysis it is possible to vary the nominal values of the aerodynamics coefficients and the structural mass of the rocket. -The relative magnitude of the variations is set by the user and it is the same for all the parameters considered in the analysis. <br/> -In the stochastic analysis several simulations are performed, in each of these the uncertain parameters assume values according to a normal distribution centered on their respective nominal values. +This program implements a sensitivity analysis on the ascent phase of the rocket. Two types of analyses are available: deterministic and stochastic. In the deterministic analysis, it is possible to vary the nominal values of the aerodynamics coefficients and the structural mass of the rocket. In the stochastic analysis, several simulations are performed, in each of these the uncertain parameters assume values according to a normal distribution centered on their respective nominal values. + +**Example:** +```matlab +[postProcess, parameters] = mainSensitivity(rocket, wind, environment, settings, plots); +``` ### 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 rocket, and various other aerodynamic values. <br/> -This simulator can also run stochastic simulations with multiple options. <br/> +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. 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. + +**Example:** +```matlab +[ascent, descent] = mainSimulator(rocket, wind, environment, settings); +``` ### stabilityAnalysis This program is used to compute and investigate the stability of the rocket in various flight conditions. +**Example:** +```matlab +mainStabilityAnalysis(rocket, wind, environment, settings); +``` + ### unitTests This program is used to create and perform tests on the toolkit to ensure that it always produces correct results. +**Example:** +```matlab +results = runtests('mainUnitTests.m'); +``` + ### utils -Although the most important folders are in the main path, this folder contains work-alone tools, and some useful scripts. +Although the most important folders are in the main path, this folder contains standalone tools and some useful scripts. diff --git a/aerodynamicsOptimization/README.md b/aerodynamicsOptimization/README.md index 35c51ca1c583df34e9585f7490911173409a47e4..6fbc0ce17549ad99b42cc7efefba42260e113d09 100644 --- a/aerodynamicsOptimization/README.md +++ b/aerodynamicsOptimization/README.md @@ -3,15 +3,20 @@ This is a program developed in MATLAB which implements an aerodynamic optimizati The rocket is optimized to reach the highest possible apogee with the chosen set of fixed parameters using a genetic algorithm. It may take some time to run, please be patient. <br/> ## Usage -The optimization variables are the fin chords and height, the fin shape, the ogive length and shape and the boat tail length. <br/> -The variable's range and other features can be set in the configOptimization script and quantities are integers to run faster without a big optimization loss. <br/> -The script requires the rocket data which is taken from the `simulationsData.m` script: +The following table shows the available optimisation parameters -``` matlab -settings.mission = 'mission_name'; -run(strcat('../data/', settings.mission, '/simulationsData')); -``` -and variables to describe the mission-specific parameters, defined in the `configOptimization.m`: +| Parameter | Number | Notes | +|:----------------:|:------:|:------------------------------------------------:| +| Fins chord | 1, 2 | - | +| Fins height | 3 | - | +| Fins sweep | 4 | Measured as distance between start of chords | +| Ogive length | 5 | - | +| Ogive shape | 6, 7 | Valid for modified Haack: edits coefficients p, C | +| Boat-tail length | 8 | - | +| Nosecone type | 9 | - | + +The variable's range and other features can be set in the optimisationConfig script and quantities are integers to run faster. <br/> +The function requires the rocket data, taken from the `rocketConfig.m` script and variables to describe the mission-specific parameters, defined in `optimisationConfig.m`: ``` matlab % mission information @@ -21,20 +26,20 @@ vars.Beta = linspace(-20, 20, 20); vars.Alt = linspace(0, 4000, 5); vars.xcg = settings.xcg; ``` -You have to replace `mission_name` with the specific name of the mission required. <br/> -Moreover, the variables that cannot be known a priori, like the flight conditions, the wind magnitude or the minimum required stability margin at the launchpad exit, are taken from the `configOptimization.m` script. The variable `expectedApogee` actually allows you to set the tolerance of the genetic algorithm, so the higher is the expected apogee, the lower is the tolerance and the more precise is the optimization. <br/> -It is also important to set the matrix of inequalities in `configOptimization.m` that acts as constraint on the optimization variables as required from the GA. <br/> -The optimization is started by running the `mainOptimization.m` script. + +The variables that cannot be known a priori, like the flight conditions, the wind magnitude or the minimum required stability margin at the launchpad exit, are taken from the `optimisationConfig.m` script. The variable `expectedApogee` actually allows you to set the tolerance of the genetic algorithm, defined as $tol = \frac{1}{\texttt{Apogee}_{exp}}$ so the higher is the expected apogee, the lower is the tolerance and the more precise is the optimization. <br/> +It is also important to set the matrix of inequalities in `optimisationConfig.m` that acts as constraint on the optimization variables as required from the GA. <br/> +The optimization is started by running the `mainOptimization.m` function. ## Options You can optimize the rocket and the boat tail or just the rocket, keeping the boat tail fixed:<br/> -* In the first case, you have to set `settings.boatOptimization = false;` in `configOptimization.m`. In this scenario, you have to also set the parameters describing the boat tail in `simulationsData`. +* In the first case, you have to set `settings.boatOptimization = false;` in `optimisationConfig.m`. In this scenario, you have to also set the parameters describing the boat tail in `simulationsData`. -* In the second case, you have to set `settings.boatOptimization = true;` in `configOptimization.m`. In this scenario, you have also to set the parameters describing the boundaries of the optimization, which are `settings.optimBoatD`, `settings.maxBoatL` and `settings.maxBeta` and check that the matrix of inequalities is suitable with the geometry of the rocket you are trying to optimize. Please note that the process will take more time. +* In the second case, you have to set `settings.boatOptimization = true;` in `optimisationConfig.m`. In this scenario, you have also to set the parameters describing the boundaries of the optimization, which are `settings.optimBoatD`, `settings.maxBoatL` and `settings.maxBeta` and check that the matrix of inequalities is suitable with the geometry of the rocket you are trying to optimize. Please note that the process will take more time. ## Output -The output data consists in a set of optimization variables which allow the rocket to reach the maximum apogee with the chosen tolerance. \ No newline at end of file +The output data consists in a print of optimization variables which allow the rocket to reach the maximum apogee with the chosen tolerance. \ No newline at end of file diff --git a/apogeeAnalysis/README.md b/apogeeAnalysis/README.md index 0f11666d3c7de66f18eea78ef6a18b3965185cc2..16c536dd375b01453e12e6ac6a5076189153a50a 100644 --- a/apogeeAnalysis/README.md +++ b/apogeeAnalysis/README.md @@ -1,82 +1,82 @@ -# apogeeAnalysis -This is a program developed in MATLAB for a primary apogee -analysis with different motors when the structural mass -is only known with a degree of uncertainty. -The simulator computes the different apogees, maximum -accelerations and launchpad exit velocities for -different motors and different masses. <br/> -You can choose between simulating engines with a full or partial burn duration, in the latter the engine is cut at a fixed percentage of total burn time. - -## Usage -The script requires the geometric variables describing the rocket which are taken from `simulationsData.m`: - -``` matlab -settings.mission = 'missionName'; -dataPath = strcat('../data/', settings.mission); -run(strcat(dataPath, '/simulationsData')); +### 3️⃣ **Review Output** + +The simulation results are saved into structured variables for analysis and visualization. The following metrics are included: + +#### **Standard Analysis Results** +- **Apogee**: Maximum altitude achieved. +- **Maximum Acceleration**: Peak acceleration during flight, limited to 15g. +- **Launchpad Exit Velocity**: Velocity at launchpad exit, limited to 20 m/s. +- **Computation Time**: Time taken for the simulation. + +#### **Engine Cut Analysis Results** +- **Apogee**: Maximum altitude with engine cut-off considered. +- **Cut-Off Timing Variations**: Evaluates performance with up to 5 variations around 80% engine cut-off time. +- **Launchpad Exit Velocity**: Initial velocity, limited to 20 m/s. +- **Computation Time**: Time taken for the simulation. + +**Example Output**: +```matlab +standardResults = struct('apogee', 3100, 'maxAcceleration', 14.5, 'exitVelocity', 25, 'compTime', 2.7); +engineCutResults = struct('apogee', 2800, 'cutOffTimeVariations', 5, 'exitVelocity', 22, 'compTime', 3.1); ``` -where you have to replace `missionName` with the specific name of the mission required (e.g. `Lynx_Portugal_October_2021`).<br/> -The variables that do not depend directly on the geometry of the rocket and that cannot be known a priori, such as the masses computed, are taken from `configApogee.m`.<br/> - -For instance, you need to choose: - -- total impulse range. It allows -the simulator to pick the motors that are in this range -from the motors matrix (`Motors.mat`) -- deviation from the structural mass -- amount of mass points in this deviation, -in order to have a different range of masses -- company that produces the engine - -The plots of maximum acceleration and launchpad exit -velocity can be chosen by setting: - -- `settings.accelerationPlot = true` -- `settings.launchpadVelPlot = true` - -For both 'upwind' and 'downwind' you have to choose: - -- wind magnitude, -- wind elevation -- wind azimuth -- elevation (`OMEGA`) of the launchpad -- azimuth (`PHI`) of the launchpad -- airbrakes height (1= closed, 2= 50% open, 3= fully open). - -Here there is a brief explaination regarding those two configuration: - -- `upwind` is what we consider the best case. In fact, in this case, wind magnitude is set to 0 and the elevation of the launchpad is 90 degrees. Moreover, airbrakes are fully open. -- `downwind` is what we consider the worst case. In fact, in this case, wind magnitude is set to 9 m/s (maximum for EuRoC rules). It is directed with an angle of 180 degrees out of phase with respect to launchpad azimuth. Moreover, airbrakes are closed. - - -The computation is started by running `mainApogee.m`. - -Once the simulation is started, it runs -`quickApogeeOnly.m`, which gives apogees and maximum -accelerations for -every motor, mass, airbrakes configuration, wind condition and launchpad setup as -outputs. - -Then, it runs `exitVelocity.m`, which gives launchpad exit velocity for -every motor, mass, airbrakes, wind condition and launchpad setup as -outputs. - -## Outputs -The main outputs are the apogee, the maximum acceleration and the launchpad exit velocity for every motor, mass, airbrakes, wind condition and launchpad setup. -This program will then plot a number of different figures, -which will be a combination of the wind and airbrakes -condition chosen. - -#### Plots -In every figure there will be three subplots where -apogees, maximum accelerations and launchpad exit -velocities will be plotted for every motor in every -mass point. There will also be a legend, where the -motors will be listed in the same order (and color) -they appear in the apogee subplot. -In the plots, some areas and lines appear. They represent the following things: - -- Green areas in both `upwind` and `downwind`, which represent graphically apogees for which the motors falling in it are acceptable. -- Line in the apogee subplot, which represents the targeted apogee. -- Line in the maximum acceleration subplot, which represents the maximum acceleration acceptable for electronic and structure constraints. -- Line in the launchpad exit velocity subplot, which represents the minimum launchpad exit velocity acceptable for competition requirements. + + +## 📊 **Output Metrics** + +### **Standard Results** +The following metrics are calculated during the standard apogee analysis: +- **Apogee**: Maximum altitude reached by the rocket in meters. +- **Maximum Acceleration**: The highest acceleration experienced by the rocket during flight in g's. +- **Launchpad Exit Velocity**: The velocity of the rocket at the moment of launchpad exit in meters per second. +- **Computational Time**: Time taken to execute the simulation. + +### **Engine Cut Results** +For the engine cut scenario, the same metrics are calculated but with additional analysis on the effect of engine cutoff during flight: +- **Apogee**: Maximum altitude reached with engine cutoff simulated. +- **Maximum Acceleration**: The highest acceleration experienced with engine cutoff simulated. +- **Launchpad Exit Velocity**: The velocity at the moment of launchpad exit, simulating the effect of engine cutoff. +- **Computational Time**: Time taken to execute the engine cut simulation. + +### **Plots** +The following plots are generated based on the configuration settings: +- **Acceleration Plot**: Shows the rocket’s acceleration over time. +- **Launchpad Exit Velocity Plot**: Displays the rocket’s exit velocity against time. +- **Apogee Distribution Plot**: Displays the distribution of apogee values for all simulation runs, including uncertainties. + + + +## ⚠️ **Troubleshooting Output Issues** + +If the output data is not as expected, consider the following: + +1. **Check Configurations**: Ensure that motor settings, uncertainties, and environmental parameters are correctly specified in the `configApogee.m` file. Incorrect or missing configuration values could lead to unexpected results or errors during the simulation. + +2. **Inspect Simulation Logs**: Errors or warnings during the simulation will appear in the MATLAB command window. These logs provide helpful insights into what went wrong. Pay attention to any messages related to motor selection, uncertainties, or configuration issues that may require adjustment. + +3. **Verify Data Integrity**: If the simulation finishes successfully but the results appear invalid (e.g., unrealistic apogee or acceleration), ensure that the input data, such as motor properties, uncertainties, and environmental conditions, are reasonable and correctly configured. + +4. **Plot Visibility**: If plots are not displaying as expected, verify that the plotting options are enabled in the `configApogee.m` file. Additionally, ensure that the plot generation conditions (e.g., valid data for acceleration and exit velocity) are met. + +5. **Examine File Paths**: Make sure that the results and plot saving paths are correctly specified and accessible. Missing or incorrect file paths can prevent the saving of output data or plots. + +--- + +## 📝 **Further Analysis and Customization** + +You can further customize the post-simulation process and analysis: + +- **Modify Plotting Functions**: You can adjust the existing plotting functions in the `mainApogeeAnalysis.m` file to generate additional visualizations. For example, you could create additional plots for other metrics or different stages of the rocket flight. + +- **Sensitivity and Uncertainty Analysis**: If you want to analyze how different parameters affect the outcome, consider performing sensitivity analysis by adjusting one or more parameters, such as motor thrust or environmental conditions. This will help identify which factors have the greatest impact on apogee or acceleration. + +- **Advanced Statistical Analysis**: You can incorporate more advanced statistical tools to interpret the simulation results, such as Monte Carlo simulations, if you want to study the effect of uncertainty propagation in the system. + +- **Automate Comparison**: If you're running multiple simulations with different configurations, consider writing a MATLAB script that automatically compares the results and generates summary statistics or plots for easy interpretation. + +--- + +## 🛠 **License and Support** + +This simulation framework is developed and maintained by **Skyward Experimental Rocketry** and is licensed under the **GPL-3.0-or-later** license. +For support, collaborations, or further inquiries, please contact us at [support@skywardrocket.com](mailto:support@skywardrocket.com). + diff --git a/autoMatricesProtub/README.md b/autoMatricesProtub/README.md index 9c562a1c487486a659800449e19cb2de6e7d2093..165ba7a9815cceef6bc4041a7f9b0d4635bde73a 100644 --- a/autoMatricesProtub/README.md +++ b/autoMatricesProtub/README.md @@ -1,19 +1,75 @@ # autoMatricesProtub -This is a program developed in MATLAB to create the aerodynamic matrices of a rocket using Missile DATCOM 97 for different airbrakes configurations. -## Usage -The script requires the geometric variables describing the rocket which are taken from `simulationsData.m`: +This program is developed in MATLAB to create the aerodynamic matrices of a rocket using Missile DATCOM 97 for different airbrakes configurations. -``` matlab -settings.mission = 'mission_name'; -dataPath = strcat('../data/', settings.mission); -run(strcat(dataPath,'/simulationsData.m')); -``` -where you have to replace `mission_name` with the specific name of the mission required.<br/> -The variables that do not depend directly on the geometry of the rocket and that cannot be known a priori, like flight conditions, are taken from `configAutoMatProtub.m`.<br/> -The computation is started by running `mainAutoMatProtub.m` +--- + +## How to Use It + +1. **Configure the Settings:** The script `autoMatProtubConfig.m` is where you set up the parameters for Missile DATCOM. You can configure: + * **State Values:** Define the Mach numbers, angles of attack, sideslip angles, and altitudes for which the aerodynamic coefficients will be computed. + * **High AOA Values:** Set the parameters for high angle of attack scenarios. + * **XCG Discretization:** Specify the number of center of gravity positions to generate aerodynamic matrices. + +2. **Run Script:** Execute the script `mainAutoMatProtub.m` to start the computation process. + +3. **Check Out the Results:** Once the computation is complete, the results are saved in `.mat` files in the mission's data directory. + +--- + +## Key Files + +* **`mainAutoMatProtub.m`:** The main script to run the computation. It: + * Loads the necessary data and configurations. + * Computes the aerodynamic coefficients for both standard and high angle of attack scenarios. + * Saves the results in `.mat` files. + +* **`autoMatProtubConfig.m`:** The configuration script where you set up the parameters for the aerodynamic computation. Key settings include: + * **State Values:** Mach numbers, angles of attack, sideslip angles, and altitudes. + * **High AOA Values:** Parameters for high angle of attack scenarios. + * **XCG Discretization:** Number of center of gravity positions. + + **Example Settings Inside `autoMatProtubConfig.m`:** + ```matlab + %% STATES + vars.mach = 0.05:0.05:1; + vars.alpha = [-22 -15 -10 -7.5 -5 -2.5 -1 -0.5 -0.1 0 0.1 0.5 1 2.5 5 7.5 10 15 22]; + vars.beta = [-13 -8 -5 -2.5 -0.1 0 0.1 2.5 5 8 13]; + vars.alt = (0:400:4000); % above local ground (env.z0 will be added in main) + + %% HIGH AOA + varsHighAOA.mach = 0.05:0.05:0.7; + varsHighAOA.alpha = [-170 -130 -115 -90.1 -60 -35 -10 -5 -1 0 1 5 10 35 60 90.1 115 130 170]; + varsHighAOA.beta = [-170 -130 -115 -90.1 -60 -35 -10 -5 -1 0 1 5 10 35 60 90.1 115 130 170]; + varsHighAOA.alt = (0:400:4000); % above local ground (env.z0 will be added in main) + + %% XCG Discretization + vars.Nxcg = 3; % Number of wanted xcgs in order to generate N aerodynamic matrices + ``` + +* **`saveVars.m`:** A helper function to save the computed aerodynamic coefficients and state variables into `.mat` files. + +--- ## Output -The output data is stored in one `.mat` file named after the engine in the rocket. -The coefficient matrix is directly saved in `../data/mission_name` and the access to each field is completely numerical, even to select the sub-matrix referred to a specific coefficient. <br/> -For further details about these matrices, we suggest reading the [`README.md`](https://git.skywarder.eu/afd/msa/msa-toolkit/-/tree/master/simulator/README.md) file in the `simulator` folder. + +The output data is stored in `.mat` files named after the engine in the rocket. The coefficient matrices are saved in the mission's data directory under `common/missions/<missionName>/data/<engineName>.mat`. The data includes: + +* **State Variables:** Mach numbers, angles of attack, sideslip angles, altitudes, and center of gravity positions. +* **Geometry Variables:** Rocket geometry parameters such as fin dimensions, nose length, and diameter. +* **Aerodynamic Coefficients:** Coefficients for different flight conditions and airbrake configurations. + +--- + +## Coefficients Matrix Dimensions + +The dimensions of the coefficients matrix are as follows: +* **Coefficients:** The 15 exported aerodynamic coefficients. +* **Alpha:** Angles of attack. +* **Mach:** Mach numbers. +* **Beta:** Sideslip angles. +* **Altitude:** Altitudes. +* **XCG:** Center of gravity positions. +* **Airbrakes:** Airbrake configurations. + + diff --git a/common b/common index 04e332747f9aeb153a4acc79d618caf51db48901..01a8a6416273f3ad59a1420fc8a1602640c67b4c 160000 --- a/common +++ b/common @@ -1 +1 @@ -Subproject commit 04e332747f9aeb153a4acc79d618caf51db48901 +Subproject commit 01a8a6416273f3ad59a1420fc8a1602640c67b4c diff --git a/sensitivityAnalysis/README.md b/sensitivityAnalysis/README.md index c67d997276d3caf21ee7d278c86d79cefc2bb924..b24940c979c21677e3aa2f254b9753c61c978c7a 100644 --- a/sensitivityAnalysis/README.md +++ b/sensitivityAnalysis/README.md @@ -1,71 +1,167 @@ -# sensitivityAnalysis - -This program implements a sensitivity analysis on the ascent phase of the rocket. - - -# Usage - -The analysis type and its features can be set in the script `configSensitivity.m`. -The nominal values of all the parameters are stored in the settings structure. -The uncertanty parameter that can be considered are: - -* **Wind conditions**: -It is possible to select each wind model availabe in the `simulator` with its coresponding parameters -* **Aerodynamics coefficients**: `CA`, `CYB`, `CY0`, `CNA`, `CN0`, `Cl`, `Clp`, `Cma`, `Cm0`, `Cmad`, `Cmq`, `Cnb`, `Cn0`, `Cnr`, `Cnp` -* **Launchpad Elevation**: `omega` -* **Launchpad Azimuth**: `phi` -* **Structural Mass**: `structMass` -* **Propellant Mass**: `expMass` -* **Thrust**: `thrust` -* **Inertias**: `Ixx`, `Iyy` and `Izz` -In particular, uncertanties in wind conditions are set directly through the `cofigSensitivity.m` while all other parameters need to create the corresponding struct to feel the array `parameters`, using the function `createParameter.m` (see the function documentation) in which is possibile to select the parameter, the type of uncertanty distribution and its characterization. - -# Output - -The output consists in series of plot showiong the results statistical distributions for: - -* Apogee -* Velocity - * Apogee velocity (relative to the wind) - * Max rocket velocity (relative to the wind) - * Launchpad exit velocity (relative to the wind) - * Launchpad exit velocity (inertial) -* Stability margin (for this analysis it is suggested to use `stabilityAnalysis.m`) - * At launchpad exit - * Minimum during the flight - * Maximum during the flight -* Rocket structural stress at drogue opening -* Aerodynamic force acting on fins -* Flight time - * To reach the apogee - * To exit the launchpad - -Moreover it is possible to use the function `correlation.m` to study the correlations between 1, 2, 3 or 4 parameters. In particular the first argument needs to be -A list with the strings describing the parameters to correlate, according to the function documentation. If there is just one parameter, an hystogram like those on the nominal output is produced, while if there is an higher number a 2D, 3D or 3D+colormap figure is producede with a parameter in each axis. The supported parameter are: - -* zApo: apogee altitude -* times(1): time to exit the launchpad -* times(2): time to reach the apogee -* vrApo: velocity relative to the wind at the apogee -* alphaTot(1): alpha total at launchpad exit -* alphaTot(2): alpha total at apogee -* vExit(1): inertial velocity at launchpad exit -* vExit(2): wind relative velocity at launchpad exit -* accMax: max acceleration -* SM(1): Minimum stability margin -* SM(2): Maximum stability margin -* SM(3): Launchpad exit stability margin -* vMax: max velocity -* machMax: max Mach number -* windMag(1): wind magnitude at ground level -* windMag(2): wind magnitude at apogee -* windMag(3): wind magnitude mean -* windMag(4): wind magnitude max -* windAz(1): wind azimuth at ground level -* windAz(2): wind azimuth at apogee -* windAz(3): wind azimuth mean -* windAz(4): wind azimuth at wind max magnitude -* maxFinForce: max force normal to each fin -* bendingTorqueApo: bending torque generated by the drogue opening at apogee -* Each other uncertanty parameter selected in the config throug the function `createParameter.m` by inserting its string name +# sensitivityAnalysis Tool Guide +This guide offers step-by-step instructions for using the sensitivity analysis tool. To help you better understand the results and simplify the process, the guide is organized into clear steps. Each step provides instructions, along with explanations of the tool's functions and methods. + +Before diving into the details, it's important to understand when this tool is typically used. It comes into play during key phases of the project, particularly when preparing for launches in Roccaraso and at the Euroc competition. Therefore, it's crucial to use the tool accurately to avoid misinterpretations and unexpected situations. Additionally, the tool can also be used throughout the year in a more relaxed context to validate parachute geometrical parameters, such as area, and assess the weight of rocket components, which can significantly impact performance and the outcomes of stochastic simulations. + +### All the functions called + +`mainSensitivity.m` calls various scripts and functions, but there are two important files from which everything starts. The first one is the config file, which is not actually run because every config file in the toolkit acts as an object, of class Settings, which takes the name of the used toolkit. Then we have the `sensitivityStochRun.m` which recalls some important functions which are frequently called by each toolkit and also some custom functions for the sensitivity only. + +| simulations | post process functions | characteristics | +| ------------- | ---------------------- | ---------------------------------------------------------------------------------------- | +| stdAscent | postprocessAscent | this function post processes the results obtained from the stdAscent simulation | +| stdDescent | postprocessDescentPara | this function porst processes the results obtained from the ballistic descent simulation | +| stdDescentBal | postprocessDescentBall | on the other hand this function post processes the nominal parachute descent | +| stdStability | postprocessStability | this function analyzes the results of stability analysis during flight | +| | postprocessLaunchMode* | this function post processes the entire flight | + + +| ODE functions | +| --------------- | +| ballistic | +| descent | +| descentParafoil | + +There are also some many others functions which are called from the script, including *Dissile Matcom* and some other functions which perform *interpolations*, in addiction to some specific funciton for *geoplots*. + +## 1. Configuration: Sensitivity Config + +The `sensitivityConfig.m` file is the starting point for configuring the simulation. It defines the main sensitivity parameters. Below are the key configurations: + +### Main Parameters +- **`sensitivity.n`**: Number of simulations to run. + Set this value based on the desired level of accuracy. A higher number increases detail but also computational time. + +- **`sensitivity.type`**: Number of simulations to execute. +You can perform different types of stochastic simulations and you can select the one you need by chossing the right numer from the list + - **1-apogee only**: this performs only the stochastic simulations of the apogee (it is employed during the design phase to validate masses and engine performances); with this you can reasonably see you performance in terms of apogee and its variations (the very first objective of the Euroc competition!) + - **2-ballistic descent**: this simulation performs the ballistic descent, which is the rocket desent without parachute, so with no control. This is the most critical situation, which has to be estimated because a ballistic rocket has no chance to be controlled by any surface, when, of couerse, the parachute doesn't operate nominaly. The risck assesment of the ballistic performance is also one of the Euroc requirements! + - **3-parachute descent**: this simulation is the "nominal" one, technically executed and analysed at the very last phase of the design to simulate the entire nominal flight. + - **4-both ballistic and parachute descent**: this simulation performs 2 and 3 together; it is usefull to get comparisons + - **5-stability**: this performs the stability analysis during the entire flight. + - **6-launch mode**: this simulation is related to the lauchpad dynamics only, so this is mostly employed to see the effect during the very first moments of the lauch in the neighbourhood of the ramp and on the ramp. This mode is limited to pins attached and detached only. The pins on the ramp are the one which determine the state of Flight Liftoff in the State Machine (this is something related only to post-process stuff). + + +- *Flags for Features*. Enable or disable certain features: + + - **Parafoil** (sensitivity.parafoil): Enable or disable the parafoil simulation. + - **Parallel Threads** (sensitivity.parThreads): Enable or disable parallel processing for faster simulations. + +- *Visualization Options*. Control the plotting behavior: + + - **Enable/Disable Plots** (sensitivity.plots.enabled): Turn plotting on or off. + - **Geographic Plots** (sensitivity.plots.geoPlots): Enable or disable geographic plotting. + - **Confidence Intervals** (sensitivity.plots.confidence): Set the desired confidence levels for the plots. + + +### Uncartanty parameter +This section is dedicated to the stochastic parameters to vary. The parameters which are commented in this sections mean that they wont contribute to the stochastic simulation, thus they will remain constant. If, for example, you want to see by means of stochastic simulation, how effective is the thrust uncartanty ypu can set you parameter as shown below: + +`p = createParameter("thrust", 4, 1, -0.1, 0.1, p);` + +The createParameter function is used to define uncertainty in simulation parameters by specifying the type of uncertainty, the distribution, and the range of variability. Here's a breakdown of how it works: + +```matlab +function parameters = createParameter(name, distr, type, A, B, parameters) +arguments + name {mustBeMember(name, { ... + 'CA','CYB','CY0','CNA','CN0','Cl','Clp', ... + 'Cma','Cm0','Cmad','Cmq','Cnb','Cn0','Cnr','Cnp', ... + 'omega','phi','rocketStructMass','motorStructMass','thrust', ... + 'Ixx','Iyy','Izz', ... + 'drogueSurface','drogueMass','drogueCl','drogueCd', ... + 'mainSurface','mainMass','mainCl','mainCd', ... + 'rocketDiameter','rocketLCenter','centerOfMass', ... + 'finsRootChord','finsFreeChord','finsHeight','finsSemiThickness', ... + 'noseLength','nosePMod','noseCMod'})} + + distr {mustBeMember(distr, [1, 2, 3, 4, 5, 6])} + type {mustBeMember(type, [1, 2])} + A {mustBeReal} + B {mustBeReal} + parameters struct = [] +end +``` + +Here's a brakedown of how it works: + +1. **name** (string):The name of the parameter. + +2. **distr** (integer):This defines the type of uncertainty distribution: + + - **1**: Uniform distribution (with A and B representing the min and max values $A < x < B$). + - **2**: Uniform distribution with a percentage range relative to the nominal value $v_0$ ($A*v_0 < x < B*v_0$). + - **3**: Uniform distribution with a delta range ($A + v_0 < x < B + v_0$). + - **4**: Uniform distribution with a delta percentage range ($(1+A)*v_0 < x < (1+B)*v_0$). + - **5**: Gaussian distribution ($\mu$ = A, standard deviation = B, x = randn). + - **6**: Gaussian distribution with percentage mean relative to the nominal value $v_0$ ($\mu$ = A, standard deviation = B, $x = (1+randn)*v_0$). + + +3. **type** (integer): Defines how the uncertainty is applied (meaningfull only if the uncertanty is applied to and array like the Thrust or the CA): + + - **1**: The same uncertainty value is applied to all elements. + - **2**: Uncertainty is computed independently for each element. + +4. **A and B** (real numbers):These are parameters that define the range or statistical properties of the uncertainty distribution. For instance, A might be the lower bound of a range, and B could be the upper bound or standard deviation. + +5. **parameters** (struct):This is the existing array of parameters. New parameters are added to this array. + + +## 2. Stochastic Simulation + +The `mainSensitivity.m` file defines the execution process for the simulation. A stochastic simulation involves analyzing system behavior under uncertainty by varying the parameters defined in the configuration. + +### Stochastic function + **Execution of Simulations**: + The key function is `sensitivityStochRun`, which performs a stochastic run considering some uncertanty parameters. This function supports 4 different types of simulations according with the chosen simulation. + + ```matlab + function [ascent, descentPara, descentBall, stability] = ... + sensitivityStochRun(rocketRef, envRef, wind, parameters, settings, wrapper) + arguments + rocketRef Rocket + envRef Environment + wind WindCustom {mustBeA(wind, {'WindCustom', 'WindMatlab'})} + parameters struct + settings Settings + wrapper DataWrapper + end + ``` + +### Stochastic simulations summary + The core of this function relies on stochastic simulation. If you're not familiar with this type of simulation and statistical concepts, here’s a brief explanation: + + A **stochastic simulation** models a system where variables can change randomly, each with its own probability distribution. Essentially, it involves running repeated random experiments to estimate an outcome. The accuracy of the results improves as the number of iterations increases, so it’s important to select an appropriate number of iterations to achieve meaningful results. + + In this case, the simulations performed are **Monte Carlo simulations**, which rely on randomness to derive a deterministic solution. For instance, flight dynamics inherently involve stochasticity because they depend on unpredictable factors like wind. While wind may follow certain statistical distributions, it remains a fundamentally random atmospheric variable. + + To clarify, stochastic simulation involves randomness inherent to the system itself, aiming to study or predict its behavior. In contrast, Monte Carlo simulation introduces randomness intentionally to solve a deterministic problem. Both approaches use randomness but differ in their application and purpose. + + #### Determining the Surface Area of a Lake + + <img src="https://upload.wikimedia.org/wikipedia/commons/thumb/3/3b/Montecarlo.svg/1920px-Montecarlo.svg.png" alt="Monte Carlo Method" width="500"/> + + This is a classic example of the Monte Carlo method. Suppose we have a rectangular or square area with known side lengths. Inside this area, there is a lake with an unknown surface area. Knowing the total area of the rectangle, we can estimate the lake's area by performing a random experiment. + + We imagine firing **X** cannonballs randomly over the area. After counting how many cannonballs, **N**, land on solid ground, the number of cannonballs that fall into the lake is **X - N**. From this, we can calculate the surface area of the lake using the formula: + + $$ + \text{lake\_surface} = \text{land\_surface} \cdot \frac{X - N}{X} + $$ + + **Example**: If the total land surface is **1000 m²**, **500 cannonballs** are fired, and **100 cannonballs** land in the lake, the lake's surface area is calculated as follows: + + $$ + \text{lake\_surface} = 1000 \cdot \frac{500 - 100}{500} = 200 \, \text{m²}. + $$ + +### Output +The output of this function are `ascent, descentPara, descentBall, stability` which consists of raw data and they need to be analyzed and umpacked by the post process functions. After the post process all data are input to the plots functions. + +## 3. Interpreting the Plots +In this section an example of execution will be provided to get familiar with the type of the ouput you would get. + +The system generates plots to represent the impact of parameter variations: +- **Sensitivity Plot**: shows the effect of each parameter on the final result. In particular, the plot you'd get is a map of the launch site in which all the elements of the simulations are shown together with 2 ellipses. The ellipses indicate the level of confidence of the simulations, which can be 65% or 90%. The more the elements fall back into the 90%-ellipse we are "more confident" that the variation of data, due to randomness, is limited. +- **Distributions**: histograms or density curves are used to compare simulated data. In more detail, you'd get histograms in which the distribution of probability of a certain altitude for apogee, for example, is depicted. diff --git a/simulator/README.md b/simulator/README.md index 13d7ce95b28fa555ff988fa653582b0911998653..ab48bdc0da8a695c80ccd5afdaac1d4027db7b14 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: diff --git a/stabilityAnalysis/README.md b/stabilityAnalysis/README.md index 4c481ec96d3d91ce0a469e9ecdeea0865ed9b5af..7edb4f2b54e292f7378a2ea209e678efa798f33e 100644 --- a/stabilityAnalysis/README.md +++ b/stabilityAnalysis/README.md @@ -1,31 +1,88 @@ -# stabilityAnalysis +# Rocket Launch Stability Tool -This program allows to evaluate the rocket static stability at launchpad exit in various atmospheric conditions. -In particular the stability margin is computed using different models: +## What Does This Tool Do? -* Classical longitudinal: `XCPlon` -* Classical lateral: `XCPlat` -* Longitudinal in the alpha total plane: `XCPlonATOT` -* Directional in the alpha total plan: `XCPlatATOT` -* With total normal moment and total normal force: `XCPtotSTD` -* With total normal moment and normal force perpendicular to the moment: `XCPtotMOD` -* With Open Rocket: `XCPor` -Different quality indices are also computed: -* Angle between aerodynamic force and aerodynamic moment -* Angle between normal aerodynamic force and normal aerodynamic moment -* Angle between normal aerodynamic force and normal wind velocity -* Error index T -* Magnitude of normal force parallel to the normal moment +This tool is designed to analyze the stability of a rocket during launch, specifically at launchpad exit. It evaluates the rocket's stability margin under various wind conditions (magnitude and azimuth) to ensure safe launch. -# Usage +--- -The analysis type and its features can be set in the script `configSensitivity.m`. -It is possibile to set a range of wind magnidute values and a range of wind azimuth values through the variables `vars.windMag` and `vars.windAz` while the launchpad setup is considered fixed. It is possible to select which quanitites to plot through the set of variables in the section `PLOT SETTINGS`. -The program computes the stability according to the different models, the aerodiynamic coefficients and the quality index in each point of the mesh defined in terms of magnitude and azimuth of the external wind. -It is possible to save the launchpad exit velocity for further analysis enabling the flag `vars.saveRes`. +## How to use it -# Output -If the mesh contains a single value of wind magnitude (or azimuth) the output consists in 2D plots of the stability, quality indices and coefficients along the different value selected, also a data printing in the command window will be present. If instead a full 2D mesh is submitted, the data printing and coefficients plot will be suppressed while stability results and quality indices are shown in 3D plots. -In any case, all data are saved in the struct `data_stability`. +1. **Configure the Settings:** The script `stabilityAnalysisConfig.m` is where you tell the tool what to analyze. You can set things like: + * **Wind Scenarios:** Choose the wind speeds and directions you want to test. + * **Output Preferences:** Decide if you want charts, text summaries, or to save the detailed results. +2. **Run Script** Run the script `mainStabilityAnalysis`. This starts the whole stability analysis process. +3. **Check Out the Results:** Once it's done running, you'll get: + * **Charts:** The tool makes graphs (using `stabilityPlots.m`) that show you the stability margin, cool "quality scores," and aerodynamic stuff. + * **Text Summary:** The function `stabilityPrints.m` prints the cases used to evaluate the stability margins. + * **Save Data (Optional):** If you set it up in the settings, you can load a file called `stabilityRes.mat` to get all the raw data for even more detailed analysis later. + +--- + +## Key Files + +* **`mainStabilityAnalysis.m`:** It's the script you run to start everything. It: + * Gets all the settings and data ready (rocket info, wind). + * Does a quick simulation of the launch to see the rocket dynamics as it leaves the pad. + * Run `computeStability.m` a function that computes the launchpad stability data. + * Makes the charts, prints the text, and saves the results based on your settings. + +* **`stabilityAnalysisConfig.m`:** It's where you set up everything for the stability analysis. Key things to set here are: + * **Wind:** Tell it what wind directions (`stability.windAz`) and speeds (`stability.windMag`) to test. + * **Output Choices:** Pick if you want charts (`stability.plots`), text summaries (`stability.prints`), and if you want to save the data (`stability.saveRes`). + * **Chart Options:** Customize which charts to make (like `stability.plotXCPlonATOT`, `stability.plotQINDEX`, `stability.plotCoeffs`). + * **`dissileMatcom` Settings:** Customize `dissile matcom` datas like (mach, alpha, beta, ecc...) + + **Example Settings Inside `stabilityAnalysisConfig.m`:** + ```matlab + %% WINDY DAY SETUP + stability.windAz = (0:45:315)*pi/180; // Test winds from all directions, every 45 degrees + stability.windMag = [5, 10, 15]; // Test wind speeds of 5, 10, and 15 meters per second + + %% OUTPUT CHOICES + stability.plots = true; // Yes, make charts + stability.prints = true; // Yes, give me text summaries + stability.saveRes = true; // Yes, save the data + + %% CHART PREFERENCES + stability.plotXCPlonATOT = true; + stability.plotQINDEX = true; + stability.plotCoeffs = false; // Skip the coefficient charts + +* **`computeStability.m`:** The brains of the operation for stability calculations. It: + * Runs through all the wind conditions you set up. + * Gets aerodynamic info from `dissileMatcom`. + * Figures out the stability margin and those "quality scores" using `getXCP.m`. + * Packs all the results into a neat package called `data_stability`. + +* **`getXCP.m`:** This is the helper that calculates the important stability numbers: + * **Stability Margin (XCP):** Longitudinal, Lateral, and Total stability margins – different ways to measure stability. + * **Quality Scores (Indices):** Numbers that tell you how "good" the aerodynamic stability is, like angles between forces and moments. + +* **`stabilityPlots.m`:** It is the chart maker. It takes the results and creates visual plots of: + * Stability Margin (SM) vs. Wind conditions + * Quality Scores vs. Wind conditions + * Aerodynamic Coefficients vs. Wind conditions + * You control which charts to make in `stabilityAnalysisConfig.m`. + +* **`stabilityPrints.m`:** The text report generator. It takes the results and creates a text summary for each wind scenario, showing: + * Flight conditions (speed, angles) + * Stability Margin values + * Quality scores + * And how long the calculations took +--- + +## Legend: +* CA Axial force coefficient +* CY Lateral force coefficient +* CN Normal force coefficient +* Cl Rolling moment coefficient +* Cm Pitching moment coefficient +* Cn Yawing moment coefficient +* SM Static Margin of stability +* α Angle of attack +* β Sideslip angle +* αtot Total angle of attack +* ϕ Aerodynamic Roll angle \ No newline at end of file diff --git a/unitTests/README.md b/unitTests/README.md index dba971d1eac85d25f8ed70dcd04493b70cfb9aa6..00affb9ec389a635d11fd43d501d35c95ca7871b 100644 --- a/unitTests/README.md +++ b/unitTests/README.md @@ -82,8 +82,7 @@ The `saveTests.m` script allows users to generate and save test reference data. #### 💾 **Step 2: Save Test Data**: - Run the `saveTests.m` script: - - > [!NOTE] - For **`TestSimulator`**, define a verifiable string and execute the saving routine as shown in the following example: + - For **`TestSimulator`**, define a verifiable string and execute the saving routine as shown in the following example: ```MATLAB if opt.createTestSimulator verifiable = 'HRE'; @@ -91,8 +90,7 @@ The `saveTests.m` script allows users to generate and save test reference data. end ``` - - > [!NOTE] - For **`TestCommonFunctions`**, configure key parameters as shown in the following example: + - For **`TestCommonFunctions`**, configure key parameters as shown in the following example: ```matlab if opt.createTestCommonFunction