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 parameter reference

Scenario files are JSON. Distances are metres, speeds are metres per second, temperatures are degrees Celsius, powers are dBm, and times are seconds unless a compact duration suffix is used.

This reference distinguishes:

• implemented fields that affect planner or OpenUSD behavior;
• visualization-only fields;
• reserved metadata retained for scenario classification but not yet used by a model.

1. Duration values

Duration fields accept a number of seconds or a string:

30       30 seconds
30s      30 seconds
5m       5 minutes
4h       4 hours
2d       2 days

Values must be positive and finite.

2. Complete top-level schema

Parameter	Type	Default	Behavior
name	string	"unnamed"	Scenario label in terminal, JSON, SVG, and root USD metadata
target	string	"human"	Legacy single-actor profile; ignored when actors is non-empty
domain	string	"ground"	Legacy single-actor domain
modality	string	"seismic+acoustic"	Default enabled modalities, separated by +
environment	string	"rural"	Descriptive environment label
site_size_m	number	600	Square plotting extent for portable SVG and fallback campus sizing
ring_radius_m	number	220	Radius used when explicit node_positions are absent
n_nodes	integer	8	Number of equally spaced ring nodes when explicit positions are absent
gateway_xy	[x,y]	[0,0]	TORUS-MEG position and center for generated ring placement
node_positions	list of [x,y]	[]	Explicit SN coordinates; takes precedence over n_nodes and ring_radius_m
source_amplitude	number	1.0	Legacy seismic source strength and planning-footprint source
attenuation_length_m	number	90	Legacy/fallback seismic exponential decay length
noise_floor	number	0.06	Legacy/fallback modality noise floor
detect_threshold_snr	number	3.0	Global normalized detection threshold
intruder_path	list of [x,y]	Built-in three-point path	Legacy single-actor path
intruder_speed_mps	number	1.4	Legacy single-actor speed
dt	number	1.0	Legacy time step when simulation.time_step_s is absent
simulation	object	{}	Duration, evaluation step, output sampling, and seed
actors	list	[]	Multi-actor definitions; replaces legacy actor fields when non-empty
obstacles	list	[]	Top-down attenuation objects
geofences	list	[]	Circle or polygon monitored zones
rf	object	{}	RF link, detection, and visualization settings
thermal	object	{}	Thermal mast and contrast settings
detection	object	{}	Fusion, modality, and repeated-detection settings
scene	object	{}	Campus dimensions and visualization switches

3. Simulation object

"simulation": {
  "duration_s": "4h",
  "time_step_s": 2.0,
  "output_interval_s": 10.0,
  "seed": 42
}

Parameter	Type	Default	Behavior
duration_s	number/string	Natural actor completion time	Total scenario duration
time_step_s	number	Top-level dt	Detection, geofence, and animation evaluation interval
output_interval_s	number	time_step_s	Stored planner track interval; cannot be smaller than time_step_s
seed	integer	None	Reserved deterministic-randomization metadata; current planner is deterministic and does not consume it

The OpenUSD actor animation uses the evaluation samples, not the thinned report track. A large output interval therefore reduces stored planner and SVG track density without removing Isaac animation samples. The current event JSON does not serialize actor tracks.

4. Node and gateway placement

Explicit placement:

"gateway_xy": [0.0, -175.0],
"node_positions": [
  [-420.0, -280.0],
  [-280.0, -300.0]
]

Automatic ring placement:

"gateway_xy": [0.0, 0.0],
"n_nodes": 12,
"ring_radius_m": 350.0

Generated identifiers are assigned in list or angular order:

SN-01, SN-02, ...

The gateway is MEG-01 in visual output. Thermal sensors are MAST-01, MAST-02, and so on.

5. Actors

actors is a list of scheduled moving targets:

{
  "id": "delivery-truck",
  "type": "truck",
  "classification": "commercial-truck",
  "start_time_s": "35m",
  "path": [[0, -520], [0, -330], [0, -210], [260, -112]],
  "speed_mps": 7.0,
  "behavior": "once",
  "threat": false
}

5.1 Actor fields

