AGI Systems Tool Kit Integration

This demo shows the preliminary integration of Valispace with AGI's Systems Tool Kit (STK) using python APIs. This tutorial requires an existing license for STK's Integration module. To get a license for STK's Integration module get an evaluation license from AGI or contact AGI support.

Systems Tool Kit

In this tutorial we are going to use AGI's Systems Tool Kit (STK), a popular off-the-shelf software for modelling, simulation and analyses of complex missions and systems. STK provides proven tools and environment for satellite mission designers and operators to analyze complex interactions in systems. Learn more about STK's capabilities here.

The goal of this tutorial is to integrate capabilities of STK with Valispace and realize the possibilities for automating and eliminating the gaps between your simulation software and mission data management. By integrating STK to Valispace, the simulation data and updates to mission are automatically updated in respective Valis and components and available to all the project members. This extrapolates into Advanced Capabilities that will empower mission designers.

Possible Advanced Capabilities

  • The automated interfaces between mission data on Valispace and mission simulation in external tool like STK can be extrapolated to automate more complex and real design scenarios. An example of this advanced interface with state-of-the-art astrodynamics module 'Astrogator' from STK is shown in the video below. In the video below, a mission designer using STK to generate the spacecraft trajectory has automated interfaces between his STK node and the Valispace projects. In brief,

    • A GEO satellite has to target a very specific and narrow GEO slot in the orbit, for a specific payload operation over a specific region. To target this, complex trajectory calculations are made for the transfer from a low earth parking orbit to a specific 'longitude' at GEO height.

    • Changes in the parking orbit due to launch change or various other reasons, forces a mission designer to recalculate every time. Following this, he has to manually update tens of parameters related to mission design, to the project database and make it available to other design teams.

    • Using STK+Valispace interface, we do this in a matter of a click :) and the data is available in the project database as soon as the STK application finishes its calculations.

    • Check out the video to see how we do it!

This tutorial aims at improving your skills of:
-> Valispace Python API usage for custom applications.
-> Data update between Valispace and STK

We will create a scenario that simulates a satellite and its access to a network of available groundstations, created entirely from a Valispace project.

You can use the complete python script and Valispace project JSON package available on STK Integration repository on Valispace Github . You can simply import the JSON file in your Valispace project and make appropriate changes to the python script to run the demo directly.

Overview:

Alternatively, you can follow these steps to develop the required project and its components.

(1) Set up your Valispace project

  • Make a project and add the following Components
    • Insert new component in the project called Scenario. This is our parent component representing variables for STK scenario setup.
    • In the Scenario component, add GroundStations and Satellite subcomponents. The GroundStations component contains a list of available groundstations and Satellite contains it's subsystems and mission data.

(2) Set up your Ground Stations

  • Creating the Ground Station network
    • In the GroundStations component, add a vali named Count with a value of 4 (number of groundstations our satellite has available).
    • Insert individual ground stations as subcomponents within the GroundStation component. We have Guam, Kourou, Kiruna and Santa_Maria of ESTRACK network.

      • Select Guam and insert three valis - Altitude with unit m, Latitude and Longitude with unit deg, representing it's Geodetic position.
      • Insert values in valis for Guam station as : Altitude = 197.119 m , Latitude = 13.615 deg and Longitude= 144.815 GS_vali
      • Repeat this for all the stations and put the following values to the respective valis.
      • Kiruna : Altitude = 402.200 m , Latitude = 67.858 deg and Longitude= 20.967
      • Kourou : Altitude = 252.26 m , Latitude = 5.251 deg and Longitude= -52.805
      • Guam : Altitude = 276 m , Latitude = 36.997 deg and Longitude= -25.136

      You can also insert your own ground station or one from the standard databases.

(3) Set up your Satellite Orbit

  • Within your satellite component, you may have several components for all the subsystems and mission design data. For this tutorial, we are only concerned with the Orbit of the satellite. If you interface with a satellite component of your own, make sure to have an Orbit component made according to the following instructions:
  • Within Satellite, make a subcomponent Orbit or ensure the name of the component containing orbit data is named as such.
  • We will now specify Classical Orbital Elements to describe the satellite orbit.
    • Select the Orbit component, and add 6 new valis with their respective values and units:
      • SemiMajorAxis = 7167 km
      • Eccentricity = 0
      • Inclination = 28 deg
      • ArgOfPerigee = 0 deg
      • RAAN = 0 deg
      • MeanAnomaly = 0 deg Orbit_valis

