Getting started

We recommend installing uv for dependency management when developing for janus-core.

This provides a number of useful features, including:

Dependencies useful for development can then be installed by running:

uv sync -p 3.12
source .venv/bin/activate

Extras, such as optional MLIPs, can also be installed by running:

uv sync -p 3.12 --extra chgnet --extra sevennet

or to install all MLIPs that do not depend on dgl:

uv sync -p 3.12 --extras all

Using uv

uv manages a persistent environment with the project and its dependencies in a .venv directory, adjacent to pyproject.toml. This will be created automatically as needed.

uv provides two separate APIs for managing your Python project and environment.

uv pip is designed to resemble the pip CLI, with similar commands (uv pip install, uv pip list, uv pip tree, etc.), and is slightly lower level. Compared with pip, uv tends to be stricter, but in most cases uv pip could be used in place of pip.

uv add, uv run, uv sync, and uv lock are known as “project APIs”, and are slightly higher level. These commands interact with (and require) pyproject.toml, and uv will ensure your environment is in-sync when they are called, including creating or updating a lockfile, a universal resolution that is portable across platforms.

When developing for janus-core, it is usually recommended to use project commands, as described in Getting started rather than using uv pip install to modify the project environment manually.

Tip

uv will detect and use Python versions available on your system, but can also be used to install Python automtically. The desired Python version can be specified when running project commands with the --python/-p option.

For further information, please refer to the documentation

Running unit tests

Packages in the dev dependency group allow tests to be run locally using pytest, by running:

pytest -v

Note

MACE must be installed for tests to run successfully. All other MLIPs are optional.

Alternatively, tests can be run in separate virtual environments using tox:

tox run -e ALL

This will run all unit tests for multiple versions of Python, in addition to testing that the pre-commit passes, and that documentation builds, mirroring the automated tests on GitHub.

Individual components of the tox test suite can also be run separately, such as running only running the unit tests with Python 3.9:

tox run -e py39

See the tox documentation for further options.

Automatic coding style check

Packages in the pre-commit dependency group allow automatic code formatting and linting on every commit.

To set this up, run:

pre-commit install

After this, the ruff linter, ruff formatter, and numpydoc (docstring style validator), will run before every commit.

Rules enforced by ruff are currently set up to be comparable to:

The full set of ruff rules are specified by the [tool.ruff] sections of pyproject.toml.

Building the documentation

Packages in the docs dependency group install Sphinx and other Python packages required to build janus-core’s documentation.

It is also necessary to install pandoc on your system.

Individual individual documentation pages can be edited directly:

docs/source/index.rst
docs/source/user_guide/index.rst
docs/source/user_guide/get_started.rst
docs/source/user_guide/tutorial.rst
docs/source/developer_guide/index.rst
docs/source/developer_guide/get_started.rst
docs/source/developer_guide/tutorial.rst
docs/source/apidoc/janus_core.rst

API documentation is automatically generated from docs/source/apidoc/janus_core.rst.

To document a new module, a new block must be added. For example, for the janus_core.calculations.single_point module, the following block was added:

janus\_core.calculations.single\_point module
---------------------------------------------

.. automodule:: janus_core.calculations.single_point
   :members:
   :special-members:
   :private-members:
   :undoc-members:
   :show-inheritance:

Sphinx can then be used to generate the html documentation:

cd docs
make clean; make html

Notebook tutorials

Jupyter notebooks in docs/source/tutorials are automatically run by Sphinx using the nbsphinx extension, creating the Tutorials.

These are tested before janus-core is published to PyPI, but can be tested locally by running:

cd docs
make clean; make tutorials

Continuous integration

janus-core comes with a .github folder that contains continuous integration workflows that run on every push and pull request using GitHub Actions. These will:

  1. Run all non-optional unit tests

  2. Build the documentation

  3. Check the coding style conforms by running the pre-commit described above

  4. Build and publish tagged commits to PyPI