Feature/322 simIncludeGravBody rewrite

docs/source/Support/bskReleaseNotes.rst

@@ -83,6 +83,10 @@ Version |release|
   and ``usePointMassGravityModel`` have been added.
 - Fixed examples and tests to run even when Basilisk is built with ``--vizInterface False``.
 - Added a new method ``setDataBuffer()`` to :ref:`simpleStorageUnit` and :ref:`partitionedStorageUnit` to add or remove data from specified partitions.
+- Refactored ``simIncludeGravBody``. The most notable change for users is that the commonly used line
+  ``scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))``
+  can be replaced by ``gravFactory.addBodiesTo(scObject)`` (where ``scObject`` is a ``spacecraft.Spacecraft`` 
+  or  ``spacecraftSystem.SpacecraftSystem``, and ``gravFactory`` is a ``simIncludeGravBody.gravBodyFactory``)
 
 Version 2.2.0 (June 28, 2023)
 -----------------------------

examples/BskSim/models/BSK_Dynamics.py

@@ -116,7 +116,7 @@ def SetGravityBodies(self):
         self.earth = 1
         self.moon = 2
 
-        self.scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(self.gravFactory.gravBodies.values()))
+        self.gravFactory.addBodiesTo(self.scObject)
         self.gravFactory.createSpiceInterface(bskPath + '/supportData/EphemerisData/',
                                               timeInitString,
                                               epochInMsg=True)

examples/BskSim/models/BSK_FormationDynamics.py

@@ -57,8 +57,8 @@ def __init__(self, SimBase, dynRate):
         self.gravFactory = simIncludeGravBody.gravBodyFactory()
         planet = self.gravFactory.createEarth()
         planet.isCentralBody = True          # ensure this is the central gravitational body
-        self.scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(self.gravFactory.gravBodies.values()))
-        self.scObject2.gravField.gravBodies = spacecraft.GravBodyVector(list(self.gravFactory.gravBodies.values()))
+        self.gravFactory.addBodiesTo(self.scObject)
+        self.gravFactory.addBodiesTo(self.scObject2)
 
         # Initialize all modules and write init one-time messages
         self.InitAllDynObjects()

examples/MultiSatBskSim/modelsMultiSat/BSK_MultiSatDynamics.py

@@ -100,7 +100,7 @@ def SetGravityBodies(self, SimBase):
         Specify what gravitational bodies to include in the simulation
         """
         # Attach the gravity body
-        self.scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(SimBase.EnvModel.gravFactory.gravBodies.values()))
+        SimBase.EnvModel.gravFactory.addBodiesTo(self.scObject)
 
     def SetGroundLocations(self, SimBase):
         """

examples/OpNavScenarios/modelsOpNav/BSK_OpNavDynamics.py

@@ -215,7 +215,7 @@ def SetGravityEffector(self):
         gravBodies['mars barycenter'].useSphericalHarmonicsGravityModel(
             bskPath + '/supportData/LocalGravData/GGM2BData.txt', 2)
 
-        self.scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(self.gravFactory.gravBodies.values()))
+        self.gravFactory.addBodiesTo(self.scObject)
         self.gravFactory.createSpiceInterface(bskPath + '/supportData/EphemerisData/',
                                               timeInitString,
                                               epochInMsg=True)
@@ -369,8 +369,8 @@ def SetEphemConvert(self):
     def SetSimpleGrav(self):
         planet = self.gravFactory.createMarsBarycenter()
         planet.isCentralBody = True
-        self.scObject.gravField.gravBodies = \
-            spacecraft.GravBodyVector(list(self.gravFactory.gravBodies.values()))
+
+        self.gravFactory.addBodiesTo(self.scObject)
 
     # Global call to initialize every module
     def InitAllDynObjects(self, SimBase):

examples/OpNavScenarios/scenariosOpNav/CNN_ImageGen/scenario_CNNImages.py

@@ -184,7 +184,7 @@ def run(TheScenario, runLog):
 
     TheScenario.vizard.kill()
 
-    spice = TheScenario.get_DynModel().gravFactory.spiceObject
+    spice = TheScenario.get_DynModel().spiceObject
     spice.unloadSpiceKernel(spice.SPICEDataPath, 'de430.bsp')
     spice.unloadSpiceKernel(spice.SPICEDataPath, 'naif0012.tls')
     spice.unloadSpiceKernel(spice.SPICEDataPath, 'de-403-masses.tpc')

examples/OpNavScenarios/scenariosOpNav/OpNavMC/scenario_OpNavAttODMC.py

@@ -141,7 +141,7 @@ def run(TheScenario):
 
     vizard.kill()
 
