mbdlyb.functional.base

Base classes for functional analysis models.

This module defines the core node types and dependency relations for functional analysis in model-based diagnosis systems. It includes:

FunctionalNode: Base class for all functional model nodes

OperatingMode: Represents system operating modes

Function: Represents system functions

Hardware: Represents hardware components

DirectObservable: Represents directly observable phenomena

ObservedError: Represents observed error codes

DiagnosticTest: Represents diagnostic tests

DiagnosticTestResult: Represents diagnostic test results

Cluster: Container for a functional model network

FunctionalDependency: Base class for dependency relations

Various relation types: RealizesRelation, RequiredForRelation, AffectsRelation, etc.

ClusterReasonerView: Reasoner view for functional clusters

The module integrates with multiple reasoning engines (Bayesian networks, Tensor networks, Markov networks) to support probabilistic fault diagnosis and failure analysis.

Classes

`AffectsRelation`	Relation indicating that hardware degradation affects function operation.
`Cluster`	Container for a functional model network.
`ClusterReasonerView`	Specialized reasoner view for functional clusters.
`CommunicatesThroughRelation`	Relation representing inter-function communication carrying error information.
`DiagnosticTest`	Represents a diagnostic test that can be performed on the system.
`DiagnosticTestResult`	Represents the result or output of a diagnostic test.
`DirectObservable`	Represents a directly observable phenomenon.
`Function`	Represents a function in the system model.
`FunctionalDependency`	Base class for dependency relations in functional models.
`FunctionalNode`	Base class for all nodes in functional models.
`Hardware`	Represents a hardware component in the system model.
`IndicatedByRelation`	Relation indicating that a test result indicates node state.
`ObservableNode`	Base class for observable nodes in functional models.
`ObservedByRelation`	Relation indicating observation of a node state.
`ObservedError`	Represents an observed error code or failure indication.
`OperatingMode`	Represents an operating mode of a system.
`RealizesRelation`	Relation indicating that a hardware component realizes a function.
`ReportsErrorRelation`	Relation indicating that a function enables error reporting.
`RequiredForRelation`	Relation indicating functional dependency between two functions.
`ResultsInRelation`	Relation indicating that a diagnostic test produces a result.
`SelectOperatingModeRelation`	Relation indicating that a function operates in a specific operating mode.
`SubfunctionOfRelation`	Relation representing functional decomposition hierarchy.
`YieldsErrorRelation`	Relation indicating that a function failure yields an error code.

Module Contents

class mbdlyb.functional.base.AffectsRelation(source: MBDNode, target: MBDNode, net: MBDNet | None = None)

Bases: mbdlyb.formalisms.bayesnet.BNDependency, mbdlyb.formalisms.tensornet.TNDependency, mbdlyb.formalisms.markovnet.MNDependency, FunctionalDependency

Relation indicating that hardware degradation affects function operation.

Variables:

_label (str) – ‘affects’
source (Hardware) – The affected hardware.
target (Function) – The function affected.

source: Hardware

target: Function

class mbdlyb.functional.base.Cluster(name: str, cluster: Cluster | None = None)

Bases: mbdlyb.formalisms.bayesnet.BayesNet, mbdlyb.formalisms.tensornet.TensorNet, mbdlyb.formalisms.markovnet.MarkovNet, mbdlyb.MBDNet

Container for a functional model network.

A cluster is a directed acyclic graph (DAG) containing functional nodes (functions, hardware, observables, etc.) and dependency relations. Clusters support multiple reasoning engines (Bayesian, Tensor, Markov networks) and operating mode management.

Variables:

elements (dict[str, Union[FunctionalNode, Cluster]]) – Named elements in this cluster.
_opmsets (dict[OpmSet, MBDNode]) – Mapping from operating mode sets to their nodes.
relations (list[FunctionalDependency]) – All dependency relations in the cluster.

add_element(element: mbdlyb.MBDElement)

Add an element to this cluster.

If the element is an OperatingMode, registers it in the operating mode set mapping.

Parameters:: element (MBDElement) – Element to add to the cluster.

