Tutorials

Purpose

This document is a tutorial that will introduce you to Brahms and agent-oriented modeling. Brahms has matured in recent years to a system usable to model complex work practice scenarios. This tutorial will present the main aspects of the language and the various modeling constructs available. As an agent language, Brahms requires a different way of thinking than object-oriented and procedural languages. In many books on object-oriented and procedural languages the Atm (automatic teller machine) scenario is used to explain the language.

The Atm example is a perfect starting point also for learning Brahms, because it showcases many of Brahms modeling constructs and also shows how Brahms differs from object-oriented or procedural languages. The discussion of a Brahms implementation of the Atm scenario therefore will form the core of this tutorial. You will be asked to complete exercises that consist in writing pieces of Brahms code to model increasingly complex aspects of the scenario. You will also be given working code examples with which to compare your answers.

This tutorial, however, does not replace the Brahms Language Specification document, that fully defines the modeling capabilities of Brahms and the formal syntax and related semantics of all the modeling concepts. While this tutorial is self-contained and does also cover elements of syntax and semantics, it is only an introduction to Brahms. It teaches by example how to use the language concepts, so that by the end of this tutorial you will be able to build simple to reasonably complex Brahms models. For a deeper mastering of the language, however, this document should be used in coordination with the Brahms Language Specification document.

Intended Audience

This document is to be used by future Brahms modelers as a guide in their development of Brahms models. Some level of previous programming experience is expected. Knowledge of object-oriented languages and rule-based languages is preferable, but not essential.

Usage

The tutorial is a self-contained introduction to the language. Experienced programmers might move quickly through the initial sections of the Atm scenario (Chapter 4, Sections 3 – 8) and spend more time on the more complex sections (Sections 9 –11). While the Atm scenario will be especially useful to people familiar with procedural or object-oriented languages, it will also be understandable by those with no prior knowledge of procedural and object-oriented languages.

The full tutorial includes installation issues, syntactical issues, as well as the description of the various steps of the tutorial. V1.2 full tutorial and the V1.1 Lesson Files are available separately.

Scenario

Brahms models may be thought of as statements in a new formal language developed for describing work practice. The online language specifications show the conventional notation and constructs used to express the syntax for the modeling language (BNF). The language is domain-general in the sense that it refers to no specific kind of social situation, workplace, or work practice; however, it does embody assumptions about how to describe social situations, workplaces and work practice.

Brahms can model and simulate work practices. Brahms models are written in the agent-oriented language that will be described in this document. The run-time component - the simulation engine - can execute a Brahms model, also referred to as a simulation run. A Brahms model can be used to simulate human-machine systems for what-if experiments, for training, for 'user models', or for driving intelligent assistants and robots. A traditional task or functional analysis of work leaves out the logistics, especially how environmental conditions come to be detected and how problems are resolved. Without consideration of these factors, we cannot accurately model how work and information actually flows, nor can we properly design software agents that help automate human tasks or interact with people as their collaborators. What is wanted is a model that includes aspects of reasoning found in an information-processing model, plus aspects of geography, agent movement, and physical changes to the environment found in a multi-agent simulation. A model of work practice focuses on informal, circumstantial, and located behaviors by which synchronization occurs, such that the task contributions of humans and machines flow together to accomplish goals.

Brahms makes this kind of models possible. Brahms relates knowledge-based models of cognition (e.g., task models) with discrete simulation and the behavior-based subsumption architecture. Brahms is centered on the concept of 'agents'. Agents' behaviors are organized into activities, inherited from groups to which agents belong. Most importantly, activities locate behaviors of people and their tools in time and space, such that resource availability and informal human participation can be taken into account. A model of activities doesn't necessarily describe the intricate details of reasoning or calculation, but instead captures aspects of the social-physical context in which reasoning occurs. Thus Brahms differs from other multi-agent systems by incorporating chronological activities of multiple agents, conversations, as well as descriptions of how information is represented, transformed, reinterpreted in various physical modalities.

The Brahms language is structured around the following concepts:

  • Agents and groups
  • Objects and classes
  • Beliefs and facts
  • Workframes
  • Activities
  • Thoughtframes
  • Geography

which can be related to each other in the following way:

Groups contain
AGENTS who are located and have
BELIEFS that lead them to engage in
ACTIVITIES that are specified by
WORKFRAMES that consist of
PRECONDITIONS of beliefs that lead to
ACTIONS, consisting of
COMMUNICATION ACTIONS
MOVEMENT ACTIONS
PRIMITIVE ACTIONS
other COMPOSITE ACTIVITIES
CONSEQUENCES of new beliefs and world facts
THOUGHTFRAMES that consist of
preconditions and
consequences