Parameter	Type	Default	Behavior
id	string	actor-NN	Unique track and event identifier
type	string	"human"	Built-in profile name
classification	string	Actor type	Classification copied to detections and events
domain	string	Profile domain	ground or air; air actors automatically add RF when no explicit RF modality is enabled
path	list of [x,y]	Top-level intruder_path	Ordered piecewise-linear waypoints
start_time_s	number/string	0	Time at which the actor becomes visible and active
speed_mps	number	Profile speed	Constant path speed; values near zero create very long travel time
altitude_m	number	Profile altitude or 0	Constant Z coordinate for air actors
behavior	string	"once"	once, hold, loop, or pingpong
threat	boolean	Profile value	Allows correlated intrusion_alarm inside protected geofences
modalities	string list	Split top-level modality	Explicit enabled subset of seismic, acoustic, rf, thermal
seismic_amplitude	number	Profile value	Relative ground source strength
acoustic_amplitude	number	Profile value	Relative acoustic source strength
thermal_c	number	Profile value	Target temperature used for contrast
rf_tx_power_dbm	number/null	Profile value	Actor RF emitter power; null means no RF source

5.2 Behavior values

Value	Result after reaching the final waypoint
once	Actor becomes inactive and invisible
hold	Actor remains at the final waypoint
loop	A closing segment to the first waypoint is added when needed, then repeated
pingpong	Actor reverses through the same path repeatedly

An empty path makes the actor inactive. A one-point path has zero travel time and remains stationary once active for every current behavior value.

5.3 Built-in actor profiles

Every field can be overridden per actor.

Type	Domain	Speed	Seismic	Acoustic	Temp C	RF dBm	Threat
human	ground	1.4	0.80	0.70	36.7	-	yes
worker	ground	1.3	0.70	0.65	36.7	-	no
runner	ground	3.2	1.15	0.90	37.5	-	yes
dog	ground	3.5	0.42	0.55	38.5	-	no
deer	ground	4.5	0.75	0.45	39.0	-	no
animal	ground	3.0	0.45	0.50	38.5	-	no
livestock	ground	1.8	1.00	0.65	38.5	-	no
car	ground	10.0	2.20	1.80	65	10	yes
vehicle	ground	8.0	2.20	1.80	65	10	yes
electric-car	ground	10.0	1.65	0.75	45	10	yes
motorcycle	ground	12.0	1.40	2.00	75	8	yes
van	ground	9.0	2.80	2.00	70	12	yes
truck	ground	8.0	4.50	3.20	85	14	yes
drone	air	12.0	0	1.00	42	20	yes
uav	air	22.0	0	1.80	55	27	yes
airplane	air	75.0	0	5.00	110	30	no
balloon	air	4.0	0	0.08	24	8	no

Unknown types inherit the human planner profile. Use:

python3 run_sim.py --list-profiles

6. Obstacles and material effects

Obstacles are evaluated in top-down line/shape intersections. They affect portable RF, acoustic, seismic, and thermal paths.

Rectangle:

{
  "id": "generator-metal-bank",
  "type": "equipment",
  "shape": "rectangle",
  "center": [275.0, -112.0],
  "size": [160.0, 70.0],
  "height_m": 5.0,
  "material": "metal",
  "density": 1.0
}

Circle:

{
  "id": "retention-water",
  "type": "lake",
  "shape": "circle",
  "center": [-315.0, -215.0],
  "radius_m": 50.0,
  "material": "water"
}

6.1 Obstacle fields

Parameter	Type	Default	Behavior
id	string	obstacle-NN	Identifier stored in crossed_objects
type	string	None	Descriptive metadata; does not select attenuation coefficients
shape	string	"rectangle"	rectangle or circle
center	[x,y]	[0,0]	Shape center
size	[width,depth]	[1,1]	Rectangle dimensions
radius_m	number	1	Circle radius
height_m	number	None	3D-authoring metadata; portable intersection remains top-down
material	string	"air"	Built-in material profile
density	number	1.0	Non-negative multiplier/exponent applied to material effects
effects	object	{}	Per-obstacle coefficient overrides

Scenario obstacles appear in the portable SVG. The fixed Isaac campus template does not automatically convert every obstacle entry into a unique 3D mesh.

6.2 Material profiles

Material	RF loss dB	Acoustic factor	Seismic factor	Thermal occlusion
air	0	1.00	1.00	0.00
foliage	3	0.82	0.94	0.25
wood	5	0.72	0.90	0.55
plastic	2	0.88	0.97	0.18
glass	3	0.78	0.95	0.30
brick	10	0.48	0.80	0.85
concrete	14	0.38	0.72	0.95
reinforced-concrete	20	0.30	0.65	1.00
metal	24	0.42	0.76	1.00
water	8	0.62	0.55	0.45

Override a material for one object:

"effects": {
  "rf_loss_db": 9.0,
  "acoustic_factor": 0.6,
  "seismic_factor": 0.8,
  "thermal_occlusion": 0.7
}

