opengnc.fdir package

Submodules

opengnc.fdir.failure_accommodation module

Actuator accommodation and control allocation weight adjustment.

class opengnc.fdir.failure_accommodation.ActuatorAccommodation(B: ndarray, initial_weights: ndarray | None = None)

Bases: object

Actuator Fault Accommodation and Weighted Control Allocation.

Redistributes control efforts across healthy actuators in response to partial or total failures. Allocation Logic: $mathbf{u} = mathbf{W}^{-1} mathbf{B}^T (mathbf{B} mathbf{W}^{-1} mathbf{B}^T)^{-1} tau$.

Parameters:

• B (np.ndarray) – Control allocation (geometry) matrix of shape $(k, m)$.

• initial_weights (np.ndarray, optional) – Weight matrix $mathbf{W}$ (relative cost of using each actuator). Can be $(m, m)$ or diagonal $(m,)$. Defaults to identity.

allocate(tau: ndarray) → ndarray

Map desired torque/effort to actuator commands.

Parameters:

tau (np.ndarray) – Desired control effort $(k,)$.

Returns:

Actuator command vector $(m,)$.

Return type:

np.ndarray

set_health(index: int, status: float) → None

Update the health status of a specific actuator.

Parameters:

• index (int) – Actuator index.

• status (float) – Health factor in range [0, 1].

update_allocation_matrix() → ndarray

Compute the optimal weighted pseudo-inverse based on health.

Returns:

$mtimes k$ allocation matrix.

Return type:

np.ndarray

opengnc.fdir.parity_space module

Parity Space methods for Fault Detection and Isolation (FDI).

class opengnc.fdir.parity_space.ParitySpaceDetector(M: ndarray)

Bases: object

Fault Detection and Isolation (FDI) via Parity Space.

Measurement Model: $mathbf{y} = mathbf{M}mathbf{x} + mathbf{v} + mathbf{f}$

The Parity Matrix $mathbf{P}$ satisfies $mathbf{P}mathbf{M} = mathbf{0}$. The Parity Vector is $mathbf{p} = mathbf{P}mathbf{y}$.

Parameters:

M (np.ndarray) – Geometry matrix $(p times n)$, $p > n$.

detect_fault(y: ndarray, threshold: float) → bool

Detect fault by checking if $|mathbf{p}| > epsilon$.

Parameters:

• y (np.ndarray) – Measurement vector.

• threshold (float) – Fault detection threshold.

Returns:

True if a fault is detected.

Return type:

bool

get_parity_vector(y: ndarray) → ndarray

Compute the parity vector $mathbf{p} = mathbf{P} mathbf{y}$.

Parameters:

y (np.ndarray) – Measurement vector $(p, 1)$ or $(p,)$.

Returns:

Parity vector of shape $(p-n,)$.

Return type:

np.ndarray

isolate_fault(y: ndarray) → int

Isolate the faulty sensor by identifying the column of $mathbf{P}$ most aligned with the parity vector $mathbf{p}$.

Parameters:

y (np.ndarray) – Measurement vector.

Returns:

Index of the faulty sensor (0 to $p-1$), or -1 if no fault.

Return type:

int

opengnc.fdir.residual_generation module

Residual generation for fault detection using observers.

class opengnc.fdir.residual_generation.AnalyticalRedundancy

Bases: object

Utilities for Analytical Redundancy-based Fault Detection.

static check_threshold(r: ndarray, threshold: float) → bool

Threshold check for a residual vector.

Parameters:

• r (np.ndarray) – Residual vector.

• threshold (float) – Fault limit.

Returns:

True if $|mathbf{r}| > text{threshold}$.

Return type:

bool

static gyro_vs_quaternion_residual(q_dot_measured: ndarray, q_dot_calculated: ndarray) → ndarray

Residual between attitude rate kinematics and sensor differentiator.

Calculates $mathbf{r} = dot{mathbf{q}}_m - dot{mathbf{q}}_c$, where $dot{mathbf{q}}_c = frac{1}{2} mathbf{q} otimes mathbf{omega}$.

Parameters:

• q_dot_measured (np.ndarray) – Measured quaternion derivative.

• q_dot_calculated (np.ndarray) – Calculated derivative from gyros.

Returns:

Attitude residual vector.

Return type:

np.ndarray

class opengnc.fdir.residual_generation.ObserverResidualGenerator(A: ndarray, B: ndarray, C: ndarray, D: ndarray | None = None, L: ndarray | None = None, x0: ndarray | None = None)

Bases: object

Fault Residual Generation via Luenberger Observer.

Implements a linear observer to estimate system outputs and generate innovation-based residuals. Observer Dynamics: $hat{mathbf{x}}_{k+1} = mathbf{A} hat{mathbf{x}}_k + mathbf{B} mathbf{u}_k + mathbf{L} (mathbf{y}_k - hat{mathbf{y}}_k)$ Residual: $mathbf{r}_k = mathbf{y}_k - mathbf{C} hat{mathbf{x}}_k$.