The Atm scenario will drive you through all of these concepts. It will first present them - step by step - and then it will ask you to use them in increasingly realistic Brahms representations of a scenario where students get cash from Atms and spend it at various restaurants.

The ATM scenario

A Brahms file is a file written according to the rules of the Brahms language and identified with the .b extension. Most of your Brahms models (including the Atm case that you will build through this tutorial) will consist of more than one Brahms file. Unlike most other languages like C, Java or Pascal, Brahms does not have a main method that serves as the starting point for a Brahms simulation. While Brahms does not prevent you from placing more than one concept in one Brahms file, it is recommended that you create one .b file for each 'concept' that you specify for your model (note that a concept can be a group, agent, class, object, areadef, area, path, conceptual class or conceptual object; but we will go back to this in detail in the next sections). It is also recommended that you always create one Brahms file (.b) for your model that will import all the other .b files that are to be part of your model.

The Atm scenario discussed in the following pages will teach you the various components of the language and the main differences between object-oriented and agent-oriented programming. The final challenge of the scenario is to model the following, complete case:

Model a day in the life of a student. Students spend most of their time studying, but get hungrier as the time goes by. When they are particularly hungry, they decide to move to one of the restaurants in town. Students choose the restaurant according to how much money they are carrying. If a student does not have enough money even for the cheapest restaurant, she will decide to pass first by the Atm of the bank where she has her account. When she arrives at the Atm, the student inserts her bankcard and tries to remember the PIN associated to her account. The Atm allows its users 3 attempts to digit the correct PIN, before refusing the card altogether. The Atm communicates with the central bank computer to verify the correctness of the information provided by the user. If the bank computer communicates to the Atm that the PIN is correct and that the user has enough balance in her account, the Atm will dispense the cash and will print an invoice with the account number and the remaining balance. Students need to have enough balance in their accounts to take out cash: if they attempt to take out more money than they have, the bank computer will notify the students (through the Atm) of the remaining amount of dollars in the account. The student will modify her approach accordingly, and take out just exactly the remaining dollars.

Don't worry - you will not have to model all of this right now! Chapter 4 will drive you through this scenario step by step, progressively adding components and activities and increasing realism and complexity. Still, to get you started and give you a sense for the language that you will be discovering, you will be now given an example of code coming from the Atm case itself. Clearly, you will not yet be able to 'read' this code. Still, it will be a good exercise to browse through it, trying to recognize the keywords that we described above, in order to get familiarized with the concept of a Brahms file. This file describes (some of) the activities of the student:

package gov.nasa.arc.brahms.atm;
group Student {
  attributes:
    public boolean male;
    public double howHungry;
    public int perceivedtime;
    public Diner chosenDiner;
    public boolean hasTakenCash;
  relations:
    public Account hasAccount;
    public Cash hasCash;
    public BankCard hasBankCard;
  initial_beliefs:
    (current.hasTakenCash = false);
    (Boa_Atm.location = BankOfAmericaUniversityBranch);
    (WF_Atm.location = WellsFargoUniversityBranch);
  activities:
    move MoveToLocation(Building loc) {
      priority: 1;
      location: loc;
    }
    primitive_activity FeelHungry() {
      priority: 1;
    }
  workframes:
    workframe wf_MoveToLocationForCash {
      repeat: true;
      variables:
      forone(Cash) cs; 
      forone(Atm) at;
      forone(Bank) bk;
      forone(Building) bd;
      when( knownval(current hasCash cs) and
      knownval(at.location = bd ))
      do {
        MoveToLocation(bd);
        conclude((current.readyToLeaveAtm = false), bc:100);
      }
    } 
  thoughtframes:
    thoughtframe tf_ChooseBlakes {
      repeat: true;
      variables:
      forone(Cash) cs;
    when( knownval(current hasCash cs) and
      knownval(cs.amount > 15.00) and
      knownval(current.checkedDiner = false) and
      knownval(Campanile_Clock.time < 20))
 
    do {
      conclude((current.chosenDiner = Blakes_Diner), bc:100);
    }
  }
} // Student

Interpretation of the Scenario in an Agent-based language

At the core of Brahms there is the concept of an agent. An agent represents an interactive system, a subject with behavior interacting with the world. An agent can for example represent a person in an organization, but could also represent an animal in a forest. A Brahms model is always about the activities of agents in a work process, and agents engage in activities depending on facts as well as the beliefs they have about facts in the world. Mapping the Atm scenario from objected oriented programming into Brahms, therefore, means that the modeler must adopt an holistic approach to modeling, trying to explain and simulate individual behavior through actions and decisions, and selecting what to keep inside the picture and what to take out. An exemplar Brahms embodiment of the Atm scenario discussed above could be the following (related Brahms concepts and keywords are indicated within parentheses):

