1. scenario_BasicOrbitMultiSat
1.1. Overview
This script sets up three spacecraft orbiting a planet (Earth or Mercury). The goal of the scenario is to
highlight the refactored BSK_Sim structure that allows for easy addition of several spacecraft,
demonstrate how to create a formation flying scenario with any number of spacecraft, and
show how to customize the environment, dynamics and flight software files.
The script is found in the folder basilisk/examples/MultiSatBskSim/scenariosMultiSat and is executed by using:
python3 scenario_BasicOrbitMultiSat.py
The simulation mimics the basic simulation in the earlier tutorials in scenario_BasicOrbit and scenario_BasicOrbitFormation. scenario_BasicOrbit introduces the use of the BSK_Sim structure and its advantages, and scenario_BasicOrbitFormation simulates a basic scenario with two spacecraft using the BSK_Sim structure. However, this last scenario hard codes both spacecraft into the dynamics and flight software (FSW) classes. While this works for a small number of spacecraft, it is not easily scalable. This example aims to show a more pipelined way of adding spacecraft that can be either homogeneous or heterogeneous (different dynamics and flight software modules from one another). Another advantage of these changes is that the simulation now has a separate process for the environment, dynamics and FSW. When Basilisk supports multi-threading the process evaluation, this will greatly reduce the time it takes to run the simulation with a large number of spacecraft.
In line with these changes, the environment is not embedded into the dynamics class, as each spacecraft has its own dynamics class. Therefore, a new environment class has also been created, where any changes can be made to accommodate different planets, ground locations, etc.
No flight software module is added in this scenario, only the environment and dynamics modules. However, for organization purposes the flight software module customization will also addressed. A more thorough review of the FSW class can be read in scenario_AttGuidMultiSat.
1.2. Configuring the scenario file
The simulation layout is very similar to the one used for the scenario_BasicOrbitFormation file. As stated
before, several simulation processes are created: one for the environment and two for each of the spacecraft, each
representing the dynamics and flight software modules. It is absolutely crucial that the environment model be created
first, then the dynamics model for each spacecraft and then the FSW model for each spacecraft. In this case, the
Environment files used are BSK_EnvironmentEarth and BSK_EnvironmentMercury, whereas the Dynamics
file used is the BSK_MultiSatDynamics. The environment used in the simulation can be changed with either the
Earth or Mercury flag on the run method. As stated before, the FSW file is not added in this scenario
to focus first on setting up the dynamics of a number of spacecraft. All these files have been
created for this specific formation flying implementation into Basilisk but can be changed to accommodate any changes to
the intended simulation.
After initializing the interfaces and making sure that the scenario_BasicOrbitMultiSat
class inherits from the modified BSKSim class, the initial conditions are configured using the
configure_initial_conditions method. This method cannot take advantage of the new BSK structure, and therefore the
initial conditions for each spacecraft must be hard coded. Three sets of orbital elements are created, each
corresponding to one spacecraft and can adapt to the planet that the spacecraft is orbiting. After that, the orbital
elements are converted to position and velocity and the initial conditions are set for each spacecraft.
After that the function that logs the outputs can be observed. Again, this looks very similar to
the log_outputs method in the scenario_BasicOrbitFormation file. However, there is one difference: since multiple
spacecraft are simulated, we must loop through each dynamics process and record each module. This makes the logging
variables be lists of arrays instead of simply arrays. The same is true for the FSW objects.
In the pull_outputs method, the logging variables (position of each spacecraft) are pulled and used to compute a 3D
plot with all the spacecraft’s orbits.
1.3. BSK_EnvironmentEarth and BSK_EnvironmentMercury files description
Both the BSK_EnvironmentEarth and BSK_EnvironmentMercury share the same structure, with a difference in the gravity bodies used: the first uses the Sun, Earth and the Moon, while the second one only uses the Sun and Mercury.
The gravity bodies are created using simIncludeGravBody and their information is overridden by the SPICE library. An eclipse module is set up using the gravitational bodies used in the simulation. A ground location (representing Boulder’s location on Earth) is also set to be used in flight software. All modules are added to the environment process.
1.4. BSK_MultiSatDynamics file description
Looking at the BSK_MultiSatDynamics file, it can be observed that the dynamics process for each spacecraft
consists of one tasks named DynamicsTaskX where X represents that spacecraft’s index. This task are added to the
corresponding dynamics process and an instance of a specific object is added.
The dynamics class creates a Module: spacecraft, Module: simpleNav, Module: reactionWheelStateEffector and Module: thrusterDynamicEffector objects. It also creates a Module: fuelTank module that uses truster information to show the status of the onboard fuel tank. Although no attitude guidance and control is implemented in this example, this class will be used in other scenarios that make use of those control surfaces (see scenario_AttGuidMultiSat and scenario_StationKeepingMultiSat).
The dynamics script also sets up a number of power-related modules such as Module: simpleSolarPanel, Module: simplePowerSink, Module: simpleBattery and Module: ReactionWheelPower.
The necessary connections between the environment and dynamics classes are also done in this file, such as adding the gravity bodies from the environment into the spacecraft object.
After that, each object is added to the corresponding task. As before, the message names are very important. The standardization of these names is the only way to properly connect the environment, dynamics and FSW messages properly.
1.5. BSK_MultiSatFsw file description
This file can be added in a similar way to the dynamics file. By adding this file, each spacecraft will have its own FSW process with specific guidance modes.
1.6. Illustration of Simulation Results
showPlots = True, numberSpacecraft=3, environment = 'Earth'
- scenario_BasicOrbitMultiSat.run(show_plots, numberSpacecraft, environment)[source]
The scenarios can be run with the followings setups parameters:
- Parameters:
show_plots (bool) – Determines if the script should display plots
numberSpacecraft (int) – Number of spacecraft in the simulation
environment (string) – Chooses which environment to set the simulation in. Options are “Earth” or “Mercury”