PowerUserTip: The python script in the link maps components and their valis by their name, to get the values and assign them to the respective fields in STK. If you're using your own project to interface with STK, you would want to keep the component/vali names for components same as the ones described here. Alternatively, you can use prefered names and make changes to the python script appropriately.

(4) Overview of the Python Integration script

NOTE: This script was developed using Python 3.7.3. - Start Spyder or any preferable python IDE. Open the script given in the [link]. - We use python API to connect to Valispace and fetch the mission data.

Connect to Valispace

    import valispace
    valispace = valispace.API(url='https://app.valispace.com', username='user', password='password')
  • Get handle for access to valispace using the url in which your project is made with your username and password.

Get the Valispace Project

    ### Enter the PROJECT NAME here ### 
    project_Name = 'ValiSAT_STK'

    # Fetch project JSON object for project_name
    dict_project = valispace.get_project_by_name(name=project_Name)

    #Get Project ID
    projectID = dict_project[0]['id']       

  • In Valispace, a unique identifier ID is assigned to components and valis. It is preferable to use these ID's, when using python API. You can find these at the end of url in your browse, when you select a component or vali. ID

Get the components

  • In our project we have a parent component Scenario and under it, two components- GroundStations and Satellite.
  • We get these components to our python workspace as JSON object using get_component_by_name attribute of Valispace API. *NOTE: Since these components are fetched using it's name, it is necessary to ensure names used in the Valispace project are same as those in the following snippet of your code. This is also applicable to the Valis within these components. Double check the names if you are creating your own project/script adapted from this tutorial.

Get the list of all Ground stations within GroundStations component

    ## Get JSON object - Looks for a parent component 'GroundStations' which contains individual GS as children
    GS_dict = valispace.get_component_by_name(unique_name = 'GroundStations',project_name = project_Name)

    #Get Component IDs for all children- individual GS
    GS_compIDs = GS_dict[0]['children']
  • These component IDs reflect each of Guam, Kiruna, Kourou and Santa_Maria stations that we created earlier. The script then loops over each of these to find Altitude, Latitude and Longitude valis and their values.

Get the Satellite Component and find Orbit subcomponent

    ## Get Satellite component from Valispace- Looks for Component 'Satellite' by name ##
    Sat_dict = valispace.get_component_by_name(unique_name = 'Satellite',project_name = project_Name)
    Sat_childIDs = Sat_dict[0]['children']

    ## Get Orbit Component of Satellite Object among all the children in Satellite component
    for idx2 in range (0,len(Sat_childIDs)):
        temp_comp = valispace.get_component(id = Sat_childIDs[idx2])
        if temp_comp['name']== 'Orbit':
            Sat_orbitID = Sat_childIDs[idx2]
            SatOrbit_dict = temp_comp
            break
    del temp_comp  

    # List all the valis in Orbit subcomponent
    Sat_valiIDs = SatOrbit_dict['valis']    

The script then searches for 6 classical orbital elements by name among the children vali IDs of Orbit component. SemiMajorAxis, Eccentricity, Inclination, RAAN, ArgOfPerigee and MeanAnomaly. Again, take care that the names in the vali search loop in the script exactly match the vali names.

Example: Fetching valis and accessing its parameters After getting the Orbit and individual ground station components, Check out how the JSON object returned to the above command looks like here for the SemiMajorAxis vali.

To get valis from children ID, we use get_vali attribute. You can search the dictionary for any of the arguments listed in the returned JSON object. As an example:

    #Returns unique full name with Parent name along with vali name
    vali_fullname = vali_dict['name']   # e.g.: 'Orbit.SemiMajorAxis'

    #Returns 'non-unique' valiname 
    vali_name = vali_dict['shortname']   # e.g: 'SemiMajorAxis'

    #Returns vali value
    SMA_value = vali_dict['value'] 

    #Returns vali unit used 
    SMA_unit = vali_dict['unit']

