engage

Overview

ENGAGE is a WSF application that is used to evaluate the effectiveness of surface weapon (and conversely, the vulnerability of the target).

Command Line

engage file <sub>1</sub> [ file<sub>2</sub> … file<sub>n</sub> ]

Where the arguments are the names of files that contain:

  • Run and output_rate input block(s) that define the configurations and outputs.

  • Definitions for weapon, target, launcher, and optional sensor(s) required for the function to be performed.

Script Methods

WsfSimulation Methods

Typical usage is to sort the different runs along with target, site and monte-carlo repetition numbers when writing out to screen or to file, (e.g. observer output files).

write_ln("Run Number: ", WsfSimulation.RunNumber(),
         " Target Number: ", WsfSimulation.TargetNumber(),
         " SiteNumber: ", WsfSimulation.SiteNumber(),
         " RepNumber: ", WsfSimulation.Repetition());
int RunNumber()

Returns the current run number.

WsfSimulation.RunNumber()
int TargetNumber()

Returns the current target number for the run.

WsfSimulation.TargetNumber()
int SiteNumber()

Returns the current site number for the run.

WsfSimulation.SiteNumber()
int RepetitionNumber()

Returns the current mote-carlo repetition number for the run.

WsfSimulation.RepetitionNumber()

Commands

thread_count <integer>

Specifies the number of threads in the thread pools to be used to complete the SWEET tasks in parallel.

run … end_run
run
   ... Run Commands ...
end_run

Note

Multiple run blocks may be input into a single executable for serial processing of each run block.

output_rate <rate-table-name> … end_output_rate
output_rate <rate-table-name>
   ... Output Rate Commands ...
end_output_rate

Specifies an output_rate configuration by name (<rate-name>) to be used with the output block of the run input block command. Multiples blocks with different names may be defined.

Note

‘’default’’ as the <rate-name> will setup a default rate table used by all output blocks not specifying and output_rate to be used explicitly.

output_template <template-name> … end_output_template
output_template <template-name>
   ... Output Template Commands ...
end_output_template

Specifies an output_template configuration by name (<template-name>) to be used with the output block of the run input block command. Multiples blocks with different names may be defined.

Run Commands

center_location <latitude-value> <longitude-value>

Specifies the center location of this run.

Default 0.0n 0.0e

event_output_file_base_name <string>

This value, along with the suffix ‘.evt’, forms the filename to which the results will be written. If a values is not specified then the event output is not written.

Note

The event_output block will also need be input for this functionality to output properly.

Default not specified

perform_flyouts <boolean-value>

Specifies if flyouts should be performed.

Default true

record_file_base_name <string>

This value, along with the suffix ‘.rep’, forms the filename to which the results will be written. If a values is not specified then the record file is not written.

Default not specified

repetition_count <integer>

Specifies the number of monte-carlo repetitions to run for this configuration.

Default 1

Site Configuration Commands

launcher_type <platform-type-name>

Specifies the launcher platform type name for the run.

Default LAUNCHER_TYPE

tracker_type <platform-type-name>

Specifies the tracker platform type name for the run.

Default TRACKER_TYPE

sites … end_sites

Specifies a list of site using the following commands multiple times:

xyz <length-value> <length-value> <length-value>

Specifies the site’s x, y, z location.

heading <angles-value>

Specifies the site’s heading.

Default 90.0 degrees

speed <speed-value>

Specifies the site’s speed in the direction of the heading.

Default 0.0 m/s

site_grid … end_site_grid

Specifies a site grid configuration using the following commands:

down_range from <length-value> to <length-value> by <length-value>

Specifies the site grid’s downrange start, end and step respectively.

cross_range from <length-value> to <length-value> by <length-value>

Specifies the site grid’s crossrange start, end and step respectively.

target_speed <speed-value>

Specifies the target’s speed.

target_altitude <length-value>

Specifies the target’s altitude.

Target Configuration Commands

target_type <platform-type-name>

Specifies the target platform type name for the run.

Default TARGET_TYPE

use_target_path

Specifies to use the targets defined flight path.

Default Use default flight characteristics

target_grid … end_target_grid

Specifies a target grid configuration using the following commands:

down_range from <length-value> to <length-value> by <length-value>

Specifies the target grid’s downrange start, end and step respectively.

cross_range from <length-value> to <length-value> by <length-value>

Specifies the target grid’s crossrange start, end and step respectively.

altitude <length-value>

Specifies the target’s altitude.

speed <speed-value>

Specifies the target’s speed.

simple_path … end_simple_path

Specifies a target simple path configuration using the following commands:

x <length-value>

Specifies the target path start x position.

Default 10000 m

y <length-value>

Specifies the target path start y position.

Default 0 m

z <length-value>

Specifies the target path start z position.

Default 5000 m

heading <length-value>

Specifies the target path heading.

Default 270 degrees

speed <speed-value>

Specifies the target path speed.

Default 134 m/s

flight_path … end_flight_path

Specifies a flight path using the following input format:

# (Time) (X, Y, Z Position) (X, Y, Z Velocity) (Pitch) (Roll) (Yaw) <time-value>

