novaphy

The top-level novaphy namespace is the primary import root for scene construction, immutable models, runtime buffers, joints, geometry, contact data, and engine-wide utilities. Solver classes and configuration objects intentionally live in novaphy.solvers instead of the top level (mirroring newton.solvers). novaphy.geometry is also an importable compatibility module; the novaphy.math, novaphy.io, and novaphy.utils pages are conceptual groupings of top-level symbols.

import novaphy

Build Pipeline

The canonical NovaPhy data flow is:

ModelBuilder  ──finalize──▶  Model  ──state()/control() + CollisionPipeline.contacts()──▶ runtime buffers
                                │                                          │
                                ├── CollisionPipeline.collide(state, contacts)
                                │                                          ▼
                                └── SolverBase.step(state_in, state_out, control, contacts, dt)

A minimal end-to-end example:

import numpy as np
import novaphy

builder = novaphy.ModelBuilder()
builder.add_ground_plane(y=0.0)

body = novaphy.RigidBody.from_box(1.0, np.array([0.5, 0.5, 0.5], dtype=np.float32))
idx = builder.add_body(body, novaphy.Transform.from_translation(np.array([0, 5, 0])))
builder.add_shape(novaphy.CollisionShape.make_box(np.array([0.5, 0.5, 0.5]), idx))

model = builder.finalize()
solver = novaphy.solvers.SolverSemiImplicit(model)

state    = model.state()
control  = model.control()
pipeline = novaphy.CollisionPipeline(model)
contacts = pipeline.contacts()

for _ in range(600):
    state.clear_forces()
    pipeline.collide(state, contacts)
    solver.step(state, state, control, contacts, 1.0 / 120.0)

For a fuller walkthrough including setup, runtime contract, and partner integration notes, see the Quick Start guide.

Multi-Env Runtime Notes

MultiEnvRunner is a lightweight RL runtime wrapper for a solver-bound multi-world Model. It owns double-buffered SimState, Control, and Contacts buffers and delegates physics to the existing SolverBase.step(state_in, state_out, control, contacts, dt) contract; it is not a simulation World object.

MultiEnvLayout.env_origins is task / viewer metadata. Runner layout setters such as set_env_origins(), set_linear_layout(), and set_grid_layout() do not mutate the immutable Model.world_origins captured during ModelBuilder.finalize().

When runner collision is enabled, replicated worlds share broadphase storage, but pairs whose two non-global shapes have different world indices are filtered automatically. Shapes with world=-1 are global and may interact with every world.

Python properties such as episode_length, terminated, truncated, and env_origins return NumPy copies. In-place edits to those arrays do not write back; use reset_envs(), reset_all(), set_done_flags(), or the layout setter methods to modify runner-owned state.

Classes

