Contributing to TorchOpt
Before contributing to TorchOpt, please follow the instructions below to setup.
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
# 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
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
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.