C++ API Reference

Overview

NovaPhy's C++ API is organized under the novaphy namespace. All types use float (never double) with Eigen *f type aliases.

Type Aliases

Defined in novaphy/include/novaphy_types.h:

namespace novaphy {
    using Scalar = float;
}

Defined in novaphy/include/math/math_types.h:

namespace novaphy {
    using Vec3f = Eigen::Vector3f;
    using Mat3f = Eigen::Matrix3f;
    using Quatf = Eigen::Quaternionf;
    using VecXf = Eigen::VectorXf;
    using MatXf = Eigen::MatrixXf;
}

Core Types

RigidBody (core/body.h)

Stores inertial properties for a single rigid body: mass, center of mass, body-local inertia tensor, and linear / angular damping.

CollisionShape (core/shape.h)

Shape types: Box, Sphere, Plane, Cylinder, ConvexHull, TriangleMesh. Per-shape flags are stored as the ShapeFlags bitmask (Visible, CollideShapes, CollideParticles, Site, Hydroelastic).

Joint (core/joint.h)

Joint types: Revolute, Fixed, Free, Slide (Prismatic alias in Python-facing docs), Ball, Distance, D6, Cable.

Articulated bodies

Articulated systems are represented in NovaPhy as flat per-link Joint / RigidBody arrays consumed by the Featherstone helpers in dynamics/featherstone/. There is no separate Articulation struct on the C++ side; topology is owned by Model and indexed by joint / body indices.

Model (core/model.h)

Immutable simulation model. Created by ModelBuilder::finalize().

ModelBuilder (core/model_builder.h)

Mutable scene description. Add bodies, shapes, joints, and articulations.

Collision

IBroadphase (collision/ibroadphase.h)

Interface for broadphase collision detection.

SweepAndPrune (collision/broadphase.h)

Default broadphase using sort-based Sweep and Prune.

Narrowphase (collision/narrowphase.h)

Dispatches to specialized collision pair algorithms and generates contact points.

Dynamics

SolverBase (dynamics/solver_base.h)

Newton-aligned forward-dynamics base class. Subclasses are constructed against an immutable Model and driven through the out-of-place step(state_in, state_out, control, contacts, dt) contract:

class SolverBase {
public:
    explicit SolverBase(const Model& model);

    // Uses the constructor-bound Model for topology and gravity.
    virtual void step(const SimState& state_in, SimState& state_out,
                      const Control* control, Contacts* contacts, float dt);

    virtual void notify_model_changed(SolverNotifyFlags flags);
    virtual void update_contacts(Contacts& out, const SimState* state) const;
    virtual JointSupportMatrix joint_support() const;
    virtual SolverBackendInfo backend_info() const;
};

state_in and state_out may alias for in-place stepping; pass distinct buffers when the input buffer must be preserved.

SolverSemiImplicit (dynamics/semi_implicit/solver_semi_implicit.h)

Free-body Sequential Impulse solver with PGS iteration.

SolverFeatherstone (dynamics/featherstone/solver_featherstone.h)

Articulated body solver using Featherstone algorithms.

SolverXPBD (dynamics/xpbd/solver_xpbd.h)

Extended Position Based Dynamics solver.

Fluid

PBFSolver (fluid/pbf_solver.h)

Position Based Fluids solver with SPH kernels and iterative density constraint. Wrapped by SolverPBF (fluid/solver_pbf.h) to expose the Newton-aligned SolverBase.step contract.

SolverSPH (fluid/solver_sph.h)

Smoothed Particle Hydrodynamics solver. Direct SolverBase subclass that owns its particle state (mirrors Newton's SolverImplicitMPM shape).

Simulation

SimState (sim/state.h)

Mutable simulation state: body positions, velocities, joint coordinates. Created from Model::state() and passed by reference into SolverBase::step.

Contacts (core/contacts.h)

Unified structure-of-arrays contact aggregate shared between collision and solvers. Rigid contacts live in rigid_contact_* columns; particle / soft-point contacts live in soft_contact_* columns. Collision is run explicitly through CollisionPipeline::detect_contacts / Model::collide; solvers consume the contact aggregate passed to SolverBase::step.

PerformanceMonitor (sim/performance_monitor.h)

Standalone per-phase timing utility with Chrome / Perfetto trace export. Driven externally with detail::PerformancePhaseScope from C++ or with monitor.scoped(): solver.step(...) from Python; solver public APIs do not take a monitor parameter.

IO

URDFParser (io/urdf_parser.h)

Parse URDF files into NovaPhy articulation structures.

OpenUSDImporter (io/openusd_importer.h)

Import scenes from OpenUSD format.

Building with CMake

find_package(novaphy CONFIG REQUIRED)
target_link_libraries(your_target PRIVATE novaphy::core)

# If using the VBD module:
# target_link_libraries(your_target PRIVATE novaphy::vbd)

Or via add_subdirectory:

add_subdirectory(/path/to/NovaPhy)
target_link_libraries(your_target PRIVATE novaphy::core)