From 769a89f2ff981b3ded8cef4e2dfbede2793b3908 Mon Sep 17 00:00:00 2001
From: giuliaghirardini <giuliaghirardini2001@gmail.com>
Date: Tue, 26 Nov 2024 10:56:04 +0100
Subject: [PATCH] [documentation][sensitivity] Sensitivity documentation, first
update
---
sensitivityAnalysis/README.md | 233 ++++++++++++++++++++++++----------
1 file changed, 163 insertions(+), 70 deletions(-)
diff --git a/sensitivityAnalysis/README.md b/sensitivityAnalysis/README.md
index c67d9972..eb336b0e 100644
--- a/sensitivityAnalysis/README.md
+++ b/sensitivityAnalysis/README.md
@@ -1,71 +1,164 @@
-# 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.
+
+### Workflow
+- **Execution of Simulations**:
+ The key function is `sensitivityStochRun`, which generates random samples based on the parameters and uses them to run simulations.
+
+ ```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
+ ```
+
+### Post-Processing
+Raw data is analyzed and aggregated using functions such as `postprocessAscent` and `postprocessDescent`. These steps yield useful metrics, such as:
+- Maximum altitude
+- Final velocity
+
+### Plots and Visualizations
+Outputs are further processed and visualized using `plots`, providing insights into the system's behavior under varying conditions.
+
+### Key Parameters
+- **Rocket**: Rocket configuration.
+- **Wind**: Wind conditions (constant or stochastic).
+- **Environment**: Environmental settings (e.g., pressure, temperature).
+- **Settings**: Includes all simu
+
+
+## 3. Interpreting the Outputs
+
+The simulation generates various outputs useful for analysis. Here's how to interpret them:
+
+### Data Format
+- **Raw Results**:
+ Each simulation produces a record containing parameter values and the corresponding results (e.g., achieved apogee, flight time).
+
+- **Aggregated Data**:
+ Includes metrics such as the mean, standard deviation, and other statistical indicators.
+
+### Visualizations
+The system generates plots to represent the impact of parameter variations:
+- **Sensitivity Plot**:
+ Shows the effect of each parameter on the final result.
+
+- **Distributions**:
+ Histograms or density curves are used to compare simulated data.
--
GitLab