Development Guide

This document is a guide for developers who want to contribute to the project.

Environment setup

Clone the repository

git clone git@github.com:newton-physics/newton.git
cd newton

Using uv

uv is a Python package and project manager.

Install uv:

# On macOS and Linux.
curl -LsSf https://astral.sh/uv/install.sh | sh

# On Windows.
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Run basic examples:

# An example with basic dependencies
uv run newton/examples/example_quadruped.py

# An example that requires extras
uv run --all-extras newton/examples/example_humanoid.py

Updating all dependencies in the project lockfile, remember to commit uv.lock after running:

uv lock -U

Using venv

These instructions are meant for users who wish to set up a development environment using venv or Conda (e.g. from Miniforge).

python -m venv .venv

# On macOS and Linux.
source .venv/bin/activate

# On Windows (console).
.venv\Scripts\activate.bat

# On Windows (PowerShell).
.venv\Scripts\Activate.ps1

Installing dependencies including optional ones:

python -m pip install mujoco --pre -f https://py.mujoco.org/
python -m pip install warp-lang --pre -U -f https://pypi.nvidia.com/warp-lang/
python -m pip install git+https://github.com/google-deepmind/mujoco_warp.git@main
python -m pip install -e .[dev]

Run basic examples:

# An example with basic dependencies
python newton/examples/example_quadruped.py

# An example that requires extras
python newton/examples/example_humanoid.py

Running the tests

The Newton test suite can be run with uv run -m newton.tests or python -m newton.tests. By default, the test suite execution will be parallelized on up to eight processes. Pass the --help flag to see the available options for the test runner.

Some tests use optional dependencies like usd-core and will be skipped if they are not installed.

When using uv, the test suite can be run with all extras installed by running:

uv run --all-extras -m newton.tests

When using venv, the extras for the test suite can be installed by running python -m pip install -e .[dev] from the root of the repository.

A code coverage report requires installing coverage[toml] and can be generated by appending the --coverage --coverage-html flags to the test command, e.g.

uv run --all-extras -m newton.tests --coverage --coverage-html htmlcov

The file htmlcov/index.html can be opened with a web browser to view the coverage report.

Code formatting and linting

Ruff is used for Python linting and code formatting. pre-commit can be used to ensure that local code complies with Newton’s checks. From the top of the repository, run:

# With uv installed
uvx pre-commit run -a

# With venv
python -m pip install pre-commit
pre-commit run -a

To automatically run pre-commit hooks with git commit:

# With uv installed
uvx pre-commit install

# With venv
pre-commit install

The hooks can be uninstalled with pre-commit uninstall.

Building the documentation

Here are a few ways to build the documentation.

Using uv

rm -rf docs/_build
uv run --extra docs sphinx-build -W -b html docs docs/_build/html

# Alternatively using the Makefile
uv sync --extra docs
source .venv/bin/activate
cd docs
make clean
make html

Using venv

python -m pip install -e .[docs]
python -m sphinx -W -b html docs docs/_build/html

# Alternatively using the Makefile
cd docs
make clean
make html

Testing documentation code snippets

The doctest Sphinx builder is used to ensure that code snippets in the documentation remains up-to-date.

The doctests can be run with:

# With uv installed
uv run --extra docs sphinx-build -W -b doctest docs docs/_build/doctest

# With venv
python -m sphinx -W -b doctest docs docs/_build/doctest

For more information, see the sphinx.ext.doctest documentation.

Packaging

To build a .whl file (e.g. to test the creation of a distribution package), run:

uv build --wheel

The output will be placed in the dist/ subdirectory.