RF losses are added. Acoustic and seismic factors are multiplied. Thermal occlusion is accumulated and clamped to 1.0. density multiplies RF loss, raises acoustic/seismic factors to that power, and multiplies thermal occlusion before accumulation.

7. Detection object

"detection": {
  "fusion": "any",
  "first_detection_per_node": false,
  "detection_cooldown_s": 300.0,
  "seismic_attenuation_length_m": 95.0,
  "seismic_noise_floor": 0.08,
  "acoustic_attenuation_length_m": 160.0,
  "acoustic_noise_floor": 0.09,
  "acoustic_threshold_snr": 3.0
}

Parameter	Type	Default	Behavior
fusion	string	"any"	any: best enabled modality passes; all: every enabled modality must pass
first_detection_per_node	boolean	true	Emit only the first actor/node detection record
detection_cooldown_s	number	60	Minimum repeated-detection interval when first-only is false
seismic_attenuation_length_m	number	Top-level attenuation_length_m	Seismic exponential decay length
seismic_noise_floor	number	Top-level noise_floor	Seismic SNR denominator
acoustic_attenuation_length_m	number	130	Acoustic exponential decay length
acoustic_noise_floor	number	Top-level noise_floor	Acoustic SNR denominator
acoustic_threshold_snr	number	Top-level detect_threshold_snr	Acoustic decision threshold

With fusion=all, an enabled modality with no actor source remains below threshold. For example, seismic+rf fails for a person whose rf_tx_power_dbm is null.

8. RF object

"rf": {
  "frequency_mhz": 433.0,
  "path_loss_exponent": 2.45,
  "node_tx_power_dbm": 20.0,
  "gateway_sensitivity_dbm": -120.0,
  "actor_detection_sensitivity_dbm": -102.0,
  "minimum_link_margin_db": 8.0,
  "visualize": true,
  "visualization_center": [0.0, -175.0],
  "visualization_radius_m": 190.0,
  "visualization_node_count": 4
}

Parameter	Type	Default	Behavior
frequency_mhz	number	433	Carrier for free-space reference loss
path_loss_exponent	number	2.4	Log-distance environment exponent
node_tx_power_dbm	number	20	SN transmit power for SN-to-MEG budget
gateway_sensitivity_dbm	number	-120	MEG receiver sensitivity
actor_detection_sensitivity_dbm	number	-105	Actor-emitter RF decision threshold
minimum_link_margin_db	number	6	rf_link_degraded warning threshold
visualize	boolean	scene.show_rf_fields or true	Create RF rings and telemetry paths in OpenUSD
visualization_center	[x,y]	gateway_xy	Center of OpenUSD RF rings
visualization_radius_m	number	170	Outer OpenUSD RF visualization radius
visualization_node_count	integer	4	Number of nearest SN telemetry paths shown

Received power is:

tx power
- free-space loss at 1 metre
- 10 * path_loss_exponent * log10(distance metres)
- crossed material RF losses

The model does not calculate antenna pattern, polarization, diffraction, multipath, Fresnel clearance, terrain, foliage moisture, or time-varying interference.

9. Thermal object

"thermal": {
  "enabled": true,
  "ambient_c": 18.0,
  "min_delta_c": 4.0,
  "max_range_m": 220.0,
  "min_visibility": 0.35,
  "palette": "ironbow",
  "sensor_positions": [
    [-400.0, -160.0],
    [360.0, -220.0]
  ]
}

Parameter	Type	Default	Behavior
enabled	boolean	false	Evaluate thermal detections and create frustums
sensor_positions	list of [x,y]	Four campus corners	Thermal mast positions
ambient_c	number	20	Background temperature
min_delta_c	number	4	Required target/background contrast
max_range_m	number	180	Simplified slant range
min_visibility	number	0.35	Minimum visibility after material occlusion
palette	string	None	Display/capture metadata; planner decision is palette-independent

Thermal score is the minimum of normalized temperature contrast, range, and visibility. Thermal detections are attributed to MAST-*.

10. Geofences

Circle:

{
  "id": "critical-operations-zone",
  "shape": "circle",
  "center": [0.0, -126.0],
  "radius_m": 105.0,
  "protected": true,
  "severity": "critical"
}

Polygon:

{
  "id": "protected-campus",
  "shape": "polygon",
  "points": [[-450,-325], [450,-325], [450,325], [-450,325]],
  "protected": true,
  "severity": "critical"
}

Parameter	Type	Default	Behavior
id	string	geofence-NN	Event source
shape	string	"polygon"	circle or polygon
center	[x,y]	[0,0]	Circle center
radius_m	number	0	Circle radius
points	list of [x,y]	[]	Polygon vertices; at least three needed
protected	boolean	true	Enables threat correlation for intrusion alarms
severity	string	"critical"	Severity on threat entry; benign entry is information

