The cfspopcon team uses Poetry to develop. If you are familiar with the usual poetry based development workflow, feel free to skip right ahead to the Contribution Guidelines.
For more information and help installing Poetry, please refer to their documentation. Once you have Poetry installed we are ready to start developing. First we clone the repository and enter into the folder.
>>> git clone https://github.com/cfs-energy/cfspopcon.git >>> cd cfspopcon
Setting up a virtual environment and installing all dependencies required to develop, is done in just one command:
>>> poetry install >>> poetry run radas -d ./radas_dir -c radas_config.yaml
If you are new to Poetry, we suggest that you at least read their brief introduction on how to use this virtual environment. You can verify that everything worked as expected by following the :ref:`Getting Started <gettingstarted>` guide.
At this point you are ready to read our Contribution Guidelines and start making changes to the code. We are looking forward to your contribution!
If you have a question or found a bug, please feel free to raise an issue on GitHub.
If you would like to make changes to the code, we ask that you follow the below guidelines:
- Please follow our Style Guide
- The Pre-Commit Checks should all pass
- Make sure tests in the test suite are still passing, see Running the Test Suite
- If adding new functionality, please try to add a unit test for it, if applicable.
- Please ensure that any changes are correctly reflected in the documentation, see Building The Documentation
The set of tools configured to run as pre-commit hooks should cover the simple style decisions.
For everything else, we follow the Google Python Style Guide, but make some exceptions for science / math variables.
The Google style guide and PEP8 encourage long, descriptive, lower case variables names. However, these can make science / math equations hard to read.
There is a case to be made for using well-established mathematical symbols as local variable names, e.g. T for temperature or r for position.
Subscripts can be added, e.g. r_plasma.
To make reading & validating formulas easier, we additionally follow the below guidelines:
- Add a descriptive comment when using short variable names.
- When local variables are declared, specify their units in a comment next to the declaration, like
x = 1.0 # [m] - Use basic SI units, unless you have a good reason not to. (e.g. prefer
[A]over[kA]). - Explicitly call out dimensionless physical quantities, e.g.
reynolds_number = 1e3 # [~]. - Functions that handle dimensional quantities should use :class:`pint.Quantity`.
Please note, that while we have some checks for docstrings, those checks do not cover all aspects. So let's look at a basic example, the :func:`~cfspopcon.formulas.geometry.calc_plasma_volume` function:
.. literalinclude:: ../../cfspopcon/formulas/geometry/analytical.py :language: python :linenos: :pyobject: calc_plasma_volume
To summarize the important points of the above example:
- Include short descriptive one-liner.
- If applicable, add a more detailed description.
- List the arguments with a short description, and include their units.
- Each return value should come with a brief explanation and unit.
- Do not include any type annotations within the docstring. These will be added automatically by sphinx.
Aside from the units annotations in the docstring, you'll notice the parameters are annotated with the type :class:`~cfspopcon.unit_handling.Unitfull`.
This is because all calculations in cfspopcon use explicit unit handling to better ensure that calculations are correct and no units handling errors sneak into a formula.
The units handling cfspopcon is powered by the pint and pint-xarray python packages.
The type :class:`~cfspopcon.unit_handling.Unitfull`, used in the above function as type annotation, is an alias of pint.Quantity | xarray.DataArray.
In addition to the above example, we also recommend having a look at the cfspopcon.formulas module, which holds many good examples.
As the name suggests, these are a list of checks that should be run before making a commit.
We use the pre-commit framework to ensure these checks are run for every commit.
You already installed the pre-commit tool as a development dependency during the Development Setup.
Run all configured checks by executing:
>>> poetry run pre-commit run --all-files
But instead of trying to remember to run this command before every commit, we suggest you follow the pre-commit documentation and install the git hooks.
>>> poetry run pre-commit install
The installed git hooks will now automatically run the required checks when you try to git commit some changes.
An added benefit is that this will usually be faster than running over all files, as pre-commit is pretty smart at figuring out which files it needs to check for a given commit.
If you are curious, you can see all the automatic checks that we have configured to run in the file .pre-commit-config.yaml:
.. literalinclude:: ../../.pre-commit-config.yaml
We use pytest and the pytest-cov plugin for our test suite.
All tests can be found in the tests subfolder.
The configuration can be found in the pyproject.toml file.
Running the entire test suit can be done via:
>>> poetry run pytest
When adding new functionality it is best to also add a test for it.
If the category of the added functionality fits within one of the existing files, please add your test to that file.
Otherwise feel free to create a new test file. The name should follow the convention test_{description}.py.
Our documentation is build and hosted on Read The Docs and previews are available on each PR. But when extending the documentation it is most convenient to first build it locally yourself to check that everything is included & rendered correctly.
Warning
Building the documentation unfortunately requires a non-python dependency: pandoc.
Please ensure that the pandoc executable is available before proceeding.
This package can easily be installed via sudo apt-get install pandoc (Linux) or brew install pandoc (MacOS).
For more details please see pandoc's installation guide.
Starting from inside the project folder you can trigger the build by running:
>>> poetry run make -C docs html
Once that build is finished, open the file ./docs/_build/html/index.html to view the documentation.
As part of our CI we also run the sphinx-doctest and sphinx-linkcheck extensions.
The sphinx-doctest extension checks that python snippets used in docstrings are actually valid python code and produce the expected output. And sphinx-linkcheck is used to ensure that any links used within our documentation are correct and accessible.
To avoid having failures in the CI it's a good idea to run these locally first as well:
poetry run make -C docs doctest poetry run make -C docs linkcheck