Introduction

Brahms consists of a number of components and integrated software tools:

1. The Compiler – the compiler parses a Brahms program (also referred to as a Brahms model).
2. The Virtual Machine (VM) – the VM loads and executes a compiled model program.
3. The Composer – the Composer is a Brahms integrated development environment integrating graphical model designers, source code editors, the compiler and the virtual machine.
4. The Agent Viewer – the Agent Viewer parses a Brahms runtime history event file into a MySQL database, and allows an end-user to view an agent's activity timeline, as well as agent-to-agent communication interactions and movement.
5. The Java application interface – the JAPI is a library of Java API methods to develop a seamless integration of Brahms agents with software components written in other programming languages, such as Java.
6. The Eclipse IDE plugin – an Eclipse plugin is available for writing Brahms code, as well as compiling and testing Brahms and Java code.

Example of Brahms Agents

A Brahms agent starts executing in its individual thread when it is created, and runs until it is either deleted by another agent, or stopped or paused. Below is some Brahms source code for creating and deleting agents.

  agent JohnPersonalAgent { ... } //define agent JohnPersonalAgent
  CreateAgent(JohnPersonalAgent); //create agent JohnPersonalAgent
  delete JohnPersonalAgent; //delete agent JohnPersonalAgent

Just as in object-oriented languages, where objects are instances of a class, in Brahms agents can be members of a group. Agents inherit all elements from their group. Brahms supports multiple-inheritance, and an agent can therefore be a member of multiple groups.

  group PersonalAgent { ... }  //define group PersonalAgent
 
  //define agent JohnPersonalAgent as an instance of PersonalAgent
  agent JohnPersonalAgent memberof PersonalAgent { ... }  
 
  //and Agent2 as an instance of PersonalAgent and AnotherGroup
  agent Agent2 memberof PersonalAgent, AnotherGroup { ... }  

Brahms agents are belief-based. Unlike objects encapsulating attributes (or members) that have a value, Brahms agents have an individual belief-base that contains beliefs about the values of attributes of agents, objects and areas. Below is an example of Brahms code of artist agents that sing songs and have beliefs about the songs that they and other agents sing:

 
class Song { ... }  //definition of a Song class
 
object WhatAWonderfulWorld instanceof Song { ... } //a song object
object LaVieEnRose instanceof Song { ... } //another song object
 
group Artist {
  attributes:
    public Song performs; //definition of an attribute and type
}
 
agent LouisArmstrong memberof Artist {
  initial_beliefs: //beliefs the agent gets at initialization
    (current.performs = WhatAWonderfulWorld); //a belief
    (EdithPiaf.performs = LaVieEnRose);  //another belief
}
 
agent EdithPiaf memberof Artist {
  initial beliefs: //beliefs the agent gets at initialization
    (current.performs = LaVieEnRose);
}

The above initial belief-base of agent LouisArmstrong shows the difference between an object with attributes and a Brahms agent with beliefs. Whereas an object can only contain attributes of itself, a Brahms agent can contain beliefs about attributes of any agent, object or area, not just about attributes of itself.

Beliefs are propositional sentences, or propositions, in propositional logic. However, beliefs are more than just propositions, they are first-order logic formulas with attributes as predicates. For example, one can write the belief

(current.performs = LaVieEnRose)

as a first-order formula P(t1, t2), where Performs is a predicate denoting the sentence t1 performs t2. Thus,

Performs(current, LaVieEnRose)

is a first-order logic formula, where current is a variable that gets resolved to the agent instance EdithPiaf, and LaVieEnRose is an instance of the Song group.

Brahms agents can exhibit intelligent behavior, both proactive and reactive behavior, because every Brahms agent contains its own forward-reasoning inference engine, allowing the agent to reason and act autonomously based on its beliefs. Agents can contain rules that fire when the agent's beliefs match upon the preconditions of the rule.

A rule can create new beliefs for the agent and perform actions in its environment, by executing defined actions. An action can be a message send to another agent, or the execution of a Java activity written in the Java language, or the calling of a method on a Java object. For example, the rule SingASong (called a workframe) in the source code example below is defined in the group Artist. Every Artist agent (instance of the group Artist) inherits this rule. When the agent gets beliefs in its belief-set that match the precondition of the rule, the rule fires and the agent sings the song. After the agent has sung, it will not sing the same song again until the belief about the has_performed attribute has been deleted from its belief-set.

group Artist {
attributes:
    public Song performs;
    public Song has_performed;
  workframes:
    workframe SingASong {
      variables:
      foreach(Song) a_song;
      when ((current.performs = a_song) and
             not(current.has_performed = a_song))
    do {
        sing(a_song);
        conclude((current.has_performed = a_song));
    }
  }
}

Compiler

