User Guide
Once you have installed MUSE2, you should be able to run it via the muse2 command-line program.
For details of the command-line interface, see here or run muse2 help.
Example models
MUSE2 comes with a number of example models, partly to demonstrate the various program features as well as to be used as templates for new models. To see the list of available examples, you can run:
muse2 example list
It should print something like the following:
missing_commodity
muse1_default
simple
two_outputs
two_regions
To view information about a particular example, you can run, e.g.:
muse2 example info simple
You can run examples like so:
muse2 example run simple
Building and running your own model
🚧 Note that this section is under construction! 🚧
In the longer term, we plan to have a tutorial describing how to build a model in more detail.
Models in MUSE2 are defined with one TOML file (model.toml) and many CSV files. For a
description of each of the files and the different fields, see the documentation for input files.
Creating a new model from an example
We recommend you use one of the examples as starting point for your own model, as there are many required files.
To create a new model based on the simple example, run:
muse2 example extract simple new_model
This will create a new subdirectory called new_model in the current folder.
Running this model
First, let's run this model so you can see the output for a working model. You can do this by running:
muse2 run new_model
If everything works as expected, you should see output on your terminal indicating the progress of the simulation (which should finish very quickly).
The first few lines should look something like:
[12:24:20 INFO muse2::cli] Starting MUSE2 v2.0.0
[12:24:20 INFO muse2::cli] Loaded model from new_model/
[12:24:20 INFO muse2::cli] Output folder: muse2_results/new_model
...
You should see that a new muse2_results folder has been created. This folder will contain the
output for your model in a subfolder called new_model. For information about how to interpret
these files, see the documentation for output files. We also have some example Jupyter
notebooks.
Next steps
You will now want to configure the model for your own use case. You should start by looking at the documentation for input files for details of the different data types and parameters for MUSE2.
Unfortunately, this may not be easy, especially if you are not already familiar with MUSE1. In the longer term, we will have tutorials, so watch this space! In the meantime, if you have a question, feel free to open an issue.
Visualising commodity graphs
To visualise the structure of your model, you can use the the muse2 save-graphs command to
create graphs of commodity/process relationships.
This command will output a graph for each region/year in the simulation, where nodes are commodities
and edges are processes.
Graphs will be saved in DOT format, which can be visualised locally with Graphviz, or online
with Graphviz online.
Dashed lines are used to indicate flows for non-primary outputs of a process (as defined in the
processes.csv input file).
Modifying the program settings
You can configure the behaviour of MUSE2 with a settings.toml file. To edit this file, run:
muse2 settings edit
There are also some more commands for working with the settings file; for details, run: muse2 settings help.
For information about the available settings, see the documentation for the settings.toml
file.
Setting the log level
MUSE uses the fern crate for logging. The default log level is info, though this can be
configured either via the log_level option in settings.toml or by setting the
MUSE2_LOG_LEVEL environment variable. (If both are used, the environment variable takes
precedence.)
The possible options are:
errorwarninfodebugtraceoff
By default, MUSE will colourise the log output if this is available (i.e. it is outputting to a terminal rather than a file).
For more information, please consult the fern documentation.