Customizing computations with STK Plug-ins using compiled code

1. Customizing computations with STK Plug-ins using compiled code Dr. Vince Coppola – Analytical Graphics, Inc. October 2005

2. Outline • What is an STK plug-in? • Motivation: TDRS SRP Model • COM based plug-ins • Access constraint example • Questions and answers

3. What is an STK plug-in? • Custom software that STK uses during computations • Purpose • Customize models used in STK computations to specific needs

4. What is an STK plug-in? (cont.) • Differs from STK/Connect • Not used to control task flow • Differs from STK/X and 4DX • Not used for custom GUIs • Not used for creating a custom application

5. Example: TDRS SRP model • TDRS • GEO Communication satellite • Solar panels track Sun • Solar sail, AW C-band antenna, and SGL antenna are nominally Earth-pointing • Need • Generate ephemeris using a high-fidelity force model • Force Model Contributors • Gravity field (solid tides?) (ocean tides?) • Third body gravity (Sun, Moon, others?) • General relativity effect • Solar radiation pressure (SRP)

6. TDRS SRP model (cont.) • Solar radiation pressure force • Depends on particle absorption and reflection • Depends on surface orientation • Surface orientation varies along the trajectory • Generic model: spherical shape • Accel = Cr * (Area/mass) * Illumination * Irradiance / c • Directed along apparent sun line • Supported by STK

7. TDRS SRP model (cont.) • Better model for TDRS • Based on Pechenick, K. and Hujsak, R. (1987) • Account for surface orientation of main parts • Account for diffuse and specular reflection • Accel = Cr *(1.0/mass)* Illumination * Irradiance / c * {A1 k + A2 k x ( k x N ) + A3 k x ( k x M ) } • k – along sun line, N normal to solar panels, M radial • A1, A2, A3 depends on area, reflection values

8. TDRS SRP model (cont.) • Use a HPOP Plug-in • Code the model in a computer language of choice • C++, C#, VB.NET, Perl, VBScript, Jscript, etc. • Adhere to the published plug-in interface • Sample code provided • Choose to use the plug-in from the HPOP GUI • Just like the other force model settings • Set any plug-in specific parameters from the GUI • Similar to the other force model settings • Configure the remaining force model parameters • HPOP generates the ephemeris using the force model

9. TDRS SRP model (cont.) • What you don’t code (nor test, doc, maintain) • All the other force model contributions • The numerical integration algorithm • The VOP formulation • The time regularization algorithm • The covariance propagation algorithm • Save time and avoid risk • Code only the custom part

10. Purpose Plug-ins provide the means for custom modeling while leveraging STK’s tested generic computational framework Only code the custom part of the model

11. HPOP plug-in uses • Attitude dependent SRP • Attitude dependent Drag • Density model • Satellite thermal emission • Micrometeorite particle collisions • Re-entry drag and lift • Outgasssing (thrust without mass loss) • Models non-physical accelerations

12. Outgassing

13. Performance 90 days propagation seconds

14. Plug-in evolution • STK 4.3 introduced plug-in scripts (2002) • Perl, VBScript, Matlab scripts • AGI-developed interface • Installation • Calling conventions • Debugging ideas • Troubleshooting

15. Available plug-in points • 15 plug-in points • Astrogator • Vector Tool • Access constraint • Attitude simulator • Communications modeling

16. Plug-in scripts • Use • Only needed when generic models are insufficient • Several customers rely on this capability • Limitations • 3 languages – Perl, VBScript, Matlab • Not as fast as compiled code • Non-standard function calling conventions • Requested input data must be known a priori • Unable to get/set plug-in parameter data

17. COM-based plug-ins • Computer programmer-friendly plug-ins • Based on Microsoft’s COM technology • STK 6.1 introduced COM Plug-ins (2004) • HPOP • STK 6.2 (2005) • Astrogator engine model, Astrogator attitude controller • STK 7.0 (2005) • Alpha prototype for Access constraints, dynamic phase array antenna

18. COM • Component Object Model • Standard Microsoft protocol • Many languages (Windows operating system) • C++, C#, VB.NET, Perl, VBScript, Jscript • Sun Java • No samples yet  customer interest? • Microsoft J++ / J# • No samples yet

19. Plug-in concepts • Focused on a computational task • HPOP: evaluating the force model • Attitude controller: steering an engine • Engine model: modeling thrust and flow rate • Access constraint: providing a visibility measure • Plug-in point • Own triggering events • Provides interface for setting/getting input/output data

20. Plug-In Points • Must modify STK to make a plug-in point • Identify a computation • Identify a need for user customization • Identify the triggering events • Identify inputs and outputs • Made available as need arises

21. Matlab plug-ins • Previous capability supported Matlab • Compatible with Matlab version 6.x and 7.x • Matlab is COM-aware • Can use COM objects • Can be used as a COM object • Recommendation • Use a scripting language plug-in to STK • Call Matlab from scripting language

22. HPOP plug-in • Custom force model • Supported by STK and ODTK • Plug-in scripts • Astrogator propagator plug-in • Custom force model • Migration to COM plug-ins  soon!

