MSS, a marine control systems simulator in MATLAB and Octave

What MSS is and where it sits

The Marine Systems Simulator is a MATLAB library for designing and testing marine control systems, and the m-files are compatible with the free GNU Octave. The README states it includes models for ships, underwater vehicles, uncrewed surface vehicles and floating structures, and that the library contains guidance, navigation and control functions for time-domain simulation.

Its relationship to a book is unusual and defines the project. MSS supplements the Handbook of Marine Craft Hydrodynamics and Motion Control, third edition, by T. I. Fossen, published in 2027 and in progress by John Wiley and Sons. The lecture notes at wiley.fossen.biz serve as the documentation for the toolbox. So the library is the executable companion to a textbook, which means its API choices, its notation and its models are all consistent with the book, and reading them together is the intended way to use it.

The repository structure follows the textbook's subject areas. CRAFT/ holds the craft model library and the time-domain simulation scripts. GNC/ holds guidance, navigation and control functions. INS/ holds inertial navigation and attitude estimation. HYDRO/ holds the hydrodynamic data processing. LIBRARY/ and FDI/ hold shared helpers and fault detection and isolation. SIMULINK/ holds Simulink models, mssExamples/ holds the textbook m-file examples, mssDemos/ the demos, and documentation/ the supporting files.

The top level also has Contents.m, the file MATLAB uses to index a toolbox, plus mssHelp.m and mssPath.m. mssPath is the path management script, and the README notes that it can update an existing path and remove dead links.

The release history is steady, with 2.0.4 and 2.0.5 both on 2026-10-09 and 2.0.6 on 2026-10-14, and the last push on 2026-10-20. The licence is MIT.

Release 2.0 and the Capytaine workflow

Release 2.0 substantially expands the CRAFT library, and the change worth understanding is the shift in where the hydrodynamic data comes from.

The new hydroVessel.m function implements the 12-state, 6-DOF equations of motion, and the editable SIMhydroVessel.m simulator is a reusable template for building a user-defined surface vessel, USV, AUV or ship. It includes a basic GUI for selecting the vessel and configuring the simulation, supports irregular seas with selectable wave spectra and directional spreading, computes first-order wave forces from force RAOs, models ocean currents, and can run either heading-autopilot or dynamic positioning control.

The hydrodynamic data itself can come from ShipX, WAMIT or Capytaine. The first two are commercial: ShipX is a 2D strip-theory program from SINTEF OCEAN AS, and WAMIT is a 3D potential-flow program from WAMIT Inc. The third is Capytaine, an open source 3D potential-flow boundary-element solver, reached through the MSS-Capytaine Python add-on. The README says this release places particular emphasis on that add-on, since it provides a freely available workflow for generating hydrodynamic vessel models.

That is the substantive change. A student or a small team without a commercial hydrodynamics licence previously had to model vessels with the textbook's simplified formulations; now they can run a potential-flow solver and feed real coefficients into the same simulator.

There is also a specific vessel model rather than a generic one. The lauvMarie.m and SIMlauvMarie.m pair is a standalone, wave-enabled model of the 2.15 m LAUV Marie at NTNU, combining MSS-Capytaine hydrodynamic data with a unified power-based seakeeping and maneuvering formulation, calibratable viscous and friction terms and additional nonlinear hydrodynamic terms. Its simulation supports ocean currents, directional JONSWAP waves with depth-attenuated first-order loads, depth and heading control, and ALOS guidance for 3-D path following.

The one removal to note is that the legacy Simulink vessel templates have been removed, although the Simulink library and demonstration models remain.

The GNC, INS and HYDRO libraries

The three subject libraries are listed in the README with enough detail to judge whether they cover your problem.

The GNC library holds reusable guidance, navigation and feedback control functions. Path following is two and three dimensional using line-of-sight, integral LOS and adaptive LOS methods, which are the standard LOS family and its variants for compensating wind and current. Paths include straight-line waypoint paths, Hermite splines and hybrid paths, with cross-track error and path-projection utilities. Navigation includes a five-state GNSS extended Kalman filter and static roll, pitch and yaw estimation from IMU measurements. Control includes nonlinear MIMO PID for dynamic positioning, integral sliding-mode heading control and linear-quadratic tracking, plus control allocation, command and reference models, LOS command filtering and saturation utilities.

