Command line tools

muscle_manager

Run the MUSCLE3 Manager.

This is a thin wrapper so that we can call the implementation directly for testing purposes. The decorators above change the signature so that this function can’t be called from Python anymore.

Usage

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. This is useful when –start-all is not specified, or when –start-all is used together with manually started instances. 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 (or if there are manual components) 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).

-m, --model <model>: Start the specified model, which must be present in the ymmsl files

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.

Usage

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.

Usage

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

Usage

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.

Usage

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)