diff --git a/_config.yml b/_config.yml index 95970070..c23ff586 100644 --- a/_config.yml +++ b/_config.yml @@ -50,14 +50,14 @@ defaults: seo: type: "WebPage" -- scope: - path: _docs - type: docs - values: - layout: docs - sectionid: docs - seo: - type: "WebPage" +# - scope: +# path: _docs +# type: docs +# values: +# layout: docs +# sectionid: docs +# seo: +# type: "WebPage" - scope: path: _tutorials diff --git a/_docs/AD-Build.md b/_docs/AD-Build.md deleted file mode 100644 index cda949fe..00000000 --- a/_docs/AD-Build.md +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: AD Build -permalink: /docs/AD-Build/ ---- - -It is recommended to read the information at [Build from Source](/docs/Build-from-Source/) first prior reading this section. - -The following requires a compiler which supports most of the C++11 features, i.e. GCC >= v4.7, Clang >= v3.0 or Intel C++ >= v12.0. - -In order to use the discrete adjoint solver the compilation requires two additional (header-only) libraries. [CoDi](https://github.com/SciCompKL/CoDiPack) provides the AD datatype and [MeDi](https://github.com/SciCompKL/MeDiPack) provides the infrastructure for the MPI communication when the reverse mode of AD is used. Both libraries are added as submodules in `externals/` in the git repository of SU2. - -## Configuration with AD support -The initialization of these libraries as well as the configuration of SU2 is handled by the python script `preconfigure.py` inside the main directory. This script accepts the **same arguments** as the usual configure script (except `CXXFLAGS=...`) but in addition it offers the option `--enable-autodiff` to enable AD (reverse mode) for the discrete adjoint solver. - -### Example -Assume that your configuration (see [Simple Build](/docs/Simple-Build/) or [Parallel Build](/docs/Parallel-Build/)) is done using the command: - - ./configure --enable-mpi --prefix=$SU2_INSTALLPATH CXXFLAGS="-O3 -Wall" - -To enable the compilation of the binaries with AD support, you'll need to change this command to: - - export CXXFLAGS="-O3 -Wall" && ./preconfigure.py --enable-autodiff --enable-mpi --prefix=$SU2_INSTALLPATH - -**Note:** If you have already called `./configure` before in the source directory, a `make distclean` is required before calling `./preconfigure.py`. - -This script creates the folders `SU2_BASE` and `SU2_AD` and calls configure in each of the folders. `SU2_BASE` then contains the configuration to compile all of the base modules (`SU2_CFD`, `SU2_DOT`, `SU2_SOL` etc.) and `SU2_AD` contains the configuration to compile the modules `SU2_CFD_AD` and `SU2_DOT_AD`. Furthermore, it creates a Makefile so that you can simply call `make install` in the main folder to compile and install everything into the specified directory or `make install SU2_BASE` or `make install SU2_AD` to compile and install them separately. diff --git a/_docs/Advanced-AD-Techniques.md b/_docs/Advanced-AD-Techniques.md deleted file mode 100644 index 3b9c6e61..00000000 --- a/_docs/Advanced-AD-Techniques.md +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: Advanced AD Techniques -permalink: /docs/Advanced-AD-Techniques/ ---- - -[Algorithmic Differentiation](https://en.wikipedia.org/wiki/Automatic_differentiation) (AD) is a frequently used method to calculate -the derivative of a function by means of the transformation of the underlying program which calculates the -numerical values of this function. As distinguished from symbolic differentiation an explicit expression for the -derivative is never formed. An advantage over FD is that no truncation errors are present, thus the numerical -value can be determined up to machine accuracy. - -Consider a function `y = f(x)`, using the reverse mode of AD we get - -`xb = (df/dx)^T yb` - -with an arbitrary seed vector `yb`. - - -### Expression Templates - -In SU2 we use the AD tool [CoDi](https://github.com/SciCompKL/CoDiPack) to enable the computation of arbitrary derivatives. It is based on the [Expression Template](https://en.wikipedia.org/wiki/Expression_templates) approach. Here the overloaded operators no longer return the (computationally expensive) result of an expression, -but a small temporary object that acts as a placeholder for this particular expression. Using this objects -we can build an internal representation of each expression to directly compute and store its partial derivatives during the evaluation of the program. This information is then used to correctly accumulate the gradients (or rather `xb`) in a second reverse sweep. - -The picture below shows the computational graph for the expression `φ=cos(v1)v2` and the compile-time representation as object with `su2double` being the general datatype used throughout SU2. -![Expression Templates](http://www.scicomp.uni-kl.de/wordpress/wp-content/uploads/2016/05/Screenshot-from-2016-05-20-15-49-59.png) - -This object can be traversed to compute and store the partial derivatives `∂φ/∂v1=-sin(v1)v2` and `∂φ/∂v2=cos(v1)` based on the derivatives of each involved unary or binary operation. If recording is enabled the traversal of the computational graph of each -expression is started as soon as it occurs on the right-hand side in a statement. Note that the partial derivatives are only stored if the corresponding argument has some dependency on the input variables set by the user. This kind of dependency or -activity tracking is relatively easy to accomplish since every variable stores an index along with its value. A -zero index represents passive variables while a non-zero index identifies active variables. This index will be -non-zero only if the corresponding variable has been assigned an expression with at least one active variable -as an argument. - -### AD Tool Wrapper - -The CoDi library provides a special datatype and is automatically included -during the compilation if AD support is requested by the user (see the build instructions for further information). For developers of SU2 there is no need to deal -with this library explicitly which is why there are simple wrapper routines for the most important features -available. These are for example the following: - -* `AD::RegisterInput(su2double &var)`: Registers the variable as input, i.e. sets the index to a -non-zero value. The exact value is determined by the AD tool. -* `AD::StartRecording()`: Starts the recording by enabling the traversal of the computational graphs -of each subsequent expression to store the partial derivatives. -* `AD::StopRecording()`: Stops the recording of information. -* `AD::ComputeAdjoint()`: Interprets the stored information to compute the gradient. -* `AD::Reset()`: Deletes all stored information, i.e. the adjoint values and the partial derivatives to -enable a new recording. -* `AD::ClearAdjoints()`: Sets the adjoint values to zero but keeps the derivative information, thereby -enabling a new interpretation with a different seed vector `yb`. - -Since the actual interpretation of the adjoints is done by the AD tool, we need some functions to set and -extract the derivative information. To account for other datatypes (like for example types that implement -the forward mode of AD or types for the complex step method) these functions are enclosed in the namespace -`SU2_TYPE`: -* `SU2_TYPE::SetDerivative(su2double &var, double &val)`: Sets the adjoint value of a variable -before calling `AD::ComputeAdjoint()`. -* `SU2_TYPE::GetDerivative(su2double &var)`: Returns the interpreted adjoint value of a variable -registered as input. Note: at the moment this function must be called in the same order as `AD::RegisterInput(su2double &var)`. - -### Local Preaccumulation - -To alleviate the high memory requirements we apply the so called local preaccumulation method. Here we -compute and store the local Jacobi matrices of certain enclosed code parts instead of storing each individual -statement contribution. To illustrate the method consider the code shown in the listing below which computes the -volume of 2D elements of the mesh. Without using preaccumulation and if we assume that nDim equals 2 we -have to store 12 partial derivative values for the 3 statements (2 ∗ 2 in line 7, 2 ∗ 2 in line 8 and 4 in line 11). - -``` - AD::StartPreacc(); - AD::SetPreaccIn(val_coord_Edge_CG, nDim); - AD::SetPreaccIn(val_coord_Elem_CG, nDim); - AD::SetPreaccIn(val_coord_Point, nDim); - - for (iDim = 0; iDim < nDim; iDim++) { - vec_a[iDim] = val_coord_Elem_CG[iDim]-val_coord_Point[iDim]; - vec_b[iDim] = val_coord_Edge_CG[iDim]-val_coord_Point[iDim]; - } - - Local_Volume = 0.5*fabs(vec_a[0]*vec_b[1]-vec_a[1]*vec_b[0]); - - AD::SetPreaccOut(Local_Volume); - AD::EndPreacc(); - - return Local_Volume; -``` - -With preaccumulation we only store the derivatives of the variables flagged using `AD::SetPreaccIn` with -respect to the variables flagged with `AD::SetPreaccOut`. For our example this results in 6 values, which -means total saving of memory of 50%. Note that this exemplary code snippet is executed for every element -in the mesh. Throughout the code this method is applied at several spots where a clear identification of -inputs and outputs was possible. diff --git a/_docs/Build-from-Source.md b/_docs/Build-from-Source.md deleted file mode 100644 index 4f33eb0f..00000000 --- a/_docs/Build-from-Source.md +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: Build From Source -permalink: /docs/Build-from-Source/ ---- - -## Source Install Overview - -This section provides details on the various tools and requirements when building the SU2 suite from the source code on Linux/Mac OS X systems. Please see the [Simple Build](/docs/Simple-Build/), [Parallel Build](/docs/Parallel-Build/) or [AD Build](/docs/AD-Build/) pages for concise directions on the install process. - -### GNU Autoconf / Automake Tools - -These tools are widely used and frequently installed with most installations of Linux and Max OS X. Please check your system to ensure these tools are available prior to installation. Starting from release 3.1.0 and onward, the required versions of autotools are included inside the externals/ directory, and a bootstrap script is included in the SU2/ directory for quickly building them and reseting the makefile structure if they are not available on your system or are an earlier version. - -Simply run ./bootstrap in the SU2/ root directory (you may need to adjust your PATH after running this script) to build the appropriate dependencies and reset the makefile structure rather than calling autoreconf on your own. - -### Compilers - -Installing SU2 from source requires a C++ compiler. The GNU compilers (gcc/g++) are open-source, widely used, and reliable for building SU2. The Intel compiler set has been optimized to run on Intel hardware and has also been used successfully by the development team to build the source code, though it is commercially licensed. The Apple LLVM compiler (Clang) is also commonly used by the developers. -- GNU gcc / g++ -- Intel icc / icpc -- Apple LLVM (clang) - -### Parallel Tools - -The ParMETIS graph partitioning software and a Message Passing Interface (MPI) implementation are required to compile and run SU2 in parallel. The source for ParMETIS is shipped with SU2 and can be found in the externals/ directory. ParMETIS will automatically be built and linked if you set -``` ---enable-mpi --with-cc=/path/to/mpicc --with-cxx=/path/to/mpicxx -``` -in your configure options, which requests a build of the parallel version of the code with the specified MPI implementation on your machine. If you do not have a MPI implementation, a number of available packages are listed on the main installation page. In particular, you will need both a C (for ParMETIS) and C++ (for SU2) MPI implementation. - -## Configuration - -Before building, a bootstrap script is included in the SU2/ directory for quickly customizing the autotools structure on your system. Simply run -``` -$ ./bootstrap -``` -in the SU2/ root directory (you may need to adjust your PATH after running this script) to build the appropriate dependencies and reset the makefile structure rather than calling autoreconf on your own. - -Next, SU2 must run the configuration script that will scan your system for the necessary prerequisites and generate the appropriate makefiles. The simplest version of SU2 can be configured by running configure with no arguments, or -``` -$ cd /path/to/SU2/ -$ ./configure -``` -This will configure serial (non-MPI) versions of all SU2 modules without external library support and a moderate level of compiler optimization. The configure tool will attempt to find a C++ compiler on your system and set some default flags if none are specified. It is strongly recommended, however, that the environment variables used by configure be set before configuring (especially CXX and CXXFLAGS). Numerous flags are available to activate or deactivate optional features. These include support for various external libraries, compiler flags for optimization and fine tuning, and the selection of specific modules to build or ignore. A complete list of optional features and relevant environment variables is shown by running -``` -$ ./configure --help -``` -For example, to configure SU2 for parallel calculations (i.e., with ParMETIS and MPI) along with CGNS and TecIO support (both libraries enabled by default) and a high level of compiler optimization, the configure command might look like this (replace with specific paths on your system): -``` -$ ./configure --prefix=/path/to/install/SU2 --enable-mpi --with-cc=/path/to/mpicc ---with-cxx=/path/to/mpicxx CXXFLAGS="-O3" -``` -When defining the installation path via the --prefix option, note that you will need write access to the destination folder when installing the executables after compiling them (see below). You can switch to a privileged user (or sudo) before installing if necessary. You do not need to rerun the configuration step unless you modify the options, i.e. you would like to change compilers, dependencies, etc. Updating the source code and recompiling does not require reconfiguring: simply rerun the make and make install commands. - -## Compiling - -After configuring, compile SU2 by calling -``` -$ make -``` -This compiles the code using the makefiles that were automatically generated from the results of the configure process. You can also use the "-j N" option of the make command in order to compile SU2 in parallel using N cores, i.e., run -``` -$ make -j 8 -``` -to compile using 8 cores. This can greatly reduce the compilation time if building on a multi-core laptop, workstation, or cluster head node. If no errors are encountered, you are ready to install. - -## Installing - -After compiling, you are ready to install SU2. To install, enter the command -``` -$ make install -``` -This will copy the programs and Python scripts comprising the SU2 suite to the folder that you selected with the `--prefix` option during configuration. If no prefix was supplied during the configure step, the executables will be installed in /usr/local/bin by default. As noted above, you will need write access to the destination folder to install. - -## Cleaning - -To clean the SU2 source tree (remove all intermediate object files), enter the command -``` -make clean -``` -in the root directory of the SU2 source distribution. This is recommended before rebuilding if you modify the configuration and / or update the source code. - -## Environment Variables - -After installing the code (but before running it), define the **SU2_HOME** and **SU2_RUN** environment variables, and update your PATH with SU2_RUN. For the basic installation, these values will be displayed at the conclusion of `./configure` from the steps above. These environment variables are useful for running SU2 from different working directories, and they are needed for some of the Python framework. - -`$SU2_RUN` should point to the folder where all binaries and python scripts were installed (by default, in a folder named `bin/` within your chosen install location from `--prefix`). `$SU2_HOME` should point to the root directory of your SU2 source distribution. - -For example, add these lines to your ~/.bashrc (linux) or ~/.bash_profile (macosx) file: -``` -export SU2_RUN="your/prefix/bin" -export SU2_HOME="/path/to/SU2" -export PATH=$SU2_RUN:$PATH -``` -If you plan to use the Python scripts for parallel calculations or design and optimization tasks, you may also want to include $SU2_RUN in your Python path: -``` -export PYTHONPATH=$SU2_RUN:$PYTHONPATH -``` - -That's it: you're now ready to run SU2! Check out the Quick Start and additional tutorials. - -### Notes for Mac OS X Users - -In order to prepare your Mac for compiling/running/developing SU2, you will need to download Xcode from the App Store. After obtaining Xcode, you should also install the Developer Tools package from inside of the Xcode distribution. This contains tools like make and the LLVM compiler, and after installing the dev tools, they will be available from within the native Terminal app. If you can not find gcc, make, etc. at the command line after installing Xcode, you may need to install the remaining developer tools by entering the following command in the terminal: `xcode-select --install`. - -Environment variables, such as SU2_RUN and SU2_HOME, on Mac OS X can be set within ~/.bash_profile (this file may not exist by default, so you can create it yourself if necessary). Lastly, note also that project files for developing the SU2 modules in Xcode are provided inside the SU2/SU2_IDE/Xcode/ directory of the SU2 source distribution. diff --git a/_docs/Code-Review.md b/_docs/Code-Review.md deleted file mode 100644 index 819c64a7..00000000 --- a/_docs/Code-Review.md +++ /dev/null @@ -1,45 +0,0 @@ ---- -title: Code Review -permalink: /docs/Code-Review/ ---- - -Code review is a process where changes to the SU2 repository are examined by other developers before being merged into the development branch - -# Purpose -The goal of code review is to maintain correct code in a consistent style. Humans make mistakes, and code review is in place to catch mistakes before they become part of the main code suite. Good code is not just correct, but is also legible, and what is clear to the code author may not be clear to a reader of the code. Code review ensures that the code is understandable by at least two developers - -# Philosophy -All developers and users (internal and external) are encouraged to participate in the code review process. The SU2 suite is a computational environment we are all working to maintain. When performing a code review, you should be asking yourself "Is this code that I want in our environment". A single developer may have written the bulk of the pull request, but once a change has been incorporated the whole community is in charge of future changes (maintenance, debugging, etc.). Questions you should ask yourself are - -1. Is this a desirable change to the code base? -- Does it make the code more legible? -- Add new features? -- Fix a bug? - -2. Is the change implemented in the correct way? -- Does it interact minimally with the rest of the code? -- Does it have the correct algorithmic complexity? -- Is it located in the right place? (file, etc.) - -3. Is the code legible? -- Is the code mostly legible on its own without documentation? -- Are the variable names concise and accurate? -- Is there documentation where necessary, and is it correct? - -4. Does the code follow established conventions? -- Does it match the SU2 code style? -- Do the variable names follow the same patterns as in other parts of the code? - -# Good code changes -The above list is a long list of questions. A large change to the code will be much harder to review than a small change. As such, good pull requests will contain a minimal set of changes to be useful. Pull requests should "do one thing". In some cases, "doing one thing" may be a large change to the code, such as adding a new flow solver. In most cases, changes can be done in small increments that can each individually be reviewed and evaluated. Pull requests should not be of the form "Add a new config option and fix a bug in interation_structure.cpp". These should be two separate pull requests. - -# The Code Review Process -Github provides an easy interface for performing code reviews as part of every Pull Request. After a Pull Request is submitted to the SU2 'develop' branch, two different developers must review and approve the code changes before the request can be merged, in addition to passing the Travis CI regression test suite. Reviewers have the opportunity to comment on the changes and requests specific changes. - -In response to these comments, the pull requester should make changes to the code (or engage in dialogue on disagreements). Traditionally this is done with the characters "PTAL", which stand for "Please take a(nother) look". - -When a reviewer is happy with the proposed changes to the code, the reviewer should approve and can say "LGTM", standing for "looks good to me". In general, the changes to the code should be finalized before a LGTM is given, though if there are only very minor outstanding issues an LGTM can be given along with the changes. For example, if the only outstanding issue with the PR is that a word has been misspelled, a reviewer may make an inline comment about the misspelling, and in the main dialogue say "LGTM with the comment fix". - -All developers are encouraged to participate in the code review process, as the code is for everyone. However, there will typically be a specific set of developers who are experts in the section of code that is being modified. Generally, an LGTM should be gotten from at least one of these developers before merging. Users can be requested using "@username", for example, "PTAL @su2luvr". This sends that user an email about the pull request. Similarly, this can be used to request the opinions of other developers. While this can feel burdensome, it is in place to maintain good, correct code. Please use good judgement -- if the change is a spelling fix in a comment, it is not necessary to solicit the opinion of the entire development team. - -Once the proper set of "LGTM"s has been received, the change can be merged. If the pull-requester has commit access, it is tradition to let them make the merge. If the requester does not, then the main/final reviewer can submit the merge. If the pull-request came from an internal branch, the branch should be deleted on conclusion if it is no longer useful. diff --git a/_docs/Code-Structure.md b/_docs/Code-Structure.md deleted file mode 100644 index 65494964..00000000 --- a/_docs/Code-Structure.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: Code Structure -permalink: /docs/Code-Structure/ ---- - -Full details on the class hierarchy and internal structure of the code can be found in the Doxygen documentation for SU2. A brief description for the major C++ classes is given on this page. - -The objective of this section is to introduce the C++ class structure of SU2 at a high level. The class descriptions below focus on the structure within SU2_CFD (the main component of SU2), but many of the classes are also used in the other modules. Maximizing the flexibility of the code was a fundamental driver for the design of the class architecture, and an overview of the collaboration diagram of all classes within SU2_CFD is shown below. - -![Class Structure General](../../docs_files/class_c_driver__coll__graph.png) - -At the highest level, SU2_CFD has a driver class, **CDriver**, that controls the solution of a multiphysics simulation. The **CDriver** class is responsible for instantiating all of the geometry, physics packages, and numerical methods needed to solve a particular problem. The **CDriver** class within SU2_CFD instantiates many classes, including the following: -- **CConfig** - Reads and stores the problem configuration, including all options and settings from the input file (extension .cfg). -- **COutput** - Writes the output of the simulation in a user-specified format (Paraview, Tecplot, CGNS, comma-separated values, etc.). -- **CIntegration** - Solves the particular governing equations by calling the child classes CMultiGridIntegration, CSingleGridIntegration. This is used for both multigrid or single-grid calculations, and it connects the subclasses CGeometry, CSolver, and CNumerics for performing integration in time and space. -- **CIteration** - Classes that complete an iteration of a single physics package, e.g., fluid or structure. - -The core capabilities of the computational tool are embedded within the CGeometry, CSolver, and CNumerics classes that manage the geometry, the main solver functionality (definition of the terms in the PDE), and the numerical methods, respectively. In the next subsection, these three classes will be discussed. - -## CGeometry Class - -This class reads and processes the input mesh file (extension .su2), and it includes several child classes, such as: -CPhysicalGeometry - Constructs the dual mesh structure from the primal mesh. Note that the FVM formulation in SU2 is based on the dual mesh with edge-based data structures. - -- **CMultiGridGeometry** - If multigrid is requested, this class automatically creates consecutively coarser meshes from the original input mesh using a control volume agglomeration procedure. These coarse grid levels are then used for multigrid calculations. -- **CPrimalGrid** and **CDualGrid** - Two classes (see Fig. below) that are used for defining the geometrical characteristics of the primal and dual grids. - -![Class Structure Geometry](../../docs_files/Class_Structure_Geometry.png) - -## CSolver Class - -In this class, the solution procedure is defined. Each child class of CSolver represents a solver for a particular set of governing equations. These solver classes contain subroutines with instructions for computing each spatial term of the PDE, e.g., loops over the mesh edges to compute convective and viscous fluxes, loops over the mesh nodes to compute source terms, and routines for imposing various boundary condition types for the PDE. - -One or more of these child classes will be instantiated depending on the desired physics, and several examples are: -- **CEulerSolver** - For the Euler equations (compressible or incompressible). -- **CTurbSolver** - For a turbulence model. -- **CAdjEulerSolver** - For the adjoint equations of the Euler equations. - -The solver containers also lead to one of the defining features of SU2: the ability to easily construct multi-physics problems by combining multiple solvers representing different physics. For example, the mean flow equations are easily coupled to the S-A turbulence model by instantiating both the CNSSolver class and the CTurbSASolver class. These two solver containers will control the solution of the different PDEs while being integrated simultaneously, and the information they contain can be freely passed back and forth. Another example of this flexibility arises when solving the adjoint equations. For instance, when solving the adjoint Euler equations, both the CAdjEulerSolver and the CEulerSolver classes are instantiated, as the adjoint equations require a copy of the flow solution that will be read from a solution file and stored by the CEulerSolver class. - -![Class Structure Sol](../../docs_files/class_c_solver__inherit__graph.png) - -The solver classes call the CVariable class for storing unknowns and other variables pertinent to the PDE at each mesh node, several classes in CNumerics in order to specify a spatial discretization of the governing equations (to be discussed below), and, if necessary, container classes for holding the matrices and vectors needed by linear solvers. A detailed list of all child classes found within CSolver is given in the Fig. below, but in general, these classes can be briefly described as follows: -- **CVariable** - Used to store variables at every point in the grid, such as the conservative variables (unknowns of the PDE). Depending on the system of equations being solved, CVariable instantiates a certain child class and stores a set of variables particular to that problem at each grid node. For example, the CNSVariable child class stores the variables for the Navier-Stokes equations, which will include viscosity, while the CEulerVariable child class does not need to store viscosity. A detailed list of all these child classes is given in the Fig. below. -- **CSysMatrix** - Stores values for the Jacobians of fluxes and source terms in a sparse matrix structure for implicit calculations. It includes various methods for solving a linear system, including Krylov methods such as GMRES and BiCGSTAB, in addition to several preconditioning techniques, such as Jacobi, LU-SGS, or line implicit preconditioning. -- **CSysVector** - Holds and manipulates vectors needed by the linear solvers in combination with CSysMatrix to store the sparse matrix representation of the Jacobian. - -![Class Structure Var](../../docs_files/class_c_variable__inherit__graph.png) - -## CNumerics Class - -This class discretizes each system of governing equations using the numerical schemes specified in the input file. There are several child classes that provide a wide range of discretization techniques for convective fluxes, viscous fluxes, and any source terms that might be present in a given PDE. For example, if one is interested in solving the Navier-Stokes equations expressed in a non-inertial frame, CNumerics would call one child class corresponding to the convective scheme, one corresponding to the viscous terms, and a third for the discretization of the momentum source term that arises from the transformation of the equations to a rotating reference frame. - -As another example, during a single iteration of an implicit calculation, methods in the CNumerics classes would compute the flux contributions and Jacobians at each node (using the variables stored in the CVariable class). These flux and Jacobian values are transferred back to the CSolver class, and the CSolver class calls routines within CSysMatrix in order to solve the resulting linear system of equations for the solution update. The Fig. below shows a list of the various capabilities in the CNumerics class. - -![Class Structure Numerics](../../docs_files/Class_Structure_Numerics.png) diff --git a/_docs/Configuration-File.md b/_docs/Configuration-File.md deleted file mode 100644 index 8af61ff1..00000000 --- a/_docs/Configuration-File.md +++ /dev/null @@ -1,20 +0,0 @@ ---- -title: Configuration File -permalink: /docs/Configuration-File/ ---- - -The configuration file is a text file that contains a user's options for a particular problem to be solved with the SU2 suite. It is specified as an input upon execution of SU2 components. This section briefly describes the file format and other conventions. - -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. 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. - - `FREESTREAM_VELOCITY = ( 5.0, 0.00, 0.00 ) % braces and commas can be used for list options` - - `REF_ORIGIN_MOMENT= 0.25 0.0 0.0 % however, braces and commas are optional for lists` - - `KIND_TURB_MODEL = NONE % space between elements is not significant` -- **Comments**. On a given line in the file, any text appearing after a % is considered a comment and is ignored by SU2. Additional % signs after the first on a given line are not significant. -- **White space**. Empty lines are ignored. On text lines that define options, white space (tabs, spaces) can be used to format the appearance of the file - -SU2 includes strict error checking of the config file upon execution of one of the C++ modules. For example, the code will throw errors if unknown options are specified, options appear more than once, extra text appears outside of comments, etc. diff --git a/_docs/Contact.md b/_docs/Contact.md deleted file mode 100644 index 9a09f691..00000000 --- a/_docs/Contact.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Contact -permalink: /docs/Contact/ ---- - -### SU2 Forum at CFD Online and GitHub - -Users of SU2 who have questions not addressed in the User's Guide, Developer's Guide, or FAQs pages, please post the question in the CFD online forum. [http://www.cfd-online.com/Forums/su2/](http://www.cfd-online.com/Forums/su2/) - -If you find bugs or issues in the source code or would like to submit a feature request, please use the issue tracker on the SU2 GitHub page at: [https://github.com/su2code/SU2/issues](https://github.com/su2code/SU2/issues) - -### SU2 User's Mailing List -Users are encouraged to join the SU2 user's email list. This list will be used to communicate important information to users such as new releases or event announcements. To join, follow the link below. We take privacy matters seriously - please see our privacy and cookie policies for more information. - -[Join the List!](https://su2foundation.org/) - -### Join the SU2 Development Team - -All developers that would like to contribute to SU2 are encouraged to get involved on [GitHub](https://github.com/su2code/SU2). Whether you would like to share new features or fixes with the community through Pull Requests, report issues or feature requests, or discuss the latest with your fellow developers, your participation is most welcome! diff --git a/_docs/Cygwin-Build-for-Windows.md b/_docs/Cygwin-Build-for-Windows.md deleted file mode 100644 index b2db2228..00000000 --- a/_docs/Cygwin-Build-for-Windows.md +++ /dev/null @@ -1,211 +0,0 @@ ---- -title: Cygwin Build for Windows -permalink: /docs/Cygwin-Build-for-Windows/ ---- - -### Overview -Cygwin provides a unix-like environment on a Windows machine, and emulates some of the functionality of a linux distribution. Downloads and more information on Cygwin is available at http://www.cygwin.com/. To compile and run SU2 in Cygwin on a Windows machine, you will need to configure Cygwin with the appropriate packages (listed below), and then continue from within Cygwin as though you were using a linux machine. -In summary, the steps are: - -1. Download Cygwin installer -2. Install Cygwin, selecting the packages necessary to compile the source code. -3. Download the source code into a directory within cygwin/ -4. Install SU2 according to the directions for the linux installation. - -### Notes on installing Cygwin for first-time or beginner Cygwin users -* It is often recommended to install in a directory rather than the default C:\ location. -* The Cygwin shell will only be able to access folders that are within the cygwin\ directory; you will need to install and run SU2 inside the cygwin directory. - -### Cygwin packages -At the package selection step, search for the following terms and select the associated packages to install. This list is a work-in-progress, and further packages may be required or desired. - -#### Basic -* g++, gcc compiler -* python: install the packages under the python sub-heading -* cpp: all debug, pre-processor, regular expression packages. - -### Example SU2 installation on WINDOWS 10 using 64-bit Cygwin - -The CYGWIN `bash` shell is used for all steps on the command line. It is automatically available after the first installation step (typically to be launched via the CYGWIN desktop icon). - -1. Install CYGWIN (64-bit version) and development packages - * Download and run: - - [setup-x86_64.exe](https://www.cygwin.com/setup-x86_64.exe) - - Inside the Cygwin Setup GUI use `C:\cygwin64` for both `Root Directory` and `Local Package Directory`. `Chose a Download Site` close to you (also http mirrors often work better). Continue to complete the bare minimum installation. This will end with a desktop icon named `Cygwin64 Terminal`. Double-click this to open the shell and launch further commands from there. - - For detailed informations on how to install CYGWIN and selected packages see [CYGWIN Installation](https://cygwin.com/install.html). - - * Install development tools (dependencies on these packages will be automatically selected by CYGWIN) - - > NOTE: A single command installing all required packages in one is given below this list - - 1. General build environment tools - * autoconf - * autoconf2.5 - * autogen - * automake - * automake1.15 - * libtool - * make - 1. Compilers - * gcc-g++ - * mingw64-x86_64-gcc-core - * mingw64-x86_64-gcc-g++ - 1. Python - * python37 - * python37-devel - * python3-configobj - 1. OpenMPI - * libopenmpi-devel - * openmpi - 1. Miscellaneous - * vim (or any other editor in order to be able to edit files) - * rsh - * wget (to be able to download from the command line) - * zlib-devel - - * All-in-one installation of packages (after the initial minimum installation): - - > NOTE: Prepend path to `setup-x86_64.exe` (depending where it has been downloaded) - - ```bash - setup-x86_64.exe -q -P autoconf,autoconf2.5,autogen,automake,automake1.15,libtool,make,gcc-g++,mingw64-x86_64-gcc-core,mingw64-x86_64-gcc-g++,python37,python37-devel,python3-configobj,libopenmpi-devel,openmpi,vim,rsh,wget,zlib-devel - ``` - -1. Configure CYGWINs default mount point (optional, but following steps use a syntax relying on this) - - ```bash - mount -c / -o binary,noacl,posix=0 - mount -m > /etc/fstab - ``` - -1. Configure OpenMPI - - Because in OpenMPI the C++ interface was removed, the option `-lmpi_cxx` has to be removed from the linker defaults. We need to check if this option is contained in the wrapper control file. This depends on the installed OpenMPI libraries. - - Assuming the 64-bit CYGWIN is installed in `C:\cygwin64` and `/etc/fstab` has been modified as in the previous step: - - ```bash - cat /c/cygwin64/usr/share/openmpi/mpic++-wrapper-data.txt | grep lmpi_cxx - ``` - - If the option is set, then the following lines would be the result of the above `grep`command: - - libs=-lmpi_cxx -lmpi - libs_static=-lmpi_cxx -lmpi -lopen-rte -lopen-pal -lm -lgdi3 - - > NOTE: If `-lmpi_cxx` was not found, skip the next step - - If this is the case, edit `mpic++-wrapper-data.txt` and remove the `-lmpi_cxx` options so that the respective lines look like this: - - libs=-lmpi - libs_static=-lmpi -lopen-rte -lopen-pal -lm -lgdi3 - -1. Set the Python version for the installation process (for permanent setting add this line to `~/.profile`) - - ```bash - export PYTHON=/usr/bin/python3.7 - ``` - -1. Get the SU2 source code: - - * Download following file for SU2 version 6.2.0 - - ```bash - wget https://github.com/su2code/SU2/archive/v6.2.0.tar.gz - ``` - - * Extract files and change into the folder where the files were extracted to: - - ```bash - tar -xzvf v6.2.0.tar.gz - cd SU2-6.2.0 - ``` - - > NOTE: This is later the folder where the SU2_HOME variable points to - -1. Run the utility for autoconf/automake toolchain setup: - - ```bash - ./bootstrap - ``` - -1. Set compiler flags (just to be sure not to use the debug option -g) - - ```bash - export CFLAGS='-O2' - export CXXFLAGS='-O2' - ``` - -1. Create Makefiles: - - > NOTE: didn't yet get `tecio` working, therefore disabled with `--disable-tecio`
- > NOTE: Removed `-DHAVE_EXECINFO_H` from metis cppflags (potentially could be solved via [gnulib](https://www.gnu.org/software/gnulib/manual/html_node/execinfo_002eh.html)) - - ```bash - ./configure --prefix=/home/Andreas/SU2-6.2.0 -enable-mpi --with-cc=/usr/bin/mpicc --with-cxx=/usr/bin/mpicxx --disable-tecio --with-metis-cppflags="-D_FILE_OFFSET_BITS=64 -DNDEBUG -DNDEBUG2 -DHAVE_GETLINE" - ``` - -1. Compile and link using: - - ```bash - make - ``` - -1. Distribute executables, etc. to their intended locations: - - ```bash - make install - ``` - -1. Reduce size of executables significantly (strip symbols, see also [CYGWIN FAQ 6.3](https://www.cygwin.com/faq.html). The SU2_CFD.exe is reduced from approx. 600MB to 15MB. Can be omitted if compiled with the -s option to gcc. - > NOTE: This should **NOT** be necessary if compiler flags are set as shown in step 7 - ```bash - make install-strip - ``` - -1. Cleanup the installation. This removes also the intermediate big executables from the build folders. - - ```bash - make clean - ``` - -1. Add the `$SU2_HOME` and `$SU2_RUN` environment variables to `~/.bashrc` (and `source ~/.bashrc`) - - ```bash - export SU2_RUN="path_where_you_want_the_Executables" (use same folder here as in the configure command above) - export SU2_HOME="/d/software/CFD/SU2/SU2-6.2.0" <-- UPDATE THIS folder according to your environment - export PATH=$PATH:$SU2_RUN - export PYTHONPATH=$PYTHONPATH:$SU2_RUN - ``` - -1. Test serial and parallel versions: - - ```bash - cd $SU2_HOME/QuickStart - ``` - - SERIAL command (due to the previous step `SU2_CFD.exe` should now be available in the path): - - ```bash - SU2_CFD.exe inv_NACA0012.cfg - ``` - - PARALLEL command: - Both `mpirun` and `mpiexec` do the same; `mpiexec` is recommended as the standard command. - - ```bash - mpiexec -n 4 SU2_CFD.exe inv_NACA0012.cfg - ``` - - If more processes are requested than cores are available an error will be thrown: - - > There are not enough slots available in the system. - - On WINDOWS this can be if hyperthreading is active. A system physically having 4 CPUs (cores), would show 8 CPUs in case of hyperthreading. Oversubscribe allows more processes than cores (which not necessarily is faster). - - ```bash - mpiexec -n 8 -oversubscribe SU2_CFD.exe inv_NACA0012.cfg - ``` diff --git a/_docs/Developing-SU2-on-GitHub-(Internal-Developers).md b/_docs/Developing-SU2-on-GitHub-(Internal-Developers).md deleted file mode 100644 index 2fd3546e..00000000 --- a/_docs/Developing-SU2-on-GitHub-(Internal-Developers).md +++ /dev/null @@ -1,85 +0,0 @@ ---- -title: Developing SU2 on GitHub (Internal Developers) -permalink: /docs/Developing-SU2-on-GitHub-(Internal-Developers)/ ---- - -The repository for SU2 is being hosted on here on GitHub. As you are likely aware, GitHub is simply an online project hosting service with a very useful web interface and additional tools to aid code development with Git as its backbone. Git is a version control system (VCS) that is similar to SVN, Mercurial, etc., and it helps organize the development of code over time by tracking changes. - -To get started, you need to create a personal user account on GitHub (free) and follow the [basic setup instructions](https://help.github.com/articles/set-up-git). These instructions include how to get Git installed on your local machine. To sync up your local settings with GitHub, change the user.email and user.name variables for your local git configuration with -``` -git config --global user.email "your_email@domain.com" -git config --global user.name "Your Name" -``` -Note that the email address should be the one associated with your GitHub account. - -SU2 is an open-source repository that can be found as part of the [**su2code** organization on GitHub](https://github.com/su2code). The web interface is useful for viewing the recent commits to the code, changes to the code over time, documentation and tutorials, or for creating and viewing branches, for instance. To contribute to the SU2 organization repositories directly, an administrator for the project must add you as a member of the developer team with push and pull privileges. However, we encourage all developers to fork the repository and to submit pull requests with their interesting new features that they would like included in the code. We regularly review pull requests as a development team. - -Most of the day-to-day development of the code will be done on your local machine at the command line using Git. After setting up Git and gaining access to the SU2 repository, create a local copy of the entire repository on your machine by cloning the version that is hosted on GitHub: -``` -git clone https://github.com/su2code/SU2.git -``` -After cloning, you should have a new SU2/ folder in your current working directory. Move into SU2/ to see the project files and to start working with the code through Git. You can see the most recent changes by typing -``` -git log -``` - -## Typical Workflow with Git - -Now that you have a local copy of SU2 from the GitHub repository, you can begin to make changes to the codebase. This section gives an example of the typical workflow for making changes to the code, committing them locally, and then pushing your changes to the remote GitHub repository. - -Please read the "Code Reviews" section of the wiki before making changes to familiarize yourself with the requirements for a good code change. - -In the SU2 repository, the master branch represents the latest stable major or minor release (3.0, 3.2.9, etc.), it should only be modified during version releases. Work on the code takes place on the develop branch. When a repository is cloned, all of the branches are as well, and so no additional work is necessary to acquire the development branch. However, you must tell git to switch to the development branch, which can be done with the "checkout" command - ``` - git checkout -b develop origin/develop - ``` -Now that changes will be on top of the development branch, code changes can be made. This next section describes the steps for creating a pull request. - -1. Create a new branch for making your changes. - ``` - git checkout -b fixquadvol - ``` -Additionally, create a branch with the same name on the SU2 github repository. First, make sure the current SU2 branch is set to develop - -![Develop Branch](../../docs_files/pr_develop_branch.png) - -then create a new branch with the appropriate name. - -![Create Branch](../../docs_files/pr_create_branch.png) - - -1. Make changes to the existing files (using your favorite text editor or integrated development environment, IDE) or add local files or folders to be tracked and compared against the global repo files. - - ``` - git add file1.cpp file2.cpp - ``` - -2. Optionally check that your changes have been registered and/or the files that you want have been added added - - ``` - git status - ``` - -3. Commit the changes to your local repository (not the global repository on GitHub) and create a descriptive message about your change. Commit messages are the easiest tool for examining past code changes, so it is important that they serve as documentation. A good commit message will consist of a short descriptive message on the first line, followed by a longer descriptive message. If the PR addresses any issues, they should be identified in the commit message. A good (fake) commit message is below. - - ``` - git commit -m "Fix computation of the volume for skewed quadrilateral elements. - -If a 2-D quadrilateral element is sufficiently skewed, the volume approximation is not computed properly. This modifies the volume computation to use the base and height of the quadrilateral instead of the base and hypotenuse. This fixes cases where the volume was incorrectly computed to be less than zero. - -Fixes issue 10." - ``` - -4. Push the code to the online version of the branch - - ``` - git push origin fixquadvol - ``` - -5. This will automatically register on github, and you can use the online API to make a pull request - -![Submit Request 1](../../docs_files/pr_submit_request_1.png) - -![Submit Request 2](../../docs_files/pr_submit_request_2.png) - -6. Now your code is available for code review! diff --git a/_docs/Download.md b/_docs/Download.md deleted file mode 100644 index ed1f8561..00000000 --- a/_docs/Download.md +++ /dev/null @@ -1,9 +0,0 @@ ---- -title: Download -permalink: /docs/Download/ ---- - -SU2 is freely available for use under the GNU Lesser General Public License, version 2.1. Please reference the [license details](https://www.gnu.org/licenses/old-licenses/lgpl-2.1.en.html) for terms and conditions. - -Please visit our [download portal](../../download.html) to obtain binary executables or the SU2 source code and [register as a user of SU2](https://su2foundation.org/)! - diff --git a/_docs/Execution.md b/_docs/Execution.md deleted file mode 100644 index d8acb036..00000000 --- a/_docs/Execution.md +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: Execution -permalink: /docs/Execution/ ---- - -Once downloaded and installed, SU2 will be ready to run simulations and design problems. Using simple command line syntax, users can execute the individual C++ programs while specifying the problem parameters in the all-purpose configuration file. For users seeking to utilize the more advanced features of the suite (such as shape optimization or adaptive mesh refinement), Python scripts that automate more complex tasks are available. Appropriate syntax and information for running the C++ modules and python scripts can be found below. - -## C++ Modules - -As described in the [Software Components](/docs/Software-Components/) page, there are a number of C++ modules that are the core of the SU2 suite. After compilation, each can be executed at the command line using a Unix-based terminal (or appropriate emulator, such as Cygwin). The executables for these modules can be found in the `$SU2_HOME//bin` directories and in the `$SU2_HOME/SU2_PY` directory. The configuration file specifies the problem and solver parameters for all SU2 modules and must be included at runtime. - -The syntax for running each C++ module individually in serial is: -``` -$ SU2_MODULE your_config_file.cfg -``` -where `SU2_MODULE` can be any of the C++ modules on the [Software Components](/docs/Software-Components/) and `your_config_file.cfg` is the name of the configuration file that you have prepared for the problem. An example of a call to SU2_CFD with a configuration file "default.cfg" is included below: -``` -$ ./SU2_CFD default.cfg -``` -where the executable, SU2_CFD, and the [Configuration File](/docs/Configuration-File/), default.cfg, are located in the current working directory. Please see the [Build from Source](/docs/Build-from-Source/) page for how you can set up environment variables to run the modules from any directory. Additionally, SU2 is a fully-parallel suite, and assuming that you have compiled with MPI support, each of the modules can be executed in parallel. For example, to run the CFD solver on 8 cores, you might enter: -``` -$ mpirun -n 8 SU2_CFD default.cfg -``` -Note that, depending on your flavor of MPI, you may need to use a different launcher, such as *mpiexec*. Please see the documentation for your particular MPI implementation. - -## Python Scripts - -The distribution of SU2 includes several Python scripts that coordinate the use of the C++ modules to perform more advanced analyses and simulations. A working installation of Python is highly recommended, as a number of tasks can be easily automated using provided scripts (e.g., computing a drag polar). These Python scripts can be found in the $SU2_HOME/SU2_PY. - -All of the scripts can be executed by calling python and passing the appropriate SU2 python script and options at runtime. The syntax is as follows: -``` -$ python script_name.py [options] -``` -where *script_name.py* is the name of the script to be run, and [options] is a list of options available to each script file. A brief description of the most commonly used scripts, their execution syntax, and runtime options are included below. Users are encouraged to look at the source code of the python scripts. As with many Python programs, the code is easily readable and gives the specifics of the implementation. They can also be used as templates for writing your own scripts for automating SU2 tasks. - -### Parallel Computation Script (parallel_computation.py) - -The parallel computation script, parallel_computation.py, coordinates the steps necessary to run SU2_CFD in parallel and produce solution output files. The script calls SU2_CFD in parallel (using MPI) with the indicated number of ranks. At the conclusion of the simulation, the parallel_computation.py script generates the solution files from the restart file written during execution by calling the SU2_SOL module. **Note that during parallel execution, only restart files are written by SU2_CFD, not solution files, in order to reduce the overhead associated with I/O for large calculations**. The SU2_SOL module can be executed at any time (in serial or parallel) to generate solution files in a specified format from a restart file and corresponding mesh. - -Usage: `$ python parallel_computation.py [options]` - -Options: -* -h, --help show this help message and exit -* -f FILE, --file=FILE read config from FILE -* -n PARTITIONS, --partitions=PARTITIONS number of PARTITIONS -* -c COMPUTE, --compute=COMPUTE COMPUTE direct and adjoint problem - -### Continuous Adjoint Gradient Calculation (continuous_adjoint.py) - -The continuous adjoint calculation script, continuous_adjoint.py, automates the procedure for calculating sensitivities using the SU2 suite using adjoint methods. The script calls SU2_CFD to first run a direct analysis to obtain a converged solution, then calls SU2_CFD again to run an adjoint analysis on the converged flow solution to obtain surface sensitivities. The SU2_DOT module is then called to project design variable perturbations onto the surface sensitivities calculated in the adjoint solution to arrive at the gradient of the objective function with respect to the specified design variables. - -Usage: `$ python continuous_adjoint.py [options]` - -Options: -* -h, --help show this help message and exit -* -f FILE, --file=FILE read config from FILE -* -n PARTITIONS, --partitions=PARTITIONS number of PARTITIONS -* -c COMPUTE, --compute=COMPUTE COMPUTE direct and adjoint problem -* -s STEP, --step=STEP DOT finite difference STEP - -### Discrete Adjoint Gradient Calculation (discrete_adjoint.py) - -Similar to the continuous adjoint script, the discrete adjoint script calls SU2_CFD to generate a flow solution and then calls SU2_CFD_AD to run an adjoint computation based on the objective function specified in the config file. Finally, SU2_DOT_AD is called to map the surface sensitivities onto the design variables specified desig variables. - -Usage: `$ python discrete_adjoint.py [options]` - -Options: -* -h, --help show this help message and exit -* -f FILE, --file=FILE read config from FILE -* -n PARTITIONS, --partitions=PARTITIONS number of PARTITIONS -* -c COMPUTE, --compute=COMPUTE COMPUTE direct and adjoint problem - -### Finite Difference Gradient Calculation (finite_differences.py) - -The finite difference calculation script is used to calculate the gradient of an objective function with respect to specified design variables using a finite difference method. This script calls SU2_CFD repeatedly, perturbing the input design variables and mesh using SU2_DEF, stores the sensitivity values, and outputs the gradient upon exit. - -Usage: `$ python finite_differences.py [options]` - -Options: -* -h, --help show this help message and exit -* -f FILE, --file=FILE read config from FILE -* -n PARTITIONS, --partitions=PARTITIONS number of PARTITIONS -* -s STEP, --step=STEP finite difference STEP -* -q QUIET, --quiet=QUIET, if True, output QUIET to log files - -### Shape Optimization Script (shape_optimization.py) - -The shape optimization script coordinates and synchronizes the steps necessary to run a shape optimization problem using the design variables and objective function specified in the configuration file. The optimization is handled using SciPy's SLSQP optimization algorithm by default. Objective functions (drag, lift, etc.) are determined by running a direct flow solution in SU2_CFD, and gradients are obtained using the adjoint solution by default (other options can be selected). For each major iteration in the design process, the mesh is deformed using SU2_DEF, and the sequence is repeated until a local optimum is reached. - -Usage: `$ python shape_optimization.py [options]` - -Options: -* -h, --help show this help message and exit -* -f FILE, --file=FILE read config from FILE -* -r NAME, --name=NAME try to restart from project file NAME -* -n PARTITIONS, --partitions=PARTITIONS number of PARTITIONS -* -g GRADIENT, --gradient=GRADIENT Method for computing the GRADIENT (ADJOINT, DISCRETE_ADJOINT, FINDIFF, NONE) -* -q QUIET, --quiet=QUIET True/False Quiet all SU2 output (optimizer output only) diff --git a/_docs/FAQ.md b/_docs/FAQ.md deleted file mode 100644 index b8c55102..00000000 --- a/_docs/FAQ.md +++ /dev/null @@ -1,59 +0,0 @@ ---- -title: FAQ -permalink: /docs/FAQ/ ---- - -# Frequently Asked Questions -### I have a question that isn't answered here. Where can I get more help? -If the answer to your question is not here, try the [forum](http://cfd-online.com/Forums/su2/). - -### I am new to CFD and I don't know where to start. Can you help me? -The best place to start for a new user after installing the code is the [Quick Start](/docs/Quick-Start/) tutorial. - -### Where is the documentation? -The most easy-to-use documentation is the github wiki, and you just found it! Try starting with the [[Quick Start]]. -For more detail on what configuration options are available and their syntax, see the file config_template.cfg in the SU2 root directory: https://github.com/su2code/SU2/blob/master/config_template.cfg -Further documentation is available in the su2code/Documentation repository. - -### My simulation diverges. What should I do? -Adjust the configuration file options, or improve mesh quality. Refer to the forum, tutorials, and TestCases for more specific examples. The most common option to change is to lower the CFL number, usually to something around 1.0. - -### When I run in parallel, the code prints multiples of the same line, for example: -``` -> Iter Time(s) Res[Rho] Res[RhoE] CLift(Total) CDrag(Total) - -> Iter Time(s) Res[Rho] Res[RhoE] CLift(Total) CDrag(Total) - -> Iter Time(s) Res[Rho] Res[RhoE] CLift(Total) CDrag(Total) - -> 0 0.190073 -3.585391 -2.989014 0.114015 0.100685 - -> 0 0.190073 -3.585391 -2.989014 0.114015 0.100685 - -> 0 0.190073 -3.585391 -2.989014 0.114015 0.100685 -``` - -The code has not been compiled with parallel support. Refer to the installation instructions. - -### Where are my solution files? -When running in serial (or a parallel version on one MPI rank), SU2_CFD will write solution files for Tecplot or ParaView upon exit. In parallel, only restart files will be written by SU2_CFD in order to save I/O overhead during the calculation. Solution files can then be generated at the end of the calculation by using the SU2_SOL module along with the restart file. Users can also use the parallel_computation.py script to automate this process. - - -### What are Conservative_1, Conservative_2, etc? What about Residual[0], Residual[1], etc? What about Primitive[0], etc? Why don't you use the flow variables I'm used to? -* The conservative variables and the residuals refer to the quantities conserved in the flow equations: density, momentum, and energy. [\rho, \rho u, \rho v, \rho w, \rho e]. -* The primitive variables refer to density, velocity, pressure, etc. -* Residuals are printed in log10 format, and indicate how close the solution is to satisfying the governing equations. Convergence is usually determined by a desired reduction in the residual - a reduction of "6" would mean the residual is 10^-6 of its initial value. -* They are referred to as "conservative" and "primitive" to allow different solvers to use the same structure without confusion - rather than vary the name, the length and the values are varied. For example, in the RANS solver additional turbulent terms are needed, and in the incompressible solver fewer primitive variables are required. - - -### Help! I just updated the code from a version that previously worked for me, and now there is an error. What do I do? -* Easy fix: read the error output. If it says that there is an unrecognized config file option, remove the associated line from the config file. Note that the config options may change between code releases to allow more control, use new features, or simplify the config file. -* Medium fix: revert to the release you used to use. Make sure that the release/version number for the TestCases repository is the same, and remember to recompile. If a case which previously converged now diverges, or otherwise doesn't do what you expect, try changing the options like CFL number, artificial dissipation coefficients, etc. Read the initial output of the code to make sure that what you have set in the config file is being applied - some config file options only apply to certain solvers. -* Advanced fix: after exhausting the easy and medium options, or if a clear bug like a segfault occurs, post to the forum at cfd-online.com/Forums/su2/. - - -### I'm getting a warning about "Nonphysical points". What does that mean, and how do I fix it? -A nonphysical point means the solution has encountered a negative density. If the warnings stop after a few iterations it's ok. If the warnings continue, the solution is likely diverging and you may need to adjust the config file options. - -### Where can I get the suite of test cases for SU2? -The test case config files are found in the SU2 code repo, while the meshes are located in a separate repository under the SU2 organization. We recommend copying the meshes into place within the SU2 source directory where the config files reside (under version control). See [this page](/docs/Test-Cases/) for directions. diff --git a/_docs/Gitting-Started.md b/_docs/Gitting-Started.md deleted file mode 100644 index 019b366c..00000000 --- a/_docs/Gitting-Started.md +++ /dev/null @@ -1,21 +0,0 @@ ---- -title: GIT-ting Started -permalink: /docs/Gitting-Started/ ---- - -As you now know, GitHub is the center of all development efforts in SU2. The su2code organization contains the main code repository as well as supporting materials. You can check out all of the development activity, and new developers are encouraged to log feature requests, questions, and bug reports through the GitHub issue tracker. Developers can have their code contributions integrated through GitHub as well. For more information, keep reading! - -## Branching Model - -We follow [a popular git branching strategy](http://nvie.com/posts/a-successful-git-branching-model/) in order to leverage decentralized development. This list describes the types of branches on the SU2 repository. You'll want to pick the right one to work with, in order keep the merging process simple. - -- master -- stable, latest release and fixes -- develop -- current development, generally the branch for you to fork or start a new branch from -- feature_* -- feature specific branches -- fix_* -- branches that fix a particular bug or capability (not new features) - -## Contributing Code - -SU2 merges new code contributions through pull requests. As a new developer, you'll want to fork SU2 to your personal account. This creates a clone of the whole SU2 repository, branches and all, inside your github account. Generally you'll want to start from the develop branch, but you can check with the developers if you think it would be more appropriate to work on a feature branch. - -You can push all of your working changes to your forked repository. Once you're happy with these, and want to push them to the origin repository, submit a pull request to the 'develop' branch under the SU2 repo. Make sure to pull any new changes from the origin repository before submitting the pull request, so that the changes can be merged more simply. The SU2 developers will review the changes, make comments, ask for some edits. Then when everything looks good, your changes will merge into the main development branch! diff --git a/_docs/Installation.md b/_docs/Installation.md deleted file mode 100644 index 7a057be9..00000000 --- a/_docs/Installation.md +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: Installation -permalink: /docs/Installation/ ---- - -## Installing SU2 - -SU2 has been designed with ease of installation and use in mind. This means that, wherever possible, a conscious effort was made to develop in-house code components rather than relying on third-party packages or libraries. In simple cases (serial version with no external libraries), the flow solver can be compiled and executed with just a C++ compiler. However, the capabilities of SU2 can be extended using externally-provided software. For example, parallel computations require an installed implementation of MPI (Message Passing Interface) for data communication. Again, to facilitate ease of use and to promote the open source nature, whenever external software is required within the SU2 suite, packages that are free or open source have been favored. These dependencies and third-party packages are discussed below. - -**Building from source**: refer to the Source Installation Guide. This is the typical install method for Linux/Mac OS X. - -The binary executables available on the Download page are intended to get new users up and running as quickly as possible. This option is best for novice CFD users or those looking to quickly sample some of the features of SU2. To make these binary distributions available to a wide range of potential users, some advanced features requiring external libraries and dependencies have been disabled (most notably the ability to run simulations in parallel). In other words, the pre-compiled binary executables are simply the serial version of the SU2 C++ modules. -No compilation is required for users who select the binary distribution of SU2. Simply install the binaries, open a terminal, and proceed to the Quick Start Tutorial. Binaries are available for multiple platforms, including installers for Windows. - -**Windows users**: please refer to the [Windows Installation Guide](/docs/Windows-Installation/). - -## Required Software for Running SU2 - -### Command Line Terminal - -In general, all SU2 execution occurs via command line arguments within a terminal. For Unix/Linux or Mac OS X users, the native terminal applications are needed. For Windows users, Console is recommended. - -### Data Visualization - -Users of SU2 need a data visualization tool to post-process solution files. The software currently supports .vtk and .plt output formats natively read by ParaView and Tecplot, respectively. ParaView provides full functionality for data visualization and is freely available under an open source license. Tecplot is a commercially-licensed software package widely used by the scientific computing community and is available for purchase. Some SU2 results are also output to comma-separated value (.csv) files, which can be read by a number of software packages. Furthermore, CGNS output files can also be generated, which can also be read by the majority of visualization programs. The three most typical packages used by the development team are the following: -- ParaView -- Tecplot -- FieldView - -## Optional Third-Party Software - -Although not required, several third-party packages help extend the capabilities of SU2 for particular purposes. Details of the capabilities enabled in SU2 by adding the packages and how to obtain them are provided here. - -### Grid Generation - -Users wishing to perform analyses on their own meshes must have a means of generating them. The native SU2 grid format is designed for readability and ease of use: users with simple computational domains can write scripts to generate the appropriate meshes (and some example scripts are provided in the mesh files page). For more complex configurations, grid generation software is recommended, and it should have the capability to export to SU2 or CGNS file formats. Several open-source and commercial products are available, and a list of those used by the development team is included below. -- Pointwise -- Gmsh -- ICEM CFD -- Gambit - -Note that there are also a number of excellent contributions from the open-source community for creating and converting meshes between various formats (e.g., OpenFOAM to SU2 format). The developers encourage members of the community to share their contributions in this regard, and many of these contributions can be found in the threads of the SU2 forum on CFD Online. - -### CGNS Library - -To make creating your own meshes easier and more accessible, support for the open CGNS data standard has been included within SU2. The main advantage gained is that complex meshes created in a third-party software package (one that supports unstructured, single-zone CGNS file export) can be used directly within SU2 without the need for conversion to the native format. Moreover, as CGNS is a binary format, the size of the mesh files can be significantly reduced. If needed, a converter from CGNS to the SU2 format has been built into SU2 (See the inviscid wedge tutorial). Starting with SU2 v4.3, the source for version 3.3.0 of the CGNS library is shipped with SU2 in the externals/ directory, and it is automatically built and linked for you when compiling SU2. - -### Parallel Tools - -Users wishing to run simulations on distributed-memory computers using mesh partitioning will need an implementation of the Message Passing Interface (MPI) standard. In these situations, SU2 performs the partitioning using the ParMETIS software package. ParMETIS comes packaged with the SU2 source code in the externals/ directory, and it will be automatically built and linked during the configure; make; make install process with the autotools (see the instructions for installation from source). A variety of implementations of the MPI standard exist, and they can often be installed using package managers on Linux or Mac OS X. Alternatively, users can download and build their own MPI implementations from source. The following are some well-known, freely-available implementations of MPI: -- OpenMPI -- MPICH -- MVAPICH - -### Python & Python Modules - -Each of the C++ modules for SU2 can be called directly from the command line and do not require Python (even for parallel calculations with MPI). However, the coupling of the C++ modules needed for, for example, design optimization problems can be automated via the execution of the appropriate Python scripts included in the software distribution. For instance, when performing shape design, the shape_optimization.py script is available to automate all steps. Note that this script has additional dependencies on the NumPy and SciPy modules for scientific computing in Python, including optimization routines in the SciPy library. These packages are freely available at the sites linked below: -- Python -- NumPy -- SciPy - -Alternatively, Python and these packages can be found in prebuilt installations, such as the Canopy scientific Python distribution by Enthought, or from package managers like Homebrew for Mac OS X. diff --git a/_docs/Mesh-File.md b/_docs/Mesh-File.md deleted file mode 100644 index ca45798b..00000000 --- a/_docs/Mesh-File.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: Mesh File -permalink: /docs/Mesh-File/ ---- - -SU2 mainly uses a native mesh file format as input into the various suite components. Limited support for the CGNS data format has also been included as an input mesh format. CGNS support can be useful when it is necessary to create complex geometries in a third-party mesh generation package that can export CGNS files. A converter from CGNS to the native format is also built into SU2. Details on how to create and use these mesh formats is given below. - -## SU2 Native Format (.su2) - - In keeping with the open-source nature of the project, SU2 relies mostly on its own native mesh format. The format is meant to be simple and readable. A description of the mesh and some examples are below. - -### Description - -The SU2 mesh format carries an extension of .su2, and the files are in a readable ASCII format. As an unstructured code, SU2 requires information about both the node locations as well as their connectivity. The connectivity description provides information about the types of elements (triangle, rectangle, tetrahedron, hexahedral, etc.) that make up the volumes in the mesh and also which nodes make up each of those elements. Lastly, the boundaries of the mesh, or _markers_, are given names, or tags, and their connectivity is specified in a similar manner as the interior nodes. - -### Specification - -Consider the following simple, 2D mesh for a square domain consisting of 8 triangular elements. It will be used to explain the .su2 mesh format. - -![Square Mesh Example](../../docs_files/square.png) - -**Square Mesh Example: Note that the figure uses Tecplot node and element number (1-based). The node and element numbering for SU2 start at 0.** - -The first line of the .su2 mesh declares the dimensionality of the problem. SU2 can handle 2D or 3D geometries. As a note, for 2D simulations, it is recommended that a truly 2D mesh is used (no z-coordinates) rather than a quasi-2D mesh (one or more cells deep in the third dimension with symmetry boundary conditions). For the 2D square mesh, the dimension is defined as follows: - -``` -NDIME= 2 -``` - -SU2 searches specifically for the keyword `NDIME=` in order to set the dimension, and the dimension value will be stored for use throughout the code. This value would be 3 for a 3D mesh. Note that while "%" is used here to denote comments, SU2 does not officially recognize it as such. Extra text added to the mesh file between sections (such as lines following a "%") will simply be ignored. - -To specify the point list, SU2 first searches for the string `NPOIN=` and stores the total number of nodes in the mesh. This value is given first, as it is used to set up a loop over all of the grid points that must immediately follow this line. Then, the coordinates for each of the nodes are given. This is specified in the .su2 format as: - -``` -NPOIN= 9 -0.00000000000000 0.00000000000000 -0.50000000000000 0.00000000000000 -1.00000000000000 0.00000000000000 -0.00000000000000 0.50000000000000 -0.50000000000000 0.50000000000000 -1.00000000000000 0.50000000000000 -0.00000000000000 1.00000000000000 -0.50000000000000 1.00000000000000 -1.00000000000000 1.00000000000000 -``` - -In this case, there are 9 nodes in the 3x3 square above. Immediately after the node number specification comes the list of node coordinates in cartesian space. Each line gives the coordinates for a single grid vertex. The grid points are assigned a global element index of 0 through 8 in the order they appear in the file. This global element index is implied by the ordering and does not need to be explicitly specified by the file, although some legacy meshes may still contain an explicit index at the end of the line that can be ignored. - -For a 2D mesh, only x and y coordinates are required, but a 3D mesh would give x, y, and z coordinates. Note that the global index values for the nodes and elements stored within SU2 are zero-based, as opposed to starting from 1 as Tecplot does. The location of each node in the list can be confirmed in space by adding 1 to the implied global index from the ordering and comparing with the figure above. - -The next part of the file describes the interior element connectivity, which begins with the `NELEM=` keyword: - -``` -NELEM= 8 -5 0 1 3 -5 1 4 3 -5 1 2 4 -5 2 5 4 -5 3 4 6 -5 4 7 6 -5 4 5 7 -5 5 8 7 -``` - -SU2 is based on unstructured mesh technology, and thus supports several element types for both 2D and 3D elements. Unlike for structured meshes where a logical, ordered indexing can be assumed for neighboring nodes and their corresponding cells (quadrilaterals in 2D and hexahedral elements in 3D), for an unstructured mesh, a list of nodes that make up each element, or the connectivity as it is often called, must be provided. First, SU2 will search for the string `NELEM=` and then store the number of interior elements. This value is given first, as it is used to set up a loop over all of the elements which must immediately follow this line. For the square mesh above, this corresponds to the 8 triangular interior elements that are assigned a global element index of 0 through 7 in the order they appear in the file. This global element index is implied by the ordering and does not need to be explicitly specified by the file, although some legacy meshes may still contain an explicit index at the end of the line that can be ignored. - -Each following line describes the connectivity of a single element. The first integer on each line is a unique identifier for the type of element that is described. SU2 supports line, triangle, quadrilateral, tetrahedral, pyramid, prism, and hexahedral elements. The identifiers follow the VTK format: - - -|Element Type | Identifier | ---------------|------------| -|Line | 3| -|Triangle |5| -|Quadrilateral |9| -|Tetrahedral |10| -|Hexahedral |12| -|Prism |13| -|Pyramid |14| - -In our square mesh, all elements are triangles, and thus the identifier (first integer) on all lines is 5. Following the identifier is a list of the node indices that make up the element. Each triangular element will have 3 nodes specified, a rectangular element would have 4 nodes specified, a tetrahedral element would have 4 nodes specified, and so on. Note again that the global index values for the nodes and elements stored within SU2 are zero-based, as opposed to starting from 1 as Tecplot does, which was used to create the mesh image. For example, take the triangular element described in the first line, which would be indexed as 0 in SU2 (1 in Tecplot). The SU2 nodes are given as (0,1,3) which would correspond to (1,2,4) in Tecplot. Looking at the figure of the mesh above, we see that this is the lower left triangular element. The ordering of the nodes given in the connectivity list for a specific element is important, and the user is referred to the VTK format guide for the correct ordering for each supported element type (page 9). - -The final component of the mesh is a description of all boundaries (which we call markers), including a name (what we call a tag). For each boundary, the connectivity information is specified using the same node global index values given above. For a 2D mesh, only line elements are supported along the boundaries. For a 3D mesh, triangular and quadrilateral elements are the possible options for boundary elements. This section of the .su2 mesh file appears as: - -``` -NMARK= 4 -MARKER_TAG= lower -MARKER_ELEMS= 2 -3 0 1 -3 1 2 -MARKER_TAG= right -MARKER_ELEMS= 2 -3 2 5 -3 5 8 -MARKER_TAG= upper -MARKER_ELEMS= 2 -3 8 7 -3 7 6 -MARKER_TAG= left -MARKER_ELEMS= 2 -3 6 3 -3 3 0 -``` - -First, the number of boundaries, or markers, is specified using the "NMARK=" string. Then for each marker, a name, or tag, is specified using "MARKER_TAG=." This tag can be any string name, and the tag name is used in the configuration file for the solver when specifying boundary conditions. Here, the tags "lower," "right," "upper," and "left" would be used. The number of elements on each marker, using "MARKER_ELEMS=," must then be specified before listing the connectivity information as is done for the interior mesh elements at the start of the file. Again, the unique VTK identifier is given at the start of each line followed by the node list for that element. For our example, only line elements (identifier 3) exist along the markers, and on each boundary of the square there are 2 edges of a triangle that make up the marker. These elements can again be verified with the mesh figure above. - -### Examples - Attached here is the simple square mesh from above in .su2 format, along with codes for creating this file in the Python, C++, and Fortran 90 programming languages. These scripts are meant to be examples of how to write .su2 meshes in a few common languages which can be easily modified for creating new meshes: - -- Square mesh: [square.su2](../../docs_files/square.su2) -- Python square mesh generator: [square.py](../../docs_files/square.py) -- C++ square mesh generator: [square.cpp](../../docs_files/square.cpp) -- Fortran 90 square mesh generator: [square.f90](../../docs_files/square.f90) - -## CGNS Format - -To make creating your own meshes easier and more accessible, support for the open CGNS data standard has been included within SU2. The main advantage gained is that complex meshes created in a third-party software package (one that supports unstructured, single-zone CGNS file export) can be used directly within SU2 without the need for conversion to the native format. Moreover, as CGNS is a binary format, the size of the mesh files can be significantly reduced. If needed, a converter from CGNS to the SU2 format has been built into SU2 (See the [inviscid wedge tutorial](../../tutorials/Inviscid_Wedge)). - -### Compiling with CGNS Support - -Starting with SU2 v4.3, the source for version 3.3.0 of the CGNS library is shipped with SU2 in the externals/ directory, and it is automatically built and linked for you when compiling SU2 (ADF support only). - -### Using and Converting CGNS Meshes - -In order to use a CGNS mesh (assuming the CGNS library has been installed and SU2 successfully compiled), the user simply needs to specify the input mesh format to be "CGNS" in the configuration file for their simulation. The configuration file option is "MESH_FORMAT=" and appears as: - -``` -MESH_FORMAT= CGNS -``` - -It is important to note that SU2 will not use any specific boundary conditions that are embedded within the CGNS mesh. However, it *will* use the names given to each boundary as the marker tags. These marker tags are used to set the boundary conditions in the configuration file. Therefore, it is recommended that the user give names to each boundary in their mesh generation package before exporting to CGNS. If you do not know the number of markers or their tags within a CGNS file, you can simply attempt a simulation in SU2_CFD (leaving out the boundary information in the configuration file at first), and during the preprocessing stage, SU2 will read and print the names of all boundary markers to the console along with other grid information before throwing an error due to incomplete boundary definitions. The user can then incorporate these marker tags into the configuration file with the appropriate boundary conditions. - -## Third-Party Mesh Software - -We are continuously working to integrate SU2 with industry-standard tools. We currently have an output plugin for the Pointwise(R) meshing software. This custom addition allows users of Pointwise version 17.00 and later to directly output their meshes in the native SU2 format. The plugin is available natively within recent versions of Pointwise (V17.0R2 or later). - -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. diff --git a/_docs/Parallel-Build.md b/_docs/Parallel-Build.md deleted file mode 100644 index 6918dcd8..00000000 --- a/_docs/Parallel-Build.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -title: Parallel Build -permalink: /docs/Parallel-Build/ ---- - -SU2 uses the GNU automake tools to configure and build the software from source in Linux and Mac OS X environments (or with a terminal emulator on Windows). While a basic version of the code can easily be compiled, we recognize that many users will want to extend capabilities by running calculations on multiple cores and on distributed memory clusters. Luckily, the build process is largely the same, apart from a few new options and dependencies. - -To illustrate an advanced build, let's assume that you would like to build SU2 for running parallel calculations. In short, you will need to make sure some extra software is available and then execute a set of commands like the following: -``` -$ cd /path/to/SU2 -$ ./bootstrap -$ ./configure --prefix=/path/to/install/SU2 CXXFLAGS="-O3" --enable-mpi ---with-cc=/path/to/mpicc --with-cxx=/path/to/mpicxx -$ make -j 8 install -``` - -Let's break this down and discuss the configure process and options in more detail. - -### Bootstrap -Before building, a bootstrap script is included in the SU2/ directory for quickly customizing the autotools structure on your system. Simply run -``` -$ ./bootstrap -``` -in the SU2/ root directory (you may need to adjust your PATH after running this script) to build the appropriate dependencies and reset the makefile structure rather than calling autoreconf on your own. - -### Compiler Flags -You can submit flags to your compiler for building SU2 using the `CXXFLAGS` variable. The most common choices are to impose a level of compiler optimization or perhaps a debug flag with `-g`. For example, a high level of compiler optimization can be set by adding -``` -CXXFLAGS="-O3" -``` -to the `configure` call. - -### Parallel Support -First, to build in parallel, we need to inform the configure process by including the following options: -``` ---enable-mpi --with-cc=/path/to/mpicc --with-cxx=/path/to/mpicxx -``` -These three options enable parallel support and specify the MPI implementation that you would like to use for building. Note here that your machine must have an implementation of the MPI standard installed, i.e., `mpicc` and `mpicxx` must be installed on your system. For example, common MPI flavors used by the development team are Open MPI, MPICH, and Intel MPI. Additionally, mesh partitioning software is needed to decompose the meshes when running in parallel. In order to simplify the build process, the ParMETIS graph partitioning software ships with the SU2 source, and it will be compiled and linked automatically for you when the options above are prescribed. - -The `--prefix` option defines the location that the executables will be installed. They will be placed in a folder named bin/ within your chosen install location from --prefix. If the `--prefix` option is not specified, the code will be installed in `/usr/local/bin`, which may require admin access. Note that we are also using the "-j N" option of the make command in order to compile SU2 in parallel using N cores. This can greatly reduce the compilation time if building on a multicore laptop, workstation, or cluster head node. While not required, here we are combining the `make` and `install` commands into one. - -Make sure to note the **SU2_RUN** and **SU2_HOME** environment variables displayed at the conclusion of configure. It is recommended that you add the **SU2_RUN** and **SU2_HOME** variables to your ~/.bashrc file and update your PATH variable to include the install location ($SU2_RUN, specified by `--prefix`). diff --git a/_docs/Post-processing.md b/_docs/Post-processing.md deleted file mode 100644 index ee9713d5..00000000 --- a/_docs/Post-processing.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Post-processing -permalink: /docs/Post-processing/ ---- - -SU2 is capable of outputting solution files and other result files that can be visualized in a number of formats, including ParaView (.vtk), Tecplot (.dat for ASCII, .plt for binary), CGNS (.cgns), comma-separated values (.csv), or STL (.stl) depending on the problem. - -At the end of each simulation (or at a a frequency specified by the user), SU2 will output several files that contain all of the necessary information for post-processing of results, visualization, and a restart. **Note that when the code is compiled and running in parallel, only restart files will be generated during runtime to avoid overheads.** The restart files can then be used as input to generate the visualization files using SU2_SOL. This will be done automatically if the parallel_computation.py script is used, but it can also be done manually at any time by calling SU2_SOL. In fact, this offers additional flexibility, as solution files in multiple formats can always be generated/regenerated as long as the original mesh and a restart file are available. SU2_SOL can be called from the command line like any of the other modules, in serial or parallel. - -For a PDE analysis (direct solution), these files might look like the following: -- **flow.dat** or **flow.vtk**: full volume flow solution. -- **surface_flow.dat** or **surface_flow.vtk**: flow solution along the surface of the geometry. -- **surface_flow.csv**: comma-separated values (.csv) file containing values along the surface of the geometry. -- **history.dat** or **history.csv**: file containing the convergence history information. -- **restart_flow.dat**: restart file in an internal format for restarting simulations in SU2. Contains the flow solution at each node (description below). - -For adjoint solutions, the file names are slightly different and depend on the particular objective chosen: -- **adjoint.dat** or **adjoint.vtk**: full volume adjoint solution. -- **surface_adjoint.dat** or **surface_adjoint.vtk**: adjoint solution along the surface of the geometry. -- **surface_adjoint.csv**: comma-separated values (.csv) file containing values along the surface of the geometry. -- **history.dat** or **history.csv**: file containing the convergence history information. -- **restart_adj_cd.dat**: readable restart file in an internal format for restarting this simulation in SU2. Note that the name of the objective appears in the file name. In this example, it is the coefficient of drag. diff --git a/_docs/Python-Wrapper-Build.md b/_docs/Python-Wrapper-Build.md deleted file mode 100644 index be309b3d..00000000 --- a/_docs/Python-Wrapper-Build.md +++ /dev/null @@ -1,46 +0,0 @@ ---- -title: Python Wrapper Build -permalink: /docs/Python-Wrapper-Build/ ---- - -It is recommended to read the information at [Build from Source](/docs/Build-from-Source/) first prior reading this section. - -In order to use the Python Wrapper of SU2, an additional compilation step is required. The wrapper is based on the CDriver structure of SU2 and the compilation is performed with [Swig](http://www.swig.org/) that is required to be installed on your system. For a parallel build, Python bindings for MPI are also required. We recommend to use [mpi4py](https://pythonhosted.org/mpi4py/usrman/). You will find a few notes that will help you install the required packages at the end of this tutorial. - -## Configuration with the Python wrapper -The Py wrapper build configuration is still based on the `configure` script but has to be enabled by adding the option `--enable-PY_WRAPPER`. - -### Example for Linux -To configure a parallel build in a specified location with the Python wrapper, the command should be: - - $ ./configure --prefix=/path/to/install/SU2 CXXFLAGS="-O3" --enable-mpi - --with-cc=/path/to/mpicc --with-cxx=/path/to/mpicxx --enable-PY_WRAPPER - -followed by the classical `make -j N` and `make install` commands. - -This will first compile the SU2 code, and all the required libraries from `./externals`, to generate the executables (SU2_CFD, SU2_SOL, SU2_DEF, ...). Then it will wrap the CDriver structure in order to create the Python module `pysu2.py` that is linked to the library `_pysu2.so` (also coming from the wrapper compilation). The `pysu2` module can be imported in a Python script so that any SU2 driver (general, fluid, ...) can be instantiated and used as a classical Py object. - -Make sure to note the **SU2_RUN** and **SU2_HOME** environment variables displayed at the conclusion of configure. It is recommended that you add the SU2_RUN and SU2_HOME variables to your ~/.bashrc file and update your PATH and PYTHONPATH variables to include the install location ($SU2_RUN, specified by --prefix). - -### Note : How to install Swig and mpi4py -On **Linux**, Swig can be easily installed with the APT: - - $ sudo apt-get install swig - -If you have a working distribution of MPI on your system, mpi4py can be installed with Python pip: - - $ sudo apt-get install python-pip - $ sudo pip install mpi4py - -On **Mac OS X**, you can use the [Homebrew](http://brew.sh/) package manager. Once it is installed on your system, you can install Swig by running: - - $ sudo brew install swig - -Note that you can also use Homebrew to easily install Open MPI on your Mac: - - $ sudo brew install open-mpi - -Install mpi4py with Python pip using easy install: - - $ sudo easy_install pip - $ sudo pip install mpi4py diff --git a/_docs/Quick-Start.md b/_docs/Quick-Start.md deleted file mode 100644 index 556914c9..00000000 --- a/_docs/Quick-Start.md +++ /dev/null @@ -1,123 +0,0 @@ ---- -title: Quick Start -permalink: /docs/Quick-Start/ ---- - -![NACA 0012 Pressure](../../docs_files/naca0012_pressure.png) - -## Introduction - -Welcome to the Quick Start Tutorial for the SU2 software suite. This tutorial is intended to demonstrate some of the key features of the analysis and design tools in an easily accessible format. Completion of this tutorial only requires a few minutes. If you haven't done so already, please visit the [Download](/download.html) and [Installation](/docs_v7/Installation/) pages to obtain the most recent stable release of the software and details for installation. This tutorial requires only the SU2_CFD tool from the SU2 suite. - -## Goals -Upon completing this simple tutorial, the user will be familiar with performing the flow and continuous adjoint simulation of external, inviscid flow around a 2D geometry and be able to plot both the flow solution and the surface sensitivities that result. The specific geometry chosen for the tutorial is the NACA 0012 airfoil. Consequently, the following capabilities of SU2 will be showcased in this tutorial: - -- Steady, 2D, Euler and Continuous Adjoint Euler equations -- Multigrid -- JST numerical scheme for spatial discretization -- Euler implicit time integration -- Euler Wall and Farfield boundary conditions - -## Resources - -The files necessary to run this tutorial are included in the SU2/QuickStart/ directory. For the other tutorials, the files will be found in the TestCases/ repository. Two files are needed as input to the code: a configuration file describing the options for the particular problem, and the corresponding computational mesh file. The files are in QuickStart/ and can also be found in the TestCases repository under TestCases/euler/naca0012. - -## Tutorial - -The following tutorial will walk you through the steps required to compute the flow and adjoint solutions around the NACA 0012 airfoil using SU2. Again, we assume that you have already obtained and compiled the SU2_CFD code (either individually, or as part of the complete SU2 package) for a serial computation. If you have yet to complete this requirement, please see the [Download](/download.html) and [Installation](/docs/Installation) pages. - -### Background - -The NACA0012 airfoil is one of the four-digit wing sections developed by the National Advisory Committee for Aeronautics (NACA), and it is a widely used geometry for many CFD test cases. The numbering system is such that the first number indicates the maximum camber (in percent of chord), the second shows the location of the maximum camber (in tens of percent of chord) and the last two digits indicate the maximum thickness (in percent of chord). More information on these airfoil sections can be found here or in the book 'Theory of Wing Sections' by Abbott and von Doenhoff. - -### Problem Setup - -This problem will solve the Euler equations on the NACA0012 airfoil at an angle of attack of 1.25 degrees, using air with the following freestream conditions: - -- Pressure = 101,325 Pa -- Temperature = 273.15 K -- Mach number = 0.8 - -The aim is to find the flow solution and the adjoint solution with respect to an objective function defined as the drag on the airfoil. - -### Mesh Description - -The unstructured mesh provided is in the native .su2 format. It consists of 10,216 triangular cells, 5,233 points, and two boundaries (or "markers") named *airfoil* and *farfield*. The airfoil surface uses a flow-tangency Euler wall boundary condition, while the farfield uses a standard characteristic-based boundary condition. The figure below gives a view of the mesh. - -![NACA 0012 Mesh](../../docs_files/naca0012_mesh.png) - -Figure (1): Far-field and zoom view of the computational mesh. - -### Configuration File Options - -Aside from the mesh, the only other file required to run the SU2_CFD solver details the configuration options. It defines the problem, including all options for the numerical methods, flow conditions, multigrid, etc., and also specifies the names of the input mesh and output files. In keeping simplicity for this tutorial, only two configuration options will be discussed. More configuration options will be discussed throughout the remaining tutorials. - -Upon opening the inv_NACA0012.cfg file in a text editor, one of the early options is the MATH_PROBLEM: -``` -% Mathematical problem (DIRECT, CONTINUOUS_ADJOINT, DISCRETE_ADJOINT) -MATH_PROBLEM= DIRECT -``` -SU2 is capable of running the direct and adjoint problems for several sets of equations. The direct analysis solves for the flow around the geometry, and quantities of interest such as the lift and drag coefficient on the body will be computed. Solving the adjoint problem leads to an efficient method for obtaining the change in a single objective function (e.g., the drag coefficient) relative to a large number of design variables (surface deformations). The direct and adjoint solutions often couple to provide the objective analysis and gradient information needed by an optimizer when performing aerodynamic shape design. In this tutorial, we will perform DIRECT and CONTINUOUS_ADJOINT solutions for the NACA 0012 airfoil. - -The user can also set the format for the solution files: -``` -% Output file format -OUTPUT_FORMAT= TECPLOT -``` -SU2 can output solution files in the .vtk (ParaView), .dat (Tecplot ASCII), and .plt (Tecplot binary) formats which can be opened in the ParaView and Tecplot visualization software packages, respectively. We have set the file type to TECPLOT in this tutorial by default, but users without access to Tecplot are encouraged to download and use the freely available [ParaView](http://www.paraview.org) package. To output solution files for ParaView, set the OUTPUT_FORMAT option to PARAVIEW. - -### Running SU2 - -The first step in this tutorial is to solve the Euler equations: - 1. Either navigate to the QuickStart/ directory or create a directory in which to run the tutorial. If you have created a new directory, copy the config file (inv_NACA0012.cfg) and the mesh file (mesh_NACA0012_inv.su2) to this directory. - 2. Run the executable by entering "SU2_CFD inv_NACA0012.cfg" at the command line. If you have not set the $SU2_RUN environment variable you will need to run "../bin/SU2_CFD inv_NACA0012.cfg" (from the QuickStart directory) or use the appropriate path to your SU2_CFD executable at the command line. - 3. SU2 will print residual updates with each iteration of the flow solver, and the simulation will finish after reaching the specified convergence criteria. - 4. Files containing the flow results (with "flow" in the file name) will be written upon exiting SU2. The flow solution can be visualized in ParaView (.vtk) or Tecplot (.dat or .plt). More specifically, these files are: - - **flow.dat** or **flow.vtk** - full volume flow solution. - - **surface_flow.dat** or **surface_flow.vtk** - flow solution along the airfoil surface. - - **surface_flow.csv** - comma separated values (.csv) file containing values along the airfoil surface. - - **restart_flow.dat** - restart file in an internal format for restarting this simulation in SU2. - - **history.dat** or **history.csv** - file containing the convergence history information. - -Next, we want to run the adjoint solution to get the sensitivity of the objective function (the drag over the airfoil) to conditions within the flow: - 1. Open the config file and change the parameter MATH_PROBLEM from DIRECT to CONTINUOUS_ADJOINT, and save this file. - 2. Rename the restart file (restart_flow.dat) to "solution_flow.dat" so that the adjoint code has access to the direct flow solution. - 3. Run the executable again by entering "SU2_CFD inv_NACA0012.cfg" at the command line. - 4. SU2 will print residual updates with each iteration of the adjoint solver, and the simulation will finish after reaching the specified convergence criteria. - 5. Files containing the adjoint results (with "adjoint" in the file name) will be written upon exiting SU2. The flow solution can be visualized in ParaView (.vtk) or Tecplot (.dat or .plt). More specifically, these files are: - - **adjoint.dat** or **adjoint.vtk** - full volume adjoint solution. - - **surface_adjoint.dat** or **surface_adjoint.vtk** - adjoint solution along the airfoil surface. - - **surface_adjoint.csv** - comma separated values (.csv) file containing values along the airfoil surface. - - **restart_adj_cd.dat** - restart file in an internal format for restarting this simulation in SU2. Note that the name of the objective appears in the file name. - - **history.dat** or **history.csv** - file containing the convergence history information. - -Note that as of SU2 v4.1, you can also compute a discrete adjoint for the Euler equations. Assuming that you have built the code with [algorithmic differentiation support](/docs/AD-Build), you can run the discrete adjoint with the following steps instead: - 1. Open the config file and change the parameter MATH_PROBLEM from DIRECT to DISCRETE_ADJOINT, and save this file. - 2. Rename the restart file (restart_flow.dat) to "solution_flow.dat" so that the adjoint code has access to the direct flow solution. - 3. Run the executable again by entering "SU2_CFD_AD inv_NACA0012.cfg" at the command line. Note that the SU2_CFD_AD executable will only be available when the source has been compiled with AD support. - -### Results - -The following figures were created in Tecplot using the SU2 results. These results are contained in the flow.dat, surface_flow.dat, adjoint.dat, and surface_adjoint.dat files. - -#### Flow Solution - -![NACA 0012 Pressure](../../docs_files/naca0012_pressure.png) - -Figure (2): Pressure contours around the NACA 0012 airfoil. - -![NACA 0012 Pressure Distribution](../../docs_files/naca0012_cp.png) - -Figure (3): Coefficient of pressure distribution along the airfoil surface. Notice the strong shock on the upper surface (top line) and a weaker shock along the lower surface (bottom line). - -#### Adjoint Solution - -![NACA 0012 Adjoint Density](../../docs_files/naca0012_psirho.png) - -Figure (4): Contours of the adjoint density variable. - -![NACA 0012 Surface Sensitivity](../../docs_files/naca0012_sensitivity.png) - -Figure (5): Surface sensitivities. The surface sensitivity is the change in the objective function due to an infinitesimal deformation of the surface in the local normal direction. These values are calculated at each node on the airfoil surface from the flow and adjoint solutions at negligible computational cost using an additional step not described in this tutorial. - -Congratulations! You've successfully performed your first flow simulations with SU2. Move on to the [tutorials](https://su2code.github.io/tutorials/home) to learn much more about using the code, and don't forget to read through the information in the user's guide. Having problems with the quick start or visualizing the results? Visit the [FAQs](/docs/FAQ) page, or see our forum at [CFD-online](http://www.cfd-online.com/Forums/su2/). diff --git a/_docs/Restart-File.md b/_docs/Restart-File.md deleted file mode 100644 index e3e9951d..00000000 --- a/_docs/Restart-File.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -title: Restart File -permalink: /docs/Restart-File/ ---- -The SU2 solution format has the extension .dat, and the files are (by default) in binary format. - -The restart files are used to restart the code from a previous solution and also to run the adjoint simulations, which require a flow solution as input. In order to run an adjoint simulation, the user must first change the name of the restart_flow.dat file to solution_flow.dat in the execution directory (these default file names can be adjusted in the config file). It is important to note that the adjoint solver will create a different adjoint restart file for each objective function, e.g. restart_adj_cd.dat. - -To restart a simulation the `RESTART_SOL` flag should be set to `YES` in the configuration file. If performing an unsteady restart the `UNST_RESTART_ITER` needs to be set to the iteration number which you want to restart from. For instance if we want to restart at iteration 100 and run the unsteady solver with 2nd-order dual time stepping method, we will need to specify `UNST_RESTART_ITER = 100` and have the restart files solution_flow_00098.dat and solution_flow_00099.dat. - diff --git a/_docs/Running-Regression-Tests.md b/_docs/Running-Regression-Tests.md deleted file mode 100644 index 0e051f52..00000000 --- a/_docs/Running-Regression-Tests.md +++ /dev/null @@ -1,19 +0,0 @@ ---- -title: Running Regression Tests -permalink: /docs/Running-Regression-Tests/ ---- - -The regression tests can be run on your local machine by using the Python scripts available in the SU2/TestCases/ directory and the mesh files from the su2code/TestCases repository. See the [Test Cases](/docs/Test-Cases/) page for more information on working with the TestCases repo. - -When you are ready to combine your modifications into the develop branch, creating a pull request will automatically run these same regression tests on the Travis CI system. Your pull request must pass these tests in order to be merged into the develop branch. In the pull request, you will be able to see the state of the tests, and by clicking on links find the details of the test results. - -If you are working with a forked version of the repository, you can use the following directions to run these same regression tests within your repository rather than within the su2code/ repository. This is preferable if you are not ready to submit your code to the develop branch and just want to run the tests, or if you want to create your own regression tests. - -1. Modify the travis.yml file in the develop branch to update the ***email address*** and ***repository url***. At this point you can also modify which branch will have the tests run. Commit the change to your fork/develop. -2. Sign up for Travis CI and allow access to your account. -3. Activate the repository within Travis CI. -4. Modify the "README" file in the SU2/ directory such that the url points to the results for your fork rather than su2code/SU2. -5. Commit the result into your fork/develop. -6. View the results: when you open up your fork/develop on github the readme file should display. There will be a colored link going to the travis CI build which state whether the test is building, passing, or failing. This link will lead to the details of the tests. Pull requests between your fork/develop and any branches you have created on your fork will also run regression tests. - -If the tests do not run at first, double check that the repository is activated within Travis CI, and if so push a commit with some small change to the travis.yml file to your repository. If it still doesn't work, double check your urls and refer to Travis CI help menu. diff --git a/_docs/Simple-Build.md b/_docs/Simple-Build.md deleted file mode 100644 index 88db2bec..00000000 --- a/_docs/Simple-Build.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -title: Simple Build -permalink: /docs/Simple-Build/ ---- - -SU2 uses the GNU automake tools to configure and build the software from source in Linux and Mac OS X environments (or with a terminal emulator on Windows). In keeping with our philosophy of simplifying the install process, a vanilla version of the code can be quickly installed without any dependencies. To compile the most basic version of SU2 (single-threaded with no optional features), execute the following commands in a terminal after extracting the source code: -``` -$ cd /path/to/your/SU2/ -$ ./bootstrap -$ ./configure --prefix=/path/to/install/SU2 -$ make -$ make install -``` -First, the bootstrap script is included in the SU2/ directory for quickly customizing the autotools structure on your system. - -The `--prefix` option defines the location that the executables will be installed (in a folder named bin/ within your chosen install location from --prefix). If the `--prefix` option is not specified, the code will be installed in `/usr/local/bin`, which may require admin access. You can also use the "-j N" option of the make command in order to compile SU2 in parallel using N cores, i.e., run -``` -make -j 8 install -``` -to compile using 8 cores. This can greatly reduce the compilation time if building on a multicore laptop, workstation, or cluster head node. - -Make sure to note the **SU2_RUN** and **SU2_HOME** environment variables displayed at the conclusion of configure. It is recommended that you add the **SU2_RUN** and **SU2_HOME** variables to your ~/.bashrc file and update your PATH variable to include the install location ($SU2_RUN, specified by `--prefix`). diff --git a/_docs/Software-Components.md b/_docs/Software-Components.md deleted file mode 100644 index 93e83f4f..00000000 --- a/_docs/Software-Components.md +++ /dev/null @@ -1,40 +0,0 @@ ---- -title: Software Components -permalink: /docs/Software-Components/ ---- - -The SU2 software suite is composed of a set of C++ based software modules that perform a wide range of CFD analysis and PDE-constrained optimization tasks. An overall description of each module is included below to give perspective on the suite's capabilities, while more details can be found in the Developer's Guide. Some modules can be executed individually, most notably SU2_CFD to perform high-fidelity analysis, but the real power of the suite lies in the coupling of the modules to perform complex activities, including design optimization and adaptive grid refinement, among others. - -A key feature of the C++ modules is that each has been designed to separate functionality as much as possible and to leverage the advantages of the class-inheritance structure of the programming language. This makes SU2 an ideal platform for prototyping new numerical methods, discretization schemes, governing equation sets, mesh perturbation algorithms, adaptive mesh refinement schemes, parallelization schemes, etc. You simply need to define a new subclass and get down to business. This philosophy makes SU2 quickly extensible to a wide variety of PDE analyses suited to the needs of the user, and work is ongoing to incorporate additional features for future SU2 releases. -The key C++ and Python tools in the SU2 software suite are briefly described below for the current release, but note that modules may be added and removed with future development. - -## 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_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_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. - -### Algorithmic Differentiation Support and Discrete Adjoint - -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_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 - -The various software modules of SU2 can be coupled together to perform complex analysis and design tasks using supplied Python scripts. A brief description of the scripts included in the current release of the software is provided below. - -- **High-fidelity analysis scripts**. These scripts have been designed to enhance the flexibility of the SU2 framework. More specifically, they simplify the execution of parallel tasks, grid adaptation, or interfacing with other software. - - **parallel_computation.py**: Handles the setup and execution of parallel CFD jobs on multi-core or cluster computing architectures. The script executes SU2_CFD in parallel and after the computation is completed runs SU2_SOL to provide a solution ready to be opened by a post-processing software of your choosing. - - **mesh_deformation.py**: Handles the setup and execution of parallel mesh deformation jobs on multi-core or cluster computing architectures. The script executes SU2_DEF in parallel. -- **Optimal shape design scripts**. These scripts have been designed to automate the optimal shape design process that includes functional and gradient computation, mesh deformation, and an optimization algorithm. - - **continuous_adjoint.py**: Automatically computes the sensitivities of a specified functional with respect to design parameter perturbations (specified in the SU2_CFD configuration file) using the continuous adjoint method. The SU2_CFD and SU2_DOT modules are called to perform the analysis. - - **discrete_adjoint.py**: Automatically computes the sensitivities of a specified functional with respect to design parameter perturbations (specified in the SU2_CFD configuration file) using the discrete adjoint method. The SU2_CFD_AD and SU2_DOT_AD modules are called to perform the analysis. - - **finite_differences.py**: Automatically computes the sensitivities of a specified functional with respect to design parameter perturbations using a finite difference method. As with the continuous_adjoint.py script, design variable information is read from the configuration file and SU2_CFD is called repeatedly to calculate the appropriate gradient elements. - - **shape_optimization.py**: Orchestrates all SU2 modules to perform shape optimization. The choice of objective function, design variables and additional module settings specifying the optimization problem are controlled through options in the configuration file. diff --git a/_docs/Style-Guide.md b/_docs/Style-Guide.md deleted file mode 100644 index 9ac10074..00000000 --- a/_docs/Style-Guide.md +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: Style Guide -permalink: /docs/Style-Guide/ ---- - -SU2 is released under an open source license to facilitate its widespread use and development in the scientific computing community. To support uniformity and consistency in the style of the source code, a C++ style guide has been included on this page, and it is strongly encouraged that outside developers adhere to the guidelines dictated in the style guide to maintain readability of the source. - -Any contributions from the scientific community at-large are encouraged and welcomed. Feel free to contact the development team at any time. - -This document describes the conventions that will be used when implementing new features in SU2. This includes allowed syntactic and semantic language features, filename conventions, indentation conventions and more. The consistency is fundamental, it is very important that any programmer be able to look at another part of the code and quickly understand it, the uniformity in the style is a key issue. Some of the ideas expressed in this document comes from the Google C++ Style Guide (revision 3.188). - -## C++ style guide - -### Version numbering - -Each code of the SU2 suite must have a release number following the rule Major.Patch, where the Major number is increased each time a new major update is performed and the Patch number is increased each time new features are added. The configuration file also has a number following the rule Major.Patch, where Major correspond with the SU2_CFD major version and Patch is increased with new changes. - -### Standard conformance, and formatting - -Source code must comply with the C++ ISO/ANSI standard. with respect to the formatting some recommendation can be made: -- Each line of text in your code should be at most 80 characters long. -- Non-ASCII characters should be rare, and must use UTF-8 formatting. -- Use only spaces (default indent is 2 spaces). You can set your editor to emit spaces when you hit the tab key. -- Sections in public, protected and private order, each indented one space. -- The hash mark that starts a preprocessor directive should always be at the beginning of the line. -- When you have a boolean expression that is longer than the standard line length, be consistent in how you break up the lines. - -### Files, functions, and variables - -Here some basic recommendation are made for creating files, functions, and variables: -- C++ filenames must have extension .cpp. -- C++ header filenames must have extension .hpp. In general, every .cpp file should have an associated .hpp file. -- C++ inline filenames must have extension .inl. Define functions inline only when they are small, say, 10 lines or less. -- All subprograms (subroutines of functions) must be contained in a class. Each parent class must be contained in a file with the same name as the class (plus extension ’.cpp’, and ’.hpp’). This implies that there can only be one parent class per file. -- When defining a function, parameter order is: inputs, then outputs. -- Order of includes. Use standard order for readability and to avoid hidden dependencies: C library, C++ library, other libraries', your project's. -- Prefer small and focused functions. -- Use overloaded functions (including constructors) only if a reader looking at a call site can get a good idea of what is happening without having to first figure out exactly which overload is being called. -- Local variables. Place a function's variables in the narrowest scope possible, and initialize variables in the declaration. -- Static or global variables of class type are forbidden: they cause hard-to-find bugs due to indeterminate order of construction and destruction. -- In the initialization, use 0 for integers, 0.0 for reals, NULL for pointers, and '\0' for chars. - -### Classes - -The classes are the key element of the object oriented programming, here some basic rules are specified. -In general, constructors should merely set member variables to their initial values. Any complex initialization should go in an explicit Init() method. -- You must define a default constructor, and destructor. -- Use the C++ keyword explicit for constructors with one argument. -- Use a struct only for passive objects that carry data; everything else is a class. -- Do not overload operators except in rare, special circumstances. -- Use the specified order of declarations within a class: public: before private:, methods before data members (variables), etc. - -### Syntactic and semantic requirements - -In this section you can find some basic rules for programming: -- All allocated memory must be deallocated at program termination. -- Read or write operations outside an allocated memory block are not allowed. -- Read or write outside index bounds in arrays or character variables are not allowed. -- No uninitialized/undefined values may be used in a way that could affect the execution. -- Local variables that are not used must be removed. -- Pointer variables must be initialized with NULL unless they are obviously initialized in some other way before they are used. -- Indentation will be two steps for each nested block-level. -- In the header file, at the beginning of each program unit (class, subroutine or function) there must be a comment header describing the purpose of this code. The doxygen format should be used. -- When possible, it is better to use #DEFINE with a physical meaning to simplify the code. -- The code must be compiled using doxygen to be sure that there is no warning in the commenting format. -- When describing a function the following tag must be used: \brie_, \para_\[in\], \para_\[out\], \retur_, \overload. -- Static or global variables of class type are forbidden: they cause hard-to-find bugs due to indeterminate order of construction and destructionUse 0 for integers, 0.0 for reals, NULL for pointers, and '\0' for chars. -- All parameters passed by reference must be labeled const. We strongly recommend that you use const whenever it makes sense to do so. -- In the code short, int, and the unsigned version of both must be used case depending. -- Code should be 64-bit and 32-bit friendly. Bear in mind problems of printing, comparisons, and structure alignment - -### Naming - -The most important consistency rules are those that govern naming. The style of a name immediately informs us what sort of thing the named entity is: a type, a variable, a function, a constant, a macro, etc., without requiring us to search for the declaration of that entity. - -The following naming conventions for variables must be used: -- Geometry: Normal, Area (2D, and 3D), Volume (2D, and 3D), Coord, Position. Solution: Solution, Residual, Jacobian. -- Function names, variable names, and filenames should be descriptive; eschew abbreviation. Types and variables should be nouns, while functions should be "command" verbs. -- Elementary functions that set or get the value of a variable (e.g. Number) must be called as GetNumber(), or GetNumber(). Function names start with a capital letter and have a capital letter for each new word, with no underscores. -- Variable names are all lowercase, with underscores between words. -- The name for all the classes must start with the capital "C" letter, followed by the name of the class (capitalizing the first letter), if the name is composed by several words, all the words must be together, e.g.: CPrimalGrid. -- All the variables that are defined in a class must be commented using /\*< \brief \________.\*/. - -### Comments - -The documentation, and comments must be Doxygen friendly, here I include some basic features: -- Start each file with a copyright notice, followed by a description of the contents of the file. -- Every class definition should have an accompanying comment that describes what it is for and how it should be used. -- Declaration comments describe use of the function; comments at the definition of a function describe operation. -- In general the actual name of the variable should be descriptive enough to give a good idea of what the variable is used for. -- In your implementation you should have comments in tricky, non-obvious, interesting, or important parts of your code. -- Pay attention to punctuation, spelling, and grammar; it is easier to read well-written comments than badly written ones. -- Short, and long comments must be in inside of /\*--- (your comment here) ---\*/, and they must be located just before the line to be commented. -- Math comments are welcome and should be in the Latex language. - -### Debugger tools - -- The C++ code must support the following features for debugging: -- Array index bounds may be checked at runtime. -- Conformance with C++ may be checked. -- Use of obsolescent features may be reported as compilation warnings. -- Unused variables may be reported as compilation warnings. -- Iteration: iPoint, jPoint, kPoint, iNode, jNode, kNode, iElem, jElem, kElem, iDim, iVar, iMesh, iEdge. diff --git a/_docs/Test-Cases.md b/_docs/Test-Cases.md deleted file mode 100644 index 4f449ccf..00000000 --- a/_docs/Test-Cases.md +++ /dev/null @@ -1,24 +0,0 @@ ---- -title: Test Cases -permalink: /docs/Test-Cases/ ---- - -If you would like to experiment with some available cases, be sure to check out the suite of test cases that are available to you, as described below. - -**Note:** While many of the cases are used for regression testing, the test case suite is provided **without any guarantees on performance or expected results**. Tutorials (which are more thoroughly checked for convergence and results) can be found [here](/tutorials/home/). - -The test cases have been structured to separate the config files (found in the SU2 repo in SU2/TestCases/), which need to remain under version control, from the mesh/solution data (remain in a separate TestCases repo). The idea is that developers will update their config files along with their code changes in the SU2 repo so that pull requests can be automatically checked with Travis CI. The meshes and solution data, which change much less frequently and are larger files, remain in the TestCases repo. - -The two repositories contain the same directory structure for the test cases, with complementary (**not overlapping**) file sets. The responsibility is on the developer to add files to both repositories in matching directory locations when adding new test cases. This makes it very easy for one to recombine the full set of files or for Travis CI to do this automatically. To run the regression tests locally, one might do the following, assuming paths are set correctly such that SU2_CFD is available: -``` -$ git clone https://github.com/su2code/SU2.git -$ git clone https://github.com/su2code/TestCases.git -$ cd SU2/ -$ ./configure -$ make install -$ cp -R ../TestCases/* ./TestCases/ -$ cd ./TestCases/ -$ python serial_regression.py -``` - -Note that there are a number of test cases included in the suite that are not covered within the regressions. After completing the copy step in the process above, one will have all of the necessary config and mesh files within the appropriate locations for running the test cases individually instead of through the regression script. If you would like to view the separate test cases repository with the mesh/solution data, you can find it within a dedicated repo on [GitHub](https://github.com/su2code/TestCases). diff --git a/_docs/Windows-Demo.md b/_docs/Windows-Demo.md deleted file mode 100644 index 878f347b..00000000 --- a/_docs/Windows-Demo.md +++ /dev/null @@ -1,34 +0,0 @@ ---- -title: Windows Demo -permalink: /docs/Windows-Demo/ ---- - -This tutorial is intended to demonstrate 1) How to set up system variable, 2) How to run SU2 on Windows. - -## Set up system variable -1. Click Windows key -![System Variable Figure 1](../../docs_files/windows_system_variable_01.png) -2. Type "environ" in the search/run box of the start menu, select "edit the system environment variables" -![System Variable Figure 2](../../docs_files/windows_system_variable_02.png) -3. Click "Environment Variables..." -![System Variable Figure 3](../../docs_files/windows_system_variable_03.png) -4. Click "Path" system variable and then click "Edit" (or select "New" if "Path" system variable doesn't exist) -![System Variable Figure 4](../../docs_files/windows_system_variable_04.png) -![System Variable Figure 5](../../docs_files/windows_system_variable_05.png) -05. You need to add path to SU2 exectuables. In this example, we add C:\SU2 in the Path variable. If you didn't use the default values from the installer, you should add the path where your executables exist ex) "C:\Program Files (x86)\SU2" -![System Variable Figure 6](../../docs_files/windows_system_variable_06.png) -06. Don't forget to click "OK" -![System Variable Figure 7](../../docs_files/windows_system_variable_07.png) - -## Running SU2 on Windows -1. Click Windows key -![Windows Quickstart Figure 1](../../docs_files/windows_quick_start_01.png) -2. Type "cmd" in the search/run box of the start menu, select "Command Prompt" -![Windows Quickstart Figure 2](../../docs_files/windows_quick_start_02.png) -3. Move to the directory containing the config file and the mesh file -![Windows Quickstart Figure 3](../../docs_files/windows_quick_start_03.png) -4. Run the executable by entering "SU2_CFD inv_channel.cfg" at the command line. **If you didn't add the path to SU2 executables in system variable "Path", this command won't work** -![Windows Quickstart Figure 4](../../docs_files/windows_quick_start_04.png) -5. SU2 will print residual updates with each iteration of the flow solver, and the simulation will finish after reaching the specified convergence criteria -![Windows Quickstart Figure 6](../../docs_files/windows_quick_start_06.png) -6. Files containing the results will be written upon exiting SU2. The flow solution can be visualized in ParaView (.vtk) or Tecplot (.dat for ASCII). To visualize the flow solution in ParaView update the OUTPUT_FORMAT setting in the configuration file diff --git a/_docs/Windows-Installation.md b/_docs/Windows-Installation.md deleted file mode 100644 index 3c01e653..00000000 --- a/_docs/Windows-Installation.md +++ /dev/null @@ -1,25 +0,0 @@ ---- -title: Windows Installation -permalink: /docs/Windows-Installation/ ---- - -As of release 4.1.1, SU2 supports Windows platforms from Windows 7 through Windows 10 in (x86) 32-bit and (x64) 64-bit architectures (see details and limitations below). Please note that the executables have been built to support any version of Windows but have only been tested on Windows 7 and Windows 10, x64 platform. The x86 versions are available for legacy support but are limited to smaller problems due to the 2 GB memory limit in x86 systems; a 64-bit architecture is recommended. Windows binaries are packaged as an Archive (.zip). If you encounter a problem installing or running in Windows please contact the support team for assistance. - -This version is built with CGNS 3.3.0 but no Tecplot binary support (Tecplot text format output is always available). - -## Installation - -1. **Download and unpack the archive**. Download the .zip for your operating system (Windows 7 or Windows 10) and unzip it where you want it to be installed. - -2. **Add SU2 environment variables**. This is done through the Environment Variables control panel. You can access these by typing "environ" in the search/run box of the start menu. Start a New System variable. Assign the Variable Name "SU2_RUN", and assign the Variable Value to be the path to your SU2 Executables (the folder that contains SU2_CFD.exe for example). If you used the default values from the installer, this could be "C:\SU2\". This variable will allow you to quickly navigate to the SU2 directory using "cd %SU2_RUN%", and run the executables using "%SU2_RUN%\" if SU2\ has not been added to the system path. - -*NOTE*: if the directory name contains white space, the executables may not work without appending ".exe", and the python scripts may not work. Additionally, when setting the enviornment variables and paths, quotes must be added, for example: "C:\Program Files\"Stanford ADL"\SU2\" - -3. **Add SU2 to the system path**. Access the system variables by typing "environ" in the search/run box of the start menu, select "edit the system environment variables", and then select "Environment Variables" from the System Properties menu. Edit the "Path" system variable (or select "New" if no "Path" system variable exists) and add the path to the SU2 executables. When there is more than one directory listed in "Path" they must be separated by semicolons. This will allow you to use the executables from any directory without explicitly specifying the path to the executable. - -4. **Optional: Install Microsoft MPI to enable parallel mode**. As the well-known, freely-available, open-source implementations of MPI listed in the Install section may not support Windows, you may want to install Microsoft MPI. - -## Running SU2 in Windows - -Running SU2 in Windows is identical to running in Linux or Mac OS environments and is run from the command line (whether cmd.exe or the freely-available Console2 for Windows). If your executable path contains white space you may need to add ".exe" . - diff --git a/_docs/contribute.md b/_docs/contribute.md deleted file mode 100644 index 9d16b435..00000000 --- a/_docs/contribute.md +++ /dev/null @@ -1,33 +0,0 @@ ---- -title: Contribute -permalink: /docs/contribute/ ---- - -Do you want to contribute to the SU2 documentation? It's easy! Just create a fork of the [SU2 Project Website repository](https://github.com/su2code/su2code.github.io), write your documentation, and open a pull request. - -## Writing content - -The documentation in this site is stored under the `_docs` folder. To add your contributions: - -**1.** Add a new Markdown file inside the subfolder, as `_docs/Your_Documentation.md`. Add the following [front matter](https://jekyllrb.com/docs/frontmatter/) to your file: - -``` ---- -title: Your Documentation Page -permalink: /docs/Your_Documentation/ ---- - -I'm contributing to SU2! Don't forget the trailing '/' on the permalink! -``` - -**2.** Add the documentation pagename to the `_data/docs.yml` file, in order to list it in the navigation panel (create a new subgroup if necessary): - -``` -- title: Your Subgroup of Documentation - docs: - - Your_Documentation -``` - -**3.** If you have supporting images or other auxiliary files, please add them to the folder `docs_files` in the root directory of the repository. Don't forget to add the correct relative links to these files in your docs, if necessary. - -**4.** When you are ready, submit a pull request to the **develop** branch of the [repository](https://github.com/su2code/su2code.github.io)... and it's all done! Thanks for your contribution! diff --git a/_docs/index.md b/_docs/index.md deleted file mode 100644 index 646d95bc..00000000 --- a/_docs/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -title: SU2, Multiphysics Simulation and Design Software -permalink: /docs/home/ -redirect_from: /docs/index.html ---- - -![SU2 Logo](../../img/logos/logoSU2.jpg) - -The SU2 suite is an open-source collection of C++ based software tools for performing Partial Differential Equation (PDE) analysis and solving PDE-constrained optimization problems. The toolset is designed with Computational Fluid Dynamics (CFD) and aerodynamic shape optimization in mind, but is extensible to treat arbitrary sets of governing equations such as potential flow, elasticity, electrodynamics, chemically-reacting flows, and many others. SU2 is under active development by individuals all around the world on [GitHub](https://github.com/su2code/SU2) and is released under an open-source license. - -For a detailed description of the code philosophy, components, and implementations, please see our [SU2 AIAA Journal article](http://arc.aiaa.org/doi/abs/10.2514/1.J053813). diff --git a/_docs_v7/Installation.md b/_docs_v7/Installation.md index f98309b8..0c19fb7a 100644 --- a/_docs_v7/Installation.md +++ b/_docs_v7/Installation.md @@ -74,3 +74,45 @@ Each of the C++ modules for SU2 can be called directly from the command line and - SciPy Alternatively, Python and these packages can be found in prebuilt installations, such as the Anaconda Distribution, or from package managers like Homebrew for Mac OS X. + +## Windows Installation + +### ⚠️ Important Note for Windows Users + +**We strongly recommend using Windows Subsystem for Linux (WSL)** for building and running SU2 on Windows. Native Windows builds have known limitations with MPI support and may encounter linking errors (see issue [#1468](https://github.com/su2code/SU2/issues/1468)). + +### Option 1: WSL Installation (Recommended) ✅ + +Windows Subsystem for Linux provides a native Linux environment on Windows and is the most reliable way to build SU2. + +#### Install WSL + +1. Open PowerShell as Administrator and run: +```powershell + wsl --install +``` + +2. Restart your computer when prompted + +3. Open Ubuntu from the Start menu (installed automatically) + +4. Follow these commands in the Ubuntu terminal: +```bash + sudo apt update && sudo apt upgrade + sudo apt install git cmake g++ python3 libopenmpi-dev + git clone https://github.com/su2code/SU2.git + cd SU2 + ./meson.py build + ./ninja -C build install +``` + +#### Advantages of WSL +- ✅ Native MPI support (no linking errors) +- ✅ Better performance than traditional VMs +- ✅ Seamless file system integration with Windows +- ✅ Same commands as Linux installation + +### Option 2: Native Windows Build (Advanced Users Only) ⚠️ + +Native Windows builds have known MPI linking issues ([#1468](https://github.com/su2code/SU2/issues/1468)). We strongly recommend WSL instead. + diff --git a/develop.html b/develop.html index 458079f2..4b175feb 100644 --- a/develop.html +++ b/develop.html @@ -35,7 +35,7 @@

Git-ting Started


-

You can check out all of the development activity, and new developers are encouraged to log feature requests, questions, and bug reports through the GitHub issue tracker. Developers can have their code contributions integrated through GitHub as well. For more information, look at the SU2 wiki on GitHub.

+

You can check out all of the development activity, and new developers are encouraged to log feature requests, questions, and bug reports through the GitHub issue tracker. Developers can have their code contributions integrated through GitHub as well. For more information, look at the SU2 wiki on GitHub.