Skip to content

novaphy.CollisionPipeline

Newton-style explicit collision pipeline handle. A thin per-model descriptor that selects the broadphase backend and produces matching Contacts aggregates. Solvers consume contacts but do not run broadphase or narrowphase internally, so most simulation loops create one pipeline and call pipeline.collide(...) before solver.step(...).

Constructor

CollisionPipeline(
    model: Model,
    broad_phase: BroadPhaseMode | str | None = None,
    *,
    reduce_contacts: bool = True,
    rigid_contact_max: int | None = None,
    shape_pairs_max: int | None = None,
    max_triangle_pairs: int | None = None,
    soft_contact_max: int | None = None,
    soft_contact_margin: float | None = None,
    deterministic: bool = False,
    contact_matching: str = "disabled",
    contact_report: bool = False,
    sdf_hydroelastic_config: HydroelasticSdfConfig | None = None,
)
Parameter Description
model The Model the pipeline runs against.
broad_phase None to use the model default, a BroadPhaseMode, or one of "explicit", "nxn" / "all_pairs", "sap".
reduce_contacts Reduce candidate contact points to the solver-facing manifold set.
rigid_contact_max, shape_pairs_max, max_triangle_pairs, soft_contact_max Optional positive capacity overrides.
soft_contact_margin Optional soft-contact distance margin override.
deterministic Enable deterministic ordering where supported.
contact_matching "disabled", "latest", or "sticky" frame-to-frame matching.
contact_report Request new/broken contact-report columns on Contacts objects subsequently allocated by this pipeline. Requires contact_matching != "disabled".
sdf_hydroelastic_config Optional HydroelasticSdfConfig override.

Properties

Property Description
broad_phase Read-only BroadPhaseMode used by this pipeline.
reduce_contacts Whether contact reduction is enabled.
deterministic Whether deterministic ordering is requested.
contact_matching Current matching mode name.
contact_report Whether contact-report allocation is requested for subsequently created Contacts objects.
rigid_contact_max, shape_pairs_max, max_triangle_pairs, soft_contact_max Resolved capacities.
soft_contact_margin Current soft-contact margin; writable.
sdf_hydroelastic_config Current Python hydroelastic SDF configuration; writable as a whole. Mutate a retrieved config and reassign the property to synchronize the C++ pipeline.
last_candidate_pair_count Candidate pairs produced by the last collision pass.
last_candidate_pair_overflow_count Candidate pairs dropped because capacity was exhausted.
last_rigid_contact_overflow_count Rigid contacts dropped because capacity was exhausted.
last_soft_contact_overflow_count Soft contacts dropped because capacity was exhausted.
last_triangle_pair_overflow_count Triangle pairs dropped because capacity was exhausted.

Methods

Method Description
contacts() Allocate a Contacts aggregate sized for the bound model.
collide(state, contacts=None) Run collision detection against state. Populates and returns contacts, or allocates one when None.
refresh_diagnostics() Explicitly copy CUDA collision diagnostic counters back to the host.

Example

import novaphy

pipeline = novaphy.CollisionPipeline(model, broad_phase="sap")
contacts = pipeline.contacts()
pipeline.collide(state, contacts)
solver.step(state, state, control, contacts, dt)

To update hydroelastic options after construction, reassign the whole configuration:

hydro = pipeline.sdf_hydroelastic_config
hydro.buffer_fraction = 0.7
pipeline.sdf_hydroelastic_config = hydro

Mutating the retrieved Python object without the final assignment does not update the C++ collision pipeline.

Notes

  • Filter pairs are configured on the Model (via CollisionFilterPair entries passed to ModelBuilder); they apply globally regardless of which pipeline is in use.
  • The Python binding is not copyable or pickleable. Create a pipeline for the desired model and configuration, then reuse it across simulation steps.

See Also