nvidia-omniverse/physx/ovphysx-session-write

Write Control Inputs into an ovphysx Simulation

Use the session write API to push caller-owned buffers — control inputs and state — into the simulation: apply velocities, teleport poses, drive joints (position / velocity and their targets), apply forces and wrenches, set mass properties, or issue wake/sleep commands. It is the mirror of the output read and the successor to the deprecated tensor-binding write. For reading simulation output back (borrowed warp arrays, ovstage identity, closed-loop write-back), use the ovphysx-output-read skill.

Workflow

1. Select the language branch and read its bundled reference:

• Python: Python session writes
• C: C write-session lifecycle

Read only the selected language reference. Select the simulated object type, the attributes to write, and the source buffer's device.

Complete when: the language, object type, attributes, and source device are explicit.

1. Keep an ovstage Stage attached and alive. When attachment and process

lifecycle are not already established, invoke the ovphysx-basic-workflow skill by name.

Complete when: the attached Stage owns the shared path dictionary for the whole write.

1. Warm up or step BEFORE the first write if you need a recipe that also works

on DirectGPU. On CPU and on GPU-with-readback a write issued before the scene's first step is APPLIED, not refused. On DirectGPU (suppressReadback) commit is REFUSED until a first step has sized the GPU scatter view. In every mode the write never auto-warms: it never steps for you. Call warmup() / ovphysx_warmup() or step_sync() first when you want one sequence for all three modes.

Complete when: the caller has either warmed or stepped, or has accepted that CPU/GPU-with-readback will apply a pre-step write and DirectGPU will not.

1. Open a write session for the attributes, fill EVERY entry of every group, then

commit each group. A session carries every attribute named when it is opened, and each fetched group reports its request position as attribute_index -- identify a group's attribute by that index, never by tensor shape or fetch order. Group tensors are mutable views onto runtime-owned storage; fill them in place. Commit publishes the WHOLE group, so a partially filled group publishes whatever its unfilled entries contain -- fill every tensor of every group before committing. A group that is never committed is discarded and publishes nothing.

Complete when: every group intended to publish is fully filled and committed, and any abandoned fill committed nothing.

1. Complete the simulation step that consumes the write, then read results back.

Control inputs marked write-only (forces, wrenches) are consumed and cleared each step; read outcomes through a STATE attribute, not the control one. Invoke the ovphysx-output-read skill for the read.

Complete when: the step has run and simulated results are read from a state attribute, not the control input.

1. Release resources and validate the selected branch. Python closes the

WriteSession and any explicit Query with their context managers; a write_sync() session waits for its releases on exit, and the default operations' releases are collected with wait_all(). C releases the write and query handles on success and error paths. Exercise an integration test that writes, steps, and observes the intended CONSEQUENCE (motion, pose change) rather than reading a write-only input back.

Complete when: every session is released before PhysX.destroy(), and the test observes the expected physical consequence.

Shared Contracts

• Native query/read/write, fetch, commit and release operations return task

receipts. Check admission, wait for that receipt, then consume outputs. Fetch exhaustion is a successful wait with a null group. Copy task diagnostics before destroying wait-result storage. Python's default session calls return an Operation; wait() collects it and raises TaskError on failure, and write_sync() / commit_sync() / close_sync() wait internally.

• Query by simulated type, not USD schema; narrow it to specific prims with a

prim-set selection when needed. Identify objects through each write group's own prim list; read/write partitions and fetch order need not match.

• Several attributes per session: pass them in one list. The open validates all

of them first -- a duplicate (including a string and a token naming the same attribute), a token that does not resolve in the attached Stage's dictionary, or an unsupported or read-only name fails the whole open. Commits are separate and not transactional: commit order is execution order, and an earlier successful commit stays applied when a later one fails.

• The writable set is listed by object type in **Writable attributes by object

type** below. The writability query (ovphysx_writability) gives the authoritative classification of every (object type, attribute) pair as WRITABLE, WRITE_ONLY, READ_ONLY, or CONDITIONAL with no scene or step -- C callers should consult it rather than guessing whether a name is writable. It has no public Python binding (hasattr(ovphysx, 'writability') is False); ovphysx._bindings.writability(object_type, attribute) is a private ctypes wrapper around the same call (used by the project's own test_writability.py), not a supported/stable public API -- prefer the table below, or attempt physx.write_sync(...), which raises TaskError (a RuntimeError) for an attribute that is not writable for the object type, rather than writing nothing silently.

• Fill EVERY mapped entry before a plain commit: it publishes every entry, so an

unfilled one publishes stale memory. To write only some rows, commit with a row mask (C ovphysx_commit_group_masked, Python commit(group, mask=...)), which writes the rows it selects and leaves the others as they were; or, for a fixed set of bodies, select their prims with a prim-set query (C ovphysx_query_selection, Python prim_paths= / pattern=). There is no kinematic-body filter, and neither ALL nor ACTIVE scope provides one.

• Uncommitted groups are discarded when the session closes. A failed commit can

partially apply its group and consumes it; previously committed groups remain applied. Copy the task diagnostic before destroying its wait result; Python includes it in the exception.

• force is a vec3 applied at the CENTRE OF MASS. wrench is nine wide --

[fx,fy,fz, tx,ty,tz, px,py,pz] = force, torque, and a WORLD application point -- so use wrench (force at the point, torque zero) for a load away from the COM, and wrench (force zero, torque set) for a pure torque. Both are WORLD frame and WRITE-ONLY: the solver consumes and clears them each step, so there is nothing to read back -- assert their consequence.

• wake is a one-time command for standalone rigid dynamics: nonzero wakes, zero sleeps.

Fill every mapped row; zero is not a leave-unchanged value. Use scope=ALL to include sleeping bodies. A prim-set selection can narrow the command to chosen bodies, including sleepers. CPU and GPU-with-readback scenes support it; DirectGPU refuses it. Kinematic and simulation-disabled bodies are skipped, and sleeping-disabled scenes ignore the sleep command. Articulation-link writes are refused. Read isSleeping separately to observe state (1 asleep, 0 awake); neither the last command nor ACTIVE membership proves current state. The command takes effect at commit.

• Angular joint columns are per-AXIS and in DEGREES (coordinates and rates);

gains are per degree and efforts are unconverted. Do not apply a blanket radian conversion. A prismatic axis stays in the stage's base length unit.

• Inspect tensor.device per group. A GPU scene may stage a write through the

host, so the write device can differ from the read; commit a CUDA group with its producer stream or event (cuda_stream= / cuda_wait_event= in Python, ovstage_cuda_sync_t in C). They name your fill work, not the stream physics uses; the default-stream value 1 refers to the CUDA context current during the commit, so make the producer's context current (Python wp.ScopedDevice).

• Read simulated results from a STATE attribute, not the control input you

wrote: a velocity-target write reads back the target, not the physics outcome.

Writable attributes by object type

Pass each attribute as a write string -- Python physx.write_sync(type, ["name"]) or physx.write(query, ["name"]), C the matching OVPHYSX_ATTR_* macro. This is the current writable set; a write-only input has no read-back (assert its consequence) and jointLimit is conditional -- see the notes under the table.