A comprehensive modeling framework for complex and adaptive systems.
utopya for simulation control and management
and dantro for data handling and visualization: 
Designed by researchers, for researchers.
Combines modern C++ with Python and YAML
Many example models
Parallelization
It’s free and open-source
It’s tested
Out-of-the-box plots and animations
Reproducibility
Made for high dimensions
Modularity
All the modelling tools you need, easily configurable.
Create a model
Utopia’s C++ 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 dantro)
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
The main goals of Utopia can be summarized as follows:
- Attempt to cover all “everyday aspects” of studying computer models.
- Adhere to software engineering best practices in order to produce reliable and reproducible results.
- Foster collaboration, e.g. by developing and using the framework throughout a research group; that way synergies can develop more rapidly and friction can be reduced.
Utopia was built with the following design philosophy in mind:
- Everything should be configurable — but with good defaults.
- Provide a wide set of tools, but don’t force them on the framework user.
- Prevent lock-in by using open data formats.
- Be computationally efficient, yet sufficiently customizable.
Utopia’s core capability is that it can bring together many (if not all) of the tools that you are using to study computer models and integrate them in a way that makes your workflow more efficient.
Utopia is for you, if
- You are interested in working with one of the many pre-implemented models for your own purposes, or
- You are a researcher looking for a comprehensive modeling tool to investigate complex processes, using e.g. network-based or grid-based models.
- You have knowledge both of C++ and Python.
On the other hand, you should not use Utopia, if
- Programming and using the command line is not your thing; Utopia embraces flexibility for programmers.
- You want a library with a simple and concise feature set; Utopia is feature-rich and extensive.
- You want a very quick solution: Utopia has a learning curve.
Model implementations in Utopia are only possible in C++, yes. This gives you access to the Utopia C++ library and the tried-and-tested tools to implement CA models, ABMs or graph-based models.
However, Utopia’s frontend utopya is built in a way that many of Utopia’s features are accessible even if not using the Utopia C++ library.
With utopya, you can invoke your own model executable, written in any language, and make use of the CLI, the configuration and simulation infrastructure, and the evaluation routines – depending on your needs.
Additionally, if you want to implement models in Python, the utopya_backend package can assist.
The base classes provided there are similar to the C++ Model base class and implement the basic simulation interface:
starting from reading the model configuration and setting up the random number generator, all the way to signal handling and communication with utopya.