FSW Sims

Basilisk flight software models (FSW) are given in bsk_rl.sim.fsw.

Flight software models serve as the interface between the operation of the satellite in simulation and the Gymnasium environment. While some FSW models add additional functionality to the satellite, such as imaging instrument control in ImagingFSWModel, others replace the default control laws with a more complex algorithms, such as SteeringFSWModel vis a vis BasicFSWModel.

Actions

Each FSW model has a number of actions that can be called to task the satellite. These actions are decorated with the action() decorator, which performs housekeeping tasks before the action is executed. These actions are the primary way to control the satellite simulation from other parts of the Gymnasium environment.

Properties

The FSW model provides a number of properties for easy access to the satellite state. These can be accessed directly from the dynamics model instance, or in the observation via the SatProperties observation.

Aliveness Checking

Certain functions in the FSW models are decorated with the aliveness_checker() decorator. These functions are called at each step to check if the satellite is still operational, returning true if the satellite is still alive.

action(func: Callable[[...], None]) → Callable[[Callable[[...], None]], Callable[[...], None]][source]

Decorator to reset the satellite software before executing an action.

Each time an action is called, the FSW tasks and dynamics models call their reset_for_action methods to ensure that the satellite is in a consistent state before the action is executed.

Action functions are typically called by Actions to task the satellite.

Parameters:

func (Callable[[...], None])

Return type:

Callable[[Callable[[…], None]], Callable[[…], None]]

class FSWModel(satellite: Satellite, fsw_rate: float, priority: int = 100, **kwargs)[source]

Bases: ABC

The abstract base flight software model.

One FSWModel is instantiated for each satellite in the environment each time the environment is reset and new simulator is created.

Parameters:

  • satellite (Satellite) – Satellite modelled by this model

  • fsw_rate (float) – [s] Rate of FSW simulation.

  • priority (int) – Model priority.

  • kwargs – Passed to task creation functions

property simulator: Simulator

Reference to the episode simulator.

property world: WorldModel

Reference to the episode world model.

property dynamics: DynamicsModel

Reference to the satellite dynamics model for the episode.

is_alive(log_failure=False) → bool[source]

Check if the FSW model has failed any aliveness requirements.

Returns:

True if the satellite FSW is still alive.

Return type:

bool

class BasicFSWModel(satellite: Satellite, fsw_rate: float, priority: int = 100, **kwargs)[source]

Bases: FSWModel

The abstract base flight software model.

One FSWModel is instantiated for each satellite in the environment each time the environment is reset and new simulator is created.

Parameters:

  • satellite (Satellite) – Satellite modelled by this model

  • fsw_rate (float) – [s] Rate of FSW simulation.

  • priority (int) – Model priority.

  • kwargs – Passed to task creation functions

action_drift() → None[source]

Decorated with action

Disable all tasks and do nothing.

Return type:

None

class SunPointTask(fsw, priority=99)[source]

Bases: Task

Task to generate a sun-pointing reference.

Parameters:

fsw (FSWModel)

name: str = 'sunPointTask'
setup_sun_pointing(nHat_B: Iterable[float], **kwargs) → None[source]

Configure the solar array sun-pointing task.

Parameters:

  • nHat_B (Iterable[float]) – Solar array normal vector.

  • kwargs – Passed to other setup functions.

Return type:

None

fsw: FSWModel
action_charge() → None[source]

Decorated with action

Charge battery by pointing the solar panels at the sun.

Return type:

None

class NadirPointTask(fsw, priority=98)[source]

Bases: Task

Task to generate nadir-pointing reference.

Parameters:

fsw (FSWModel)

name: str = 'nadirPointTask'
fsw: FSWModel
class RWDesatTask(fsw, priority=97)[source]

Bases: Task

Task to desaturate reaction wheels using thrusters.

Parameters:

fsw (FSWModel)

name: str = 'rwDesatTask'
setup_thruster_mapping(controlAxes_B: Iterable[float], thrForceSign: int, **kwargs) → None[source]

Configure the thruster mapping.

Parameters:

  • controlAxes_B (Iterable[float]) – Control unit axes.

  • thrForceSign (int) – Flag indicating if pos (+1) or negative (-1) thruster solutions are found.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_momentum_dumping(hs_min: float, maxCounterValue: int, thrMinFireTime: float, desatAttitude: str | None, **kwargs) → None[source]

Configure the momentum dumping algorithm.