23. HPOP plug-in events • Init() • PrePropagate() • PreNextStep() • Evaluate() • PostEvaluate() • PostPropagate() • Free()

24. Hpop plug-in events (cont.) PrePropagate() while needing to take another step { PreNextStep() while haven’t taken a good step { Attempt the step Assess whether step is good } } PostPropagate()

25. Hpop plug-in events (cont.) Attempt the step: Evaluate force model : Perform preliminary computations Evaluate() Compute all force model contributions PostEvaluate() Add all force model contributions

26. Calling convention • Plug-in scripts passed input / output data • COM based plug-ins pass interfaces • Each event has an interface appropriate for that event • The interface has properties and methods for getting inputs and outputs bool Evaluate( IAgAsHpopPluginResultEval interface)

27. Calling Convention (cont.) bool Evaluate( IAgAsHpopPluginResultEval interface) illum = interface.SolarIntensity if(illum > 0) { interface.SunPosition(eSRP, eInertial, sunX, sunY, sunZ) … <compute SRP acceleration> … interface.AddAccleration(eInertial, aX, aY, aZ) }

28. Calling Convention (cont.) Init( IAgUtPluginSite siteInterface) PrePropagate( IAgAsHpopPluginResult interface) PreNextStep( IAgAsHpopPluginResult interface) Evaluate( IAgAsHpopPluginResultEval interface) PostEvaluate( IAgAsHpopPluginResultPostEval interface) PostPropagate( IAgAsHpopPluginResult interface) Free()

29. Exception handling • Event calls return a Boolean value • True: everything is okay • False: an unrecoverable error occurred • Turns this event off – no longer called • STK code captures exceptions raised by a plug-in • Exception text sent to message viewer • Certain interface function may fail • Sets a defined error code

30. Inputs and outputs • Specific to each interface • Ephemeris • Variables pertaining to the plug-in point • HPOP: Cd, Drag Area, Cr, SRP Area, Mass, etc. • Engine Model: thrust, mass flow rate, Isp • Attitude Controller: Euler angles, quaternion • Methods and properties

31. Documentation • Compiled help file (stkPlugins.chm) • Plug-in points • Triggering events • Interface methods and properties • 7 language syntaxes shown • VB.NET, VB6, C# • Managed C++, Unmanaged C++ • VBScript, Perl

32. Evaluate method

33. Evaluate method (cont.)

34. Eval interface

35. SunPosition method

36. SunPosition_Array method

37. IAgUtPluginSite interface • bool Init( IAgUtPluginSite site) • Message Viewer • Write messages to message viewer • Vector Tool • Vectors, axes, points, angles, etc • Ephemeris and attitude of any object expressed in any components • Astrogator Calc Objects

38. Building plug-in components • Scripting languages • Windows script host • Text editor • Compiled languages • Microsoft Visual Studio (C++, C#, VB.NET)

39. Installation • Standard COM registration • Registration in the Windows registry • GUID • Regsvr32 • C++ components • Perl, VBScript, Jscript components • Regasm • .NET components (C#, VB.NET) • Must register on every machine you want to run on

40. Debugging • Available for compiled plug-ins • Able to debug plug-in code when running STK • Must exit STK before re-building the plug-in • Not available for scripting languages • Create a log file instead • Use message viewer (but not too much) • Advantage: Can edit text file with STK running • Helps to reduce cycle time

41. TDRS SRP model • Init() • Return true to turn plug-in On • PrePropagate() • Check whether SRP is On • Pre-compute some variables • PreNextStep, PostPropagate(), Free() • If debug mode, output msgs else do nothing

42. TDRS SRP model (cont.) • Evaluate() • Compute SRP based on formula • Use interface->AddAcceleration() • PostEvaluate() • If debug mode, output diagnostic messages to viewer

43. TDRS SRP model (cont.) • Plug-in parameter data • Diffuse reflectivity, specular reflectivity • ‘Debug’ settings (messages sent to MessageViewer) • IAgUtPluginConfig • Implement this interface to set / get parameter data • GetPluginConfig() • Register parameter data with STK • VerifyPluginConfig() • Determine whether user settings are acceptable

44. TDRS SRP model (cont.) AddBoolDispatchProperty ( scope, "DebugMode", "Turn debug messages on or off", "DebugMode", eFlagNone )

45. TDRS SRP model (cont.) AddDoubleDispatchProperty ( scope, "Reflectivity_Specular", "Specular reflectivity coefficient", "SpecularReflectivity", eFlagNone )

46. TDRS SRP model (cont.)

47. TDRS SRP model (cont.)

48. Choosing a plug-in language

49. Using COM in plug-in scripts • Post STK 7.0 • Migration to use COM based plug-ins • Able to use COM plug-ins from VBScript • Restricted to inputs / outputs available • Must use AGI-defined interface • Get handle to the COM component on initialization • Route inputs to the COM component • Have COM component compute values • Return using plug-in script mechanism

50. Access constraints • Constraints are often measures • Elevation angle • Range • Ground elevation angle • Sunlight • Used for visibility and for Figures Of Merit (FOM) • Coverage: visibility to a grid of points • FOM: quality of coverage during visibility times