Overview



The BRAHMS Manager is a Matlab GUI that helps you manage your BRAHMS configuration. To launch it, run brahms_manager in Matlab (it is currently included in the Matlab Invocation Bindings folder for convenience). The first time you launch it after installing BRAHMS, you will be instructed to set your Working Directory.

Warnings
  • There is a bug in the Linux version of Matlab R14, which will manifest in the BRAHMS Manager as the message "File does not exist" returned when trying to select directories. See the FAQ if you encounter this.
Notes
  • The BRAHMS Manager is not available to Octave users. However, everything you can do with BRAHMS Manager, you can alternatively do with brahms_utils. Try "help brahms_utils" to get started.

Functions

  • Configuring your Namespace Roots - controlling where BRAHMS searches for Components.
  • Creating new Process components (from one of the provided templates).
  • Modifying Execution Parameters (BRAHMS configuration files).
Notes
  • The BRAHMS Manager is the recommended route for creating new Processes - don't try doing this manually unless you can't do it with the Manager for some reason.
  • Same goes for parameters - only modify the configuration files manually if you can't use the Manager, or if you need to change install-level parameters, which are not accessible through the Manager.
Warnings
  • This utility is brand new in Version 0.7.1, so cross your fingers.

Left Pane (Namespace Manager)

Namespace Roots

After installing BRAHMS you should add at least one Namespace Root (over and above the default root installed with BRAHMS), which you can then populate with your own Processes. To do this, click on Add under "Configured namespace roots" and choose a directory. This directory can be anywhere in your file space, but its contents should be treated like any documents (that is, you should be backing up this directory - these are not temporary files).

You can add more Roots as you wish - one situation where you might want to do this is if your group shares a Namespace Root, on a remote fileserver, say, and all the members want to use Components from this root, whilst maintaining their own Root locally for their own Components. You can also remove Roots by clicking on Remove - this does not affect the file system, but prevents BRAHMS from searching these folders for Components in future.

Namespace

Provided you have at least one Root, then the contents (Components) of the selected Root are displayed in the listbox below. You can refresh this list by clicking Refresh, though restarting the Manager achieves the same end. If you accidentally add the wrong folder, and the search is going on and on for ever, you can click Cancel to abort the search.

With an entry (component) in the list selected, you can click on one of the four lower buttons to operate on it. The following operations are available.

New
Import a Process template from the BRAHMS install folder, and install it to the selected Namespace Root.
Open
Open the release folder of the currently selected node in a File Browser (this is where your source files, build scripts, etc., are all kept).
Build
Write a new build script into the release folder, and execute it. This build script can then be modified, if it isn't quite right for your environment. The build script is just a shell script, so, once it is written, you can run it from outside the Manager, and this may be easier once you're up and running.
Test
Run the test.m script that came with the template, to see if it can be loaded and executed in BRAHMS successfully. This will not work until you have built the node, and it may not work once you have modified the Process. It is provided only to help you find your feet.

Starting a new process

Creating the process

When you click on New, you will be asked which binding you want to develop against. See the notes at Component Bindings to help you choose, if you don't already know.

You will then be asked to choose a SystemML Class Name for your new Process. This is its unique identifier in the Namespace, and is the tag that your users will use to specify your Process. You may, in principle, use any valid SystemML Class Name (alphanumeric, underscore, and forward slashes only, see the SystemML Documentation for full details of the syntax), but there are strongly recommended forms (see Namespace). For publishing, you should use <org>/<year>/<name>. Collaborating internally to your group, you should use the local branch of the Namespace to avoid future conflicts with published Components, for example local/bob/modelx. For example, local/2004/follicle is the class name of a model published within our group in 2004.

Notes
  • Currently, the BRAHMS Manager does not enforce the Namespace rules. Please see the documentation on the Namespace for details. To summarise, if you are creating a new class, you should name it as "dev/..." (under development). Later, you may promote it to the "local" branch, or publish on the public server under your organisation's branch.

Finally, you will be asked to confirm the copy operation. When you click OK, the new Process is created, and entered into the list of nodes in the Manager left pane (and selected).

Building and testing the process

If you chose a compiled language (C or C++), you must next build the process. Click on Build to write a build script into the release folder and run it. You can view the results in the Matlab Console window. The build script written is a standard shell script, using g++ on Linux and OSX, and cl on Windows. Depending on your environment, it may not work out of the box. In this case, you should click Open to open the release folder and modify the script to suit your environment. In particular, the build script assumes that C/C++ runtime libraries are available to your compiler and linker for including and linking. You will have to make sure this is so, or add pre-amble to the build script to arrange this.

Once built, or for non-native processes (Matlab or Python), click on Test to run the new Process. You can view the results in the Matlab Console window. If the test is successful, you are done with the Manager, and you can now start modifying your new Process as desired. Click on Open to find the associated files. If the test is unsuccessful, you can start by looking up the error code E_XXX on the Errors page, but please report this, because it would be nice if this worked first time on all platforms.

Right Pane (Parameter Manager)

In this pane you can manage your configuration (Execution Parameters). Mostly, you can just leave these alone, but you can review the reference pages for each parameter type if you want to see what is available.

One parameter you should modify after installation is WorkingDirectory - If WorkingDirectory is empty, the BRAHMS bindings will raise an error when you try to send a system for execution. The WorkingDirectory is used for temporary files, so you need not back up its contents. Select WorkingDirectory in the drop-down list, and click on one of the browse buttons (which may be showing up orange). You can set this parameter at machine-level or user-level - if you are the only user of your machine, it doesn't matter which you choose.