Source of truth

This guide is maintained in the PacketFive/TORUS repository under torus-isaac-sim/docs/ and is published here verbatim from torus-isaac-sim.

TORUS simulation build, deployment, and usage¶

This document is the deployment summary. For complete workstation and container installation, every command-line option, GUI operation, screenshot generation, troubleshooting, and developer extension workflow, see the TORUS simulation user and developer guide.

TORUS has two simulation tiers:

Portable planner - standard-library Python for scenario design, RF link budgets, material attenuation, geofence events, and CI. It runs without a GPU.
OpenUSD campus twin - NVIDIA Isaac Sim for RTX rendering, animated actors, RF-field overlays, thermal sensor visualization, and synthetic data.

The public website hosts documentation and pre-rendered images only. A static web server cannot execute Isaac Sim without an NVIDIA GPU, drivers, and an interactive or headless rendering runtime. Users download the repository and run the GPU tier on a compatible workstation or GPU server.

Hardware and software¶

Portable planner¶

Python 3.8 or newer
No third-party Python packages

Isaac Sim tier¶

Linux workstation or GPU server supported by NVIDIA Isaac Sim 5.1+
NVIDIA RTX GPU and current compatible driver
10 GB VRAM recommended for the procedural campus; reduce assets and sensors when running near the minimum
32 GB host memory recommended
Isaac Sim native installation, or Docker with NVIDIA Container Toolkit

RaytracedLighting is the practical default. Path tracing is intended for final stills on GPUs with sufficient VRAM.

Download¶

git clone https://github.com/PacketFive/TORUS.git
cd TORUS/torus-isaac-sim

Portable planning run¶

bin/torus-sim preview scenarios/configurable_campus_security.json \
  --duration 30m \
  --svg output/campus-plan.svg \
  --events-json output/campus-events.json

Override nested parameters without editing the JSON:

bin/torus-sim preview scenarios/configurable_campus_security.json \
  --duration 8h \
  --set rf.path_loss_exponent=2.8 \
  --set thermal.ambient_c=5.0 \
  --set detection.detection_cooldown_s=600 \
  --events-json output/winter-shift.json

List the built-in actor and material profiles:

python3 run_sim.py --list-profiles

The JSON event log contains actor configuration, TORUS-SN-to-MEG RF link budgets, sensor detections, geofence transitions, degraded-link warnings, and correlated intrusion alarms.

Native Isaac Sim¶

Set the Isaac Sim location if it is not /opt/isaacsim:

export ISAAC_SIM_ROOT=/path/to/isaac-sim
export OMNI_KIT_ACCEPT_EULA=yes

Generate the OpenUSD layers without opening a window:

bin/torus-sim generate scenarios/configurable_campus_security.json \
  --output output/campus \
  --renderer RaytracedLighting

Open the animated campus:

bin/torus-sim gui scenarios/configurable_campus_security.json \
  --output output/campus \
  --renderer RaytracedLighting

The root stage is output/campus/torus-campus.usda. The timeline uses scenario seconds, so a multi-day scenario should normally be inspected by jumping to event timestamps rather than replaying it in real time.

Container deployment¶

Docker is preferred over Vagrant because NVIDIA Container Toolkit provides a supported GPU pass-through path and the Isaac Sim base image already contains the rendering runtime. Vagrant would still require host-specific PCI/GPU pass-through and duplicate a large guest operating system.

Authenticate to NVIDIA NGC and accept the Isaac Sim image license, then:

docker login nvcr.io
mkdir -p output assets
docker compose build
docker compose run --rm torus-isaac

The container sets NVIDIA's required ACCEPT_EULA=Y; using it confirms that the operator has accepted the applicable Isaac Sim container license.

Choose another scenario:

TORUS_SCENARIO=/workspace/TORUS/scenarios/long_duration_patrol.json \
  docker compose run --rm torus-isaac

Or invoke commands directly:

docker compose run --rm torus-isaac preview \
  --duration 2h \
  --events-json /workspace/output/events.json

