README

Brahms Agent Environment version 2.0.6 alpha

9/23/2011
Copyright (c) 1998-2011 NASA Ames Research Center. All Rights Reserved.

I. Welcome!

Welcome to NASA's Brahms Agent Environment 2.0.6 alpha for Windows XP, Vista, 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 AgentEnvironment directory.

If you have a previous version of Brahms installed you must first uninstall that version. Before uninstalling the version or upgrading the Brahms Agent Environment 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 the Brahms Agent Environment. The installation will install a minimum of six scripts/executables in the bin directory, one for the compiler (bc), one for the virtual machine (bvm), one for the Brahms Hosting Environment (HostingEnvironment), one for the Brahms Integrated Development Environment (Composer), and one to generate an encrypted password for use with SSL (encpwd). On certain platforms also a process manager and wrapper script/executable are installed. The hosting environment, process manager, and password encryption scripts are used for the server component of Brahms to run Brahms models in distributed mode. 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, it is highly recommended to also pass the DTD referencing the local file system for efficiency.

The installation software will automatically install the appropriate version of Sun's JRE 6, except on Mac OS X where the appropriate version of Java must already be installed (JSE 5.0) and be the default Java virtual machine. The virtual machine requires at a minimum JRE 5.

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.cfg
teservice.cfg

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 Agent Environment directory to your system PATH environment variable.

III. What's New

Brahms Language

1. Previously, a Brahms (object.attribute = value) belief or fact could have a Java object as its value but a Java object could not be the "subject" of the belief or fact. This restriction has been lifted so that Brahms beliefs and facts can represent the values of the properties of a Java object as Brahms attribute values. Beliefs or facts about the properties of Java objects can trigger workframes, thoughtframes, and detectables and can be the content of communications between agents.
2. A new syntax for consequences (conclude statements) is supported that allows integration with the properties of Java objects and the conclusion of values for multiple attributes of a Brahms or Java object.
3. A subset of Java language expressions may be used in the body of workframes. Supported expressions include assignments, method invocations, constructor invocations, array creations, array initializers, and array access expressions.
4. Java types for Brahms attributes, variables, and parameters are no longer restricted to be subtypes of java.io.Serializable.
5. New value types -- byte, char, short, and float -- are available for Brahms attributes, variables, and parameters. These new types correspond to the Java primitive types of the same name. In addition, literals of type float can be indicated with a 'f' or 'F' suffix and character literals (e.g. 'A') are supported.
6. Local variable declarations are supported in the bodies of workframes. Local variable declarations are appropriate for variables that are not referenced in the preconditions of a workframe. Local variables may be given initializer expressions in their declarations and may be re-assigned in subsequent workframe body elements.
7. A Brahms compilation unit can now contain references to fully qualified concept names and fully qualified Java type names. A fully qualified concept name consists of the concept's package name followed by a '.' and an identifier for the concept. This allows two concepts in a model to have the same “simple” name as long as they are defined in different packages.
8. Backwards compatibility: "new", "byte", "char", "short", and "float" are now reserved words in the Brahms language and can no longer be used as identifers for Brahms concepts, attribute names, relation names, variables, or parameters.

Brahms Virtual Machine

1. Added support for new language features described in language specification version 3.0.
2. Added support for simrt as a new value for the mode configuration parameter in addition to the existing sim, rt, and drt values. The simrt mode is the same as the sim mode except that it introduces delays into the simulation every second if needed in order to keep the simulation clock in sync with real time. So a simulation that is run in simrt mode that takes n simulation units to run will take approximately n*time_unit seconds to complete. This mode may be useful for human-in-the-loop simulations.
3. Made some performance enhancements including more selective backtracking when evaluating the preconditions of a frame.
4. Many of the Java interfaces for the Brahms Java API were moved from vm.jar to common.jar to make them available to the Brahms compiler. This will only be an issue when compiling Java code that uses the Java API and has vm.jar on its build path but not common.jar. The problem can be fixed by adding common.jar to the build path.

Brahms Compiler

1. Added support for new language features described in language specification version 3.0.
2. The compiler now allows one or more compilation units to be compiled without requiring compilation of the entire model.
3. The compiler has several new command-line options:
-nowarn suppresses all warnings resulting from the compilation
-compatible enable backwards compatibility with looser import declaration requirements (default)
-strict require imports for any concepts from a different package that are referenced by a simple name
-debug display debugging information
-debugcfg <cfgfilename> use the specified log4j configuration file
4. When running in strict mode the Brahms compiler treats unqualified concept references in a manner similar to Java class references. An unqualified reference in a compilation unit to a concept defined in a package that is different from the compilation unit's package requires an import statement to be available in the compilation unit for resolving the unqualified concept name to a fully qualified name. When running in compatible mode the import declarations are global, i.e. a concept imported in one compilation unit can be referenced from another compilation unit without requiring it to be imported into that compilation unit.
5. Although it still parses all compilation units, the compiler will not regenerate a .bcc file for a concept if that file has a more recent modification date than the .b file for the compilation unit in which the concept is defined.

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.
When installing Brahms in Program Files or Program Files (x86) on Vista or Windows 7 with User Account Control (UAC) turned on Brahms will not be able to generate the history files, event information, and log files. The solution is either to turn off UAC or to install Brahms in a location other then Program Files or Program Files (x86) or to change the config/favservice.cfg, config/teservice.cfg, and config/vmLogger.cfg to specify a directory other then a directory in Program Files or Program Files (x86). The Proram Files directories are restricted by Vista/Windows 7.

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

To run the Brahms Agent Environment installer and the Agent Environment components on Mac OS X you must install JSE 5.0 or 6.0 from Apple and make it the default Java virtual machine for your OS X. The installer will not function correctly and the components will not function at all if JSE 5.0 or 6.0 is not installed and is not the default Java virtual machine.
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 AgentEnvironment\deploy 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 wish to place these jar files into a different directory make sure to update the bc and bvm scripts to include them in the classpath/extensions directories.
The Composer is able to reload Java classes from Java archives for external activities and external agents when running the compiler multiple times, allowing you to drop updates of these archives in the Agents directory and recompile the model with the updates. However the virtual machine is not yet capable of doing this. So if you need to rerun your model with updated Java archives you must restart the Composer if you want to run the virtual machine from the Composer.

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 Agent Environment. We hope you find it useful in your modeling and agent development efforts.

Sincerely,

The Brahms Development Team