We organize this information and pass it to STK.*

Initiating STK application and configuring scenario

This script was developed with STK 11.5

  • STK's Connect module lets us interface our python script with STK application in a server-client environment. The Documentation of all the Connect library commands can be found here.

  • Below is the general snippet for starting the application and creating a scenario. To learn more about the methods used below. Take a look at STK Programming Interface help.

    from comtypes.client import CreateObject
    from comtypes.gen import STKUtil
    from comtypes.gen import STKObjects

    ## ------------- Build STK Scenario -------------------- ##
    # Reference to running STK instance
    uiApplication    = CreateObject("STK11.Application")

    uiApplication.Visible=True
    uiApplication.UserControl=True

    # Get IAgStkObjectRoot interface
    root=uiApplication.Personality2

    ## Create a new scenario.
    root.NewScenario("ValispaceBeta")
    scenario         = root.CurrentScenario

    ## Set the analysis time period.
    scenario2        = scenario.QueryInterface(STKObjects.IAgScenario)
    scenario2.SetTimePeriod('Today','+24hr')
    ##   Reset the animation time.
    root.Rewind();
  • Create a new satellite in the current scenario and set it's orbit from Keplerian Elements using SetState command.
    #Create a satellite Object 
    satellite        = scenario.Children.New(STKObjects.eSatellite, "ValiSAT")

    ### Set state and Propagate the orbit.
    root.ExecuteCommand('SetState */Satellite/ValiSAT Classical HPOP "' + scenario2.StartTime + '" "'+ scenario2.StopTime +'" 60 J2000 "'+ scenario2.StartTime +'" '+ Sat_SMA +' '+ Sat_ecc +' '+ Sat_inc +' '+ Sat_AOP +' '+ Sat_RAAN +' '+ Sat_MA +'')

With these basic snippets, the core of your scenario should be ready. The demo script linked with this tutorial contains additional code to plot groundstations and compute accesses. This code section enables interfacing with STK and creating groundstations, orbit and accesses for the given mission. This is based on the STK tutorial for Integration with Python.

(5) Running the Integration script

  • On running the Integration script, the STK application starts and configures the scenario automatically.
  • Once, the first segment of the code finishes running, you should see the groundstations, satellite, it's orbit and access in 2D and 3D viewers in your STK application.

    Initial Analysis

    STK1

    • Lets check the sunlight intervals for this orbit.
    • Click on Analysis in the Menu bar.
    • Select Analysis Workbench. In the Workbench, select Time Tab.
    • Select the satellite object ValiSAT in the left list.
    • In the list on the right side, expand Lighting Intervals.
    • Right click on Sunlight and select Graph.

    Sunlight Intervals for current orbit

    Lighting1

    Updating the orbit - Let's assume, one of the requirements of the mission in it's current form is to have near-continuous lighting. To do this, we change the orbit to be of Sun-Synchronous type. - Double-click on the satellite object ValiSAT in the object browser docked to the left to open the Object Property window. - Select Orbit in the Basic category. You should see the classical orbital elements of the current orbit. - Edit and change Inclination = 98 deg and RAAN = 340 deg. Click OK.

    Orbitprop

    • Repeat the steps above to check the lightin intervals in the Analysis Workbench for the new orbit.
    • We now have continuous lighting for the new orbit.

    lighting2

    Note in the 2D viewer that we now also have access to Kiruna ground station.

    • You can make more changes to the orbit as desired, until it meets your requirements.

(6) Update the Valispace project

  • After making the changes and completing the analyses, it is desirable to have an automated update of all the concerned parameters of your project. With valispace, you can instantly update and make the new orbit data available to all the project members

    • Open the python IDE. You should see the following message asking for update authorisation:

    auth

    • Type Y in response and wait for update to complete.

    • Open your valispace project again. Open the Orbit subcomponent, to which the update was made.

    • We now have the updated values of the two orbital elements we changed during analysis.

    updated


You can find the Project JSON package for import and the script for this tutorial in the STK Integration repository on Valispace Github

Ad Astra!

For any questions regarding the tutorial or to know more about the potential of STK Integration with Valispace, reach us by email