docker compose run --rm torus-isaac generate \
  --renderer RaytracedLighting

The compose stack mounts:

./output at /workspace/output
./assets read-only at /workspace/assets

Set ISAAC_SIM_IMAGE to an organization-approved Isaac Sim image when the default NGC tag differs. Set TORUS_ASSET_ROOT to a licensed USD asset library.

Licensed asset replacements¶

Place these files in the selected asset directory:

data-hall.usd
deciduous-tree.usd
torus-sn.usd
torus-meg.usd
torus-mast.usd

They must use metres, Z-up coordinates, useful pivots, and simulation-ready materials. The built-in ruggedized procedural assets remain the license-clean fallback.

Deployment workflow¶

Copy configurable_campus_security.json.
Import or enter site dimensions, terrain, restricted areas, access routes, and candidate node and gateway positions.
Add attenuation objects for tree belts, walls, glass, metal equipment, water, and other obstructions.
Define protected geofences.
Add actors and event start times.
Run the portable planner and compare coverage, RF margins, detection redundancy, alarms, false positives, installation access, and maintenance constraints.
Adjust thresholds and placement, then repeat across environmental and component-tolerance assumptions.
Generate the OpenUSD stage on a GPU system.
Replace procedural assets where licensed production models are available.
Validate selected candidates in the 3D twin and capture approved stills, thermal views, or synthetic-data outputs.

Physics backend decision¶

The deployment planner and the Isaac physics backend solve different problems:

Planning question	Primary TORUS capability
Where should TORUS-SN and MEG units be placed?	Placement and coverage optimization
Will RF links meet margin targets?	Calibrated RF model or connected RF solver
Will seismic/acoustic targets be detectable?	Calibrated propagation and detection models
Can cameras and thermal masts see the target?	Geometry, occlusion, sensor models, and field data
Can personnel or a deployment vehicle reach the site?	Terrain and route analysis; optional rigid-body validation
Will a mast, enclosure, mount, or deployment robot behave physically?	PhysX or optional Newton validation

NVIDIA Newton is a GPU-accelerated OpenUSD/Warp physics framework for rigid and deformable bodies, contact, friction, locomotion, and manipulation. It is not an RF, acoustic, seismic, thermal, or electromagnetic propagation solver and is not itself a deployment optimizer.

The supported TORUS runtime remains Isaac Sim 5.1. Newton integration should be evaluated separately with Isaac Sim 6.0+ rather than added as a nominal switch to the present scene: current actors are keyframed and campus objects are mostly static colliders, so changing the backend alone provides no additional planning fidelity.

Introduce Newton only for a defined physical validation case, such as:

deployment-vehicle or UGV traversal over surveyed terrain;
node insertion, burial, impact, or enclosure stability;
mast mounting, collision, maintenance, or robotic installation;
interaction of people, animals, vehicles, debris, cables, or flexible barriers with TORUS equipment.

Each case needs measured mass, inertia, friction, compliance, terrain or material parameters, plus an acceptance criterion. Keep the same OpenUSD site layers and compare Newton and PhysX results before making Newton a supported backend.

Duration and performance¶

simulation.duration_s accepts seconds or compact strings (30m, 8h, 2d). time_step_s controls detection evaluation; output_interval_s controls track storage and visualization density. For long runs, keep the detection step fine enough for the fastest actor and increase only the output interval:

Scenario	Suggested step	Suggested output
Walking intrusion	0.5-2 s	2-10 s
Vehicle approach	0.2-1 s	1-5 s
Drone/UAV	0.1-0.5 s	0.5-2 s
Day-scale patrol	10-30 s	1-5 min

Simulation boundaries¶

The portable propagation model is deterministic planning logic, not a certified RF, seismic, acoustic, or thermal solver. Object losses are configurable engineering assumptions. Calibrate them with site surveys, measured path loss, soil and vibration characterization, acoustic recordings, thermal camera performance data, and validated external solvers before using results for deployment guarantees.