Overview

Execution Parameters control how BRAHMS operates, above and beyond what it is asked to do at any individual invocation. They affect execution procedurally; that is, they control aspects of the mechanistic procedure of reaching the outcome, but do not have an effect on the outcome (other than whether it is reached).

Layers

The parameters are defined in five layers: installation-level, machine-level, user-level, execution-level and invocation-level. Definitions at each layer override earlier layers, unless a parameter has been marked as immutable, in which case definitions at deeper layers generate a warning and do not change the value. You should modify parameters using the BRAHMS Manager, and the great majority of the time you should set them at user-level.

The first three layers are files: these should not be edited directly - rather, you should use the BRAHMS Manager to set parameters. The only exception to this is if you intend to change install-level parameters, which the BRAHMS Manager cannot modify, but this should only be appropriate for administrators of multi-user systems. For this reason, the file format for brahms.xml is not documented (but the locations of the files are specified at the bottom of this page). The final two layers are defined in the Execution File and on the Command Line, respectively (the linked pages describe how to set parameters at these levels).

To confirm which files are found and read and what the final parameters are in your environment, execute brahms --show-pars at the Matlab or Shell prompt (this will not report execution-level or invocation-level parameters, because there aren't any unless you are running an execution). Alternatively, you can use brahms_utils to view the current Execution Parameters from Matlab.

Notes
  • immutable is not yet implemented.

Access

Components can access the value of Execution Parameters through ENGINE_EVENT_GET_PARAMETER_STRING. A contract wrapper for this event, getParameterString(), is provided in C++ bindings.

Execution Parameters

Global

These parameters are used by the BRAHMS executable at run-time, should also be read by Components (where appropriate), and may also be used by Invocation Bindings.

BufferingPolicy
One of "OnlyDisk", "FavourDisk", "Balanced", "FavourMemory" or "OnlyMemory". Components should respect a policy, if specified, when buffering data for any purpose. "OnlyDisk" indicates that buffering should be exclusively to disk, minimising memory footprint. "FavourDisk" indicates the same, except where this would seriously impact performance, in which case memory may be used. "OnlyMemory" indicates that buffering should be exclusively to memory, minimising run-time interruptions (on out-of-memory, an error should be raised). "FavourMemory" indicates that buffering should be to memory whilst memory is available (on out-of-memory, disk may be substituted). "Balanced" indicates that a normal balance should be struck between performance and memory use.
SupplementaryFilePath
NOTE that this parameter is derived at run-time by the framework - you cannot specify it. This parameter is set during EVENT_STATE_GET, EVENT_STATE_SET and EVENT_LOG_TERM to the path where supplementary files should be read or written. You should not generally need to use this, but if you must read or write supplementary files yourself to get information into or out of your process, you should expect to find them, or write them, on the specified path. Note that if you are authoring a data object, you should use the filename provided by the framework in EVENT_LOG_INIT rather than using this parameter to generate your own filename. For information, this parameter is currently set to the path to the folder in which the System In File (EVENT_STATE_SET), System Out File (EVENT_STATE_GET) or Report File (EVENT_LOG_TERM) is stored.
WorkingDirectory
If a directory is not otherwise specified, this directory is used to store files when the Invocation Bindings are preparing an execution for sending to BRAHMS. If this parameter is empty, the bindings will raise an error. You can also use this path to store temporary files created by your process that are not associated with the input and output files. See also SupplementaryFilePath.
VoiceID
This identifier is guaranteed to be unique for this execution on this machine. Concatenate with the name of your process to give a string that is unique to your process and this execution. This may be useful for generating a temporary filename, for instance.

Executable

These parameters are used by the BRAHMS executable at run-time, and may also be used by Invocation Bindings.

GUIUpdateInterval
The framework will update the GUI (if enabled) on some interval. Fast polling will slow down execution; slow polling will result in poor user feedback. Therefore, this interval is calculated on-the-fly as the wallclock time since run-phase started divided by some factor, within upper and lower bounds. The default value is "100,1,250" (factor 100, between 1 and 250mS). These values give a good balance between performance and appearance on my development hardware.
IntervoiceCompression
An integer from 0 to 9, corresponding to gzip (zlib) compression levels -0 to -9. Default is 0, which disables inter-voice compression. If trying to improve performance of a parallel execution, set this first to 1 - if this doesn't give you a speed-up, nothing will. If 1 speeds you up, try 2, and so on.
MinUniqueSeedsPerProcess
At least this many seeds can be requested by any individual Process without two Processes getting identical seeds. This only applies to framework-supplied seeds: if you specify the seed for a Process explicitly, non-unique seeds can be achieved much more easily. Generally, leave this value be.
MaxThreadCount
The maximum number of threads that each Voice may use. The default value (empty) indicates "no limit" ("0" indicates the same thing). A single integer is an explicit limit. A string of the form "xN" (the letter "x" followed by an integer) indicates no more than N threads per identified processor or core (if the framework cannot identify the number of processors, it will assume a single processor). The Command Line shortcut --nothreads sets this parameter to 1 for that execution only, disabling multi-threading.
NamespaceRoots
By default, this parameter is empty, and BRAHMS searches only SYSTEMML_INSTALL_PATH/Namespace for components. When you start adding your own components (or those of other developers) you will need to add a User Namespace, by setting this parameter. You can add as many User Namespaces as you want here, separated by your platforms path separator (semicolon on Windows, colon on Linux and OSX). Each one will be searched by BRAHMS when it is looking for components. Typically, you will add one root, somewhere in your "My Documents" or "home" folder (somewhere that is backed up - this will contain data).
Priority
One of "Low", "Normal", "High" or "Realtime", indicating the priority at which BRAHMS should run. These values will cause BRAHMS to run, respectively, as "background processing", in fair competition with other processes on the machine, ahead of most other processes, or at a real-time priority level. Usually, only the values "Low" and "High" will be needed (the default is "Low"), so that BRAHMS either runs "whenever a processor is free" or "as fast as possible", respectively. The value of "Normal" is unlikely to be useful. The value of "Realtime" should be used only with great care for real-time systems (i.e. systems that interact with hardware clocks); if "Realtime" is used on a pure software system, the machine will become unusable until the execution completes and may crash as a result. See Priority Management for details.
PushDataMaxBytes
The maximum number of bytes allowed to accumulate in the receive buffer of each inter-voice Link before the sending Voice will start expressing PushDataWaitStep millisecond sleeps, holding up its own execution.
PushDataMaxItems
The maximum number of items (PUSHDATA messages) allowed to accumulate in the receive buffer of each inter-voice Link before the sending Voice will start expressing PushDataWaitStep millisecond sleeps, holding up its own execution.
PushDataWaitStep
The number of milliseconds a worker thread will sleep for each time the communications layer indicates that the remote receive buffer for one of the Links it sends out is backed up.
ShowGUI
If true, show and update the GUI. You should not normally need to disable this since the processing load is negligible. You may disable it in a non-GUI environment to prevent errors, though I haven't tried if this works in any practical situation. You may also want to disable it when running batch jobs on a machine you are interacting with, since otherwise the GUI will be constantly popping up in front of you.
SocketsBasePort
The first port that the sockets layer will use, if in use. Default value is 57344 (0x0E00). Change this if this conflicts with other usage on your system.
SocketsTimeout
The sockets layer will wait this long for inter-voice communications to complete, and no longer (milliseconds). Generally set at installation level and forget, but may need to be increased for systems that include processes with long single service times.
SocketsUseNagle
If true, the Nagle algorithm is used in the TCP/IP layer of concerto. If false (the default), you may get a lot of speed-up of sockets layer comms, depending on the nature of your System. Generally, there is no compelling reason to change this parameter to true, since the Nagle algorithm is designed to balance latency against bandwidth, and in BRAHMS we are usually only concerned with bandwidth in cases where the message size is large (in which case Nagle wins us nothing anyway).
TimeoutThreadHang
The framework will wait this long (milliseconds) for a thread to send signal C_STILL_ACTIVE or return, and then will assume the thread has hung and throw E_THREAD_HUNG.
TimeoutThreadTerm
The framework will wait this long (milliseconds) for a process to terminate, and no longer. Generally set at installation level and forget.
TimeRunPhase
If true, perform wallclock timing of run-phase. Setting this true will slow down fine-grained executions (and, thus, generate a warning). Generally should be false at installation level, but set to true for run-phase performance monitoring.
ThreadPollInterval
The framework will poll threads for state changes (active, timeout, hang) on some interval. Fast polling will slow down execution; slow polling will cause poor responsiveness to Soft Stop. Therefore, this interval is calculated on-the-fly as the wallclock time since run-phase started divided by some factor, within upper and lower bounds. The default value is "100,1,250" (factor 100, between 1 and 250mS).

Bindings

These parameters are used only by Invocation Bindings.

LaunchLineSolo, LaunchLineSockets, LaunchLineMPI
The default Launch Line to use to invoke Solo or Concerto (using Sockets or MPI comms layer). Set this parameter for your local configuration, to avoid having to set the Launch Line for each execution. This parameter is only likely to be of interest if you are using multi-processing - the default Solo Launch Line should work in all conditions.
OpenURL
The bindings will try to open URLs and local logs using this parameter. Set it to the system command that launches the browser of your choice. On Windows, try rundll32 url.dll,FileProtocolHandler "((URL))". On OSX, try open -a safari '((URL))'. On Linux, presumably something like mozilla '((URL))' will work. If the parameter is not set (it is not set when you first install BRAHMS), the bindings will prompt you to set it.

Layer Files

The default file paths for the first three parameter layers are given below (if they do not exist, the BRAHMS Manager will create them; failing that, you can copy the installation-level file to get started, or use brahms_utils to set a parameter in each file, forcing a write).

Warnings
  • It is recommended that you do not set Execution Parameters at the install level, since they will be overwritten if you upgrade your BRAHMS release. The only reason to change install-level parameters is if you are maintaining an installation for multiple users who log in from multiple machines - in this case, take a copy of your local install parameters before you upgrade your installation.

Windows

Installation Level
SYSTEMML_INSTALL_PATH/BRAHMS/brahms.xml
Machine Level
C:/Documents and Settings/All Users/Application Data/BRAHMS/brahms.xml
User Level
C:/Documents and Settings/UserName/Application Data/BRAHMS/brahms.xml

Linux and OSX

Installation Level
SYSTEMML_INSTALL_PATH/BRAHMS/brahms.xml
Machine Level
/etc/BRAHMS/brahms.xml (you will probably need root privileges to create or modify this file - this means running the BRAHMS Manager as root, as well)
User Level
~/.BRAHMS/brahms.xml