Deploying to gh-pages from @ 091b07f 🚀

.buildinfo

@@ -0,0 +1,4 @@
+# Sphinx build info version 1
+# This file records the configuration used when building these files. When it is not found, a full rebuild will be done.
+config: b9a7243bd55f1f7490f5200a3937f44a
+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 judgment 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,97 @@
+.. _dev-documenting:
+
+Documentation
+=============
+
+AMR-Wind comes with two different types of documentation:
+
+- The manual, i.e., the document you are reading now, that is
+  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>`_
+
+Manual
+------
+
+The AMR-Wind manual 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>`_.
+
+Writing 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.
+
+
+Source code documentation
+-------------------------
+
+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. The
+:doc:`../doxygen/html/index` documentation for the latest snapshot of
+the codebase can be browsed in this manual. The `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.
+
+Building documentation
+----------------------
+
+Dependencies
+````````````
+
+To generate the AMR-Wind manual on a local machine, `doxygen`,
+`graphviz`, `doxysphinx`, `enchant`, and `sphinx` are required.
+
+To install the required packages on Linux:
+
+.. code-block:: console
+
+    $ sudo apt-get install -y --no-install-recommends graphviz libenchant-2-dev
+
+and on OSX with homebrew:
+
+.. code-block:: console
+
+    $ brew install doxygen graphviz enchant
+
+To install the required python packages:
+
+.. code-block:: console
+
+    $ pip install sphinx sphinx_rtd_theme sphinx_toolbox sphinx_copybutton pyenchant sphinxcontrib-spelling doxysphinx
+
+Build
+`````
+
+Run the following command to build the documentation:
+
+.. code-block:: console
+
+    $ cd build && cmake -DAMR_WIND_ENABLE_DOCUMENTATION:BOOL=ON .. && cmake --build . -t docs
+
+.. tip::
+
+   On OSX, before running the cmake, you may need to :code:`$ export PYENCHANT_LIBRARY_PATH=/opt/homebrew/lib/libenchant-2.dylib`
+
+The resulting documentation is in `docs/spinx/html`
+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.

_sources/developer/index.rst.txt

@@ -0,0 +1,17 @@
+.. _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
+   ../doxygen/html/index
+   unit_testing
+   regression_testing
+   verification
+   coding_guidelines