Class	Description
AABB	Axis-aligned bounding box.
Axis	Coordinate-axis enumeration.
BodyFlags	Dynamic / kinematic body filter bitmask used by articulation evaluators.
BroadPhaseMode	Collision broadphase mode.
BroadPhasePair	Candidate pair emitted by standalone broadphase utilities.
ColoringAlgorithm	Graph-coloring mode used by ModelBuilder.color().
CollisionFilterPair	Disabled shape pair entry for narrowphase filtering.
CollisionPipeline	Broad + narrow phase collision pipeline used before solver steps.
CollisionShape	Collision shape descriptor.
Contacts	Structure-of-arrays contact aggregate (rigid_contact_*, soft_contact_*).
Control	Caller-owned runtime control inputs (joint forces, targets).
CudaGraphCapture	Driver-level CUDA graph capture helper for external capture loops.
Device	CPU / CUDA device descriptor.
DeviceArray concrete classes	Concrete device-buffer wrappers used by Model, SimState, Control, and Contacts.
DeviceType	Device kind enum.
EqType	Equality-constraint type (CONNECT, WELD, or JOINT).
HydroelasticSdfConfig	Runtime hydroelastic SDF contact and pressure-law configuration.
IndexRange	Half-open range into a flat model buffer.
Joint	Per-link joint descriptor used by Featherstone helpers.
JointDofConfig	Per-DOF joint configuration consumed by ModelBuilder.add_joint_*.
JointTargetMode	Per-DOF drive mode (NONE, POSITION, VELOCITY, POSITION_VELOCITY, or EFFORT).
JointType	Joint type enumeration.
Mesh	Triangle mesh with optional precomputed inertia.
Model	Immutable simulation model produced by ModelBuilder.finalize().
ModelBuilder	Mutable scene builder for bodies, shapes, joints, articulations, particles, and imported assets.
ModelWorldRange	Per-world ranges into bodies, shapes, joints, particles, and constraint buffers.
MultiEnvLayout	Runtime layout metadata for batched logical env origins.
MultiEnvRunner	RL-style multi-world runtime wrapper over SolverBase.step(...).
PressureCompileError	Error raised for unsupported custom hydroelastic pressure laws.
RigidBody	Rigid body mass and inertia descriptor.
ShapeConfig	Shape parameters consumed by ModelBuilder.add_shape_*.
ShapeFlags	Shape visibility and collision bit flags.
ShapeType	Collision shape type enumeration.
SimState	Caller-owned runtime body / particle / joint state.
Site	Named attachment point used by sensors and importers.
SpatialTransform	6D spatial transform for Featherstone algebra.
StateFlags	Bitmask selecting state arrays for solver reset methods.
SweepAndPrune	Standalone SAP broadphase utility.
Transform	3D rigid transform (position + rotation).
VbdKinematicBodyBoundaryCuda	CUDA kinematic rigid-boundary helper for VBD demos.
VbdParticleTwistBoundaryCuda	CUDA particle twist-boundary helper for VBD cloth demos.

Functions

Function	Description
axis_to_vec3()	Convert an Axis enum value to a 3D unit vector.
apply_particle_contact_reactions()	Apply particle velocity reactions from Contacts.soft_contact_*.
apply_particle_coupling_contacts()	Apply particle / soft-point contact forces back to rigid bodies.
batch_transform_vertices()	Transform indexed batches of local vertices into a preallocated world-space buffer.
clear_current_cuda_stream()	Clear NovaPhy's thread-local CUDA stream override.
eval_fk()	Newton-aligned forward kinematics over a Model and SimState.
eval_ik()	Evaluate inverse kinematics from maximal body state into flat joint arrays.
eval_jacobian()	Return or fill per-articulation Jacobian matrices.
eval_mass_matrix()	Return or fill per-articulation generalized mass matrices.
current_cuda_stream()	Return the current thread-local CUDA stream pointer.
current_cuda_stream_is_capturing()	Report whether the current CUDA stream is under capture.
has_ipc()	Returns whether the package was built with IPC / libuipc support.
has_featherstone_cuda()	Returns whether the Featherstone CUDA backend is available.
has_mujoco_cuda()	Returns whether the native SolverMuJoCo CUDA backend is available.
has_sph_cuda()	Returns whether the SPH CUDA backend is available.
has_vbd_cuda()	Returns whether the SolverVBD CUDA backend is available.
has_vbd_dlan()	Returns whether the SolverVBD Denglin DLAN backend is available.
pressure_func()	Mark a Python function for hydroelastic pressure-law compilation.
set_current_cuda_stream()	Install an opaque CUDA stream pointer for NovaPhy kernels on this thread.
synchronize_current_cuda_stream()	Synchronize the current CUDA stream or device fallback.
version()	Returns the engine version string.

Constants

Name	Description
__version__	Same string as novaphy.version().

Compatibility aliases

Name	Description
GeoType	Alias of ShapeType.
HydroelasticSDF	Alias of novaphy.geometry.HydroelasticSDF, a compatibility namespace whose nested Config dataclass stores option values. Use HydroelasticSdfConfig for the executable collision-pipeline configuration.

Submodules

Submodule	Purpose
novaphy.actuators	Actuator framework.
novaphy.ik	Implemented class-style IK objectives/optimizers plus compatible free-function helpers.
novaphy.sensors	Sensor framework.
novaphy.solvers	Solver classes and configuration.