mbdlyb.base

Core base classes for Model-Based Diagnostics library.

This module provides the fundamental building blocks for MBD models, including elements, nodes, nets, and relations. It implements the hierarchical structure that supports model-based diagnostic reasoning.

Attributes

`T_NUMERICAL`	float or integer.
`T_VALUE`	string, float, or integer.

Classes

`MBDDependency`	Directed dependency relation from a source node to a target node.
`MBDElement`	Abstract base class for elements in the MBD model hierarchy.
`MBDInfluence`	Relation representing non-causal influence or correlation between nodes.
`MBDInfluenceableNode`	A node that can be influenced by other nodes through influences relations.
`MBDNet`	A container for hierarchically organizing MBD model elements.
`MBDNetReasonerView`	Context manager for managing reasoner operations on an MBD network.
`MBDNode`	Discrete node in the MBD model representing a variable or system component.
`MBDNumericalElement`	Stateful element with numerical states and optional text labels.
`MBDNumericalNode`	A node that combines numerical states with optional labels and dependency relations.
`MBDRelation`	Abstract base class for relations between nodes in an MBD model.
`MBDStatefulElement`	Element that has discrete states representing possible values or conditions.
`PartOfRelation`	A specific type of dependency representing a 'part-of' relationship.
`TypedElement`	Base class for uniquely identifiable elements using UUID.

Module Contents

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

Bases: MBDRelation

Directed dependency relation from a source node to a target node.

An MBDDependency represents a causal or functional dependency where a source node influences or affects a target node. This is a directed relation with clear causality direction.

Variables:

source (MBDNode) – The source node (cause).
target (MBDNode) – The target node (effect).

create()

Register this dependency with the network and both involved nodes.

Raises:: InvalidRelationError – If either node rejects this dependency.

remove(): Remove this dependency from both involved nodes and the network.

source: MBDNode

target: MBDNode

class mbdlyb.base.MBDElement(name: str, net: MBDNet | None = None)

Bases: abc.ABC, TypedElement

Abstract base class for elements in the MBD model hierarchy.

MBDElement represents any named entity in the MBD model that can be organized hierarchically within networks (MBDNet). Each element has a fully qualified name (FQN) that reflects its position in the hierarchy.

Variables:

name (str) – The local name of this element.
_fqn (FQN) – The fully qualified name reflecting position in hierarchy.
_net (Optional[MBDNet]) – The parent network containing this element.

remove()

Remove this element from its parent network and clean up resources.

This method removes the element from the network’s element map and parent network’s elements dictionary, then deletes the object.

set_net(net: MBDNet)

Set the parent network and update FQN accordingly.

Parameters:: net (MBDNet) – The parent network to assign.

property at_root: bool

Check if this element is at the root level (has no parent network).

Returns:: True if element has no parent network, False otherwise.
Return type:: bool

property fqn: mbdlyb.fqn.FQN

Get the fully qualified name reflecting the element’s position in hierarchy.

Returns:: The fully qualified name.
Return type:: FQN

name: str

property net: MBDNet | None

Get the immediate parent network containing this element.

Returns:: The parent network, or None if at root level.
Return type:: Optional[MBDNet]

property root: MBDNet

Abstractmethod:

Get the root network of the hierarchy.

Returns:: The root network containing this element.
Return type:: MBDNet

class mbdlyb.base.MBDInfluence(*nodes: MBDInfluenceableNode, net: MBDNet | None = None)

Bases: MBDRelation

Relation representing non-causal influence or correlation between nodes.

An MBDInfluence differs from a dependency in that it represents a correlation or symmetric relationship between two or more influenceable nodes, rather than a causal dependency with a clear direction.

Variables:: nodes (list[MBDInfluenceableNode]) – The nodes involved in this influence relation.

create(): Register this influence in the network and with all involved nodes.

remove(): Remove this influence from all involved nodes and the network.

property fqn: mbdlyb.fqn.FQN

Get the fully qualified name for this influence.

Returns:: The FQN combining the network FQN and this relation’s name.
Return type:: FQN

property name: str

