C++ Module: spacecraftChargingDynamics

Executive Summary

The spacecraftChargingDynamics class is derived from the the parent class DynamicObject. This module integrates the electric potential of two spacecraft (a servicer and a target) in a plasma environment using a first order ordinary differential equation for each spacecraft. The charging model includes plasma electron current, plasma ion current, photoelectric current, and an optional electron beam current.

Note

while this module defaults all module member variables, there is a setter method available for each attribute.

Message Connection Descriptions

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

Module I/O Messages
Msg Variable Name	Msg Type	Description
servicerStateInMsg	SCStatesMsgPayload	Input spacecraft inertial state message for the servicer.
targetStateInMsg	SCStatesMsgPayload	Input spacecraft inertial state message for the target.
servicerSurfaceAreaInMsg	ProjectedAreaMsgPayload	Input message containing the total servicer surface area.
targetSurfaceAreaInMsg	ProjectedAreaMsgPayload	Input message containing the total target surface area.
servicerSunlitAreaInMsg	ProjectedAreaMsgPayload	Input message containing the total servicer sunlit area.
targetSunlitAreaInMsg	ProjectedAreaMsgPayload	Input message containing total target sunlit area.
electronBeamInMsg	ElectronBeamMsgPayload	Optional input message containing the electron beam parameters.
servicerPotentialOutMsg	VoltMsgPayload	Output message containing the servicer electric potential.
targetPotentialOutMsg	VoltMsgPayload	Output message containing the target electric potential.
servicerEBCurrentOutMsg	CurrentMsgPayload	Output message containing the servicer electron beam current.
targetEBCurrentOutMsg	CurrentMsgPayload	Output message containing the target electron beam current.
servicerPhotoelectricCurrentOutMsg	CurrentMsgPayload	Output message containing the servicer photoelectric current.
targetPhotoelectricCurrentOutMsg	CurrentMsgPayload	Output message containing the target photoelectric current.
servicerPlasmaElectronCurrentOutMsg	CurrentMsgPayload	Output message containing the servicer plasma electron current.
targetPlasmaElectronCurrentOutMsg	CurrentMsgPayload	Output message containing the target plasma electron current.
servicerPlasmaIonCurrentOutMsg	CurrentMsgPayload	Output message containing the servicer plasma ion current.
targetPlasmaIonCurrentOutMsg	CurrentMsgPayload	Output message containing the target plasma ion current.

Detailed Module Description

See the following journal paper for a detailed description of the charging equations implemented in this module.

Note

J. Hammerl and H. Schaub, “Servicing and Target Spacecraft Charging Behavior Due to Emission of an Electron Beam”.

The module computes the total current on each spacecraft as the sum of:

plasma electron current

plasma ion current

photoelectric current

optional electron beam current

For each spacecraft, total current is divided by the spacecraft capacitance and integrated to determine the spacecraft potential as a function of time.

Module Functions

Below is a list of functions this module performs:

Reads the servicer and target spacecraft inertial velocity states

Reads the servicer and target total surface area and sunlit area inputs

Reads the optional electron beam input message

Computes the plasma electron current for each spacecraft

Computes the plasma ion current for each spacecraft

Computes the electron beam current for each spacecraft

Computes the photoelectric current for each spacecraft

Integrates the servicer and target potential states forward in time

Writes the spacecraft potentials and all currents as output messages

Module Assumptions and Limitations

The module requires two spacecraft to be configured: servicer and target

Each spacecraft is represented by a fixed capacitance and a potential.

The module requires all state and area input messages (except the optional electronBeamInMsg) to be linked and written.

If a required input message is not linked or not written, the module logs an error and returns from UpdateState().

Test Description and Success Criteria

The unit test for this module is located at src/simulation/environment/spacecraftChargingDynamics/_UnitTest/test_spacecraftChargingDynamics.py. The test verifies that the spacecraft charging dynamics module correctly computes the different types of currents impacting both a target and servicer spacecraft. Specifically, this test checks that the module correctly computes the photoelectric current, electron beam current, plasma electron current, and plasma ion current acting on both spacecraft. While the module defaults many required variables, the user has the ability to configure all information describing the electrons, ions, and photons using setter methods.

