WSF_GUIDANCE_COMPUTER

Derives From: WSF_SCRIPT_PROCESSOR

Script Class: WsfGuidanceComputer

processor WSF_GUIDANCE_COMPUTER
processor <name> WSF_GUIDANCE_COMPUTER

   ... WSF_SCRIPT_PROCESSOR Commands ...

   # Global Commands

   show_status
   show_diagnostics
   show_commands
   show_evaluations
   guide_to_truth ...

   program ... end_program

   phase <phase-name-1>

      # General Subcommands

      guidance_delay ...
      on_entry ... end_on_entry
      on_exit ... end_on_exit
      on_update ... end_on_update

      # Aimpoint Selection Subcommands

      guidance_target ... | guide_to_truth
      allow_route_following ...
      aimpoint_altitude_offset ...
      aimpoint_azimuth_offset ...
      aimpoint_range_offset ...
      aimpoint_evaluation_interval ...

      # Program Selection Commands

      use_program ...
      program ... end_program

      # Navigation Subcommands

      proportional_navigation_gain ...
      proportional_navigation_limit_angle ...
      proportional_navigation_method ...
      velocity_pursuit_gain ...

      # Trajectory Shaping Subcommands

      g_bias ...
      lateral_g_bias ...
      commanded_altitude ...
      commanded_azimuth_offset ...
      commanded_flight_path_angle ...
      commanded_mach ...
      commanded_speed ...
      commanded_throttle ...

      # Limiting Subcommands

      maximum_commanded_g ...
      maximum_ascent_rate ...
      maximum_descent_rate ...
      maximum_pitch_angle ...
      pitch_change_gain ...

      # Phase Changing Subcommands

      next_phase ...

   end_phase

   phase <phase-name-n>
   end_phase

   # Script Interface

   script_variables ... end_script_variables
   script ... end_script
   on_initialize ... end_on_initialize
   on_initialize2 ... end_on_initialize2
   on_update ... end_on_update
   ... Other Script Commands ...

end_processor

Overview

WSF_GUIDANCE_COMPUTER is a processor that typically resides on a weapon and provides the guidance for a weapon whose mover is typically of type WSF_GUIDED_MOVER. It uses the track provided through CurrentTargetTrack to represent the target to be pursued. The mover invokes this processor to request guidance updates. The processor computes the desired guidance and supplies them back to the mover.

Guidance Programs

Starting with AFSIM 2.2 an additional form of guidance is provided through the use of ‘programs’. Programs several advantages over the existing guidance methods:

  • They don’t have any hidden behavior. With the old system you had to explicitly disable things proportional and pursuit guidance and gravity bias if you didn’t want them. With the new system you don’t get them unless you ask for them.

  • Programs can span phases. You can define a program and use it such that it will retain its state across phase changes.

  • Multiple programs can be executed in one phase to get a combined effect.

  • The program architecture is extensible. New program types can be easily added. If a new guidance model is needed for a particular application it can be compiled and included like any other model.

The initial set of programs provided in AFSIM 2.2 were mainly to implement launch-to-orbit capabilities and some advanced ballistic missile needs. Thus, it will not initially serve all needs.

The use of guidance programs or the legacy guidance is selected by phase. If you use or define a program within a phase then only programs will be used. If you do not use or define a program within a phase then you will get the legacy behavior. Each phase can be different - one can use programs and another can use legacy guidance.

Global Commands

Note

The update_interval command should NOT be specified for this processor. It is called as required from the mover.

show_status

Specifies that information should be written to standard output whenever a phase or stage transition occurs.

show_diagnostics

Specifies that diagnostic information from guidance programs should be written to standard output. This is typically used when attempting to tune the guidance computer for generating orbital launch computers with weapon_tools.

Note

This introduces some extra overhead and should be used only during tuning.

show_commands

Specifies that calls from script commands should be written to standard output.

show_evaluations

Specifies that phase change rule evaluations should be written to standard output.

guide_to_truth <boolean-value>

Specifies if the guidance target should be the location specified in the current target track (false), or should be the true location of the platform specified in the current target track (true).

This command exists both here and in the ‘phase’ block. This form specifies the default for a phase if the command was not specified in the phase block.

Default: false

phase <phase-name> phase-commands end_phase

The ‘phase’ block is used to define the guidance for the various phases of flight and the rules to transition between phases.

