TMC #0005: McCulloch-Pitts Neuron Simulator

"""
TMC #0005 — McCulloch-Pitts Neuron and Logical Brain
=====================================================
Simulates the McCulloch-Pitts (1943) formal neuron model:
  - Binary threshold neuron: output 1 iff weighted sum >= threshold
  - Excitatory and inhibitory inputs
  - Network construction and forward propagation
  - Proof that McCulloch-Pitts networks can compute any Boolean function
  - Demonstrations: AND, OR, NOT, NAND, XOR (via multi-layer)
  - Sequence recognition network
  - Comparison with a modern perceptron

Run:
    python mcculloch_pitts.py
"""

from __future__ import annotations

import itertools
from dataclasses import dataclass
from typing import Callable, Dict, List, Tuple

# ─────────────────────────────────────────────
# 1. McCulloch-Pitts (MP) Neuron
#
#    y = 1  if  (Σ excitatory inputs) - (Σ inhibitory inputs) >= θ
#          AND  no inhibitory input is firing  [absolute inhibition variant]
#    y = 0  otherwise
#
#    The 1943 paper used absolute inhibition:
#    ANY active inhibitory input forces output 0.
#    We support both models.
# ─────────────────────────────────────────────


@dataclass
class MPNeuron:
    """
    A single McCulloch-Pitts neuron.

    Inputs:
        excitatory: list of input indices that contribute +1
        inhibitory: list of input indices whose activation blocks output
        threshold:  activation threshold θ
        name:       optional label
    """

    excitatory: List[int]
    inhibitory: List[int]
    threshold: float
    name: str = "neuron"
    absolute_inhibition: bool = True  # original 1943 model

    def activate(self, inputs: List[int]) -> int:
        """
        Compute neuron output given binary input vector.
        inputs[i] is 1 (firing) or 0 (silent).
        """
        # Absolute inhibition: if ANY inhibitory input fires, output = 0
        if self.absolute_inhibition:
            if any(inputs[i] for i in self.inhibitory):
                return 0

        excite_sum = sum(inputs[i] for i in self.excitatory)
        # Weighted inhibition (non-absolute variant)
        if not self.absolute_inhibition:
            excite_sum -= sum(inputs[i] for i in self.inhibitory)

        return 1 if excite_sum >= self.threshold else 0

    def __repr__(self) -> str:
        return (
            f"MPNeuron({self.name!r}: exc={self.excitatory}, "
            f"inh={self.inhibitory}, θ={self.threshold})"
        )


# ─────────────────────────────────────────────
# 2. MP Network: layered feedforward net
# ─────────────────────────────────────────────


class MPNetwork:
    """
    Layered McCulloch-Pitts network.
    Layers are evaluated sequentially; each layer's outputs
    become the inputs for the next.
    """

    def __init__(self, input_size: int):
        self.input_size = input_size
        self.layers: List[List[MPNeuron]] = []

    def add_layer(self, neurons: List[MPNeuron]) -> "MPNetwork":
        self.layers.append(neurons)
        return self

    def forward(self, inputs: List[int]) -> List[int]:
        """Run forward pass. Returns output layer activations."""
        current = list(inputs)
        for layer in self.layers:
            current = [n.activate(current) for n in layer]
        return current

    def output(self, inputs: List[int]) -> int:
        """Convenience: returns single output neuron value."""
        return self.forward(inputs)[0]


# ─────────────────────────────────────────────
# 3. Classic Boolean Gates as MP Networks
# ─────────────────────────────────────────────


def make_AND() -> MPNetwork:
    """AND(x0, x1): fire only if both inputs active. θ=2."""
    net = MPNetwork(input_size=2)
    net.add_layer([MPNeuron([0, 1], [], threshold=2, name="AND")])
    return net


def make_OR() -> MPNetwork:
    """OR(x0, x1): fire if at least one input active. θ=1."""
    net = MPNetwork(input_size=2)
    net.add_layer([MPNeuron([0, 1], [], threshold=1, name="OR")])
    return net


def make_NOT() -> MPNetwork:
    """NOT(x0): inhibitory input, fires when x0=0. θ=0, absolute inhibition."""
    # With absolute inhibition: neuron fires (sum >= 0) unless inhibited
    # We use a bias trick: excitatory bias=1, inhibitory=x0
    # This requires us to pass a bias=1 as index 1
    # Input: [x0, bias=1]
    net = MPNetwork(input_size=2)
    net.add_layer(
        [MPNeuron([1], [0], threshold=1, name="NOT", absolute_inhibition=True)]
    )
    return net


