[WIP] Add documentation

_data/docs_v7.yml

@@ -40,6 +40,7 @@
   - Physical-Definition
   - Markers-and-BC
   - Convective-Schemes
+  - Gradients-Limiters
   - Custom-Output
   - Linear-Solvers-and-Preconditioners
   - Multizone

_docs_v7/Configuration-File.md

@@ -7,7 +7,7 @@ The configuration file is a text file that contains a user's options for a parti
 
 The SU2 configuration file name typically carries a name of the form *filename.cfg*. The file extension .cfg is optional (this is our own convention), and the prefix can be any valid string with no spaces; e.g. config.cfg, su2-config.cfg, and flow_config.cfg are all suitable file names. 
 
-**Note: An example configuration file, called config_template.cfg, can be found in the root SU2/ directory or [here](https://github.com/su2code/SU2/blob/master/config_template.cfg). The developers keep this file up to date with the latest options, and it serves as the first reference for the available options in SU2**
+**Note: An example configuration file, called config_template.cfg, can be found in the root SU2/ directory or [here](https://github.com/su2code/SU2/blob/master/config_template.cfg). It is a very important document because it supplements the documentation in this website. The developers keep this file up to date with the latest options, and it serves as the first reference for the available options in SU2.**
 
 The configuration file consists of only three elements:
 - **Options**. An option in the file has the following syntax: option_name = value, where option_name is the name of the option and value is the desired option value. The value element may be a scalar data type, a list of data types, or a more complicated structure. The "=" sign must come immediately after the option_name element and is not optional. Lists of data types may be formatted for appearance using commas, ()-braces, {}-braces, and []-braces, though this is not required. Semicolons are semantically relevant for several option types and may not be used as convenience delimiters. SU2 will exit with an error if there are options in the config file which do not exist or if there are options with improper formatting. Some example option formats are given below.

_docs_v7/Custom-Output.md

@@ -44,12 +44,15 @@ SU2 can output the solution in several file formats. You can specify what files
 | `RESTART` | Native SU2 binary restart format |
 | `RESTART_ASCII` | ASCII CSV restart format |
 | `CSV` | ASCII CSV restart format (identical to `RESTART_ASCII`) |
-| `PARAVIEW` | Binary Paraview .vtk format |
+| `PARAVIEW` | Binary Paraview XML .vtu format |
+| `PARAVIEW_LEGACY` | Binary Paraview .vtk format |
+| `PARAVIEW_MULTIBLOCK` | Paraview XML Multiblock .vtm format |
 | `PARAVIEW_ASCII` | ASCII Paraview .vtk format |
 | `TECPLOT` | Binary Tecplot .szplt format |
 | `TECPLOT_ASCII` | ASCII Tecplot .dat format |
 | `SURFACE_CSV` | Surface values in CSV format (includes all markers set with `MARKER_PLOTTING`) |
-| `SURFACE_PARAVIEW` | Surface values in binary Paraview .vtk format (includes all markers set with `MARKER_PLOTTING`)|
+| `SURFACE_PARAVIEW` | Surface values in binary Paraview .vtu format (includes all markers set with `MARKER_PLOTTING`)|
+| `SURFACE_PARAVIEW_LEGACY` | Surface values in binary Paraview .vtk format (includes all markers set with `MARKER_PLOTTING`)|
 | `SURFACE_PARAVIEW_ASCII` | Surface values in ASCII Paraview .vtk format (includes all markers set with `MARKER_PLOTTING`)|
 | `SURFACE_TECPLOT` | Surface values in binary Tecplot .szplt format (includes all markers set with `MARKER_PLOTTING`)|
 | `SURFACE_TECPLOT_ASCII` | Surface values in ASCII Tecplot .dat format (includes all markers set with `MARKER_PLOTTING`)|
@@ -75,17 +78,20 @@ For the compressible Navier-Stokes solver (i.e. `SOLVER=NAVIER_STOKES`), a **non
 |  `MOMENTUM-X` | Momentum x-component | `SOLUTION`   |
 |  `MOMENTUM-Y` | Momentum y-component  | `SOLUTION`   |
 |  `MOMENTUM-Z` | Momentum z-component |  `SOLUTION`  |
-|  `ENERGY` | Energy  |  `SOLUTION`  |
+|  `ENERGY` | Density times the specific total energy  |  `SOLUTION`  |
+|  `RMS_` | Root-mean square residual of the solution  |  `RMS_RES`  |
 |  `PRESSURE` | Pressure|  `PRIMITIVE`  |
 |  `TEMPERATURE` | Temperature |  `PRIMITIVE`  |
 |  `MACH` | Mach Number |  `PRIMITIVE`  |
 |  `PRESSURE_COEFF` | Pressure Coefficient  |  `PRIMITIVE`  |
 |  `LAMINAR_VISCOSITY` | Laminar viscosity  |  `PRIMITIVE`  |
-|  `SKIN_FRICTION-X` | Skin friction coefficient x-component |  `PRIMITIVE`  |
-|  `SKIN_FRICTION-Y` | Skin friction coefficient y-component  |  `PRIMITIVE`  |
-|  `SKIN_FRICTION-Z` | Skin friction coefficient z-component |  `PRIMITIVE`  |
+|  `SKIN_FRICTION-X` | Skin friction coefficient x-component in local coordinates |  `PRIMITIVE`  |
+|  `SKIN_FRICTION-Y` | Skin friction coefficient y-component in local coordinates |  `PRIMITIVE`  |
+|  `SKIN_FRICTION-Z` | Skin friction coefficient z-component in local coordinates |  `PRIMITIVE`  |
 |  `HEAT_FLUX` | Heat flux |  `PRIMITIVE`  |
 |  `Y_PLUS` | Y-Plus |  `PRIMITIVE`  |
+| `VORTICITY` | Vorticity | `VORTEX_IDENTIFICATION` |
+| `Q_Criterion` | Q-Criterion | `VORTEX_IDENTIFICATION` |
 
 
 ## Customizing the Screen and History Output ##

_docs_v7/Gradients-Limiters.md

@@ -0,0 +1,39 @@
+---
+title: Gradients and Limiters
+permalink: /docs_v7/Gradients-Limiters/
+---
+
+This page lists the gradient computation methods and the limiter functions in SU2 as well as their associated options, it is not meant as a detailed theory guide but some application guidance is given nonetheless. The options listed here do not apply to the high order DG solver.?
+
+---
+
+
+---
+
+## Gradient Computation ##
+The numerical method for the spatial gradients computation is specified by the `NUM_METHOD_GRAD` field. The list of availabel options is given below.
+`GREEN_GAUSS`: classic gradient reconstruction based on the Green-Gauss theorem.
+`LEAST_SQUARES`: Compute the gradient of a field using unweighted Least- Squares approximation.
+`WEIGHTED_LEAST_SQUARES`: Compute the gradient of a field using inverse-distance-weighted approximation.
+The default option is set to `WEIGHTED_LEAST_SQUARES`.
+
+The spatial gradients method used only for upwind reconstruction is pecified by the `NUM_METHOD_GRAD_RECON` field.
+
+Thin Shear Layer gradient reconstruction is always used for the construction of the Jacobian.
+
+## Limiters ##
+SU2 implements limiter functions to prevent the generation of oscillations when using upwind spatial discretisations. These are specified by the config field `SLOPE_LIMITER_FLOW`. The available options are:
+- `NONE`                 - No limiter
+- `VENKATAKRISHNAN`      - Slope limiter using Venkatakrisnan method.
+- `VENKATAKRISHNAN_WANG` - Slope limiter using Venkatakrisnan method, eps based on solution. EPS is...?
+- `BARTH_JESPERSEN`      - Slope limiter using Barth-Jespersen method.
+- `VAN_ALBADA_EDGE`      - Slope limiter using Van Albada method.
+- `SHARP_EDGES`          - Slope limiter using sharp edges.
+- `WALL_DISTANCE`        - Slope limiter using wall distance.
+The default option is set to `VENKATAKRISHNAN`.
+
+   *  \n DESCRIPTION: Coefficient for the limiter. DEFAULT value 0.5. Larger values decrease the extent of limiting, values approaching zero cause lower-order approximation to the solution. \ingroup Config */
+  addDoubleOption("VENKAT_LIMITER_COEFF", Venkat_LimiterCoeff, 0.05);
+
+
+The option `LIMITER_ITER` specifies the number of iterations afterFreeze the value of the limiter after a number of iterations. DEFAULT value $999999$.

_docs_v7/Markers-and-BC.md

@@ -61,14 +61,16 @@ For all Finite Volume (FVM) solvers, i.e. not the `FEM_*` solvers, its implement
 MARKER_SYM = (Symmetry_Wall1, Symmetry_Wall2, ...)
 ```
 
+The negative Sapalart-Allmaras model implements the same boundary conditions as for the standard/standalone version.
+
 ## Constant Heatflux (no-slip) Wall ##
 
 | Solver | Version | 
 | --- | --- |
 | `NAVIER_STOKES`, `RANS`, `INC_NAVIER_STOKES`, `INC_RANS`, `FEM_NAVIER_STOKES`, `HEAT_EQUATION_FVM` | 7.0.0 |
 
 
-A wall with a prescribed constant heatflux is defined with the `MARKER_HEATFLUX` option. The option format is the marker name followed by the value of the heatflux (in Watts per square meter `[W/m^2],[J/(s*m^2)]`), e.g.
+A viscous wall with a prescribed constant heatflux is defined with the `MARKER_HEATFLUX` option. The option format is the marker name followed by the value of the heatflux (in Watts per square meter `[W/m^2],[J/(s*m^2)]`), e.g.
 ```
 MARKER_HEATFLUX = (Wall1, 1e05, Wall2, 0.0)
 ```
@@ -106,7 +108,7 @@ MARKER_ISOTHERMAL = (Wall1, 300.0, Wall2, 250.0)
 | --- | --- |
 | `EULER`, `NAVIER_STOKES`, `RANS`, `INC_EULER`, `INC_NAVIER_STOKES`, `INC_RANS`, `FEM_EULER`, `FEM_NAVIER_STOKES` | 7.0.0 |
 
-A marker can be defined as a Farfield boundary by addings its name to the `MARKER_FAR` option. No other values are necesseary for that option. The actual values which will be prescribed depend on the solver and other user input settings. More details can be found in the [Physical Definition](/docs_v7/Physical-Definition/) section.
+A marker can be defined as a Farfield boundary by addings its name to the `MARKER_FAR` option. No other values are necesseary for that option. The actual values which will be prescribed depend on the solver and other user input settings. The implementation is based on the Riemann invariants of the Euler system calculated from the user input config file. More details can be found in the [Physical Definition](/docs_v7/Physical-Definition/) section.
 
 ```
 MARKER_FAR= (farfield)
@@ -172,7 +174,7 @@ MARKER_INLET = (inlet1, 300 , 1e6, 1.0, 0.0, 0.0, inlet2, 200, 1e6, 0.0, 1.0, 0.
 
 ## Outlet Boundary Condition ##
 
-Outlet boundary conditions are set using the `MARKER_OUTLET` option.
+Outlet boundary conditions are set using the `MARKER_OUTLET` option. These are prescribed by computing the Riemann invariants.
 
 ### Pressure Outlet (Compressible) ###
 
@@ -222,6 +224,12 @@ MARKER_OUTLET = (outlet, 1e1)
 | --- | --- |
 | `NAVIER_STOKES`, `RANS`, `INC_NAVIER_STOKES`, `INC_RANS`, `FEM_NAVIER_STOKES` | 7.0.0 |
 
+For two given periodic surfaces `periodic marker` and `donor marker` SU2 defines periodicity by 
+```
+MARKER_PERIODIC= ( periodic marker, donor marker, rotation_center_x, rotation_center_y, rotation_center_z, rotation_angle_x-axis, rotation_angle_y-axis, rotation_angle_z-axis, translation_x, translation_y, translation_z, ... )
+```
+The same number of points on both surfaces is assumed. Their orientation is specified by the additional set of parameters. Whereby `rotation_center_` specifies the coordinates of the center of rotation for the specified axis, `rotation_angle_` defines the rotation angle [in radians] between `periodic marker` and `donor marker` about the specified axis and `translation_` specifies the translation in space between `periodic marker` and `donor marker` about the specified axis.
+
 ## Structural Boundary Conditions ##
 
 ### Clamped Boundary ###

_docs_v7/Mesh-File.md

@@ -147,3 +147,13 @@ It is important to note that SU2 will not use any specific boundary conditions t
 ## Third-Party Mesh Software
 
 We are continuously working to integrate SU2 with industry-standard tools. The latest releases of the Pointwise meshing software can both export and import meshes in the native ASCII SU2 format. In addition, a number of other packages support direct output to the SU2 format, such as GMSH and CENTAUR. CGNS files created by a number of other meshing packages have been successfully tested and used, such as those from ICEM CFD, for instance.
+
+## Geometry Nomneclature Inside SU2
+
+The following image illustrates the primary and dual grid components nomenclature used inside the SU2 code.
+
+![SU2 geometry definition](../../docs_files/SU2_geometry_nomenclature.png)
+
+with the dual grid in red and the primary grid in black.
+
+MAKE IT PRETTIER!

_docs_v7/Software-Components.md

@@ -19,11 +19,11 @@ The key C++ and Python tools in the SU2 software suite are briefly described bel
 
 ## C++ Software Modules
 
-- **SU2_CFD (Computational Fluid Dynamics Code)**: Solves direct, adjoint, and linearized problems for the Euler, Navier-Stokes, and Reynolds-Averaged Navier-Stokes (RANS) equation sets, among many others. SU2_CFD can be run serially or in parallel using MPI. It uses a Finite Volume Method (FVM), and an edge-based structure. A Discontinuous-Galerkin Finite Element Method solver is currently being completed and will be available to the public in an upcoming release.  Explicit and implicit time integration methods are available with centered or upwinding spatial integration schemes. The software also has several advanced features to improve robustness and convergence, including residual smoothing, preconditioners, and agglomeration multigrid.
+- **SU2_CFD (Computational Fluid Dynamics Code)**: Solves direct, adjoint (conitnuous?), and linearized problems for the Euler, Navier-Stokes, and Reynolds-Averaged Navier-Stokes (RANS) equation sets, among many others. SU2_CFD can be run serially or in parallel using MPI. It uses a Finite Volume Method (FVM), and an edge-based structure. A Discontinuous-Galerkin Finite Element Method solver is currently being completed and will be available to the public in an upcoming release.  Explicit and implicit time integration methods are available with centered or upwinding spatial integration schemes. The software also has several advanced features to improve robustness and convergence, including residual smoothing, preconditioners, and agglomeration multigrid.
 - **SU2_DOT (Gradient Projection Code)**: Computes the partial derivative of a functional with respect to variations in the aerodynamic surface. SU2_DOT uses the surface sensitivity, the flow solution, and the definition of the geometrical variable to evaluate the derivative of a particular functional (e.g. drag, lift, etc.). This is essentially a large dot product operation between the adjoint sensitivities and geometric sensitivities for the particular design variable parameterization.
 - **SU2_DEF (Mesh Deformation Code)**: Computes the geometrical deformation of an aerodynamic surface and the surrounding volumetric grid. Once the type of deformation is defined, SU2_DEF performs the grid deformation by solving the linear elasticity equations on the volume grid. Three-dimensional geometry parameterization is defined using Free Form Deformation, while two-dimensional problems can be defined by both Free From Deformation or bump functions, such as Hicks-Henne.
-- **SU2_MSH (Mesh Adaptation Code)**: Performs grid adaptation using various techniques based on an analysis of a converged flow solution, adjoint solution, and linearized problem to strategically refine the mesh about key flow features. This module also contains a preprocessor that creates the appropriate structures for periodic boundary conditions.
-- **SU2_SOL (Solution Export Code)**: Generates the volumetric and surface solution files from SU2 restart files.
+- **SU2_MSH (Mesh Adaptation Code)**: Performs grid adaptation using various techniques based on an analysis of a converged flow solution, adjoint solution, and linearized problem to strategically refine the mesh about key flow features. This module also contains a preprocessor that creates the appropriate structures for periodic boundary conditions. THIS DOES NOT LONGER EXIST??
+- **SU2_SOL (Solution Export Code)**: Generates the volumetric and surface solution files from SU2 restart files. HOW TO USE IT??
 - **SU2_GEO (Geometry Definition Code)**: Geometry preprocessing and definition code. In particular, this module performs the calculation of geometric constraints for shape optimization. 
 
 While they are not C++ modules, two other similar directories included in the source distribution should be mentioned. First, the **SU2_IDE** (Integrated Development Environment) directory contains files associated with various IDEs to aid developers (Eclipse, VisualStudio, Wing, Xcode). Second, the **SU2_PY** directory contains all of the files making up the Python framework, and some of these will be highlighted in a section below.
@@ -33,6 +33,7 @@ While they are not C++ modules, two other similar directories included in the so
 SU2 includes integrated support for Algorithmic Differentiation (AD) based on Operator Overloading to compute arbitrary derivatives. One application of this feature is the discrete adjoint solver that is implemented in SU2. In contrast to the continuous adjoint method, special versions of the modules SU2_CFD and SU2_DOT are required to use this solver.
 
 - **SU2_CFD_AD**: Solves the discrete adjoint equations using a consistent linearization of the flow solver with the help of AD. Although it has additionally the same features as SU2_CFD, using it for other solvers will result in a slight slow-down due to the AD overhead.
+- **SU2_CFD_DIRECTDIFF**: Computes the gradients of an objective function by forward mode of AD. Although it has additionally the same features as SU2_CFD, using it for other solvers will result in a slight slow-down due to the AD overhead.
 - **SU2_DOT_AD**: The discrete adjoint formulation does not include the influence of the mesh deformation, therefore this module will compute the required partial derivative of the functional with respect to variations in the computational mesh. Instead of SU2_DOT, SU2_DOT_AD uses the volume sensitivities to evaluate the derivative. Finally, the resulting sensitivities on the aerodynamic surface are projected on to the particular design parameterization.
 
 ## Python Scripts