Development

Installation

To work on the source code, first clone the repository:

git clone https://gitlab.ethz.ch/compmech/gripyth.git

Then create a dedicated virtual Python environment:

python -m venv venv
. venv/bin/activate

Install the build dependencies:

pip install meson-python numpy cython setuptools

Finally, install the project in "editable" mode:

pip install --no-build-isolation --editable .[dev]

This includes the development dependencies, such as pyTest and Ruff. Within this virtual environment, the package is now readily available via import gripyth in Python code. The --editable flag in the above command means that changes to the source code take effect without the need to reinstall the package.

The --no-build-isolation flag integrates the Meson build system into the development environment so that it can recompile modified Fortran code on the fly. When working on the Fortran routines, it may help to set the environment variable MESONPY_EDITABLE_VERBOSE (to any value) to show compilation logs when rebuilding the package on import.

Add --upgrade to the install command to update external dependencies, such as NumPy and SciPy. This will pull in the latest releases from PyPI, but respect the version constraints defined in pyproject.toml. Except for possibly the Python version, this will replicate the environment in which the CI pipeline (see below) is about to run.

IDE

For Python newcomers, we recommend VS Code / VSCodium and to use the configuration in .vscode/settings.sample.json:

cp .vscode/settings.sample.json .vscode/settings.json

Testing

Quality and correctness of the code base will be checked by the CI pipeline (continuous integration) whenever you push commits to the GitLab repository. If the CI tests pass, all is good. Otherwise amend the commits and push them again.

Alternatively, you may also run the checks locally in your development environment. Either using a plug-in for your IDE (such as VS Code), or manually from the command line:

To check that code is correctly formatted:

ruff format --check

To "lint" the code for common programming errors:

ruff check

To perform a static analysis of all type annotations:

mypy

To run the test suite:

pytest

pyTest will automatically discover the test functions inside the tests folder. Run pytest --cov to additionally display code coverage results, i.e. how much of the code base is covered by the test suite. To generate a coverage report in HTML format, use coverage html --directory=coverage, then point your browser to coverage/index.html.

Documentation

To work on the documentation locally, run

mkdocs serve

from the project root folder, then open http://127.0.0.1:8000 in the browser.