-    spice = TheScenario.get_DynModel().gravFactory.spiceObject
+    spice = TheScenario.get_DynModel().spiceObject
     spice.unloadSpiceKernel(spice.SPICEDataPath, 'de430.bsp')
     spice.unloadSpiceKernel(spice.SPICEDataPath, 'naif0012.tls')
     spice.unloadSpiceKernel(spice.SPICEDataPath, 'de-403-masses.tpc')

examples/scenarioAerocapture.py

@@ -233,15 +233,12 @@ def run(show_plots, planetCase):
 
     # setup Gravity Body
     gravFactory = simIncludeGravBody.gravBodyFactory()
-    if planetCase == 'Earth':
-        planet = gravFactory.createEarth()
-    else:
-        planet = gravFactory.createMars()
+    planet = gravFactory.createBody(planetCase)
     planet.isCentralBody = True  # ensure this is the central gravitational body
     mu = planet.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     if planetCase == 'Earth':
         r = 6503 * 1000

examples/scenarioAlbedo.py

@@ -250,7 +250,7 @@ def run(show_plots, albedoData, multipleInstrument, multiplePlanet, useEclipse,
         scObject.hub.v_CN_NInit = vN  # m - v_CN_N
         scObject.hub.sigma_BNInit = [[0.0], [0.0], [0.0]]  # sigma_BN_B
         scObject.hub.omega_BN_BInit = [[0.0], [0.0], [.5 * macros.D2R]]  # rad/s - omega_BN_B
-        scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+        gravFactory.addBodiesTo(scObject)
 
     # Add spacecraft object to the simulation process
     scSim.AddModelToTask(simTaskName, scObject)

examples/scenarioAsteroidArrival.py

@@ -290,8 +290,7 @@ def run(show_plots):
 
     # Create additional gravitational bodies
     gravFactory = simIncludeGravBody.gravBodyFactory()
-    gravFactory.createBodies(["earth", "sun"])
-    sun = gravFactory.gravBodies["sun"]
+    gravFactory.createBodies("earth", "sun")
 
     # Set gravity body index values
     earthIdx = 0
@@ -300,12 +299,10 @@ def run(show_plots):
 
     # Create and configure the default SPICE support module. The first step is to store
     # the date and time of the start of the simulation.
-    gravFactory.createSpiceInterface(bskPath + '/supportData/EphemerisData/',
-                                     timeInitString,
-                                     epochInMsg=True)
+    spiceObject = gravFactory.createSpiceInterface(time=timeInitString, epochInMsg=True)
 
     # Add the SPICE object to the simulation task list
-    scSim.AddModelToTask(simTaskName, gravFactory.spiceObject)
+    scSim.AddModelToTask(simTaskName, spiceObject)
 
     # Create the asteroid custom gravitational body
     asteroid = gravFactory.createCustomGravObject("bennu", mu
@@ -320,15 +317,15 @@ def run(show_plots):
     scObject.ModelTag = "bskSat"
 
     # Connect all gravitational bodies to the spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
     scSim.AddModelToTask(simTaskName, scObject)
 
     # Create an ephemeris converter to convert messages of type
     # 'SpicePlanetStateMsgPayload' to 'EphemerisMsgPayload'
     ephemObject = ephemerisConverter.EphemerisConverter()
     ephemObject.ModelTag = 'EphemData'
-    ephemObject.addSpiceInputMsg(gravFactory.spiceObject.planetStateOutMsgs[earthIdx])
-    ephemObject.addSpiceInputMsg(gravFactory.spiceObject.planetStateOutMsgs[sunIdx])
+    ephemObject.addSpiceInputMsg(spiceObject.planetStateOutMsgs[earthIdx])
+    ephemObject.addSpiceInputMsg(spiceObject.planetStateOutMsgs[sunIdx])
     # Recall the asteroid was not created with Spice.
     ephemObject.addSpiceInputMsg(gravBodyEphem.planetOutMsgs[0])
     scSim.AddModelToTask(simTaskName, ephemObject)

examples/scenarioAttGuideHyperbolic.py

@@ -262,7 +262,7 @@ def run(show_plots, useAltBodyFrame):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     #
     #   initialize Spacecraft States with initialization variables

examples/scenarioAttLocPoint.py

@@ -189,7 +189,7 @@ def run(show_plots):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     #
     #   initialize Spacecraft States with initialization variables

examples/scenarioAttitudeConstrainedManeuver.py

@@ -143,30 +143,28 @@ def run(show_plots, use2SunSensors, starTrackerFov, sunSensorFov, attitudeSetCas
     gravFactory = simIncludeGravBody.gravBodyFactory()
 
     # Next a series of gravitational bodies are included
-    gravBodies = gravFactory.createBodies(['earth', 'sun'])
+    gravBodies = gravFactory.createBodies('earth', 'sun')
     planet = gravBodies['earth']
     planet.isCentralBody = True
 
     mu = planet.mu
     # The configured gravitational bodies are added to the spacecraft dynamics with the usual command:
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     # Next, the default SPICE support module is created and configured.
     timeInitString = "2021 JANUARY 15 00:28:30.0"
 
-    # The following is a support macro that creates a `gravFactory.spiceObject` instance
-    gravFactory.createSpiceInterface(bskPath +'/supportData/EphemerisData/',
-                                     timeInitString,
-                                     epochInMsg=True)
+    # The following is a support macro that creates a `spiceObject` instance
+    spiceObject = gravFactory.createSpiceInterface(time=timeInitString, epochInMsg=True)
 
     # Earth is gravity center
-    gravFactory.spiceObject.zeroBase = 'Earth'
+    spiceObject.zeroBase = 'Earth'
 
     # The SPICE object is added to the simulation task list.
     scSim.AddModelToTask(simTaskName, gravFactory.spiceObject, 2)
 
     # The gravitational body is connected to the spacecraft object
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     # setup the orbit using classical orbit elements
     oe = orbitalMotion.ClassicElements()
@@ -356,8 +354,8 @@ def run(show_plots, use2SunSensors, starTrackerFov, sunSensorFov, attitudeSetCas
     sNavObject.scStateInMsg.subscribeTo(scObject.scStateOutMsg)
     CAM.scStateInMsg.subscribeTo(scObject.scStateOutMsg)
     CAM.vehicleConfigInMsg.subscribeTo(vcMsg)
-    CAM.keepOutCelBodyInMsg.subscribeTo(gravFactory.spiceObject.planetStateOutMsgs[1])
-    CAM.keepInCelBodyInMsg.subscribeTo(gravFactory.spiceObject.planetStateOutMsgs[1])
+    CAM.keepOutCelBodyInMsg.subscribeTo(spiceObject.planetStateOutMsgs[1])
+    CAM.keepInCelBodyInMsg.subscribeTo(spiceObject.planetStateOutMsgs[1])
     attError.attNavInMsg.subscribeTo(sNavObject.attOutMsg)
     attError.attRefInMsg.subscribeTo(CAM.attRefOutMsg)
     mrpControl.guidInMsg.subscribeTo(attError.attGuidOutMsg)
@@ -370,12 +368,12 @@ def run(show_plots, use2SunSensors, starTrackerFov, sunSensorFov, attitudeSetCas
 
     # Boresight modules
     stBACObject.scStateInMsg.subscribeTo(scObject.scStateOutMsg)
-    stBACObject.celBodyInMsg.subscribeTo(gravFactory.spiceObject.planetStateOutMsgs[1])
+    stBACObject.celBodyInMsg.subscribeTo(spiceObject.planetStateOutMsgs[1])
     ssyBACObject.scStateInMsg.subscribeTo(scObject.scStateOutMsg)
-    ssyBACObject.celBodyInMsg.subscribeTo(gravFactory.spiceObject.planetStateOutMsgs[1])
+    ssyBACObject.celBodyInMsg.subscribeTo(spiceObject.planetStateOutMsgs[1])
     if use2SunSensors:
         sszBACObject.scStateInMsg.subscribeTo(scObject.scStateOutMsg)
-        sszBACObject.celBodyInMsg.subscribeTo(gravFactory.spiceObject.planetStateOutMsgs[1])
+        sszBACObject.celBodyInMsg.subscribeTo(spiceObject.planetStateOutMsgs[1])
 
     # Vizard Visualization Option
     # ---------------------------

examples/scenarioAttitudeConstraintViolation.py

@@ -189,32 +189,30 @@ def run(show_plots, use2SunSensors, starTrackerFov, sunSensorFov, attitudeSetCas
     gravFactory = simIncludeGravBody.gravBodyFactory()
 
     # Next a series of gravitational bodies are included
-    gravBodies = gravFactory.createBodies(['earth', 'sun'])
+    gravBodies = gravFactory.createBodies('earth', 'sun')
     planet = gravBodies['earth']
     planet.isCentralBody = True
 
     mu = planet.mu
     # The configured gravitational bodies are added to the spacecraft dynamics with the usual command:
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     # Next, the default SPICE support module is created and configured.
     timeInitString = "2021 JANUARY 15 00:28:30.0"
     spiceTimeStringFormat = '%Y %B %d %H:%M:%S.%f'
     timeInit = datetime.strptime(timeInitString, spiceTimeStringFormat)
 
-    # The following is a support macro that creates a `gravFactory.spiceObject` instance
-    gravFactory.createSpiceInterface(bskPath +'/supportData/EphemerisData/',
-                                     timeInitString,
-                                     epochInMsg=True)
+    # The following is a support macro that creates a `spiceObject` instance
+    spiceObject = gravFactory.createSpiceInterface(time=timeInitString, epochInMsg=True)
 
     # Earth is gravity center
-    gravFactory.spiceObject.zeroBase = 'Earth'
+    spiceObject.zeroBase = 'Earth'
 
     # The SPICE object is added to the simulation task list.
-    scSim.AddModelToTask(simTaskName, gravFactory.spiceObject, 2)
+    scSim.AddModelToTask(simTaskName, spiceObject, 2)
 
     # The gravitational body is connected to the spacecraft object
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     # setup the orbit using classical orbit elements
     oe = orbitalMotion.ClassicElements()
@@ -404,12 +402,12 @@ def run(show_plots, use2SunSensors, starTrackerFov, sunSensorFov, attitudeSetCas
 
     # Boresight modules
     stBACObject.scStateInMsg.subscribeTo(scObject.scStateOutMsg)
-    stBACObject.celBodyInMsg.subscribeTo(gravFactory.spiceObject.planetStateOutMsgs[1])
+    stBACObject.celBodyInMsg.subscribeTo(spiceObject.planetStateOutMsgs[1])
     ssyBACObject.scStateInMsg.subscribeTo(scObject.scStateOutMsg)
-    ssyBACObject.celBodyInMsg.subscribeTo(gravFactory.spiceObject.planetStateOutMsgs[1])
+    ssyBACObject.celBodyInMsg.subscribeTo(spiceObject.planetStateOutMsgs[1])
     if use2SunSensors:
         sszBACObject.scStateInMsg.subscribeTo(scObject.scStateOutMsg)
-        sszBACObject.celBodyInMsg.subscribeTo(gravFactory.spiceObject.planetStateOutMsgs[1])
+        sszBACObject.celBodyInMsg.subscribeTo(spiceObject.planetStateOutMsgs[1])
 
     # Vizard Visualization Option
     # ---------------------------

examples/scenarioAttitudeFeedback.py

@@ -247,7 +247,7 @@ def run(show_plots, useUnmodeledTorque, useIntGain, useKnownTorque, useCMsg):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     # setup extForceTorque module
     # the control torque is read in through the messaging system

examples/scenarioAttitudeFeedback2T.py

@@ -211,7 +211,7 @@ def run(show_plots, useUnmodeledTorque, useIntGain):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     # setup extForceTorque module
     # the control torque is read in through the messaging system

examples/scenarioAttitudeFeedback2T_TH.py

@@ -358,7 +358,7 @@ def run(show_plots, useDVThrusters):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     # setup extForceTorque module
     # the control torque is read in through the messaging system

examples/scenarioAttitudeFeedback2T_stateEffTH.py

@@ -260,7 +260,7 @@ def run(show_plots, useDVThrusters):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     # setup extForceTorque module
     # the control torque is read in through the messaging system

examples/scenarioAttitudeFeedbackRW.py

@@ -424,7 +424,7 @@ def run(show_plots, useJitterSimple, useRWVoltageIO):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     #
     # add RW devices

examples/scenarioAttitudeFeedbackRWPower.py

@@ -196,7 +196,7 @@ def run(show_plots, useRwPowerGeneration):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     #
     # add RW devices

examples/scenarioAttitudeGG.py

@@ -152,7 +152,7 @@ def run(show_plots):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     #
     #   initialize Spacecraft States with initialization variables

examples/scenarioAttitudeGuidance.py

@@ -280,7 +280,7 @@ def run(show_plots, useAltBodyFrame):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     #
     #   initialize Spacecraft States with initialization variables

examples/scenarioAttitudePrescribed.py

@@ -164,7 +164,7 @@ def run(show_plots, useAltBodyFrame):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     #
     #   initialize Spacecraft States with initialization variables

examples/scenarioAttitudeSteering.py

@@ -309,7 +309,7 @@ def run(show_plots, simCase):
     mu = earth.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     # add RW devices
     rwFactory = simIncludeRW.rwFactory()

examples/scenarioBasicOrbit.py

@@ -305,7 +305,7 @@ def run(show_plots, orbitCase, useSphericalHarmonics, planetCase):
     mu = planet.mu
 
     # Finally, the gravitational body must be connected to the spacecraft object.  This is done with
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
     # Here the complete list of gravitational bodies is automatically assigned to the spacecraft, regardless if
     # it is only one body like Earth or Mars, or a list of multiple bodies.
 

examples/scenarioBasicOrbitStream.py

@@ -156,7 +156,7 @@ def run(show_plots, liveStream, timeStep, orbitCase, useSphericalHarmonics, plan
     mu = planet.mu
 
     # attach gravity model to spacecraft
-    scObject.gravField.gravBodies = spacecraft.GravBodyVector(list(gravFactory.gravBodies.values()))
+    gravFactory.addBodiesTo(scObject)
 
     #
     #   setup orbit and simulation time