evonet 0.1.0.dev27__py3-none-any.whl

evonet/activation.py

@@ -0,0 +1,207 @@
+# SPDX-License-Identifier: MIT
+"""
+Activation functions for evolvable neural networks.
+
+Includes standard nonlinearities (ReLU, Tanh, Sigmoid), linear and threshold functions,
+modern smooth activations (Swish, Mish), and a softmax utility.
+
+All functions are scalar-based and stateless, unless noted otherwise.
+"""
+
+import random
+from typing import Callable, List, Tuple, Union
+
+import numpy as np
+
+Scalar = Union[int, float]
+
+
+# Common Activation Functions
+
+
+def tanh(x: Scalar) -> float:
+    """Hyperbolic tangent activation: [-inf, inf] --> [-1, 1]."""
+    return float(np.tanh(x))
+
+
+def ntanh(x: Scalar) -> float:
+    """Normalized tanh: (tanh(x) + 1) / 2 --> [0, 1]."""
+    return (np.tanh(x) + 1) / 2
+
+
+def sigmoid(x: Scalar) -> float:
+    """Sigmoid/logistic function: [-inf, inf] --> [0, 1]."""
+    x = np.clip(float(x), -500, 500)
+    return 1 / (1 + np.exp(-x))
+
+
+def relu(x: Scalar) -> float:
+    """ReLU: max(0, x)."""
+    return max(0.0, float(x))
+
+
+def relu_max1(x: Scalar) -> float:
+    """ReLU clipped to [0, 1]."""
+    return min(max(0.0, float(x)), 1.0)
+
+
+def leaky_relu(x: Scalar, alpha: float = 0.01) -> float:
+    """Leaky ReLU: x if x ≥ 0 else alpha * x."""
+    x = float(x)
+    return x if x >= 0 else alpha * x
+
+
+def elu(x: Scalar, alpha: float = 1.0) -> float:
+    """Exponential Linear Unit."""
+    x = float(x)
+    return x if x >= 0 else alpha * (np.exp(x) - 1)
+
+
+def selu(x: Scalar, alpha: float = 1.67326324, scale: float = 1.05070098) -> float:
+    """Scaled Exponential Linear Unit (SELU)."""
+    x = float(x)
+    return scale * x if x >= 0 else scale * alpha * (np.exp(x) - 1)
+
+
+def gaussian(x: Scalar) -> float:
+    """Gaussian bell function: exp(-x^2)."""
+    x = float(x)
+    if np.abs(x) > 38:
+        return 0.0
+    return np.exp(-(x**2))
+
+
+# Threshold Functions
+
+
+def binary(x: Scalar) -> float:
+    """Step function: 1 if x > 0 else 0."""
+    return 1.0 if x > 0 else 0.0
+
+
+def signum(x: Scalar) -> float:
+    """Sign function: 1, -1 or 0 depending on sign of x."""
+    return 1.0 if x > 0 else -1.0 if x < 0 else 0.0
+
+
+# Linear Variants
+
+
+def linear(x: Scalar) -> float:
+    """Linear identity: returns x."""
+    return float(x)
+
+
+def linear_max1(x: Scalar) -> float:
+    """Linear function clipped to [-1, 1]."""
+    return min(max(-1.0, float(x)), 1.0)
+
+
+def invert(x: Scalar) -> float:
+    """Returns -x."""
+    return -float(x)
+
+
+def null(_: Scalar = 0) -> float:
+    """Always returns 0.0."""
+    return 0.0
+
+
+# Modern Functions
+
+
+def swish(x: Scalar) -> float:
+    """Swish activation: x * sigmoid(x). Smooth and non-monotonic."""
+    return float(x) * sigmoid(x)
+
+
+def mish(x: Scalar) -> float:
+    """Mish activation: x * tanh(softplus(x))."""
+    return float(x) * np.tanh(np.log1p(np.exp(x)))
+
+
+def softplus(x: Scalar) -> float:
+    """Smooth ReLU approximation: log(1 + exp(x))."""
+    return np.log1p(np.exp(float(x)))
+
+
+def softsign(x: Scalar) -> float:
+    """Smooth alternative to tanh: x / (1 + |x|)."""
+    return float(x) / (1 + abs(float(x)))
+
+
+def hard_sigmoid(x: Scalar) -> float:
+    """Piecewise linear approximation of sigmoid."""
+    return min(max(0.0, 0.2 * float(x) + 0.5), 1.0)
+
+
+# Special Functions
+
+
+def softmax(values: Union[List[float], Tuple[float], np.ndarray]) -> np.ndarray:
+    """
+    Applies softmax over a list of values.
+
+    Args:
+        values: Array-like input with ≥2 values.
+
+    Returns:
+        np.ndarray: Normalized softmax output summing to 1.
+    """
+    arr = np.array(values, dtype=float)
+    if arr.size < 2:
+        raise ValueError("Softmax input must have at least two values")
+    exp_x = np.exp(arr - np.max(arr))  # For numerical stability
+    return exp_x / np.sum(exp_x)
+
+
+def random_function_name(activations: list[str] | None = None) -> str:
+    """
+    Return a random activation function name from the registry.
+
+    Args:
+        activations (list[str] | None): Optional subset of allowed function names.
+            If None, all registered activation names are considered.
+
+    Raises:
+        ValueError: If any name is not in the activation registry.
+
+    Returns:
+        str: Randomly selected activation function name.
+    """
+
+    if activations is None:
+        activations = list(ACTIVATIONS.keys())
+
+    invalid = set(activations) - set(ACTIVATIONS.keys())
+    if invalid:
+        raise ValueError(f"Invalid activation functions: {invalid}")
+
+    return random.choice(activations)
+
+
+# Registry
+
+ACTIVATIONS: dict[str, Callable] = {
+    "tanh": tanh,
+    "ntanh": ntanh,
+    "sigmoid": sigmoid,
+    "relu": relu,
+    "relu_max1": relu_max1,
+    "leaky_relu": leaky_relu,
+    "elu": elu,
+    "selu": selu,
+    "gaussian": gaussian,
+    "binary": binary,
+    "signum": signum,
+    "linear": linear,
+    "linear_max1": linear_max1,
+    "invert": invert,
+    "null": null,
+    "swish": swish,
+    "mish": mish,
+    "softplus": softplus,
+    "softsign": softsign,
+    "hard_sigmoid": hard_sigmoid,
+    "softmax": softmax,
+}

