Contributing to TorchOpt

Before contributing to TorchOpt, please follow the instructions below to setup.

  1. Fork TorchOpt (fork) on GitHub and clone the repository.

git clone git@github.com:<your username>/torchopt.git  # use the SSH protocol
cd torchopt

git remote add upstream git@github.com:metaopt/torchopt.git
  1. Setup a development environment via conda / mamba:

# You may need `CONDA_OVERRIDE_CUDA` if conda fails to detect the NVIDIA driver (e.g. in docker or WSL2)
CONDA_OVERRIDE_CUDA=11.7 conda env create --file conda-recipe.yaml

conda activate torchopt
  1. Setup the pre-commit hooks:

pre-commit install --install-hooks

Then you are ready to rock. Thanks for contributing to TorchOpt!

Install Develop Version

To install TorchOpt in an “editable” mode, run:

make install-editable  # or run `pip3 install --no-build-isolation --editable .`

in the main directory. This installation is removable by:

make uninstall

Lint Check

We use several tools to secure code quality, including:

  • Python code style: black, isort, pylint, flake8, ruff

  • Type hint check: mypy

  • C++ Google-style: cpplint, clang-format, clang-tidy

  • License: addlicense

  • Documentation: pydocstyle, doc8

To make things easier, we create several shortcuts as follows.

To automatically format the code, run:

make format

To check if everything conforms to the specification, run:

make lint

Test Locally

This command will run automatic tests in the main directory:

make test

Build Wheels

To build compatible manylinux2014 (PEP 599) wheels for distribution, you can use cibuildwheel. You will need to install docker first. Then run the following command:

pip3 install --upgrade cibuildwheel

export TEST_TORCH_SPECS="cpu cu116"  # `torch` builds for testing
export CUDA_VERSION="11.7"           # version of `nvcc` for compilation
python3 -m cibuildwheel --platform=linux --output-dir=wheelhouse --config-file=pyproject.toml

It will install the CUDA compiler with CUDA_VERSION in the build container. Then build wheel binaries for all supported CPython versions. The outputs will be placed in the wheelhouse directory.

To build a wheel for a specific CPython version, you can use the CIBW_BUILD environment variable. For example, the following command will build a wheel for Python 3.7:

CIBW_BUILD="cp38*manylinux*" python3 -m cibuildwheel --platform=linux --output-dir=wheelhouse --config-file=pyproject.toml

You can change cp38* to cp310* to build for Python 3.10. See https://cibuildwheel.readthedocs.io/en/stable/options for more options.

Documentation

Documentations are written under the docs/source directory as ReStructuredText (.rst) files. index.rst is the main page. A Tutorial on ReStructuredText can be found here.

API References are automatically generated by Sphinx according to the outlines under directory docs/source/api and should be modified when any code changes.

To compile documentation into webpage, run

make docs

The generated webpage locates under directory docs/build and will open the browser after building documentation.

Detailed documentation is hosted online at https://torchopt.readthedocs.io.