This repository contains Utopia models by Thomas Gaskin

• Installation
• Model Documentation
• Quickstart
• Information for Developers
• Dependencies

Note: If not mentioned explicitly, all instructions and considerations from the main repository still apply here. ☝️

The following instructions assume that you built Utopia in a development environment, as indicated in the framework repository's README.

These instructions are intended for homebrew-based Ubuntu or macOS setups with Utopia already built by your user.

⚠️ Be aware that this repository has some additional dependencies which might not be satisfiable easily on Ubuntu without homebrew. If you don't use homebrew, you will have to fulfil the required dependency versions in some other way.

Follow the setup procedure of the Utopia framework repository as described in its README.

Enter the Utopia directory into which you previously cloned the main repository.

With access to the Utopia GitLab group, you can clone the repository to that directory using the following command:

git clone <CLONE-URL>

Inside your top level Utopia directory, there should now be (at least) two repositories:

• utopia: the framework repository
• KronGen: this repository with your own models

Install the third-party dependencies using homebrew.

If you use some other package manager, make sure to fulfil the dependencies requirements. Additionally, consider the notes given in the section on installing dependencies in the Utopia framework repository.

brew update
brew install <additional-dependencies-here>

If you want, install the optional dependencies:

brew install fftw doxygen

Enter the repository and create your desired build directory:

cd models
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 KronGen
make -j4 all    # builds all models, using 4 CPUs

You should now be able to run Utopia models from both the framework and this repository via the Utopia CLI.

Upon configuration, CMake creates symlinks to the Python virtual environment of the Utopia repository. You can enter it by navigating to either of the build directories and calling

source ./activate

You can now execute the Utopia frontend as you are used to, only now the models of this repository should be available.

• If the cmake .. command fails because it cannot locate the Utopia main repository, something went wrong with the CMake User Package Registry. You can always specify the location of the package build directory via the CMake variable Utopia_DIR and circumvent this CMake feature:

  cmake -DUtopia_DIR=<path/to/>utopia/build ..

• If your model requires a certain branch of the Utopia framework, make sure to re-configure and re-build the framework repository after switching the branch.

Unlike the main Utopia documentation, the models included in this repository come with their own documentation which has to be built locally. It is not available online.

To build these docs locally, navigate to the build directory and execute

make doc

The Sphinx-built user documentation will then be located at build/doc/html/, and the C++ doxygen-documentation can be found at build/doc/doxygen/html/. Open the respective index.html files to browse the documentation.

The Utopia command line interface (CLI) is, by default, only available in a Python virtual environment, in which utopya (the Utopia frontend) and its dependencies are installed. This virtual environment is located in the main (utopia) repository's build directory. However, symlinks to the activate and run-in-utopia-env scripts are provided within the build directory of this project. You can enter it by specifying the correct path:

source <path/to/{utopia,models}>/build/activate

Now, your shell should be prefixed with (utopia-env). All the following should take place inside this virtual environment.

As you have already done with the dummy model, the basic command to run a model named KronGen is:

utopia run KronGen

You can list all models registered in the frontend with

utopia model ls

Please refer to the documentation of the framework repository.

Not all test groups of the main project are available in this repository.

Note:

• Identifiers marked with † require all models to be built (by running make all).
• Identifiers marked with ‡ do not have a corresponding build_tests_* target.
• Notice that you cannot execute tests for models of the main project in this repository.

Code coverage is useful information when writing and evaluating tests. The coverage percentage of the C++ code is reported via the GitLab CI pipeline. Check the README.md in the main repository for information on how to compile your code with coverage report flags and how to retrieve the coverage information.

These dependencies come on top of Utopia's dependencies. For some dependencies, a more recent version number is required than by the Utopia framework; the numbers given here take precedence and are enforced. Note that the homebrew-based CI/CD testing image might use more recent versions, so it's actually best to have those installed.

⚠️ There seem to be some weird errors with boost v1.74, observed only in the pipeline, thus the testing image uses v1.71.

If your models require additional Python packages (e.g., for plotting and testing), they can be added to the python/requirements.txt file. All packages listed there will be automatically installed into the Python virtual environment as part of the CMake configuration.

Note that if such an installation fails, it will not lead to a failing CMake configuration.