-
Notifications
You must be signed in to change notification settings - Fork 82
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Deploying to gh-pages from @ 6831033 🚀
- Loading branch information
0 parents
commit ab8bd59
Showing
8,370 changed files
with
1,522,641 additions
and
0 deletions.
The diff you're trying to view is too large. We only load the first 3000 changed files.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,4 @@ | ||
# Sphinx build info version 1 | ||
# This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. | ||
config: 20cc6b8c25b2c02e892763a29e629fa3 | ||
tags: 645f666f9bcd5a90fca523b33c5a78b7 |
Empty file.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file not shown.
Binary file not shown.
Binary file not shown.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,190 @@ | ||
.. dev_coding-guidelines: | ||
Coding Guidelines | ||
================= | ||
|
||
This section presents an incomplete list of coding guidelines currently used to | ||
develop AMR-Wind code. As is the case with rules, it might not apply to all | ||
circumstances. Please use your best judgement when trying to comply with the | ||
rules and break them if necessary, but be ready to convince the rest of the | ||
team. | ||
|
||
**Use modern C++** | ||
|
||
Traditionally, AMReX based solvers have used C++ for managing data structures | ||
but Fortran for computational kernels. However, AMR-Wind is purely written in | ||
C++. One of the primary drivers for this choice is our desire to target | ||
next-generation Exascale systems that require targeting GPUs through CUDA, | ||
HIP, and other offloading paradigms. Support for languages other than C/C++ | ||
is not very mature for these architectures. | ||
|
||
Consult `ISO C++ Core Guidelines | ||
<https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines>`_ for best | ||
practices when coding in C++. | ||
|
||
**Write code targeting heterogenous architectures** | ||
|
||
All code must be written in a way such that it can run on GPUs without | ||
errors. Please consult the `GPU section | ||
<https://amrex-codes.github.io/amrex/docs_html/GPU_Chapter.html>`_ in AMReX | ||
documentation to learn the correct data structures and looping paradigms to | ||
use when targeting heterogenous architectures. | ||
|
||
**Unit and regression tests** | ||
|
||
Code modifications must not break existing unit tests or regression tests. If | ||
a change is known to break current behavior, e.g., a bug fix or an | ||
enhancement, the tests must be updated to account for this change and any | ||
necessary updates to documentation must be made to document this. | ||
|
||
New features must be accompanied with the necessary suite of unit and | ||
regression tests as appropriate. There should be at least one test that | ||
exercises the feature to catch issue early on. New features must also be | ||
documented in the user and theory manual. | ||
|
||
**Pull-request based workflow** | ||
|
||
All updates must be submitted as `pull-requests | ||
<https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/proposing-changes-to-your-work-with-pull-requests>`_ | ||
on the public GitHub repository. Pull requests will be reviewed by core | ||
developers and must also pass all Continuous Integration checks before it is | ||
merged into mainline source tree. | ||
|
||
If a pull-requests fails during nightly tests after it is merged with the | ||
mainline code base, it will be reverted and a new pull request should be | ||
submitted with appropriate fixes. | ||
|
||
|
||
Style Guide/Recommendations | ||
---------------------------- | ||
|
||
This section documents the preferred style for formatting source code within | ||
AMR-Wind. While the guidelines presented in the previous section are based on | ||
technical and quality assurance reasons, the formatting style is largely a | ||
matter of individual taste and there is no hard and fast rule. However, to | ||
ensure consistency in a codebase used by a large team, we provide some | ||
guidelines here. | ||
|
||
AMR-Wind comes with a :file:`.clang-format` definition that can be used with | ||
`Clang format <https://clang.llvm.org/docs/ClangFormat.html>`_ to automatically | ||
reformat source code to be consistent with the rest of the codebase. Many source | ||
code editors come with Clang format integration that allows you to reformat code | ||
from within your text editor. Please consult the Clang format documentation, or | ||
your editor's documentation to setup clang-format integration. However, please | ||
be careful that you only use Clang format on code you've written modified and | ||
not on code that has not been written by you. | ||
|
||
Other AMR-Wind specific conventions: | ||
|
||
#. All AMR-Wind specific code must be within ``amr_wind`` namespace. Code for | ||
unit tests must be in ``amr_wind_tests`` namespace. | ||
|
||
#. Following AMReX convention, header files will use a ``.H`` extension and C++ | ||
source files will use a ``.cpp`` extension. | ||
|
||
#. Use `snake_case <https://en.wikipedia.org/wiki/Snake_case>`_ almost | ||
everywhere, i.e., for variables, namespaces, function and method names. | ||
Exceptions include when overriding AMReX class methods in inherited classes. | ||
|
||
#. Use `CamelCase <https://en.wikipedia.org/wiki/Camel_case>`_ for class names. | ||
Capitalize the first letter of the first word in the compound name also. | ||
|
||
#. Use ``m_`` prefix for class instance variables. No prefix for class methods. | ||
|
||
#. Keep logic in functions short. Always use descriptive names for function | ||
names and variables that provide the reader with clues as to what the | ||
function does. | ||
|
||
Sample C++ code | ||
~~~~~~~~~~~~~~~ | ||
|
||
.. code-block:: c++ | ||
:linenos: | ||
|
||
#ifndef CFDSIM_H | ||
#define CFDSIM_H | ||
|
||
#include "AMReX_AmrCore.H" | ||
#include "SimTime.H" | ||
#include "FieldRepo.H" | ||
#include "PDEBase.H" | ||
#include "Physics.H" | ||
|
||
namespace amr_wind { | ||
|
||
// Forward declaration if necessary | ||
namespace turbulence { | ||
class TurbulenceModel; | ||
} | ||
|
||
/** Data structures for a CFD simulation | ||
* | ||
* CFDSim is a thin wrapper that holds all the necessary objects for a CFD | ||
* simulation. The key data members within this object are: | ||
* | ||
* - mesh (amrex::AmrCore) The AMR mesh hierarchy data structure | ||
* - time (SimTime) The time object | ||
* - repo (FieldRepo) The field repository | ||
* - pde_manager (PDEMgr) PDE manager interface | ||
* - physics_manager List of physics active in this simulation | ||
* - turbulence_model Reference to the turbulence model | ||
*/ | ||
class CFDSim | ||
{ | ||
public: | ||
CFDSim(amrex::AmrCore& mesh); | ||
~CFDSim(); | ||
|
||
//! Return the AMR mesh hierarchy | ||
amrex::AmrCore& mesh() { return m_mesh; } | ||
const amrex::AmrCore& mesh() const { return m_mesh; } | ||
|
||
//! Return simulation time control | ||
SimTime& time() { return m_time; } | ||
const SimTime& time() const { return m_time; } | ||
|
||
//! Return the field repository | ||
FieldRepo& repo() { return m_repo; } | ||
const FieldRepo& repo() const { return m_repo; } | ||
|
||
//! Return the PDE manager instance | ||
pde::PDEMgr& pde_manager() { return m_pde_mgr; } | ||
const pde::PDEMgr& pde_manager() const { return m_pde_mgr; } | ||
|
||
//! Return the physics manager instance | ||
PhysicsMgr& physics_manager() { return m_physics_mgr; } | ||
const PhysicsMgr& physics_manager() const { return m_physics_mgr; } | ||
|
||
//! Return a vector of physics instances active in this simulation | ||
PhysicsMgr::TypeVector& physics() { return m_physics_mgr.objects(); } | ||
const PhysicsMgr::TypeVector& physics() const { return m_physics_mgr.objects(); } | ||
|
||
//! Return the turbulence model instance used in this simulation | ||
turbulence::TurbulenceModel& turbulence_model() { return *m_turbulence; } | ||
const turbulence::TurbulenceModel& turbulence_model() const | ||
{ return *m_turbulence; } | ||
//! Initialize the turbulence model after reading necessary inputs | ||
void create_turbulence_model(); | ||
|
||
//! Initialize the different physics models based on user inputs | ||
void init_physics(); | ||
|
||
private: | ||
amrex::AmrCore& m_mesh; | ||
|
||
SimTime m_time; | ||
|
||
FieldRepo m_repo; | ||
|
||
pde::PDEMgr m_pde_mgr; | ||
|
||
PhysicsMgr m_physics_mgr; | ||
|
||
std::unique_ptr<turbulence::TurbulenceModel> m_turbulence; | ||
}; | ||
|
||
} // namespace amr_wind | ||
|
||
#endif /* CFDSIM_H */ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,94 @@ | ||
.. _dev-documenting: | ||
|
||
Documentation - user manual and source code docs | ||
================================================ | ||
|
||
AMR-Wind comes with two different types of documentation: | ||
|
||
- User & developer manuals, such as the document you are reading now, that are | ||
written using `Sphinx <https://www.sphinx-doc.org/en/master/index.html>`_, and | ||
|
||
- Inline documentation within C++ source code that are written in a format that can be | ||
processed automatically by `Doxygen <http://www.doxygen.nl/manual/index.html>`_ | ||
|
||
User documentation | ||
------------------ | ||
|
||
AMR-Wind user documentation is written using a special format called | ||
ReStructured Text (ReST) and is converted into HTML and PDF formats using a | ||
python package Sphinx. Since the manuals are written in simple text files, they | ||
can be version controlled alongside the source code. Documentation is | ||
automatically generated with new updates to the GitHub repository and deployed | ||
at `AMR-Wind documentation site <https://exawind.github.io/amr-wind>`_. | ||
|
||
Building documentation | ||
`````````````````````` | ||
|
||
To update and build documentation locally on your system you will need Sphinx | ||
installed on your system. Please consult the `Sphinx installation page | ||
<https://www.sphinx-doc.org/en/master/usage/installation.html>`_ for | ||
instructions to install Sphinx. Users of `Anaconda python distribution | ||
<https://www.anaconda.com/>`_ can install Sphinx by executing the following | ||
command within their desired environment. | ||
|
||
.. code-block:: console | ||
conda install sphinx | ||
Once Sphinx is installed properly, you should have access to the | ||
:program:`sphinx-build` executable. To build documentation follow the instructions below: | ||
|
||
.. code-block:: console | ||
# Switch to AMR-Wind build directory | ||
cd ~/exawind/source/amr-wind/build/ | ||
# Build docs in HTML format | ||
sphinx-build -M html ../docs/sphinx . | ||
The above command will build docs in HTML format and the output is placed in | ||
:file:`html` directory within the :file:`build` directory. Documentation can | ||
also be generated in other formats, consult `Sphinx docs | ||
<https://www.sphinx-doc.org/en/master/usage/builders/index.html>`_ for available | ||
formats and their usage. | ||
|
||
Writing user documentation | ||
`````````````````````````` | ||
|
||
As mentioned previously, documentation is written using a special text format | ||
called reStructuredText. Sphinx user manual provides a `reST Primer | ||
<https://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html>`_ that | ||
provides an overview of this format and how to write documentation using this format. | ||
|
||
|
||
Documenting source code | ||
------------------------- | ||
|
||
Source code (C++ files) are commented using a special format that allows Doxygen | ||
to extract the annotated comments and create source code documentation as well | ||
as inheritance diagrams. API documentation for the latest snapshot of the | ||
codebase can be browsed online `here | ||
<https://exawind.github.io/amr-wind/api_docs>`_. To build the documentation | ||
locally, first install ``doxygen`` and ``graphviz`` executables on your system. | ||
Once they are successfully installed, execute the following command from the | ||
root directory of ``amr-wind`` | ||
|
||
.. code-block:: console | ||
doxygen ./docs/doxygen/Doxyfile | ||
The default format is HTML, and upon successful completion of the above command, | ||
the documentation files are available in :file:`build/html` directory. Open | ||
:file:`build/html/index.html` on your browser to browse the locally generated | ||
documentation. | ||
|
||
`Doxygen manual <http://www.doxygen.nl/manual/index.html>`_ provides an overview | ||
of the syntax that must be used. Please follow the Doxygen style of commenting | ||
code when commenting AMR-Wind sources. | ||
|
||
When commenting code, try to use self-documenting code, i.e., descriptive names | ||
for variables and functions that eliminate the need to describe what is going on | ||
in comments. In general, comments should address *why* something is being coded | ||
in a particular way, rather than how the code does things. Try to write the code | ||
in a clear manner so that it is obvious from reading the code instead of having | ||
to rely on comments to follow the code structure. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,16 @@ | ||
.. _dev-docs: | ||
|
||
Developer Documentation | ||
======================= | ||
|
||
This section is meant for potential developers who are interested in modifying | ||
and extending the ``amr-wind`` source code for their own use cases. | ||
|
||
.. toctree:: | ||
:maxdepth: 3 | ||
|
||
documentation | ||
unit_testing | ||
regression_testing | ||
verification | ||
coding_guidelines |
Oops, something went wrong.