The format of a phase block is:

phase <phase-name>
   ... phase commands ...
end_phase

The ‘phase’ block should be defined for each unique phase required. The first ‘phase’ block defines the phase to be used then the weapon is fired.

edit phase <phase-name> phase-commands end_phase

This command is typically used when creating a new guidance computer type by deriving from another guidance computer type.

For example:

processor DEMO_GUIDANCE WSF_GUIDANCE_COMPUTER
   guide_to_truth true
   phase TERMINAL
      ...
   end_phase
end_processor

processor DEMO_GUIDANCE_MOD DEMO_GUIDANCE
   edit phase TERMINAL
      guide_to_truth false      # Overrides the base class value
   end_phase
end_processor
program <name> <type> … end_program

Defines a guidance program with the specified <name> using the predefine guidance program <type> (See Guidance Program Types.) The program can then be selected for use in a phase by specifying use_program <name>.

Note: A program must appear in the input prior to the use_program that references the program.

For example:

program RESET_ATTITUDE ATTITUDE_PROGRAM
   reset
   yaw_rate 5 deg/sec
   pitch_rate 5 deg/sec
   roll_rate 5 deg/sec
end_program
...
phase BEGIN_DESCENT
   use_program RESET_ATTITUDE
   next_phase DESCENT when program RESET_ATTITUDE complete
end_phase
...
phase DESCENT
   ...
end_phase

Phase Commands

The subcommands in a phase block can be broken in the following broad categories:

General Subcommands

guidance_delay <time-value>

Specifies the elapsed time since the start of the phase when guidance commands should start being computed. This is useful during lift-off and other phases where pursuit of the target is not desirable.

Default: 0 seconds (start computing guidance commands upon entry into the phase)

Script Command: WsfGuidanceComputer.SetGuidanceDelay.

on_entry … end_on_entry
on_exit … end_on_exit

These commands define scripts to be executed when entering and exiting the phase.

on_entry
   ... script commands ...
end_on_entry

on_exit
   ... script commands ...
end_on_exit
on_update …

Define a script to be executed on every phase update.

on_update
   ... script commands ...
end_on_update

This script is generally only used when:

  • The values of guidance commands must be varied during a phase

  • A phase change condition needs to be evaluated that cannot be accomplished with a next_phase command.

Note

Do not use this indiscriminately as it is executed at every integration time step of the mover. Attempt to keep the script as simple as possible

Aimpoint Selection Subcommands

guidance_target [ predicted_intercept | perception | truth ]
guide_to_truth <boolean-value>

Overrides the top-level guide_to_truth command for the current phase. This is expanded to include the options:

  • predicted_intercept - Guidance computations are based on the predicted intercept location provided by the launch computer. No consideration is given to the actual location of the target. This is often used during the initial phases when prediction of an intercept point based on CURRENT conditions is unreliable.

  • perception - Guidance computations are made based on the perception of the target as provided by the current target track. Because the track may have sensor errors, the weapon may be directed to a location other that where the target is located. (This is the same as guide_to_truth false).

  • truth - Guidance computations are made based on the actual location of the target. (This is the same as guide_to_truth true).

  • default - Use value from the global guide_to_truth command.

The guide_to_truth form is an older form. See the above for description for the equivalent values.

Default: default (Use the value of the top-level guide_to_truth command.)

Script Command: WsfGuidanceComputer.SetGuidanceTarget.

aimpoint_altitude_offset <length-value>

Modify the aimpoint to be above or below the perceived target location. This is typically used to create an air burst.

Default: 0 meters (no altitude offset)

Script Command: WsfGuidanceComputer.SetAimpointAltitudeOffset.

aimpoint_azimuth_offset <angle-value> [ left | right | either ]
aimpoint_range_offset <length-value>

These commands provide a method to produce an aimpoint that is laterally offset from the perceived target location. This is typically used to meet some tactical requirement.

aimpoint_azimuth_offset is the desired relative bearing to the target (‘angle off the nose’) when the ground range to the target is equal to the value specified by aimpoint_range_offset. The left, right and either modifiers for aimpoint_azimuth_offset indicates where the target should be located with respect to the weapon. either will place the offset so as to minimize the heading change of the weapon.

These commands may also be combined with aimpoint_altitude_offset.

Following is a brief example of how to use this command:

