doc(input): input variables list

contents/user-input.tex

@@ -20,20 +20,370 @@ 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 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/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.
 
 
 \section{Input variables}
+All input parameters are structured as in the following example.
+\describeOption{Option Name}{unit}{\lst{Example values}}{
+  A brief description of the option with further indications regarding the input
+  values if necessary.
+}
 
 
+% ===============================================
+\subsection{General simulation options}
+The structure \lstmat{Sim} contains all general parameters to tailor the
+behavior of the software.
+
+\subsubsection{Sim.Save}
+This structure holds all parameters related to the automated saving of the
+simulation results.
+
+\describeOption{Sim.Save.autosave}{}{\lst{true,false}}{
+  Automatically save the simulation results in a MAT-file. This MAT-file can be
+  re-imported later for post-processing and result analysis.
+}
+
+\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.
+}
+
+\describeOption{Sim.Save.dir}{}{\lst{'results/'}}{
+  Directory  where to store the saved results.
+}
+
+\describeOption{Sim.Save.filename}{}{\lst{'myfile'}}{
+  Filename of the saved results.
+}
+
+\describeOption{Sim.Save.appendInfo}{}{\lst{true,false}}{
+  Automatically append some simulation information to the FilenameBase.
+}
+
+\describeOption{Sim.Save.prependTime}{}{\lst{true,false}}{
+  Automatically prepend a time code (format \lst{YYYYMMDDHHmmSS} at the
+  beginning of the filename.
+}
+
+\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.
+}
+
+\describeOption{Sim.Out.3DhubType}{}{See below}{
+  Type of hub (cone) to display on the 3D graph. See
+  \href{https://en.wikipedia.org/wiki/Nose_cone_design}{Nose cone design
+  (wikipedia)} for representation of the nose cones.\\
+  \textit{The nose cones are only for a more realistic visual representation of
+    the rotor. The type of hub itself has absolutely no impact in the actual
+  computation of the BEMT results.}\par
+
+  \begin{tabular}[c]{lll}
+    \qquad & Values & \lstmat{'none'}, \lstmat{'cylinder'}, \lstmat{'conic'},
+    \lstmat{'blunted_conic'}, \lstmat{'bi-conic'}, \lstmat{'tangent_ogive'}, \\
+    \qquad & & \lstmat{'blunted_tangent_ogive'}, \lstmat{'secant_ogive_regular'},
+    \lstmat{'secant_ogive_bulge'},\\
+    \qquad & & \lstmat{'elliptical'}, \lstmat{'parabolic'},
+    \lstmat{'power_series'}, \lstmat{'lv-haack'}, \lstmat{'vonkarman'}.
+  \end{tabular}
+}
+
+
+\describeOption{Sim.Out.console}{}{\lst{true,false}}{
+  Print the simulation results in the console.
+}
+
+\describeOption{Sim.Out.verbosity}{}{\lst{min,all}}{
+  Verbosity level for the console output.
+}
+
+\subsubsection{Sim.Warn}
+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
+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).
+}
+
+\subsubsection{Sim.Misc}
+Other miscellaneous parameters.
+
+
+\describeOption{Sim.Misc.nonDim}{}{\lst{'US','EU'}}{
+  The non dimensionalization factor used to get the thrust, torque and power
+  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
+}
+
+\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.
+}
+
+
+% ===============================================
+\subsection{Models and solver options}
+The structure \lstmat{Mod} contains the parameters for the solvers and the
+extension and corrections to apply. It also specifies the numerical limits
+(number of iterations, precision, etc.).
+
+\describeOption{Mod.solver}{}{\lst{'leishman', 'prop', 'turbine', 'stahlhut'}}{
+  Type of solver to use. The solvers are described in length in
+  Chapter~\ref{chap:tech:solvers}.
+}
+
+\describeOption{Mod.polars}{}{\lst{'manual', 'polynomial', 'auto'}}{
+  Type of losses to consider.
+}
+
+\describeOption{Mod.polarFile}{}{\lst{'mypolar.mat'}}{
+  File name for the polar.
+}
+
+\describeOption{Mod.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.
+}
+
+
+
+\subsubsection{Mod.Ext}
+Parameters related to the extensions and corrections to apply to the base BEMT.
+
+\describeOption{Mod.Ext.losses}{}{\lst{'none', 'hub', 'tip', 'both'}}{
+  Type of losses to consider.
+}
+
+
+\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
+  results.
+}
+
+\describeOption{Mod.Num.maxIter}{-}{1e}{
+  Maximum iterations allowed when doing iterative processes. If this number is
+  reached, the code will output an error and stop its execution.
+}
+
+
+% ===============================================
+\subsection{Flow}
+The structure \lstmat{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. \\
+  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).
+}
+
+
+% ===============================================
+\subsection{Operating points}
+The structure \lstmat{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.
+
+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.
+}
+
+\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.collective}{deg}{Array ($M \times N_3$)}{
+  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).
+
+\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. 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).
+}
+
+\describeOption{Airfoil.polarsFile}{}{\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}.
+}
+
+\describeOption{Airfoil.clPoly}{deg$^{-1}$}{Vector}{
+  \danger \, \textit{Only used when \lst{Mod.polars='manual'}}.
+
+  Coefficients for the polynomial form of the lift coefficient, $C_l$.\\
+  The vector should be in the form $[p_1, p_2, ..., p_n]$ to represent the
+  polynomial
+  $$ C_l = \sum_{i=1}^n p_i \alpha^{n-i}$$
+  , where $\alpha$ is the angle of attack in degree.
+}
+
+\describeOption{Airfoil.cdPoly}{deg$^{-1}$}{Vector}{
+  \danger \, \textit{Only used when \lst{Mod.polars='manual'}}.
+
+  Same as \lst{Blade.Airfoil.clPoly}, but for the drag coefficient.
+}
+
+
+\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.
+
+\danger \textbf{Most blade dimensions are specified through a vector of at least
+two elements}. The first element always correspond to the blade root, the last
+one is always the blade tip. The blade geometry will then constructed by
+interpolating points at the different segments, using a spline interpolation (it
+is therefore not necessary to add every single blade section in these vectors).
+The vectors can contain as many points as desired in order to refine the mesh or
+better control the overall geometry of the blade.
+
+Note that the vectors must all have the same dimensions as
+\lst{Blade.radius}. Every element of the other variables is being linked to
+the corresponding spanwise position defined in \lst{radius}.
+
+
+\describeOption{Blade.nBlades}{-}{3}{
+  Number of blades on the rotor.
+}
+
+\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.
+  Intermediary points may be added to tweak more precisely the blade geometry.
+}
+
+\describeOption{Blade.chord}{m}{[$c_\text{root}, \dots, c_\text{tip}$]}{
+  Chord of the elements.
+}
+
+\describeOption{Blade.twist}{deg}{
+  [$\theta_\text{root}, \dots, \theta_\text{tip}$]
+}{
+  Twist (or stagger) angle of the elements. Note that if \lst{Mod.collective} is
+  not 0, the actual pitch of the elements will be the sum of the twist and the
+  collective.
+}
+
+\describeOption{Blade.Airfoil}{}{[$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
+
+  Example:
+  \begin{center}
+    \begin{tabular}[c]{lccc}
+      \toprule
+      Section & 1 & 2 & 3 \\
+      \midrule
+      Radius & 0.1 & 0.5 & 1 \\
+      Airfoil & 1 & 2 & 3 \\
+      \bottomrule
+    \end{tabular}
+  \end{center}
+
+  In that case, the \lst{Airfoil(1)} will be applied for all elements between
+  $[0.1; 0.5[$ m, the \lst{Airfoil(2)} will be used for all elements between
+  $[0.5; 1[$ m and the \lst{Airfoil(3)} will be used for the tip.
+}
+
+
+\describeOption{Blade.nElem}{-}{100}{
+  Number of blade elements to use in the Blade Element Method. The elements will
+  be linearly spaced along the span of the blade (defined by the two bounds of
+  \lst{Blade.radius}).
+}
+
+% ===============================================
 \section{Configuration validation}
+\label{sec:user:input:valid}
 
 Before initiating a simulation, the user input file is passed through a
-validation function. This function checks if all inputs are properly defined and
-formatted before starting the simulation. It also fixes small typos in the
-string parameters whenever possible to ensure proper behavior of the software.
+validation function automatically. This function checks if all inputs are
+properly defined and formatted before starting the simulation. It also fixes
+small typos in the string parameters whenever possible to ensure proper behavior
+of the software.
 
 If the validation of a parameter fails, a comprehensive error message will be
 returned. This should help the user to fix their issues easily.

doc-setup.tex

@@ -81,5 +81,30 @@
 %                          ADDITIONAL PACKAGES
 % ==============================================================================
 
+\usepackage{uliege-colors} % ULiege color theme
 \usepackage{scrhack} % So other packages play nice with KOMA-Scripts
 \usepackage{definitions} % Custom definitions (see style/definitions.sty)
+\usepackage[nolinks]{qrcode} % QR codes
+\usepackage{booktabs} % Better looking tables
+\usepackage{amsmath}
+
+\usepackage{menukeys} % Keys, menus, directories, etc
+\renewmenumacro{\directory}{pathswithfolder} % default: paths
+
+% ==============================================================================
+%                               MISC STUFF
+% ==============================================================================
+
+\newcommand{\describeOption}[4]{
+  \par
+  \begin{minipage}[t]{\textwidth}
+    \textbf{#1}
+    \if\relax\detokenize{#2}\relax
+      % nothing
+  \else
+    [#2]
+  \fi
+  \dotfill\, #3\\
+  #4
+\end{minipage}
+}

rotare-doc.tex

@@ -13,7 +13,7 @@
 
 \documentclass[%
 paper=A4,               % paper size
-twoside=true,           % oneside or twoside printing
+twoside=false,           % oneside or twoside printing
 openright,              % chapter headings on right side
 parskip=half,           % spacing value / method for paragraphs
 chapterprefix=true,     % prefix for chapter marks
@@ -65,13 +65,13 @@ draft=false,            % toggle if draft version
 
 \part{User manual}
 \input{contents/user-install}
-\input{contents/user-input}
 \input{contents/user-usage}
+\input{contents/user-input}
 \input{contents/user-troubleshooting}
 
-%\part{Technical documentation}
+\part{Technical documentation}
 %\input{contents/tech-architecture}
-%\input{contents/tech-solvers}
+\input{contents/tech-solvers}
 %\input{contents/tech-extensions}
 %\input{contents/tech-validation}
 %\input{contents/tech-roadmap}

style/definitions.sty

@@ -35,6 +35,11 @@
 \newcommand{\yQ}{\textcolor{myOrange}{\faQuestion}}
 \newcommand{\oV}{\textcolor{myOrange}{\faCheck}}
 
+\newcommand{\danger}{\textcolor{myOrange}{\faExclamationTriangle}\xspace}
+
+\newcommand\lst[1]{\lstinline[basicstyle=\ttfamily\normalsize]{#1}}
+\newcommand\lstmat[1]{\lstinline[language=matlab]{#1}}
+
 % --- Code & software names, ---------------------------------------------------
 \newcommand\rotare{\textsc{Rotare}\xspace}
 \newcommand\matlab{\textsc{Matlab}\xspace}