diff --git a/contents/user-input.tex b/contents/user-input.tex
index c6b0faa8bcc40ed9e3ef92d782f1c70a3c6c7cfe..68422b32fda398f4dda7628e231ef249ff689516 100644
--- a/contents/user-input.tex
+++ b/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.
diff --git a/doc-setup.tex b/doc-setup.tex
index 22a7d6a5cc34f8287b4ce5f6b9996a436d0c8d2b..1219b0707044ff4abbdeda30915cefbc55977dd0 100644
--- a/doc-setup.tex
+++ b/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}
+}
diff --git a/rotare-doc.tex b/rotare-doc.tex
index 98272c315b2816e2df289732faa142c8674c9151..00b3453f76efc419b0569bcf869c543cf40388d2 100644
--- a/rotare-doc.tex
+++ b/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}
diff --git a/style/definitions.sty b/style/definitions.sty
index 7193ed6e21632ccc6f0ed8c091722169ece15041..5fb8dadfc7523596412c7953432bc1997dbd32c1 100644
--- a/style/definitions.sty
+++ b/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}