README

Brahms Professional Agent version 1.0 beta 6

1/12/2005
Copyright (c) 1998-2005 NASA Ames Research Center. All Rights Reserved.

I. Welcome!

Welcome to NASA's Brahms Professional Agent 1.0 beta 6 for Windows 2000, Windows XP, Linux, Sparc/Solaris and Mac OS X. Please take a few minutes to read this file, which contains the latest information regarding this release.

II. Installation Notes

In order to use the software you will need a license file (brahms.lic). Without the license file you will be able to install the software but you will not be able to use the Brahms virtual machine. If you have registered before to download previous versions of Brahms you can request a license file by sending an e-mail to register@agentisolutions.com. Include your name in the e-mail and we will send you a license file. If you registered to download this current version of Brahms then you will have received a user name and password to download this software as well as a license key. Place the license key in the ProfessionalAgent directory.

If you have a previous version of Brahms installed you must first uninstall that version. Before uninstalling the version or upgrading Professional Agent to this latest version make sure you copy your configuration files in case you want to use the same settings with the new version. You can copy the configuration files to the new version of Brahms once the new version is installed. The new version installs new configuration files and note that new configuration properties are supported in the virtual machine's configuration file. So make sure to check out the newly installed vm.cfg file before overwriting it with your own.

Start the setup program. It will start an installation program that will guide you through the steps to install Professional Agent. The installation will install four executables in the bin directory, one for the compiler (bc), one for the virtual machine (bvm), one for the Brahms Integrated Development Environment (Composer) and one for the Brahms Agent Monitor (AgentMonitor). The installation program will install two batch/script files in the installation directory to start the compiler and the virtual machine with commonly used parameters already set. The parameters that are already set are the DTD path for the compiler and the vm.cfg file path for the virtual machine.

The Server directory contains six batch files to start all the necessary server components to run Brahms models in distributed mode. These batch files are numbered to indicate their starting order. These batch files start the Corba naming service, KAoS directory service, KAoS domain manager, KAoS servlet runner, KAoS Policy Administration Tool (KPAT) and Brahms Agent Environment Manager. For more information on running Brahms in distributed mode see the ReadmeDistributedVM file.

In the bc batch/script file two values have to be passed at a minimum, the first one being the library path, the second one being the source file to be compiled.

The installation software will automatically install the appropriate version of Sun's JRE 1.5, except on Mac OS X where the appropriate version of Java is already installed. The virtual machine requires at a minimum JRE 1.5.0.

The various components use some configuration files. These files are generated during the installation and contain the appropriate default settings. The configuration files generated by the installation program are (depending on the chosen installation):

vm.cfg
vmLogger.cfg
favservice.ini
teservice.ini
oworldservice.ini

The configuration files contain comments on how to use or set their properties. Make sure to verify the vm.cfg, you might have to change your library path and/or working directory.

In order to use the compiler and virtual machine from other places on your machine, make sure to add the Brahms Professional Agent directory to your system PATH environment variable.

III. What's New

Brahms Professional Agent allows for agent-based systems developed using Brahms to be run distributed over multiple Brahms virtual machines. Agents are able to communicate with one another across Brahms virtual machines over a network. This release of Brahms Professional Agent uses Corba/IIOP for its naming, directory and transport services managed by the KAoS agent architecture.

Whenever the Brahms virtual machine is run in (distributed) real-time mode the virtual machine will now export all of its events time stamped using the real time the event occurred instead of the discrete event time. This is reflected in the EventInformation.txt file. The file agent viewer service now interprets the new time stamps correctly and allows a modeler to view the results of an agent-based system execution in the agent viewer.

Brahms Professional Agent now allows external agents to communicate to remote agents and adds support for Brahms Language Specification V2.12 adding support for gesture and create area activities and adding support for the relational operators >, >=, < and <= in detectable conditions in addition to the relational operators = and !=.