Alex (agent), a student (group) at Berkeley (location), has cash (object) and an account (object) at the Bank of America (instance of the class Bank) that he can access by using his cashcard (object) at an Atm machine (object with location). Alex studies most of the time, but as the time goes by he also feels the urge to eat. There are some restaurants in Berkeley, with different menus and prices. When he is hungry, Alex checks (thoughtframe) how much money he has, and whenever he needs more money to go to the restaurant and eat. Depending on his financial situation, therefore, he can then decide to (workframe) move (primitive activity) to the restaurant and eat, or instead go first to the Atm to get some cash (workframe, composite activity). At the Atm, Alex will insert his cashcard into the Atm machine, which will read the card and ask for its pin. The Atm then will communicate with the Bank, verify the card and the provided information, and complete or abort the transaction. To make things more interesting, there is another student, Kim, who does the same things Alex does but likes different restaurants, has a different time schedule, and has opened her account at a different Bank from the one Alex is using...

As it might be already clear from this short example (and it will get clearer as you work through the tutorial), there is a deep conceptual difference between the way the Atm scenario can be dealt with in Brahms and the object-oriented approach. To write a proper Brahms model, you will have to think about what agents and objects do and why they do them. This is a more complete and more holistic approach. It is a human centered computing (HCC) view as opposed to the software engineering view. The latter might be satisfied with focusing on use cases; the HCC view instead studies why and how the human is using the machine, before designing the Atm machine itself. This also translates in language differences between Brahms and other object-oriented languages: Brahms is an agent-oriented language with elements of rule-based languages, where activities are not the same things as methods, and rules are not the same as if..then constructs of imperative languages. It is important to keep this in mind while modeling in Brahms in order to avoid errors and misunderstandings.

Full Tutorial

The Full version of this Tutorial is available as a PDF file or zipped Word document. Together with this document, you should also download a set of folders containing the Atm model files at different stages of its evolution.

You can use these files for comparison and for help when you will have to write your own Brahms code to model various aspects of the Atm scenario. You can also use those files to see immediately how a Brahms model work. The folder called 'Final' contains the complete version of the scenario, that is, what your model should look like at the end of this tutorial. The other folders contain the scenario as modeled up till different sections of this tutorial, that is, they are the 'solutions' to earlier sections of the tutorial. These folders offer you a way to study and compare the evolution of the tutorial from the simple activities of the first Lessons to the complex interactions of the last ones. You can open these files right now and see their content. You will find:

  • .b files: they are the Brahms model files.
  • .xml files: they are the files produced by the Brahms compiler.
  • Atm...txt files: they are files containing the history of the events in the simulation, and they are produced by the Virtual Machine.
  • Atm...mdb files: they are files containing the simulation in a format that the AgentViewer can read. They are produced by the parser in the AgentViewer
  • Other files (such as .dsp, .dsw) which can be used in coordination with Microsoft Visual C++

The compiler, the virtual machine, and the AgentViewer are components of the Brahms environment that you can download from the Developers section and that will be described in the next sections.

Files and folders

The Full version of this Tutorial is available as a PDF file or zipped Word document. Together with this document, you should also download a set of folders containing the Atm model files at different stages of its evolution.

To use these files, you must copy the content of the folder whose scenario you want to run, and paste it into the ATM model folder on your machine. You can generate the xml files and compile the scenario:

C:\Brahms\AgentEnvironment\bin\bc.bat -dtd C:\Brahms\AgentEnvironment\DTD -lp 
C:\Brahms\AgentEnvironment\Models\lib;C:\Brahms\projects\AtmModel\final_source 
C:\Brahms\projects\AtmModel\final_source\gov\nasa\arc\brahms\atm\AtmModel.b
C:\Brahms\AgentEnvironment\bin\bvm -cf C:\Brahms\AgentEnvironment\config\vm.cfg -lp 
C:\Brahms\AgentEnvironment\Models\lib;C:\Brahms\Projects\AtmModel\final_source gov.nasa.arc.brahms.atm.AtmModel

which will create the history file of the simulation in the Databases folder in AgentEnvironment. You can recognize this file because it is a .txt file with the name of the file you compiled, with date and time appended.

Thereafter, open the application Composer and switch to the Agent Viewer view in the toolbar (select drop down with Composer Design View and select Agent Viewer), and click on the top File menu, select Agent Viewer, then select New Database to parse the history file into a new database. Look for the history file when the selection window opens, and once you find it, select it. The AgentViewer will create a new MySQL database with the history of the simulation and then it will actually start parsing the file. If the parsing completes without sending out error messages, it will open the database and display the agents and objects that were part of the simulation.

Versions

Version history available here

ConditionsPublications