STK Astrogator Plugin Points

STK Astrogator provides the following plugin points:

For definitions of certain terms used in describing inputs and outputs, see Parameter Definitions.

Additional plugin points utilizing Microsoft COM technologies are available for Astrogator. These plugin points include HPOP Force Model plugins, Search Profile plugins, Engine Model plugins, and Attitude Controller plugins. For information on developing and using COM-based plugin scripts, see the COM-based Engine Plugins topic in the STK Programming Interface Helpselect Programming Interface Help in the STK Help menu tab and go to Select the Right Technology > Extend AGI Products > Extend the Engine > COM Based Engine Plugins. Examples of these plugins in several programming languages are located under CodeSamples\Extend in the STK install directory.

Custom functions

Many of the Astrogator plugin points are implemented using Custom Functions. A Custom Function is an Astrogator Component in the Component Browser that calls a script function defined in a file. There are three types of Custom Functions: MATLAB, VBScript, and Python. A Custom Function has only one attribute: the filename containing the function to be called. Each time a Custom Function is initialized, STK checks the timestamp of the file. If the file has been edited since its last loading, then it is automatically reloaded; otherwise, reloading is unnecessary and is not performed.

For more information, see Scripting Environments.

Calculation objects

Calc Objects can utilize scripting through the use of:

  • Inline functions
  • Custom Functions

You can find each of these types in the Scripts folder under the Astrogator Components > Calculation Objects folder in the Component Browser. The Component Browser is available from the Utilities menu.

Inline functions

You can use inline functions for very simple computations that are not currently available as Calculation Objects in the Component Browser. They have three attributes:

Attributes of Inline Functions

Attribute Description
CalcArguments A list of Calculation Objects that are inputs to the functions
InlineFunc The body of the function that uses the inputs to compute one double value
UnitDimension The dimension that the resulting value is declared to have

There are three types of inline script functions available: MATLAB, VBScript, and JavaScript. When you use an inline Calculation Object, STK creates a function with the inputs listed in CalcArguments, returning the value computed by the InlineFunc, with a name derived from the CalculationObject name itself.

Example:

     CalcObject Name:        Incl cos Raan
     CalcArguments:          Inclination, RAAN
     InlineFunc:             Inclination*cos(RAAN)
     UnitDimension:          AngleUnit

In this example, STK creates an inline function named CalcObject_Incl_cos_Raan, with Inclination and RAAN as inputs. The InlineFunc expression must use the correct syntax of the scripting language, as follows:

The MATLAB Calculation Object uses the MATLAB inline function to define the function:

CalcObject_Incl_cos_Raan  = inline('Inclination*cos(RAAN)', 'Inclination',
     'RAAN');

The VBScript Calculation Object creates the function:

Function CalcObject_Incl_cos_Raan (Inclination, RAAN)
       Dim value
       value = Inclination*cos(RAAN)
       CalcObject_Incl_cos_Raan  =  value
End Function

The JavaScript Calculation Object creates the function:

function CalcObject_Incl_cos_Raan (Inclination, RAAN)
{
      return eval(“Inclination*cos(RAAN)”);
}