def not_output(x: int) -> int:
    """NOT using the bias trick: inputs are [x, 1]."""
    net = make_NOT()
    return net.output([x, 1])


def make_NAND() -> MPNetwork:
    """NAND(x0,x1): NOT(AND(x0,x1)). Two layers."""
    # Layer 1: AND neuron, output index 0
    # Layer 2: NOT of that output (with bias at index 1)
    # We handle this inline since the bias must thread through
    net = MPNetwork(input_size=2)
    # Layer 1: AND
    net.add_layer(
        [
            MPNeuron([0, 1], [], threshold=2, name="AND"),
            MPNeuron(
                [], [], threshold=999, name="bias"
            ),  # always 0 — we inject bias below
        ]
    )
    return net  # caller uses nand_output for proper bias handling


def nand_output(x0: int, x1: int) -> int:
    """NAND via two-layer MP network."""
    # Layer 1: AND
    and_val = 1 if (x0 + x1) >= 2 else 0
    # Layer 2: NOT(and_val) with bias
    return not_output(and_val)


def xor_output(x0: int, x1: int) -> int:
    """
    XOR requires 3 layers in MP model:
    XOR(a,b) = OR(AND(a, NOT(b)), AND(NOT(a), b))
    Simplified: XOR(a,b) = AND(OR(a,b), NAND(a,b))
    """
    or_val = 1 if (x0 + x1) >= 1 else 0
    nand_val = nand_output(x0, x1)
    return 1 if (or_val + nand_val) >= 2 else 0


# ─────────────────────────────────────────────
# 4. Truth Table Verifier
# ─────────────────────────────────────────────


def verify_gate(name: str, fn: Callable, expected: Dict[Tuple, int]) -> bool:
    """Check that fn matches expected truth table."""
    ok = True
    for inputs, expected_out in expected.items():
        actual = fn(*inputs)
        status = "✓" if actual == expected_out else "✗"
        if actual != expected_out:
            ok = False
        print(f"  {name}({', '.join(str(i) for i in inputs)}) = {actual}  [{status}]")
    return ok


# ─────────────────────────────────────────────
# 5. Sequence Recognition: "fires on 1,0,1"
#    Demonstrates temporal logic in MP nets
# ─────────────────────────────────────────────


class TemporalMPNetwork:
    """
    McCulloch-Pitts network with unit delay — each neuron's output
    at time t feeds neurons at time t+1.
    Simulates temporal sequence detection.
    """

    def __init__(self, size: int):
        self.size = size
        self.state: List[int] = [0] * size

    def step(self, external: List[int], neurons: List[MPNeuron]) -> List[int]:
        """
        One timestep: combine external inputs with delayed state.
        Returns new state.
        """
        combined = list(external) + list(self.state)
        new_state = [n.activate(combined) for n in neurons]
        self.state = new_state
        return new_state


def demo_sequence_detector():
    """
    Detect the pattern 101 in a binary stream.
    Three state neurons:
      s0: last input was 1
      s1: last two inputs were 1,0  (s0 was 1, current is 0)
      s2: last three inputs were 1,0,1  (s1 was 1, current is 1)
    Inputs: [x_current, s0_prev, s1_prev, s2_prev]
    Indices: 0=x, 1=s0, 2=s1, 3=s2
    """
    # s0 = x_current
    # s1 = AND(s0_prev=1, x_current=0) → excite [1], inhibit [0], thresh=1
    # s2 = AND(s1_prev=1, x_current=1) → excite [0,2], thresh=2
    neurons = [
        MPNeuron([0], [], threshold=1, name="s0"),  # s0 = x
        MPNeuron([1], [0], threshold=1, name="s1"),  # s1 = prev_x=1 AND cur_x=0
        MPNeuron(
            [0, 2], [], threshold=2, name="s2(detect)"
        ),  # s2 = cur_x=1 AND prev_s1=1
    ]
    net = TemporalMPNetwork(size=3)

    stream = [1, 0, 1, 1, 0, 1, 0, 0, 1, 0, 1]
    print("  Sequence:", " ".join(str(x) for x in stream))
    print("  Detecting pattern 101:")
    detections = []
    for t, x in enumerate(stream):
        state = net.step([x], neurons)
        s2 = state[2]
        if s2:
            detections.append(t)
        print(
            f"    t={t}: x={x}  s0={state[0]} s1={state[1]} s2={state[2]}  {'← DETECTED 101' if s2 else ''}"
        )
    print(f"  Pattern detected at time steps: {detections}")
    # Manual check: 101 ends at t=2, t=5, t=10
    return detections