evonet/connection.py

@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: MIT
+"""
+Connection between neurons in an evolvable neural network.
+
+A connection links a source neuron to a target neuron and transmits a weighted signal.
+Supports optional connection types for specialized behaviors (e.g. inhibitory,
+recurrent).
+"""
+
+
+from collections import deque
+from typing import TYPE_CHECKING, Deque, Optional
+
+from evonet.enums import ConnectionType
+
+if TYPE_CHECKING:
+    from evonet.neuron import Neuron
+
+
+class Connection:
+    """
+    Represents a directed, weighted connection between two neurons.
+
+    Attributes:
+        source (Neuron): The source neuron (presynaptic).
+        target (Neuron): The target neuron (postsynaptic).
+        weight (float): Multiplicative weight of the transmitted signal.
+        delay (int): Delay in discrete time steps (used for recurrent edges).
+        type (ConnectionType): Type of connection (e.g. standard, recurrent).
+    """
+
+    def __init__(
+        self,
+        source: "Neuron",
+        target: "Neuron",
+        weight: float = 1.0,
+        delay: int = 0,
+        conn_type: ConnectionType = ConnectionType.STANDARD,
+    ) -> None:
+
+        if delay < 0:
+            raise ValueError("delay must be >= 0")
+
+        # Normalize: recurrent implies delay >= 1
+        if conn_type is ConnectionType.RECURRENT and delay == 0:
+            delay = 1
+
+        self.source = source
+        self.target = target
+        self.weight = weight
+        self.delay = delay
+        self.type = conn_type
+
+        self._history: Optional[Deque[float]] = None
+        if self.type is ConnectionType.RECURRENT:
+            self._history = deque(maxlen=self.delay)
+
+    def set_delay(self, delay: int) -> None:
+        if self.type is not ConnectionType.RECURRENT:
+            raise ValueError("set_delay is only valid for recurrent connections")
+        if delay <= 0:
+            delay = 1
+        self.delay = int(delay)
+        self._history = deque(maxlen=self.delay)
+
+    def push_source_output(self, value: float) -> None:
+        """
+        Push the current source output into the delay buffer.
+
+        This should be called once per time step after the network computed outputs.
+        """
+        if self._history is None:
+            return
+        self._history.append(float(value))
+
+    def delayed_source_output(self) -> float:
+        """
+        Return the delayed source output.
+
+        Semantics:
+            - delay == 0  -> no delay buffer used (caller decides what to do)
+            - delay > 0   -> returns output[t-delay] if available else 0.0
+        """
+        if self.delay == 0:
+            return 0.0
+
+        if self._history is None:
+            return 0.0
+
+        if len(self._history) < self.delay:
+            return 0.0
+
+        return float(self._history[0])
+
+    def reset_buffer(self) -> None:
+        """Clear the internal delay history buffer."""
+        if self._history is not None:
+            self._history.clear()
+
+    def get_signal(self) -> float:
+        """
+        Return the weighted signal from the source neuron.
+
+        Returns:
+            float: source.output × weight
+        """
+
+        return self.source.output * self.weight
+
+    def __repr__(self) -> str:
+        """
+        Return a concise string representation of the connection.
+
+        Example:
+            <Conn abc123 -> def456 w=0.85 d=3 type=standard>
+        """
+
+        type_str = self.type.name.lower()
+        return (
+            f"<Conn {self.source.id[:6]} "
+            f"-> {self.target.id[:6]} "
+            f"d={self.delay} "
+            f"w={self.weight:.2f} type={type_str}>"
+        )