sirc 0.1.0__tar.gz

sirc-0.1.0/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: sirc
+Version: 0.1.0
+Summary: SIRC - Digital Logic and Circuit Simulation Engine
+Author-email: CRISvsGAME <cris@crisvsgame.com>
+Maintainer-email: CRISvsGAME <cris@crisvsgame.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/CRISvsGAME/sirc.git
+Keywords: digital logic,circuit simulation,simulation engine
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# SIRC

sirc-0.1.0/README.md

@@ -0,0 +1 @@
+# SIRC

sirc-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["setuptools"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "sirc"
+version = "0.1.0"
+dependencies = []
+requires-python = ">=3.12"
+authors = [{name = "CRISvsGAME", email = "cris@crisvsgame.com"}]
+maintainers = [{name = "CRISvsGAME", email = "cris@crisvsgame.com"}]
+description = "SIRC - Digital Logic and Circuit Simulation Engine"
+readme = "README.md"
+license = "MIT"
+keywords = ["digital logic", "circuit simulation", "simulation engine"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python",
+    "Topic :: Scientific/Engineering",
+]
+
+[project.optional-dependencies]
+dev = ["build", "mypy", "pylint", "pytest", "twine"]
+
+[project.urls]
+Repository = "https://github.com/CRISvsGAME/sirc.git"
+
+[tool.pylint]
+ignore-patterns = [".*\\.pyi"]

sirc-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

sirc-0.1.0/src/sirc/core/device.py

@@ -0,0 +1,134 @@
+"""
+SIRC Core Device Module.
+
+Defines the LogicDevice base class and several common logic devices: VDD, GND,
+Input, Probe, and Port. A LogicDevice owns exactly one terminal Node and may
+drive a single LogicValue onto that Node. LogicDevices do not perform any logic
+resolution. The Simulator handles all evaluation and propagation.
+"""
+
+from __future__ import annotations
+from abc import ABC
+from sirc.core.logic import LogicValue
+from sirc.core.node import Node
+
+
+class LogicDevice(ABC):
+    """
+    Abstract class for single-terminal logic devices.
+
+    Each LogicDevice owns one Node and may drive one LogicValue onto it. This
+    class defines only structural information. The Simulator is responsible for
+    injecting driver values and resolving all electrical behaviour.
+    """
+
+    __slots__ = ("_node", "_value")
+
+    def __init__(self) -> None:
+        """Create a new LogicDevice with a terminal Node and default Z value."""
+        self._node = Node()
+        self._value = LogicValue.Z
+
+    # --------------------------------------------------------------------------
+    # Properties
+    # --------------------------------------------------------------------------
+
+    @property
+    def terminal(self) -> Node:
+        """Return the terminal Node of this LogicDevice."""
+        return self._node
+
+    @property
+    def value(self) -> LogicValue:
+        """Return the LogicValue driven by this LogicDevice."""
+        return self._value
+
+    # --------------------------------------------------------------------------
+    # Debug Representation
+    # --------------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        """Return a debug representation of this LogicDevice."""
+        cls = self.__class__.__name__
+        return f"<{cls} value={self.value!r} terminal={self.terminal!r}>"
+
+
+# ------------------------------------------------------------------------------
+# Power Rail
+# ------------------------------------------------------------------------------
+
+
+class VDD(LogicDevice):
+    """
+    Logic "1" power rail device.
+
+    This device permanently drives its terminal Node with LogicValue.ONE.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._value = LogicValue.ONE
+
+
+# ------------------------------------------------------------------------------
+# Ground Rail
+# ------------------------------------------------------------------------------
+
+
+class GND(LogicDevice):
+    """
+    Logic "0" ground rail device.
+
+    This device permanently drives its terminal Node with LogicValue.ZERO.
+    """
+
+    def __init__(self) -> None:
+        super().__init__()
+        self._value = LogicValue.ZERO
+
+
+# ------------------------------------------------------------------------------
+# Input Device
+# ------------------------------------------------------------------------------
+
+
+class Input(LogicDevice):
+    """
+    Logic signal input device.
+
+    This device allows external setting of its driven LogicValue.
+    """
+
+    def set_value(self, value: LogicValue) -> None:
+        """Set the LogicValue driven by this Input device."""
+        self._value = value
+
+
+# ------------------------------------------------------------------------------
+# Probe Device
+# ------------------------------------------------------------------------------
+
+
+class Probe(LogicDevice):
+    """
+    Logic signal probe device.
+
+    This device allows sampling of the LogicValue present on its terminal Node.
+    """
+
+    def sample(self) -> LogicValue:
+        """Return the current resolved LogicValue of the terminal Node."""
+        return self._node.value
+
+
+# ------------------------------------------------------------------------------
+# Port Device
+# ------------------------------------------------------------------------------
+
+
+class Port(LogicDevice):
+    """
+    Logic signal port device.
+
+    This device is a passive connection point for linking circuit Nodes.
+    """

sirc-0.1.0/src/sirc/core/device.pyi

@@ -0,0 +1,24 @@
+from abc import ABC
+from sirc.core.logic import LogicValue as LogicValue
+from sirc.core.node import Node as Node
+
+class LogicDevice(ABC):
+    def __init__(self) -> None: ...
+    @property
+    def terminal(self) -> Node: ...
+    @property
+    def value(self) -> LogicValue: ...
+
+class VDD(LogicDevice):
+    def __init__(self) -> None: ...
+
+class GND(LogicDevice):
+    def __init__(self) -> None: ...
+
+class Input(LogicDevice):
+    def set_value(self, value: LogicValue) -> None: ...
+
+class Probe(LogicDevice):
+    def sample(self) -> LogicValue: ...
+
+class Port(LogicDevice): ...

sirc-0.1.0/src/sirc/core/logic.py

@@ -0,0 +1,143 @@
+"""
+SIRC Core Logic Module.
+
+Defines the four-state digital logic values used throughout the SIRC simulation
+engine. The logic rules follow the four-state resolution semantics defined by
+IEEE 1800-2023, but the terminology used here follows SIRC conventions.
+"""
+
+from __future__ import annotations
+from enum import Enum, unique
+from typing import Iterable
+
+
+@unique
+class LogicValue(Enum):
+    """
+    Four-state digital logic value used by Nodes and drivers in SIRC.
+
+    Values:
+        ZERO (0) -> logical low
+        ONE  (1) -> logical high
+        X        -> unknown or conflicting value
+        Z        -> undriven or high-impedance value
+    """
+
+    ZERO = "0"
+    ONE = "1"
+    X = "X"
+    Z = "Z"
+
+    # --------------------------------------------------------------------------
+    # Helper Properties
+    # --------------------------------------------------------------------------
+
+    @property
+    def is_zero(self) -> bool:
+        """Return True if this value is ZERO."""
+        return self is LogicValue.ZERO
+
+    @property
+    def is_one(self) -> bool:
+        """Return True if this value is ONE."""
+        return self is LogicValue.ONE
+
+    @property
+    def is_x(self) -> bool:
+        """Return True if this value is unknown (X)."""
+        return self is LogicValue.X
+
+    @property
+    def is_z(self) -> bool:
+        """Return True if this value is high-impedance (Z)."""
+        return self is LogicValue.Z
+
+    # --------------------------------------------------------------------------
+    # Two-Driver Resolution
+    # --------------------------------------------------------------------------
+
+    def resolve(self, other: LogicValue) -> LogicValue:
+        """
+        Resolve two driver values into a single LogicValue.
+
+        Args:
+            other: The second LogicValue driving the same Node.
+
+        Returns:
+            LogicValue: The resolved value.
+
+        Resolution Table (N = Node):
+             N | 0 | 1 | X | Z
+            ---+---+---+---+---
+             0 | 0 | X | X | 0
+            ---+---+---+---+---
+             1 | X | 1 | X | 1
+            ---+---+---+---+---
+             X | X | X | X | X
+            ---+---+---+---+---
+             Z | 0 | 1 | X | Z
+        """
+        result = self
+
+        if self is not other:
+
+            if self.is_x or other.is_x:
+                result = LogicValue.X
+
+            elif self.is_z and other.is_z:
+                result = LogicValue.Z
+
+            elif (self.is_zero and other.is_one) or (self.is_one and other.is_zero):
+                result = LogicValue.X
+
+            elif self.is_z:
+                result = other
+
+            elif other.is_z:
+                result = self
+
+        return result
+
+    # --------------------------------------------------------------------------
+    # Multi-Driver Resolution
+    # --------------------------------------------------------------------------
+
+    @staticmethod
+    def resolve_all(values: Iterable[LogicValue]) -> LogicValue:
+        """
+        Resolve multiple driver values into a single LogicValue.
+
+        Args:
+            values: Iterable of LogicValue instances.
+
+        Raises:
+            ValueError: If no values are provided.
+
+        Returns:
+            LogicValue: The resolved value.
+        """
+        iterator = iter(values)
+
+        try:
+            result = next(iterator)
+        except StopIteration as e:
+            raise ValueError("resolve_all() requires at least one LogicValue.") from e
+
+        for value in iterator:
+            result = result.resolve(value)
+            if result.is_x:
+                return LogicValue.X
+
+        return result
+
+    # --------------------------------------------------------------------------
+    # Display Helpers
+    # --------------------------------------------------------------------------
+
+    def __str__(self) -> str:
+        """Return compact string form ('0', '1', 'X', 'Z')."""
+        return self.value
+
+    def __repr__(self) -> str:
+        """Return readable debug representation."""
+        return f"LogicValue.{self.name}"

sirc-0.1.0/src/sirc/core/logic.pyi

@@ -0,0 +1,19 @@
+from enum import Enum
+from typing import Iterable
+
+class LogicValue(Enum):
+    ZERO = '0'
+    ONE = '1'
+    X = 'X'
+    Z = 'Z'
+    @property
+    def is_zero(self) -> bool: ...
+    @property
+    def is_one(self) -> bool: ...
+    @property
+    def is_x(self) -> bool: ...
+    @property
+    def is_z(self) -> bool: ...
+    def resolve(self, other: LogicValue) -> LogicValue: ...
+    @staticmethod
+    def resolve_all(values: Iterable[LogicValue]) -> LogicValue: ...

sirc-0.1.0/src/sirc/core/node.py

@@ -0,0 +1,117 @@
+"""
+SIRC Core Node Module.
+
+Defines the Node class used by the SIRC simulation engine. Nodes represent
+logical connection points in the circuit. Multiple Nodes may be connected,
+forming an electrical group that collectively resolves a single LogicValue.
+"""
+
+from __future__ import annotations
+from sirc.core.logic import LogicValue
+
+
+class Node:
+    """
+    A Node is a passive logical connection point in the SIRC circuit model.
+
+    It may hold zero or more driver LogicValues and may be directly connected
+    to other Nodes. A Node performs no resolution or computation by itself;
+    all evaluation and propagation are handled entirely by the Simulator.
+    """
+
+    __slots__ = ("_drivers", "_connections", "_value")
+
+    def __init__(self) -> None:
+        """Create an isolated Node with no drivers and a default Z value."""
+        self._drivers: list[LogicValue] = []
+        self._connections: set[Node] = set()
+        self._value: LogicValue = LogicValue.Z
+
+    # --------------------------------------------------------------------------
+    # Value Handling (Simulator-Controlled)
+    # --------------------------------------------------------------------------
+
+    def set_resolved_value(self, value: LogicValue) -> None:
+        """
+        Set the resolved LogicValue of this Node.
+
+        Args:
+            value: The resolved LogicValue to set.
+        """
+        self._value = value
+
+    @property
+    def value(self) -> LogicValue:
+        """Return the current resolved LogicValue of this Node."""
+        return self._value
+
+    # --------------------------------------------------------------------------
+    # Driver Management
+    # --------------------------------------------------------------------------
+
+    def add_driver(self, value: LogicValue) -> None:
+        """
+        Add a driver LogicValue to this Node.
+
+        Args:
+            value: The LogicValue driving this Node.
+        """
+        self._drivers.append(value)
+
+    def clear_drivers(self) -> None:
+        """Remove all driver LogicValues from this Node."""
+        self._drivers.clear()
+
+    def get_drivers(self) -> tuple[LogicValue, ...]:
+        """Return all driver LogicValues as an immutable tuple."""
+        return tuple(self._drivers)
+
+    # --------------------------------------------------------------------------
+    # Connectivity
+    # --------------------------------------------------------------------------
+
+    def add_connection(self, other: Node) -> None:
+        """INTERNAL USE ONLY: Add a direct connection to another Node."""
+        self._connections.add(other)
+
+    def remove_connection(self, other: Node) -> None:
+        """INTERNAL USE ONLY: Remove a direct connection to another Node."""
+        self._connections.discard(other)
+
+    def connect(self, other: Node) -> None:
+        """
+        Create a bidirectional connection between this Node and another.
+
+        Args:
+            other: The Node to connect to.
+        """
+        if self is other:
+            return
+
+        self.add_connection(other)
+        other.add_connection(self)
+
+    def disconnect(self, other: Node) -> None:
+        """
+        Remove the bidirectional connection between this Node and another.
+
+        Args:
+            other: The Node to disconnect from.
+        """
+        if self is other:
+            return
+
+        self.remove_connection(other)
+        other.remove_connection(self)
+
+    def get_connections(self) -> tuple[Node, ...]:
+        """Return all directly connected Nodes as an immutable tuple."""
+        return tuple(self._connections)
+
+    # --------------------------------------------------------------------------
+    # Debug Representation
+    # --------------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        """Return a debug representation of this Node."""
+        return f"<Node value={self._value!r} drivers={tuple(self._drivers)!r}>"

sirc-0.1.0/src/sirc/core/node.pyi

@@ -0,0 +1,15 @@
+from sirc.core.logic import LogicValue as LogicValue
+
+class Node:
+    def __init__(self) -> None: ...
+    def set_resolved_value(self, value: LogicValue) -> None: ...
+    @property
+    def value(self) -> LogicValue: ...
+    def add_driver(self, value: LogicValue) -> None: ...
+    def clear_drivers(self) -> None: ...
+    def get_drivers(self) -> tuple[LogicValue, ...]: ...
+    def add_connection(self, other: Node) -> None: ...
+    def remove_connection(self, other: Node) -> None: ...
+    def connect(self, other: Node) -> None: ...
+    def disconnect(self, other: Node) -> None: ...
+    def get_connections(self) -> tuple[Node, ...]: ...

sirc-0.1.0/src/sirc/core/transistor.py

@@ -0,0 +1,122 @@
+"""
+SIRC Core Transistor Module.
+
+Defines the abstract Transistor class and its NMOS and PMOS implementations. A
+Transistor is a three-terminal digital switch with gate, source, and drain
+Nodes. Transistors do not resolve logic or perform any electrical computation;
+the Simulator evaluates each device's conduction state based on its gate value.
+"""
+
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from sirc.core.logic import LogicValue
+from sirc.core.node import Node
+
+
+class Transistor(ABC):
+    """
+    Abstract class for three-terminal transistor devices.
+
+    Each Transistor contains:
+        - gate  : Node controlling conduction
+        - source: One side of the controlled channel
+        - drain : The other side of the controlled channel
+
+    This class defines only structural information and simple access helpers.
+    Device-specific conduction rules are implemented by subclasses. All logic
+    evaluation and node-group management is performed entirely by the Simulator.
+    """
+
+    __slots__ = ("gate", "source", "drain")
+
+    def __init__(self) -> None:
+        """
+        Create a new transistor with dedicated gate, source, and drain Nodes.
+        All Nodes begin in high-impedance (Z) state with no drivers. These Nodes
+        belong exclusively to this device and are never shared.
+        """
+        self.gate: Node = Node()
+        self.source: Node = Node()
+        self.drain: Node = Node()
+
+    # --------------------------------------------------------------------------
+    # Abstract Methods
+    # --------------------------------------------------------------------------
+
+    @abstractmethod
+    def is_conducting(self) -> bool:
+        """
+        Return True if this transistor is currently conducting.
+
+        A conducting transistor forms an electrical path between its source and
+        drain. The Simulator uses this result to determine whether the two Nodes
+        should be treated as members of the same node-group.
+        """
+        raise NotImplementedError("Must be implemented by subclasses.")
+
+    # --------------------------------------------------------------------------
+    # Public Methods
+    # --------------------------------------------------------------------------
+
+    def terminals(self) -> tuple[Node, Node, Node]:
+        """
+        Return a tuple of (gate, source, drain) Nodes.
+
+        Used by the Simulator for registration and structural traversal.
+        """
+        return (self.gate, self.source, self.drain)
+
+    def conduction_nodes(self) -> tuple[Node, Node]:
+        """
+        Return the (source, drain) Nodes involved in conduction.
+
+        Used by the Simulator when establishing or removing connectivity.
+        """
+        return (self.source, self.drain)
+
+    # --------------------------------------------------------------------------
+    # Debug Representation
+    # --------------------------------------------------------------------------
+
+    def __repr__(self) -> str:
+        """Return a debug representation of this Transistor."""
+        name = self.__class__.__name__
+        return f"<{name} gate={self.gate} source={self.source} drain={self.drain}>"
+
+
+# ------------------------------------------------------------------------------
+# NMOS Transistor Implementation
+# ------------------------------------------------------------------------------
+
+
+class NMOS(Transistor):
+    """
+    NMOS transistor device.
+
+    Conduction Rule:
+        - Conducts when the gate value is LogicValue.ONE.
+        - Non-conducting for ZERO, X, or Z.
+    """
+
+    def is_conducting(self) -> bool:
+        g = self.gate.value
+        return g is LogicValue.ONE
+
+
+# ------------------------------------------------------------------------------
+# PMOS Transistor Implementation
+# ------------------------------------------------------------------------------
+
+
+class PMOS(Transistor):
+    """
+    PMOS transistor device.
+
+    Conduction Rule:
+        - Conducts when the gate value is LogicValue.ZERO.
+        - Non-conducting for ONE, X, or Z.
+    """
+
+    def is_conducting(self) -> bool:
+        g = self.gate.value
+        return g is LogicValue.ZERO

sirc-0.1.0/src/sirc/core/transistor.pyi

@@ -0,0 +1,20 @@
+import abc
+from abc import ABC, abstractmethod
+from sirc.core.logic import LogicValue as LogicValue
+from sirc.core.node import Node as Node
+
+class Transistor(ABC, metaclass=abc.ABCMeta):
+    gate: Node
+    source: Node
+    drain: Node
+    def __init__(self) -> None: ...
+    @abstractmethod
+    def is_conducting(self) -> bool: ...
+    def terminals(self) -> tuple[Node, Node, Node]: ...
+    def conduction_nodes(self) -> tuple[Node, Node]: ...
+
+class NMOS(Transistor):
+    def is_conducting(self) -> bool: ...
+
+class PMOS(Transistor):
+    def is_conducting(self) -> bool: ...

sirc-0.1.0/src/sirc/simulator/device.py

@@ -0,0 +1,238 @@
+"""
+SIRC Device Simulator Module.
+
+Provides the DeviceSimulator class, responsible for evaluating a circuit
+composed of Nodes, LogicDevices, and Transistors. The simulator performs
+fixed-point iteration to resolve driver values, establish dynamic conduction
+paths, and propagate LogicValues across connected node-groups.
+"""
+
+from __future__ import annotations
+from typing import Iterable
+from sirc.core.logic import LogicValue
+from sirc.core.node import Node
+from sirc.core.device import LogicDevice
+from sirc.core.transistor import Transistor
+
+
+class DeviceSimulator:
+    """
+    Simulator for evaluating SIRC logic devices and transistors.
+
+    The DeviceSimulator maintains registered devices, transistors, and nodes.
+    Each tick clears drivers, applies device outputs, resolves node-groups via
+    DFS, and updates dynamic connectivity created by transistor conduction.
+    Fixed-point iteration continues until the circuit reaches a stable state.
+    """
+
+    def __init__(self) -> None:
+        """SIRC"""
+        self.devices: set[LogicDevice] = set()
+        self.transistors: set[Transistor] = set()
+        self.nodes: set[Node] = set()
+
+    # --------------------------------------------------------------------------
+    # Device Registration
+    # --------------------------------------------------------------------------
+
+    def register_device(self, device: LogicDevice) -> None:
+        """
+        Register a LogicDevice and its terminal Node with the simulator.
+
+        Args:
+            device: The LogicDevice to register.
+        """
+        self.devices.add(device)
+        self.nodes.add(device.terminal)
+
+    def register_devices(self, devices: Iterable[LogicDevice]) -> None:
+        """
+        Register multiple LogicDevices and terminal Nodes with the simulator.
+
+        Args:
+            devices: An iterable of LogicDevices to register.
+        """
+        for device in devices:
+            self.register_device(device)
+
+    def register_transistor(self, transistor: Transistor) -> None:
+        """
+        Register a Transistor and its terminal Nodes with the simulator.
+
+        Args:
+            transistor: The Transistor to register.
+        """
+        self.transistors.add(transistor)
+        self.nodes.update(transistor.terminals())
+
+    def register_transistors(self, transistors: Iterable[Transistor]) -> None:
+        """
+        Register multiple Transistors and terminal Nodes with the simulator.
+
+        Args:
+            transistors: An iterable of Transistors to register.
+        """
+        for transistor in transistors:
+            self.register_transistor(transistor)
+
+    def unregister_device(self, device: LogicDevice) -> None:
+        """
+        Unregister a LogicDevice and its terminal Node from the simulator.
+
+        Args:
+            device: The LogicDevice to unregister.
+        """
+        self.devices.discard(device)
+        self.nodes.discard(device.terminal)
+
+    def unregister_devices(self, devices: Iterable[LogicDevice]) -> None:
+        """
+        Unregister multiple LogicDevices and terminal Nodes from the simulator.
+
+        Args:
+            devices: An iterable of LogicDevices to unregister.
+        """
+        for device in devices:
+            self.unregister_device(device)
+
+    def unregister_transistor(self, transistor: Transistor) -> None:
+        """
+        Unregister a Transistor and its terminal Nodes from the simulator.
+
+        Args:
+            transistor: The Transistor to unregister.
+        """
+        self.transistors.discard(transistor)
+        self.nodes.difference_update(transistor.terminals())
+
+    def unregister_transistors(self, transistors: Iterable[Transistor]) -> None:
+        """
+        Unregister multiple Transistors and terminal Nodes from the simulator.
+
+        Args:
+            transistors: An iterable of Transistors to unregister.
+        """
+        for transistor in transistors:
+            self.unregister_transistor(transistor)
+
+    # --------------------------------------------------------------------------
+    # Logical Connection
+    # --------------------------------------------------------------------------
+
+    def connect(self, a: Node, b: Node) -> None:
+        """
+        Create a bidirectional connection between two Nodes.
+
+        Args:
+            a: The first Node.
+            b: The second Node.
+        """
+        a.connect(b)
+
+    def disconnect(self, a: Node, b: Node) -> None:
+        """
+        Remove the bidirectional connection between two Nodes.
+
+        Args:
+            a: The first Node.
+            b: The second Node.
+        """
+        a.disconnect(b)
+
+    # --------------------------------------------------------------------------
+    # Simulation Execution
+    # --------------------------------------------------------------------------
+
+    def _dfs(self, collection: Iterable[Node]) -> list[set[Node]]:
+        """
+        Perform depth-first search to identify connected node-groups.
+
+        Args:
+            collection: Iterable of Nodes to explore.
+
+        Returns:
+            List of sets, each containing Nodes in a connected group.
+        """
+        visited: set[Node] = set()
+        stack: list[Node] = []
+        groups: list[set[Node]] = []
+
+        for start in collection:
+            if start in visited:
+                continue
+
+            stack.append(start)
+            group: set[Node] = set()
+
+            while stack:
+                node = stack.pop()
+
+                if node in visited:
+                    continue
+
+                visited.add(node)
+                group.add(node)
+
+                for neighbor in node.get_connections():
+                    if neighbor not in visited:
+                        stack.append(neighbor)
+
+            groups.append(group)
+
+        return groups
+
+    def _resolve_groups(self, groups: list[set[Node]]) -> None:
+        """
+        Resolve LogicValues for each connected node-group.
+
+        Args:
+            groups: List of node-groups to resolve.
+        """
+        for group in groups:
+            drivers: list[LogicValue] = [LogicValue.Z]
+
+            for node in group:
+                drivers.extend(node.get_drivers())
+
+            resolved_value: LogicValue = LogicValue.resolve_all(drivers)
+
+            for node in group:
+                node.set_resolved_value(resolved_value)
+
+    def tick(self) -> None:
+        """
+        Execute a simulation tick to update device states and connectivity.
+
+        This method performs the following steps:
+            1. Clears all Node drivers.
+            2. Applies LogicDevice outputs to their terminal Nodes.
+            3. Repeatedly:
+                a. Identifies connected node-groups via DFS.
+                b. Resolves LogicValues for each group.
+                c. Updates transistor conduction paths.
+            4. Continues until a fixed-point state is reached.
+        """
+        for node in self.nodes:
+            node.clear_drivers()
+
+        for device in self.devices:
+            device.terminal.add_driver(device.value)
+
+        while True:
+            groups = self._dfs(self.nodes)
+            self._resolve_groups(groups)
+            fixed_point = True
+
+            for transistor in self.transistors:
+                a, b = transistor.conduction_nodes()
+                if transistor.is_conducting():
+                    if a not in b.get_connections():
+                        transistor.source.connect(transistor.drain)
+                        fixed_point = False
+                else:
+                    if a in b.get_connections():
+                        transistor.source.disconnect(transistor.drain)
+                        fixed_point = False
+
+            if fixed_point:
+                break

sirc-0.1.0/src/sirc/simulator/device.pyi

@@ -0,0 +1,22 @@
+from sirc.core.device import LogicDevice as LogicDevice
+from sirc.core.logic import LogicValue as LogicValue
+from sirc.core.node import Node as Node
+from sirc.core.transistor import Transistor as Transistor
+from typing import Iterable
+
+class DeviceSimulator:
+    devices: set[LogicDevice]
+    transistors: set[Transistor]
+    nodes: set[Node]
+    def __init__(self) -> None: ...
+    def register_device(self, device: LogicDevice) -> None: ...
+    def register_devices(self, devices: Iterable[LogicDevice]) -> None: ...
+    def register_transistor(self, transistor: Transistor) -> None: ...
+    def register_transistors(self, transistors: Iterable[Transistor]) -> None: ...
+    def unregister_device(self, device: LogicDevice) -> None: ...
+    def unregister_devices(self, devices: Iterable[LogicDevice]) -> None: ...
+    def unregister_transistor(self, transistor: Transistor) -> None: ...
+    def unregister_transistors(self, transistors: Iterable[Transistor]) -> None: ...
+    def connect(self, a: Node, b: Node) -> None: ...
+    def disconnect(self, a: Node, b: Node) -> None: ...
+    def tick(self) -> None: ...

sirc-0.1.0/src/sirc.egg-info/PKG-INFO

@@ -0,0 +1,24 @@
+Metadata-Version: 2.4
+Name: sirc
+Version: 0.1.0
+Summary: SIRC - Digital Logic and Circuit Simulation Engine
+Author-email: CRISvsGAME <cris@crisvsgame.com>
+Maintainer-email: CRISvsGAME <cris@crisvsgame.com>
+License-Expression: MIT
+Project-URL: Repository, https://github.com/CRISvsGAME/sirc.git
+Keywords: digital logic,circuit simulation,simulation engine
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Provides-Extra: dev
+Requires-Dist: build; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+Requires-Dist: pylint; extra == "dev"
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: twine; extra == "dev"
+
+# SIRC

sirc-0.1.0/src/sirc.egg-info/SOURCES.txt

@@ -0,0 +1,20 @@
+README.md
+pyproject.toml
+src/sirc/__init__.py
+src/sirc.egg-info/PKG-INFO
+src/sirc.egg-info/SOURCES.txt
+src/sirc.egg-info/dependency_links.txt
+src/sirc.egg-info/requires.txt
+src/sirc.egg-info/top_level.txt
+src/sirc/core/__init__.py
+src/sirc/core/device.py
+src/sirc/core/device.pyi
+src/sirc/core/logic.py
+src/sirc/core/logic.pyi
+src/sirc/core/node.py
+src/sirc/core/node.pyi
+src/sirc/core/transistor.py
+src/sirc/core/transistor.pyi
+src/sirc/simulator/__init__.py
+src/sirc/simulator/device.py
+src/sirc/simulator/device.pyi

sirc-0.1.0/src/sirc.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

sirc-0.1.0/src/sirc.egg-info/requires.txt

@@ -0,0 +1,7 @@
+
+[dev]
+build
+mypy
+pylint
+pytest
+twine

sirc-0.1.0/src/sirc.egg-info/top_level.txt

@@ -0,0 +1 @@
+sirc