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 "Extend AGI Products->Extend the Engine->COM Based Engine Plugins" in the STK Programming Interface help system. To access this help system, select Programming Interface Help from the STK Help menu. Examples of these plugins in multiple programming languages are located under CodeSamples\Extend in the STK install directory.
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 four types of Custom Functions: MATLAB, VBScript, Python and Perl. 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.
Calc Objects can utilize scripting through the use of:
Each of these types is found 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 are used for very simple computations that are not currently available as Calculation Objects in the Component Browser. They have three attributes:
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 four types of inline script functions available: MATLAB, VBScript, JavaScript, and Perl. When an inline Calculation Object is used, 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
An inline function named CalcObject_Incl_cos_Raan is created, 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)”); }
Perl defines functions differently from MATLAB and VBScript. The Perl Calculation Object equivalent function is defined as:
sub CalcObject_Incl_cos_Raan { return $_[0]*cos($_[1]); }
Note that there is no method for declaring the arguments as Inclination and RAAN: they have been replaced by $_[0] and $_[1], respectively, based on the knowledge that the order of the arguments is Inclination followed by RAAN. You can enter the InlineFunc value in proper Perl notation as shown above (complete with the scalar prefix $) but then must translate each argument to the function by the proper symbol $_[n], where n is the index of the argument (beginning with 0 in Perl).
If you are not familiar with Perl syntax but want to use Perl, The Perl Calculation Object will create the proper Perl syntax automatically from an InlineFunc written using the names—thus, you can enter Inclination*cos(RAAN) as the InlineFunc even for Perl. When utilizing this behavior, be careful not to mix the two approaches: $Inclination*cos($RAAN) will result in a syntax error.
Caution: 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, VBScript and Perl each allow underscores in function names. Symbols such as '(' or '*' etc. are not allowed however.
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 can be utilized. Use of any Entry Point is optional, though the value of the calc Object will be 0.0 if the Eval Entry Point is not used.
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 re-initialized (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:
Name | ArgumentType | Type | Additional Keywords | Additional Keyword Options |
---|---|---|---|---|
Value | Output | --- | --- | --- |
<name> | Input | CalcObject | --- | --- |
<name> | Input | GatorVector | RefName | <refAxes> |
Epoch | Input | --- | --- | --- |
DateUTC | Input | --- | --- | --- |
In the above table, <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.
A COM-based Custom Engine Model plugin script is now available. We recommend 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 COM-based scripting in STK, see the COM-based Engine Plugins topic in the Programming Interface Help, which is accessible from the Help menu.
To run a deprecated Custom Engine Model plugin script, use the Astrogator script driver plugin available from the Component Browser.
The Custom Engine Models has 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. |
Eval | Called at every force model evaluation | To return engine thrust, mass flow rate, and optionally specific impulse. |
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 | --- | --- | --- |
<name> | Input | CalcObject | --- | --- |
<name> | Input | GatorVector | RefName | <ref-Axes> |
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 Component Browser, and <refAxes> indicates the name of an Axes from the Component Browser.
The SegmentStart Entry Point has the same inputs that are available in the Update Entry Point, but has no outputs.
The Eval Entry point has the following available inputs and outputs:
Name | ArgumentType | Type | Additional Keywords | Additional Keyword Options |
---|---|---|---|---|
Status | Output | --- | --- | --- |
Thrust | Output | --- | --- | --- |
Isp | Output | --- | --- | --- |
MassFlowRate | Output | --- | --- | --- |
<name> | Input | CalcObject | --- | --- |
<name> | Input | GatorVector | RefName | <refAxes> |
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 Component Browser, and <refAxes> indicates the name of an Axes from the Component Browser.
A COM-based Propagator plugin script is now available. We recommend 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 COM-based scripting in STK, see the COM-based Engine Plugins topic in the Programming Interface Help, which is accessible from the Help menu.
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. |
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.
Note: 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.
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.
Note: 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.
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.
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.
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. |
STK Programming Interface 11.0.1