The Brahms Compiler is responsible for checking the syntax and semantics of Brahms models written in source code compliant with the Brahms language specification into a format understandable by the Brahms virtual machine. The format for the Brahms virtual machine is XML (Extensible Markup Language) to be compliant with the Brahms DTD (Document Type Definition).

The compiler checks the source code of the Brahms models for syntax errors and for errors in the semantics to ensure correct behavior of the models in the virtual machine. The source files must have the extension .b.

The compiler is integrated with the Brahms Composer to further ease the development process.

If you experience problems with the compiler please make sure to check out the known problems before reporting a bug. If the problem isn't listed be sure to check out the forums (opens in a new tab).

Usage

 **bc** [options] <Brahms file> <Brahms file>

The Brahms file is the .b file to be compiled. To use the compiler you need to make sure that the base library is located in your library path (by default /Brahms/AgentEnvironment). A batch file (bc.bat) is also included in which the library path for the base model and the DTD path are set to the appropriate path.

The following options can be passed to the compiler:

Virtual Machine

Brahms agents are executed in the Brahms Virtual Machine (the "bvm"). The bvm is written in the Java language, and Brahms agents are executed as Java threads running in a Java virtual machine. Therefore, the limit on the number of agents that can be created in a bvm is directly related to the number of threads that can be created, and the memory that can assigned to a thread, in a Java virtual machine. Brahms allows distributed bvm's, enabling scaling to hundreds of thousands of agents over hundreds of virtual machines and many physical CPU clusters.

The Brahms Virtual Machine is used to either simulate Brahms models or to run Brahms models using intelligent software agents. The virtual machine interprets the compiled Brahms models and runs Brahms models/agents for as long as the user desires. All simulation or run-time state information and state changes of the agents are stored in a history file, located in /Brahms/AgentEnvironment/Databases, by the virtual machine's file agent viewer service which can be easily disabled. The history file can be parsed by the Brahms Agent Viewer which stores the data in a database that can be used for later analysis using Brahms Agent Viewer or other tools that are able to access relational databases using SQL.

The virtual machine has a Java Application Programming Interface (JAPI) that allows for developers to develop their own virtual machine services, Java-based agents and Java-based agent activities that interact with the virtual machine and the agents managed by the virtual machine. The JAPI can be used to register for virtual machine events and handle those events for different purposes and can be used to interface external systems with Brahms agents.

The virtual machine has a log function that can log the virtual machine's behavior to a log file. The virtual machine also includes an event service that displays all events generated by the virtual machine in a readable format in an event information file. These files are located in /Brahms/AgentEnvironment/logs.

The virtual machine can be configured using a configuration file located in /Brahms/AgentEnvironment/config. It allows the user to register different services and configure what information is to be logged.

Usage:

**bvm** [-options] [<model>]

Note 1: The virtual machine must at minimum get a brahms compiled file as a parameter or a configuration file for the vm to register itself with a directory service for remote control by another component.

Note 2: The time as specified in the date parameter must be in 24-hour clock format, aka 'military time'. The zzzz parameter represents the time zone, which must be specified using its full name, eg America/New_York or America/Los_Angeles. For a full list see the Calendar.b file in /Brahms/AgentEnvironment/Models/brahms/base.

Composer

The Brahms Composer is the Brahms Integrated Development Environment (IDE). This Composer replaces the former Brahms Builder. The Composer allows a Brahms developer to quickly and easily develop models of work practice. The Composer integrates a selection of tools in one easy to use environment.

The Composer will grow into the main environment from which everything related to Brahms can be controlled, from design, implementation, debugging, and testing, to agent environment and agent control and monitoring, to analysis and reporting.

The Composer currently integrates the following main components:

1. Designers for the various sub models that are part of a Brahms model of work practice, designers for the agent model, object model, conceptual object model, geography model and activity model.
2. Source code editor with syntax color coding and syntax checking.
3. Package explorer to organize and manage the source code files in their respective packages
4. Document outline to visualize the model elements in the currently active source code editor.
5. Compiler, to check the syntax and semantics (such as type checking) of a model.
6. Task list displaying the syntax and semantical errors found in the model, allowing a developer to quickly find and jump to the place in source code where the error occurs.
7. The Agent Viewer to visualize and analyze the agent behaviors after a run.

The Composer organizes all of the components by means of so-called dockable windows. The designers and task list can be placed at various locations within the Composer to best suit the productivity of the developer. Dockable windows can be merged with one another into one window allowing each component to be accessed through a tab. The Composer preserves the layout between Composer sessions.

The designers give you a quick and manageable overview of your entire model, making maintenance of your model easier. The designers support creating and editing all Brahms language elements and support drag and drop capabilities to associate elements with one another. It is possible to create entire models using only the designers without manually writing any source code. The Composer will generate the source code for every edit made in the designers.

The Composer seamlessly integrates the designers with the source code editors. Changes made through the designers are reflected in the source code preserving any comments or formatting of other code you have in a file. Changes made in a source code editor are reflected in the designers.