Parameters:

  • hs_min (float) – [N*m*s] Minimum RW cluster momentum for dumping.

  • maxCounterValue (int) – Control periods between firing thrusters.

  • thrMinFireTime (float) – [s] Minimum thruster firing time.

  • desatAttitude (str | None) –

    Direction to point while desaturating:

    • "sun" points panels at sun

    • "nadir" points instrument nadir

    • None disables attitude control.

  • kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None[source]

Disable power draw for thrusters when a new action is selected.

Return type:

None

fsw: FSWModel
action_desat() → None[source]

Decorated with action

Charge while desaturating reaction wheels.

This action maneuvers the satellite into desatAttitude, turns on the thruster power sink, and enables the desaturation tasks. This action typically needs to be called multiple times to fully desaturate the wheels.

Return type:

None

class TrackingErrorTask(fsw, priority=90)[source]

Bases: Task

Task to convert an attitude reference to guidance.

Parameters:

fsw (FSWModel)

name: str = 'trackingErrTask'
fsw: FSWModel
class MRPControlTask(fsw, priority=80)[source]

Bases: Task

Task to control the satellite with reaction wheels.

Parameters:

fsw (FSWModel)

name: str = 'mrpControlTask'
setup_mrp_feedback_rwa(K: float, Ki: float, P: float, **kwargs) → None[source]

Set the MRP feedback control properties.

Parameters:

  • K (float) – Proportional gain.

  • Ki (float) – Integral gain.

  • P (float) – Derivative gain.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_rw_motor_torque(controlAxes_B: Iterable[float], **kwargs) → None[source]

Set parameters for finding motor torque from the control law.

Parameters:

  • controlAxes_B (Iterable[float]) – Control unit axes.

  • kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None[source]

MRP control is enabled by default for all tasks.

Return type:

None

fsw: FSWModel
class ImagingFSWModel(*args, **kwargs)[source]

Bases: BasicFSWModel

Adds instrument pointing and triggering control to FSW.

property c_hat_P

Instrument pointing direction in the planet frame.

property c_hat_H

Instrument pointing direction in the hill frame.

class LocPointTask(fsw, priority=96)[source]

Bases: Task

Task to point the instrument at ground targets.

name: str = 'locPointTask'
setup_location_pointing(inst_pHat_B: Iterable[float], **kwargs) → None[source]

Set the Earth location pointing guidance module.

Parameters:

  • inst_pHat_B (Iterable[float]) – Instrument pointing direction.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_instrument_controller(imageAttErrorRequirement: float, imageRateErrorRequirement: float, **kwargs) → None[source]

Set the instrument controller parameters.

The instrument controller is used to take an image when certain relative attitude requirements are met, along with the access requirements of the target (i.e. imageTargetMinimumElevation and imageTargetMaximumRange as set in setup_imaging_target).

Parameters:

  • imageAttErrorRequirement (float) – [MRP norm] Pointing attitude error tolerance for imaging.

  • imageRateErrorRequirement (float) – [rad/s] Rate tolerance for imaging. Disable with None.

  • kwargs – Passed to other setup functions.

Return type:

None

show_sensor(vizInterface=None, vizSupport=None)[source]

Visualize the sensor in Vizard.

reset_for_action() → None[source]

Reset pointing controller.

Return type:

None

fsw: FSWModel
action_image(r_LP_P: Iterable[float], data_name: str) → None[source]

Decorated with action

Attempt to image a target at a location.

This action sets the target attitude to one tracking a ground location. If the target is within the imaging constraints, an image will be taken and stored in the data buffer. The instrument power sink will be active as long as the task is enabled.

Args:

r_LP_P: [m] Planet-fixed planet relative target location. data_name: Data buffer to store image data to.

Parameters:

  • r_LP_P (Iterable[float])

  • data_name (str)

Return type:

None

Decorated with action

Attempt to downlink data.

This action points the satellite nadir and attempts to downlink data. If the satellite is in range of a ground station, data will be downlinked at the specified baud rate. The transmitter power sink will be active as long as the task is enabled.

Return type:

None

class ContinuousImagingFSWModel(*args, **kwargs)[source]

Bases: ImagingFSWModel

FSW model for continuous nadir scanning.

Instead of imaging point targets, this model is used to continuously scan the ground while pointing nadir.

class LocPointTask(*args, **kwargs)[source]

Bases: LocPointTask

Task to point nadir and trigger the instrument.

setup_instrument_controller(imageAttErrorRequirement: float, imageRateErrorRequirement: float, **kwargs) → None[source]

Set the instrument controller parameters for scanning.