The INS library covers inertial navigation and attitude estimation, with user-editable functions and simulation examples. It has aided error-state Kalman filters using either Euler-angle or unit-quaternion attitude representations, multiplicative extended Kalman filters for quaternion attitude and aided INS estimation, and a nonlinear Mahony-Hamel-Pflimlin quaternion attitude observer with angular-rate bias estimation. There are examples for position, velocity, compass, magnetometer, AHRS and pressure-aided navigation including heave estimation, plus IMU test-signal generation and gravity and magnetic-field reference models.

The HYDRO library reads the output files that seakeeping programs produce and processes them for use in MATLAB or Octave. It ships example vessels and supports data from ShipX, WAMIT and Capytaine. The Capytaine path is the open one, and the README mentions pre-generated Capytaine cases for a synthetic testShip in HYDRO/vessels_capytaine.

Each library has its own markdown documentation file with a categorised function overview, which is the fastest way to see whether a specific algorithm you need is implemented.

FDI, the Simulink part and what the toolbox does not cover

Two parts of the repository are worth a mention because they tell you what the toolbox is for.

The FDI/ directory holds fault detection and isolation. In marine control that is not a niche requirement: a propulsion fault on an autonomous surface vessel has to be detected and isolated so the remaining actuators can take over, and the diagnostic algorithms are a different family from the guidance and control ones in GNC.

The SIMULINK/ directory holds Simulink models and demos. That matters because MATLAB is not the only tool in the academic marine control world; Simulink is what most of the published control papers are built in, and the toolbox supports both worlds. The legacy Simulink vessel templates were removed in release 2.0 while the Simulink library and demonstration models remain, so the direction is toward the m-file scripts as the primary interface with Simulink as a secondary route.

What the toolbox does not cover is as important to state. It is a simulation and design library, not a control system implementation for a specific hardware target, and the README gives no indication of code generation for real hardware. The INS library covers estimation and the GNC library covers guidance and control, but the link from those algorithms to a running autopilot on a specific vessel is left to the user.

It is also specific to marine craft. The hydrodynamics, the seakeeping models, the manoeuvring formulations and the guidance laws are all for vessels in water. The framework generalises in the sense that the GNC and INS functions are reusable, but the craft models are the part that makes it a domain library rather than a general simulation toolkit.

One more constraint to plan around: the Octave compatibility is claimed for the m-files, and the installation guide for Octave notes that the old path in the startup file must be deleted before a new path with subfolders is saved. Any tool that touches the Octave startup file has to be handled carefully, since a stale entry left behind will break the library on the next run.

Installing it and using the examples

There is no package manager step. MSS is installed by placing the repository on the MATLAB path or the Octave path, and the README points at two separate installation guides, one for MATLAB and one for GNU Octave.

For MATLAB the guide covers updating an existing path automatically and removing dead links using the mssPath command. For Octave the instruction is slightly more involved: the old path in the startup file has to be deleted before a new path with subfolders is saved, because the Octave startup file keeps the path entries and a stale entry pointing at a moved directory breaks the library.

Once installed, the entry point is a single command in the MATLAB command window:

mssHelp

which is how you get started and find help on using the library.

The examples live under three catalogs. /MSS/mssExamples/ holds the textbook m-file examples for the 2027 edition of the handbook. /MSS/mssDemos/ holds the MSS m-file demos. /MSS/SIMULINK/mssSimulinkDemos/ holds the Simulink demos.

The craft models and editable simulation scripts are under /MSS/CRAFT/, with the CRAFT-Library.md documentation describing the available models, scripts and the hydrodynamic vessel workflow.

A worked example of what the output looks like is given in the README: the user-editable script SIMremus100.m simulates the Remus 100 AUV, described in the figure caption, during 3-D path following. That is the pattern the library is built around. The model file describes the vehicle, and the SIM script is yours to edit, changing the sea state, the guidance law or the controller and watching what happens.

For citation, the README asks that the software be cited as Fossen, Thor I. (2026), Marine Systems Simulator, with a BibTeX block provided. The original development and historical background is attributed to Fossen and T. Perez (2004).

Editorial conclusion

Adopt MSS if you are simulating or designing marine craft control systems and want the same vessel models, guidance laws and estimators the textbook uses, in a language your numeric stack already speaks. Skip it if your work is on aircraft, ground vehicles or industrial processes, since the model library is specific to marine craft. Verify first by installing it for Octave and running mssHelp, then by opening one of the editable SIM scripts for a vessel and changing a sea state, since the point of the library is that the scripts are meant to be edited.

Frequently asked questions

Official sources

1. cybergalactic/MSS on GitHub
2. License: MIT
3. Project website
4. README
5. Releases