API reference#

Attachment#

ovnewton.attach_ovstage(ovstage_stage, *, model=None, ordinal=1)#

Bind a Newton model to an ovstage.

model=None builds the model from the ovstage — bodies, mass, joints and gravity taken from the populated stage (primitive and triangle-mesh colliders are supported). model=<newton.Model> skips the parse and binds the supplied model, using its body_label / joint_label as the body / joint -> prim-path mapping (the model must have been built from the same USD that populated this ovstage). ordinal bounds the populated payloads used to build or validate the binding and defaults to the conventional initial population ordinal, 1. Ovstage does not retain historical payloads. Returns a StageBinding.

Parameters:

ordinal (int)

class ovnewton.StageBinding(stage, model, *, ordinal=1)#

Correspondence between a Newton model and an ovstage, via the model’s per-index body_label / joint_label (= prim paths). Publishes stepped state to the stage, resyncs it, and exposes selected native state. Stage updates are serialized because they reuse device buffers. Output reads may borrow the supplied state; callers must order state mutation after consumers. Recreate the binding after changing stage topology or runtime layouts.

Parameters:

ordinal (int)

property model#

The connected newton.Model.

query(stage_query=None, *, paths=None)#

Prepare a reusable body/joint selection from a stage query or paths.

Pass either stage_query or paths, but not both. Paths must be unique absolute stage paths. Read results keep body order and preserve joint order within each returned group. Joints with different numbers of values are returned in separate groups. A stage query may also match unrelated prims; those prims are ignored. The returned selection remains valid after the stage query is closed.

Create a new selection after changing the model or stage structure.

Parameters:

  • stage_query (Any)

  • paths (Sequence[str] | None)

Return type:

Query

read(state, *, query=None, attributes)#

Expose selected Newton state arrays as read-only groups.

state must provide the requested arrays. Their sizes must match the connected model, and they must use the same device. If query is omitted, the read includes every available body and joint. attributes accepts body_q, body_qd, joint_q, and joint_qd as names or token IDs.

Body groups and compatible single-width joint groups refer directly to arrays from state and may provide a row map. Other joint selections are gathered once per requested array and split by coordinate width. Use data_row_index(i) or data_index_dlpack() to locate logical prim i. Do not mutate borrowed state until every reader has finished.

CPU data is ready when this method returns. CUDA work does not block the CPU; a reader on another CUDA stream must wait for group.cuda_sync.wait_event.

Parameters:

  • state (Any)

  • query (Query | None)

  • attributes (Sequence[str | int])

Return type:

ReadResult

update_to_ovstage(state, *, ordinal)#

Write the current Newton state to ovstage at ordinal.

This writes body poses, body velocities, and supported one-axis joint positions and velocities. The writes finish before this method returns. Call stage.advance_write_floor(ordinal) to make them visible to readers.

Raises ValueError if an array has the wrong size or device.

update_from_ovstage(state, control, *, ordinal=None)#

Apply all available state and drive targets from ovstage.

If ordinal is omitted, this reads the latest values made visible by the stage. Otherwise, it reads values at or below that ordinal. The method reads all supported state and drive fields; callers cannot select a subset.

Raises ovnewton.OvstageContractError if the stage cannot provide one consistent set of values.

Output reads#

class ovnewton.Query(
binding,
*,
body_index_tensor,
body_indices_host,
body_prim_list,
body_count,
joint_q,
joint_qd,
attributes,
prim_count,
path_lists,
)#

Reusable selection of bound Newton bodies and joints.

Create this object with StageBinding.query(). attributes lists the fields that can be read, and prim_count is the number of selected bodies and joints.

Parameters:

  • binding (Any)

  • body_index_tensor (Any)

  • body_indices_host (Optional[Tuple[int, ...]])

  • body_prim_list (int)

  • body_count (int)

  • joint_q (Any)

  • joint_qd (Any)

  • attributes (Tuple[int, ...])

  • prim_count (int)

  • path_lists (Tuple[int, ...])

class ovnewton.ReadResult(groups)#

Read-only output groups from one read.

A result may refer to arrays from the state passed to StageBinding.read(); it is not always a separate snapshot. Results do not need to be closed or released.

Parameters:

groups (Sequence[ReadGroup])

class ovnewton.ReadGroup(
storage,
*,
attribute,
prim_list,
prim_count,
tensors,
is_array,
data_indices=None,
data_index_tensor=None,
)#

Read-only Newton output group following the ovstage read protocol.

attribute identifies the Newton state field. data_row_index(i) maps path i in prim_list to its row in the tensor.

Keeping the group alive also keeps its data alive. On CUDA, cuda_sync.wait_event identifies when the data is ready.

Parameters:

  • storage (_ReadStorage)

  • attribute (int)

  • prim_list (int)

  • prim_count (int)

  • tensors (Tuple[Any, ...])

  • is_array (bool)

  • data_indices (Optional[Tuple[int, ...]])

  • data_index_tensor (Any)

prim_index(local)#

Return the prim index for row local.

Parameters:

local (int)

Return type:

int

data_row_index(local)#

Return the tensor row for prim local.

Parameters:

local (int)

Return type:

int

tensor(index)#

Return the DLTensor at index.

Parameters:

index (int)

Return type:

Any

array(index)#

Return a read-only NumPy view of a CPU tensor without copying it.

Parameters:

index (int)

dlpack(index, *, readonly=True)#

Return a read-only DLPack view and keep its source data alive.

Parameters:

  • index (int)

  • readonly (bool)

Return type:

Any

data_index_tensor()#

Return the optional raw DLTensor row map.

Return type:

Any

data_index_array()#

Return the optional read-only CPU row map.

data_index_dlpack(*, readonly=True)#

Return the optional read-only DLPack row map.

Parameters:

readonly (bool)

Return type:

Any

class ovnewton.ReadGroupMeta(attribute_write_floor_ordinal=0, layout_generation=0)#

Metadata attached to a generated output group.

Parameters:

  • attribute_write_floor_ordinal (int)

  • layout_generation (int)

class ovnewton.ReadGroupCudaSync(stream=0, wait_event=0)#

CUDA dependency attached to a generated output group.

Parameters:

  • stream (int)

  • wait_event (int)

Errors#

exception ovnewton.InvalidPhysicsError#

The populated stage contains malformed or contradictory physics data.

exception ovnewton.UnsupportedPhysicsError#

The stage uses physics semantics that ovnewton does not implement.

This is reserved for semantics whose loss would materially change physics and for which ovnewton has no exact representation or safe import policy.

exception ovnewton.OvstageContractError#

Ovstage returned data that violates the transport contract ovnewton consumes.