API reference#

Package#

ovnewton.__version__: str = '0.2.1'#

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

Attachment#

ovnewton.register_usd_schemas()#

Register ovnewton’s USD schemas before the first USD schema read.

Registration is process-wide, irreversible, and safe to repeat. It must run before any USD schema definitions are read in the process, including by an ovstage population or export call.

Return type:

None

ovnewton.population_desc()#

Select physics data and composed API-schema names for ovnewton imports.

Use with population.open_usd_with_desc (or its string variant), alongside any rendering descriptors. This preserves unregistered schema names and supported MuJoCo joint and equality parameters, allowing the importer to identify equalities and detect unsupported physics. It does not register plugins or repopulate a stage; call ovnewton.register_usd_schemas() before the first population operation.

Return type:

population.Desc

ovnewton.add_ovstage(builder, ovstage_stage, *, ordinal=1)#

Add one populated ovstage’s model data to a caller-owned Newton builder.

The current implementation supports one ovstage per builder. builder must not contain model entities, but its defaults and custom attribute definitions may be configured. This function applies the stage’s up axis and gravity, adds the stage-backed entities, and returns without finalizing the builder or creating a StageBinding. Callers may perform solver-specific preparation afterwards.

Populate USD inputs with ovnewton.population_desc() (or an equivalent descriptor) so unsupported authored API names survive schema population. This function cannot detect names discarded before import.

Supported surface cloth retains its publication mappings through Newton’s custom model attributes. For VBD cloth, call builder.color(include_bending=True) before finalization, then bind the finalized model with attach_ovstage(stage, model=model).

ordinal bounds the populated payloads read from the stage. The returned metadata reports whether preserving rootless joints requires skipping Newton’s articulation-membership validation during finalization.

Parameters:

  • builder (newton.ModelBuilder)

  • ovstage_stage (ovstage.Stage)

  • ordinal (int)

Return type:

OvstageImportResult

class ovnewton.OvstageImportResult(has_orphan_joints=False)#

Information needed to finalize a builder populated from ovstage.

has_orphan_joints is true when the USD intentionally leaves joints outside an articulation. Preserve that topology with builder.finalize(skip_validation_joints=result.has_orphan_joints).

Parameters:

has_orphan_joints (bool)

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

Create a StageBinding for an ovstage and a Newton model.

When model is supplied, this function binds it without importing or finalizing anything. Its body_label and joint_label values must match prim paths in the ovstage.

When model is None, this function creates a newton.ModelBuilder, adds the ovstage contents, finalizes the model, and binds it. Call add_ovstage() directly when the application needs to configure the builder before finalization.

For imports, populate USD inputs with ovnewton.population_desc() or an equivalent descriptor to preserve unsupported authored API names.

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.

Parameters:

  • ovstage_stage (ovstage.Stage)

  • model (newton.Model | None)

  • ordinal (int)

Return type:

StageBinding

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

Connect a Newton model to an ovstage through the model’s body and joint labels.

Writes simulation state to ovstage, reads stage changes into Newton, and lets applications read selected Newton state or model arrays. Writes run one at a time because they reuse buffers. A read may borrow arrays from its supplied state or from the bound model; do not change those arrays until every reader has finished. Recreate the binding after changing the model or stage structure.

Parameters:

  • stage (ovstage.Stage)

  • model (newton.Model)

  • ordinal (int)

property model: newton.Model#

The connected newton.Model.

query(
stage_query=None,
*,
paths=None,
object_type=None,
scope=ObjectScope.ALL,
)#

Prepare a reusable output selection from a stage query or paths.

Pass either stage_query or paths, but not both. When object_type is provided, both may be omitted to select every object of that type. Paths must be unique absolute paths. Bound bodies, articulation roots, the effective physics scene, and authored joints use stage prim paths; generated Newton joints may use model-only labels. 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. ObjectScope.ALL is supported. Active and changed-since membership are not yet supported. 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 (ovstage.Query | None)

  • paths (Optional[Sequence[str]])

  • object_type (SimObjectType | None)

  • scope (ObjectScope)

Return type:

Query

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

Expose selected Newton output arrays as read-only groups.

state must provide any requested state arrays. Their sizes must match the connected model, and they must use the same device. It may be omitted when only model attributes are requested. control supplies current joint targets and is required only when targets are requested. If query is omitted, the read includes every available output object. attributes accepts the body pose, velocity, optional acceleration, mass-property, shape-material, articulation-root, and scene fields documented in Read simulation output, plus shared per-axis joint state, targets, properties, and the Newton-native joint_q and joint_qd fields. Names or token IDs are accepted. Native fields expose their Newton arrays directly. Split and converted fields are produced on the model device.

