{"owner":"newton-physics","repo":"newton","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["AGENTS.md"],"skills":{"AGENTS.md":"# Newton Development Guidelines\n\n- `newton/_src/` is internal. Examples and docs must not import from `newton._src`. Expose user-facing symbols via public modules (`newton/geometry.py`, `newton/solvers.py`, etc.).\n- Breaking changes require a deprecation first. Do not remove or rename public API symbols without deprecating them in a prior release.\n- Prefix-first naming for autocomplete: `ActuatorPD` (not `PDActuator`), `add_shape_sphere()` (not `add_sphere_shape()`).\n- Prefer nested classes for self-contained helper types/enums.\n- PEP 604 unions (`x | None`, not `Optional[x]`).\n- Annotate Warp arrays with bracket syntax (`wp.array[wp.vec3]`, `wp.array2d[float]`, `wp.array[Any]`), not the parenthesized form (`wp.array(dtype=...)`). Use `wp.array[X]` for 1-D arrays, not `wp.array1d[X]`.\n- Follow Google-style docstrings. Types in annotations, not docstrings. `Args:` use `name: description`.\n  - Sphinx cross-refs (`:class:`, `:meth:`) with shortest possible targets. Prefer public API paths; never use `newton._src`.\n  - SI units for physical quantities in public API docstrings: `\"\"\"Particle positions [m], shape [particle_count, 3].\"\"\"`. Joint-dependent: `[m or rad]`. Spatial vectors: `[N, N·m]`. Compound arrays: per-component. Skip non-physical fields.\n- Code comments: brief, and only for non-obvious code. Explain *why* (intent, constraints, edge cases), not *what* the code already shows. Prefer a cross-reference (doc, `:class:`/`:meth:`) over re-explaining context.\n- Run `docs/generate_api.py` when adding public API symbols.\n- Before relying on or changing a documented claim, open the relevant internal cross-references and external primary-source links. Verify Newton-specific behavior against the current code; if a linked source is unavailable, state that limitation instead of assuming it supports the claim.\n- Avoid new required dependencies. Strongly prefer not adding optional ones — use Warp, NumPy, or stdlib.\n- Create a feature branch before committing — never commit directly to `main`. Use `<username>/feature-desc`.\n- Imperative mood in commit messages (\"Fix X\", not \"Fixed X\"), ~50 char subject, body wraps at 72 chars explaining _what_ and _why_.\n- Verify regression tests fail without the fix before committing.\n- Pin GitHub Actions by SHA: `action@<sha>  # vX.Y.Z`. Check `.github/workflows/` for allowlisted hashes.\n- In SPDX copyright lines, use the year the file was first created. Do not create date ranges or update the year when modifying a file.\n\nRun `uvx pre-commit run -a` to lint/format before committing. Use `uv` for all commands; fall back to `venv`/`conda` if unavailable.\n\n```bash\n# Examples\nuv sync --extra examples\nuv run -m newton.examples basic_pendulum\n```\n\n## Tests\n\nAlways use `unittest`, not pytest.\n\n```bash\nuv run --extra dev -m newton.tests\nuv run --extra dev -m newton.tests -k test_viewer_log_shapes           # specific test\nuv run --extra dev -m newton.tests -k test_basic.example_basic_shapes  # example test\nuv run --extra dev --extra torch-cu12 -m newton.tests                  # with PyTorch\n```\n\n### Testing guidelines\n\n- Give every test function or method a docstring using triple double quotes (`\"\"\"...\"\"\"`). Start with a concise one-line summary in imperative mood that states what the test verifies. For a particularly complex test, add a body that elaborates on the tested behavior, separated from the summary by a blank line following Google-style docstring conventions.\n- Never call `wp.synchronize()` or `wp.synchronize_device()` right before `.numpy()` on a Warp array. This is redundant as `.numpy()` performs a synchronous device-to-host copy that completes all outstanding work.\n\n```bash\n# Benchmarks\nuvx --with virtualenv asv run --launch-method spawn main^!\n```\n\n## PR Instructions\n\n- If opening a pull request on GitHub, use the template in `.github/PULL_REQUEST_TEMPLATE.md`.\n- Follow `changelog/README.md`: add a Towncrier fragment for user-facing changes instead of editing `CHANGELOG.md` directly. A `.skip` reason is optional for changes without user-facing impact.\n- Preview fragments with `uvx --from towncrier==25.8.0 towncrier build --draft --version X.Y.Z --date YYYY-MM-DD`.\n\n## Examples\n\n- Follow the `Example` class format.\n  - Implement `test_final()` — runs after the example completes to verify simulation state is valid.\n  - Optionally implement `test_post_step()` — runs after every `step()` for per-step validation.\n- Register in `README.md` with `python -m newton.examples <name>` command and a 320x320 jpg screenshot.\n"},"files":{"AGENTS.md":"# Newton Development Guidelines\n\n- `newton/_src/` is internal. Examples and docs must not import from `newton._src`. Expose user-facing symbols via public modules (`newton/geometry.py`, `newton/solvers.py`, etc.).\n- Breaking changes require a deprecation first. Do not remove or rename public API symbols without deprecating them in a prior release.\n- Prefix-first naming for autocomplete: `ActuatorPD` (not `PDActuator`), `add_shape_sphere()` (not `add_sphere_shape()`).\n- Prefer nested classes for self-contained helper types/enums.\n- PEP 604 unions (`x | None`, not `Optional[x]`).\n- Annotate Warp arrays with bracket syntax (`wp.array[wp.vec3]`, `wp.array2d[float]`, `wp.array[Any]`), not the parenthesized form (`wp.array(dtype=...)`). Use `wp.array[X]` for 1-D arrays, not `wp.array1d[X]`.\n- Follow Google-style docstrings. Types in annotations, not docstrings. `Args:` use `name: description`.\n  - Sphinx cross-refs (`:class:`, `:meth:`) with shortest possible targets. Prefer public API paths; never use `newton._src`.\n  - SI units for physical quantities in public API docstrings: `\"\"\"Particle positions [m], shape [particle_count, 3].\"\"\"`. Joint-dependent: `[m or rad]`. Spatial vectors: `[N, N·m]`. Compound arrays: per-component. Skip non-physical fields.\n- Code comments: brief, and only for non-obvious code. Explain *why* (intent, constraints, edge cases), not *what* the code already shows. Prefer a cross-reference (doc, `:class:`/`:meth:`) over re-explaining context.\n- Run `docs/generate_api.py` when adding public API symbols.\n- Before relying on or changing a documented claim, open the relevant internal cross-references and external primary-source links. Verify Newton-specific behavior against the current code; if a linked source is unavailable, state that limitation instead of assuming it supports the claim.\n- Avoid new required dependencies. Strongly prefer not adding optional ones — use Warp, NumPy, or stdlib.\n- Create a feature branch before committing — never commit directly to `main`. Use `<username>/feature-desc`.\n- Imperative mood in commit messages (\"Fix X\", not \"Fixed X\"), ~50 char subject, body wraps at 72 chars explaining _what_ and _why_.\n- Verify regression tests fail without the fix before committing.\n- Pin GitHub Actions by SHA: `action@<sha>  # vX.Y.Z`. Check `.github/workflows/` for allowlisted hashes.\n- In SPDX copyright lines, use the year the file was first created. Do not create date ranges or update the year when modifying a file.\n\nRun `uvx pre-commit run -a` to lint/format before committing. Use `uv` for all commands; fall back to `venv`/`conda` if unavailable.\n\n```bash\n# Examples\nuv sync --extra examples\nuv run -m newton.examples basic_pendulum\n```\n\n## Tests\n\nAlways use `unittest`, not pytest.\n\n```bash\nuv run --extra dev -m newton.tests\nuv run --extra dev -m newton.tests -k test_viewer_log_shapes           # specific test\nuv run --extra dev -m newton.tests -k test_basic.example_basic_shapes  # example test\nuv run --extra dev --extra torch-cu12 -m newton.tests                  # with PyTorch\n```\n\n### Testing guidelines\n\n- Give every test function or method a docstring using triple double quotes (`\"\"\"...\"\"\"`). Start with a concise one-line summary in imperative mood that states what the test verifies. For a particularly complex test, add a body that elaborates on the tested behavior, separated from the summary by a blank line following Google-style docstring conventions.\n- Never call `wp.synchronize()` or `wp.synchronize_device()` right before `.numpy()` on a Warp array. This is redundant as `.numpy()` performs a synchronous device-to-host copy that completes all outstanding work.\n\n```bash\n# Benchmarks\nuvx --with virtualenv asv run --launch-method spawn main^!\n```\n\n## PR Instructions\n\n- If opening a pull request on GitHub, use the template in `.github/PULL_REQUEST_TEMPLATE.md`.\n- Follow `changelog/README.md`: add a Towncrier fragment for user-facing changes instead of editing `CHANGELOG.md` directly. A `.skip` reason is optional for changes without user-facing impact.\n- Preview fragments with `uvx --from towncrier==25.8.0 towncrier build --draft --version X.Y.Z --date YYYY-MM-DD`.\n\n## Examples\n\n- Follow the `Example` class format.\n  - Implement `test_final()` — runs after the example completes to verify simulation state is valid.\n  - Optionally implement `test_post_step()` — runs after every `step()` for per-step validation.\n- Register in `README.md` with `python -m newton.examples <name>` command and a 320x320 jpg screenshot.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Newton Development Guidelines\n\n- `newton/_src/` is internal. Examples and docs must not import from `newton._src`. Expose user-facing symbols via public modules (`newton/geometry.py`, `newton/solvers.py`, etc.).\n- Breaking changes require a deprecation first. Do not remove or rename public API symbols without deprecating them in a prior release.\n- Prefix-first naming for autocomplete: `ActuatorPD` (not `PDActuator`), `add_shape_sphere()` (not `add_sphere_shape()`).\n- Prefer nested classes for self-contained helper types/enums.\n- PEP 604 unions (`x | None`, not `Optional[x]`).\n- Annotate Warp arrays with bracket syntax (`wp.array[wp.vec3]`, `wp.array2d[float]`, `wp.array[Any]`), not the parenthesized form (`wp.array(dtype=...)`). Use `wp.array[X]` for 1-D arrays, not `wp.array1d[X]`.\n- Follow Google-style docstrings. Types in annotations, not docstrings. `Args:` use `name: description`.\n  - Sphinx cross-refs (`:class:`, `:meth:`) with shortest possible targets. Prefer public API paths; never use `newton._src`.\n  - SI units for physical quantities in public API docstrings: `\"\"\"Particle positions [m], shape [particle_count, 3].\"\"\"`. Joint-dependent: `[m or rad]`. Spatial vectors: `[N, N·m]`. Compound arrays: per-component. Skip non-physical fields.\n- Code comments: brief, and only for non-obvious code. Explain *why* (intent, constraints, edge cases), not *what* the code already shows. Prefer a cross-reference (doc, `:class:`/`:meth:`) over re-explaining context.\n- Run `docs/generate_api.py` when adding public API symbols.\n- Before relying on or changing a documented claim, open the relevant internal cross-references and external primary-source links. Verify Newton-specific behavior against the current code; if a linked source is unavailable, state that limitation instead of assuming it supports the claim.\n- Avoid new required dependencies. Strongly prefer not adding optional ones — use Warp, NumPy, or stdlib.\n- Create a feature branch before committing — never commit directly to `main`. Use `<username>/feature-desc`.\n- Imperative mood in commit messages (\"Fix X\", not \"Fixed X\"), ~50 char subject, body wraps at 72 chars explaining _what_ and _why_.\n- Verify regression tests fail without the fix before committing.\n- Pin GitHub Actions by SHA: `action@<sha>  # vX.Y.Z`. Check `.github/workflows/` for allowlisted hashes.\n- In SPDX copyright lines, use the year the file was first created. Do not create date ranges or update the year when modifying a file.\n\nRun `uvx pre-commit run -a` to lint/format before committing. Use `uv` for all commands; fall back to `venv`/`conda` if unavailable.\n\n```bash\n# Examples\nuv sync --extra examples\nuv run -m newton.examples basic_pendulum\n```\n\n## Tests\n\nAlways use `unittest`, not pytest.\n\n```bash\nuv run --extra dev -m newton.tests\nuv run --extra dev -m newton.tests -k test_viewer_log_shapes           # specific test\nuv run --extra dev -m newton.tests -k test_basic.example_basic_shapes  # example test\nuv run --extra dev --extra torch-cu12 -m newton.tests                  # with PyTorch\n```\n\n### Testing guidelines\n\n- Give every test function or method a docstring using triple double quotes (`\"\"\"...\"\"\"`). Start with a concise one-line summary in imperative mood that states what the test verifies. For a particularly complex test, add a body that elaborates on the tested behavior, separated from the summary by a blank line following Google-style docstring conventions.\n- Never call `wp.synchronize()` or `wp.synchronize_device()` right before `.numpy()` on a Warp array. This is redundant as `.numpy()` performs a synchronous device-to-host copy that completes all outstanding work.\n\n```bash\n# Benchmarks\nuvx --with virtualenv asv run --launch-method spawn main^!\n```\n\n## PR Instructions\n\n- If opening a pull request on GitHub, use the template in `.github/PULL_REQUEST_TEMPLATE.md`.\n- Follow `changelog/README.md`: add a Towncrier fragment for user-facing changes instead of editing `CHANGELOG.md` directly. A `.skip` reason is optional for changes without user-facing impact.\n- Preview fragments with `uvx --from towncrier==25.8.0 towncrier build --draft --version X.Y.Z --date YYYY-MM-DD`.\n\n## Examples\n\n- Follow the `Example` class format.\n  - Implement `test_final()` — runs after the example completes to verify simulation state is valid.\n  - Optionally implement `test_post_step()` — runs after every `step()` for per-step validation.\n- Register in `README.md` with `python -m newton.examples <name>` command and a 320x320 jpg screenshot.\n","category":"root","tokens":1133}]}