Crib Notes on Using JFORCES

This memo provides insight into how to actually use the JFORCES model. If you have questions about what JFORCES is click here. Alternately, if you need detailed information relating to inputting specific data or performing specific functions through the JFORCES interface click here.


The JFORCES model is a comprehensive wargame simulation encompassing both distributed real-time man-, software- or hardware-in-the-loop capabilities for exercise and testbed support as well as batch run capabilities for analysis support. This dual nature of JFORCES, while powerful and not difficult to use in practice, sometimes leads to confusion when attempting to describe how to use JFORCES in both modes simultaneously. Therefore, this paper will describe how a user interested in using JFORCES to support analysis should run the model. This section should be of interest to all users. Then additional key runtime controls pertinent to interactive control and exercise support will be addressed.


Starting JFORCES

But before proceeding to the details of how to run JFORCES, the user needs to know how to start JFORCES. The user will need to log into the computer as a JFORCES user. Ask the system administrator (or whoever else set up JFORCES on the machine) for the username and password for this user. If JFORCES has not been installed on your machine email us to request a copy of the JFORCES installation CD. Please specify your government sponsor or other US-government related reason to be granted access to JFORCES and any information on your machine. Reccommended configurations to run JFORCES under Linux (the most cost-effective solution) can be found elsewhere on this site.


Assuming JFORCES is installed, after logging in the user will be presented with a default screen appropriate to his system. Click here to see a default screen for a RedHat Linux installation. The user might have to open a terminal window. To do this on a RedHat machine click on the "New Window" icon. Click here to view a screen capture with this icon highlighted. This will cause a terminal window to be created (click here for a sample). Note that the user can modify this window for his preferences by right clicking in the body of the window and selecting "Preferences" from the list presented. The system will save the modified preferences as new window defaults. Terminal widows have a number of options that can be set (or reset) using any of the three mouse buttons. Please see the terminal documentation on http://www.redhat.com for a complete description.


Now that user has a terminal window he can start the standard JFORCES interface by typing "start <carriage return>". Click here for a picture of the initial JFORCES interface. The two primary JFORCES control widgets appear, the Master Control widget in the northwest corner of the screen and the map display in the northeast. JFORCES uses the blue label in the center of the Master Control widget to prompt the user to perform an action or notify him of a key simulation event. Initially the user is prompted to select a mode using the system controls. As shown in this picture, when the System Control menubutton is selected a list of options is presented to the user. The principle options that the user will select at this time are:

  1. Start Scenario - this will permit the user to select a run and execute it either interactively or in a batch mode

  2. Mission Planner - This allows the user to create or modify scenarios and change the performance and capabilities of scenario elements

  3. DBA - This is short for Data Base Administration. These functions allow the user to perform analysis on data in the database as well as to perform a number of other database related activities.


Common operations for both standalone analysis and exercise support are described below.


Using JFORCES for Analytic Modeling (All Users Should Read This Section)

Logically the use of the JFORCES model for analysis can be broken down into the following three components:

Presimulation scenario and database setup

Runtime interaction - this is usually just a review of scenario progress in this mode

Post Run Analysis


The overall procedure is to put data in to describe the scenario and players, check the data, run JFORCES, and check the results. Once this is done, the model can be run in a stand-alone mode to populate the database with results for analysis.


There are also a number of helpful command line scripts. The most important one is "kill_all". This command will kill any ongoing simulations running in the background as well as the JFORCES interface. Note that the "Kill MMI" option on the JFORCES interface will not kill background simulations. Click here for an overview of other common command line options.


Presimulation Scenario and Database Setup

This section will outline how to setup the data defining scenarios. The JFORCES interface is dynamically reconfigured to allow the user to define scenario inputs when the user selects the "Mission Planner" mode from the System Controls menubutton on the Master Control widget. A list of known databases and scenarios will be presented to the user. When one is selected the data is read into the system and a menubutton labeled "Scenario Defn" is created in the center bottom of the Master Control widget. The options for creating, reviewing, editing and deleting scenario elements are listed under this menubutton.


JFORCES is largely a data-driven model. This is a two-edged sword; while it makes JFORCES very flexible to a wide variety of applications, it also means that the validity of any run is primarily dependent upon the data put in. For this reason behooves all users to know the contents of their databases.


The JFORCES databases are broken into the following areas:


Control database (usually called adilib). This database contains information on the run parameters of the database. The following is specified in this database:

1) The scenario database to use

2) The specific scenario to run

3) The models to be employed (e.g. whether or not DTED information should be used or whether a spherical-Earth model should be employed).

4) Data files to be used for various applications (e.g. supporting external inputs from stored sensor streams).

For a more complete description of how to specify run controls click here.


Scenario database - There are no "standard" scenario database names at this time and typical installations often maintain multiple scenario databases simultaneously. Each scenario database contains the following data:


Each of these data categories need to be populated before a successful run can be made. It is generally a good idea to review the data in each category before making JFORCES runs.


