Utopia deliberately avoids versioning: You will neither find exact version numbers nor periodic releases of Utopia. Instead, the idea is to always use the latest version of the framework.
Despite the above approach towards versioning, large infrastructure changes are indicated by an increase in a major version (
vX) and a corresponding release branch of the same name.
We do not specify minor version numbers or patch numbers because we do not want to suggest that there is a versioning scheme; we’d like you to “live at HEAD”.
So far, there has only been one large enough infrastructure change to warrant a new major version.
The version of Utopia prior to that change is labelled
v1 – more information on that below.
The current version of Utopia is referred to as “latest”.
v2 is avoided to not over-emphasize version numbers.
While there are no version numbers, the Utopia frontend (starting after Utopia v1!) keeps track of the state of the involved repositories at the time of a simulation run, see here. This assists in reconstructing the state of a project at the time a model was run.
v1 refers to the state of Utopia prior to the outsourcing of the utopya frontend package into its own repository.
To use Utopia
v1, make sure to locally check out the release branch of the same name and stay on that branch.
While we aim to cherry-pick important bug fixes into the branch, future development of Utopia will occur on the main branch, so it’s worth considering to upgrade to the latest version of Utopia.
To upgrade Utopia to its latest version, simply pull the latest changes:
# Pull the latest changes cd utopia git pull # Re-configure cd build cmake ..
In case configuration fails, delete and re-create the
build directory and have a look at the troubleshooting section of the README.
That’s all you need to do to upgrade the Utopia framework.
If you are using a separate project for model implementations, a few changes are necessary to make your project work with the latest version of Utopia again:
First, upgrade the Utopia framework as described above.
Then, in your models repository, run
cmake .., which should give you an error message coming from the
register_models_with_frontendfunction. That message contains instructions about upgrading your project, in brief:
Rename the failing CMake function call to
Create the project info file
.utopya-project.ymlin the root directory of your project and add the following content, adjusting the marked entries:
project_name: YourProjectName # TODO Set to your project's name framework_name: Utopia # Information about your project's directory structure paths: models_dir: rel/path/to/models/src/dir # TODO Set rel. path to your models py_tests_dir: python/model_tests # if they exist py_plots_dir: python/model_plots # if they exist # Metadata about your project (aggregated in utopya models registry) metadata: # TODO Adjust to your needs authors: - your name - another author's name # Other fields: description, long_name, long_description, license, language, website
metadatanode, you can put in some descriptive info about your models, e.g. a list of authors or a short description. Hint: You can also have a look at Utopia’s
.utopya-project.ymlfile to see more possible entries.
build/CMakeCache.txtfile in your models repository to avoid carrying over outdated variables. If you get an error in the next step, try deleting the whole
builddirectory and creating it anew.
Furthermore, you may need to update
importstatements in your Python model tests or model plots because the utopya and dantro package structures changed. To find out the new import locations, refer to the API references in the utopya documentation and dantro documentation.
If you encounter difficulties in upgrading, we are happy to help; please open an issue in our GitLab project.
After upgrading, most things should remain the same compared to
However, there are some differences in the CLI, most notably:
--no-plotoptions has been renamed to
--singleflags have been replaced by the
--plot-onlyoption now only takes a single argument but can be given multiple times, e.g.
--po some_plot --po some_other_plot.
For details on the new CLI, have a look at the corresponding
--help in case you encounter errors.