create_reasoner_view() → mbdlyb.MBDNetReasonerView

Create a reasoner view for this cluster.

Returns:: A ClusterReasonerView instance.
Return type:: MBDNetReasonerView

filter_operating_modes(operating_modes: list[str]) → tuple[set[mbdlyb.MBDNode], set[FunctionalDependency]]

Filter the model to only include active operating modes.

Removes nodes and relations that are disabled by the selected operating modes in a 5-step process: 1. Remove disabled dependency relations 2. Remove test-result nodes with removed indicated-by/yields-error relations 3. Remove function nodes with removed subfunction relations 4. Remove isolated nodes without any relations 5. Remove diagnostic tests without results

Parameters:: operating_modes (list[str]) – List of operating mode names that are active.
Returns:: Removed nodes and relations.
Return type:: tuple[set[MBDNode], set[FunctionalDependency]]

get_all_opm_nodes() → dict[mbdlyb.functional.operating_mode.OpmSet, mbdlyb.MBDNode]

Get all operating mode nodes in this cluster.

Returns:: Mapping from OpmSet to OperatingMode node.
Return type:: dict[OpmSet, MBDNode]

get_opm_node(fqn: mbdlyb.fqn.FQN) → mbdlyb.MBDNode | None

Get an operating mode node by its fully qualified name.

Parameters:: fqn (FQN) – Fully qualified name of the operating mode node.
Returns:: The operating mode node, or None if not found.
Return type:: Optional[MBDNode]

get_opm_node_from_set(opm_set: mbdlyb.functional.operating_mode.OpmSet) → mbdlyb.MBDNode | None

Get the operating mode node for a specific OpmSet.

Parameters:: opm_set (OpmSet) – The operating mode set.
Returns:: The operating mode node, or None if not found.
Return type:: Optional[MBDNode]

propagate_operating_modes(verbose=False)

Propagate operating mode constraints throughout the model.

Infers operating modes on dependency relations through four propagation steps: 1. Propagate between function nodes via required-for and subfunction relations 2. Propagate from functions to hardware via realizes and affects relations 3. Propagate from yields-error to reports-error relations 4. Propagate from indicated-by to results-in relations

Parameters:: verbose (bool) – If True, print inferred operating modes. Defaults to False.

elements: dict[str, FunctionalNode | Cluster]

relations: list[FunctionalDependency]

class mbdlyb.functional.base.ClusterReasonerView(net: Cluster)

Bases: mbdlyb.MBDNetReasonerView

Specialized reasoner view for functional clusters.

Performs model transformations to make functional clusters suitable for probabilistic reasoning, including cycle elimination, functional decomposition handling, and error reporting unfolding.

Variables:

net (Cluster) – The cluster being reasoned over.
_dropped_functional_decomposition_functions (list[Function]) – Functions removed during decomposition cleaning.
_dropped_functional_decomposition_relations (list[SubfunctionOfRelation]) – Relations removed during decomposition cleaning.
_cycles (list[list[Function]]) – Detected cycles in function dependencies.
_cycle_functions (list[Optional[Function]]) – Cycle placeholders.
_cycle_relations (list[Optional[RequiredForRelation]]) – Cycle relation placeholders.
_duplicated_reporting_functions (dict[Function, set[Function]]) – Duplicated reporting functions.
_duplicated_reporting_chains (dict[RequiredForRelation, set[RequiredForRelation]]) – Duplicated chains.
_duplicated_reporting_dependencies (dict[FunctionalDependency, set[FunctionalDependency]]) – Duplicated dependencies.

net: Cluster

class mbdlyb.functional.base.CommunicatesThroughRelation(source: mbdlyb.MBDNode, target: mbdlyb.MBDNode, error_codes: list[ObservedError] | None = None, weight: float = 1.0, net: Cluster | None = None)

Bases: FunctionalDependency

Relation representing inter-function communication carrying error information.

Represents error propagation through communication between functions.

Variables:

_label (str) – ‘communicates_through’
_error_codes (list[ObservedError]) – Error codes propagating through communication.
source (Function) – The communicating function.
target (Function) – The function receiving communication.

