BSK_Faults

Fault definitions for BskSim fault-injection scenarios.

This module provides FaultObject subclasses that can be assembled into a faultList (for example, in scenario_FaultList.py).

Each fault object encapsulates:

  1. A trigger time (simulation nanoseconds),

  2. The mutation applied to the dynamics/FSW model, and

  3. A one-time status message.

Usage pattern in scenarios:

  1. Instantiate one or more fault objects.

  2. Add them to a list.

  3. Call fault.addFaultToSimulation(sim, idx) for each element.

The base class registers each fault as an event through createNewEvent and executes the fault action at its configured time.

Indexing conventions:

  • Fault index arguments use 0-based indexing.

  • Reaction wheel indices must be in the range 0..3.

  • CSS sensor indices must be in the range 0..7.

  • Magnetometer axis indices must be in the range 0..2.

class BSK_Faults.CssSignalFault(time, type, cssIdx, name='cssSignalOff')[source]

Bases: FaultObject

Represents a coarse sun sensor (CSS) measurement fault.

The types of CSS faults are as follows: 1. The specified CSS measurement is turned off (“CSSFAULT_OFF”). 2. The CSS measurement is stuck at the current value (“CSSFAULT_STUCK_CURRENT”). 3. The CSS measurement is stuck at the maximum value (“CSSFAULT_STUCK_MAX”). 4. The CSS measurement is stuck at a random value (“CSSFAULT_STUCK_RAND”). 5. The CSS measurement is randomly altered (“CSSFAULT_RAND”).

Parameters:

  • time (float) – Simulation time (in nanoseconds) when the fault occurs.

  • type (str) – Type of CSS fault, one of: “CSSFAULT_OFF”, “CSSFAULT_STUCK_CURRENT”, “CSSFAULT_STUCK_MAX”, “CSSFAULT_STUCK_RAND”, or “CSSFAULT_RAND”.

  • cssIdx (list[int]) – Index (0, 1, 2, 3, 4, 5, 6, 7) of the affected CSS sensor.

  • name (str, optional) – Name identifier for the fault (default: “cssSignalOff”).

class BSK_Faults.DebrisImpactOff(time, name='DebrisImpactOff')[source]

Bases: FaultObject

Represents the end of a debris impact fault.

This fault resets the external force and torque applied by a previous debris impact (e.g., DebrisImpactOn) back to zero, effectively ending the impact event.

Parameters:

  • time (float) – Simulation time (in nanoseconds) when the impact effect ends.

  • name (str, optional) – Name identifier for the fault (default: “DebrisImpactOff”).

class BSK_Faults.DebrisImpactOn(time, debris_location, direction, mass, velocityMag=8000.0, name='DebrisImpactOn')[source]

Bases: FaultObject

Represents a debris impact fault on the spacecraft.

This fault simulates an impact from space debris at a specified location on the spacecraft body. The momentum transfer due to the impact generates both force and torque on the spacecraft.

Parameters:

  • time (float) – Simulation time (in nanoseconds) when the impact occurs.

  • debris_location (array_like) – Impact location in body coordinates [m] as a 3-element vector.

  • direction (array_like) – Impact direction in body coordinates as a 3-element vector. The vector is normalized internally.

  • mass (float) – Mass of the debris particle in kilograms (kg).

  • velocityMag (float, optional) – Magnitude of the debris velocity in meters per second (m/s) (default: 8e3 m/s).

  • name (str, optional) – Name identifier for the fault (default: “DebrisImpactOn”).

class BSK_Faults.MagPolarNoise(time, faultType, name='magPolarFault')[source]

Bases: FaultObject

Magnetometer fault model that emulates degradation effects in Earth’s polar regions.

This fault object modifies the behavior of a three-axis magnetometer (TAM) based on the spacecraft’s geomagnetic latitude. As the spacecraft enters high-latitude regions (\(|\mathrm{latitude}| \gtrsim 60\,\mathrm{deg}\)), the fault severity transitions smoothly from nominal to polar conditions using a sigmoid weighting function.

Depending on the selected fault type, the model can:

  • Increase sensor noise and random-walk bounds (“NOISE”)

  • Inject sporadic measurement spikes (“SPIKE”)

  • Apply both noise degradation and spiking behavior (“BOTH”)

The spacecraft position is obtained in the inertial frame, transformed into the Earth-fixed frame using SPICE-provided planet state information, and converted to geodetic latitude. Fault parameters are then interpolated between nominal and polar values based on latitude.

Parameters:

  • time (float) – Simulation time at which the fault is executed.

  • faultType (str) – Type of magnetometer fault to apply. Must be one of: {“NOISE”, “SPIKE”, “BOTH”}.

  • name (str, optional) – Name of the fault object (default is “magPolarFault”).

