-
Notifications
You must be signed in to change notification settings - Fork 11
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Add dev docs for Nalu Preprocessing utility
- Loading branch information
Showing
3 changed files
with
183 additions
and
62 deletions.
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
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,68 @@ | ||
| .. _dev_intro: | ||
|
|
||
| Introduction | ||
| ============ | ||
|
|
||
| This part of the documentation is intended for users who wish to extend or add | ||
| new functionality to the NaluWindUtilities toolsuite. End users who want to use | ||
| existing utilities should consult the :ref:`user_guide` for documentation on | ||
| standalone utilities. | ||
|
|
||
| Version Control System | ||
| ---------------------- | ||
|
|
||
| Like `Nalu <http://nalu.readthedocs.io/en/latest/>`_, NaluWindUtils uses `Git | ||
| SCM <https://www.git-scm.com>`_ to track all development activity. All | ||
| development is coordinated through the `Github repository | ||
| <https://github.com/NaluCFD/NaluWindUtils>`_. `Pro Git | ||
| <https://www.git-scm.com/book/en/v2>`_, a book that covers all aspects of Git is | ||
| a good resource for users unfamiliar with Git SCM. `Github Desktop | ||
| <https://desktop.github.com>`_ and `Git Kraken <https://www.gitkraken.com>`_ are | ||
| two options for users who prefer a GUI based interaction with Git source code. | ||
|
|
||
| .. _dev_docs_build: | ||
|
|
||
| Building API Documentation | ||
| -------------------------- | ||
|
|
||
| In-source comments can be compiled and viewed as HTML files using `Doxygen | ||
| <http://www.stack.nl/~dimitri/doxygen/index.html>`_. If you want to generate | ||
| class inheritance and other collaboration diagrams, then you will need to | ||
| install `Graphviz <http://www.graphviz.org>`_ in addition to Doxygen. | ||
|
|
||
| #. API Documentation generation is disabled by default in CMake. Users will have | ||
| to enable this by turning on the :cmakeval:`ENABLE_DOXYGEN_DOCS` flag. | ||
|
|
||
| #. Run ``make api-docs`` to generate the documentation in HTML form. | ||
|
|
||
| The resulting documentation will be available in :file:`doc/doxygen/html/` | ||
| within the CMake build directory. | ||
|
|
||
| Contributing | ||
| ------------- | ||
|
|
||
| The project welcomes contributions from the wind research community. Users can | ||
| contribute to the source code using the normal `Github fork and pull request | ||
| workflow <https://guides.github.com/activities/forking/>`_. Please follow these | ||
| general guidelines when submitting pull requests to this project | ||
|
|
||
| * All C++ code must conform to the C++11 standard. Consult `C++ Core Guidelines | ||
| <http://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines>`_ on | ||
| best-practices to writing idiomatic C++ code. | ||
|
|
||
| * Check and fix all compiler warnings before submitting pull requests. Use | ||
| ``-Wall -Wextra -pedantic`` options with GNU GCC or LLVM/Clang to check for | ||
| warnings. | ||
|
|
||
| * New feature pull-requests must include doxygen-compatible *in source* | ||
| documentation, additions to user manual describing the enchancements and their | ||
| usage, as well as the necessary updates to CMake files to enable configuration | ||
| and build of these capabilities. | ||
|
|
||
| * Prefer Markdown format when documenting code using Doxgen-compatible comments. | ||
|
|
||
| * Avoid incurring additional third-party library (TPL) dependencies beyond what | ||
| is required for building Nalu. In cases where this is unavoidable, please | ||
| discuss this with the development team by creating an issue on `issues page | ||
| <https://github.com/NaluCFD/NaluWindUtils/issues>`_ before submitting the pull | ||
| request. |
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,111 @@ | ||
| .. _dev_nalu_preprocessing: | ||
|
|
||
| Nalu Pre-processing Utilities | ||
| ============================= | ||
|
|
||
| NaluWindUtils provides several pre-processing utilities that are built as | ||
| subclasses of :class:`sierra::nalu::PreProcessingTask`. These utilities are | ||
| configured using a YAML input file and driven through the | ||
| `sierra::nalu::PreProcessDriver` class -- see `_util_nalu_preprocess_exe` for | ||
| documentation on the available input file options. All pre-processing utilities | ||
| share a common interface and workflow through the | ||
| :class:`sierra::nalu::PreProcessingTask` API, and there are three distinct | ||
| phases for each utility namely: construction, initialization, and execution. The | ||
| function of each of the three phases as well as the various actions that can be | ||
| performed during these phases are described below. | ||
|
|
||
| Task Construction Phase | ||
| ----------------------- | ||
|
|
||
| The driver initializes each *task* through a constructor that takes two | ||
| arguments: | ||
|
|
||
| - :class:`sierra::nalu::CFDMesh` -- a mesh instance that contains the MPI | ||
| communicator, STK MetaData and BulkData instances as well as other mesh | ||
| related utilities. | ||
|
|
||
| - :class:`YAML::Node` -- a yaml-cpp node instance containing the user defined | ||
| inputs for this particular task. | ||
|
|
||
| The driver class initializes the instances in the order that was specified in | ||
| the YAML input file. However, the classes must not assume existence or | ||
| dependency on other task instances. | ||
|
|
||
| The base class :class:`PreProcessingTask` already stores a reference to the | ||
| :class:`CFDMesh` instance in ``mesh_``, that is accessible to subclasses via | ||
| protected access. It is the responsibility of the individual task instances to | ||
| process the YAML node during construction phase. Currently, this is typically | ||
| done via the ``load``, a private method in the concrete task specialization | ||
| class. | ||
|
|
||
| No actions on STK MetaData or BulkData instances should be performed during the | ||
| construction phase. The computational mesh may not be loaded at this point. The | ||
| construction should only initialize the class member variables that will be used | ||
| in subsequent phases. The instance may store a reference to the YAML Node if | ||
| necessary, but it is better to process and validate YAML data during this phase | ||
| and store them as class member variables of correct types. | ||
|
|
||
| It is recommended that all tasks created support execution in parallel and, if | ||
| possible, handle both 2-D and 3-D meshes. However, where this is not possible, | ||
| the implementation much check for the necessary conditions via asserts and throw | ||
| errors appropriately. | ||
|
|
||
| Task Initialization Phase | ||
| ------------------------- | ||
|
|
||
| Once all the task instances have been created and each instance has checked the | ||
| validity of the user provided input files, the driver instance calls the | ||
| ``initialize`` method on all the available task instances. All | ||
| :class:`stk::mesh::MetaData` updates, e.g., part or field creation and | ||
| registration, must be performed during this phase. No | ||
| :class:`stk::mesh::BulkData` modifications should be performed during this | ||
| stage. Some tips for proper initialization of parts and fields: | ||
|
|
||
| - Access to :class:`stk::mesh::MetaData` and :class:`stk::mesh::BulkData` is | ||
| through ``mesh_.meta()`` and ``mesh_.bulk()`` respectively. They return | ||
| non-const references to the instances stored in the mesh object. | ||
|
|
||
| - Use :meth:`MetaData::get_part` to check for the existence of a part in the | ||
| mesh database, :meth:`MetaData::declare_part` will automatically create a | ||
| part if none exists in the database. | ||
|
|
||
| - As with parts, use :meth:`MetaData::declare_field` or | ||
| :meth:`MetaData::get_field` to create or perform checks for existing fields | ||
| as appropriate. | ||
|
|
||
| - New fields created by pre-processing tasks must be registered as an output | ||
| field if it should be saved in the result output ExodusII database. The | ||
| default option is to not output all fields, this is to allow creation of | ||
| temporary fields that might not be necessary for subsequent Nalu | ||
| simulations. | ||
|
|
||
| - The *coordinates* field is registered on the universal part, so it is not | ||
| strictly necessary to register this field on newly created parts. | ||
|
|
||
| Once all tasks have been initialized, the driver will **commit** the STK | ||
| MetaData object and populate the BulkData object. At this point, the mesh is | ||
| fully loaded and BulkData modifications can begin and the driver moves to the | ||
| execution phase. | ||
|
|
||
| Task Execution Phase | ||
| -------------------- | ||
|
|
||
| The driver initiates execution phase of individual tasks by calling the | ||
| :meth:`run()` method, which performs the core pre-processing task of the | ||
| instance. Since STK MetaData has been committed, no further MetaData | ||
| modifications (i.e., part/field creation) can occur during this phase. All | ||
| actions at this point are performed on the BulkData instance. Typical examples | ||
| include populating new fields, creating new entities (nodes, elements, | ||
| sidesets), or moving mesh by manipulating coordinates. If the mesh does not | ||
| explicitly create any new fields, the *task* instance can still force a write of | ||
| the output database by calling the :meth:`CFDMesh::set_write_flag()` to indicate | ||
| that the database modifications must be written out. By default, no output | ||
| database is created if no actions were performed. | ||
|
|
||
| Task Destruction Phase | ||
| ---------------------- | ||
|
|
||
| All *task* implementations must provide proper cleanup procedures via | ||
| destructors. No explicit clean up task methods are called by the driver utility. | ||
| The preprocessing utility depends on C++ destruction actions to free resources | ||
| etc. |