munetauvsim.simulator

Core simulation driver for AUV multi-agent scenarios.

Provides the Simulator class for running autonomous underwater vehicle simulations with support for multiple vehicles, swarm coordination, communication networks, environmental modeling, data collection, and visualization.

Classes

Simulator: Main simulation orchestrator for AUV scenarios.

Functions

save(simulation, filename, format): Save Simulator object to file (pickle format).
load(filename, format): Load Simulator object from file.

Notes

Supports direct-access (no network), muNet, and AquaNet communication modes.

Functions

`load`(filename[, format])	Load Simulator object from file.
`save`(simulation[, filename, format])	Save Simulator object to file.

Classes

`NDArray`	alias of `ndarray`[`Any`, `dtype`[`ScalarType`]]
`NPFltArr`	alias of `ndarray`[`Any`, `dtype`[`float64`]]
`Simulator`([name, sampleTime, N, ocean, ...])	Main simulation coordinator for multi-agent AUV scenarios.

class munetauvsim.simulator.Simulator(name='Simulation', sampleTime=0.02, N=60000, ocean=None, vehicles=None, comnet=None, logging='all', commLogging='all', **kwargs)[source]

Bases: object

Main simulation coordinator for multi-agent AUV scenarios.

Manages the complete simulation workflow including time evolution, vehicle dynamics integration, environmental modeling, inter-vehicle communication, data collection, collision detection, and visualization. Supports multiple communication modes (direct-access, MuNet, AquaNet) and flexible deployment strategies for swarm coordination research.

Parameters:

name (str, default='Simulation') – Simulation title. Used for output directory and file naming.
sampleTime (float, default=0.02) – Iteration time step in seconds (50 Hz default). Used for discrete-time integration of vehicle dynamics and kinematics.
N (int, default=60000) – Total number of simulation iterations. With default sampleTime, gives 20 minutes of simulated time.
ocean (env.Ocean, optional) – Ocean environment object containing Ocean current and floor depth map. If None, simulation runs without environmental effects.
vehicles (list of Vehicle, optional) – List of vehicle objects to simulate. Can be added after initialization via the vehicles property.
comnet (str, {'muNet', 'AquaNet', None}, optional) – Communication network type. If None, uses direct-access mode where vehicles can directly read each other’s states (no network delays).
logging (str, default='all') – Main logger configuration. Options: ‘all’, ‘none’, ‘noout’, ‘nofile’, ‘quiet’, ‘onlyfile’, ‘onlyconsole’.
commLogging (str, default='all') – Communication logger configuration. Same options as logging parameter.
**kwargs (dict) – Additional attributes to set on simulator instance.

Attributes

Time Management:

sampleTimefloat
Simulation time step (seconds per iteration).

Nint
Number of simulation iterations.

runTimefloat
Total simulation time in seconds. Equal to N * sampleTime. Setting any of these three automatically updates the others.

simTimendarray, shape (N+1,)
Time vector for plotting. Includes t=0 start point.

initTimestr
Timestamp when simulator was created (YYMMDD-HHMMSS format).

Environment and Vehicles:

oceanenv.Ocean
Ocean environment with currents, floor depth, etc.

vehicleslist of Vehicle
List of all vehicles in simulation.

nVehint (read-only)
Number of vehicles in simulation.

Communication Networks:

comnetstr
Communication network type (‘Direct-Access’, ‘muNet’, ‘AquaNet’).

muNetcomm.MuNet
muNet network instance (if using muNet).

Output and Logging:

namestr
Simulation name. Can only be set at initialization.

outDirstr (read-only)
Output directory path: outputs/<script_name>/<name>_<timestamp>/

saveFilestr (read-only)
Full path for saving simulator object (pickle).

logFilestr
Path to main log file.

commFilestr
Path to communication log file.

gifFilestr
Path to animated GIF output.

loglogging.Logger
Main simulation logger instance.

loggingstr
Main logger configuration setting.

commLoggingstr
Communication logger configuration setting.

Data Collection:

simDatandarray, shape (nVeh, N+1, 18)
Complete simulation data array containing vehicle states and controls. For each vehicle and timestep: [eta(6), nu(6), u_control(3), u_actual(3)]. Size N+1 to include initial conditions at t=0.

Visualization:

numDataPointsint, default=200
Number of trajectory points displayed in 3D animation.

FPSint, default=8
Frames per second for animated GIF output.

Vehicle Proximity Monitoring:

vehProxMultfloat, default=1.0
Safety multiplier for vehicle contact radius. Contact radius = vehicle_length * vehProxMult.

vehProxImmobilizebool, default=True
If True, vehicles stop moving on contact detection for the remainder of the simulation.

Internal Group Management (Private):

_groupsDictdict
Dictionary of non-leader vehicles by groupId.

_leadersDictdict
Dictionary of leader vehicles by groupId.

_noneGrouplist
Vehicles without groupId or target assignment.

_contactCountint
Total number of vehicle collisions detected.

_contactRadiusndarray
Cached contact threshold distances for all vehicle pairs.

Methods

Simulation Execution:

run()
Execute complete simulation: loop, collect data, log stats, generate plots.

simulate()
Run iteration loop and return collected simulation data.