Notes

  • The latitude transition is centered at 60 degrees with a 5-degree smoothing width.

  • Noise and random-walk bounds are applied directly to the TAM model.

  • Spiking faults are enabled via the magnetometer fault-state interface.

  • This model assumes an Earth-centered mission and valid SPICE ephemerides.

class BSK_Faults.MagnetometerFault(time, faultType, faultyAxis, stuckValue=0.0, spikeProbability=0.01, spikeAmount=2.0, name='magnetometerFault')[source]

Bases: FaultObject

Represents a magnetometer sensor fault.

This fault simulates scenarios in which magnetometer measurements become inaccurate due to stuck readings or random spikes, depending on the selected fault type. It can affect one or more of the sensor’s three axes (x, y, z).

Parameters:

  • time (float) – Simulation time (in nanoseconds) when the fault occurs.

  • faultType (str) – Type of magnetometer fault. Supported types include: - “MAG_FAULT_STUCK_CURRENT” : Output held at the current value. - “MAG_FAULT_STUCK_VALUE” : Output fixed at a given constant value. - “MAG_FAULT_SPIKING” : Output intermittently spiking.

  • faultyAxis (int) – Axis affected by the fault (0–2), corresponding to x, y, z.

  • stuckValue (float, optional) – Constant value used when the fault type is “MAG_FAULT_STUCK_VALUE” (default: 0.0).

  • spikeProbability (float, optional) – Probability of a spike occurring at each time step when the fault type is “MAG_FAULT_SPIKING” (default: 0.01).

  • spikeAmount (float, optional) – Magnitude of the spike added to the nominal measurement when a spike occurs (default: 2.0).

  • name (str, optional) – Name identifier for the fault (default: “magnetometerFault”).

class BSK_Faults.RWBitFlipFault(time, bitFlipIdx, RW_Idx, elementIdx, name='RWBitFlipFault')[source]

Bases: FaultObject

Represents a reaction wheel control bit-flip fault.

This fault simulates a scenario in which a single bit in the reaction wheel control axis configuration is flipped.

Parameters:

  • time (float) – Simulation time (in nanoseconds) when the fault occurs.

  • bitFlipIdx (int) – Zero-based index of the bit to flip (0–15).

  • RW_Idx (int) – Index of the affected reaction wheel (0–3).

  • elementIdx (int) – Zero-based index of the axis to flip within the reaction wheel control (0–2).

  • name (str, optional) – Name identifier for the fault (default: “RWBitFlipFault”).

class BSK_Faults.RWGainBitFlipFault(time, bitFlipIdx, gainType, name='RWGainBitFlipFault')[source]

Bases: FaultObject

Represents a reaction wheel feedback gain bit-flip fault.

This fault simulates a scenario in which a single bit in the reaction wheel feedback gain configuration is flipped.

Parameters:

  • time (float) – Simulation time (in nanoseconds) when the fault occurs.

  • bitFlipIdx (int) – Zero-based index of the bit to flip (0–15).

  • gainType (str) – Type of gain affected, one of: - “K” : Proportional gain applied to MRP errors (rad/sec) - “P” : Rate error feedback gain (N·m·s) - “Ki” : Integral feedback on rate error (N·m)

  • name (str, optional) – Name identifier for the fault (default: “RWGainBitFlipFault”).

class BSK_Faults.RwFrictionFault(time, frictionMultiplier, wheelIdx, name='rwFriction')[source]

Bases: FaultObject

Represents a reaction wheel friction fault event.

This fault increases the friction in one of reaction wheels, reducing their effective torque output.

Parameters:

  • time (float) – Simulation time (in nanoseconds) when the fault occurs.

  • frictionMultiplier (float) – Multiplier applied to the reaction wheel friction. For example, 2.0 doubles the nominal friction.

  • wheelIdx (int) – Index (0, 1, 2, or 3) of the affected reaction wheel.

  • name (str, optional) – Name identifier for the fault (default: “rwFriction”).

class BSK_Faults.RwPowerFault(time, reducedLimit, wheelIdx, name='rwPowerLimited')[source]

Bases: FaultObject

Represents a reaction wheel power fault event.

This fault reduces the maximum power or torque output available from one or all reaction wheels.

Parameters:

  • time (float) – Simulation time (in nanoseconds) when the fault occurs.

  • reducedLimit (float) – Power limit value (in watts).

  • wheelIdx (int or str) – Index (0, 1, 2, or 3) of the affected reaction wheel(s), or “all” to apply to every wheel.

  • name (str, optional) – Name identifier for the fault (default: “rwPowerLimited”).