Skip to content
Snippets Groups Projects
Verified Commit dac56130 authored by Thomas Lambert's avatar Thomas Lambert :helicopter:
Browse files

fix(config): reflect current parameters

parent ac3ef3d3
No related branches found
No related tags found
No related merge requests found
Hide whitespace changes
Inline Side-by-side
contents/user-input.tex
+ 96
− 113
View file @ dac56130
......@@ -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.
}
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment