Development

The following includes note and information for nupyprop developers to help orient themselves with respect to the source code and the build system.

Developing with the source code

The source code is available at https://github.com/NuSpaceSim/nupyprop. This is a git repository hosted on the nuSpaceSim github organization. You can clone this repository locally for version control management with

git clone https://github.com/NuSpaceSim/nupyprop

Then simply cd nupyprop to enter the nupyprop directory and begin development.

Nupyprop uses a :PEP: 518 compliant, src-tree package layout. Important Configuration Files are mostly kept at the top level of the repo, while source code is in the src/nupyprop directory. Other important directories are:

  • docs, with source code for generating documentation

  • figures for holding static images

  • recipe for building with non- :PEP: 517 compliant systems like conda

  • tests for unit tests.

A final important directory is the hidden .github directory which holds the github Actions files for our CI pipeline.

Compiling the code for development

Nupyprop is compliant with both PEP 517 and PEP 518, and relies on pip for as a PEP 517 compatable build tool to build the package into a binary wheel and install it on host systems.

You will need a working Fortran90 compiler such as gfortran, and an OpenMP implementation. On MacOS and Ubuntu both are provided as part of the latest gcc compiler suite.

You will also need pip as all additional python requirements such as numpy will be installed by pip.

Hint

Install gcc on your system using a package manager.

On Ubuntu Linux with apt-get use: sudo apt-get install gcc gfortran openmp

On MacOS with Homebrew use: brew install gcc

Developers will want to install the package in “editable” mode in order to make fast, iterative changes to the python code without having to recompile. pip install to build and install the package:

python3 -m pip install -e .

All changes to the fortran code will require recompiling. Simply rerun the above command to generate the new shared library.

numpy.distutils and Fortran

Fortran module propagate is compiled with numpy distutils. Minimal specification included in setup.py

Try to minimize the amount of code here so the build system can be as declarative as reasonable.

Version management

nupyprop uses setuptools_scm for versioning. This means the version number is generated at build time from the latest tag in the git repository. To set a new version number use git tag to tag your commit with a semantic version scheme.

git tag v0.0.1

If you have added new commits but are not ready to tag a new version, setuptools_scm will update the version by adding a -postN to the version string, where N is the number of commits past the latest tag version your git repository is.

the version is written to a file named _version.py, which is ignored by git.

Configuration Files

Build requirements specified in pyproject.toml

Metadata and Runtime requirements in setup.cfg

Tooling configuration in goth pyproject.toml and setup.cfg based on tool support.

Fortran extensions compiled in setup.py

Nupyprop as a console_script

Once installed users use the command line executable. This is managed using setuptools’ entry_points console_script feature, in setup.cfg.

Running the tests

Tests require pytest and are held in tests directory. To run all the tests locally, run:

pytest tests/

To test in an isolated environment for your python version use tox. If my python version is 3.9 I run:

tox -e py39

Building the wheel

python3 -m pip wheel -w dist --no-deps .

Building the conda package

conda install conda-build #if not installed
conda build -c conda-forge recipe/

Building the documentation

tox -e docs

Using the CI pipeline

https://github.com/NuSpaceSim/nupyprop/actions/workflows/pypi-build-test-publish.yml

Run automatically on new pushes, pull-requests and release tags.

Can be run manually with the workflow dispatch “Run Workflow” option.