The test varies the initial spacecraft potentials and sizes, the electron beam parameters, and the bulk plasma ion velocity. The test checks that the module correctly computes the photoelectric current, electron beam current, plasma electron current, and plasma ion current acting on both spacecraft.

User Guide

The following steps are required to set up the spacecraftChargingDynamics module in Python.

Import required Basilisk modules:

import numpy as np
from Basilisk.utilities import SimulationBaseClass
from Basilisk.utilities import macros
from Basilisk.architecture import astroConstants
from Basilisk.simulation import spacecraft
from Basilisk.simulation import spacecraftChargingDynamics
from Basilisk.architecture import messaging

Create the servicer spacecraft:

servicer_radius = 3.0  # [m]
mass_servicer = 500.0  # [kg]
length_servicer = servicer_radius  # [m]
width_servicer = servicer_radius  # [m]
height_servicer = servicer_radius  # [m]
I_servicer_11 = (1.0 / 12.0) * mass_servicer * (length_servicer * length_servicer + height_servicer * height_servicer)  # [kg m^2]
I_servicer_22 = (1.0 / 12.0) * mass_servicer * (length_servicer * length_servicer + width_servicer * width_servicer)  # [kg m^2]
I_servicer_33 = (1.0 / 12.0) * mass_servicer * (width_servicer * width_servicer + height_servicer * height_servicer)  # [kg m^2]

servicer_spacecraft = spacecraft.Spacecraft()
servicer_spacecraft.ModelTag = "ServicerSpacecraft"
servicer_spacecraft.hub.mHub = mass_servicer  # [kg]
servicer_spacecraft.hub.r_BcB_B = [0.0, 0.0, 0.0]  # [m]
servicer_spacecraft.hub.IHubPntBc_B = [[I_servicer_11, 0.0, 0.0], [0.0, I_servicer_22, 0.0], [0.0, 0.0, I_servicer_33]]  # [kg m^2]
servicer_spacecraft.hub.r_CN_NInit = [[10.0], [0.0], [0.0]]  # [m]
servicer_spacecraft.hub.v_CN_NInit = [[-5199.77710904224], [-3436.681645356935], [1041.576797498721]]  # [m/s]
servicer_spacecraft.hub.omega_BN_BInit = [[0.0], [0.0], [macros.D2R * 1.5]]  # [rad/s]
servicer_spacecraft.hub.sigma_BNInit = [[0.0], [0.0], [0.0]]

Create the target spacecraft:

target_radius = 2.0  # [m]
mass_target = 800.0  # [kg]
length_target = target_radius  # [m]
width_target = target_radius  # [m]
height_target = target_radius  # [m]
I_target_11 = (1.0 / 12.0) * mass_target * (length_target * length_target + height_target * height_target)  # [kg m^2]
I_target_22 = (1.0 / 12.0) * mass_target * (length_target * length_target + width_target * width_target)  # [kg m^2]
I_target_33 = (1.0 / 12.0) * mass_target * (width_target * width_target + height_target * height_target)  # [kg m^2]
target_spacecraft = spacecraft.Spacecraft()
target_spacecraft.ModelTag = "TargetSpacecraft"
target_spacecraft.hub.mHub = mass_target  # [kg]
target_spacecraft.hub.r_BcB_B = [0.0, 0.0, 0.0]  # [m]
target_spacecraft.hub.IHubPntBc_B = [[I_target_11, 0.0, 0.0], [0.0, I_target_22, 0.0], [0.0, 0.0, I_target_33]]  # [kg m^2]
target_spacecraft.hub.r_CN_NInit = [[5.0], [0.0], [0.0]]  # [m]
target_spacecraft.hub.v_CN_NInit = [[-5199.77710904224], [-3436.681645356935], [1041.576797498721]]  # [m/s]
target_spacecraft.hub.omega_BN_BInit = [[0.0], [0.0], [macros.D2R * -1.0]]  # [rad/s]
target_spacecraft.hub.sigma_BNInit = [[0.0], [0.0], [0.0]]

Create the total surface area and sunlit area messages for each spacecraft. (For complex articulating spacecraft, the C++ Module: facetedSpacecraftProjectedArea module should be used):

servicer_surface_area_msg_data = messaging.ProjectedAreaMsgPayload()
servicer_surface_area_msg_data.area = 4.0 * np.pi * servicer_radius * servicer_radius  # [m^2]
servicer_surface_area_msg = messaging.ProjectedAreaMsg().write(servicer_surface_area_msg_data)

