Set an Initial Guess with the Scripting Tool

STK Premium (Space) or STK Enterprise
You can obtain the necessary licenses for this tutorial by visiting http://licensing.agi.com/stk/evaluation or contacting AGI Support at support@agi.com or 1-800-924-7244.

This lessons uses the Visual Basic Scripting Edition (VBScript) scripting language. Microsoft has announced that VBScript is deprecated and will be removed from future versions of Windows. You can continue to use VBScript with the STK software in current versions of Windows. Refer to Microsoft's documentation for more information and the deprecation timeline.

The results of the tutorial may vary depending on the user settings and data enabled (online operations, terrain server, dynamic Earth data, etc.). It is acceptable to have different results.

Capabilities covered

This lesson covers the following capabilities of the Ansys Systems Tool Kit® (STK®) digital mission engineering software:

  • STK Pro
  • Astrogator

Problem statement

Engineers and operators require a quick way to design high-fidelity spacecraft trajectories for mission planning and operations, all without external tools.

Solution

Use the Scripting Tool, a utility available within the STK/Astrogator® capability, to compute the initial guesses for the maneuver magnitude.

What you will learn

Upon completion of this tutorial, you will be able to:

  • Open and use the Scripting Tool
  • Use VBScript to define object properties, calc objects, and parameters
  • Use the Scripting Tool in a target sequence

Video guidance

Watch the following video. Then follow the steps below, which incorporate the systems and missions you work on (sample inputs provided).

Using the starter scenario

To speed things up and enable you to focus on this lesson's main goal, a partially created scenario has been built for you. The partially created scenario is saved as a visual data file (VDF) in your STK install.

  1. Launch the STK application ().
  2. Click Open a Scenario in the Welcome to STK dialog box.
  3. Go to <Install Dir>\Data\Resources\stktraining\VDFs.
  4. Select Target_Hohmann_Transfer.vdf.
  5. Click Open.

This lesson builds on the Hohmann Transfer Using Targeter tutorial. Please note, the propagator converges in that lesson without using the Scripting Tool. You can also choose to build on that lesson.

Saving the VDF as a scenario

Save and extract the VDF data in the form of a scenario folder. When you save a VDF in the STK application, it will save in its originating format. That is, if you open a VDF, the default save format will be a VDF (.vdf). If you want to save and extract a VDF as a scenario folder, you must change the file format by using the Save As feature. This will create a permanent scenario file complete with child objects and any additional files packaged with the VDF.

  1. Open the File menu.
  2. Select Save As....
  3. Select the STK User folder in the navigation pane when the Save As dialog box opens.
  4. Select the Target_Hohmann_Transfer folder.

    5. A scenario folder with the same name as the VDF was created for you when you opened the VDF in the STK application. This folder contains the temporarily unpacked files from the VDF.

  5. Click Open.
  6. Select Scenario Files (*.sc) as the Save as type.
  7. Select the Target_Hohmann_Transfer Scenario file in the file browser.
  8. Click Save.
  9. Click Yes when the Confirm Save As dialog box opens to overwrite the existing scenario file in the folder and to save your scenario.

Save () often during this lesson!

Adding a Sequence segment

Add a new Sequence segment to the beginning of the MCS. A Sequence segment is used as a structural element to organize segments and define the nature of the results to pass on to the next segment or sequence in the MCS. A sequence is comprised of segments, each of which is propagated forward in order within the sequence. Each segment nested within a sequence is created and defined in the normal way, and behaves exactly as it would at the MCS level.

  1. Open Hohmann_Sat_Targeter's () Properties ().
  2. Right-click on the Inner Orbit () Initial State segment.
  3. Select Insert Before... in the shortcut menu.
  4. Select Sequence () when the Segment Selection dialog box opens.
  5. Click OK to confirm your selection and to close the Segment Selection dialog box.
  6. Click and drag all the segments into the Sequence () segment.

    7. Be sure you preserve the same order and structure of the MCS when you move the segments into the Sequence.

    MCS segments nested in Sequence

  7. Select the Sequence () segment.
  8. Select the Enabled check box in the Scripting Panel.
  9. Click Scripting Tool....

Using the Scripting Tool

The Scripting Tool is a utility within Astrogator that enables you to write scripts in JScript, VBScript, Python, or MATLAB that will interact with object attributes, calculation object components, and custom-defined parameters. You can use the Scripting Tool to perform a variety of functions to augment the logic of the Mission Control Sequence.

There are four areas in the Scripting Tool:

Option Value
Object Properties Allow you to get/set values from Astrogator segments. In this example, you will use this to set the desired orbits and the initial guesses for the maneuver magnitudes.
Calc Objects Allow you to pull a value from any calculation object into the script. Examples include the current time, current orbital elements and information about engines.
Parameters Allows you to define additional values which may be used for computations. They may be custom constants or variables which are set during the computations.
Scripting Area Location where the actual script is written. You can use VBScript, JavaScript, MATLAB, or Python.

