CORNET Unified Config Schema Reference¶

This page is auto-generated from cornet/config/schema.py. All fields support YAML and JSON input. Dot-path notation (e.g. network.middleware.rtf) is used in sweep axes.

UnifiedConfig¶

Root configuration model. Every config.yaml must parse as UnifiedConfig.

Field	Type	Default	Required	Description
`network`	NetworkConfig	—	✓	Network simulation backend configuration (NS-3, Mininet, or both).
`robot`	RobotConfig	—	✓	Robot simulation backend configuration (Gazebo + ROS 2).
`experiment`	ExperimentConfig	—	✓	Experiment runtime settings: duration, output, metrics, and optional parameter sweep.
`catalog`	CatalogProvenance	null	null

NetworkConfig¶

Network simulation backend settings (network: section).

Field	Type	Default	Required	Description
`plugin`	string	—	✓	Network backend plugin identifier: 'ns3', 'mininet', or 'ns3+mininet'.
`type`	string	—	✓	Network simulation type. Must match plugin.
`nodes`	list[NodeConfig]	`[]`		List of network nodes in the topology.
`mininet`	MininetConfig	null	null
`middleware`	MiddlewareConfig	null	null
`mobility`	MobilityConfig	null	null
`scenario`	ScenarioConfig	null	null
`radio_sites`	RadioSitesConfig	null	null
`population`	list[PopulationEntity]	—		Background population. Walkers are Gazebo actors; devices are NS-3 nodes.
`blockage`	string	`"none"`		Statistical blockage. model_a enables TR 38.901 Model A with 3GPP defaults.
`non_self_blockers`	string	null	null
`channel_update_ms`	integer	null	null
`requires_nr_capability`	list[string]	string	null	null
`timing_log`	boolean	`False`		Forward --timingLog and --timingPeriodMs to the NS-3 scratch script even when it is not a bundled CORNET script. Bundled scripts receive the flags automatically. Custom scripts that do not implement the flags must leave this false.

NodeConfig¶

A single network node in the topology.

Field	Type	Default	Required	Description
`name`	string	—	✓	Unique node identifier within the network topology.
`type`	string	`"MOBILE"`		Node role. MOBILE/STATIC for Mininet nodes; UE/GNB/EPC for NS-3 5G nodes.
`container`	ContainerConfig	null	null
`ip`	string	null	null
`x`	number	null	null
`y`	number	null	null
`z`	number	null	null
`model_name`	string	null	null

ContainerConfig¶

Docker container configuration for a network node.