Entering and exiting any geofence creates transition events. A threat actor detected inside a protected geofence creates one intrusion_alarm until the actor exits and the alarm rearms.

11. Scene object

"scene": {
  "template": "hyperscale-campus",
  "campus_width_m": 900.0,
  "campus_depth_m": 650.0,
  "ground_condition": "damp",
  "weather": "clear",
  "season": "summer",
  "show_rf_fields": true,
  "show_thermal_frustums": true
}

Parameter	Type	Default	Status
template	string	"hyperscale-campus"	Stored in root USD; portable SVG draws the campus only for this value
campus_width_m	number	site_size_m * 0.9 in Isaac	Controls generated terrain/security width
campus_depth_m	number	site_size_m * 0.65 in Isaac	Controls generated terrain/security depth
show_rf_fields	boolean	true	Fallback RF visualization switch
show_thermal_frustums	boolean	true	OpenUSD thermal-frustum switch
ground_condition	string	None	Reserved metadata; no current propagation or material change
weather	string	None	Reserved metadata; no current rain/fog/wind model
season	string	None	Reserved metadata; no current foliage or temperature model
actor_altitude_m	number	None	Reserved legacy metadata; actor altitude_m controls current air tracks

The Isaac generator currently builds the repository's representative hyperscale campus. Changing template does not select a second 3D template.

12. Modalities and decision calculations

Seismic

amplitude = source
          * exp(-distance / attenuation length)
          * crossed material factors

SNR = amplitude / noise floor

Acoustic

Uses the same exponential structure with 3D distance, acoustic source, acoustic attenuation length, acoustic material factors, and acoustic noise.

RF actor detection

Compares received actor-emitter power with actor_detection_sensitivity_dbm.

Thermal

Requires temperature contrast, range, and post-occlusion visibility to pass.

Fusion

• any: the highest normalized modality score controls the decision.
• all: all enabled modality scores must be at least 1.0.

13. Events

Kind	Trigger
rf_link_degraded	SN-to-MEG margin below minimum_link_margin_db at time zero
geofence_enter	Actor transitions from outside to inside
geofence_exit	Actor transitions from inside to outside
sensor_detection	Node or mast passes the detection rule
intrusion_alarm	Threat actor is detected inside a protected geofence

14. Event JSON output

--events-json writes:

{
  "scenario": "name",
  "duration_s": 14400.0,
  "actors": [],
  "rf_links": [],
  "detections": [],
  "events": []
}

RF link record

Field	Meaning
node	SN identifier
distance_m	SN-to-MEG distance
received_dbm	Calculated MEG input power
margin_db	Received power minus MEG sensitivity
crossed_objects	Obstacle IDs intersecting the path

Detection record

Field	Meaning
t	Scenario time
node	SN or MAST identifier
x, y	Actor position
score	Normalized decision score
snr	Actual seismic/acoustic SNR when applicable; null for RF/thermal
actor	Actor ID
modality	Winning or fused modality
classification	Actor classification
metrics	Modality-specific SNR, margin, contrast, or visibility
crossed_objects	Obstacle IDs on the path

Event record

Field	Meaning
t	Scenario time
kind	Event kind
actor	Actor or deployment identifier
source	Node, mast, or geofence
x, y	Event position
severity	information, warning, or critical
details	Event-specific classification, modality, score, or RF values

15. Command-line overrides

Examples:

python3 run_sim.py \
  --scenario 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 \
  --set scene.weather='"cold-rain"'

Values are decoded as JSON where possible. Quote string JSON values when the shell would otherwise remove the quotation marks.

Supported:

rf.path_loss_exponent=2.8
thermal.enabled=false
gateway_xy=[0,-175]

Not currently supported:

actors.0.speed_mps=2.0
obstacles.3.material="metal"

Edit the scenario JSON for list-element changes.

16. Validation rules

The loader currently enforces:

• valid JSON;
• recognized top-level dataclass fields;
• positive finite time_step_s;
• output_interval_s >= time_step_s;
• positive finite duration syntax.

Profile names and nested dictionary keys are intentionally extensible. A typo can therefore fall back or become unused metadata. Review terminal output, events, and the generated stage after editing a scenario.

17. Calibration boundary

The included coefficients are planning assumptions, not certified material or sensor specifications. Calibrate site variants with measured RF, vibration, acoustic, thermal, soil, foliage, weather, and antenna data before using results for deployment guarantees.