Command line tools


Run the MUSCLE3 Manager.

The MUSCLE manager manages a coupled simulation. It can start the various submodels, and it helps them to find and connect to each other to exchange messages. The manager also distributes settings from the configuration file(s) to the submodel instances.

The muscle_manager command takes a list of configuration files in yMMSL format (see the online documentation). The files are combined in the order given, so if for example a setting is given multiple times, then the value in the last file in the list to mention it is used.

muscle_manager [OPTIONS] YMMSL_FILES...


--log-level <log_level>

Set the local log level. Try DEBUG for (much) more output.



--run-dir <run_dir>

Directory to write logs, run metadata and output to. By default, a directory with the name run_<model>_<date>-<time> will be created.

--location-file <location_file>

File to write the network location of the manager to if –start-all is not specified. If a relative path is given, then it will be resolved relative to the directory in which the manager was started.

The manager will write to this file a single line of text, which should be passed to the instances via the MUSCLE_MANAGER environment variable or on their command line using the –muscle-manager=<contents> option.

If –start-all is not specified and –location-file is also not given, then the location will be printed on standard output.

--start-all, --no-start-all

Start all submodel instances listed in the configuration file(s).



Required argument(s)


MUSCLE3 command line interface

This command provides various functions for running coupled simulations using MUSCLE3.

Use muscle3 <command> –help for help with individual commands.



Visualise profiling information.

Takes data from a performance.sqlite file written by the manager, and produces one or more plots on the screen.

Profiling functionality is still somewhat experimental, so this command may be changed and extended in the coming releases. Please let us know if there are any changes or additional features you would like to have by making an issue on GitHub, or through your usual support channel.


With -i, shows a chart depicting for each instance how much time it spend running, waiting and communicating.

With -r, shows a chart depicting for each resource (CPU core) which instances ran on it for how long.

With -t, shows a timeline of the different instances, depicting when they were sending, waiting, receiving and running.



-i, --instances

Show per-instance statistics

-r, --resources

Show per-resource statistics

-t, --timeline

Show a timeline of events



Required argument


Calculate the number of nodes needed to run the simulation.

In order to run a MUSCLE3 simulation on a cluster, a batch job has to be submitted specifying the resources needed. This command calculates the number of nodes needed to run a given simulation without oversubscribing, given the number of cores available in each node.

If multiple yMMSL files are given, then they will be combined left to right, i.e. if there are conflicting declarations, the one from the file last given is used.


With the -v option, the allocation of each instance will be printed to stdout. Without it, a single number will be printed, the number of nodes needed to run the simulation.


muscle3 resources –cores-per-node 24 simulation.ymmsl

muscle3 resources -c 16 model.ymmsl resources.ymmsl

num_nodes=$(muscle3 resources -c 16 simulation.ymmsl) sbatch -N ${num_nodes}

muscle3 resources [OPTIONS] YMMSL_FILES...


-c, --cores-per-node <cores_per_node>

Required Set number of cores per cluster node.

-v, --verbose

Show instance allocations.



Required argument(s)


Display information about stored snapshots.

Per provided snapshot, display metadata. Stored data can also be output by supplying the ‘-d’ or ‘–data’ flags. Note that this may result in a lot of data displayed.

muscle3 snapshot [OPTIONS] SNAPSHOT_FILES...


-d, --data

Display stored data. Note this may result in a lot of output!

-v, --verbose

Display more metadata.



Required argument(s)