Developer Guide#

Getting Started for Developers#

Warning

The following guide is used only if you want to develop the CTLearn package, if you just want to write code that uses it as a dependency, you can install CTLearn from PyPI. See User Guide.

Installation for Developers#

As a developer, clone the repository and install CTLearn in development mode. We support two methods: pip/venv and Pixi.

Install Pixi if needed, then clone the repository and install the development environment:

$ git clone https://github.com/ctlearn-project/ctlearn.git
$ cd ctlearn
$ pixi install -e dev

Useful commands from the repository directory:

$ pixi run -e dev test            # run the test suite
$ pixi run -e test-py313 test     # run tests with Python 3.13
$ pixi run -e test-py314 test     # run tests with Python 3.14
$ pixi run -e dev make -C docs html
$ pixi shell -e dev               # open a shell in the dev environment
$ pixi clean                      # remove Pixi environments

Pixi targets Linux x86_64 and Apple Silicon macOS.

$ git clone https://github.com/ctlearn-project/ctlearn.git
$ cd ctlearn
$ python -m venv .venv
$ source .venv/bin/activate
$ python -m pip install --upgrade pip
$ python -m pip install -e ".[dev]"

Contributing to CTLearn#

CTLearn is open source and welcomes contributions from the community! CTLearn follows the same code style and development guidelines as the ctapipe community. We recommend reviewing the ctapipe Developer Guide in detail and following the guidelines below:

Contributing guidelines#

In CTLearn we follow the “fork-and-pull” Git workflow:

  • Fork the repository on GitHub

  • Clone the project to your own machine

  • Commit your changes to your own branch

  • Push your work back up to your fork on GitHub

  • Submit a Pull Request so the core developer team can review your changes

Some CI features are unavailable for pull requests from forks. Frequent contributors and those preparing pull requests with significant changes can contact the maintainers to request write access and contribute from a branch in the main repository instead of a fork.

Code quality#

CTLearn uses pre-commit hooks for whitespace and file checks, spelling, and Ruff linting and formatting. Install the development dependencies and set up the hooks in your checkout with:

pip install -e ".[dev]"
pre-commit install

The hooks will run automatically before each commit. To run them manually on all files, use:

pre-commit run --all-files

CI also runs SonarQube analysis through SonarCloud on pull requests from this repository. It checks code quality, including potential bugs, security issues, maintainability, and test coverage.

Documentation builds#

For documentation-only pull requests, apply the documentation-only label to skip the pip and Pixi test jobs and the dependent SonarCloud scan. The documentation build still runs, as do the lint and data-cache jobs and any other applicable workflow checks. Removing the label restores the skipped pull request jobs. The label does not affect push builds, including pushes to main and tags, or the release workflow.

To speed up a pull request’s documentation build, apply the skip-docs-tutorials label. The documentation and tutorial pages are still built, but the tutorials are not executed, so their outputs are omitted. Removing the label restores tutorial execution. Push builds always execute the tutorials, regardless of pull request labels.

Changelog entries#

Every pull request should include a Towncrier fragment describing its user-facing changes. See docs/changes/README.md for the naming conventions and supported categories. If a change does not warrant a changelog entry, maintainers can apply the no-changelog-needed pull request label.

Issues#

Feel free to submit issues and enhancement requests through our issues page on GitHub.

Core Dependencies#

The following list shows CTLearn’s most important dependencies and their minimum versions where specified. We recommend installing the latest releases.

  • python>=3.12

  • torch>=2.4.0

  • tensorflow>=2.18

  • keras>=3.0

  • astropy

  • ctapipe>=0.29.0

  • dl1_data_handler>=0.14.13,<0.15.0

  • numba

  • numpy

  • pandas

  • pyyaml