Native body groups and compatible single-width joint groups refer directly to arrays from state or the connected model and may provide a row map. Other groups use device-side extraction or gathers. Use data_row_index(i) or data_index_dlpack() to locate logical prim i. Do not mutate borrowed state or model arrays until every reader has finished.

CPU data is ready when this method returns. On CUDA, call this method on the Warp stream that last wrote the requested state or model arrays, or first make the current stream wait for that work. CUDA work does not block the CPU; a reader on another CUDA stream must wait for group.cuda_sync.wait_event.

Parameters:

  • state (newton.State | None)

  • control (newton.Control | None)

  • query (Optional[Query])

  • attributes (Sequence[str | int])

Return type:

ReadResult

update_to_ovstage(state, *, ordinal)#

Write the current Newton state to ovstage at ordinal.

Body world poses are written through omni:xform with omni:resetXformStack enabled. This also writes 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.

Parameters:

  • state (newton.State)

  • ordinal (int)

Return type:

None

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

Apply sealed state and drive targets from ovstage.

With attributes=None (the default), read all supported body/joint state and drive targets. Body poses include ancestor transforms. Select any combination of body_q, body_qd, jointPosition, jointVelocity, jointPositionTarget, and jointVelocityTarget to update only those fields. Joint fields cover existing single-DOF channels; other coordinates and unselected arrays stay unchanged. Explicit selections do not run forward/inverse kinematics or reconcile body and joint state. Use the default full resync for body-derived joint coordinates. An empty selection is a no-op; unknown names are rejected.

Joint angular values convert from stage degrees to Newton radians; linear values retain the stage’s length units. If ordinal is omitted, read the latest sealed values. An explicit ordinal is a consistency ceiling, not a request for historical payloads.

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

Parameters:

  • state (newton.State)

  • control (newton.Control)

  • ordinal (int | None)

  • attributes (Sequence[str] | None)

Return type:

None

Output reads#

class ovnewton.Query(
binding,
*,
body_index_array,
body_index_tensor,
body_indices_host,
body_prim_list,
body_count,
scene_prim_list,
scene_count,
shape_counts,
shape_indices,
shape_width,
articulation_index_array,
articulation_prim_list,
articulation_count,
joint_q,
joint_qd,
joint_dof,
joint_position,
joint_velocity,
joint_position_target,
attributes,
prim_count,
object_type,
scope,
path_lists,
)#

Reusable selection of bound Newton scene objects.

This object is returned by StageBinding.query(). attributes lists the output fields that can be read, and prim_count is the number of selected bodies, articulation roots, joints, and the effective physics scene.

Parameters:

  • binding (StageBinding)

  • body_index_array (wp.array | None)

  • body_index_tensor (ovstage.DLTensor | None)

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

  • body_prim_list (int)

  • body_count (int)

  • scene_prim_list (int)

  • scene_count (int)

  • shape_counts (wp.array | None)

  • shape_indices (wp.array | None)

  • shape_width (int)

  • articulation_index_array (wp.array | None)

  • articulation_prim_list (int)

  • articulation_count (int)

  • joint_q (_JointOutputSelection | None)

  • joint_qd (_JointOutputSelection | None)

  • joint_dof (_JointOutputSelection | None)

  • joint_position (_JointOutputSelection | None)

  • joint_velocity (_JointOutputSelection | None)

  • joint_position_target (_JointOutputSelection | None)

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

  • prim_count (int)

  • object_type (SimObjectType | None)

  • scope (ObjectScope)

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

class ovnewton.ReadResult(groups)#

Read-only output groups from one read.

A result may refer to arrays from the state or model used by StageBinding.read() instead of a copy. Its metadata does not identify a simulation step. Results do not need to be closed or released. This object is returned by StageBinding.read() and is not constructed directly.

Parameters:

groups (tuple[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.

This object is returned in ReadResult.groups and is not constructed directly.

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

object_type is copied from the query. It is None for a query that combines more than one object type.

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[ovstage.DLTensor, ...])

  • is_array (bool)

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

  • data_index_tensor (ovstage.DLTensor | None)

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:

ovstage.DLTensor

array(index)#

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

Parameters:

index (int)

Return type:

npt.NDArray[np.generic]

dlpack(index, *, readonly=True)#

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

Parameters:

  • index (int)

  • readonly (bool)

Return type:

ovstage.ManagedDLTensor

data_index_tensor()#

Return the optional raw DLTensor row map.

Return type:

ovstage.DLTensor | None

data_index_array()#

Return the optional read-only CPU row map.

Return type:

npt.NDArray[np.generic] | None

data_index_dlpack(*, readonly=True)#

Return the optional read-only DLPack row map.

Parameters:

readonly (bool)

Return type:

ovstage.ManagedDLTensor | None

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.