coralmaster

Execution master (Coral 0.9.0)

This program will connect to the network and obtain information about
available slave types, and can be used to run simple simulations.

Usage:
  coralmaster <command> [command-specific args]

Commands:
  info     Shows detailed information about one slave type.
  list     Lists available slave types.
  ls-vars  Lists information about a slave type's variables.
  run      Runs a simulation.

Run "coralmaster <command> --help" for command-specific information.

Shows detailed information about a slave type.

Usage:
  coralmaster info <slave-type> [options...]

Arguments:
  slave-type          A slave type name.

Options:
  --interface arg (=127.0.0.1) The IP address or (OS-specific) name of the
                               network interface to use for network
                               communications, or "*" for all/any.
  --port arg (=10272)          The UDP port used to listen for slave providers.
  --help                       Display a help message and exit.

Lists the slave types that are available on the network.

Usage:
  coralmaster list [options...]

Options:
  --interface arg (=127.0.0.1) The IP address or (OS-specific) name of the
                               network interface to use for network
                               communications, or "*" for all/any.
  --port arg (=10272)          The UDP port used to listen for slave providers.
  --help                       Display a help message and exit.

Prints a list of variables for one slave type.

Usage:
  coralmaster ls-vars <slave-type> [options...]

Arguments:
  slave-type          The name of the slave type whose variables are to be
                      listed.

Options:
  -c [ --causality ] arg (=cilop)   The causalities to include.  May contain
                                    one or more of the following characters:
                                    c=calculated parameter, i=input, l=local,
                                    o=output, p=parameter.
  --interface arg (=127.0.0.1)      The IP address or (OS-specific) name of the
                                    network interface to use for network
                                    communications, or "*" for all/any.
  -l [ --long ]                     "Long" format.  Shows type, causality and
                                    variability as a 3-character string after
                                    the variable name.
  --port arg (=10272)               The UDP port used to listen for slave
                                    providers.
  -t [ --type ] arg (=birs)         The data type(s) to include.  May contain
                                    one or more of the following characters:
                                    b=boolean, i=integer, r=real, s=string.
  -v [ --variability ] arg (=cdftu) The variabilities to include.  May contain
                                    one or more of the following characters:
                                    c=constant, d=discrete, f=fixed, t=tunable,
                                    u=continuous.
  --help                            Display a help message and exit.

Runs a simulation.

Usage:
  coralmaster run <exec-config> <sys-config> [options...]

Arguments:
  exec-config         Configuration file which describes the execution
                      settings (start time, step size, etc.).
  sys-config          Configuration file which describes the system to
                      simulate (slaves, connections, etc.).


Options:
  --debug-pause                Wait for a user keypress after slaves have been
                               spawned, to allow time to attach a debugger.
  --interface arg (=127.0.0.1) The IP address or (OS-specific) name of the
                               network interface to use for network
                               communications, or "*" for all/any.
  -n [ --name ] arg            The execution name.  If left unspecified, a name
                               will be created based on the current date and
                               time.
  --port arg (=10272)          The UDP port used to listen for slave providers.
  -r [ --realtime ] arg (=0)   Real-time multiplier, i.e., how fast the
                               simulation should go compared to wall clock
                               time.  A value of 1 means that the simulation
                               should run in real time, while e.g. 2 means
                               twice as fast.  The default is 0, which is a
                               special value that means "as fast as possible".
  -w [ --warnings ]            Enable warnings while parsing configuration
                               files.
  --help-exec-config           Display a help message about the format of
                               execution configuration files and exit.
  --help-sys-config            Display a help message about the format of
                               system configuration files and exit.
  --help                       Display a help message and exit.

One of the inputs to coralmaster run is the execution configuration file, which describes how the simulation should be executed. (The system configuration file, on the other hand, describes the system that will be simulated.)

The execution configuration file is a simple text file consisting of keys and values, where each key is separated from its value by whitespace. (Specifically, it must be in the Boost INFO format.) The following example file contains all the settings currently available:

; Time step size (mandatory)
step_size 0.2

; Simulation start time (optional, defaults to 0)
start 0.0

; Simulation end time (optional, defaults to "indefinitely")
stop 100.0

; General command/communications timeout, in milliseconds (optional,
; defaults to 1000 ms)
;
; This is how long the master will wait for replies to commands sent
; to a slave before it considers the connection to be broken.  It should
; generally be a short duration, as it is used for "cheap" operations
; (i.e., everything besides the "perform time step" command).
comm_timeout_ms 5000

; Time step timeout multiplier (optional, defaults to 100)
;
; This controls the amount of time the slaves get to carry out a time
; step.  The timeout is set equal to step_timeout_multiplier` times the
; step size, where the step size is assumed to be in seconds.
step_timeout_multiplier 10

; Slave instantiation timeout, in milliseconds (optional, defaults
; to 30,000 ms = 30 s)
;
; This is the maximum amount of time that may pass from the moment the
; instantiation command is issued to when the slave is ready for
; simulation.  Some slaves may take a long time to instantiate, either
; because the FMU is very large and thus takes a long time to unpack
; or because its instantiation routine is very demanding.  -1 is a
; special value which means "wait indefinitely".  This is somewhat
; risky, however, because it means the entire slave provider will
; hang if a slave hangs or crashes during startup.
instantiation_timeout_ms 10000

One of the inputs to coralmaster run is the system configuration file, which describes the system to simulate. (The execution configuration file, on the other hand, describes how the simulation should be executed.)

Here is an example:

; The "slaves" section contains a list of all the subsimulators.
slaves {
    ; Each subsimulator is identified by a name, in this case "mass" and "spring".
    mass {
        type "1d_mass"        ; This is the type, i.e., the model name of an FMU
        init {
            mass     20.0     ; Here, one can set initial values for different variables.
            position  3.0
        }
    }
    spring {
        type "1d_spring"
        init {
            stiffness            10.0
            uncompressed_length  5.0
            position_a           0.0
        }
    }
}

; This section contains the variable connections, on the following form:
;     <slave A>.<input variable> <slave B>.<output variable>
; (To make the order easier to remember, mentally insert an "equals" sign
; between them.)
connections {
    mass.force        spring.force
    spring.position_b mass.position
}

; This section contains parameter changes that are to take place at a
; specific point in time. There is one subsection for each time point.
scenario {
    1.5 {                         ; At 1.5 seconds...
        spring.stiffness  5.0     ; ...the spring stiffness will be changed
        mass.mass        10.0     ; ...along with the mass.
    }
    4.3 {                         ; You can have as many events as you like.
        spring.stiffness  2.4
    }
}