fix(config): reflect current parameters

contents/user-input.tex

@@ -20,9 +20,10 @@ geometry itself. These five types of input are collected inside five different
 structures for easier handling in the code.
 
 This input file should be a \matlab script (not a function). Examples of
-configuration are given in \directory{src/config/}. In order to always have a
-fully-defined, working configuration available, it is suggested to just copy the
-template and edit your copy instead of directly working in the template.
+configuration are given in \directory{src/configs/}. In order to always have a
+fully-defined and working configuration available, it is suggested to just copy
+the template and edit your copy instead of directly working in the template
+(\rotare will nag you if you are using the template anyway).
 
 
 % ===============================================
@@ -40,22 +41,25 @@ If the validation of a parameter fails, a comprehensive error message will be
 returned. This should help the user fix their issues easily.
 
 The validation function will also return preliminary warnings whenever some
-parameters may lead to potential issues (\eg not enough elements).
+parameters may lead to potential issues (\eg not enough elements to properly
+define the geometry, etc.).
 
 % ===============================================
 \section{Input variables}
-All input parameters are structured as in the following example.
+In this documentation, all input parameters are structured as in the following
+example.
 
-\describeOption{Option Name}{unit}{\lst{Example values}}{
+\describeOption{Option Name}{unit}{\lst{Example or allowed values}}{
   A brief description of the option with further indications regarding the input
   values if necessary.
 }
 
 
 % ===============================================
-\subsection{General simulation options}
+\subsection{General simulation options (Sim)}
 The structure \textsf{Sim} contains all general parameters to tailor the
-behavior of the software.
+behavior of the software. It is itself made of sub-structures, ordered by
+themes.
 
 \subsubsection{Sim.Save}
 This structure holds all parameters related to the automated saving of the
@@ -69,15 +73,16 @@ simulation results.
 \describeOption{Sim.Save.overwrite}{}{\lst{true,false}}{
   Overwrite existing results when saving automatically. Results are only
   overwritten if a file with matching name exist.\\
-  If set to \lst{false}, a number will be added at the end of the filename.
+  If set to \lst{false}, a number will be added at the end of the filename and
+  incremented upon each save.
 }
 
-\describeOption{Sim.Save.dir}{}{\lst{'results/'}}{
-  Directory  where to store the saved results.
+\describeOption{Sim.Save.dir}{}{\lst{'../results/'}}{
+  Directory  where the saved results will be exported.
 }
 
 \describeOption{Sim.Save.filename}{}{\lst{'myfile'}}{
-  Filename of the saved results.
+  Filename to use for the saved results.
 }
 
 \describeOption{Sim.Save.appendInfo}{}{\lst{true,false}}{
@@ -89,17 +94,20 @@ simulation results.
   beginning of the filename.
 }
 
+\describeOption{Sim.Save.timeFormat}{}{\lst{YYYYMMDDHHmmSS}}{
+  Format of the timecode to use when \lst{Sim.Save.prependTime=true}.
+}
+
 \subsubsection{Sim.Out}
 This structure holds all parameters related to the display of the simulation's
 results.
 
-
 \describeOption{Sim.Out.showPlots}{}{\lst{true,false}}{
   Display all plots and graphs at the end of the simulation.
 }
 
 \describeOption{Sim.Out.show3D}{}{\lst{true,false}}{
-  Show the 3D view of the rotor and blade.
+  Show a 3D view of the rotor and one with a single isolated blade.
 }
 
 \describeOption{Sim.Out.hubType}{}{See below}{
@@ -117,7 +125,6 @@ results.
   in the actual computation of the BEMT results.}
 }
 
-
 \describeOption{Sim.Out.console}{}{\lst{true,false}}{
   Print the simulation results in the console.
 }
@@ -131,24 +138,18 @@ Enable or disable specific warnings during the simulations.
 
 Note that only \textit{low severity} warnings can be disabled this way from the
 configuration file. These warnings usually indicate a poor rotor design or a
-poor operating condition for a proper rotor. As this is perfectly expected when
-the full operating map of the rotor is being simulated, these low severity
-warnings can be silenced to avoid cluttering the console.\\
-However, the code can also output more severe warnings. These are typically
+poor operating condition for a proper rotor. As these conditions are to be
+expected when the full operating map of the rotor is being simulated, these low
+severity warnings can be silenced to avoid cluttering the console.\\
+However, the code may also output more severe warnings. These are typically
 related to violated hypotheses and indicate unreliable results. As they are
 considered more serious, it is by purpose that they can not be silenced easily
 through the configuration file. Even though it is \textit{heavily discouraged},
 it is still possible to use \matlab built-in functions to disable these critical
 warnings.
 
-
-\describeOption{Sim.Warn.stall}{}{\lst{true,false}}{
-  Warns the user if some blade sections are stalled.
-}
-
-\describeOption{Sim.Warn.negLift}{}{\lst{true,false}}{
-  Warns the user if some blade sections generate negative lift (negative angle
-  of attack).
+\describeOption{Sim.Warn.sonicTip}{}{\lst{true,false}}{
+  Warns the user if the blade tip is trans/super sonic.
 }
 
 \subsubsection{Sim.Misc}
@@ -160,25 +161,26 @@ Other miscellaneous parameters.
   coefficient is not always the same between the US and the rest of the world.
   While they differ only from a factor 0.5, this can lead to difficulties when
   comparing with existing experimental data.
-
-  \todo{Add notations}
+  
+  \textit{See section~\ref{chap:tech:solvers:coeff} for details about the rotor
+  coefficients.}
 }
 
-\describeOption{Sim.Misc.app}{}{\lst{'prop', 'heli', 'turbine'}}{
-  Specifies the type of application for the rotor studied. This is mostly used
-  to ensure proper sign for the output variables, etc.
-}
+\describeOption{Sim.Misc.appli}{}{\lst{'prop', 'heli', 'turbine'}}{
+  Specifies the type of application for the rotor studied. This impacts the
+  definition of the forces, moments and power coefficients calculated. It is
+  also used to display the 3D view in the appropriate position and to ensure 
+  proper sign for the output variables, etc.
 
-\describeOption{Sim.Misc.pitchRef}{}{\lst{'zerolift','chordline'}}{
-  It is common to define the pitch angle of a blade element with respect to the
-  zero-lift angle of its airfoil instead of the chord line. This parameter
-  ensures the correct reference is taken.
+  \textit{See section~\ref{chap:tech:solvers:coeff} for details about the rotor
+  coefficients.}
 }
 
+
 % ===============================================
-\subsection{Models and solver options}
+\subsection{Models and solver options (Mod)}
 The structure \lstmat{Mod} contains the parameters for the solvers and the
-extension and corrections to apply. It also specifies the numerical limits
+extensions/corrections to apply. It also specifies the numerical limits
 (number of iterations, precision, etc.).
 
 \describeOption{Mod.solvers}{}{\lst{'leishman', 'prop', 'turbine', 'stahlhut',
@@ -189,37 +191,21 @@ extension and corrections to apply. It also specifies the numerical limits
   will then loop for all solvers.}
 }
 
-
-\subsubsection{Mod.Syst}
-Parameters related to multi-rotors systems.
-
-\describeOption{Mod.Syst.nRotors}{}{\lst{1}}{
-  Number of rotors. Currently \rotare is only capable of simulating a single
-  rotor in isolation. A value other than \lst{1} will result in an error. The
-  coaxial implementation is going to be implemented in a few weeks.
-}
-
-\describeOption{Mod.Syst.rotSpacing}{}{Vector}{
-  Spacing between multiple coaxial rotors. This should be specified as a vector
-  (or scalar if there are only two rotors).
-}
-
-
 \subsubsection{Mod.Ext}
 Parameters related to the extensions and corrections to apply to the base BEMT.
+See section~\ref{chap:tech:ext} for details regarding these models.
 
 \describeOption{Mod.Ext.losses}{}{\lst{'none', 'hub', 'tip', 'both'}}{
-  Type of losses to consider.
+  Type of losses to consider (using Prandtl formula).
 }
 
-
 \subsubsection{Mod.Num}
 Numerical limits for the simulations.
 
 \describeOption{Mod.Num.convCrit}{-}{1e-4}{
-  Value for the convergence criterion to use when doing iterative process. Note
-  that this criterion will be used to assess the \emph{relative} error between
-  two iterations. A precision of 0.01\% is often low enough to get valid
+  Value for the convergence criterion to use when doing iterative processes.
+  Note that this criterion will be used to assess the \emph{relative} error
+  between two iterations. A precision of 0.01\% is often low enough to get valid
   results.
 }
 
@@ -228,14 +214,12 @@ Numerical limits for the simulations.
   reached, the code will output an error and stop its execution.
 }
 
-\describeOption{Mod.Num.azimStep}{deg}{1}{
-  Azimuthal step to use when simulating oblique flows. See
-  Chapter\fxnote{Chapter ref} for
-  details regarding oblique flow implementation.
-
-  \textit{The BEMT equations needs to be resolved for each azimuthal position of
-  the blade. Using a very small step will lead to longer computational time.}
-  }
+\describeOption{Mod.Num.relax}{-}{0.1}{
+  Relaxation factor to use in order to ease the convergence of iterative
+  processes. A low number would increase chance of success of the convergence
+  process at the cost of a slower converge. A higher number (up to 1) will
+  proceed faster, but the solution may diverge.
+}
 
 % ===============================================
 \subsection{Flow}
@@ -243,74 +227,54 @@ The structure \lst{Flow} contains the parameters related to the flow itself.
 
 \describeOption{Flow.fluid}{}{\lst{'air', 'seawater', 'freshwater'}}{
   Nature of the fluid. This is used to determine the density and viscosity of
-  the fluid. \\
+  the fluid.\\
   Note that if the fluid is air, the altitude (see \lst{Op.alt}) is also used in
   order to determine the proper density and viscosity (using ISA tables).
 }
 
-\describeOption{Flow.angle}{deg}{\lst{20}}{
-  Angle of the flow with respect to the direction perpendicular to the rotor
-  plane (\ie, 0$^\circ$ for axial flows).
-
-  \todo{Ref to schematics}
-}
-
 % ===============================================
 \subsection{Operating points}
-The structure \lstmat{Op} determines the various operating points of the
+The structure \lst{Op} determines the various operating points of the
 rotor(s). These four variables can be specified as vectors in order to study a
 given rotor geometry over multiple operation points (thus creating a whole
 operating map of the rotor). Obviously, it is also possible to simply specify
-scalars. That would lead to the analysis of the rotor at one single point.
+scalars. In that case, \rotare will analyze of the rotor at one single point.
 
 Note that \rotare will loop over \textit{every combination} of these four
 operating points. Therefore, the total number of simulations can become very
-large should you decide to study lots of these points.
-
-\describeOption{Op.alt}{m}{Vector ($1 \times N_1$)}{
-  The rotor altitude (\eg flight altitude, wind turbine altitude).\\
-  This is only used to get a better estimation of the air density. If
-  \lstmat{Flow.fluid} is not air, this is not used.
-}
+large should you decide to study lots of these points. 
 
 \describeOption{Op.speed}{m/s}{Vector ($1 \times N_2$)}{
   Axial velocity of the fluid.
 }
 
-\describeOption{Op.rpm}{rpm}{Array ($M \times N_4$)}{
-  The rotor angular velocity in RPM.\\
-  In the case of simulations with multiple rotors (coaxial), each line of the
-  array correspond to a rotor. This allows specifying different rotation speed
-  couples for the first and second rotor. In that case, the first operating
-  point corresponds to the first column, the second to the second column and so
-  on. This does not test all combinations between first and second lines.\\
-  If the simulation is for one single rotor, then only the first line is used
-  and a warning is issued during the validation of the input (see
-  Section~\ref{sec:user:input:valid}).
+\describeOption{Op.altitude}{m}{Vector ($1 \times N$)}{
+  The rotor altitude (\eg flight altitude, wind turbine elevation).\\
+  This is only used to get a better estimation of the air density. If
+  \lstmat{Flow.fluid} is not air, this is not used.
 }
 
+\describeOption{Op.rpm}{rpm}{Vector ($1 \times N$)}{
+  The rotor angular velocity in RPM.\\
+}
 
-\describeOption{Op.collective}{deg}{Array ($M \times N_3$)}{
+\describeOption{Op.collective}{deg}{Vector ($1 \times N$)}{
   The collective pitch setting for the rotor. If the rotor has no collective
   pitch setting (\eg drone propeller), it is advised to let this option at 0 and
   only specify the twist of the rotor in the \lst{Blade} structure.
-
-  As for \lst{Op.rpm} this can be specified as an array if there are multiple
-  rotors. In that case, each line corresponds to a different rotor.
 }
 
 
-
 % ===============================================
 \subsection{Airfoil}
 Data regarding the various airfoils that will be used along the blade. Note that
 multiple airfoils can be specified. In that case, just use multi-dimension
-structures (\ie, \lst{Airfoil(1)}, \lst{Airfoil(2)}, \dots).
+structures (\ie \lst{Airfoil(1)}, \lst{Airfoil(2)}, \dots).
 
 \describeOption{Airfoil.coordFile}{}{\lst{'airfoil\_data/naca0012.dat'}}{
-  Name of the file with the airfoil data. At the moment, this file is only used
-  to draw the 3D view of the rotor, but it is still a mandatory input. The best
-  source for such data files is to directly get the
+  Name of the file with the airfoil coordinates points. At the moment, this file
+  is only used to draw the 3D view of the rotor, but it is still a mandatory
+  input. The best source for such data files is to directly get the
   \href{https://m-selig.ae.illinois.edu/ads/coord_database.html}{UIUC Airfoil
   Coordinates Database}. The data can be formatted either following Selig or
   Ledneicer convention (the two types of format found on UIUC Database).
@@ -323,17 +287,25 @@ structures (\ie, \lst{Airfoil(1)}, \lst{Airfoil(2)}, \dots).
       \rotare.
     \item \textbf{polynomial}: The $C_l$ and $C_d$ are given as polynomial
       expressions of $\alpha$.
-    \item \textbf{auto}: \rotare retreives the polars automatically using XFOIL.
-
   \end{itemize}
 }
 
-\describeOption{Airfoil.polarsFile}{}{\lst{'airfoil\_data/naca0012-polar.mat'}}{
+\describeOption{Airfoil.polarFile}{}{\lst{'airfoil\_data/naca0012-polar.mat'}}{
   Name of the files with the airfoil polars. This file should contain a Matlab
   structure called \lst{Polar}. Such file can be obtained by generating the
   airfoil polars with XFOIL or XFLR5 and then exporting them with the
   \lst{xf2mat} utility that can be found in the free and open-source
   \href{https://gitlab.uliege.be/am-dept/matlab_airfoil_toolbox}{matlab\_airfoil\_toolbox}.
+  Note that this toolbox is a required library for \rotare and should already be
+  present and usable in your installation.
+}
+
+\describeOption{Airfoil.extrap}{}{\lst{true, false}}{
+  Extrapolate the polars from \lst{Airfoil.polarFile} over the complete range of
+  angles of attack ([-180, 180] deg). Although this extrapolation is not ideal,
+  it allows for the computation of sections that are at very large/low angles of
+  attack. This is particularity useful when doing a sweep of operating
+  conditions.
 }
 
 \describeOption{Airfoil.clPoly}{deg$^{-1}$}{Vector}{
@@ -354,11 +326,11 @@ structures (\ie, \lst{Airfoil(1)}, \lst{Airfoil(2)}, \dots).
 
 
 \subsection{Blade}
-The structure \lst{Blade} contains all the parameters related to the rotor and
-blade geometry. If there are multiple rotors (\ie, currently only for coaxial
-case), you must specify these parameters for both rotors. If the two rotors are
-the same, a simple way to do that consists in adding \lst{Blade(2) = Blade}
-after the definition of the first rotor.
+The structure \lst{Blade} contains the parameters related to the rotor and blade
+geometry. If there are multiple rotors (\ie, currently only for coaxial case),
+you must specify these parameters for both rotors. If the two rotors are the
+same, a simple way to do that consists in adding \lst{Blade(2) = Blade} after
+the definition of the first rotor.
 
 \danger \textbf{The blade dimensions are specified through a vector of at least
 two elements}. The first element always correspond to the blade root, the last
@@ -376,6 +348,12 @@ stations defined in \lst{Blade.radius}.
   Number of blades on the rotor.
 }
 
+\describeOption{Blade.pitchRef}{}{\lst{'zerolift','chordline'}}{
+  It is common to define the pitch angle of a blade element with respect to the
+  zero-lift angle of its airfoil instead of the chord line. This parameter
+  ensures the correct reference is taken.
+}
+
 \describeOption{Blade.radius}{m}{[$r_\text{root}, \dots, r_\text{tip}$]}{
   Radial position of the elements. The first element corresponds to the root of
   the blade (include the cutout) and the last one corresponds to the blade tip.
@@ -394,7 +372,7 @@ stations defined in \lst{Blade.radius}.
   collective.
 }
 
-\describeOption{Blade.Airfoil}{}{[$i_\text{root}, \dots, i_\text{tip}$]}{
+\describeOption{Blade.iAirfoil}{}{[$i_\text{root}, \dots, i_\text{tip}$]}{
   Index of the \lst{Airfoil(i)} to use for each element. As there is no simple
   way to interpolate between different airfoils, the same airfoil will be
   applied on all sections until a new airfoil is specified.\par
@@ -421,3 +399,8 @@ stations defined in \lst{Blade.radius}.
   be linearly spaced along the span of the blade (defined by the two bounds of
   \lst{Blade.radius}).
 }
+
+\describeOption{Blade.hubPos}{m}{[0, 0, 0]}{
+  Coordinates of the rotor center point. This parameter is important for
+  multi-rotor systems. For single rotors, it is discarded.
+}