This script sets up a 3-DOF spacecraft which is orbiting a planet that has a magnetic field. The purpose is to illustrate how to create and setup the centered dipole magnetic field, as well as determine the magnetic field at a spacecraft location. The orbit setup is similar to that used in scenarioBasicOrbit.

The script is found in the folder basilisk/examples and executed by using:


Simulation Scenario Setup Details

The simulation layout is shown in the following illustration. A single simulation process is created which contains the spacecraft object. The spacecraft state message is connected to the magnetic field module which outputs the local magnetic field in inertial frame components.


When the simulation completes 2 plots are shown for each case. One plot always shows the inertial position vector components, while the second plot shows the local magnetic field vector components with respect to the inertial frame.

Note that the magnetic field module are zeroed, and appropriate parameters must be specified for the planet. The following code illustrates setting the Earth dipole parameters:

magModule.g10 = -30926.00 / 1e9 * 0.5  # Tesla
magModule.g11 =  -2318.00 / 1e9 * 0.5  # Tesla
magModule.h11 =   5817.00 / 1e9 * 0.5  # Tesla
magModule.planetRadius = 6371.2 * 1000  # meters

The python support file provides helper functions to setup command magnetic field environments including the centered dipole models for Mercury, Earth, Jupiter, Saturn, Uranus and Neptune.

The default planet’s position vector is assumed to be the inertial frame origin and an identity orientation matrix. If a different planet state message is required this can be specified through the optional input message planetPosInMsgName.

The magnetic field module can produce the magnetic field for a vector of spacecraft locations, not just for a single spacecraft. Let scObject be an instance of Module: spacecraft, then the spacecraft state output message is added to the magnetic field module through:


Note that this command can be repeated if the magnetic field should be evaluated for different spacecraft.

Every time a spacecraft is added to the magnetic field module, an automated output message name is created. For magModule is “CenteredDipole_0_data” as the ModelTag string is CenteredDipole and the spacecraft number is 0. This output name is created in the addSpacecraftToModel() function. However, if the default output name is used for the second planetary magnetic field model, then both module share the same output name and one will overwrite the others output. To ensure the second magnetic field has a unique output name, the default name is replaced with a unique message.

The reach of the magnetic field model is specified through the module variables envMinReach and envMaxReach. Their default values are -1 which turns off this feature, giving the magnetic field evaluation infinite reach. As the elliptical Earth scenario uses 2 Earth-fixed magnetic fields, we want magModule2 to only evaluate a magnetic field if the orbit radius is less than req*1.3. Similarly, for radii above req*1.3 we want the first magnetic field model to be used.

Illustration of Simulation Results

The following images illustrate the expected simulation run returns for a range of script configurations.

show_plots = True, orbitCase='circular', planetCase='Earth'
show_plots = True, orbitCase='elliptical', planetCase='Earth'

This case illustrates an elliptical Earth orbit inclination where 2 dipole magnetic fields are attached. One model acts above 1.3 Earth radius, and the other below that region.

show_plots = True, orbitCase='elliptical', planetCase='Jupiter'
../_images/scenarioMagneticFieldCenteredDipole1ellipticalJupiter.svg../_images/scenarioMagneticFieldCenteredDipole2ellipticalJupiter.svg, orbitCase, planetCase)[source]

At the end of the python script you can specify the following example parameters.

  • show_plots (bool) – Determines if the script should display plots

  • orbitCase (str) – {‘circular’, ‘elliptical’}

  • planetCase (str) – {‘Earth’, ‘Junpiter’}