Home

Welcome to the OpenMAS wiki

OpenMAS is an open-source multi-agent simulator for MATLAB. You build a scene as a cell array of object handles, place them in a global East-North-Up frame, and hand that array to OMAS_initialise. Each step the simulator integrates published velocity, builds an observation packet for every agent, and calls main. When the run ends it writes trajectories, events, and the figures you asked for.

This wiki is the newcomer guide: what the folders are, which class to use, how a scenario is laid out, which figures exist, and how the Monte Carlo studies are organised.

Start here

1. Getting Started — MATLAB, paths, and a first run of examples/setup_example.m.
2. Codebase — repository layout and what one time step actually does.
3. Creating agents, obstacles, and waypoints — the GLOBAL / setup / main contract.
4. Agent dictionary — every class, what it does, and where the file lives.
5. Scenarios — ready-made layouts and the scenario_builder generators.
6. Figures — every figures label and the data it needs.
7. Monte Carlo — studies, sessions, cycles, and the example scripts.
8. Studies and use cases — the paper setups and which script still matches the current API.

A simulation in one block

From the repository root:

addpath('core');
addpath(genpath('objects'));
addpath('scenarios');

agentIndex = cell(1, 3);
for k = 1:3
    agentIndex{k} = agent_2D_RVO('radius', 0.5);
end

objectIndex = scenario_concentric_ring( ...
    'agents', agentIndex, ...
    'agentOrbit', 10, ...
    'agentVelocity', 0, ...
    'waypointOrbit', 15, ...
    'plot', true);

[DATA, META] = OMAS_initialise( ...
    'objects', objectIndex, ...
    'duration', 30, ...
    'dt', 0.25, ...
    'figures', {'events', 'plan', 'gif'}, ...
    'outputPath', fullfile(pwd, 'data'));

DATA holds trajectories and event statistics. META holds the configuration, the object summaries, and META.outputPath, which is the session folder that also contains DATA.mat, META.mat, EVENTS.mat, and OBJECTS.mat.

How to choose a class

You want to…	Start with
Learn the interface	agent_example in examples/setup_example.m
Compare planar avoidance	agent_2D_VO, agent_2D_RVO, agent_2D_HRVO, agent_2D_ORCA
Compare spatial avoidance	agent_VO, agent_RVO, agent_HRVO, agent_vectorSharing, agent_IA
Fly a vehicle model	quadcopter, ARdrone, ARdrone_LQR, fixedWing
Hold a formation	agent_formation_* or agent_formation_boids
Place a static body	obstacle, obstacle_cuboid, obstacle_spheroid
Orbit a planet	earth, moon, ISS with scenario_earth_orbit
Repeat a scene with noise	OMAS_monteCarlo via setup_monte_carlo.m

The full list, inheritance, and file paths are on the agent dictionary.

Citation

@misc{openmas2020,
    author    = {Douthwaite, James A. and Mihaylova, Lyudmila S.},
    title     = {{OpenMAS - An open-source multi-agent simulator for MatLab}},
    year      = {2020},
    doi       = {10.15131/shef.data.11954418.v1},
    publisher = {figshare},
    url       = {https://figshare.shef.ac.uk/articles/OpenMAS_-_An_open-source_multi-agent_simulator_for_systems_with_complex_and_arbitrary_decision_mechanics_and_dynamic_behaviour/11954418/1}
}

Questions that are not answered here: Welcome and FAQs.