Development Setup¶

Prerequisites¶

Python 3.10 or later is required. warp-lang and numpy are the only required runtime dependencies. Tests, benchmarks, and oracle comparisons need the dev extra (torch, scipy, matplotlib, pytest).

Editable install with the dev extra¶

Using uv (recommended):

# Install uv if not already present
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a project venv — uv fetches Python 3.12 if it isn't present
uv venv --python 3.12

# Install track_gen (editable) with all dev dependencies
uv pip install -e ".[dev]"

Using plain venv and pip:

python -m venv .venv
.venv/bin/pip install -e ".[dev]"

Both approaches create a .venv/ directory. Run anything inside it with .venv/bin/python … (or source .venv/bin/activate, or uv run …).

Running the test suite¶

Warning

Always run pytest with the PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 environment variable set.

The system-wide ROS 2 Humble installation at /opt/ros/humble ships broken pytest plugins that are picked up automatically by pytest’s plugin discovery. Without this variable, test collection fails before a single test runs.

Example fast-lane command (copy-paste ready):

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .venv/bin/python -m pytest -q -m "not slow and not benchmark and not cuda"

Fast lane¶

Skips slower quality gates, benchmark checks, and CUDA-only graph tests. Suitable for rapid iteration during development:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .venv/bin/python -m pytest -q -m "not slow and not benchmark and not cuda"

Full suite¶

Runs all tests. CUDA-only assertions are skipped automatically when no CUDA device is available:

PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 .venv/bin/python -m pytest -q

Pytest markers¶

Marker	Meaning
`slow`	Quality gates that are useful but heavier than smoke tests.
`benchmark`	Benchmark harness checks.
`cuda`	Tests that require a CUDA device; skipped automatically when CUDA is unavailable.

Additional development commands¶

Compare every registered centerline generator on quality, diversity, and speed:

.venv/bin/python -m benchmarks.compare_generators --E 512 --seed 0

End-to-end pipeline benchmark (auto device, E=8192):

# Capture and time the CUDA graph
.venv/bin/python -m benchmarks.benchmark_pipeline --graph

# CPU run with a smaller batch
.venv/bin/python -m benchmarks.benchmark_pipeline --E 2048 --cpu

Render sample tracks without launching the interactive UI:

.venv/bin/python -m viz.plot_tracks --images 1 --rows 4 --cols 4 --cpu