create()

Create this relation and register error codes.

Adds this relation to the observation paths of its error codes.

remove()

Remove this relation and unregister error codes.

Removes this relation from the observation paths of its error codes.

property error_codes: list[ObservedError]

Get the error codes propagating through this communication.

Returns:: Error codes carried by this communication.
Return type:: list[ObservedError]

property label: str

Get label with associated error codes.

Returns:: Label including error code list.
Return type:: str

source: Function

target: Function

class mbdlyb.functional.base.DiagnosticTest(name: str, fixed_cost: dict[str, float], preconditions: dict[str, bool], cluster: Cluster)

Bases: FunctionalNode

Represents a diagnostic test that can be performed on the system.

Diagnostic tests are actions taken to evaluate the state of functions and hardware. They have fixed costs and preconditions required before execution.

Variables:

fixed_cost (dict[str, float]) – Fixed costs by type (e.g., ‘time’, ‘money’).
preconditions (dict[str, bool]) – Conditions required for test execution.

get_fixed_cost(cost_type: str | None = None) → float

Get the fixed cost of performing this diagnostic test.

If cost_type is specified, returns only that cost type. Otherwise returns the sum of all cost types.

Parameters:: cost_type (Optional[str]) – Specific cost type to retrieve. Defaults to None.
Returns:: The fixed cost value or sum of costs.
Return type:: float

fixed_cost: dict[str, float]

preconditions: dict[str, bool]

property test_results: list[DiagnosticTestResult]

Get all results produced by this diagnostic test.

Returns:: Test result nodes related via ResultsInRelation.
Return type:: list[DiagnosticTestResult]

class mbdlyb.functional.base.DiagnosticTestResult(name: str, states: list[str], fp_rate: float, fn_rate: float, cluster: Cluster)

Bases: ObservableNode

Represents the result or output of a diagnostic test.

Test results are observations that show whether a diagnostic test passed or failed. They are produced by DiagnosticTest nodes.

property test: DiagnosticTest

Get the diagnostic test that produces this result.

Returns:: The test node related via ResultsInRelation.
Return type:: DiagnosticTest

class mbdlyb.functional.base.DirectObservable(name: str, states: list[str], fp_rate: float, fn_rate: float, cluster: Cluster)

Bases: ObservableNode

Represents a directly observable phenomenon.

Direct observables are measurements or observations that directly indicate the state of system components.

class mbdlyb.functional.base.Function(name: str, states: list[str], cluster: Cluster)

Bases: mbdlyb.formalisms.bayesnet.BayesAutoSplitNode, mbdlyb.formalisms.tensornet.TensorAutoSplitNode, mbdlyb.formalisms.markovnet.MarkovAutoSplitNode, FunctionalNode

Represents a function in the system model.

Functions are the core elements of functional models, representing capabilities or behaviors that the system can perform. Functions can have subfunctions (functional decomposition) and can realize hardware components.

Variables:

DEFAULT_STATES (list[str]) – Default states [‘Ok’, ‘NOk’].
_split_preserve_classes (list) – Classes to preserve during splitting (OperatingMode).
false_positive_weight (float) – Weight for false positive errors.

superfunction_chain(as_fqn: bool = False) → list[list[Function | mbdlyb.fqn.FQN]]

Get all chains of superfunctions up to root functions.

Parameters:: as_fqn (bool) – If True, return FQN objects instead of Function objects. Defaults to False.
Returns:: Chains of superfunctions, one per direct superfunction.
Return type:: list[list[Union[Function, FQN]]]

valid_parent_relation(relation: mbdlyb.MBDDependency) → bool

Validate if a dependency relation is valid for this function.

Parameters:

relation (MBDDependency) – The dependency relation to validate.

Returns:

True if relation is a FunctionalDependency or a normalized: numerical node relation.

Return type:

bool

DEFAULT_STATES = ['Ok', 'NOk']

false_positive_weight: float = 0.0

property has_subfunctions: bool

Check if this function has subfunctions.

