Module: magnetometer¶

Executive Summary¶

This document describes how Three-Axis Magnetometer (TAM) devices are modeled in the Basilisk software. The purpose of this module is to implement magnetic field measurements on the sensor frame $S$.

Module Assumptions and Limitations¶

Assumptions made in TAM module and the corresponding limitations are shown below:

Magnetic Field Model Inputs: The magnetometer sensor is limited with the used magnetic field model which are individual magnetic field models complex and having their own assumptions. The reader is referred to the cited literature to learn more about the model limitations and challenges.
Error Inputs: Since the error models rely on user inputs, these inputs are the most likely source of error in TAM output. Instrument bias would have to be measured experimentally or an educated guess would have to be made. The Gauss-Markov noise model has well-known assumptions and is generally accepted to be a good model for this application.
External Disturbances: Currently, the module does not consider the external magnetic field, so it is limited to the cases where this effect is not significant. This can be overcome by using magnetic field models taking into these effects account or adding it as an additional term.

Message Connection Descriptions¶

The following table lists all the module input and output messages. The module msg variable name is set by the user from python. The msg type contains a link to the message structure definition, while the description provides information on what this message is used for.

Module I/O Messages¶
Msg Variable Name	Msg Type	Description
magIntMsgName	magneticFieldSimMsg	Magnetic field input messager from one of the magnetic field models
stateIntMsgName	scPlusStatesSimMsg	Spacecraft state input message
tamDataOutMsgName	tamDataSimMsg	TAM sensor output message

Detailed Module Description¶

There are a multitude of magnetic field models. As all the magnetic field models are children of Module: magneticFieldBase base class, magnetometer can be created based on any of the magnetic field model.

Planet Centric Spacecraft Position Vector¶

For the following developments, the spacecraft location relative to the planet frame is required. Let $\boldsymbol r_{B/P}$ be the spacecraft position vector relative to the planet center. In the simulation the spacecraft location is given relative to an inertial frame origin $\cal{O}$. The planet centric position vector is computed using

\[\boldsymbol r_{B/P} = \boldsymbol r_{B/O} - \boldsymbol r_{P/O}\]

If no planet ephemeris message is specified, then the planet position vector $r_{P/O}$ is set to zero. Let $[PN]$ be the direction cosine matrix that relates the rotating planet-fixed frame relative to an inertial frame $\cal{N}$. The simulation provides the spacecraft position vector in inertial frame components. The planet centric position vector is then written in Earth-fixed frame components using

\[{}^{\cal{P}}{{\boldsymbol r}_{B/P}} = [PN] \ {}^{\cal{N}}{{\boldsymbol r}_{B/P}}\]

Magnetic Field Models¶

The truth of the magnetometer measurements in sensor frame coordinates with no errors are output as:

\[{}^{\cal{S}}{\boldsymbol B} = [SN]\ {}^{\cal{N}}{\boldsymbol B}\]

where $[SN]$ is the direction cosine matrix from $\cal{N}$ to $\cal{S}$, and ${{}^\cal{N}}{ \boldsymbol B}$ is the magnetic field vector of the magnetic field model in inertial frame components.

Sensor Error Modeling¶

The magnetic field vector of the magnetic field models is considered to be “truth”. So, the errors are applied on the “truth” values to simulate a real instrumentation:

\[\boldsymbol B_{measured} = (\boldsymbol B_{truth} + \boldsymbol e_{noise} + \boldsymbol e_{bias}) f_{scale}\]

where $\boldsymbol e_{noise}$ is the Gaussian noise, $\boldsymbol e_{bias}$ is the bias applied on the magnetic field measurements, and $f_{scale}$ is the scale factor applied on the measurements for linear scaling.

Saturation¶

Sensors might have specific saturation bounds for their measurements. It also prevents the sensor for giving a value less or higher than the possible hardware output. The saturated values are:

\[ \begin{align}\begin{aligned}\boldsymbol B_{{sat}_{max}} = \mbox{min}(\boldsymbol B_{measured}, \mbox{maxOutput})\\\boldsymbol B_{{sat}_{min}} = \mbox{max}(\boldsymbol B_{measured}, \mbox{minOutput})\end{aligned}\end{align} \]

This is the final output of the sensor module.

User Guide¶

General Module Setup¶

This section outlines the steps needed to add a Magnetometer module to a sim. First, one of the magnetic field models must be imported:

from Basilisk.simulation import magneticFieldCenteredDipole
magModule = magneticFieldCenteredDipole.MagneticFieldCenteredDipole()
magModule.ModelTag = "CenteredDipole"

and/or

from Basilisk.simulation import magneticFieldWMM
magModule = magneticFieldWMM.MagneticFieldWMM()
magModule.ModelTag = "WMM"

Then, the magnetic field measurements must be imported and initialized:

from Basilisk.simulation import magnetometer
testModule = magnetometer.Magnetometer()
testModule.ModelTag = "TAM_sensor"

The model can be added to a task like other simModels.

unitTestSim.AddModelToTask(unitTaskName, testModule)

