This page describes the HLA Federates that are provided with the EarthCARE Simulator. The HLA Federates are accessible through a centralized repository.

The EarthCARE federates essentially consist of wrappers for the simulation packages. Their structure complies with the general structure of EODiSP wrappers.

The HLA Federates are described in terms of their Simulation Object Model or SOM. The SOM 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.

Only the following elements are included in the SOMs of the EarthCARE federates:

• objectClasses to describe the attributes published by each federates.
• synchronizations to describe the synchronization points used by the federates.
• dataTypes to describe the types of attributes published by the federates.
• interactions to describe the HLA interactions used by the federates.

The sections below describe the usage of the above elements in the EarthCARE federates. The last section in the page explains how to access the federate SOMs and the code implementing them.

Object Class Structure

The HLA standard prescribes that all object classes be derived from the predefined HLAobjectRoot class. This is accordingly the top-level class for the object classes defined in the EarthCARE SOMs.

In order to create a dedicated namespace for the EarthCARE object classes, the EarthCARE object class is defined as a child of the HLAobjectRoot class and as the direct parent of all EarthCARE object classes. This object class is empty and defines no attributes. All the other object classes defined by the EarthCARE SOMs are child classes of EarthCARE.

The EarthCARE object classes are defined to be either pure 'publish' or pure 'subscribe' classes. Their attributes are either 'publish' or 'subscribe' attributes ('publishSubscribe' atttributes are not used) and a certain class only contain attributes of the same kind.

There are basically two types of federates in the EarthCARE Simulator. One type is represented by the sim_controller federate. The second type is represented by all the other federates (the federates wrapping the KNMI models and the orbit_propagator federate). The typical structure of the SOM of the latter kind of federate is shown in the figure below.

This SOM has three kinds of object classes. The FederateInfo object class is common to all federates except the sim_controller federate. It defines attributes that are published by all these federates and that relate to their general execution status. The LidFiltePar object class defines the configuration parameters of the federates. All federates (except the sim_controller federate) have such a xxxPar object class (where 'xxx' is the name of the federate) to define their configuration parameters. Finally the xxxStream object classes describe the files that the federate generates as outputs or reads as inputs.

The SOM of the sim_controller federate has a structure that is the complement of those of the other federates: it subscribes to the FederateInfo object class which is published by all other federates, and it publishes all the xxxPar object classes. The sim_controller federate does not see the stream object classes because these only mediate exchanges of data between the other federates.

The FederateInfo Object Class

There are some key data that are published by all federates (except the sim_controller federate) and which are intended to be displayed through an excel interface by the sim_controller federate. In order to facilitate their uniform treatment, these data are gathered together in one single object class called the FederateInfo. Its attributes are:

• name: the name of the KNMI program embedded within the federate or 'orbit_propagator' for the orbit_propagator federate.
• modelVersion: a string defining the version of the program embedded within the federate.
• failureMode: a flag indicating the failure mode of the federate.
• execStatus: a flag indicating the execution status of the federate. This flag essentially indicates whether the program embedded within the federate has already run or whether the federate is still waiting for some or all of its input data.
• senderId: the federate handle, namely an integer uniquely identifying the federate that is updating the attributes in this object class.

The sim_controller federate subscribes to the FederateInfo object class. When it receives a notification that one of its attributes have been updated, it needs to know which federate did the update. For this reason, the EarthCARE federates are designed to always send the value of the senderId attribute together with the value of the updated attribute. The presence of the senderId allows the sim_controller federate to identify the origin of the update and to process it appropriately.

The Parameter Object Classes

Most simulation models need to be configured by specifying the values of certain simulation parameters. The EarthCARE federates accordingly define object classes to hold the model parameters. For each federate that needs the specification of one or more simulation parameter, an object class with a name like 'xxxPar' is defined where 'xxx' is the name of the federate. This object class defines the attributes associated to the simulation parameters associated to the federate.

The federate subscribes to the parameter object class. All the parameter object classes are published by the sim_controller federate.

All parameter attributes are defined to be of primitive type.

The File Stream Object Classes