Returns:: True if this function has any subfunction_of relations.
Return type:: bool

property has_superfunctions: bool

Check if this function has superfunctions.

Returns:: True if this function is a subfunction of other functions.
Return type:: bool

property subfunctions: list[Function]

Get all subfunctions of this function.

Returns:: List of functions this function depends on.
Return type:: list[Function]

property superfunctions: list[Function]

Get all superfunctions of this function.

Returns:: List of functions that depend on this function.
Return type:: list[Function]

class mbdlyb.functional.base.FunctionalDependency(source: mbdlyb.MBDNode, target: mbdlyb.MBDNode, weight: float = 1.0, net: Cluster | None = None, operating_modes: mbdlyb.functional.operating_mode.OpmLogic | None = None)

Bases: mbdlyb.MBDDependency

Base class for dependency relations in functional models.

Represents dependencies between functional nodes with optional operating mode constraints and weights. Supports both explicit and inferred operating modes.

Variables:

weight (float) – Strength or probability weight of the dependency.
_operating_modes (OpmLogic) – Explicitly specified operating mode constraints.
_inferred_opm (Optional[OpmLogic]) – Inferred operating mode constraints.

set_inferred_operating_modes(operating_modes: mbdlyb.functional.operating_mode.OpmLogic)

Set the inferred operating mode constraints.

Parameters:: operating_modes (OpmLogic) – The inferred operating mode constraints.

property inferred_operating_modes: mbdlyb.functional.operating_mode.OpmLogic

Get the inferred operating mode constraints.

Returns:: Inferred operating mode logic expression.
Return type:: OpmLogic

property label: str

Get the label for this dependency.

Includes explicit or inferred operating mode constraints if present.

Returns:: Label string, optionally with operating mode constraints.
Return type:: str

property operating_modes: mbdlyb.functional.operating_mode.OpmLogic

Get the explicit operating mode constraints.

Returns:: Operating mode logic expression.
Return type:: OpmLogic

weight: float = 1.0

class mbdlyb.functional.base.FunctionalNode(name: str, states: list[T], net: MBDNet)

Bases: mbdlyb.MBDNode

Base class for all nodes in functional models.

Functional nodes are the basic building blocks of functional models and represent various aspects of a system such as functions, hardware, observables, and tests. All functional nodes support operating modes.

Variables:

DEFAULT_STATES (list[str]) – Default state values for this node type.
_EQ_MAP (dict) – Mapping from node class names to equivalent/ok states.
_operating_modes (OpmSet) – The operating modes applicable to this node.
parent_relations (set[FunctionalDependency]) – Incoming dependency relations.
child_relations (set[FunctionalDependency]) – Outgoing dependency relations.

set_operating_modes(operating_modes: mbdlyb.functional.operating_mode.OpmSet)

Set the operating modes for this node.

Parameters:: operating_modes (OpmSet) – Operating modes to assign to this node.

DEFAULT_STATES: list[str] = []

child_relations: set[FunctionalDependency]

property operating_modes: mbdlyb.functional.operating_mode.OpmSet

Get the operating modes for this node.

Returns:: Set of operating modes.
Return type:: OpmSet

parent_relations: set[FunctionalDependency]

class mbdlyb.functional.base.Hardware(name: str, fault_rates: dict[str, float], cluster: Cluster)

Bases: mbdlyb.formalisms.bayesnet.BayesNode, mbdlyb.formalisms.tensornet.TensorNode, mbdlyb.formalisms.markovnet.MarkovNode, FunctionalNode

Represents a hardware component in the system model.

Hardware components have failure modes with associated fault rates. They can realize one or more functions in the system.

Variables:

DEFAULT_STATES (list[str]) – Default states with ‘Healthy’ as the only state.
fault_rates (dict[str, float]) – Mapping from fault state names to fault rates.

DEFAULT_STATES = ['Healthy']

fault_rates: dict[str, float]

property is_elementary: bool

Check if this hardware is elementary (has no subfunctions).

Returns:: True if this hardware realizes only functions without subfunctions.
Return type:: bool

