Overview
Notes

BRAHMS implements the SystemML Namespace as a collection of one or more physical roots, called Namespace Roots. When instantiating a System, BRAHMS will search for each Component under each root specified in NamespaceRoots until it finds an implementation of that Component. It doesn't matter which root the Component is under, but you will typically maintain at least one root, or User Namespace, on top of the root that is installed with BRAHMS. You may, in addition, maintain further roots - for instance, your research group may share one, or you may have one for each of several distinct projects. The BRAHMS Manager will help you to configure your Namespaces.

  • One Namespace is installed with BRAHMS, with its root at SYSTEMML_INSTALL_PATH/Namespace. This holds the Components installed with BRAHMS (the Standard Library and some client-specific Components for testing and examples).
  • You can create your own User Namespace using the BRAHMS Manager. A User Namespace is just another root in which you can develop your own Components.

Namespace Roots

Each Namespace root is treated as representing the root of the SystemML Namespace. You may maintain many physical roots (above), but their contents are overlaid on each other. For instance, the root installed with BRAHMS has a branch at std/2009, where the current release of the Standard Library is implemented. Your User Namespace may have a branch at dev/bob; these exist in the same Namespace, even if they are not in the same folder.

Namespace Rules

See SystemML Namespace.

Namespace Nodes

Each folder under the root is a Namespace node, which can either be a Component node or a Container node. This mirrors the filing system on your computer, which is no accident, with Components as files and Containers as folders. That is, Container nodes can contain further nodes of either type, whereas Component nodes are terminators - they represent a SystemML Component, which BRAHMS can interact with (load and execute, amongst other things). One difference is that Component nodes are, themselves, folders, because a Component in SystemML may have many files associated with it.

Container Nodes

Container nodes are implemented simply as folders, but they are important, because they imply the SystemML Class of the Component nodes they contain. For instance, if you have a Namespace root at D:\MyNamespaceRoot, and you install a Component node at D:\MyNamespaceRoot\dev\bob, then BRAHMS will look there for a SystemML Component with Class dev/bob. Note that BRAHMS will also look at SYSTEMML_INSTALL_PATH/Namespace/dev/bob, since all roots share the same Namespace. It would be best, in general, if it only ever finds a particular SystemML Component Class under one of the roots it searches. Otherwise, behaviour is undefined.

Component Nodes

Each Component Node represents a single SystemML Component - for instance, the folder at SYSTEMML_INSTALL_PATH/BRAHMS/Namespace/std/2009/source/numeric is the Component Node for the SystemML Class std/2009/source/numeric. In that folder, one or more client folders may exist (e.g. brahms). In the client folder, one or more release folders are found (e.g. 0, for Release 0). Since every Component installed with BRAHMS is on Release 0, they are all found in a sub-path under their Component node called brahms/0. Your Components should begin their lives in a corresponding folder under their Component node.

Each Component node should have a node file in it, called node.xml. These may also exist in Container nodes, but are not currently used. The node.xml file is included with each Component template - you can copy it into its rightful place if you don't create your Component through brahms_manager. It should read as follows.

XML File or Snippet
<?xml version="1.0" encoding="UTF-8"?> <Node> <Type>X</Type> </Node>

where "X" can be "Process", "Data" or "Utility".

Release Folder

A release folder contains the implementation of a Component (it may include other items, such as the source code, documentation, or developer notes). It must contain at least two files for all Components. The first is the release file, release.xml, which should read as follows.

XML File or Snippet
<?xml version="1.0" encoding="UTF-8"?> <Release> <Language>X</Language> </Release>

where "X" can be "1199", "1258", "1262" or "1266". The second is the module file (the actual implementation of the Component). The name of this file by default should be "component", with an extension dependent on the language, as follows.

1199
Platform-specific library extension ("dll" on Windows, "so" on Linux, "dylib" on OSX).
1258
"m", for m-script.
1262
"py", for Python-script.
1266
Platform-specific library extension.

A third file, the header file, should be provided for Data and Utility objects, which specifies the interface that the Component offers to other Components. This file must be called data.h or utility.h, as appropriate.

Changing the file name

You may want to call your implementation file something different, for instance if you are fed up with all the files open in your source code editor being called the same thing, "component". Make an entry in release.xml for <Filename> to specify the base name of your implementation file. For example, the release file below will cause the implementation file to be sought at "basal_ganglia.py".

XML File or Snippet
<?xml version="1.0" encoding="UTF-8"?> <Release> <Language>1262</Language> <Filename>basal_ganglia</Filename> </Release>

Summary of Namespace Layout

A BRAHMS-implemented Namespace has the following rules governing its layout. Explore the installed root to see these rules in action.

  • The Namespace root is a Container node.
  • Each Container node contains Container and/or Component nodes.
  • Each Component node corresponds to a SystemML Class, which is exactly equal to the relative path to the node from the root.
  • Component nodes contain a client folder named brahms, and the node file node.xml.
  • The client folder contains one or more release folders named for the integer Component release number.
  • A release folder contain an actual implementation of the Component, and the release file release.xml.
    • For Data or Utility modules, the release folder also contains the Component's SDK (usually a header file, data.h or utility.h).