As long as these two conditions are met, scanning will occur continuously.

Parameters:

  • imageAttErrorRequirement (float) – [MRP norm] Pointing attitude error tolerance for imaging.

  • imageRateErrorRequirement (float) – [rad/s] Rate tolerance for imaging. Disable with None.

  • kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None[source]

Reset scanning controller.

Return type:

None

action_nadir_scan() → None[source]

Decorated with action

Scan nadir.

This action points the instrument nadir and continuously adds data to the buffer as long as attitude requirements are met. The instrument power sink is active as long as the action is set.

Return type:

None

action_image(*args, **kwargs) → None[source]

Decorated with action

Disable action_image from parent class.

meta private:

Return type:

None

class SteeringFSWModel(*args, **kwargs)[source]

Bases: BasicFSWModel

FSW extending attitude control to use MRP steering instead of MRP feedback.

This class replaces the simple attitude feedback control law with a more sophisticated MRP steering control law.

class MRPControlTask(fsw, priority=80)[source]

Bases: Task

Task to control the satellite with reaction wheels.

Parameters:

fsw (FSWModel)

name: str = 'mrpControlTask'
setup_mrp_steering_rwa(K1: float, K3: float, omega_max: float, servo_Ki: float, servo_P: float, **kwargs) → None[source]

Define the control properties.

Parameters:

  • K1 (float) – MRP steering gain.

  • K3 (float) – MRP steering gain.

  • omega_max (float) – [rad/s] Maximum targetable spacecraft body rate.

  • servo_Ki (float) – Servo gain.

  • servo_P (float) – Servo gain.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_rw_motor_torque(controlAxes_B: Iterable[float], **kwargs) → None[source]

Define the motor torque from the control law.

Parameters:

  • controlAxes_B (Iterable[float]) – Control unit axes.

  • kwargs – Passed to other setup functions.

Return type:

None

reset_for_action() → None[source]

Keep MRP control enabled on action calls.

Return type:

None

fsw: FSWModel
class SteeringImagerFSWModel(*args, **kwargs)[source]

Bases: SteeringFSWModel, ImagingFSWModel

Convenience type that combines the imaging FSW model with MRP steering.

class MagicOrbitalManeuverFSWModel(*args, **kwargs)[source]

Bases: BasicFSWModel

Model that allows for instantaneous Delta V maneuvers.

property dv_available

Delta-V available for the satellite.

fuel_remaining() → bool[source]

Decorated with aliveness_checker

Check if the satellite has fuel remaining.

Return type:

bool

setup_fuel(dv_available_init: float, **kwargs)[source]

Set up available fuel for the satellite.

Parameters:

  • dv_available_init (float) – [m/s] Initial fuel level.

  • kwargs – Passed to other setup functions.

action_impulsive_thrust(dv_N: ndarray) → None[source]

Decorated with action

Thrust relative to the inertial frame.

Args:

dv_N: [m/s] Inertial Delta V.

Parameters:

dv_N (ndarray)

Return type:

None

class RSOInspectorFSWModel(*args, **kwargs)[source]

Bases: ContinuousImagingFSWModel

FSW model for continuous nadir scanning.

Instead of imaging point targets, this model is used to continuously scan the ground while pointing nadir.

set_target_rso(rso: Satellite) → None[source]

Set the RSO to point at.

Parameters:

rso (Satellite)

Return type:

None

class LocPointTask(*args, **kwargs)[source]

Bases: LocPointTask

Task to point at the RSO and trigger the instrument.

setup_location_pointing(inst_pHat_B: Iterable[float], **kwargs) → None[source]

Set the location pointing guidance module to point at the RSO.

The function set_target_rso must be called externally to connect the RSO to the pointing module.

Parameters:

  • inst_pHat_B (Iterable[float]) – Instrument pointing direction.

  • kwargs – Passed to other setup functions.

Return type:

None

setup_instrument_controller(imageAttErrorRequirement: float, imageRateErrorRequirement: float, **kwargs) → None[source]

Set the instrument controller parameters for scanning.

As long as these two conditions are met, scanning will occur continuously.

Parameters:

  • imageAttErrorRequirement (float) – [MRP norm] Pointing attitude error tolerance for imaging.

  • imageRateErrorRequirement (float) – [rad/s] Rate tolerance for imaging. Disable with None.

  • kwargs – Passed to other setup functions.

Return type:

None

action_inspect_rso() → None[source]

Decorated with action

Action to inspect the RSO.

Return type:

None