# ─────────────────────────────────────────────
# 6. Comparison: MP Neuron vs Modern Perceptron
# ─────────────────────────────────────────────


@dataclass
class Perceptron:
    """Rosenblatt-style perceptron (1958). Real-valued weights, learned threshold."""

    weights: List[float]
    bias: float

    def activate(self, inputs: List[float]) -> int:
        total = sum(w * x for w, x in zip(self.weights, inputs)) + self.bias
        return 1 if total >= 0 else 0

    def train_step(self, inputs: List[float], target: int, lr: float = 0.1) -> None:
        pred = self.activate(inputs)
        error = target - pred
        self.weights = [w + lr * error * x for w, x in zip(self.weights, inputs)]
        self.bias += lr * error


def train_perceptron_and(epochs: int = 100) -> Perceptron:
    p = Perceptron([0.0, 0.0], 0.0)
    data = [([0, 0], 0), ([0, 1], 0), ([1, 0], 0), ([1, 1], 1)]
    for _ in range(epochs):
        for inputs, target in data:
            p.train_step(inputs, target)
    return p


# ─────────────────────────────────────────────
# 7. Demonstrations
# ─────────────────────────────────────────────


def demo_boolean_gates():
    print("=" * 60)
    print("McCulloch-Pitts Boolean Gates")
    print("=" * 60)

    print("\n  AND gate (θ=2, excitatory both inputs):")
    and_net = make_AND()
    for x0, x1 in itertools.product([0, 1], repeat=2):
        print(f"    AND({x0},{x1}) = {and_net.output([x0, x1])}")

    print("\n  OR gate (θ=1):")
    or_net = make_OR()
    for x0, x1 in itertools.product([0, 1], repeat=2):
        print(f"    OR({x0},{x1}) = {or_net.output([x0, x1])}")

    print("\n  NOT gate (absolute inhibition):")
    for x in [0, 1]:
        print(f"    NOT({x}) = {not_output(x)}")

    print("\n  NAND gate (2 layers):")
    for x0, x1 in itertools.product([0, 1], repeat=2):
        print(f"    NAND({x0},{x1}) = {nand_output(x0, x1)}")

    print("\n  XOR gate (3 layers — cannot be done in single MP neuron):")
    for x0, x1 in itertools.product([0, 1], repeat=2):
        print(f"    XOR({x0},{x1}) = {xor_output(x0, x1)}")
    print()


def demo_truth_table_verification():
    print("=" * 60)
    print("Truth Table Verification")
    print("=" * 60)
    and_net = make_AND()
    or_net = make_OR()

    verify_gate(
        "AND",
        lambda a, b: and_net.output([a, b]),
        {(0, 0): 0, (0, 1): 0, (1, 0): 0, (1, 1): 1},
    )
    verify_gate(
        "OR",
        lambda a, b: or_net.output([a, b]),
        {(0, 0): 0, (0, 1): 1, (1, 0): 1, (1, 1): 1},
    )
    verify_gate("NOT", lambda a: not_output(a), {(0,): 1, (1,): 0})
    verify_gate("NAND", nand_output, {(0, 0): 1, (0, 1): 1, (1, 0): 1, (1, 1): 0})
    verify_gate("XOR", xor_output, {(0, 0): 0, (0, 1): 1, (1, 0): 1, (1, 1): 0})
    print()


def demo_perceptron_comparison():
    print("=" * 60)
    print("MP Neuron vs Perceptron: Learning AND")
    print("=" * 60)
    p = train_perceptron_and(epochs=200)
    print(
        f"  Trained weights: {[round(w, 3) for w in p.weights]}, bias={round(p.bias, 3)}"
    )
    for x0, x1 in itertools.product([0, 1], repeat=2):
        pred = p.activate([x0, x1])
        expected = 1 if (x0 and x1) else 0
        status = "✓" if pred == expected else "✗"
        print(f"    Perceptron AND({x0},{x1}) = {pred} [{status}]")
    print()
    print("  Key difference:")
    print("    MP neuron: weights are fixed, hand-designed, binary threshold")
    print("    Perceptron: weights are learned from examples, real-valued")
    print()


if __name__ == "__main__":
    demo_boolean_gates()
    demo_truth_table_verification()

    print("=" * 60)
    print("Temporal Sequence Detection: Pattern 101 in binary stream")
    print("=" * 60)
    demo_sequence_detector()
    print()

    demo_perceptron_comparison()