You can find the tool on Sequence and Backward Sequence segments, on differential corrector and plugin search profiles, and also as a standalone profile on Target Sequences.

Adding the initial parameter

Start by adding two parameters that specify the initial and final values of the semi-major axis. You can use seven types of parameters in a script: Boolean, Date, Double, Enumeration, Integer, Quantity, and String. Each parameter appears on a separate line with Name, Value, Unit, Type, Dimension, and User Comment fields. Use the Name field to identify the parameter and as a variable in the script. The Value, Unit, and Dimension fields are all dependent on the parameter's type. Value can be any real number. Dimension can be any unit type supported by the STK software. Unit can be any unit of the selected Dimension that is supported by the STK software.

  1. Click New () in the Parameters panel of the Scripting Tool.
  2. Double-click in the Name field.
  3. Rename the parameter initial_a.
  4. Select the Enter key
  5. Click on the Type filed
  6. Select Quantity in the drop-down list
  7. Ensure that Dimension is set to DistanceUnit.
  8. Click in the Value field.
  9. Enter 6700 km.
  10. Select the Enter key.

Adding the final parameter

Create a second parameter for the final semi-major axis.

  1. Follow the steps above, using final_a, as the Name and 42164 km as the Value.
  2. Click OK to close the Parameter Properties when you are finished.
  3. Note that both parameters have been added to the Sequence's properties in the Parameters list.

Creating a new object property

So far, the initial_a and final_a parameters are just constants. You need to set the initial semimajor axis and the desired radius of apogee to use these values by defining them as object properties. Start with the initial one.

  1. Click New () in the Object Properties panel.
  2. Double-click in the Name field.
  3. Rename the Property a0.

The script will be able to use and change object properties assigned to it.

Selecting the object and attribute

Next, choose the object that contains the properties and the attribute that corresponds to the property that the script will change.

  1. Click Properties... () in the Object Properties toolbar.
  2. Double-click on the Object Value entry in the Component Details list when the Object Properties dialog box opens.
  3. Select the Inner Orbit () segment when the Component Selection dialog box opens.

    4. All segments nested within the Sequence in which the Scripting Tool is located are available for selection.

  4. Click OK to confirm your selection and to close the Component Selection dialog box.
  5. Keep the ReadOnlyProperty set to false.
  6. Double-click on the Attribute entry.
  7. Select InitialState.Keplerian.sma from the selection drop-down list.

    8. This size attribute sets the semi-major axis used to define the satellite's initial state. The attributes of each object are described in detail in the Connect documentation.

  8. Click OK to confirm your selection.
  9. Click OK to confirm your selections and close the Object Properties dialog box.

Creating a second object property

Now, define the second object property to modify. In this case, the desired radius of apoapsis.

  1. Create a new Object Property ().
  2. Rename the new Property a1.
  3. Click Properties... () in the Object Properties toolbar.
  4. Set the Object to the Start Transfer () Target Sequence.
  5. Keep the ReadOnlyProperty set to false.
  6. Set the Attribute to Profiles.Differential Corrector.Results.DV1 : Radius Of Apoapsis.Desired.

    7. The Differential_Corrector attribute defines the Differential_Corrector targeting profile. The Results attribute is used with Target Sequences to set equality constraints and the attributes of those results.

  7. Click OK to confirm your selection.
  8. Click OK to close Object Properties dialog box.

Setting the Desired Values

Now you can set your desired values in Astrogator.

  1. Select VBScript in the Language drop-down list in the Scripting area.
  2. Enter or copy and paste the following code onto a new line in the scripting area to set the a0 property to the initial_a parameter:
    3. a0 = initial_a
  3. Enter or copy and paste the following code onto a new line in the scripting area to set the a1 property to the final_a parameter:
    4. a1 = final_a

Object attributes, calculation objects, and parameters are all available as variables in the script, using the same names you specified. In the script, the variables are initialized to the value of the object properties, calculation objects, and parameters in the units associated with them, if applicable. Setting the value of a variable associated with an editable object property in the script will set the object property to that value in the MCS, in the specified unit of the object property, if applicable.

Adding a calc objects

Next, you need to compute the Delta-V required to achieve the orbits specified above. You'll use simple two-body equations of motion for those calc objects:

Option Value
μ Gravitational constant
r Distance from the satellite to the center of the Earth at the time of interest.
a Semimajor axis

For the initial and final circular orbits, this reduces to:

First, you need to get the value of μ to perform these calculations.

  1. Click New () in the Calc Objects panel.
  2. Rename the new Calc Object mu.
  3. Click Properties... () on the Calc Objects menu.
  4. Double-click on the CalcObject entry.
  5. Click Change... when the Embedded Component Link Selection dialog box opens.
  6. Expand () the Constants () folder.
  7. Select Gravitational Parameter ().
  8. Click OK to confirm your selection and to close the Component Link Selection dialog box.
  9. Click OK to confirm your change and to close the Embedded Component Link Selection dialog box.
  10. Click OK to confirm your changes and to close the New... dialog box.

