Utopia features
Model building
Utopia provides powerful tools for implementing scientific computer models, starting from the infrastructure supplied by the Model base class and ranging to ready-to-use manager structures for implementing cellular automata or agent-based models.
Here is an overview of some of its most useful model building features.
When implementing a model you almost always will need access to model configurations, datasets for writing data, a random number generator, and other infrastructure.
Such basic functionality is conveniently provided by the Model base class.
It also prescribes the fundamental structure of your model by separating where the dynamic happens (perform_step), what development to track while simulating (monitor), and which data to write (write_data).
This unified model structure allows for a smooth integration of your model into the framework without imposing strong restrictions in how you implement your model.
Many models' dynamics can be formulated as a set of iteratively called rules. A rule function operates on a single entity of a model — a cell, an agent, or the node of a network — and implement a certain action like conditionally moving an agent in space, updating the opinion of an agent in a social network, or updating a cell state in a cellular automaton.
Depending on the rule function, there are certain requirements to their application. Can they be applied to all entities at once (synchronously) or rather consecutively (asynchronously)? Should they be applied to all entities or only to a subset? Do the rules perhaps require a randomized iteration order to prevent modeling artifacts?
Utopia ships with a simple-to-use rule application interface, apply_rule, which helps to implement rule-based models.
This feature aims to prevent common modeling pitfalls by prompting a model developer to reflect on the choice of application method.
Using this interface, an iteration step of the Geomorphology model looks like this:
void perform_step () {
// Perform erosion and uplift processes
apply_rule<Update::sync>(erode, _cm.cells());
apply_rule<Update::sync>(uplift_rule, _cm.cells());
// Topple the cells; need random and asynchronous application here
apply_rule<Update::async, Shuffle::on>(toppling, _cm.cells(), *this->_rng);
// Finally, can build the drainage network
build_network();
}
The physical Space a model is embedded in contains information on dimensionality, periodicity, and physical extent.
Each Model has, by default, a 2D space attached; periodicity and extent is set by the base Model using the model configuration.
It is used by managers to map a grid to the space or control agent movement.
The CellManager creates a grid discretization of the physical space and aims to be controllable from the configuration while providing a good performance.
The AgentManager managers agents in space and lets them move to a relative or absolute position.
It also makes sure that the agent does not leave the bounds specified by the associated physical space the model is embedded in.
Utopia models use a strictly hierarchical structure for model configurations and all associated infrastructure. Subsequently, it becomes possible to nest models within other models.
For instance, one model could represent the movement of agents in space while another represents the dynamics of the environment. These could now be embedded into a common parent model, which implements the interaction of these two models.
Utopia provides extensive capabilities to simulate network processes. It includes a broad variety of fast graph generation algorithms, including for scale-free, small-world, or highly clustered graphs. You can also load a custom graph from a file to use for your simulations. Utopia allows attaching custom objects to graphs (such as vertex properties or edge weights), as well as an interface to easily apply rules to graph entities.
Utopia overloads several STL algorithms with runtime execution policies for multithreading and vectorization. The code is agnostic to whether the optional dependencies for multithreading are installed.
Utopia’s ExecPolicy mirrors STL execution policies.
Parallel features can be controlled via the meta-configuration without requiring re-compilation of the model.
Building a model in a new framework can be overwhelming and frustrating.
To help you with it, Utopia comes with three template models: CopyMeGraph, CopyMeGrid, and CopyMeBare.
Each contains:
- The
Modelbase class - Minimal configuration files for the model and its plots
- A template documentation file
- Python modules for model testing and evaluation
- Explanatory comments
In addition, CopyMeGrid and CopyMeGraph provide minimal CA-based or graph-based Utopia models, with infrastructure for setting up and writing cell and graph data, constructors, and example configuration files.
With these template models, copying a model becomes as simple as invoking the following CLI command:
utopia models copy CopyMeGraph --new-name MyGraphModel
In principle, model development can happen directly in a fork or clone of the utopia GitLab project.
However, in the scientific context, it is often desired to have development happen in a separate project, using Utopia as a library.
To simplify setting up a separate repository and corresponding project infrastructure for your model implementations, we provide a template repository. With that template, setting up a new project is done in a few easy steps:
pip install cookiecutter
cookiecutter https://gitlab.com/utopia-project/models_template
# ... and follow the prompts ...
The template not only includes the required build system infrastructure, ready-to-go, but also a GitLab CI/CD configuration that can be adapted to your needs.