Developer Notes

This page contains information for developers.

Branching Model

T3D is currently being developed using a trunk-based development strategy. This works best with small incremental changes. Long-lived branches should only be used for larger changes, such as new model development. It is the responsibility of developers to keep their branches current with the main branch.

Python Style Guide

We strive to adhere to the PEP 8 style guide as much as possible. The CI will automatically update the formatting when a development branch is merged into the main branch. Developers are encouraged to run

flake8

or

autopep8

while working on the code, by simply running either command from the t3d home directory. Note that flake8 will only report on formatting issues whereas autopep8 will also fix them. Errors and formatting issues that are currently being ignored are listed in the .flake8 and pyproject.toml files.

Code Testing

Unit Testing

To run all the unit tests, use the following from the main directory

t3d-unittests

which is a short-cut command for python3 -m unittest. Individual unit tests can be performed using, for example

python3 -m unittest tests/unit/test_import.py

See the python files in tests/unit for the available unit tests. Developers are encouraged to add new unit tests.

Regression Testing

Regression testing can be performed by running the test cases in the tests/regression/ directory. Currently there are only reference results for the serial tests with the ReLU model.

t3d tests/regression/test-w7x-relu.in
t3d tests/regression/test-jet-relu.in

The bpcmp utility is used to compare the ADIOS2 bp output file from the new and old results. This utility is installed as part of the t3d installation.

bpcmp --ignore-atts title history inputs infile -r 1e-9 -v 1 tests/regression/test-w7x-relu.bp tests/regression/ref-w7x-relu.bp

The -v option sets the verbosity level with options of 0 for quiet mode, 1 to list all attributes/variables with differences, and 2 to list the status of the comparison for all attributes/variables.

Continuous Integration (CI)

CI is performed using bitbucket pipelines. Unit and regression tests are run on branches pushed to the remote repository. he regression tests only perform serial tests with the ReLU model. Upon merging into the main branch a linting stage is performed using autopep8 which updates the formatting to (mostly) adhere to the PEP 8 style guide.

Updating Documentation

T3D documentation is maintained with Read-the-Docs. To review your documentation changes locally, first install the required packages

pip install -e .[docs]

Then build the documentation

sphinx-autobuild docs/ docs/_build/html

Some warnings and errors will be printed to the terminal screen. The documentation can be viewed by going to http://127.0.0.1:8000.

Note

The local documentation will update as changes are saved.

Terminal and file log output

A Logbook class was developed to stream output to both the terminal and a specified log file. To use, python files should import the Logbook with .. code-block:: python

from Logbook import info, bold, emph, warn, errr, debug

Do not import unused functions. These functions should be used instead print. A color can be passed to this function so that terminal output is colorized. All colors are stripped from the output string before writing to the log file otherwise the log file will contain ascii characters when viewed with most editors. For example,

info(msg=f"x = {x}", color=green)

The color input is optional and will use the default color if not specified. Other output functions include

bold(msg=f"x = {x}", color=green)  # The output will be the specified color and bold
emph(msg=f"x = {x}")  # The output will be blue and bold
warn(msg=f"x = {x}")  # The output will be yellow, bold, and include a WARNING prefix
errr(msg=f"x = {x}")  # The output will be red, bold, and include a ERROR prefix
debug(msg=f"x = {x}")  # The output will only be written to the log file

Flux models have their own instance of the Logbook class which only write output to files.

Available colors include:

  • red

  • green

  • yellow

  • blue

  • magenta

  • cyan

  • and light_ versions of the above