Computing the initial guess for dv1

Now that you have all the necessary inputs, you can compute the initial guess for the first maneuver.

  1. Enter a new line in the scripting area after your two definitions.
  2. Enter or copy and paste the following code onto a new line in the scripting area:
    3. v_init = sqr(mu/initial_a)

    This computes the velocity in the circular initial orbit.

  3. Enter or copy and paste the following code onto a new line in the scripting area:
    4. transfer_a = (initial_a + final_a) / 2.0

    This calculates the semimajor axis of the transfer orbit.

  4. Enter or copy and paste the following code onto a new line in the scripting area:
    5. v_transfer_peri = sqr(2.0*mu/initial_a - mu/transfer_a)

    This allows you to determine the required initial velocity of the transfer orbit.

  5. Enter or copy and paste the following code onto a new line in the scripting area:
    6. dv1 = v_transfer_peri - v_init

    The maneuver magnitude is just the difference between these two velocities.

Setting the value for dv1

Now that you have the initial guess for the first maneuver, you need to apply it.

  1. Create a new Object Property ().
  2. Rename the Property dv1_guess.
  3. Click Properties... () in the Object Properties toolbar.
  4. Set the Object to the Start Transfer.DV1 () segment.
  5. Keep the ReadOnlyProperty set to false.
  6. Set the Attribute to ImpulsiveMnvr.Pointing.Cartesian.X.
  7. Click OK to close the Object Properties dialog box.
  8. Enter or copy and paste the following code onto a new line in the scripting area:
    9. dv1_guess = dv1

    This sets the dv1_guess value to be what you computed dv1 to be.

  9. Enter or copy and paste the following code onto a new line in the scripting area:
    10. msgbox(dv1)

    This adds a message box for testing to make sure you get the correct values.

  10. Click OK to save your changes and to close the Scripting Tool.

Propagating the satellite with the script for dv1 guess

With the dv1 guess value set, reset the profiles and corrections in the Start Transfer target sequence and propagate the satellite.

  1. Select Start Transfer () in the MCS.
  2. Click Reset in the Profiles and Corrections panel all values in the Start Transfer () Target Sequence.
  3. Click Run Entire Mission Control Sequence () in the MCS toolbar to Propagate the satellite.
  4. Review the message in the message box that appears.

    5. This is the message box you created in your script. The correct dv1 should be 2.4195 km/s.

  5. Click OK to close the message box.

The Target Sequence should converge quickly.

Computing the initial guess and setting the value for dv2

Complete the same setup for dv2. This requires you to compute the value for dv2 and then set it.

  1. Select the Sequence () segment in the MCS.
  2. Click Scripting Tool....
  3. Create a new Object Property ().
  4. Rename the Property dv2_guess.
  5. Click Properties... () on the Object Properties toolbar.
  6. Set the Object to the Finish.Transfer.DV2 () segment.
  7. Keep the ReadOnlyProperty set to false.
  8. Set the Attribute to ImpulsiveMnvr.Pointing.Cartesian.X.
  9. Click OK to close the Object Properties dialog box.
  10. Enter or copy and paste the following code onto a new line in the scripting area:
    11. v_transfer_apo = sqr(2.0*mu/final_a - mu/transfer_a)
v_final = sqr(mu/final_a)
dv2 = v_final - v_transfer_apo
dv2_guess = dv2

    This code block adds the computations of dv2 and set it equal to dv2_guess.

You now have a completed script, which will compute the guesses for the maneuver magnitude.

The full script can be viewed here:Closed

a0 = initial_a
a1 = final_a

v_init = sqr(mu/initial_a)
transfer_a = (initial_a + final_a) / 2.0
v_transfer_peri = sqr(2.0*mu/initial_a - mu/transfer_a)
dv1 = v_transfer_peri - v_init
dv1_guess = dv1
msgbox(dv1)

v_transfer_apo = sqr(2.0*mu/final_a - mu/transfer_a)
v_final = sqr(mu/final_a)
dv2 = v_final - v_transfer_apo
v2_guess = dv2

Resetting both target sequences

With both guesses defined, reset the Target Sequences and re-run the MCS.

  1. Click OK to close the Scripting Tool.
  2. Select Start Transfer () in the MCS.
  3. Click Reset.
  4. Select FinishTransfer () in the MCS.
  5. Click Reset.
  6. Click Run Entire Mission Control Sequence () to propagate the satellite.

Both Target Sequences should converge quickly.

Saving your work

Clean up and close out your scenario.

  1. Close any open reports, properties, and the Report & Graph Manager.
  2. Save () your work.

Summary

You began by opening a previously-built scenario with an MCS featuring a Hohmann transfer using two Target Sequences. You added the MCS segments to a Sequence segment, then used the Scripting tool to create and define object properties, parameters, and calc objects to compute the initial guesses for the maneuver magnitude. The Scripting Tool allows you to perform your own computations without the need for external tools.

On your own

Try changing the values for initial_a and final_a to make sure the script continues to work.