Deploying to gh-pages from @ e8b5656 🚀

.buildinfo

@@ -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: 96abb715065329dafbfa2c410d67796d
+tags: 645f666f9bcd5a90fca523b33c5a78b7

_sources/developer/coding_guidelines.rst.txt

@@ -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 heterogeneous 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 heterogeneous 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 */

_sources/developer/documentation.rst.txt

@@ -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.

_sources/developer/index.rst.txt

@@ -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