Utopia

Utopia is a comprehensive modelling framework for complex and evolving systems. It aims to provide the tools to conveniently implement a model, configure and perform simulation runs, and evaluate the resulting data.

Utopia is free software and licensed under the [GNU Lesser General Public License Version 3][LGPL] or any later version. For the copyright notice and the list of copyright holders, see COPYING.md.

Overview

Complex and evolving systems are investigated with a wide array of different models types. Among the most popular are cellular automata (CA), agent-based models (ABMs), and network models. Utopia provides a library to build these types of models in modern C++. Its core template library contains functions for implementing model dynamics and scaffoldings for building new models. The Utopia dataIO library is capable of storing hierarchical simulation data efficiently in the H5 file format. Within Utopia, and when using Utopia as a dependency, models are integrated into a simulation infrastructure for conveniently executing and analyzing them.

The [utopya Python package][utopya] constitutes Utopia's frontend. It configures and performs the simulation runs and embeds the model into a data processing pipeline, such that the simulation data can directly be analyzed and visualized. All parts of the frontend make use of a hierarchic, recursively-updated YAML-based configuration structure. Using the [paramspace package][paramspace], this allows to easily define parameter sweeps, which can then be carried out as simultaneous simulations on massively parallel, distributed machines. The [dantro][dantro]-based data processing pipeline automates visualization, thereby coupling the model implementation and its analysis closer together.

Several models are readily included in the framework, among them Conway's Game of Life, one CA- and one agent-based contagious disease model, and a network-based model of social opinion dynamics. Investigating these models by performing simulation runs with a few varying parameters, or sensitivity analysis over a large parameter space, requires little to no programming skills.

For introductory guides, feature lists, FAQs, and API references refer to the online [user manual at docs.utopia-project.org][Utopia-docs]

Utopia development happens in the utopia-project group on GitLab.com. Additionally, you can retrieve the code and get in contact via a mirrored repository on [GitHub][Utopia-Github]. Note that we used to host our own GitLab instance at ts-gitlab.iup.uni-heidelberg.de; traces of that past development platform may still be around this project somewhere ... 👻

How to cite Utopia

Utopia was reviewed and published in the Journal of Open Source Software (JOSS). Please cite at least the following publication if you use Utopia (or a modified version thereof) for your own work:

Lukas Riedel, Benjamin Herdeanu, Harald Mack, Yunus Sevinchan, and Julian Weninger. 2020. “Utopia: A Comprehensive and Collaborative Modeling Framework for Complex and Evolving Systems.” Journal of Open Source Software 5 (53): 2165. DOI: 10.21105/joss.02165.

The CITATION.cff file in this repository follows the citation file format and contains additional metadata to reference this software, its authors, and associated publications. See the user manual for more information and BibTeX data.

Contents of this README

• How to install
  • On your machine
  • Alternative: docker image
• Quickstart
• Documentation and Guides
• Information for Developers
  • Testing
  • Setting up a separate models repository
• Dependencies
• Troubleshooting

---

<!-- ###################################################################### --> <!-- marker-installation-instructions -->

How to install

The following instructions will install Utopia into a development environment on your machine. If you simply want to run Utopia, you can do so via a [ready-to-use docker image][Utopia-docker]; see below for more information.

Step-by-step Instructions

These instructions are intended for 'clean' macOS (both Intel and Apple Silicon) or recent Ubuntu setups. Since Windows supports the installation of Ubuntu via Windows Subsystem for Linux, Utopia can also be used on Windows. Follow the WSL Installation Guide to install Ubuntu, then follow the instructions for Ubuntu in this README.

Note: Utopia is always tested against a recent Ubuntu release, currently Ubuntu 24.04 (LTS). However, you can use Utopia with any earlier release, as long as the dependencies can be fulfilled.

⚠️ If you encounter difficulties, have a look at the troubleshooting section. If this does not resolve your installation problems, [please file an issue in the GitLab project][Utopia-issues].

1 — Clone Utopia

First, create a Utopia directory at a place of your choice. This is where the Utopia repository will be cloned to. When working with or developing for Utopia, auxiliary data will have a place there as well.

In your terminal, enter the Utopia directory you just created and invoke the clone command:

git clone https://gitlab.com/utopia-project/utopia.git

Alternatively, you can clone via SSH, using the address from the "Clone" button on the [project page][Utopia].

After cloning, there will be a new utopia directory (mirroring this repository) inside your top-level Utopia directory.

2 — Install dependencies

Install the third-party dependencies using a package manager.

Note: If you have [Anaconda][Anaconda] installed, you already have a working Python installation on your system, and you can omit installing the python packages below. However, notice that there might be issues during the configuration step. Have a look at the troubleshooting section to see how to address them.

On Ubuntu (24.04 LTS)

apt update
apt install cmake gcc g++ gfortran git libarmadillo-dev libboost-all-dev \
            libhdf5-dev libspdlog-dev libyaml-cpp-dev pkg-config \
            python3-dev python3-pip python3-venv

Further, we recommend installing the following optional packages:

apt update
apt install ffmpeg graphviz doxygen

You will probably need administrator rights.

Note: For simplicity, we suggest installing the meta-package libboost-all-dev which includes the whole [Boost][Boost] library. If you want a minimal installation (only the strictly required components), use the following packages instead: libboost-dev libboost-test-dev libboost-graph-dev libboost-regex-dev.

On macOS

First, install the Apple Command Line Tools:

xcode-select --install

There are two popular package managers on macOS, [Homebrew][Homebrew] and [MacPorts][MacPorts]; we recommend to use Homebrew. Here are the installation instructions for both:

• Homebrew:

  Install the required packages:

  brew update
  brew install armadillo boost cmake hdf5 pkg-config python3 spdlog yaml-cpp
  

  Further, we recommend installing the following optional packages:

  brew update
  brew install ffmpeg graphviz doxygen
  

• MacPorts:

  Please be aware that port commands typically require administrator rights (sudo).

  Install the required packages:

  port install armadillo boost cmake hdf5 python37 py37-pip spdlog yaml-cpp
  

  Select the installed versions of Python and Pip:

  port select --set python python37
  port select --set python3 python37
  port select --set pip pip37
  port select --set pip3 pip37
  

  Further, we recommend installing the following optional packages:

  port install ffmpeg graphviz doxygen
  

3 — Configure and build

Enter the repository and create your desired build directory:

cd utopia
mkdir build

Now, enter the build directory and invoke CMake (and mind the caveats below):

cd build
cmake ..

Note: If you are using MacPorts, append the location of your Python installation to the CMake command (this is only required when calling CMake on a clean build directory):

cmake -DPython_ROOT_DIR=/opt/local ..

The terminal output will show the configuration steps, which includes the installation of further Python dependencies and the creation of a virtual environment.

After this, you can build a specific or all Utopia models using:

make dummy     # builds only the dummy model
make -j4 all   # builds all models, using 4 CPUs

4 — Run a model 🎉

You should now be able to run a Utopia model. Being in the build directory, call:

source ./activate

to enter the virtual environment, where the Utopia Command Line Interface (CLI) is available. (If you later want to exit the virtual environment, call the deactivate command.)

Note: If you are using csh or fish shells, use the respective activate scripts located in build/utopia-env/bin/ (see below).

The utopia command is now available and gives you control over running and evaluating model simulations:

utopia ru