Run simulations locally and remotely with OV SIM#

Author and simulate a falling cube through the OV SIM client API. Start with an in-process client, then use the same client model to transfer a stage to a standalone gRPC server and advance the simulation remotely.

Learning objectives#

After completing this tutorial, you can:

  • Author prims and typed data through the OV SIM client API.

  • Initialize and advance an in-process simulation.

  • Transfer an authored stage to a gRPC server and read remote simulation state.

  • Choose between local and remote deployment based on lifecycle and transport requirements.

Prerequisites#

  • Complete Install and run.

  • Run the commands in this tutorial from the repository root.

  • Configure the gRPC server runtime paths for your operating system as described in Move simulation to a gRPC server. The in-process examples do not require a server.

Examples used#

Example

Role in this tutorial

Author a Cube

Authors a stage through the OV SIM client API.

Simulate a Cube

Runs the simulation with the in-process OV SIM implementation.

Simulate a Cube over gRPC

Runs the same workflow through a remote gRPC transport.

Each example page lists its source directory, requirements, and runner commands.

Use one client model for two deployments#

An in-process client executes operations in the calling process. A gRPC client sends the operations to a separate OV SIM server. Both expose authoring, simulation, and data interfaces, but the remote workflow must also manage the server, endpoint, and stage transfer.

Client

Best suited for

Additional responsibility

in-process

Local authoring and simulation with the lowest coordination overhead.

Keep the stage and simulation lifecycle in the application process.

grpc

Process isolation or simulation on another host.

Manage connectivity, transfer stage data, and operate the server.

Author through an in-process client#

Create a stage through make_client("in-process"). Use control.authoring for stage and prim lifecycle operations, and use data to write typed properties:

def main() -> None:
    """Create a stage and author a cube."""
    client = make_client("in-process")
    if not client.control.authoring.create_stage():
        raise RuntimeError("Stage creation failed.")
    try:
        cube = "/World/Cube"
        position = [0.0, 0.0, 2.0]
        client.control.authoring.define_prim(cube, "Cube")
        client.data.write(cube, "size", 1.0)
        client.data.write(cube, "position", position)

        print(f"Authored {cube} at ({position[0]:.1f}, {position[1]:.1f}, {position[2]:.1f}).")
    finally:
        client.control.authoring.close_stage()


This interface avoids direct USD object access. Run the focused authoring example:

source/examples/example.sh run falling_cube_ovsim.author_cube
.\source\examples\example.bat run falling_cube_ovsim.author_cube

Add local simulation#

Apply ColliderBody and RigidBody behavior to the cube, add a ground plane and physics scene, then initialize and step OvPhysX through the client’s simulation interface:

cube = "/World/Cube"
client.control.authoring.define_prim(cube, "Cube")
client.data.write(cube, "size", 1.0)
client.data.write(cube, "position", [0.0, 0.0, 2.0])
client.control.authoring.define_prim(cube, "ColliderBody")
client.control.authoring.define_prim(cube, "RigidBody")

ground_plane = "/World/GroundPlane"
client.control.authoring.define_prim(ground_plane, "GroundPlane")

physics_scene = "/World/PhysicsScene"
client.control.authoring.define_prim(physics_scene, "PhysicsScene")
client.data.write(physics_scene, "physics:gravityDirection", [0.0, 0.0, -1.0])
client.data.write(physics_scene, "physics:gravityMagnitude", 9.81)

client.control.simulation.set_parameter("physics", "physics-engine", "ovphysx")
client.control.simulation.initialize()
simulation_initialized = True

initial_height = float(client.data.read(cube, "position").numpy()[0, 2])
for _ in range(10):
    client.control.simulation.step()

The position read after stepping is simulation output. The same client.data.read operation retrieves the authored and simulated values, so the application does not need a backend-specific entity wrapper.

Run the in-process simulation:

source/examples/example.sh run falling_cube_ovsim.simulate_cube
.\source\examples\example.bat run falling_cube_ovsim.simulate_cube

Move simulation to a gRPC server#

Start the server from the installed developer environment. Do not run the executable from _cmake_build/isaacsim-libraries-release/modules/isaacsim_ovsim/bin; that build-tree directory does not contain all required runtime libraries.

In the first terminal, configure the runtime paths, prepare the example dependencies, and start the server:

$prefix = (Resolve-Path "_cmake_build\isaacsim-libraries-release\developer-environment").Path
$runtimePaths = @(
    "$prefix\bin"
    "$prefix\plugins"
    "$prefix\bin\plugins"
    "$prefix\bin\plugins\omni.client.lib"
    "$prefix\bin\plugins\omni.usd_resolver"
)
$env:PATH = ($runtimePaths + $env:PATH) -join ";"

source\examples\example.bat build falling_cube_ovsim.simulate_cube_grpc
isaacsim-ovsim-grpc-server --listen-address 127.0.0.1:50051
prefix="$PWD/_cmake_build/isaacsim-libraries-release/developer-environment"
export PATH="$prefix/bin:$PATH"

source/examples/example.sh build falling_cube_ovsim.simulate_cube_grpc
isaacsim-ovsim-grpc-server --listen-address 127.0.0.1:50051

The server listens on 127.0.0.1:50051 and runs in the foreground. Keep the first terminal open while you run the client.

In a second terminal, run the client from the repository root:

source\examples\example.bat run falling_cube_ovsim.simulate_cube_grpc -- --endpoint 127.0.0.1:50051
source/examples/example.sh run falling_cube_ovsim.simulate_cube_grpc -- --endpoint 127.0.0.1:50051

The client authors the scene locally, exports it as text, imports it through the remote client, and advances simulation on the server:

stage_content = local_client.control.authoring.export_stage_to_string()
if not remote_client.control.authoring.import_stage_from_string(stage_content):
    raise RuntimeError("Remote simulation creation failed.")
remote_stage_open = True
remote_client.control.simulation.initialize()

initial_height = float(remote_client.data.read(cube, "position").numpy()[0, 2])
for _ in range(10):
    remote_client.control.simulation.step()

The client-side authoring, data, and simulation operations keep the same structure, while the application explicitly owns transport configuration and both stage lifecycles. Stop the server with Ctrl+C when you finish.

Verify local and remote behavior#

Run the example tests:

source/examples/example.sh test falling_cube_ovsim.author_cube
source/examples/example.sh test falling_cube_ovsim.simulate_cube
source/examples/example.sh test falling_cube_ovsim.simulate_cube_grpc:loopback
.\source\examples\example.bat test falling_cube_ovsim.author_cube
.\source\examples\example.bat test falling_cube_ovsim.simulate_cube
.\source\examples\example.bat test falling_cube_ovsim.simulate_cube_grpc:loopback

The authoring test verifies that stage creation completes successfully. The local and remote simulation tests compare the initial and final cube heights. The loopback test starts a server on a temporary local port, waits for it to become ready, runs the client, and shuts down the server.

Tradeoffs#

The example uses an insecure gRPC channel on loopback. Supply the network access and security controls required by your deployment before using a non-loopback endpoint. Prefer the in-process client when process separation does not justify serialization, server lifecycle, and network overhead.

Next steps#

Continue with Build a native OVGL stage viewer to inspect stages in a lightweight C++ application.