The KNMI programs exchange information through files that represent their inputs and outputs. These input and output files are mapped to object classes in the federates that wrap the programs. For each input or output file a dedicated object class is defined with a name like 'xxxStream' where 'xxx' is the name of the file.

The file stream object classes cover both file access modes supported by the EarthCARE Simulation. The files generated by the KNMI programs can be very large (with sizes of hundres of megabytes or even gigabytes). For this reason, their transfer through the HLA infrastructure must be done in chunks of size sufficiently small to fit within the address space of the JVM where the federates are running. The size of each chunk is fixed and is defined as an initialization parameter for the federate itself.

The attributes of the file stream object classes are:

• chunk: a byte array representing a chunk of the file that is being transferred.
• chunkNr: an integer defining the chunk that is being sent in this transfer.
• nrOfChunks: the total number of chunks in the current transfer.
• url: a string representing the URL of the input or output file.

Obviously, the last attribute is only used when the federate is operating in url transfer mode.

Data Types

The EarthCARE federates only use a small set of data types. Three kinds of HLA data types are used: basic data types, enumerated data types, and array data types.

Synchronization Points

The EarthCARE federates use the five synchronization points predefined by the EODiSP (EODISP_START, EODISP_PAUSE, EODISP_STEP, EODISP_RESUME, and EODISP_STOP). No additional simulator-specific synchronization points are defined.

The EODiSP synchronization points are registered by the EODiSP control federate. The EarthCARE federates therefore are only responsible for achieving these synchronization points.

The EODiSP_START synchronization point is achieved after all attribute subscriptions and publications have been completed.

After the EODiSP_START synchronization point has been achieved, each federate is ready to react to a notification that one of its input attributes (i.e. one of the attributes to which it subscribes) has been updated. At this point there are two flows of attribute updates.

The info flow is related to the update of attributes in the FederateInfo object class. Federates that publish this object class are designed to update attributes in this class immediately after the EODiSP_START synchronization point is achieved.

The simulation flow is related to the generation and processing of the KNMI input and output files. This flow starts only after the sim_controller federate updates the configuration parameters of all the other federates.

After all configuration parameters have been updated by the sim_controller federate, the simulation proper starts. The scene_creator federate, which does not depend on any input file, triggers the execution of the scene_creator program. When this program terminates, it makes its output file available and therefore releases the execution of the forward model federates (the lid_filter federate, the rad_filter federate, the MC_sim_main federate, and the MC_LW_sim_main federate). And so on until all programs embedded within the KNMI federates have been executed.

The KNMI federates achieve the EODiSP_STOP synchronization point after the program which they embed has completed execution. The other two federates - which are purely passive - achieve it immediately.

The pause, step and resume mechanism is implemented at the level of two KNMI federates: the radar and the lidar_ret1 federates. For this purpose, these KNMI federates can be placed in an 'inhibited' state. If they are in this state, then they will not execute the program they embed even if all their input data have arrived.

A pause request is intended to cause the simulation to stop after the currently executing KNMI programs have terminated execution. The EODiSP_PAUSE synchronization point in the radar and the lidar_ret1 federates is achieved after the federates have been placed in the 'inhibited' state. In the case of other federates, it is achieved immediately.

A step request can only have an effect if it is preceeded by a pause request. It causes all and only the programs that have all their inputs available (but are being held because the simulator received a pause request) to be executed. KNMI federates that have all their inputs ready, achieve the EODiSP_STEP synchronization point after the program they embed has been executed. All other federates achieve it immediately.

A resume request is intended to cause the simulation to resume execution. The EODiSP_RESUME synchronization point in the radar and the lidar_ret1 federates is achieved after the federate is taken out of the 'inhibited' state. Federates whose input data are ready, will therefore immediately resume execution.

Interactions

The EarthCARE Simulator federates use only the pre-defined EODiSP registerFederate interaction. No simulator-specific interactions are used.

Federate Code

All the code implementing the wrappers for the EarthCARE federate is accessible from the download page of the EarthCARE Simulator. The federate code can be found in the federates directory. There is a dedicated subdirectory for each federate. The SOM are stored in files with the .som extension. The rest of the wrapper code can be found in the src directory.