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.
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:
Start Scenario - this will permit the user to select a run and execute it either interactively or in a batch mode
Mission Planner - This allows the user to create or modify scenarios and change the performance and capabilities of scenario elements
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.
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.
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:
Platform Definitions- Permits the user to define the performance and signatures of all platform types (e.g. F-15E or M1A3) that can exist within scenarios in this database. This definition must be created before an asset of this type can be used in a scenario. Users can create new platform definitions, or review, modify and delete existing ones from the "Database Prototyping" interface.
Scenario Asset Definitions - This is the deployment and employment of specific instances of the platform types defined in database prototyping for specific scenarios. This includes initial locations, prescripted routes and missions, and reporting assignments. Most of the Mission Planner is designed to support the interactive definition of scenarios. JFORCES permits the user to specify these items for each asset individually when required. A number of tools (e.g. The SIOP Planner) are provided to simplify scenario generation by using automated rules. The user can use the results of these tools to quickly define large scenarios or can use the results for "roughing in" the data and then tailor specifications for any asset individually through the specific asset editor in the mission planner.
Group Definitions - This provides organizational information for the groups. At a minimum the list of assets belonging to groups is specified (when appropriate) as well as a hierarchical specification of group reporting structure. Additionally, missions (e.g. prescripted ground attacks or reconnassance) can be specified. Also postures can be defined. These posture are defined in JFORCES as geometric deployments of assets and subgroups within a group that the group should adopt under specified conditions and orders.
Environmental Definition - This includes all non-scenario element items including weather, terrorist attacks, prescripted intel inputs and area foliage/clutter.
Statistical Data Collection Parameters - This includes the data to be kept, which elements it's to be kept for, and how often data is to be collected for non-event based data collection.
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:
The line-of-sight model does not appear to be working
Specific map overlays are unavailable or don't work correctly
Map backgrounds either aren't working or you want to add map images to the library
Assets or groups that are defined in the database aren't being displayed on the map.
It is desired to restart a scenario from a saved checkpoint instead of reloading from the database and running from the beginning.
Data saved from a run is to be added to the database for analysis.
The following categories of data are contained in these files:
Bitmaps for Assets and Groups - Usually these are in /data/bitmaps, but when in doubt type "echo $BITMAP_DIR" at a command line prompt - this will give you the current setting for this directory. The important thing here is that the bitmap file specified in the icon_map database table in the scenario database is not here the icon will not be drawn. This means that regardless of how many tanks you think should be located in an area you won't see them if you're not tied to a file in that actually exists in this directory. The simulation might well agree with you that these tanks are there and killing things even without this display information.
DTED (Digital terrain elevation data) - this data should be in the $DTED_DIR directory (usually /data/DTED). The information is organized according to the convention used on the DTED CD. If these directories are not populated JFORCES sill net be able to used DTED information on any calculations.
Graphics information - the following data is kept in the $GRAPHICS_DIR directory (usually /data/graphics):
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.
Data driven overlays. These are data files specifying either sets of lines or icons to be drawn over the map upon user request. Click here to review interface. Basically these are just files named either overlay_(id) for lines or overlayicon_(id) for icons. The ID is the overlay id and must be between 1 and 999. Thus overlay_33 contains line information for overlay 33. There's a GUI provided to support the creation, editing and deletion of these overlays.
Predefined map views. The file $GRAPHICS_DIR/locations.dat contains information on predefined map views. To add, modify or delete predefined map views edit this file. It consists of one line per predefined location with the center latitude, center longitude, altitude (in km) for the eyeball, and a character string in quotes providing a quick description of the view. Currently there's no GUI for editing this file.
Map images - These are the map backgrounds to be drawn on the maps when the map option is selected either in the Data Analysis detection and engagement profiles. These can be .gif or .jpg files.
Hotstart files - These are the memory images of this simulation stored when the user specifies checkpoint. Subsequent runs can be restarted from these files instead of starting the run from the beginning. This is done though setting the replay option of the run configuration. Click here to find out how.
Logfiles - By convention this is where the results for any run go. Files are loaded by the execution of a scenario and reflect the events and outcomes of that scenario. The data needs to be loaded into the database for data analysis. Typically this is either done thought the batch script itself or the GUI interface.
Maps support- This includes the map files to support the TCL interface (found in the $MAP_DIR directory, typically /data/maps/gifs). Map support data can also be found in the $DTA_DIR/VMAP directory (typically /data/VMAP). This directory contains all vector map information for display support including the world-wide definitions of political boundaries, coasts, rivers and roads.
Parser support - this includes definitional files for the field definitions for messages from or to external sources (e.g. the ACMI interface. This is used only for the ACMI and PCDS interfaces and is required only when linking to these systems dynamically.
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:
Type "start" in a command window. Some installations have a "JFORCES" icon that will execute this command automatically.
Select "System Controls"->"Start Scenario" from the JFORCES Master Controls.
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.
Click on the "Execute" button.
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.
Originally JFORCES was an interactive-only model and many of the interfaces reflect this.