MUSCLE configuration file

The MUSCLE configuration file, or historically, the  Complex Automata (CxA) file specifies what code will be used in a simulation, and how its coupled together. It is actually a Ruby file, so any Ruby syntax will work inside it.

To use it, make a file add kernels to it by giving a name and a Java class that has the submodel implementation

w = Instance.new('w', 'examples.simplejava.Sender')
r = Instance.new('r', 'examples.simplejava.ConsoleWriter')

When using a C++ kernel without a Java interface, use the muscle.core.standalone.NativeKernel package. For an MPI executable, on a machine where mpiexec/mpirun can be called directly, use muscle.core.standalone.MPIKernel.

To add properties, add them to the global $env hash or to the instances directly:

$env['max_timesteps'] = 4
w['dt'] = 1
w['someDoubleProperty'] = 6.1
w['someOtherProperty'] = "this is w text"
r['someOtherProperty'] = "this is r text"

Properties that are only meant for a single submodel are prepended with the name and a colon (e.g., "submodelName:propertyName"). Other properties are global and will be used by all submodels.

The scale of the submodels can also be specified in the CxA file. For the timestep of a submodel, use "dt", for the total time it will run, "T". For the first 3 spatial dimensions, use dx, dy, dz as step size, and X, Y, Z as total size. In Java, the scale can be accessed with the getScale() method of a submodel.

In the example, submodel w is attached to submodel r by tying the conduit entrance dataOut of w to the conduit exit dataIn of r. It also ties conduit entrance otherOut of w to other of r.

w.couple(r, {'dataOut' => 'dataIn', 'otherOut' => 'other'})

If the conduit entrance and exit have the same name, the second argument of tie is optional.

Native code

For native executables that uses the MUSCLE API, the following parameters may be set: "submodelName:command" to set the path to the executable; and "submodelName:args" to give additional command-line parameters to the executable. Suppose my executable is somewhere in my home bin directory, this could be

subA["command"] = ENV['HOME'] + "/bin/subA"
subA["args"] = "paramA paramB"

For MPI code, two additional parameters should be set: "mpiexec_command" with the name or the path the the mpiexec/mpirun executable; and "mpiexec_args" which are the arguments, like "-np 2", etc.

Filters

If a conduit filter should be applied to a conduit, these can be added as a list as the last argument of tie():

w.couple(r, {'dataOut' => 'dataIn'}, ['muscle.core.conduit.filter.MultiplyDoubleFilter_0.5'])

In the example, the MUSCLE filter MultiplyDoubleFilter is applied, which multiplies each double with a value, in this case 0.5. For user defined filters, one double argument may be given, separated from the class name by an underscore. MUSCLE supplies some filters in package muscle.core.conduit.filter:

Filter Class Arguments Message datatype Behavior
null NullFilter none any Removes all incoming messages
pipe PipeFilter none any Forwards all incoming messages unchanged
console ConsoleWriterFilter none any Prints all messages to console and forwards them
thread ThreadedFilter none any Runs a thread, so the following filter will run in a separate thread
serialize SerializeFilter none any to byte[] Serializes any serializable Java object to a byte array
deserialize DeserializeFilter none byte[] to object Deserializes a serialized byte array to a Java object
compress CompressFilter none byte[] Compresses byte arrays using the Deflate algorithm
decompress DecompressFilter none byte[] Decompresses compressed byte arrays
chunk ChunkFilter int chunks byte[] Splits up a byte array into chunks smaller byte arrays for separate processing.
dechunk DechunkFilter int chunks byte[] Combines a byte array that was split up by the chunk filter.
linearinterpolation LinearInterpolationFilterDouble none double[] Creates a double[] of length-1 of the original, and linearly interpolates between the original values: k'_i <- (k_i+k_{i+1})/2
lineartimeinterpolationLinearTimeInterpolationFilterDoubleint stepdouble[] For step==2, forwards the first message and then sends two messages for every message received, interpolating between one message and the next.
multiply MultiplyFilterDouble double factor double[] Multiplies each value of the incoming message by factor
drop DropFilter int step any Drops messages that are not a multiple of step
timeoffset TimeOffsetFilter double time any Adds an offset time to the timestamps of messages
timefactor TimeFactorFilter double factor any Multiplies the sent timestamp of messages
blockafter BlockAfterTimeFilter double time any Drops messages with a timestamp greater than time

For convenience, the MUSCLE filters may be referred to by their name instead of their class:

w.couple(r, {'dataOut' => 'dataIn'}, ['multiply_0.5','console'])

By default, the conduit filters get applied at the receiving submodel. If a filter should be applied at the sending submodel or if filters should be applied at both locations, the couple function takes an additional argument, so that the first list of filters is applied at the sending side and the second list of filters is applied at the receiving side. The following fragment multiplies the data with a constant on the sending side, and prints it on the receiving side:

w.couple(r, {'dataOut' => 'dataIn'}, ['multiply_0.5'], ['console'])

And the following fragment compresses data on the sending side and uncompresses it on the receiving side:

w.couple(r, {'dataOut' => 'dataIn'}, ['serialize','compress'], ['decompress','deserialize'])

For large data sets it may increase performance to split the data into multiple chunks before compressing. In the following configuration, it gets sent in separate chunks and compressing is done in a separate thread from sending:

w.couple(r, {'dataOut' => 'dataIn'}, ['serialize','chunk_16','compress','thread'], ['decompress','dechunk_16','deserialize'])

Terminals

It may be convenient to couple a submodel to dummy terminals, to evaluate its individual behavior, or to read a message from file instead of receiving it from another submodel. A terminal is initialized by calling

readA = Terminal.new('readA', 'muscle.core.conduit.terminal.DoubleFileSource')
readA['filename'] = "/path/to/some.file"
readA['suffix'] = 'dat'
readA['relative'] = false
readA['delimiter'] = ','

readA.couple(r, 'dataIn')

Here, we're reading the file /path/to/some.file.dat, and the path is not relative to the runtime path of MUSCLE. The doubles in that file are delimited by commas. Finally, a terminal port takes any name of the receiving or sending end, so only one value is given to tie. For the moment, it is not possible to apply filters to terminals.

Back to new configuration syntax