<(x,y,z)> <length-unit> <(Vx, Vy, Vz)> <speed-unit> <angle-value> <angle-value> <angle-value>

flight_path
   # (Time) (X Y Z Position) (X Y Z Velocity) (Pitch) (Roll) (Yaw)
    0.0 sec    0.0    50.0 100.0 m 200.0   0.0 0.0 m/sec 0.0 0.0 90.0 deg
   10.0 sec 2000.0    50.0 100.0 m 200.0   0.0 0.0 m/sec 0.0 0.0 90.0 deg
   10.1 sec 2020.0    70.0 100.0 m   0.0 200.0 0.0 m/sec 0.0 0.0  0.0 deg
  110.1 sec 2020.0 20070.0 100.0 m   0.0 200.0 0.0 m/sec 0.0 0.0  0.0 deg
end_flight_path
flight_route … end_flight_route

Specifies a flight route using the following input format:

(X Y Z Position) (Speed)

<(x,y,z)> <length-unit> <speed-value>

flight_route
   # (X, Y, Z Position) (Speed)
   0.0        0.0 100.0 m 200.0 m/sec
   2000.0     0.0 100.0 m 200.0 m/sec
   2020.0    20.0 100.0 m 200.0 m/sec
   2020.0 20020.0 100.0 m 200.0 m/sec
end_flight_route

Note

The use of use_target_path, target_grid, simple_path, flight_path and flight_route are mutually exclusive and the last one in the input processing stack is used.

Output Commands

output … end_output

Specifies the output data that is to be output. The output block can be defined multiple times within the run input block to tailor output to user needs. The following commands are available:

file <file-name>

Specifies the output filename to output the data of the run to.

phase [<all | acquiring | tracking | flying>]

Specifies the phase of the run in which to output data per the given phases above.

event_output <boolean-value>

Specifies to output event data.

summary_output <boolean-value>

Specifies to output run summary data.

rate_table_name <rate-table-name>

Specifies the rate table to use by name, as specified by output_rate command.

items .. end_items

Specifies the items in which to be output and format of those items per the following format:

variable <variable-name> units <variable-units> format <formatting-value>

<variable-name>

Specifies the variable name to be output. Valid values are specified by category are:

  • time, weapon_flight_time

  • target_x, target_y, target_z

  • target_vx, target_vy, target_vz

  • target_ax, target_ay, target_az

  • weapon_x, weapon_y, weapon_z

  • weapon_vx, weapon_vy, weapon_vz

  • weapon_ax, weapon_ay, weapon_az

  • weapon_speed, weapon_mach, weapon_gee_force

  • weapon_to_target_range

<variable-units>

Specifies the units for the <variable-name> entered to be output. Valid units are checked based on variable name.

<formatting-value>

Specifies the formatting in the string syntax following the ANSI C standard.

items
   variable weapon_flight_time format "%.2f"
   variable target_x units km format " %7.3f"
   variable target_y units km format " %7.3f"
   variable target_z units m format " %7.1f"
   variable weapon_x units km format " %7.3f"
   variable weapon_y units km format " %7.3f"
   variable weapon_z units m format " %7.1f"
   variable weapon_to_target_range units m format " %7.1f"
end_items
events .. end_events

Specifies the events that are to be enable or disables per the following commands:

events
   disable [ <event-name> | all ]
   enable [ <event-name> | all ]
end_events
disable [ <event-name> | all ]
enable [ <event-name> | all ]

Specifies the names of the events to be included or excluded in the event log. These commands are typically specified multiple times to select the events of interest. By default all events start out as being disabled. The commands are processed in order of appearance with each successive command selecting or deselecting events as appropriate.

Note

Be careful about using enable all. This can generate a lot of output and the addition of new events in the future could result in enormous amounts of output.

The valid values for event-name are as follows:

Output Rate Commands

time <time>

Specifies the time at which the output will be written.

Default 0.0 sec

period <time>

Specifies the period in which to output the data for the specified output.

Default 0.5 secs

Output Template Commands

TBD

Pk Table Generation Commands

enable_Pk_table_generation <boolean-value>

Enables the generation of Pk tables for the associated run. Note that Pk table generation is only viable with a site grid, and will effectively be disabled for a target grid regardless of this value.

Default false

Pk_table_target_type <string>

Sets the name of the target when generating the Pk table directory hierarchy and table headers.

Default “DEFAULT”

Pk_table_site_type <string>

Sets the name of the site when generating the Pk table directory hierarchy and table headers.

Default “DEFAULT

Pk_table_output_directory <string>

The path location to output the generated Pk table data hierarchy

Default “.”

Pk_output_length_units <length-value>

Converts all output values to use this unit for Pk table generation and directory hierarchy.

Default “m”

Pk_output_speed_units <speed-value>

Converts all output speed values to use this unit for Pk table generation and directory hierarchy.

Default “m/s”

enable_Pk_table_periodic_flush <boolean-value>

Instead of writing all Pk table data when generation is complete, data may be output when all data points associated with an target altitude has completed processing. This allows the possibility of retaining partial Pk data during very long generation routines in the case of an aborted or interrupted process. This will have no effect on the output process unless multiple altitude values are utilized.

Default false