Get a compound name for this influence based on node names.

Returns:: Name composed of class name and node names.
Return type:: str

nodes: list[MBDInfluenceableNode]

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

Bases: MBDNode[T]

A node that can be influenced by other nodes through influences relations.

Extends MBDNode to support MBDInfluence relations, which differ from dependency relations by representing non-causal influences or correlations between nodes.

Variables:: influences (list[MBDInfluence]) – All influence relations involving this node.

remove()

Remove this node and clean up all its influence relations.

Removes all influence relations involving this node before removing the node itself from the network.

property influencers: list[MBDInfluenceableNode]

Get all nodes that influence this node through influence relations.

Returns:: List of influencing nodes (excluding self).
Return type:: list[MBDInfluenceableNode]

influences: list[MBDInfluence]

class mbdlyb.base.MBDNet(name: str, net: MBDNet | None = None)

Bases: MBDElement

A container for hierarchically organizing MBD model elements.

MBDNet represents a hierarchical network or subnet that can contain other elements (nodes and subnets) and relations. Networks can be nested, forming a tree structure. It maintains a fully qualified name (FQN) based map of all contained elements for efficient lookup.

Variables:

elements (dict[str, MBDElement]) – Immediate children of this network.
relations (list[MBDRelation]) – All relations (dependencies and influences) defined at this level.
_element_map (dict[FQN, MBDElement]) – Map of all elements (including nested) by their FQN.

add_element(element: MBDElement)

Add an element as a child of this network.

Parameters:: element (MBDElement) – The element to add.
Raises:: ElementExistsError – If an element with the same name already exists in this network.

add_elements(*elements: MBDElement)

Add multiple elements as children of this network.

Parameters:: *elements (MBDElement) – Variable number of elements to add.

add_mapped_element(element: MBDElement)

Add an element to the global element map by its FQN.

This is used internally to maintain the efficient lookup map of all elements in the network hierarchy.

Parameters:: element (MBDElement) – The element to map.
Raises:: ElementExistsError – If an element with the same FQN already exists.

create_reasoner_view() → MBDNetReasonerView

Create a context manager for reasoner operations on this network.

Returns:: A view object that can be used as a context manager.
Return type:: MBDNetReasonerView

drop_mapped_element(fqn: mbdlyb.fqn.FQN)

Remove an element from the global element map by its FQN.

Parameters:: fqn (FQN) – The fully qualified name of the element to remove.
Raises:: ElementNotFoundError – If no element with the given FQN exists.

get_element(fqn: mbdlyb.fqn.FQN | str) → MBDElement

Retrieve an element by its fully qualified name.

Parameters:: fqn (Union[FQN, str]) – The fully qualified name or an empty value to get self.
Returns:: The requested element.
Return type:: MBDElement
Raises:: ElementNotFoundError – If no element with the given FQN exists.

get_flat_dependencies() → list[MBDDependency]

Get all dependency relations in this network and all nested subnets.

Returns:: Flat list of all dependency relations.
Return type:: list[MBDDependency]

get_flat_influences() → list[MBDInfluence]

Get all influence relations in this network and all nested subnets.

Returns:: Flat list of all influence relations.
Return type:: list[MBDInfluence]

get_flat_nodes() → list[MBDNode]

Get all nodes in this network and all nested subnets.

Returns:: Flat list of all nodes recursively contained in this network.
Return type:: list[MBDNode]

get_flat_relations() → list[MBDRelation]

Get all relations in this network and all nested subnets.

Returns:: Flat list of all relations recursively contained.
Return type:: list[MBDRelation]

get_nodes_of_type[T](*klass: Type[MBDNode], depth=1000000.0) → list[T]

Get all nodes of specified type(s) up to a given depth.

Parameters:

*klass (Type[MBDNode]) – Node types to retrieve (can specify multiple types).
depth (float) – Maximum recursion depth for subnets. Default is 1e6 (effectively unlimited).

Returns:

List of nodes matching the specified types.

Return type:

list[T]

has_element(fqn: mbdlyb.fqn.FQN)

Check if an element with the given FQN exists in this network hierarchy.