target_surface_area_msg_data = messaging.ProjectedAreaMsgPayload()
target_surface_area_msg_data.area = 4.0 * np.pi * target_radius * target_radius  # [m^2]
target_surface_area_msg = messaging.ProjectedAreaMsg().write(target_surface_area_msg_data)

servicer_sunlit_area_msg_data = messaging.ProjectedAreaMsgPayload()
servicer_sunlit_area_msg_data.area = np.pi * servicer_radius * servicer_radius  # [m^2]
servicer_sunlit_area_msg = messaging.ProjectedAreaMsg().write(servicer_sunlit_area_msg_data)

target_sunlit_area_msg_data = messaging.ProjectedAreaMsgPayload()
target_sunlit_area_msg_data.area = np.pi * target_radius * target_radius  # [m^2]
target_sunlit_area_msg = messaging.ProjectedAreaMsg().write(target_sunlit_area_msg_data)

Create the electron beam input message (optional):

electron_beam_msg_data = messaging.ElectronBeamMsgPayload()
electron_beam_msg_data.energyEB = 10000.0  # [eV]
electron_beam_msg_data.currentEB = 250e-6  # [A]
electron_beam_msg_data.alphaEB = 0.5  # [-]
electron_beam_msg = messaging.ElectronBeamMsg().write(electron_beam_msg_data)

Create and configure the charging dynamics module:

capacitance = 1e-9  # [F]
charging_dynamics = spacecraftChargingDynamics.SpacecraftChargingDynamics()
charging_dynamics.ModelTag = "SpacecraftChargingDynamics"
charging_dynamics.setServicerPotentialInit(0.0)  # [Volts]
charging_dynamics.setTargetPotentialInit(0.0)  # [Volts]
charging_dynamics.setServicerCapacitance(capacitance)  # [farads]
charging_dynamics.setTargetCapacitance(capacitance)  # [farads]

charging_dynamics.setTempPhotoelectrons(2.0)  # [eV]
charging_dynamics.setFluxPhotoelectrons(1e-6)  # [A/m^2]
charging_dynamics.setTempElectrons(2.0)  # [eV]
charging_dynamics.setDensityElectrons(950000.0)  # [m^-3]
charging_dynamics.setTempIons(2.0)  # [eV]
charging_dynamics.setDensityIons(950000.0)  # [m^-3]
charging_dynamics.setBulkVelocityIons(400000.0)  # [m/s]

Connect all required input messages:

charging_dynamics.servicerStateInMsg.subscribeTo(servicer_spacecraft.scStateOutMsg)
charging_dynamics.targetStateInMsg.subscribeTo(target_spacecraft.scStateOutMsg)
charging_dynamics.electronBeamInMsg.subscribeTo(electron_beam_msg)
charging_dynamics.servicerSurfaceAreaInMsg.subscribeTo(servicer_surface_area_msg)
charging_dynamics.targetSurfaceAreaInMsg.subscribeTo(target_surface_area_msg)
charging_dynamics.servicerSunlitAreaInMsg.subscribeTo(servicer_sunlit_area_msg)
charging_dynamics.targetSunlitAreaInMsg.subscribeTo(target_sunlit_area_msg)

Add all modules to a task:

sim.AddModelToTask(task_name, servicer_spacecraft)
sim.AddModelToTask(task_name, target_spacecraft)
sim.AddModelToTask(task_name, charging_dynamics)

class SpacecraftChargingDynamics : public DynamicObject 

#include <spacecraftChargingDynamics.h>

spacecraft charging dynamics module

Public Functions

SpacecraftChargingDynamics()

Constructor.

Class constructor.

~SpacecraftChargingDynamics() = default: Destructor.

void initializeDynamics()

Method to initialize dynamics.

void Reset(uint64_t CurrentSimNanos)

Reset method.

void registerStates(DynParamManager &states)

Method to register states.

void writeOutputStateMessages(uint64_t clockTime)

Method to write output messages.

Method to write module output messages.

void UpdateState(uint64_t CurrentSimNanos)

Update method.

Module update method.

void equationsOfMotion(double integTimeSeconds, double timeStep)