Brahms Professional Agent now includes five new concepts in the base library 'SystemGroup' and 'SystemClass', both declaring some generic activities that can be used to write beliefs, facts or string based messages to the log file from within a model, 'Calendar', 'CalendarUtilGroup' and 'CalendarUtilClass', these new concepts allow agents to retrieve and manipulate date/time information. Check the source code for those concepts for more instructions on their use. Check those concepts for more instructions on their use.

Professional Agent includes an updated Brahms integrated development environment called the Brahms Composer. The new Brahms Composer now includes both a design view and source code view to allow for Brahms models to be developed visually and/or to develop Brahms models by writing source code. The two views are integrated with one another so for elements added to the design view source code is generated and the elements written in source code are displayed in the design view. The Brahms Composer has full support for language specification 2.12. The Brahms Composer displays syntax and semantical errors in a task list that allows a user to quickly jump to the line of source code in the source file where the error was found. The Brahms Composer furthermore integrates with the Brahms compiler. For more information about the Composer please read the Composer_Readme file.

Professional Agent includes a new component named the Brahms Agent Monitor. This applications allows users to monitor all of the Brahms virtual machines, also called agent environments, and agents running in each agent environment from anywhere on the network. This application can give the user a quick overview of which agent environments are running with what agents and what their connectivity status is on the network.

Professional Agent includes an updated Brahms Agent Viewer. The Brahms Agent Viewer in its version 1.4.5 alpha will replace the previous version 1.3.1 that was tied to the Windows platform. The new agent viewer is integrated with the Brahms Composer as a plug-in and is now platform independent and can run on Windows, Linux, Sparc/Solaris and Mac OS X and uses MySQL 4.x as the underlying database (not included with Professional Agent) replacing the Microsoft Access database. The agent viewer includes a variety of bug fixes. For more information about the Agent Viewer please read the AgentViewer_Readme file.

IV. Known Problems

Compiler: All brahms files need to have the extension '.b'. The Brahms Compiler will not be able to find imported files that have other extensions like for example '.txt'.
Virtual Machine: The distributed virtual machine does not yet distribute the areas. All areas must therefore remain local on each virtual machine they are references. This will also result in agents running in different virtual machines not being able to automatically detect one another when in the same area.

V. Revision History

The revision history for the Brahms Composer, Agent Monitor, Agent Viewer, Compiler and Virtual Machine can be found in the file named Changes.

VI. Important Notes

This new version can cause problems when compiling models that use a non-approved base library with custom added attributes. These models are required to be updated in order to use them with this version. The best way to update those models is to create model specific base classes that will automatically inherit from the base classes and in which the model builder specifies any customizations that were made to the base classes. The base library is included in the installation and can be found in the Models directory. Make sure to have this base library available in your library path when compiling your models.
If you use external activities or external agents as part of your Brahms models, make sure to package them up as jar files using Sun's jar tool and place the jar files in the ProfessionalAgent\ Agents directory. The compiler and virtual machine will in that case be able to find those external activities and agents, not placing them in that directory will cause the compiler and virtual machine to generate errors that they are unable to find the appropriate class files. If you want to place the class files in a different location you will have to pass an appropriate Java class path to the compiler and set the class path appropriately in the vm.cfg file. Not doing so will cause the compiler to generate an error stating that it cannot find an external activity and the virtual machine will also generate an error stating that it is unable to find the Java classes required for these external components. If adding the classes to the classpaths using the compiler and vm settings doesn't work you can add the path to the classpath in the bc.lax file and bvm.lax file located in the ProfessionalAgent\bin directory. You can open those files with a text editor and edit the lax.class.path entry.

VII. Contacting the Brahms project team for Technical Support

In case you have problems with the installation or questions and problems with the use of the Brahms Composer, Agent Viewer, Compiler or Virtual Machine you can reach Technical Support at:

E-mail: support@agentisolutions.com
www: http://www.agentisolutions.com/support/support.htm

Thank you for trying the Brahms Professional Agent version 1.0 beta 6. We hope you find it useful in your modeling and agent development efforts.

Sincerely,

The Brahms Development Team