Parameters:: fqn (FQN) – The fully qualified name to check.
Returns:: True if the element exists, False otherwise.
Return type:: bool

remove()

Remove this network and all its contained elements.

Recursively removes all child elements before removing the network itself.

set_net(net: MBDNet)

Set the parent network and update element mapping.

Parameters:: net (MBDNet) – The parent network to assign.

property dependencies: list[MBDDependency]

Get all dependency relations at this network level (not including nested subnets).

Returns:: List of dependency relations.
Return type:: list[MBDDependency]

elements: dict[str, MBDElement]

property influences: list[MBDInfluence]

Get all influence relations at this network level (not including nested subnets).

Returns:: List of influence relations.
Return type:: list[MBDInfluence]

relations: list[MBDRelation]

property root: MBDNet

Get the root network in the hierarchy.

Returns:: The root network (itself if this is the root).
Return type:: MBDNet

property subnets: dict[str, MBDNet]

Get all child networks (subnets) of this network.

Returns:: Dictionary of subnets keyed by their names.
Return type:: dict[str, MBDNet]

class mbdlyb.base.MBDNetReasonerView(net: MBDNet)

Context manager for managing reasoner operations on an MBD network.

MBDNetReasonerView provides a context manager interface for performing reasoner operations within a managed scope. This can be used to ensure proper setup and teardown of reasoning contexts.

Variables:: net (MBDNet) – The network being provided a reasoner view.

net: MBDNet

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

Bases: MBDStatefulElement[T]

Discrete node in the MBD model representing a variable or system component.

MBDNode represents a fundamental unit in the diagnostic model with discrete states. Nodes can have dependencies (parent-child relationships) with other nodes through MBDDependency relations.

Variables:

parent_relations (list[MBDDependency]) – Incoming dependencies from parent nodes.
child_relations (list[MBDDependency]) – Outgoing dependencies to child nodes.

remove()

Remove this node and clean up all its relations.

Removes all dependency relations connected to this node before removing the node itself from the network.

valid_child_relation(relation: MBDDependency) → bool

Check if a proposed child relation would be valid for this node.

Override this method in subclasses to enforce specific constraints on outgoing dependencies.

Parameters:: relation (MBDDependency) – The proposed outgoing dependency.
Returns:: True if the relation is valid, False otherwise.
Return type:: bool

valid_parent_relation(relation: MBDDependency) → bool

Check if a proposed parent relation would be valid for this node.

Override this method in subclasses to enforce specific constraints on incoming dependencies.

Parameters:: relation (MBDDependency) – The proposed incoming dependency.
Returns:: True if the relation is valid, False otherwise.
Return type:: bool

child_relations: list[MBDDependency]

property children: list[MBDNode]

Get all child nodes (target nodes of outgoing dependencies).

Returns:: List of child nodes.
Return type:: list[MBDNode]

parent_relations: list[MBDDependency]

property parents: list[MBDNode]

Get all parent nodes (source nodes of incoming dependencies).

Returns:: List of parent nodes.
Return type:: list[MBDNode]

property relations: list[MBDDependency]

Get all dependency relations connected to this node.

Returns:: Combined list of parent and child relations.
Return type:: list[MBDDependency]

class mbdlyb.base.MBDNumericalElement(name: str, states: list[T_NUMERICAL | tuple[T_NUMERICAL, str]], net: MBDNet)

Bases: MBDStatefulElement[T_NUMERICAL]

Stateful element with numerical states and optional text labels.

Extends MBDStatefulElement to support numerical values (floats or integers) as states, with optional human-readable labels for each state. Tracks minimum and maximum values.

Variables:

_labels (dict[T_NUMERICAL, str]) – Mapping of numerical states to text labels.
_min (T_NUMERICAL) – Minimum value in the states list.
_max (T_NUMERICAL) – Maximum value in the states list.

label(v: T_NUMERICAL) → str

Get the text label for a numerical state value.

Parameters:: v (T_NUMERICAL) – The state value to get the label for.
Returns:: The text label for the state.
Return type:: str
Raises:: InvalidValueError – If the value is not in the states list.

