Command line tools

muscle_manager

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...

Options

--log-level <log_level>

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

Default:: INFO

--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).

Arguments

YMMSL_FILES: Required argument(s)

muscle3

MUSCLE3 command line interface

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

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

muscle3 [OPTIONS] COMMAND [ARGS]...

profile

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.

Result:

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.

muscle3 profile [OPTIONS] PERFORMANCE_FILE

Options

-i, --instances: Show per-instance statistics

-r, --resources: Show per-resource statistics

-t, --timeline: Show a timeline of events

Arguments

PERFORMANCE_FILE: Required argument

resources

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.

Result:

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.

Examples:

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} simulation.sh

muscle3 resources [OPTIONS] YMMSL_FILES...

Options

-c, --cores-per-node <cores_per_node>: Required Set number of cores per cluster node.

-v, --verbose: Show instance allocations.

Arguments

YMMSL_FILES: Required argument(s)

snapshot

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...

Options

-d, --data: Display stored data. Note this may result in a lot of output!

-v, --verbose: Display more metadata.

Arguments

SNAPSHOT_FILES: Required argument(s)