Additional JFORCES inputs - Additional JFORCES inputs are contained within the directory pointed to by the environmental variable DTA_DIR. Usually this is set to /data. Generally this data is not as volatile as the data in the database and so its not necessary to check it as often, but it's important to check this data if:

  1. The line-of-sight model does not appear to be working

  2. Specific map overlays are unavailable or don't work correctly

  3. Map backgrounds either aren't working or you want to add map images to the library

  4. Assets or groups that are defined in the database aren't being displayed on the map.

  5. It is desired to restart a scenario from a saved checkpoint instead of reloading from the database and running from the beginning.

  6. Data saved from a run is to be added to the database for analysis.


The following categories of data are contained in these files:




locations.dat - This is a list of the locations tied to the "Locations" menubutton on the top of the Map window. New locations (defined in terms of name, central latitude/longitude, and viewing height) can be input into this file and will be available the next time the JFORCES interface is restarted.


At this time it appears all other entries in this directory are unnecessary.






Runtime Interaction

Even though this section describes running JFORCES for generating statistical data, most people will want to watch the simulation execute the first few times to verify that it's running as expected. To run the simulation interactively the user should:

  1. Type "start" in a command window. Some installations have a "JFORCES" icon that will execute this command automatically.

  2. Select "System Controls"->"Start Scenario" from the JFORCES Master Controls.

  3. Click on the button labeled "..." under the "Run Configuration" label. A dropdown will appear providing run configuration options. This widget shows a list of all currently defined run configurations. This is NOT the scenario list. To learn more about run configurations, including how to create one and how to make one run your scenario, click here. Occasionally a fatal error occurs at this point. This fatal error indicates that this database is down. For information on how to fix it click here.

  4. Click on the "Execute" button.

  5. A widget notifying you of the simulation port ID will appear. Occasionally, due to network errors, this widget is slow coming up. If there's more than a 10 second delay before this widget appears you need to adjust your network settings. Click here for help troubleshooting this problem.

There are other options for starting a run. Click here for more details.


After the command to execute a specific run configuration is made the middle menu button on the JFORCES Master Controls command options changes to "Scenario Controls" and additional options are provided to the user under the "System Controls" menubutton. In addition to these options the user can use the map controls in the map interface to focus on areas of interest. The following are the most important controls that the user needs to know about to watch the simulation execute:


Map Controls - These allow the user to pan and zoom the map to points of interest. Click here for a description of the interface.


System Controls - The most important of these controls are:


Clock Controls - This widget permits the user to change the speed of execution of a simulation run. The user can also pause the run or resume its execution from a paused state. Click here for more details.


Monitor Execution - Options under this widget allow the user to monitor the simulation progress and test the interface to the simulation. These options can be very useful when nothing appears to be happening and the user wants to very the simulation is still running. The "Verify Connection" option will be available only after the simulation completes initialization. A message displayed in the central blue area of the Master Control widget will notify the user when simulation initialization is completed. After this point the user will be able to click on "Verify Connection" and a message stating that the simulation is responding will appear in the central blue message area in a few seconds if all is well. There will be a delay if the simulation is busy with an intensive function, such as loading data for analysis. Prior to the completion of simulation execution the easiest way to see if the simulation is running is to select "Sim Monitor". This will provide an echo of the information that the simulation is sending to the logfile. Note: The logfile is created regardless of whether this monitor is created and can be found in the /tmp directory. Informational messages about missing or inconsistent data is stored in this logfile and this file can be very useful in debugging a scenario. But the data must be inspected before another run is started because the file is rewritten every time the simulation restarts.


A more complete description of the System Control options is available here.


Scenario Controls - These controls allow the user to interact with the simulation. For a user setting up batch runs the most important functions are those providing status information. The key status interfaces are:


Umpire Controls->Status Reports->Full Group Status - A listing of the current location, health and status of every group in the scenario will be presented. Frankly, this report is often too long to be useful, so I recommend using the status reports on groups in an area or specific unit status reports instead.


Umpire Controls->Status Reports->Unit Reports in an Area - The user will be prompted to pick two corner points and a list of all units and all assets in this area is provided.


Force A Controls->Force A Status->Group Status - This allows the user to select individual groups from the map and review their current orders, health and status.


Force A Controls->Defensive Controls->Aircraft Control - This interface provides information on the current position, speed and heading for any selected asset (it is not limited to aircraft, though the selection filter for the type of asset being selected can be set as desired in the "Filter" button). Set motion type to "Status" before using this interface if you only want to review an asset's location.


Force A Controls->Force A Status->Subsystem Status - This interface will allow the user to review the current subsystem status of any selected asset. This information includes subsystems on board, whether they're currently operational and on, and current inventory, which changes as some subsystems (e.g. warheads) are used. WARNING - The user is looking at this information through an umpire control widget - this means that if the user changes any of these values (e.g. turning on a jammer or changing the number of AMRAAM missiles on an interceptor) the simulation will pass this to the asset as a command and this value will be changed in the simulation.


Equivalent Force B controls are also available. Force A corresponds to the blue force, Force B to the red force. We intend to phase out references to Forces A & B in the future and refer only to Blue and Red.


The final phase of using the JFORCES model is Data Analysis, described here.


Additional Information for Users Interested In Running JFORCES Interactively

Originally JFORCES was an interactive-only model and many of the interfaces reflect this.