newton-mcp: Instructions file for Codex

Newton Guidelines

Public API and _src boundary

• newton/_src/ is internal library implementation only.
  • User code, that means Newton examples (under newton/examples/) and documentation, must not import from newton._src.
  • Internal refactors can freely reorganize code under _src as long as the public API stays stable.
• Any user-facing class/function/object added under _src must be exposed via the public Newton API.
  • Add re-exports in the appropriate public module (e.g. newton/geometry.py, newton/solvers.py, newton/sensors.py, etc.).
  • Prefer a single, discoverable public import path. Example: from newton.geometry import BroadPhaseAllPairs (not from newton._src.geometry.broad_phase_all_pairs import BroadPhaseAllPairs).

API design rules (naming + structure)

• Prefix-first naming for discoverability (autocomplete).
  • Classes: ActuatorPD, ActuatorPID (not PDActuator, PIDActuator).
  • Methods: add_shape_sphere() (not add_sphere_shape()).
• Method names are snake_case.
• CLI arguments are kebab-case.
  • Example: --use-cuda-graph (not --use_cuda_graph).
• Prefer nested classes when self-contained.
  • If a helper type or an enum is only meaningful inside one parent class and doesn't need a public identity, define it as a nested class instead of creating a new top-level class/module.
• Follow PEP 8 for Python code.
• Use modern Python type-hint syntax.
  • Prefer PEP 604 unions: x | y, x | None. Do not use typing.Union or typing.Optional.
• Use specific type hints for public interfaces.
  • For Warp arrays, annotate concrete dtypes (e.g., wp.array(dtype=wp.vec3)) rather than generic object.
  • Prefer consistent parameter names across base/override APIs (e.g., xforms, scales, colors, materials).
• Use Google-style docstrings.
  • Write clear, concise docstrings that explain what the function does, its parameters, and its return value.
  • Keep argument/return types in function annotations, not inline in docstrings.
  • In Args: entries, use name: description (not name (Type): description).
  • Use Sphinx cross-reference roles for symbol references (e.g. :class:, :meth:, :attr:, :paramref:), but keep targets as short as possible.
  • Within the same class/module, prefer short local references (e.g. :meth:\log_mesh`, :attr:`model``) over fully qualified paths.
  • If qualification is needed, prefer public API paths (e.g. newton.Mesh) and do not use newton._src in Sphinx role targets.
• State SI units for all physical quantities in docstrings.
  • Use inline [unit] notation, e.g. """Particle positions [m], shape [particle_count, 3], float.""".
  • For joint-type-dependent quantities use [m or rad, depending on joint type].
  • For spatial vectors annotate both components, e.g. [N, N·m].
  • For compound arrays list per-component units, e.g. [0] k_mu [Pa], [1] k_lambda [Pa], ....
  • When a parameter's interpretation varies across solvers, document each solver's convention instead of a single unit.
  • Skip non-physical fields (indices, keys, counts, flags).
  • This rule applies to public API docstrings only, not test docstrings.
• Keep the documentation up-to-date.
  • When adding new files or symbols that are part of the public-facing API, make sure to keep the auto-generated documentation updated by running docs/generate_api.py.
• Add examples to README.md
  • When contributing a new Newton example you must follow the format of the existing examples, where we have an Example class. Then register the example in the appropriate table in README.md with the corresponding uv run command and a screenshot.
  • Ensure your example implements a meaningful test_final() method that is executed after the example has been run to verify the state of the simulation is valid.
  • Optionally you may implement a test_post_step() method that is evaluated after every step() of the example.