Overview

The only required argument at the command line is the path to the Execution File, which is written in BRAHMS ExecutionML. This gives BRAHMS all the information it needs to run. In particular, it points to a System in a System File, advises where outputs should be put, and specifies the parameters of the Execution.

For how to interact with an Execution File from Matlab, see brahms_execution.

Format (with example values)

XML File or Snippet
<Execution Version="1.0" AuthTool="BRAHMS Matlab Bindings" AuthToolVersion="0.7.0.1546"> <Title>My System's Title</Title> <SystemFileIn>name-sys.xml</SystemFileIn> <SystemFileOut>name-sys-out.xml</SystemFileOut> <ReportFile>name-rep-((VOICE)).xml</ReportFile> <WorkingDirectory>C:/Program Files/SystemML/BRAHMS/temp</WorkingDirectory> <ExecutionStop>1</ExecutionStop> <Seed>42</Seed> <Logs Precision="..." Window="..." Encapsulated="..." Recurse="..." All="..."> <Log Precision="..." Window="..." Encapsulated="..." Recurse="...">...</Log> ... </Logs> <Voices> <Voice> <Address protocol="...">...</Address> ... </Voice> ... </Voices> <Affinity> <Group Voice="..."> <Identifier>...</Identifier> ... </Group> ... </Affinity> <ExecutionParameters> <ShowGUI>0</ShowGUI> ... </ExecutionParameters> </Execution>

Fields

"Working Directory" (used below) is taken from the WorkingDirectory field - if that field is empty, the directory in which the Execution File is stored is assumed to be the Working Directory.

Title
A title for the execution, for information only (ignored by BRAHMS).
SystemFileIn
The absolute path to the System File that holds the initial state of the system. Alternatively, supply a relative path, and BRAHMS will load the file from the working directory.
SystemFileOut
The absolute path to the System File that will be written with the final state of the system. Alternatively, supply a relative path, and BRAHMS will load the file from the working directory.
ReportFile
The absolute path to the Report File that BRAHMS is to create to hold the results of the execution. Alternatively, supply a relative path, and BRAHMS will load the file from the working directory. The token ((VOICE)) will be replaced by the index of the Voice that generates the Report File.
WorkingDirectory
A temporary directory which BRAHMS can use to store, for example, unencapsulated output binary files, and which is used as the base for files specified with relative paths. If empty, the directory in which the Execution File is found is used.
ExecutionStop
The time to stop executing the system. See Timing.
Seed
The execution-level random Seed (see Seeding).
Logs
This field is detailed below.
Voices
This field is detailed below.
Affinity
This field is detailed below.
ExecutionParameters
This field may contain one or more Execution Parameters, in the form shown. These are the "execution-level" Execution Parameters.

Field Details

Logs

Governs which Components in the System are to be logged, and how. Any number of Components can be explicitly specified by a Log Tag within the Logs Tag, causing them to be logged. Behaviour for Components that are not explicitly specified is governed by the attributes of the Logs Tag.

Logs Tag Attributes

Precision
Logging precision for all Components that do not override this setting (0 or a small positive integer). Absent means "not set", which will be understood by Components to mean "maximal", or "hide nothing". Other values will be interpreted by the particular Component: for numeric data, this value is interpreted as "significant figures".
Window
Logging window(s) for all Components that do not override this setting. Absent means "always log", i.e. a window that runs from the start of the execution to its expected stop.
Encapsulated
Encapsulation for all Components that do not override this setting (0 or 1). Absent means "unencapsulated".
Recurse
Settings applied in Log tags apply to the specified Component and all of its descendants (0 or 1). Absent means "recurse".
All
If true ("1"), all Components not explicitly specified as children of the <Logs> tag will be logged with the default settings given above. If false, all Components not explicitly specified will not be logged.

Log Tag Attributes

The Log tag has the following attributes.

Precision
Override logging precision just for this output.
Window
Override logging window(s) just for this output.
Encapsulated
Override encapsulation just for this output.
Recurse
Override recursion just for this output.

Log Tag Content

The text content of the tag may be any of the following:

If "Recurse" is true, all descendants of the object specified in the text content of the Log tag have the same settings applied to them. For an output Port, there are no descendants. For a Process, its output Ports are its descendants. For a Subsystem, any Subsystems and/or Processes within it are its descendants (and, naturally, any output Ports of such Processes).

Example

This example specifies that four outputs of the Process "mech" should be logged, only. None of the outputs specifies logging parameters, so the logging parameters set in the Logs Tag will be used (precision 6, not encapsulated)

XML File or Snippet
<Logs Precision="6" Encapsulated="0" All="0"> <Log>mech>>>strain</Log> <Log>mech>>>SA</Log> <Log>mech>>>RA</Log> <Log>mech>>>dump</Log> </Logs>

Affinity

Affinity governs how processes in the system are deployed across multiple Voices (it is not currently possible to group processes by thread within a Voice). This is achieved by grouping Processes together; all member Processes of a Group will be computed on the same Voice. The framework will decide where these groups should be computed if the user does not specify this explicitly.

Any Processes that are not members of an affinity group will be mopped up by the framework scheduler. Currently, scheduling policy is to assign each process in turn to the voice with the least number of assigned processes, or the first of those if there are more than one (i.e. round-robin).

Affinity Tag

The Affinity tag should contain zero or more Group tags, each of which specifies a group of SystemML computables that should be computed together.

Group Tag

The Group tag should contain one or more Identifier tags, each of which specifies a SystemML computable. It may also have an attribute "Voice", in which case the group will be scheduled on the specified Voice (this is useful if your hardware is not symmetric).

Identifier Tag

The Identifier tag has no attributes, and contains only a SystemML Absolute Identifier. The SystemML computable (Process, Subsystem) which has this identifier will be matched and added to the Group.

Example

This set of tags will schedule anything in a Subsystem "sub" or any process called "sub" on Voice 1. The other group will be scheduled on Voice 2 (if present) or also on Voice 1 (if not). Any processes in the system that are not specified below will be scheduled by round-robin.

XML File or Snippet
<Affinity> <Group Voice="1"> <Identifier>sub</Identifier> </Group> <Group> <Identifier>eproduct</Identifier> <Identifier>esum</Identifier> </Group> </Affinity>

Voices

Voices Tag

The Voices tag should include one or more Voice tags - the number of these indicates how many Voices are involved in executing the System.

Voice Tag

The Voice tag lists the addresses on which each Voice can be reached by the other Voices. Multiple addresses may be listed for any of the Voices. Each Voice will choose the best address on which to communicate with each other Voice. For instance, if some Voices form part of an MPI communications group, they will use MPI to exchange data; if some other Voices do not form part of that MPI group, but do offer an IP address, voices in the MPI group will communicate with voices outside it using Sockets.

Address Tag

The Address tag should have an attribute "protocol" which can be "sockets" or "mpi". The tag contains the address information, which should be an IP address or an MPI rank (zero-based index into MPI communications group).

Example

This example specifies four Voices, each accessible on only one address, over the Sockets layer on IP address 127.0.0.1. That is, it specifies a four-voice Babble.

XML File or Snippet
<Voices> <Voice> <Address protocol="sockets">127.0.0.1</Address> </Voice> <Voice> <Address protocol="sockets">127.0.0.1</Address> </Voice> <Voice> <Address protocol="sockets">127.0.0.1</Address> </Voice> <Voice> <Address protocol="sockets">127.0.0.1</Address> </Voice> </Voices>