phase PHASE_X
   ...
   aimpoint_altitude_offset     10000 m
   aimpoint_azimuth_offset      45 deg either
   aimpoint_range_offset        10 nm

   next_phase PHASE_Y when target_azimuth > 45 deg
end_phase

In this example the aimpoint will be created such that when the weapon reaches the point, the target will be 10 nautical miles away at relative bearing of 45 degrees and the weapon will be at an altitude of 10000 m above that of the target. The comparison value in next_phase command for target_azimuth should be same value of the aimpoint_azimuth_offset.

Default: No aimpoint offsets.

Script Command: WsfGuidanceComputer.SetAimpointAzimuthOffset and WsfGuidanceComputer.SetAimpointRangeOffset.

Note

If either aimpoint_azimuth_offset or aimpoint_range_offset is non-zero then both must be non-zero.

Note

The aimpoint offset will not be applied while following a route.

Note

This is typically only used for static or slowly moving surface targets. It has not been tested for air targets.

aimpoint_evaluation_interval <time-value>

Controls how often a new aimpoint is computed when using aimpoint_azimuth_offset and aimpoint_range_offset. This is a fairly time-consuming operation that does not need to be performed on every call to the guidance computer.

Default: 5 seconds.

Script Command: WsfGuidanceComputer.SetAimpointEvaluationInterval

allow_route_following <boolean-value>

If true, the computer will follow a route if it has been provided to the associated mover. If the mover does not have a route then this command has no effect. Conventional target point selection will resume at the end of the route.

The command ‘next_phase <phase-name> at_end_of_route’ may be used to switch to a different phase when the end of the route is encountered.

Default: false

Script Command: WsfGuidanceComputer.SetAllowRouteFollowing

Program Selection Subcommands

Specify the guidance programs that will be used within the phase. One or more programs may be selected or defined and are called in order of appearance.

Note that the many of the programs have commands that have the same purpose as defined in Navigation Subcommands and Trajectory Shaping Subcommands below. In such cases the command can be defined in either the program definition or in the phase. If it is defined in the program then it CANNOT be overridden by script commands.

Also note that some of the Limiting Subcommands are overridden by the programs.

use_program <name>

Specifies that the named program defined in a program block outside of the phase will be used. It is useful to define a program if it is going to be used in multiple phases.

program <type> end_program

Defines a program of the specified <type> and uses it for the current phase. <type> must be one of the predefined guidance program types (see Guidance Program Types.)

Trajectory Shaping Subcommands

The trajectory shaping subcommands are used to modify the computed navigation commands to shape the trajectory.

g_bias <real-value>

Specifies the bias factor used to overcome gravity. This is typically used during mid-course to prevent the trajectory from sagging. If zero is specified then gravity bias will not be applied.

Default: 1.0

Script Command: WsfGuidanceComputer.SetGeeBias.

lateral_g_bias <real-value>

Specifies the bias factor used skew the horizontal component of the trajectory in a particular direction. If zero is specified then gravity bias will not be applied.

Default: 0.0

Script Command: WsfGuidanceComputer.SetLateralGeeBias.

commanded_altitude <length-value> [ msl | agl ]

Specifies a commanded altitude. Typically used to climb or dive to a cruise altitude and hold the altitude. The altitude reference tag (’msl’, or ‘above mean sea level’; ‘agl’, or ‘above ground level’) may be omitted, in which case ‘msl’ is assumed.

Specifying an altitude reference of ‘agl’ is a crude mechanism for implementing terrain-following. When ‘agl’ is specified the mover will enforce an additional constraint that it always stays above the ground. However, no look-ahead is performed (it only checks the height above the terrain directly under the platform), so it is possible that the vehicle may make very abrupt changes if the terrain rises rapidly.

Default: No commanded altitude

Script Command: WsfGuidanceComputer.SetCommandedAltitude and WsfGuidanceComputer.SetCommandedAltitudeAGL.

commanded_azimuth_offset <angle-value>

Specifies the azimuth angle to the target that should be maintained. The angle is defined to be the angle in the local horizontal plane between the weapon velocity vector and the line-of-sight vector from the weapon to the target. (This is consistent with the ‘target_azimuth’ conditional tests in the next_phase command.)

Default: No commanded azimuth offset angle.

Script Command: WsfGuidanceComputer.SetCommandedAzimuthOffset