Parameters:

• A (np.ndarray) – State transition matrix $(n, n)$.

• B (np.ndarray) – Input matrix $(n, m)$.

• C (np.ndarray) – Output matrix $(p, n)$.

• D (np.ndarray, optional) – Feedthrough matrix $(p, m)$. Defaults to zero.

• L (np.ndarray) – Observer gain matrix $(n, p)$.

• x0 (np.ndarray, optional) – Initial state estimate.

step(u: ndarray, y: ndarray) → ndarray

Advance observer and return residual $mathbf{r}_k$.

Parameters:

• u (np.ndarray) – Input vector $mathbf{u}_k$.

• y (np.ndarray) – Measurement vector $mathbf{y}_k$.

Returns:

Residual $mathbf{r}_k in mathbb{R}^p$.

Return type:

np.ndarray

opengnc.fdir.safe_mode module

Safe mode and fault detection logic for system mode transitions.

class opengnc.fdir.safe_mode.SafeModeCondition(check_fn: Callable[[], bool], trigger_time_sec: float = 0.0)

Bases: object

Trigger logic for Safe Mode state transitions.

Monitors a specific fault condition and confirms it based on a time-to-trigger threshold to avoid false positives.

Parameters:

• check_fn (Callable[[], bool]) – Function returning True if the condition is currently violated.

• trigger_time_sec (float, optional) – Confirmation threshold (s). Default is 0.0 (immediate).

update() → bool

Evaluate condition and return True if confirmation time is exceeded.

Returns:

True if safety trigger is active.

Return type:

bool

class opengnc.fdir.safe_mode.SafeModeLogic(initial_mode: SystemMode = SystemMode.NOMINAL)

Bases: object

Finite State Machine for Spacecraft Mode Management (FDIR).

Parameters:

initial_mode (SystemMode, optional) – Starting mode. Default is NOMINAL.

add_condition(name: str, condition: SafeModeCondition) → None

Register a new safety trigger.

Parameters:

• name (str) – Unique identifier for the condition.

• condition (SafeModeCondition) – Trigger implementation.

force_mode(mode: SystemMode, reason: str = 'Commanded') → None

Force a mode transition (e.g., via ground command).

Parameters:

• mode (SystemMode) – Target mode.

• reason (str, optional) – Rationale for the forced change.

update() → SystemMode

Process all conditions and update system mode.

Returns:

Current operating mode.

Return type:

SystemMode

class opengnc.fdir.safe_mode.SystemMode(value)

Bases: Enum

NOMINAL = 'NOMINAL'

RECOVERY = 'RECOVERY'

SAFE = 'SAFE'

Module contents

Fault Detection, Isolation & Recovery (FDIR) module.

class opengnc.fdir.ActuatorAccommodation(B: ndarray, initial_weights: ndarray | None = None)

Bases: object

Actuator Fault Accommodation and Weighted Control Allocation.

Redistributes control efforts across healthy actuators in response to partial or total failures. Allocation Logic: $mathbf{u} = mathbf{W}^{-1} mathbf{B}^T (mathbf{B} mathbf{W}^{-1} mathbf{B}^T)^{-1} tau$.

Parameters:

• B (np.ndarray) – Control allocation (geometry) matrix of shape $(k, m)$.

• initial_weights (np.ndarray, optional) – Weight matrix $mathbf{W}$ (relative cost of using each actuator). Can be $(m, m)$ or diagonal $(m,)$. Defaults to identity.

allocate(tau: ndarray) → ndarray

Map desired torque/effort to actuator commands.

Parameters:

tau (np.ndarray) – Desired control effort $(k,)$.

Returns:

Actuator command vector $(m,)$.

Return type:

np.ndarray

set_health(index: int, status: float) → None

Update the health status of a specific actuator.

Parameters:

• index (int) – Actuator index.

• status (float) – Health factor in range [0, 1].

update_allocation_matrix() → ndarray

Compute the optimal weighted pseudo-inverse based on health.

Returns:

$mtimes k$ allocation matrix.

Return type:

np.ndarray

class opengnc.fdir.AnalyticalRedundancy

Bases: object

Utilities for Analytical Redundancy-based Fault Detection.

static check_threshold(r: ndarray, threshold: float) → bool

Threshold check for a residual vector.

Parameters:

• r (np.ndarray) – Residual vector.

• threshold (float) – Fault limit.

Returns:

True if $|mathbf{r}| > text{threshold}$.

Return type:

bool

static gyro_vs_quaternion_residual(q_dot_measured: ndarray, q_dot_calculated: ndarray) → ndarray

Residual between attitude rate kinematics and sensor differentiator.

Calculates $mathbf{r} = dot{mathbf{q}}_m - dot{mathbf{q}}_c$, where $dot{mathbf{q}}_c = frac{1}{2} mathbf{q} otimes mathbf{omega}$.