property is_normalized_state: bool

Check if states are normalized to the range [0, 1].

Returns:: True if minimum is 0 and maximum is 1, False otherwise.
Return type:: bool

property labels

Get the mapping of state values to their text labels.

Returns:: Dictionary mapping numerical states to labels.
Return type:: dict[T_NUMERICAL, str]

property max: T_NUMERICAL

Get the maximum state value.

Returns:: The maximum value in the states list.
Return type:: T_NUMERICAL

property min: T_NUMERICAL

Get the minimum state value.

Returns:: The minimum value in the states list.
Return type:: T_NUMERICAL

class mbdlyb.base.MBDNumericalNode(name: str, states: list[T_NUMERICAL | tuple[T_NUMERICAL, str]], net: MBDNet)

Bases: MBDNode[T_NUMERICAL], MBDNumericalElement

A node that combines numerical states with optional labels and dependency relations.

Combines the features of MBDNode (for dependencies) and MBDNumericalElement (for numerical states with labels) into a single node type useful for representing continuous or quantified variables in the diagnostic model.

class mbdlyb.base.MBDRelation(nodes: list[MBDNode], net: MBDNet | None = None)

Bases: TypedElement

Abstract base class for relations between nodes in an MBD model.

MBDRelation represents connections between MBDNode objects. Relations are stored in the network they belong to and require at least 2 nodes. Subclasses define specific types of relations like dependencies and influences.

Variables:

_label (str) – The label/name of this relation type.
net (MBDNet) – The network containing this relation.

create()

Register this relation in its network.

Called during initialization to add this relation to the network’s relations list. Subclasses override to perform additional setup.

classmethod get_label() → str

Get the label/name of this relation type.

Returns:: The relation type label.
Return type:: str

remove()

Remove this relation from its network and clean up.

Removes the relation from the network’s relations list. Subclasses override to perform additional cleanup with related nodes.

property label: str

Get the label/name of this relation instance.

Returns:: The relation type label.
Return type:: str
Raises:: NotImplementedError – If label is not defined for this relation type.

net: MBDNet

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

Bases: MBDElement

Element that has discrete states representing possible values or conditions.

MBDStatefulElement extends MBDElement to include a list of discrete states. This is useful for representing variables with discrete values (e.g., ‘healthy’, ‘degraded’, ‘failed’).

Variables:

_states (list[T]) – The list of possible states for this element.
_net (MBDNet) – The parent network (inherited from MBDElement).

get_state(v: T) → T

Get a state from the states list by value.

Parameters:: v (T) – The state value to retrieve.
Returns:: The requested state.
Return type:: T
Raises:: InvalidValueError – If the value does not exist in the states list.

get_state_idx(v: T) → int

Get the index of a state in the states list.

Parameters:: v (T) – The state value to find.
Returns:: The index of the state.
Return type:: int
Raises:: InvalidValueError – If the value does not exist in the states list.

property net: MBDNet

Get the parent network.

Returns:: The parent network.
Return type:: MBDNet

property root: MBDNet

Get the root network.

Returns:: The root network.
Return type:: MBDNet

property states: list[T]

Get the list of possible states.

Returns:: The list of discrete states.
Return type:: list[T]

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

Bases: MBDDependency

A specific type of dependency representing a ‘part-of’ relationship.

PartOfRelation is a specialized MBDDependency used to represent compositional relationships where the target is part of or contained within the source.

class mbdlyb.base.TypedElement

Base class for uniquely identifiable elements using UUID.

Every TypedElement is assigned a unique UUID at creation that persists throughout its lifetime. This enables reliable identification and comparison of elements.

Variables:: _id (UUID) – The unique identifier for this element.

property id: uuid.UUID

Get the unique identifier of this element.

Returns:: The unique identifier.
Return type:: UUID

type mbdlyb.base.T_NUMERICAL = float | int

float or integer.

Type:: Type alias for numerical values

type mbdlyb.base.T_VALUE = str | float | int

string, float, or integer.

Type:: Type alias for discrete values