Installing Utopia

Step-by-step instructions

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; consult the documentation for more information on how to use it.

These instructions are intended for ‘clean’ macOS or Ubuntu (20.04) setups. Utopia is always tested against a recent Ubuntu release. However, you may also use Utopia with an earlier release, as long as the dependencies can be fulfilled.

1

Clone or fork the repository

You can clone the code from the Gitlab repository, or fork the project on Github:

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

If you are a developer, get an SSH key registered and clone via SSH.
Detailed instructions arrow-right

2

Install Utopia and dependencies

Install the third-party dependencies using a package manager. For instance, on macOS and using homebrew, do

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

See the full instructions for details on how to install on other platforms. Then, navigate to your top-level directory containing the ‘utopia’ folder and create a build directory:

cd utopia
mkdir build

Now, enter the build directory and invoke CMake:

cd build
cmake ..

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
Detailed instructions arrow-right

3

Read the beginner's tutorial

In the Utopia tutorial, you will learn how to configure, run, and evaluate the models already implemented in Utopia. After having worked through it, you can apply the learned concepts and methods to all available models; the content and available parameters may change but the structure remains the same. You can also use this tutorial as a reference guide, in which you can look up how to run a model simulation or configure plots.
To the tutorial arrow-right

4

Build your own model

Utopia makes building, running and evaluating your own model easy. You can start from scratch, modify one of the pre-impelemented models, or base your model on one of three templates models that you may find provide a good starting point for your specific scenario:

  • CopyMeGrid: A basic Cellular Automaton model. Already includes the CellManager. Recommended if you want to work with a Cellular Automaton
  • CopyMeGraph: A basic graph model. Already includes a graph and example functionality. Recommended if you want to work with a graph.
  • CopyMeBare: The bare basics. Really. Recommended if you do not need a Cellular Automaton or a Graph, and are already proficient with Utopia.
Detailed instructions arrow-right

5

Troubleshooting

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.