Method defining equations of motion.

Method for the charging equations of motion

void preIntegration(uint64_t callTimeNanos) final

Pre-integration method.

Method for pre-integration steps.

Parameters:: integrateToThisTimeNanos – Time to integrate to

void postIntegration(uint64_t callTimeNanos) final

Post-integration method.

Method for post-integration steps.

Parameters:: integrateToThisTimeNanos – Time to integrate to

void setServicerPotentialInit(const double potentialInit)

Setter for the initial servicer potential.

Parameters:: potentialInit – [Volts] Servicer initial potential

void setTargetPotentialInit(const double potentialInit)

Setter for the initial target potential.

Parameters:: potentialInit – [Volts] Target initial potential

double getServicerPotentialInit() const

Getter for the initial servicer potential.

Getter for the servicer initial potential.

Returns:: double

double getTargetPotentialInit() const

Getter for the initial target potential.

Getter for the target initial potential.

Returns:: double

void setServicerCapacitance(const double capacitance)

Setter for the servicer capacitance.

Setter for the servicer spacecraft capacitance.

Parameters:: capacitance – [farad] Servicer spacecraft capacitance

void setTargetCapacitance(const double capacitance)

Setter for the target capacitance.

Setter for the target spacecraft capacitance.

Parameters:: capacitance – [farad] Target spacecraft capacitance

double getServicerCapacitance() const

Getter for the servicer capacitance.

Getter for the servicer spacecraft capacitance.

Returns:: double

double getTargetCapacitance() const

Getter for the target capacitance.

Getter for the target spacecraft capacitance.

Returns:: double

void setFluxPhotoelectrons(const double flux)

Setter for the photoelectron flux.

Parameters:: flux – [A/m^2] Photoelectron flux

void setTempPhotoelectrons(const double temp)

Setter for the photoelectron temperature.

Parameters:: temp – [eV] Photoelectron temperature

double getFluxPhotoelectrons() const

Getter for the photoelectron flux.

Returns:: double

double getTempPhotoelectrons() const

Getter for the photoelectron temperature.

Returns:: double

void setTempElectrons(const double temp)

Setter for the electron temperature.

Parameters:: temp – [eV] Electron temperature

double getTempElectrons() const

Getter for the electron temperature.

Returns:: double

void setDensityElectrons(const double density)

Setter for the electron density.

Parameters:: density – [m^-3] Electron density

double getDensityElectrons() const

Getter for the electron density.

Returns:: double

void setTempIons(const double temp)

Setter for the ion temperature.

Parameters:: temp – [eV] Ion temperature

double getTempIons() const

Getter for the ion temperature.

Returns:: double

void setDensityIons(const double density)

Setter for the ion density.

Parameters:: density – [m^-3] Ion density

double getDensityIons() const

Getter for the ion density.

Returns:: double

void setBulkVelocityIons(const double density)

Setter for the bulk ion velocity.

Parameters:: velocity – [m/s] Bulk ion velocity

double getBulkVelocityIons() const

Getter for the bulk ion velocity.

Returns:: double

Public Members

ReadFunctor<SCStatesMsgPayload> servicerStateInMsg: Servicer state input message.

ReadFunctor<SCStatesMsgPayload> targetStateInMsg: Target state input message.

ReadFunctor<ElectronBeamMsgPayload> electronBeamInMsg: Electron beam input message (optional).

ReadFunctor<ProjectedAreaMsgPayload> servicerSurfaceAreaInMsg: Servicer surface area input message.

ReadFunctor<ProjectedAreaMsgPayload> targetSurfaceAreaInMsg: Target surface area input message.

ReadFunctor<ProjectedAreaMsgPayload> servicerSunlitAreaInMsg: Total servicer sunlit facet area input message.

ReadFunctor<ProjectedAreaMsgPayload> targetSunlitAreaInMsg: Total target sunlit facet area input message.

Message<VoltMsgPayload> servicerPotentialOutMsg: Servicer potential (voltage) output message.

Message<VoltMsgPayload> targetPotentialOutMsg: Target potential (voltage) output message.

Message<CurrentMsgPayload> servicerEBCurrentOutMsg: Servicer electron beam current output message.

Message<CurrentMsgPayload> targetEBCurrentOutMsg: Target electron beam current output message.