commanded_flight_path_angle <angle-value>
commanded_flight_path_angle from_launch_computer

Specifies a commanded flight path angle. If from_launch_computer is specified then the value produced by the launch computer will be used (if present).

This is typically used to produce lofted ballistic trajectories.

Default: No commanded flight path angle.

Script Command: WsfGuidanceComputer.SetCommandedFlightPathAngle

commanded_mach <real-value>
commanded_speed <speed-value>

Specifies the commanded speed/mach to be used during this phase. Typically used for cruise.

Default: No commanded speed or Mach.

Script Command: WsfGuidanceComputer.SetCommandedSpeed and WsfGuidanceComputer.SetCommandedMach.

Note

Not all movers support this capability.

Note

Fuel utilization may not be properly modeled when using this command.

commanded_throttle <real-value>

Specifies a throttle factor in the range [0..1] that overrides and throttle specification in the mover.

This is not typically used as a command. It exists primarily to allow script calls to alter the throttle.

Default: No commanded throttle.

Script Command: WsfGuidanceComputer.SetCommandedThrottle

Limiting Subcommands

maximum_commanded_g <acceleration-value>

Specifies the magnitude of the maximum acceleration that can be commanded.

Default: 25.0 g

Script Command: WsfGuidanceComputer.SetMaximumCommandedGees.

maximum_ascent_rate <speed-value>
maximum_descent_rate <speed-value>

Specifies the maximum rate of ascent or descent to be used to reach the commanded_altitude.

Note

A value of 0 specifies no constraint on ascent/descent rate.

Script Command: WsfGuidanceComputer.SetMaximumAscentRate and WsfGuidanceComputer.SetMaximumDescentRate.

Default: 0, no constraint

maximum_pitch_angle <angle-value>

Specifies the absolute value of the maximum flight path angle that may be used to ascend or descend to the commanded_altitude.

Default: 70.0 degrees

Script Command: WsfGuidanceComputer.SetMaximumPitchAngle

pitch_change_gain <real-value>

Specifies the gain factor for changing the pitch angle when trying to achieve the commanded_altitude.

Default: 1.0

Script Command: WsfGuidanceComputer.SetPitchChangeGain

Phase Changing Subcommands

next_phase <phase-name> [if | when] <event>
next_phase <phase-name> [if | when] <variable> [<operator> <reference-value>]

The next_phase command defines a condition under which a phase transition occurs. A phase block may have multiple next_phase commands to define a number of conditions that might trigger a phase change. The next_phase commands are evaluated on each guidance update and are evaluated in the order specified.

The first form of the command is used for detecting events.

end_of_route

The mover has indicated that the last point in a route has been passed (if the mover was following waypoints).

boost_complete

The mover has indicated that it is no longer boosting. This typically means that all thrust-producing stages have been used.

stage_ignition

The mover has indicated the current stage has ignited.

stage_burnout

The mover has indicated the current stage has burned-out.

stage_separation

The mover has indicated the current stage has separated.

on_commanded_flight_path_angle

The flight path angle of the weapon has reached the loft angle commanded by the launch computer (if provided)

sensor_track_initiated

The local on-board sensor has established autonomous track on the target.

program <program-name> complete

The specified program has specified completion. Not all programs have a condition where they define completion. Such programs are continuous and will run until the end of the phase.

The second form of the command is used for detecting when the <variable> achieves a certain relationship with the <reference-value>.

<reference-value> can either be a constant value of the form:

*<real-value>* *<units>*

Or a variable value of the form:

/variable *<variable-name>*
variable *<variable-name>* *<units>*

The last two forms indicate the <reference-value> is to be gotten from a double script variable. The variable must be defined in a script_variables block that occurs before the command that references the variable and it must not appear with a ‘phase’ block.

If the variable is a dimensional quantity then the value of the variable must be in the proper units:

  • Standard WSF units if ‘/variable’ is specified. The standard units are indicated in the ‘Description’ column below.

  • In the units specified <units> if ‘variable’ is specified.

When using the variable form, <variable-name> must be the name of an double script variable and <units> represents the units of the data stored in the variable. The variable must be defined within a script_variables block in the computer that appears before the reference.

Valid <operators> are <;, <;=, ==, !=, >;=, or >;. Valid <variables> are:

Variable

Ref-Variable-Type

Description

