Tardigrade Balance Equations

Project Description

A C++ framework containing balance equation terms and their Jacobians

Information

TODO

Developers

• Nathan Miller: Nathan.A.Miller@colorado.edu

Dependencies

For convenience, the minimal Conda environment requirements for project development are included in environment.txt. A minimal anaconda environment for building the documentation can be created from an existing anaconda installation with the following commands.

$ conda create --name tardigrade-balance-equations-env --file environment.txt --channel conda-forge

You can learn more about Anaconda Python environment creation and management in the Anaconda Documentation.

The build, test, and run time requirements are subsets of the development environment requirements found in environment.txt. This project builds and deploys as a Conda package to the AEA Conda channel. The Conda recipe and build, test, run time requirements are found in the recipe/ directory.

Build and Test

This project is built with CMake and uses Sphinx to build the documentation with Doxygen + Breathe for the c++ API.

Environment variables

This project's CMake configuration accepts two build type strings: 'Release' and 'conda-test'.

The build type can be set with the -DCMAKE_BUILD_TYPE=<build type string> during project configuration. Both build types will require the upstream dependent libraries

• error_tools: https://github.com/UCBoulder/tardigrade_error_tools
• vector_tools: https://github.com/UCBoulder/tardigrade_vector_tools

and the 'conda-test' build type also depends upon

• constitutive_tools: https://github.com/UCBoulder/tardigrade_constitutive_tools
• hydra: https://github.com/UCBoulder/tardigrade_hydra

to be installed and found in the user's environment. If the build type string doesn't match those previously listed, the CMake project will build missing upstream libraries with the CMake fetch_content feature. The 'conda-test' build type excludes the project libraries from the build configuration and will attempt to find the project libraries in the user's environment to perform the project unit and integration tests against the as-installed project files.

Building the documentation

To build just the documentation pick up the steps here:

2. Create the build directory and move there

   $ pwd
   /path/to/tardigrade-balance-equations/
   $ mkdir build/
   $ cd build/

3. Run cmake configuration

   $ pwd
   /path/to/tardigrade-balance-equations/build/
   $ cmake ..

4. Build the docs

   $ cmake --build . --target Sphinx

5. Documentation builds to:

   tardigrade-balance-equations/build/docs/sphinx/html/index.html

6. Display docs

   $ pwd
   /path/to/tardigrade-balance-equations/build/
   $ firefox docs/sphinx/html/index.html &

7. While the Sphinx API is still a WIP, try the doxygen API

   $ pwd
   /path/to/tardigrade-balance-equations/build/
   $ firefox docs/doxygen/html/index.html &

Install the library

Build the entire before performing the installation.

4. Build the entire project

   $ pwd
   /path/to/tardigrade-balance-equations/build
   $ cmake --build .

5. Install the library

   $ pwd
   /path/to/tardigrade-balance-equations/build
   $ cmake --install . --prefix path/to/root/install
   
   # Example local user (non-admin) Linux install
   $ cmake --install . --prefix /home/$USER/.local
   
   # Example install to conda environment
   $ conda activate my_env
   $ cmake --install . --prefix ${CONDA_PREFIX}

Contribution Guidelines

Git Commit Message

Begin Git commit messages with one of the following headings:

• BUG: bug fix
• DOC: documentation
• FEAT: feature
• MAINT: maintenance
• TST: tests
• REL: release
• WIP: work-in-progress

For example:

git commit -m "DOC: adds documentation for feature"

Git Branch Names

When creating branches use one of the following naming conventions. When in doubt use feature/<description>.

• bugfix/\<description>
• feature/\<description>
• release/\<description>

reStructured Text

Sphinx reads in docstrings and other special portions of the code as reStructured text. Developers should follow styles in this Sphinx style guide.

Style Guide

This project uses the gersemi CMake linter. The CI style guide check runs the following command

and any automatic fixes may be reviewed and then applied by developers with the following commands

This project enforces its style using clang-tidy and clang-format as configured with the .clang-format and .clang-tidy files in the root directory. The formatting of the project can be checked using clang-tidy by first configuring the project using

where ... are the other configuration flags specified. After this clang-tidy can be run on the full project from the source directory via

Caution!

Commit all changes prior to running the clang tidy command. This will edit all source files.

The formatting can be checked using clang-format by running

which will indicate if the formatting is correct. The c++ files can be re-formatted to match the style guidance by running

Caution!

Commit all changes prior to running the format command. This will edit all source files.

If the style is not constrained by the above, it should be inferred by the surrounding code. Wherever a style can't be inferred from surrounding code this project falls back to PEP-8-like styles the exceptions to the notional PEP-8 fall back:

1. Doxygen style docstrings are required for automated, API from source documentation.