User Manuals

This page gives access to user-level information describing how to install and operate the EODiSP. This information is organized as a set of pages that cover various aspects of EODiSP usage. The information in these pages is intended for end users of the EODiSP. Developer-level information is available on the Developer Manauls pages.

The EODiSP is a simulation framework built on the High Level Architecture (HLA). The HLA is defined by an IEEE standard. In order to understand the information presented in this page and, indeed, in order to use the EODiSP, familiarity with the HLA is necessary. It is not the purpose of this page or of this web site to provide an introduction to the HLA. This can be found in several publicly accessible documents. However, a brief description of the HLA together with a description of the general EODiSP concept is available in the project overview page.

Contents

Installation

The programs are available either as source code from a svn repository or as self-contained .jar files. Here it is assumed that you download the jar files from the website.

You will find all programs on the download page of this website. There a six main programs available. You can download and run them independently by issuing the following command on a command line:

java -jar <eodisp_xxx>.jar [options]

On windows, running the program is even simpler and can be done by double-clicking directly on the .jar file.

Usage

Configuration Files

The mode of operation of the EODiSP is defined by a set of configuration files. The configuration files are simple text-based files with [key, value] pairs, each identifying and setting a specific value. A description of each value is given in the respective file and will not be repeated here. All required configuration files are automatically created by the application itself if it is missing (i.e. the first time the application is started).

Several configuration files are defined, each covering a particular aspect of the EODiSP operation. A single EODiSP application may therefore be controlled by several configuration files.

Configuration files have names like: xxx.conf and they are all located in the same directory <working-dir>/conf where <working-dir> is the working directory of the EODiSP application (recall that the working directory of an EODiSP application can be set as a startup parameter for every EODiSP application by providing a value to the --working-dir parameter).

The table below lists all the EODiSP configuration files:

Name of Configuration File Description
remote.conf Configuration parameters for distribution aspects
jxta.conf JXTA configuration parameters
log4j.conf Configuration parameters for data logging
sm_core.conf Configuration parameters for Simulation Manager core
sm_gui.conf Configuration parameters for Simulation Manager GUI
mm_core.conf Configuration parameters for Model Manager core
mm_gui.conf Configuration parameters for Model Manager GUI
repos.conf Configuration parameters for Repository core
rm_gui.conf Configuration parameters for Repository GUI
rti.conf Configuration parameters for Runtime Infrastructure (RTI)
crc.conf Configuration parameters for Central RTI Component (CRC)
lrc.conf Configuration parameters for Local RTI Component (LRC)

As an example, suppose you wish to find the configuration file covering distribution issues for the Model Manager application. Suppose too that the model manager runs on a Unix machine and that it is started with the default working directory (which is ~/.eodisp/model_manager). The desired configuration file would then be: ~/.eodisp/model_manager/conf/remote.conf.

Test Cases

The EODiSP test cases describe various aspects of the operation of the EODiSP. Each test case defines a step-by-step procedure to achieve a certain objective and it specifies the criteria to determine whether the test case was successful. The test cases may depend on each other in the sense that execution of test case A may first require the successful execution of test case B. Such dependencies are clearly spelt out in the test case description.

Four groups of test cases are identified, one for each of the four applications provided by the EODiSP: the simulation manager application, the model manager application, the repository application, and the support application.

The full set of EODiSP test cases is presented in list form in a dedicated page which also contains the links to the individual test case descriptions.

Many of the test cases rely on the EarthCARE Simulator as a demonstration platform. The configuration of the EarthCARE Simulator that is used for the use cases is also described on a dedicated page.

Sample Code

  • Sample Federates: sample HLA federates ready for integration in the EODiSP.
  • Sample Wrappers: sample wrappers to transform generic simulation packages into HLA-compliant federates.

EODiSP Instantiation

The EODiSP is a platform that simulation developers can use to build a simulation application. The process whereby the EODiSP deliverables as provided in this web site are used to build a simulation application is called instantiation.

The input to the instantiation process is the set of simulation packages that must be integrated together to build the target simulation. The basic steps in the instantiation process are:

  • the definition of the simulation architecture,
  • the development of the wrappers for the simulation packages, and
  • the registration of the resulting HLA federates in the EODiSP repository.

Given the data-driven paradigm underlying the EODiSP, the first step basically entails identifying the input and output data of each simulation package. More formally, it entails defining the interface of the federates that will represent the simulation packages in the EODiSP simulation. The description of these interfaces can first be done informally but must eventually be done using a formalism prescribed by the HLA. For this purpose, the HLA defines an XML-based language and for each federate a Simulation Object Model or SOM must be defined. The SOM is an XML-based document that fully describes the type of information that an individual federate can provide to an HLA federation as well as the information that an individual federate can receive from other federates in the HLA federation. The structure of the SOM is defined by the HLA standard.

In the second step in the instantiation process, wrappers are developed that transform the simulation packages into HLA federates that comply with the SOM's defined in the first step.

Once the simulation packages have been wrapped as HLA federates, they can be registered into the EODiSP repository from where they are available to participate in an EODiSP application. This registration process is done through the EODiSP model manager application.

For demonstration purposes, a complete instantiation of the EODiSP has been done to build the EarthCARE Simulator. Readers can refer to the simulator web site for concrete examples of how the above three steps can be carried out.

EODiSP Extension

The EODiSP is provided under a free and open software licence. Users can therefore extend it by modifying its implementation or by adding new functionalities to it.

Developers who wish to extend the EODiSP need to understand its architecture. This is described in the EODiSP developer's guide. This page also gives access to the detailed design documentation for the EODiSP in Javadoc format. The EODiSP software can be accessed from the download page.

Typical extensions that users may want to do include:
  • At present, the EODiSP only implements a subset of the HLA services. This subset could be extended to improve the coverage of the HLA standard. This extension would only affect the HLA layer of the EODiSP architecture.
  • The EODiSP networking layer could be upgraded or replaced. This layer is currently based on the JXTA framework and its definition was driven by the requirements that the EODiSP be able to support the development of distributed simulations where some of the simulation models are located behind firewalls. Accommodating this requirement has led to design choices that are marginally suboptimal in terms of execution speed. Users who are interested in maximizing performance may want to replace or modify the EODiSP network layer. Note that the EODiSP has a layered architecture that is intended to allow this kind of selective upgrades or replacements.
  • Tthe backend in the repository implementation could be replaced. Currently, EMF is used to store the data in the repository. The format in which this data is stored is XML. This implementation is stable and suits the need of the current requirements of the EODiSP. However, if a repository grows very large, it could be beneficial to replace this implementation with a relational database to increase data handling performance as well as improve memory footprint of the repository application. Note that such a change would not be trivial, since it affects not only the repository code itself, but also the code in the client applications (i.e. the manager applications).