phase_time

<time-value>

The time (seconds) that has elapsed since the start of the phase.

flight_time

<time-value>

The time (seconds) that has elapsed since the platform was launched.

altitude

<length-value>

The current altitude (meters) of the weapon.

speed

<speed-value>

The current speed (meters/second) of the weapon.

vertical_speed

<speed-value>

The current vertical speed (meters/second) of the weapon.

flight_path_angle

<angle-value>

The current flight path angle (radians) of the weapon.

dynamic_pressure

<pressure-value>

The current dynamic pressure (Newtons/meter2) on the weapon.

target_altitude

<length-value>

The current altitude (meters) of the target.

target_speed

<speed-value>

The current speed (meters/second) of the target.

target_flight_path_angle

<angle-value>

The current flight path angle (radians) of the target.

closing_speed

<speed-value>

The closing speed (meters/second) between the weapon and the target. Positive values are closing.

time_to_intercept

<time-value>

The approximated predicted time (seconds) until the weapon and target intercept.

range_to_intercept

<length-value>

The approximate distance (meters) to the predicted point of intercept between weapon and the target.

target_slant_range

<length-value>

The slant range (meters) between the weapon and the target.

target_ground_range

<length-value>

The approximate ground range (meters) between the weapon and the target.

target_elevation

<angle-value>

The angle (radians) above or below the local horizontal plane (tangent to the Earth’s surface) and the line-of-sight vector from the weapon to the target. A positive value means the target is above the local horizontal plane while a negative value indicates it is below.

target_azimuth

<angle-value>

The angle (radians) in the local horizontal plane (tangent to the Earth’s surface) between the horizontal components of the weapon velocity vector and line-of-sight vector from the weapon to the target. This value is always positive.

los_target_elevation

<angle-value>

The elevation angle (radians) of the target with respect to the current orientation of the weapon.

los_target_azimuth

<angle-value>

The azimuth angle (radians) of the target with respect to the current orientation of the weapon. This value is always positive.

los_target_angle

<angle-value>

The 3D angle (radians) of the target with respect to the current orientation of the weapon.

Examples for using events:

next_phase PHASE2 if end_of_route
next_phase PHASE2 if boost_complete
next_phase PHASE2 if stage_ignition
next_phase PHASE2 if stage_burnout
next_phase PHASE2 if stage_separation
next_phase PHASE2 when on_commanded_flight_path_angle
next_phase PHASE2 when sensor_track_initiated
next_phase PHASE2 when FLIGHT_PATH_ANGLE_PROGRAM complete

Examples for using a constant for reference-value:

next_phase PHASE2 when phase_time > 200 sec
next_phase PHASE2 when flight_time > 25 sec
next_phase PHASE2 when altitude > 10000 m
next_phase PHASE2 when speed > 500 m/s
next_phase PHASE2 when vertical_speed > 100 m/s
next_phase PHASE2 when target_altitude > 10000 m
next_phase PHASE2 when target_speed    > 500 m/s
next_phase PHASE2 when closing_speed > 1000 m/s
next_phase PHASE2 when time_to_intercept < 1 sec
next_phase PHASE2 when range_to_intercept < 1 m
next_phase PHASE2 when target_slant_range < 1 m
next_phase PHASE2 when target_ground_range < 1 m
next_phase PHASE2 when target_azimuth > 179 deg
next_phase PHASE2 when target_elevation > 89 deg
next_phase PHASE2 when los_target_azimuth > 179 deg
next_phase PHASE2 when los_target_elevation > 89 deg
next_phase PHASE2 when los_target_angle > 179 deg
next_phase PHASE2 when altitude > 10 km

Examples when using a script variable for a reference-value:

# In this form the value of TARGET_ALTITUDE should be in meters.
next_phase PHASE2 when altitude > /variable TARGET_ALTITUDE
# In this form the value of TARGET_ALTITUDE should be in kilometers (km).
next_phase PHASE2 when altitude > variable TARGET_ALTITUDE km

The script variable TARGET_ALTITUDE should have been defined in a ‘script_variables’ block and assigned a value in one of the script blocks exposed by this processor.

Script Interface

WSF_GUIDANCE_COMPUTER utilizes the capabilities of the Common Script Interface and WSF_SCRIPT_PROCESSOR, and supports the additional script methods defined in WsfGuidanceComputer.