Each Magnetometer module calculates the magnetic field based on the magnetic field and output state messages of a spacecraft. To add spacecraft to the magnetic field model the spacecraft state output message name is sent to the f$mbox{addSpacecraftToModel}f$ method:

scObject = spacecraftPlus.SpacecraftPlus()
scObject.ModelTag = "spacecraftBody"
magModule.addSpacecraftToModel(scObject.scStateOutMsgName)

Magnetic field data is transformed from inertial to body, then to the sensor frame. The transformation from $\cal B$ to $\cal S$ can be set via dcm_SB using the helper function:

setBodyToSensorDCM(psi, theta, phi)

where (psi, theta, phi) are classical 3-2-1 Euler angles that map from the body frame to the sensor frame $\cal S$.

Specifying TAM Sensor Corruptions¶

Three types of TAM sensor corruptions can be simulated. If not specified, all these corruptions are zeroed. To add a Gaussian noise component to the output, the variable senNoiseStd is set to a non-zero value. This is the standard deviation of Gaussian noise in Tesla.

Next, to simulate a constant bias, the variable senBias is set to a non-zero value. To simulate a linear scaling of the outputs, the variable scaleFactor is used.

Finally, to set saturation values, the variables maxOutput and minOutput are used. Minimum and maximum bounds for saturation are set to large values as $(-10^{200} \mbox{nT})$ and $(10^{200} \mbox{nT})$ respectively in order not to saturate the outputs by default.

class Magnetometer : public SysModel ¶

Public Functions

Magnetometer()¶: This is the constructor, setting variables to default values.

~Magnetometer()¶: This is the destructor, nothing to report here.

void SelfInit()¶

Method for initializing own messages.

This method performs all of the internal initialization for the model itself. Primarily that involves initializing the random number generator and creates the output message.

void CrossInit()¶

Method for initializing cross dependencies.

This method simply calls the LinkMessages method to ensure that input messages are matched correctly.

void Reset(uint64_t CurrentClock)¶

Method for reseting the module.

This method is used to reset the module.

Return

void

Parameters

CurrentSimNanos: The current simulation time from the architecture

void UpdateState(uint64_t CurrentSimNanos)¶

Method to update state for runtime.

This method is called at a specified rate by the architecture. It makes the calls to compute the current magnetic field information and write the output message for the rest of the model.

Parameters

CurrentSimNanos: The current simulation time from the architecture

void readInputMessages()¶

Method to read the input messages.

This method reads necessary input messages.

void computeTrueOutput()¶

Method to compute the true magnetic field vector.

This method computes the true sensed values for the sensor.

void computeMagData()¶

Method to get the magnetic field vector information.

This method computes the magnetic field vector information in the sensor frame.

void applySensorErrors()¶

Method to set the actual output of the sensor with errors.

This method takes the true values (trueValue) and converts it over to an errored value. It applies Gaussian noise, constant bias and scale factor to the truth.

void applySaturation()¶

Apply saturation effects to sensed output (floor and ceiling)

This method applies saturation using the given bounds.

void writeOutputMessages(uint64_t Clock)¶

Method to write the output message to the system.

This method writes the output messages.

Eigen::Matrix3d setBodyToSensorDCM(double yaw, double pitch, double roll)¶

Utility method to configure the sensor DCM.

This method composes the transformation matrix from Body to Sensor frame.

Public Members

std::string stateIntMsgName¶: [-] Message name for spacecraft state

std::string magIntMsgName¶: [-] Message name for magnetic field data

std::string tamDataOutMsgName¶: [-] Message name for TAM output data

Eigen::Matrix3d dcm_SB¶: [-] DCM from body frame to sensor frame

Eigen::Vector3d tam_S¶: [T] Magnetic field vector in sensor frame

Eigen::Vector3d sensedValue¶: [T] Measurement including perturbations

Eigen::Vector3d trueValue¶: [T] Measurement without perturbations

double scaleFactor¶: [-] Scale factor applied to sensor

Eigen::Vector3d senBias¶: [T] Sensor bias value

double senNoiseStd¶: [T] Sensor noise standard deviation value

uint64_t outputBufferCount¶: [-] Number of output msgs stored

Eigen::Vector3d walkBounds¶: [T] “3-sigma” errors to permit for states

double maxOutput¶: [T] Maximum output for saturation application

double minOutput¶: [T] Minimum output for saturation application

BSKLogger bskLogger¶: BSK Logging

Private Members

int64_t magIntMsgID¶: [-] Connect to input magnetic field message

int64_t stateIntMsgID¶: [-] Connect to input state message

int64_t tamDataOutMsgID¶: [-] Connect to output magnetometer data

MagneticFieldSimMsg magData¶: [-] Magnetic field model data

SCPlusStatesSimMsg stateCurrent¶: [-] Current spacecraft state

uint64_t numStates¶: [-] Number of States for Gauss Markov Models

GaussMarkov noiseModel¶: [-] Gauss Markov noise generation model

Saturate saturateUtility¶: [-] Saturation utility