class mbdlyb.functional.base.IndicatedByRelation(source: MBDNode, target: MBDNode, net: MBDNet | None = None)

Bases: mbdlyb.formalisms.bayesnet.BNDependency, mbdlyb.formalisms.tensornet.TNDependency, mbdlyb.formalisms.markovnet.MNDependency, FunctionalDependency

Relation indicating that a test result indicates node state.

Variables:

_label (str) – ‘indicated_by’
source (Union[Hardware, Function]) – The indicated component.
target (DiagnosticTestResult) – The test result indicating state.

source: Hardware | Function

target: DiagnosticTestResult

class mbdlyb.functional.base.ObservableNode(name: str, states: list[str], fp_rate: float, fn_rate: float, cluster: Cluster)

Bases: mbdlyb.formalisms.bayesnet.BayesNode, mbdlyb.formalisms.tensornet.TensorNode, mbdlyb.formalisms.markovnet.MarkovNode, FunctionalNode

Base class for observable nodes in functional models.

Observable nodes represent phenomena that can be observed or measured to assess the state of functions and hardware. They have false positive and false negative rates.

Variables:

DEFAULT_STATES (list[str]) – Default states [‘Ok’, ‘NOk’].
fp_rate (float) – False positive rate (observing failure when healthy).
fn_rate (float) – False negative rate (not observing failure when faulty).

DEFAULT_STATES = ['Ok', 'NOk']

fn_rate: float = 0.0

fp_rate: float = 0.0

class mbdlyb.functional.base.ObservedByRelation(source: MBDNode, target: MBDNode, net: MBDNet | None = None)

Bases: mbdlyb.formalisms.bayesnet.BNDependency, mbdlyb.formalisms.tensornet.TNDependency, mbdlyb.formalisms.markovnet.MNDependency, FunctionalDependency

Relation indicating observation of a node state.

Variables:

_label (str) – ‘observed_by’
source (Union[Hardware, Function]) – The observed component.
target (DirectObservable) – The observable indicating its state.

source: Hardware | Function

target: DirectObservable

class mbdlyb.functional.base.ObservedError(name: str, states: list[str], fp_rate: float, fn_rate: float, error_code: str, cluster: Cluster)

Bases: DirectObservable

Represents an observed error code or failure indication.

Observed errors are error codes or indicators that show when functions have failed. They have an associated error code identifier and can be observed through various observation paths (required-for and communicates-through relations).

Variables:

DEFAULT_STATES (list[str]) – Default states [‘Absent’, ‘Present’].
error_code (str) – Unique identifier for this error code.
observation_path (set) – Relations through which this error can be observed.

DEFAULT_STATES = ['Absent', 'Present']

property enabling_functions: list[Function]

Get functions that must be Ok to enable error reporting.

Returns:: Functions related via ReportsErrorRelation.
Return type:: list[Function]

error_code: str

observation_path: set[RequiredForRelation | CommunicatesThroughRelation]

property observed_function: Function

Get the function that yields this error.

Returns:: The function related via YieldsErrorRelation.
Return type:: Function

class mbdlyb.functional.base.OperatingMode(name: str, operating_modes: list[str], cluster: Cluster)

Bases: mbdlyb.formalisms.bayesnet.BayesNode, mbdlyb.formalisms.tensornet.TensorNode, mbdlyb.formalisms.markovnet.MarkovNode, FunctionalNode

Represents an operating mode of a system.

Operating modes define different states or configurations in which a system can operate. Each mode represents a mutually exclusive set of possible values.

Variables:: opm_set (OpmSet) – The set of operating mode values.

opm_set: mbdlyb.functional.operating_mode.OpmSet

class mbdlyb.functional.base.RealizesRelation(source: MBDNode, target: MBDNode, net: MBDNet | None = None)

Bases: mbdlyb.formalisms.bayesnet.BNDependency, mbdlyb.formalisms.tensornet.TNDependency, mbdlyb.formalisms.markovnet.MNDependency, FunctionalDependency

Relation indicating that a hardware component realizes a function.