Because the name of the Calculation Object is used in the name of the function being defined, it must be a valid function name. Spaces in the name are allowed because STK will substitute underscores (i.e., '_'); MATLAB and VBScript each allow underscores in function names. However, symbols such as ( or * are not allowed.

Custom Function Calc Objects

Calculation Objects based upon Custom Functions are available for use with computations that are lengthy or involved. Unlike the inline functions, Custom Function Calc Objects require you to write a script stored in a file. See Custom Functions.

Custom Function Calc Objects have two entry points that you can use. Use of any Entry Point is optional, though the value of the Calc Object will be 0.0 if you do not use the Eval entry point.

Entry points for Custom Function Calc Objects

Entry Point Event Intended Use
Eval Called at every Calc Object evaluation To return the value of the Calc Object.
Reset Called every time script is reinitialized (before computing, before each segment runs, and before reporting) To initialize any variables in preparation for Eval to be used

The Eval entry point has the following available inputs and outputs:

Custom Function Calc Objects — Eval entry point arguments and keywords

Name ArgumentType Type Additional Keywords Additional Keyword Options
Value Output --- --- ---
<name> Input CalcObject --- ---
<name> Input GatorVector RefName <refAxes>
Epoch Input --- --- ---
DateUTC Input --- --- ---

In the table above, <name> indicates the name of an object of the given Type from the Component Browser, and <refAxes> indicates the name of Axes from the Component Browser.

The Reset entry point has the same inputs as the Eval entry point, but no outputs.

Custom Function Python Calculation Objects

To set up a Python plugin script calculation object, you need to create two custom components in STK. The first component is a Custom Function that loads the Python script, and the second is a Calculation Object that implements the custom function component.

You must have the Python active scripting engine registered before you can set up a custom function using Python. If you do not have the engine registered, follow the Installation for Python Users instructions to set up the engine.

You can follow these step-by-step instructions to create the components that you need:

  1. On the Utilities menu, select Component Browser...
  2. Select the Custom Functions folder in the left pane of the Component Browser window.
  3. In the list of components in the right pane, select PythonCustomFunction.
  4. Above the list of components, click Duplicate.
  5. Enter a Name and User Comment to identify the new component and click OK.
  6. Double-click the new component to open the Custom Function dialog box.
  7. Click to browse to the Python file that will implement the calculation object.
  8. Click OK to close the Custom Function dialog box.
  9. Select the Calculation Objects folder in the left pane of the Component Browser window and expand it.
  10. Select the Scripts folder within the Calculation Objects folder.
  11. In the list of components in the right pane, select CustomFunctionCalcObject.
  12. Above the list of components, click Duplicate.
  13. Enter a Name and User Comment to identify the new component and click OK.
  14. Double-click the new component to open its properties dialog box.
  15. If you want to use the Python custom function to evaluate the object's value, then double-click the EvalFunction row in the table. If you want to use it to reset some values before computing, then double-click the ResetFunction row.
  16. In the Multiple Component Link Selection dialog box, select the Python custom function in the Available Components pane and then click to assign it to the calculation object.
  17. Click OK to close the dialog box and then click OK to close the component's properties dialog box.

Propagators (deprecated)

A COM-based Propagator plugin script is now available. AGI recommends that when a plugin point is available for both scripting and COM-based plugin scripts, that you use the COM-based plugin script. For information on developing and using COM-based plugin scripts, see the COM-based Engine Plugins topic in the STK Programming Interface Helpselect Programming Interface Help in the STK Help menu tab and go to Select the Right Technology > Extend AGI Products > Extend the Engine > COM Based Engine Plugins.

To run a deprecated Custom Propagator plugin script, use the Astrogator script driver plugin available from the Component Browser.

All Propagators have five Entry Points that may be utilized. Use of any Entry Point is optional.

Entry Point Event Intended Use
Pre-Propagation Called before any propagation begins To perform any necessary preprocessing before the Update or Eval scripts are called. Examples: load a file used in the Eval script; open a socket
Post-Propagation Called after all propagation ends To perform any necessary cleanup operation. Examples: let go of a filehandle; close a socket
SegmentStart Called when a new segment starts To perform any necessary initialization.
Update Called at the beginning of every integration step. Also called on the last state of the segment To update a parameter in a discontinuous way. No discontinuities in parameter values should be made during an integration step, i.e. none should be made using Eval. Also, to update a parameter in a permanent manner, so that subsequent computations (including subsequent segments if applicable) utilize the updated value (unless overridden in Eval)
Eval Called at every force model evaluation To return an additional acceleration; and/or to set certain parameter values (DragArea, CD, density, etc.) that are to be used during this force model computation- --parameter changes are not permanent and are not remembered.

Inputs and Outputs

The Pre-Propagation and Post-Propagation Entry Points have no inputs or outputs. (The script function signature, however, must still allow for one argument).

The Update Entry point has the following available inputs and outputs:

Name ArgumentType Type Additional Keywords Additional Keyword Options
Status Output --- --- ---
CD Output --- --- ---
CR Output --- --- ---
DragArea Output --- --- ---
SRPArea Output --- --- ---
DryMass Output --- --- ---
FuelMass Output --- --- ---
<name> Input CalcObject --- ---
<name> Input GatorVector RefName <refAxes>
Status Input --- --- ---
DateUTC Input --- --- ---
CbName Input --- --- ---
Epoch Input --- --- ---
Mu Input --- --- ---
TotalMass Input --- --- ---
DryMass Input --- --- ---
FuelMass Input --- --- ---
CD Input --- --- ---
CR Input --- --- ---
DragArea Input --- --- ---
SRPArea Input --- --- ---
Position Input --- RefName
RefName
Inertial
Fixed
Velocity Input --- RefName
RefName
Inertial
Fixed

In the above table, <name>indicates the name of an object of the given Type from the Astrogator Component Browser, and <refAxes> indicates the name of an Axes from the Astrogator Component Browser.

When CD, CR, DragArea, SRPArea, DryMass, and/or FuelMass are set as outputs, the values that are assigned permanently affect the satellite's physical properties as viewed on the GUI or reported in the MCS Summary. Thus, assigning values for these during Update will affect the force model computation, unless overridden by the Eval Entry Point. In addition, subsequent MCS segments will use these updated values as well.

The SegmentStart Entry Point has the same inputs that are available in the Update Entry Point, but has no outputs.

Propagators – Eval Entry Point Arguments and Keywords

The Eval Entry point has the following available inputs and outputs:

Name ArgumentType Type Additional Keywords Additional Keyword Options
Status Output --- --- ---
CD Output --- --- ---
CR Output --- --- ---
DragArea Output --- --- ---
SRPArea Output --- --- ---
Density Output --- --- ---
SolarIntensity Output --- --- ---
Acceleration Output --- RefName
RefName
RefName
RefName
Inertial
Fixed
CbiVNC
CbiLVLH
<name> Input CalcObject --- ---
<name> Input GatorVector RefName <refAxes>
Status Input --- --- ---
DateUTC Input --- --- ---
CbName Input --- --- ---
Epoch Input --- --- ---
Mu Input --- --- ---
TotalMass Input --- --- ---
DryMass Input --- --- ---
FuelMass Input --- --- ---
CD Input --- --- ---
CR Input --- --- ---
DragArea Input --- --- ---
SRPArea Input --- --- ---
Position Input --- RefName
RefName
Inertial
Fixed
Velocity Input --- RefName
RefName
Inertial
Fixed
Density Input --- --- ---
SolarIntensity Input --- --- ---
AtmTemperature Input --- --- ---
AtmPressure Input --- --- ---
DragAltitude Input --- --- ---
Longitude Input --- --- ---
Latitude Input --- --- ---
SatToSunVector Input --- SunPosType True
Apparent
ApparentToTrueCb

In the above table,<name> indicates the name of an object of the given Type from the Astrogator Component Browser, and <refAxes> indicates the name of an Axes from the Astrogator Component Browser.

When CD, CR, DragArea, SRPArea, Density, and/or SolarIntensity are set as outputs, the values that are assigned permanently affect the satellite's physical properties as viewed on the GUI or reported in the MCS Summary. Thus, assigning values for these during Update will affect the force model computation, unless overridden by the Eval Entry Point. In addition, subsequent MCS segments will use these updated values as well.

Information on Arguments

Representation and Units

In the following table, arguments are identified by the Name element and, where necessary, the Type element. For each argument, the Representation (essentially, the data type) and Units are given.

Entry Point Representation and Units

Name (Type) Representation Units
<name> (CalcObject) Double based on CalcObject
<name> (GatorVector) Double:3 STK internal
Acceleration Double:3 m/sec^2
AtmPressure Double N/m^2
AtmTemperature Double Kelvin
CbName String ---
CD Double unitless
CR Double unitless
DateUTC String DDD /YYYY HH:MM:SS.ss
Density Double kg/m^3
DragAltitude Double m
DragArea Double m^2
DryMass Double kg
Epoch Epoch epoch secs
FuelMass Double kg
Isp Double secs
Latitude Double rad
Longitude Double rad
MassFlowRate Double kg/sec
Mu Double m^3/sec^2
Position Double:3 m
SatToSunVector Double:3 m
SolarIntensity Double unitless
SRPArea Double m^2
Status String ---
Thrust Double N
TotalMass Double kg
Velocity Double:3 m/sec

In the above table, <name> indicates the name of an object of the given Type from the Astrogator Component Browser.

Parameter Definitions

The following table explains some of the terms used in defining arguments to Entry Points for Astrogator Plugin Points:

Parameter Definition
Acceleration The additional acceleration to add to the acceleration computed according to the Propagator's Force Model settings.
AtmPressure The pressure as indicated by the Atmospheric Model, if available. If not, a negative number is given.
AtmTemperature The temperature as indicated by the Atmospheric Model, if available. If not, a negative number is given.
CbName The name of the central body that acts as the reference frame source for the Position and Velocity inputs.
DateUTC The UTC date equivalent to Epoch, given in the format DDD/YYYY HH:MM:SS.ss. One can extract from this string the calendar date if such knowledge is required in the script.
DragAltitude The altitude that was used in the drag model to compute the Density.
Epoch The time, in epoch seconds.
FuelMass During Eval, this is part of the integrator's state data.
Latitude The detic latitude with reference to the central body indicated by CbName, corresponding to the Position at this Epoch.
Longitude The longitude corresponding to the Position at this Epoch.
Mu The gravitational parameter associated with the central body named by CbName.
Position The position at this Epoch, in the frame indicated, with reference to the central body indicated by CbName. During Eval, this is part of the integrator's state data.
SatToSunVector The position of the Sun, in the Inertial frame of the central body indicated by CbName, as used in SRP computations.
SolarIntensity A measure of the obstruction of the solar disk, as viewed from Position. A value of 1.0 indicates no obstruction, and value of 0.0 indicates full obstruction (i.e. umbra), and a value between 0.0 and 1.0 is partial obstruction (i.e. penumbra).
Status On input, value is set to OK. As an output, its value is checked against the words "Error", "Stop" and "Cancel" in a case-insensitive manner. If one of these was returned as an output, then the script is turned off and a message (indicating which string was found) is returned to the Message Viewer window. This provides a mechanism within the script for turning it off.
TotalMass The sum of DryMass plus FuelMass.
Velocity The velocity at this Epoch, in the frame indicated, with reference to the central body indicated by CbName. During Eval, this is part of the integrator's state data.