Modules, mods for short, are, simply put, collections of data that can be gathered together and used to spawn a simulation instance. It’s helpful to think of mods as packages - mods allow for modularity, in the sense that we can put different collections of mods together and achieve a working simulation model that can be run.

This ability to combine multiple mods is the key here. For managing multiple mods within one “environment” we’re moving into the domain of scenarios.

Mod within the larger file structure

Mods always exist in dedicated mods directory. This directory can be found inside larger structures of scenarios, which almost by definition are collections of multiple mods.

File structure within the module

There are not many strict requirements in terms of internal organization of files in a module. One such requirement is the module.yaml file.


Each mod needs a module.yaml file present in it's top directory.


  • name unique name of the module, string without spaces
  • version version of the module
  • outcome version of the outcome architecture the module is written for


  • title evan more human readable version of the name
  • description briefly about the mod
  • description_long longer description
  • author group or person behind the mod
  • website place to get more information about the mod and people behind it
  • dependencies list of required modules for this module to work, see more about dependencies
# example of a module.yaml file
name: test_mod
title: Test mod
description: Just testing.
description_long: This is just a testing module, not really usable yet.
author: John Doe
version: 0.0.1
outcome: 0.0.1
  base: 0.0.1

Flexibility within the mod

Apart from the required files, there is much flexibility when it comes to organization of non-essential files (user-written module files) inside the mod. This flexibility is possible because the files themselves specify everything inside them - the declarations made within module files don't need any additional context. Thus, structure of directories within the mod, even the names of the files are not an essential part of the module file processing.

Program reading a module will read all files (given they have the proper yaml/json extensions).

Organization of files into directories can be useful, so can be certain approaches to naming the module files.