Field	Type	Default	Required	Description
`image`	string	—	✓	Docker image name (e.g. 'ros:humble' or a custom image built from the task's Dockerfile).
`environment`	dict[str, string]	`{}`		Environment variables injected into the container at start-up.
`volumes`	list[string]	`[]`		Host-to-container volume mounts in 'host:container[:mode]' format.
`cpu_quota`	number	null	null
`mem_limit_mb`	integer	null	null

MininetConfig¶

Mininet-WiFi access point settings.

Field	Type	Default	Description
`wmediumd`	boolean	`False`	Enable wmediumd wireless medium daemon for realistic Wi-Fi interference emulation (requires Docker).
`ssid`	string	`"cornet-net"`	SSID for the Mininet-WiFi access point.
`mode`	string	`"g"`	IEEE 802.11 mode ('a', 'b', 'g', 'n', 'ac').
`channel`	integer	`1`	Wi-Fi channel number (1–14 for 2.4 GHz, 36–165 for 5 GHz).

MiddlewareConfig¶

Co-simulation middleware layer settings.

Field	Type	Default	Description
`enabled`	boolean	`False`	Enable the CORNET co-simulation middleware layer (TUN manager, packet dispatcher, AoI tracker, physics clock).
`ip_list`	list[string]	`[]`	IP addresses of simulation nodes that the TUN manager should bridge to the robot network.
`rtf`	number	`1.0`	Real-time factor. 1.0 = wall-clock speed. Values < 1 slow simulation; 0 = maximum simulation speed (decoupled from wall clock).
`deadline_s`	number	`0.5`	Packet age deadline in seconds. Packets older than this are dropped by the dispatcher before delivery.
`ber`	number	`0.0`	Bit-error rate in [0, 1]. 0 = no artificial errors. Applied by the dispatcher before AoI accounting.
`clock_timeout_s`	number	`5.0`	Seconds after which the physics clock falls back to wall clock if no NS-3 clock tick is received.
`clock_socket`	string	`"/tmp/cornet_clock.sock"`	UNIX socket path for the physics clock synchronisation channel.
`positions_socket`	string	`"/tmp/cornet_positions.sock"`	UNIX socket path for the PositionBroadcaster live position feed.
`sensor_port`	integer	`5001`	UDP port for robot sensor data flow (forwarded to NS-3 scratch script as --sensorPort). Default 5001.
`control_port`	integer	`5002`	UDP port for robot control command flow (forwarded to NS-3 scratch script as --controlPort). Default 5002.

MobilityConfig¶

Live position update settings for PositionBroadcaster.

Field	Type	Default	Description
`enabled`	boolean	`False`	Enable the PositionBroadcaster, which pushes Gazebo model poses to NS-3 node positions in real time.
`source`	string	`"socket"`	Position data source: 'socket', 'ros2_topic' (/tf), 'model_states' (Gazebo model states, including actors), or 'none'.
`update_hz`	number	`10.0`	Position update rate in Hz when update_mode='periodic'.
`update_mode`	string	`"periodic"`	When to push position updates: 'periodic' (every 1/update_hz s), 'threshold' (when movement exceeds position_threshold_m), 'step_aligned' (on NS-3 simulation step boundaries).
`position_threshold_m`	number	`0.5`	Minimum Euclidean movement in metres that triggers a position update when update_mode='threshold'.

ScenarioConfig¶

5G/6G NS-3 scenario profile selection.

Field	Type	Default	Required	Description
`profile`	string	—	✓	NS-3 scenario profile to run. One of: 5g_nr_urllc, 5g_nr_embb, 5g_nr_mmtc, 6g_thz.
`numerology`	integer	null	null
`bandwidth_mhz`	number	null	null
`scheduler`	string	null	null
`experimental`	boolean	`False`		Automatically set to True for profiles that are not production-ready (e.g. 6g_thz). Do not set manually.

RadioSitesConfig¶

3GPP deployment preset (network.radio_sites).

Field	Type	Default	Required	Description
`deployment`	string	—	✓	Deployment preset. ISD and BS height are derived from the preset.
`rings`	integer	`0`		Hex rings: 0, 1, or 2 sites rings (1, 7, or 19 sites).
`sectors`	integer	`3`		Sectors per site. 1 or 3.
`inf_scenario`	string	null	null
`inf_hall`	string	`"small"`		InF hall. small is 120 x 60 m at 20 m ISD; big is 300 x 150 m at 50 m ISD.
`rma_isd_m`	integer	null	null
`robot_anchor`	string	`"centre_site"`		Point in the layout that is aligned with the world origin.
`indoor_building`	boolean	`False`		Place the world as a building inside a macro layout, with outdoor-to-indoor loss.
`wraparound`	boolean	`False`		Install hexagonal wrap-around. Requires hex_wraparound.
`background_ues_per_cell`	integer	`10`		Background UEs per cell. Reduction is recorded in provenance.
`custom_sites`	list[SitePosition]	—		Explicit site positions for deployment custom. Each item has x, y, and optional z.
`blockage`	string	`"none"`		TR 38.901 Model A when model_a. Model A does not follow actor positions.
`non_self_blockers`	string	null	null

SitePosition¶

One explicit site for a custom deployment.

Field	Type	Default	Required	Description
`name`	string	null	null
`x`	number	—	✓	Site X position in metres.
`y`	number	—	✓	Site Y position in metres.
`z`	number	null	null

PopulationEntity¶

One background-population archetype.

Field	Type	Default	Required	Description
`archetype`	string	—	✓	Background entity. Walkers have a Gazebo body; phone users also have an NS-3 UE.
`count`	integer	`1`		How many entities of this archetype to place.
`zone`	string	null	null
`motion`	PopulationMotion	null	null
`traffic`	PopulationTraffic	null	null
`channel`	integer	null	null

PopulationMotion¶

Walker speed range for seeded waypoint times.

Field	Type	Default	Required	Description
`speed_mps`	list[number]	—		Walker speed range in metres per second. Waypoint times use a seed draw from this range.

PopulationTraffic¶

Traffic profile for a population device.

Field	Type	Default	Required	Description
`profile`	string	—	✓	NR and LTE use a 5G-LENA NGMN/3GPP generator. WiFi uses an NS-3 application.

CatalogProvenance¶

Catalogue compiler provenance (catalog).

Field	Type	Default	Required	Description
`robot`	string	—	✓	Robot pack name.
`world`	string	—	✓	World pack name.
`network`	string	—	✓	Network pack name.
`versions`	dict[str, string]	—		Pack name to pack version.
`standard`	boolean	`True`		False for a custom deployment or a non-default blockage mapping.
`controller_placement`	string	`"edge_server"`		edge_server is one radio hop. ue places the controller as a second UE.

RobotConfig¶

Robot simulation backend settings (robot: section).

Field	Type	Default	Required	Description
`plugin`	string	—	✓	Robot simulation backend plugin identifier (e.g. 'gazebo').
`launch_file`	string	null	null
`world`	string	null	null
`robots`	list[RobotEntry]	`[]`		List of robots to spawn in the simulation world.
`model_paths`	list[string]	—		Directories prepended to GAZEBO_MODEL_PATH so world packs can resolve model:// URIs.

RobotEntry¶

A single robot to spawn in the simulation world.

Field	Type	Default	Required	Description
`name`	string	—	✓	Unique robot identifier within the simulation (used as ROS namespace and Gazebo model name).
`model`	ModelConfig	—	✓	Robot model file reference (URDF or SDF).
`pose`	PoseConfig	—		Initial spawn pose in the Gazebo world.
`ros_namespace`	string	null	null

ModelConfig¶

Robot model file reference.

Field	Type	Default	Required	Description
`type`	string	—	✓	Robot model format: 'urdf' (ROS 2) or 'sdf' (Gazebo/SDF).
`path`	string	—	✓	Path to the model file, relative to the task directory or absolute.

PoseConfig¶

Initial spawn pose for a robot.

Field	Type	Default	Description
`x`	number	`0.0`	X position in metres (world frame).
`y`	number	`0.0`	Y position in metres (world frame).
`z`	number	`0.0`	Z position in metres (world frame, 0 = ground level).
`roll`	number	`0.0`	Roll angle in radians.
`pitch`	number	`0.0`	Pitch angle in radians.
`yaw`	number	`0.0`	Yaw angle in radians (0 = facing +X axis).

ExperimentConfig¶

Experiment runtime settings (experiment: section).

Field	Type	Default	Required	Description
`name`	string	—	✓	Human-readable experiment name, used as the leaderboard title.
`duration`	number	—	✓	Experiment wall-clock duration in seconds. The orchestrator terminates all plugins after this time.
`seed`	integer	`1`		Base seed for catalogue placement and NS-3 --rngRun. Sweep repeats use seed, seed+1, seed+2, and so on.
`output_dir`	string	`"results"`		Directory where results, logs, and leaderboard entries are written (relative to task directory or absolute).
`primary_metric`	string	null	null
`higher_is_better`	boolean	`False`		Leaderboard sort direction for primary_metric. True = higher score ranks first; False = lower score ranks first.
`sweep`	SweepConfig	null	null
`timing`	TimingConfig	—		Thresholds for per-run timing telemetry (Gazebo RTF and NS-3 realtime lag). Monitoring only.

SweepConfig¶

Parameter sweep configuration.

Field	Type	Default	Required	Description
`axes`	dict[str, list[any]]	—	✓	Parameter sweep axes as a mapping of dot-path config keys to lists of values (e.g. {'network.numerology': [1, 2, 3], 'network.bandwidth_mhz': [20, 40]}). The cartesian product of all axes is expanded into one variant per combination.
`parallel`	boolean	`False`		Run sweep variants in parallel subprocesses. False = sequential (safer for resource-limited machines).
`repeats`	integer	`1`		Number of independent repetitions per variant (for statistical averaging). Must be >= 1.