Parameters:

• q_dot_measured (np.ndarray) – Measured quaternion derivative.

• q_dot_calculated (np.ndarray) – Calculated derivative from gyros.

Returns:

Attitude residual vector.

Return type:

np.ndarray

class opengnc.fdir.ObserverResidualGenerator(A: ndarray, B: ndarray, C: ndarray, D: ndarray | None = None, L: ndarray | None = None, x0: ndarray | None = None)

Bases: object

Fault Residual Generation via Luenberger Observer.

Implements a linear observer to estimate system outputs and generate innovation-based residuals. Observer Dynamics: $hat{mathbf{x}}_{k+1} = mathbf{A} hat{mathbf{x}}_k + mathbf{B} mathbf{u}_k + mathbf{L} (mathbf{y}_k - hat{mathbf{y}}_k)$ Residual: $mathbf{r}_k = mathbf{y}_k - mathbf{C} hat{mathbf{x}}_k$.

Parameters:

• A (np.ndarray) – State transition matrix $(n, n)$.

• B (np.ndarray) – Input matrix $(n, m)$.

• C (np.ndarray) – Output matrix $(p, n)$.

• D (np.ndarray, optional) – Feedthrough matrix $(p, m)$. Defaults to zero.

• L (np.ndarray) – Observer gain matrix $(n, p)$.

• x0 (np.ndarray, optional) – Initial state estimate.

step(u: ndarray, y: ndarray) → ndarray

Advance observer and return residual $mathbf{r}_k$.

Parameters:

• u (np.ndarray) – Input vector $mathbf{u}_k$.

• y (np.ndarray) – Measurement vector $mathbf{y}_k$.

Returns:

Residual $mathbf{r}_k in mathbb{R}^p$.

Return type:

np.ndarray

class opengnc.fdir.ParitySpaceDetector(M: ndarray)

Bases: object

Fault Detection and Isolation (FDI) via Parity Space.

Measurement Model: $mathbf{y} = mathbf{M}mathbf{x} + mathbf{v} + mathbf{f}$

The Parity Matrix $mathbf{P}$ satisfies $mathbf{P}mathbf{M} = mathbf{0}$. The Parity Vector is $mathbf{p} = mathbf{P}mathbf{y}$.

Parameters:

M (np.ndarray) – Geometry matrix $(p times n)$, $p > n$.

detect_fault(y: ndarray, threshold: float) → bool

Detect fault by checking if $|mathbf{p}| > epsilon$.

Parameters:

• y (np.ndarray) – Measurement vector.

• threshold (float) – Fault detection threshold.

Returns:

True if a fault is detected.

Return type:

bool

get_parity_vector(y: ndarray) → ndarray

Compute the parity vector $mathbf{p} = mathbf{P} mathbf{y}$.

Parameters:

y (np.ndarray) – Measurement vector $(p, 1)$ or $(p,)$.

Returns:

Parity vector of shape $(p-n,)$.

Return type:

np.ndarray

isolate_fault(y: ndarray) → int

Isolate the faulty sensor by identifying the column of $mathbf{P}$ most aligned with the parity vector $mathbf{p}$.

Parameters:

y (np.ndarray) – Measurement vector.

Returns:

Index of the faulty sensor (0 to $p-1$), or -1 if no fault.

Return type:

int

class opengnc.fdir.SafeModeCondition(check_fn: Callable[[], bool], trigger_time_sec: float = 0.0)

Bases: object

Trigger logic for Safe Mode state transitions.

Monitors a specific fault condition and confirms it based on a time-to-trigger threshold to avoid false positives.

Parameters:

• check_fn (Callable[[], bool]) – Function returning True if the condition is currently violated.

• trigger_time_sec (float, optional) – Confirmation threshold (s). Default is 0.0 (immediate).

update() → bool

Evaluate condition and return True if confirmation time is exceeded.

Returns:

True if safety trigger is active.

Return type:

bool

violated_start_time: float | None

class opengnc.fdir.SafeModeLogic(initial_mode: SystemMode = SystemMode.NOMINAL)

Bases: object

Finite State Machine for Spacecraft Mode Management (FDIR).

Parameters:

initial_mode (SystemMode, optional) – Starting mode. Default is NOMINAL.

add_condition(name: str, condition: SafeModeCondition) → None

Register a new safety trigger.

Parameters:

• name (str) – Unique identifier for the condition.

• condition (SafeModeCondition) – Trigger implementation.

conditions: dict[str, SafeModeCondition]

force_mode(mode: SystemMode, reason: str = 'Commanded') → None

Force a mode transition (e.g., via ground command).

Parameters:

• mode (SystemMode) – Target mode.

• reason (str, optional) – Rationale for the forced change.

history: list[dict[str, Any]]

update() → SystemMode

Process all conditions and update system mode.

Returns:

Current operating mode.

Return type:

SystemMode