Visualization:

plot3D(numDataPoints, FPS, gifFile, vehicles, figNo, show*)
Create 3D animated visualization and save as GIF.

Vehicle Deployment:

deployAtWpt(vehicle, posOnly)
Deploy vehicle at next waypoint position in its database.

deploySwarmGrid()
Deploy vehicles in grid formation by group, West of leader.

Swarm Coordination:

linkSwarmGroup()
Populate vehicle.group lists with references or Models for coordination.

Communication Setup:

loadMuNet(network, episode, txOffset, vehicles, kwargs)
Configure MuNet communication network.

loadAquaNet(episode, frames, vehicles)
Configure AquaNet TDMA communication.

Monitoring and Logging:

initVehicleContactMonitor()
Initialize collision detection system.

logCommStats()
Log network performance statistics.

Internal Simulation Loops (Private):

_simulateNoComm(nVeh, simData)
Direct-access iteration loop (no network delays).

_simulateMuNet(nVeh, simData)
muNet communication iteration loop.

_simulateAquaNet(nVeh, simData)
AquaNet TDMA iteration loop with time synchronization.

_simSync()
Synchronize simulation time with AquaNet communication timing.

Notes

Time Parameter Interdependence:

The attributes sampleTime, N, and runTime are coupled:

sampleTime can be set directly
N and runTime update automatically when one is set
Setting sampleTime recalculates runTime if N is defined

Example:

>>> sim.sampleTime = 0.01   # 100 Hz
>>> sim.N = 10000           # 100 seconds at 100 Hz
>>> print(sim.runTime)
100.0

Communication Modes:

Direct-Access (comnet=None):
- Vehicles directly read each other’s states
- No network delays or packet loss
- Ideal for baseline comparisons
muNet (comnet=’muNet’):
- Simulated acoustic modem network
- Configurable packet loss, jitter, collision detection
- Supports FDMA and TDMA access modes
AquaNet (comnet=’AquaNet’):
- Real AquaNet stack via Unix sockets
- TDMA protocol with leader-follower timing
- Requires AquaNet installation and configuration

Output Directory Structure:

outputs/
    <script_name>/
        <name>_<timestamp>/
            <name>_<timestamp>.log          # Main log
            <name>_<timestamp>_comm.log     # Communication log
            <name>_<timestamp>.gif          # Animation
            <name>_<timestamp>.pickle       # Saved simulator

Vehicle Contact Detection:

The simulator continuously monitors vehicle-vehicle distances during simulation. When distance < contact_radius:

Warning logged with vehicle IDs and positions
Contact counter incremented
Vehicles immobilized (if vehProxImmobilize=True)

Contact radius based on vehicle length and safety multiplier.

Examples

### Basic simulation with path-following leader:

>>> import munetauvsim.simulator as muSim
>>> import munetauvsim.environment as env
>>> import munetauvsim.vehicles as veh
>>> import munetauvsim.guidance as guid
>>> import munetauvsim.communication as com
>>>
>>> # Create vehicles
>>> leader = veh.Remus100s(groupId="A", isLeader=True)
>>> leader.wpt = guid.Waypoint([0, 500], [0, 500], [0, 15])
>>> leader.loadPathFollowing()
>>> leader.loadConstantProp()
>>>
>>> # Create simulator
>>> sim = muSim.Simulator(
...     name="LeaderDemo",
...     sampleTime=0.02,
...     N=30000,  # 10 minutes
...     ocean=env.Ocean(),
...     vehicles=[leader]
... )
>>>
>>> # Deploy and run
>>> sim.deployAtWpt(leader)
>>> sim.run()

### Multi-agent swarm with muNet communication:

>>> # Create swarm
>>> leader = veh.Remus100s(groupId="A", isLeader=True)
>>> leader.wpt = guid.Waypoint([0, 1000], [0, 0], [0, 40])
>>> leader.loadPathFollowing()
>>> leader.loadConstantProp()
>>>
>>> followers = veh.buildGroup(3, "A", hasLeader=False)
>>> for f in followers:
...     f.loadTargetTracking(leader, law="APF")
>>>
>>> # Setup communication
>>> network = com.MuNet(PLR=0.05, MAX_JITTER=0.3)
>>>
>>> # Create simulator
>>> sim = muSim.Simulator(
...     name="SwarmDemo",
...     N=60000,  # 20 minutes
...     ocean=env.Ocean(spd=0.5, ang=0),
...     vehicles=[leader] + followers
... )
>>>
>>> # Configure and run
>>> sim.loadMuNet(network, episode=5.0, txOffset=0.5)
>>> sim.deployAtWpt(leader)
>>> sim.deploySwarmGrid()
>>> sim.run()
>>> muSim.save(sim)

### Load and analyze previous simulation:

>>> sim = muSim.load(
...     "/path/to/outputs/SwarmDemo/SwarmDemo_241103-143000.pickle"
... )
>>> print(f"Simulation ran for {sim.runTime} seconds")
>>> print(f"Vehicle contacts: {sim._contactCount}")
>>>
>>> # Re-plot with different settings
>>> sim.plot3D(numDataPoints=500, FPS=12, showFloor=False)