A comprehensive modeling framework for complex and adaptive systems.
Designed by researchers, for researchers.
Combines modern C++ with Python and YAML
Many example models
It’s free and open-source
Out-of-the-box plots and animations
Made for high dimensions
All the modelling tools you need, easily configurable.
Create a model
Model base class is the scaffolding for your model:
it loads the model configuration, sets up a random number generator and loggers, can send progress information
to the frontend, handle signals … and more.
By integrating a
CellManager or an
AgentManager, you can quickly get started on CA models and ABMs —
or implement your own dynamics.
Utopia’s pre-implemented models can be used as implementation examples and starting points,
simply by creating a new model from an existing one using the
utopia models copy command.
Hint: If you want to use another language than C++, that’s also possible.
Tell it what to do
Alongside your model implementation, a model configuration file holds the default parameters for your model. This avoids hard-coding values and makes your simulations more reproducible.
To configure a model, you merely need to specify the parameters you want to have updated. Also, defining parameter sweeps (for any parameter) is very easy:
ContDisease: # Sweep over the infection probability p_infect: !sweep default: 0.01 values: [0.01, 0.02, 0.04]
Configurability is a key design principle of Utopia: using YAML files, you can control almost every aspect of the framework’s setup, the model’s simulation, and its evaluation routine — without needing to write a single line of code. However, with sensible default values provided, you do not need to control everything.
Run your model – once or many times
Running a model is as simple as calling:
utopia run ContDisease
This will assemble all relevant configuration files and start the model simulation. In Utopia, an individual instantiation of a model is called a universe; the set of all universes is the so-called multiverse.
If parameter sweeps are configured, many universe simulations are carried out in parallel – or even distributed over the nodes of a cluster! All of this can be controlled from a powerful command line interface and via configuration files.
Data management: taken care of
Utopia takes care to have all simulation data written to a specific output directory. After the run has finished, the simulation data is automatically loaded into a tree-like structure, which houses data from different sources (HDF5, CSV, YAML, …) and can reflect their hierarchical organization.
The uniform interface of this data tree (implemented in
allows easy automation of data transformations and evaluation of model simulations.
Data analysis, right from the config
Utopia’s data processing pipeline deliberately separates the steps of transforming and visualizing the data, thus allowing for more generality and easier automation of plots.
It integrates dantro’s data transformation framework that allows to select and analyze data in preparation for visualizing it. Analysis steps can be defined directly in the config file, alongside the specification of a plot.
Visualization – automated, simple, flexible
The plotting framework makes evaluation of your simulation run very easy. With data transformation taken care of, creating a new plot is as simple as specifying what you want to plot in which way – all from the plot configuration, without needing to touch any code.
By allowing to base a plot configuration on existing templates, repetitions are reduced. For instance, to generate an animated plot for a cellular automaton (CA) time series, you simply add the following entry to the plot configuration:
ca/age: # name of the plot based_on: - .creator.universe # one plot per universe - .plot.ca # specialized CA plot - .animation.ffmpeg # turn on animation select: # the data to plot … age: age to_plot: # … and how to plot it age: title: Age cmap: YlGn limits: [0, max]
Plots can be configured to be generated automatically after each simulation; or if a predefined condition is met.
If you want to evalute a simulation run again at a later point, it’s as easy as running the evaluation routine separately:
utopia eval ForestFire