The source code editor highlights certain words in different colors to highlight which words are reserved language keywords, what are comments and what are identifiers or other non keyword values. The source code editor supports multiple levels of undo/redo. The source code editor parses the contents of the file after saving the file and displays any syntax errors you might have in the file in the task list.

When the developer is ready he/she can build/compile the entire model to generate the code necessary to either simulate the model or to start the agent-based system using the Brahms virtual machine. The current version of the Composer allows you to start the virtual machine directly. Any errors or warnings reported by the Brahms compiler will be listed in the Composer's task list. The developer can quickly jump to the location in the source files where the errors were found by double clicking the error in the task list.

New models can be created using the IDE, but also models that were developed outside of the Brahms Composer can easily be loaded into the Composer by using the Composer's import function.

The Brahms Agent Viewer is integrated into the Composer to allow a developer to effortlessly go through the various stages of development from design to implementation to testing and analysis. The Composer User Guide is available for download as a PDF.

Agent Viewer

The Brahms Agent Viewer is an analysis tool that displays the behavior of agents and objects over time and allows for the analysis of their behavior. The agent viewer features:

• Runtime View displaying the agents and objects that were active in an agent environment.
• Graphical Timeline View with per selected agent or object the frames and activities performed by that agent with their duration.
• Communication View displaying the communication between agents and objects.
• Explanation Facility allowing for a more detailed analysis of the state and behavior of the agents and objects.

At runtime the Brahms Virtual Machine records the behavior and state changes of the agents, objects and world state in a history file located in /Brahms/AgentEnvironment/Databases. This history file is maintained by the virtual machine's file agent viewer service and is only maintained if this service is enabled which it is by default. The Agent Viewer has the ability to parse this file and store all the information in a MySQL (opens in a new tab) relational database. The Agent Viewer retrieves all the necessary information for its views from this database.

Runtime View

The user opens the database with the information that need to be displayed. When the database is loaded the runtime view is populated with all of the agents and objects that were active at any point in time in the Brahms Virtual Machine. The runtime view furthermore displays the relationships between conceptual objects, locations of agents and objects, groups that agents belong to, and classes of objects. From the Runtime View the user can select what agents and objects need to be displayed in the Timeline View.

Timeline View

Selecting or dragging an agent or object into the Timeline View displays the agent's or object's timeline. The timeline displays for each agent and object what workframes and activities were performed when and for how long. The nesting of workframes within composite activities is shown using multiple levels. Above the timeline the location of each agent is displayed showing where certain activities were performed. Red lines at the end of workframes or activities indicate interrupts. The small yellow bars on primitive activities indicate that objects were used as resources when performing the activity. Hovering the mouse over the yellow area will display the 'touched' or used objects. Clicking with a mouse on workframes or thoughtframes will activate the explanation facility. Light bulb icons displayed along the timeline show when thoughtframes were triggered.

Communication View

The Agent Viewer has two types of Communication Views. The collapsed view shows only the communication between agents and objects selected for display from the Runtime View. It shows when a communication occurred, how many beliefs were communicated and in what direction. The expanded view not only shows agents and objects selected for display from the Runtime View but also all unselected agents or objects communicated with during any activity of the selected agent or object. Clicking on the icon of the agent or object communicated with will add that agent or object to the Timeline View. This allows the user to determine the activity the other agent or object was working on. Double clicking on a communication itself will display the beliefs that were communicated.

Explanation Facility

The explanation facility allows the model builder to analyze the behavior and state of agents and objects at a deeper level then the graphical view. It allows the user to determine what caused the activation of a workframe, what beliefs an agent had at time X, what actions were performed in a workframe, and what caused the termination of a workframe. The screenshots below show in order:

1. The facts in the world managed by the world state with a filter applied for the location attribute.
2. The beliefs of an agent at a user specified time, the filter is closed and all of the agents beliefs are shown.
3. The state information of a workframe with a reconstruction of the source code for that workframe based on the available data in the database. Frame available/start/end times are relative to a 0 based start time.
4. The state information of a workframe with the beliefs that matched the workframe's preconditions causing it to become available. Frame available/start/end times are here displayed using absolute time, displaying full date/time information.
5. The state information of a workframe with all the actions that were executed while the workframe was active.

Eclipse plugin

In addition to the Brahms Composer, you can also download and install an Eclipse plug-in for Brahms. This plug-in does not yet have all of the features offered by the Composer; its feature set consists of package management, source code editing, and compilation supporting the enhanced source code editing features expected in Eclipse. The plug-in offers the design views but does not offer full editing capabilities within those design views. The plug-in now also includes an integrated agent viewer. The plug-in requires at least Eclipse version 3.5 (Galileo) or 3.6 (Helios) and requires at a minimum JSE 5. It can be downloaded as per the instructions in the Brahms installation .zip file.

Changes

See the Change history for a list of changes to Brahms components.