More updates for v7.

Author: economon

_docs_v7/Developing-SU2-on-GitHub-(Internal-Developers).md

@@ -3,7 +3,7 @@ title: Developing SU2 on GitHub (Internal Developers)
 permalink: /docs_v7/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. 
+The repository for SU2 is being hosted 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
 ```
@@ -12,7 +12,7 @@ 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.
+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 development 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 are constantly reviewing 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:
 ```
@@ -29,7 +29,9 @@ Now that you have a local copy of SU2 from the GitHub repository, you can begin
 
 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
+We follow the popular "GitFlow" branching model for scalable development. In the SU2 repository, the master branch represents the latest stable major or minor release (7.0, 6.2.0, etc.), it should only be modified during version releases. Work that is staged for release is put into the develop branch via Pull Requests (to be discussed in a moment) from various "feature" branches where folks do their day-to-day work on the code. At release time, the work that has been merged into the develop branch is pushed to the master branch and tagged as a release.
+
+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
  ```
@@ -70,7 +72,7 @@ If a 2-D quadrilateral element is sufficiently skewed, the volume approximation
 Fixes issue 10."
     ```
 
-4. Push the code to the online version of the branch
+4. Push the code to the remote version of the branch on GitHub
 
     ```
     git push origin fixquadvol 
@@ -83,3 +85,5 @@ Fixes issue 10."
 ![Submit Request 2](../../docs_files/pr_submit_request_2.png)
 
 6. Now your code is available for code review!
+
+We encourage developers to submit draft pull requests on GitHub, which has several benefits. This helps keep the community updated as you work on your particular feature, and offers the opportunity for others to collaborate or offer helpful feedback in the process. Duplicate work and wasted effort can be avoided this way. Additionally, draft pull requests will also benefit from continuous integration testing, and you will be alerted to any regression test failures immediately, which can also save development effort.

_docs_v7/Execution.md

@@ -3,7 +3,7 @@ title: Execution
 permalink: /docs_v7/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.
+Once downloaded and installed, and now that you know the basics for setting up your problems, 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.
 
 ---
 
@@ -31,7 +31,7 @@ where `SU2_MODULE` can be any of the C++ modules on the [Software Components](/d
 ```
 $ ./SU2_CFD default.cfg
 ```
-where the executable, SU2_CFD, and the [Configuration File](/docs_v7/Configuration-File/), default.cfg, are located in the current working directory.  Please see the [Build from Source](/docs_v7/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:
+where the executable, SU2_CFD, and the [Configuration File](/docs_v7/Configuration-File/), default.cfg, are located in the current working directory.  Please see the [Build from Source](/docs_v7/Build-SU2-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
 ```
@@ -49,7 +49,7 @@ where *script_name.py* is the name of the script to be run, and [options] is a l
 
 ### 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.
+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. 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]`
 
@@ -61,7 +61,7 @@ Options:
 
 ### 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.
+The continuous adjoint calculation script, continuous_adjoint.py, automates the procedure for calculating sensitivities using a continuous adjoint method. 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]`
 

_docs_v7/FAQ.md

@@ -11,12 +11,14 @@ If the answer to your question is not here, try the [forum](http://cfd-online.co
 The best place to start for a new user after installing the code is the [Quick Start](/docs_v7/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]].
+The most easy-to-use documentation is here on GitHub, and you just found it! Users are especially encouraged to go through the docs in the Installation and Users Guide sections for all of the necesary details for running your first calculations.
+
 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. 
+Adjust the configuration file options, or improve mesh quality. Refer to the forum, tutorials, and TestCases for more specific examples (many of the config files there can be used as initial templates for your own cases. The most common option to change is to lower the CFL number to improve stability.
+
 
 ### When I run in parallel, the code prints multiples of the same line, for example:
 ```
@@ -33,27 +35,22 @@ Adjust the configuration file options, or improve mesh quality. Refer to the for
 > 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. 
+The code has not been compiled properly 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. 
+### What is the format of the residuals that are written to the console, and what do they mean?
+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. If possible, it is recommended to converge your simulations until the residuals reach machine precision.
 
 
 ### 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/. 
+* Advanced fix: after exhausting the easy and medium options, or if a clear bug like a segfault occurs, [post an Issue on the GitHub repository](https://github.com/su2code/SU2/issues). 
 
 
 ### 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. 
+A nonphysical point means the flow solution has encountered a negative density, pressure, or temperature. 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_v7/Test-Cases/) for directions.