Message<CurrentMsgPayload> servicerPhotoelectricCurrentOutMsg: Servicer photoelectric current output message.

Message<CurrentMsgPayload> targetPhotoelectricCurrentOutMsg: Target photoelectric current output message.

Message<CurrentMsgPayload> servicerPlasmaElectronCurrentOutMsg: Servicer plasma electron current output message.

Message<CurrentMsgPayload> targetPlasmaElectronCurrentOutMsg: Target plasma electron current output message.

Message<CurrentMsgPayload> servicerPlasmaIonCurrentOutMsg: Servicer plasma ion current output message.

Message<CurrentMsgPayload> targetPlasmaIonCurrentOutMsg: Target plasma ion current output message.

BSKLogger bskLogger: BSK Logging.

Private Functions

void computeCurrents()

Method to compute all electric currents.

Method for computing all currents acting on the spacecraft

void computeElectronBeamCurrent()

Method to compute electron beam current.

Method to compute electron beam currents

void computePhotoelectricCurrent()

Method to compute photoelectric current.

Method to compute photoelectric currents

double computePlasmaElectronCurrent(double sunlitArea, double spacecraftPotential)

Method to compute plasma electron current.

Method to compute plasma electron current

Parameters:

surfaceArea – [m^2] Spacecraft surface area
spacecraftPotential – [Volts] Spacecraft potential

Returns:

double

double computePlasmaIonCurrent(double surfaceArea, double sunlitArea, double spacecraftPotential, double v_BN_N_norm)

Method to compute plasma ion current.

Method to compute plasma ion current

Parameters:

surfaceArea – [m^2] Spacecraft surface area
sunlitArea – [m^2] Spacecraft sunlit area
spacecraftPotential – [Volts] Spacecraft potential
v_BN_N_norm – [m/s] Spacecraft inertial velocity norm

Returns:

double

Private Members

double servicerPotentialInit = {}: [Volts] Initial servicer potential

double targetPotentialInit = {}: [Volts] Initial target potential

double servicerCapacitance = {1e-9}: [farads] Servicer capacitance

double targetCapacitance = {1e-9}: [farads] Target capacitance

double servicerSurfaceArea = {}: [m^2] Servicer surface area

double targetSurfaceArea = {}: [m^2] Target surface area

double servicerSunlitArea = {}: [m^2] Servicer sunlit area

double targetSunlitArea = {}: [m^2] Target sunlit area

double tempPhotoelectrons = 2.0: [eV] Photoelectron temperature

double fluxPhotoelectrons = 1e-6: [A/m^2] Photoelectron flux

double tempElectrons = 2.0: [eV] Electron temperature

double densityElectrons = 950000: [m^-3] Electron density

double tempIons = 2.0: [eV] Ion temperature

double densityIons = 950000: [m^-3] Ion density

double bulkVelocityIons = {400000}: [m/s] Bulk ion velocity

double electronBeamEnergy = {}: [eV] Electron beam energy

double electronBeamCurrent = {}: [Amps] Electron beam current

double alphaEB = {}: [-] Scaling term for the fraction of current reaching the target

double v_SN_N_norm = {}: [m/s] Servicer inertial velocity norm

double v_TN_N_norm = {}: [m/s] Target inertial velocity norm

double servicerPotential = {}: [Volts] Servicer potential

double targetPotential = {}: [Volts] Target potential

double servicerEBCurrent = {}: [Amps] Servicer electron beam current

double targetEBCurrent = {}: [Amps] Target electron beam current

double servicerPhotoelectricCurrent = {}: [Amps] Servicer photoelectric current

double targetPhotoelectricCurrent = {}: [Amps] Target photoelectric current

double servicerPlasmaElectronCurrent = {}: [Amps] Servicer plasma electron current

double targetPlasmaElectronCurrent = {}: [Amps] Target plasma electron current

double servicerPlasmaIonCurrent = {}: [Amps] Servicer plasma ion current

double targetPlasmaIonCurrent = {}: [Amps] Target plasma ion current

StateData *servicerPotentialState = nullptr: State data container for servicer potential.

StateData *targetPotentialState = nullptr: State data container for target potential.

std::string nameOfServicerPotentialState: Name of servicer potential state.

std::string nameOfTargetPotentialState: Name of target potential state.