mbdlyb.base =========== .. py:module:: mbdlyb.base .. autoapi-nested-parse:: 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 ---------- .. autoapisummary:: mbdlyb.base.T_NUMERICAL mbdlyb.base.T_VALUE Classes ------- .. autoapisummary:: mbdlyb.base.MBDDependency mbdlyb.base.MBDElement mbdlyb.base.MBDInfluence mbdlyb.base.MBDInfluenceableNode mbdlyb.base.MBDNet mbdlyb.base.MBDNetReasonerView mbdlyb.base.MBDNode mbdlyb.base.MBDNumericalElement mbdlyb.base.MBDNumericalNode mbdlyb.base.MBDRelation mbdlyb.base.MBDStatefulElement mbdlyb.base.PartOfRelation mbdlyb.base.TypedElement Module Contents --------------- .. py:class:: MBDDependency(source: MBDNode, target: MBDNode, net: Optional[MBDNet] = None) Bases: :py:obj:`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. :ivar source: The source node (cause). :vartype source: MBDNode :ivar target: The target node (effect). :vartype target: MBDNode .. py:method:: create() Register this dependency with the network and both involved nodes. :raises InvalidRelationError: If either node rejects this dependency. .. py:method:: remove() Remove this dependency from both involved nodes and the network. .. py:attribute:: source :type: MBDNode .. py:attribute:: target :type: MBDNode .. py:class:: MBDElement(name: str, net: Optional[MBDNet] = None) Bases: :py:obj:`abc.ABC`, :py:obj:`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. :ivar name: The local name of this element. :vartype name: str :ivar _fqn: The fully qualified name reflecting position in hierarchy. :vartype _fqn: FQN :ivar _net: The parent network containing this element. :vartype _net: Optional[MBDNet] .. py:method:: 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. .. py:method:: set_net(net: MBDNet) Set the parent network and update FQN accordingly. :param net: The parent network to assign. :type net: MBDNet .. py:property:: at_root :type: bool Check if this element is at the root level (has no parent network). :returns: True if element has no parent network, False otherwise. :rtype: bool .. py:property:: fqn :type: mbdlyb.fqn.FQN Get the fully qualified name reflecting the element's position in hierarchy. :returns: The fully qualified name. :rtype: FQN .. py:attribute:: name :type: str .. py:property:: net :type: Optional[MBDNet] Get the immediate parent network containing this element. :returns: The parent network, or None if at root level. :rtype: Optional[MBDNet] .. py:property:: root :type: MBDNet :abstractmethod: Get the root network of the hierarchy. :returns: The root network containing this element. :rtype: MBDNet .. py:class:: MBDInfluence(*nodes: MBDInfluenceableNode, net: Optional[MBDNet] = None) Bases: :py:obj:`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. :ivar nodes: The nodes involved in this influence relation. :vartype nodes: list[MBDInfluenceableNode] .. py:method:: create() Register this influence in the network and with all involved nodes. .. py:method:: remove() Remove this influence from all involved nodes and the network. .. py:property:: fqn :type: mbdlyb.fqn.FQN Get the fully qualified name for this influence. :returns: The FQN combining the network FQN and this relation's name. :rtype: FQN .. py:property:: name :type: str Get a compound name for this influence based on node names. :returns: Name composed of class name and node names. :rtype: str .. py:attribute:: nodes :type: list[MBDInfluenceableNode] .. py:class:: MBDInfluenceableNode[T](name: str, states: list[T], net: MBDNet) Bases: :py:obj:`MBDNode`\ [\ :py:obj:`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. :ivar influences: All influence relations involving this node. :vartype influences: list[MBDInfluence] .. py:method:: 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. .. py:property:: influencers :type: list[MBDInfluenceableNode] Get all nodes that influence this node through influence relations. :returns: List of influencing nodes (excluding self). :rtype: list[MBDInfluenceableNode] .. py:attribute:: influences :type: list[MBDInfluence] .. py:class:: MBDNet(name: str, net: Optional[MBDNet] = None) Bases: :py:obj:`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. :ivar elements: Immediate children of this network. :vartype elements: dict[str, MBDElement] :ivar relations: All relations (dependencies and influences) defined at this level. :vartype relations: list[MBDRelation] :ivar _element_map: Map of all elements (including nested) by their FQN. :vartype _element_map: dict[FQN, MBDElement] .. py:method:: add_element(element: MBDElement) Add an element as a child of this network. :param element: The element to add. :type element: MBDElement :raises ElementExistsError: If an element with the same name already exists in this network. .. py:method:: add_elements(*elements: MBDElement) Add multiple elements as children of this network. :param \*elements: Variable number of elements to add. :type \*elements: MBDElement .. py:method:: 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. :param element: The element to map. :type element: MBDElement :raises ElementExistsError: If an element with the same FQN already exists. .. py:method:: 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. :rtype: MBDNetReasonerView .. py:method:: drop_mapped_element(fqn: mbdlyb.fqn.FQN) Remove an element from the global element map by its FQN. :param fqn: The fully qualified name of the element to remove. :type fqn: FQN :raises ElementNotFoundError: If no element with the given FQN exists. .. py:method:: get_element(fqn: Union[mbdlyb.fqn.FQN, str]) -> MBDElement Retrieve an element by its fully qualified name. :param fqn: The fully qualified name or an empty value to get self. :type fqn: Union[FQN, str] :returns: The requested element. :rtype: MBDElement :raises ElementNotFoundError: If no element with the given FQN exists. .. py:method:: get_flat_dependencies() -> list[MBDDependency] Get all dependency relations in this network and all nested subnets. :returns: Flat list of all dependency relations. :rtype: list[MBDDependency] .. py:method:: get_flat_influences() -> list[MBDInfluence] Get all influence relations in this network and all nested subnets. :returns: Flat list of all influence relations. :rtype: list[MBDInfluence] .. py:method:: 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. :rtype: list[MBDNode] .. py:method:: get_flat_relations() -> list[MBDRelation] Get all relations in this network and all nested subnets. :returns: Flat list of all relations recursively contained. :rtype: list[MBDRelation] .. py:method:: 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. :param \*klass: Node types to retrieve (can specify multiple types). :type \*klass: Type[MBDNode] :param depth: Maximum recursion depth for subnets. Default is 1e6 (effectively unlimited). :type depth: float :returns: List of nodes matching the specified types. :rtype: list[T] .. py:method:: has_element(fqn: mbdlyb.fqn.FQN) Check if an element with the given FQN exists in this network hierarchy. :param fqn: The fully qualified name to check. :type fqn: FQN :returns: True if the element exists, False otherwise. :rtype: bool .. py:method:: remove() Remove this network and all its contained elements. Recursively removes all child elements before removing the network itself. .. py:method:: set_net(net: MBDNet) Set the parent network and update element mapping. :param net: The parent network to assign. :type net: MBDNet .. py:property:: dependencies :type: list[MBDDependency] Get all dependency relations at this network level (not including nested subnets). :returns: List of dependency relations. :rtype: list[MBDDependency] .. py:attribute:: elements :type: dict[str, MBDElement] .. py:property:: influences :type: list[MBDInfluence] Get all influence relations at this network level (not including nested subnets). :returns: List of influence relations. :rtype: list[MBDInfluence] .. py:attribute:: relations :type: list[MBDRelation] .. py:property:: root :type: MBDNet Get the root network in the hierarchy. :returns: The root network (itself if this is the root). :rtype: MBDNet .. py:property:: subnets :type: dict[str, MBDNet] Get all child networks (subnets) of this network. :returns: Dictionary of subnets keyed by their names. :rtype: dict[str, MBDNet] .. py:class:: 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. :ivar net: The network being provided a reasoner view. :vartype net: MBDNet .. py:attribute:: net :type: MBDNet .. py:class:: MBDNode[T](name: str, states: list[T], net: MBDNet) Bases: :py:obj:`MBDStatefulElement`\ [\ :py:obj:`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. :ivar parent_relations: Incoming dependencies from parent nodes. :vartype parent_relations: list[MBDDependency] :ivar child_relations: Outgoing dependencies to child nodes. :vartype child_relations: list[MBDDependency] .. py:method:: 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. .. py:method:: 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. :param relation: The proposed outgoing dependency. :type relation: MBDDependency :returns: True if the relation is valid, False otherwise. :rtype: bool .. py:method:: 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. :param relation: The proposed incoming dependency. :type relation: MBDDependency :returns: True if the relation is valid, False otherwise. :rtype: bool .. py:attribute:: child_relations :type: list[MBDDependency] .. py:property:: children :type: list[MBDNode] Get all child nodes (target nodes of outgoing dependencies). :returns: List of child nodes. :rtype: list[MBDNode] .. py:attribute:: parent_relations :type: list[MBDDependency] .. py:property:: parents :type: list[MBDNode] Get all parent nodes (source nodes of incoming dependencies). :returns: List of parent nodes. :rtype: list[MBDNode] .. py:property:: relations :type: list[MBDDependency] Get all dependency relations connected to this node. :returns: Combined list of parent and child relations. :rtype: list[MBDDependency] .. py:class:: MBDNumericalElement(name: str, states: list[Union[T_NUMERICAL, tuple[T_NUMERICAL, str]]], net: MBDNet) Bases: :py:obj:`MBDStatefulElement`\ [\ :py:obj:`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. :ivar _labels: Mapping of numerical states to text labels. :vartype _labels: dict[T_NUMERICAL, str] :ivar _min: Minimum value in the states list. :vartype _min: T_NUMERICAL :ivar _max: Maximum value in the states list. :vartype _max: T_NUMERICAL .. py:method:: label(v: T_NUMERICAL) -> str Get the text label for a numerical state value. :param v: The state value to get the label for. :type v: T_NUMERICAL :returns: The text label for the state. :rtype: str :raises InvalidValueError: If the value is not in the states list. .. py:property:: is_normalized_state :type: bool Check if states are normalized to the range [0, 1]. :returns: True if minimum is 0 and maximum is 1, False otherwise. :rtype: bool .. py:property:: labels Get the mapping of state values to their text labels. :returns: Dictionary mapping numerical states to labels. :rtype: dict[T_NUMERICAL, str] .. py:property:: max :type: T_NUMERICAL Get the maximum state value. :returns: The maximum value in the states list. :rtype: T_NUMERICAL .. py:property:: min :type: T_NUMERICAL Get the minimum state value. :returns: The minimum value in the states list. :rtype: T_NUMERICAL .. py:class:: MBDNumericalNode(name: str, states: list[Union[T_NUMERICAL, tuple[T_NUMERICAL, str]]], net: MBDNet) Bases: :py:obj:`MBDNode`\ [\ :py:obj:`T_NUMERICAL`\ ], :py:obj:`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. .. py:class:: MBDRelation(nodes: list[MBDNode], net: Optional[MBDNet] = None) Bases: :py:obj:`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. :ivar _label: The label/name of this relation type. :vartype _label: str :ivar net: The network containing this relation. :vartype net: MBDNet .. py:method:: 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. .. py:method:: get_label() -> str :classmethod: Get the label/name of this relation type. :returns: The relation type label. :rtype: str .. py:method:: 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. .. py:property:: label :type: str Get the label/name of this relation instance. :returns: The relation type label. :rtype: str :raises NotImplementedError: If label is not defined for this relation type. .. py:attribute:: net :type: MBDNet .. py:class:: MBDStatefulElement[T](name: str, states: list[T], net: MBDNet) Bases: :py:obj:`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'). :ivar _states: The list of possible states for this element. :vartype _states: list[T] :ivar _net: The parent network (inherited from MBDElement). :vartype _net: MBDNet .. py:method:: get_state(v: T) -> T Get a state from the states list by value. :param v: The state value to retrieve. :type v: T :returns: The requested state. :rtype: T :raises InvalidValueError: If the value does not exist in the states list. .. py:method:: get_state_idx(v: T) -> int Get the index of a state in the states list. :param v: The state value to find. :type v: T :returns: The index of the state. :rtype: int :raises InvalidValueError: If the value does not exist in the states list. .. py:property:: net :type: MBDNet Get the parent network. :returns: The parent network. :rtype: MBDNet .. py:property:: root :type: MBDNet Get the root network. :returns: The root network. :rtype: MBDNet .. py:property:: states :type: list[T] Get the list of possible states. :returns: The list of discrete states. :rtype: list[T] .. py:class:: PartOfRelation(source: MBDNode, target: MBDNode, net: Optional[MBDNet] = None) Bases: :py:obj:`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. .. py:class:: 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. :ivar _id: The unique identifier for this element. :vartype _id: UUID .. py:property:: id :type: uuid.UUID Get the unique identifier of this element. :returns: The unique identifier. :rtype: UUID .. py:type:: T_NUMERICAL :canonical: Union[float, int] float or integer. :type: Type alias for numerical values .. py:type:: T_VALUE :canonical: Union[str, float, int] string, float, or integer. :type: Type alias for discrete values