Variables:

_label (str) – ‘realizes’
source (Hardware) – The hardware component.
target (Function) – The function realized.

source: Hardware

target: Function

class mbdlyb.functional.base.ReportsErrorRelation(source: MBDNode, target: MBDNode, net: MBDNet | None = None)

Bases: mbdlyb.formalisms.bayesnet.BNDependency, mbdlyb.formalisms.tensornet.TNDependency, mbdlyb.formalisms.markovnet.MNDependency, FunctionalDependency

Relation indicating that a function enables error reporting.

Variables:

_label (str) – ‘reports_error’
source (Function) – The enabling function.
target (ObservedError) – The error code being reported.

source: Function

target: ObservedError

class mbdlyb.functional.base.RequiredForRelation(source: mbdlyb.MBDNode, target: mbdlyb.MBDNode, operating_modes: mbdlyb.functional.operating_mode.OpmLogic | None = None, error_codes: list[ObservedError] | None = None, weight: float = 1.0, net: Cluster | None = None)

Bases: mbdlyb.formalisms.bayesnet.BNDependency, mbdlyb.formalisms.tensornet.TNDependency, mbdlyb.formalisms.markovnet.MNDependency, FunctionalDependency

Relation indicating functional dependency between two functions.

Represents that one function must work for another to work. Can track error codes that propagate through this dependency.

Variables:

_label (str) – ‘required_for’
source (Function) – The required function.
target (Function) – The dependent function.
error_codes (list[ObservedError]) – Error codes propagating through this relation.

create()

Create this relation and register error codes.

Adds this relation to the observation paths of its error codes.

remove()

Remove this relation and unregister error codes.

Removes this relation from the observation paths of its error codes.

error_codes: list[ObservedError]

property label: str

Get label with associated error codes.

Returns:: Label including error code indicators.
Return type:: str

source: Function

target: Function

class mbdlyb.functional.base.ResultsInRelation(source: mbdlyb.MBDNode, target: mbdlyb.MBDNode, weight: float = 1.0, net: Cluster | None = None, operating_modes: mbdlyb.functional.operating_mode.OpmLogic | None = None)

Bases: FunctionalDependency

Relation indicating that a diagnostic test produces a result.

Variables:

_label (str) – ‘results_in’
source (DiagnosticTest) – The test.
target (DiagnosticTestResult) – The result.

source: DiagnosticTest

target: DiagnosticTestResult

class mbdlyb.functional.base.SelectOperatingModeRelation(source: MBDNode, target: MBDNode, net: MBDNet | None = None)

Bases: mbdlyb.formalisms.bayesnet.BNDependency, mbdlyb.formalisms.tensornet.TNDependency, mbdlyb.formalisms.markovnet.MNDependency, FunctionalDependency

Relation indicating that a function operates in a specific operating mode.

Variables:

_label (str) – ‘select’
source (OperatingMode) – The operating mode.
target (Function) – The function operating in this mode.

source: OperatingMode

target: Function

class mbdlyb.functional.base.SubfunctionOfRelation(source: MBDNode, target: MBDNode, net: MBDNet | None = None)

Bases: mbdlyb.formalisms.bayesnet.BNDependency, mbdlyb.formalisms.tensornet.TNDependency, mbdlyb.formalisms.markovnet.MNDependency, FunctionalDependency

Relation representing functional decomposition hierarchy.

Variables:

_label (str) – ‘subfunction_of’
source (Function) – The subfunction.
target (Function) – The superfunction.

source: Function

target: Function

class mbdlyb.functional.base.YieldsErrorRelation(source: MBDNode, target: MBDNode, net: MBDNet | None = None)

Bases: mbdlyb.formalisms.bayesnet.BNDependency, mbdlyb.formalisms.tensornet.TNDependency, mbdlyb.formalisms.markovnet.MNDependency, FunctionalDependency

Relation indicating that a function failure yields an error code.

Variables:

_label (str) – ‘yields_errors’
source (Function) – The function that yields the error.
target (ObservedError) – The error code yielded.

source: Function

target: ObservedError