evolib 0.2.0b4.dev6__tar.gz → 0.2.0b4.dev8__tar.gz

{evolib-0.2.0b4.dev6/evolib.egg-info → evolib-0.2.0b4.dev8}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evolib
-Version: 0.2.0b4.dev6
+Version: 0.2.0b4.dev8
 Summary: A modular framework for evolutionary strategies and neuroevolution.
 Author-email: EvoLib <evolib@dismail.de>
 License: MIT License
@@ -164,7 +164,6 @@ modules:
     type: evonet
     dim: [4, 6, 2]
     activation: [linear, tanh, tanh]
-    initializer: normal_evonet
     mutation:
       strategy: constant
       probability: 1.0

{evolib-0.2.0b4.dev6 → evolib-0.2.0b4.dev8}/README.md

@@ -105,7 +105,6 @@ modules:
     type: evonet
     dim: [4, 6, 2]
     activation: [linear, tanh, tanh]
-    initializer: normal_evonet
     mutation:
       strategy: constant
       probability: 1.0

{evolib-0.2.0b4.dev6 → evolib-0.2.0b4.dev8}/docs/config_guide.md

@@ -145,11 +145,14 @@ modules:
     type: evonet
     dim: [2, 0, 0, 1]       # hidden layers start empty
     activation: [linear, tanh, tanh, sigmoid]
-    initializer: normal_evonet
     weights:
+      initializer: normal
+      std: 0.5
       bounds: [-5.0, 5.0]
-    bias:
-        bounds: [-1.0, 1.0]
+    bias:      
+      initializer: normal
+      std: 0.5
+      bounds: [-1.0, 1.0]
 
     recurrent: direct   # REQUIRED for delay to have any effect
 
@@ -157,7 +160,7 @@ modules:
     # If `recurrent` is not enabled, this block has no effect.
     delay:
       initializer: uniform   # uniform | fixed
-      bounds: [1, 8]        # only for random
+      bounds: [1, 8]
       # value: 3            # only for fixed
 
     mutation:

{evolib-0.2.0b4.dev6 → evolib-0.2.0b4.dev8}/docs/config_parameter.md

@@ -138,44 +138,146 @@ evolution:
 ## Modules
 
 Modules define the parameter representation(s) of each individual. Multiple modules can be combined.
+Depending on `structure`, the vector can represent a simple flat genome or a
+structured parameter layout (e.g. network-like interpretation).
+
+---
+
+### Vector Module
+
+The `vector` module defines an evolvable parameter vector.
+
+| Parameter                        | Type                                              | Default        | Description |
+|----------------------------------|---------------------------------------------------|----------------|------------|
+| `type`                           | `"vector"`                                        | —              | Module type identifier. |
+| `dim`                            | `int \| list[int]`                                | —              | Vector length (`int`) or structured dimensions (`list[int]`). Must be > 0. |
+| `structure`                      | `"flat" \| "net"                                  | `"flat"`       | Structural interpretation of the vector. |
+| `initializer`                    | `str`                                             | —              | Initializer name from the registry (e.g. `random_vector`, `zero_vector`, `normal_vector`, `fixed_vector`). |
+| `bounds`                         | `tuple[float, float]`                             | `[-1.0, 1.0]`  | Hard clamp range applied after mutation. |
+| `init_bounds`                    | `tuple[float, float] \| null`                     | `null`         | Clamp applied only during initialization. Falls back to `bounds` if not set. |
+| `shape`                          | `tuple[int, ...] \| null`                         | `null`         | Optional explicit shape. If set, `dim = product(shape)`. Shape is retained as metadata. |
+| `values`                         | `list[float] \| null`                             | `null`         | Required for `initializer: fixed_vector`. If `dim` is omitted, it is inferred from `len(values)`. |
+| `activation`                     | `str \| null`                                     | `null`         | Only relevant if `structure: "net"`. |
+| `mean`                           | `float \| null`                                   | `0.0`          | Mean parameter for normal-based initializers (if used by initializer). |
+| `std`                            | `float \| null`                                   | `1.0`          | Standard deviation for normal-based initializers (if used by initializer). |
+| `mutation`                       | `dict`                                            | —              | **Required.** Mutation configuration (see below). |
+| `randomize_mutation_strengths`   | `bool \| null`                                    | `false`        | If true, per-parameter strengths are randomly initialized within min/max bounds (strategy-dependent). |
+| `tau`                            | `float \| null`                                   | `0.0`          | Scaling factor for self-adaptive mutation strategies. Interpretation is strategy-dependent. |
+| `crossover`                      | `dict \| null`                                    | `null`         | Optional crossover configuration. Semantics depend on operator. |
+
+
+## Mutation Configuration
+
+The `mutation` block must follow the `MutationConfig` schema.
 
 ### Common Fields
 
-| Parameter    | Type | Default | Explanation                                                 |
-|--------------|------|---------|-------------------------------------------------------------|
-| `type`       | str  | —       | Type of parameter representation (`vector`, `evonet`, ...). |
-| `initializer`| str  | —       | Initialization method for the module.                       |
-| `bounds`     | list | —       | Lower and upper limits for values (only for vectors).       |
+| Parameter       | Type     | Description |
+|-----------------|----------|-------------|
+| `strategy`      | `str`    | Mutation strategy (e.g. `constant`, `adaptive_individual`, `adaptive_global`). |
+| `probability`   | `float`  | Mutation probability.|
+| `strength`      | `float`  | Mutation strength.|
 
 ---
 
-### Vector Module
+### Strategy: `constant`
 
-| Parameter     | Type        | Default | Explanation                                                                  |
-|---------------|-------------|---------|------------------------------------------------------------------------------|
-| `dim`         | int         | —       | Dimensionality of the vector.                                                |
-| `initializer` | str         | —       | Initialization method (e.g. `normal_vector`, `random_vector`, `zero_vector`).|
-| `bounds`      | list        | —       | Hard bounds for values.                                                      |
-| `init_bounds` | list \| null | null    | Bounds used during initialization (fallback to `bounds` if omitted).        |
-| `values`      | list \| null | null    | Fixed values for `initializer: fixed_vector`.                               |
-| `mutation`    | dict \| null | null    | Mutation settings for the vector.                                           |
-| `crossover`   | dict \| null | null    | Crossover settings for the vector.                                          |
+Uses a fixed mutation strength.
+
+Requires:
+- `probability`
+- `strength`
+
+```yaml
+mutation:
+  strategy: constant
+  probability: 1.0
+  strength: 0.05
+```
+
+### Strategy: `adaptive_individual`
+
+Self-adaptive mutation at the individual level.
+
+Requires:
+- `probability`
+- `min_strength`
+- `max_strength`
+
+```yaml
+mutation:
+  strategy: adaptive_individual
+  probability: 1.0
+  min_strength: 0.01
+  max_strength: 0.05
+```
+
+### Strategy: `adaptive_global`
+
+Global self-adaptive mutation strength shared across parameters.
+
+```yaml
+mutation:
+  strategy: adaptive_global
+  probability: 1.0
+  min_strength: 0.01
+  max_strength: 0.1
+```
 
-Example:
+
+### Minimal Example:
 
 ```yaml
 modules:
   main:
     type: vector
     dim: 8
-    initializer: normal_vector
+    initializer: random_vector
     bounds: [-1.0, 1.0]
+
     mutation:
-      strategy: adaptive_individual
+      strategy: constant
       probability: 1.0
-      strength: 0.1
+      strength: 0.05
+```
+
+### Fixed Vector Example
+```yaml
+modules:
+  main:
+    type: vector
+    initializer: fixed_vector
+    values: [0.0, 1.0, 0.5, -0.5]
+    bounds: [-1.0, 1.0]
+
+    mutation:
+      strategy: constant
+      probability: 1.0
+      strength: 0.01
 ```
+If dim is omitted, it is inferred from values.
 
+### Advanced Example (Self-Adaptive)
+```yaml
+modules:
+  main:
+    type: vector
+    structure: flat
+    dim: 6
+    initializer: normal_vector
+    mean: 0.0
+    std: 0.2
+    bounds: [-1.0, 1.0]
+
+    mutation:
+      strategy: adaptive_individual
+      probability: 0.8
+      min_strength: 0.01
+      max_strength: 0.05
+
+    tau: 0.0
+    randomize_mutation_strengths: false
+```
 ---
 
 ### EvoNet Module
@@ -186,7 +288,7 @@ modules:
 |-------------------|---------------------|---------|-------------|
 | `dim`             | list[int]           | —       | Layer sizes, e.g. `[4, 0, 0, 2]`. Hidden layers can start empty (0) and grow through structural mutation. |
 | `activation`      | str \| list[str]    | —       | If list: activation per layer. If str: used for non-input layers; input layer is treated as linear. |
-| `initializer`     | str                 | —       | Network initialization method (e.g. `normal_evonet`, `unconnected_evonet`). |
+| `initializer`     | str                 | default_evonet       | Topology preset (e.g. `default_evonet`, `unconnected_evonet`, `identity_evonet`). Parameter initialization is configured via `weights`, `bias`, and `delay`. |
 | `weights`         | dict                | —       | Weight init and bounds configuration (initializer, bounds, optional params). | 
 | `bias`            | dict                | —       | Bias init and bounds configuration (initializer, bounds, optional params). | 
 | `neuron_dynamics` | list[dict] \| null  | null    | Optional per-layer neuron dynamics specification. Must match `len(dim)`. |
@@ -197,30 +299,34 @@ modules:
 |Parameter	 | Type	 | Default	 | Explanation |
 |------------|-------|-----------|-------------|
 |initializer | str   | "normal"	 | Weight initializer preset (normal, uniform, zero, …). |
-|bounds	     | list[float]	| [-1.0, 1.0]	| Hard clipping bounds [min_w, max_w]. |
+|bounds	     | list[float]	| [-0.5, 0.5]	| Hard clipping bounds. |
 |std         | float | null	|null | Std-dev for normal (if used). |
 
 ##### bias block
 |Parameter	 | Type	 | Default	 | Explanation |
 |------------|-------|-----------|-------------|
-|initializer | str   | "normal"	 | Weight initializer preset (normal, uniform, zero, …). |
-|bounds	     | list[float]	| [-1.0, 1.0]	| Hard clipping bounds [min_w, max_w]. |
-|std         | float | null	|null | Std-dev for normal (if used). |
+|initializer | str   | "normal"	 | Bias initializer preset (normal, uniform, zero, …). |
+|bounds	     | list[float]	| [-1.0, 1.0]	| Hard clipping bounds. |
+|std         | float | null	| Std-dev for normal (if used). |
 
 ---
 
-#### EvoNet Initializer
+#### EvoNet Initializer (Topology Presets)
+
+`initializer` selects a **topology preset**.  
 
-The EvoNet module uses:
+Parameter initialization is configured via:
+- `weights`
+- `bias`
+- `delay` (recurrent connections only)
 
-| Initializer         | Weights                            | Biases                           | Notes                                       |
-|---------------------|------------------------------------|----------------------------------|---------------------------------------------|
-| `normal_evonet`     | Normal(0, 0.5)                     | Normal(0, 0.5)                   | Default initializer for general use         |
-| `unconnected_evonet`| None                               | 0                                | For pure structural growth; empty topology  |
-| `random_evonet`     | Random                             | Uniform(bias bounds)             | For broader stochastic exploration           |
-| `zero_evonet`       | 0                                  | 0                                | Deterministic baseline; debugging            |
-| `identity_evonet`   | Small random                       | Small random                     | Designed for stable recurrent memory         |
+Allowed presets:
 
+| Initializer            | Meaning (topology only) |
+|------------------------|-------------------------|
+| `default_evonet`       | Standard EvoNet topology preset (uses `connection_scope`, `connection_density`, and `recurrent`). |
+| `unconnected_evonet`   | Creates neurons/layers but starts with **no connections** (use structural mutation to grow). |
+| `identity_evonet`      | Special preset intended for stable recurrent memory (may override parameters internally; see notes below). |
 
 ---
 
@@ -246,7 +352,6 @@ modules:
     type: evonet
     dim: [1, 16, 1]
     activation: [linear, tanh, sigmoid]
-    initializer: normal_evonet
     neuron_dynamics:
       - name: standard
         params: {}
@@ -276,7 +381,7 @@ modules:
     ...
     delay:
       initializer: uniform  # uniform | fixed
-      bounds: [1, 8]        # only for random
+      bounds: [1, 8]
       # value: 3            # only for fixed
 ```
 
@@ -390,9 +495,9 @@ structural:
 
 | Field                | Type          | Default  | Description |
 |---------------------|---------------|----------|-------------|
-| `recurrent`          | str           | `none`   | Controls recurrence: `none`, `direct`, `lateral`/`local`, `indirect`, or `all` (implementation-dependent aliases may exist). |
+| `recurrent`          | str           | `none`   | Controls recurrence: `none`, `direct`, `local` or `all`. |
 | `connection_scope`   | str           | `adjacent` | Allowed layer connectivity: `adjacent` (neighbor layers only) or `crosslayer` (any-to-any). |
-| `connection_density` | float \| null | null     | Optional density control for created connections (if supported). |
+| `connection_density` | float         | 1.0     | Fraction of possible connections initialized at creation time. |
 | `max_neurons`        | int \| null   | null     | Maximum number of non-input neurons (`null` = unlimited). |
 | `max_connections`    | int \| null   | null     | Maximum number of edges (`null` = unlimited). |
 
@@ -432,6 +537,8 @@ modules:
       strategy: adaptive_individual
       probability: 1.0
       strength: 0.1
+      min_strength: 0.01
+      max_strength: 0.05
 
   brain:
     type: evonet

{evolib-0.2.0b4.dev6 → evolib-0.2.0b4.dev8}/evolib/config/evonet_component_config.py

@@ -31,25 +31,112 @@ from evolib.config.base_component_config import (
     StructuralMutationConfig,
 )
 
+Bounds = Tuple[float, float]
+
 
 class WeightsConfig(BaseModel):
-    """Configuration for connection weight initialization and bounds."""
+    # None means: no parameter-level initialization requested (preset may initialize).
+    initializer: Optional[str] = None  # normal | uniform | zero | None
+    std: Optional[float] = None
+    bounds: Bounds = (-1.0, 1.0)  # mutation/search bounds
+    init_bounds: Optional[Bounds] = None  # init-time clipping bounds
 
-    initializer: Literal["normal", "uniform", "zero"] = "normal"
-    bounds: tuple[float, float] = Field(default=(-1.0, 1.0))
-    std: Optional[float] = (
-        None  # required if initializer == "normal" (optional for now)
-    )
+    @model_validator(mode="after")
+    def _validate(self) -> "WeightsConfig":
+        # Validate bounds
+        lo, hi = self.bounds
+        if lo >= hi:
+            raise ValueError("weights.bounds must satisfy lower < upper")
+
+        if self.init_bounds is not None:
+            ilo, ihi = self.init_bounds
+            if ilo >= ihi:
+                raise ValueError("weights.init_bounds must satisfy lower < upper")
+            if not (lo <= ilo and ihi <= hi):
+                raise ValueError("weights.init_bounds must lie within weights.bounds")
+
+        # Validate initializer-specific fields
+        if self.initializer is None:
+            # Preset-based initialization
+            if self.std is not None:
+                raise ValueError(
+                    "weights.std is not allowed when " "weights.initializer is not set"
+                )
+            return self
+
+        if self.initializer == "normal":
+            if self.std is None or self.std <= 0:
+                raise ValueError(
+                    "weights.std must be set and > 0 for initializer=normal"
+                )
+
+        elif self.initializer in ("uniform", "zero"):
+            if self.std is not None:
+                raise ValueError("weights.std is only allowed for initializer=normal")
+
+        else:
+            raise ValueError(f"Unknown weights initializer: {self.initializer}")
+
+        return self
 
 
 class BiasConfig(BaseModel):
-    """Configuration for Neuron-Bias nitialization and bounds."""
+    # None means: no parameter-level initialization requested (preset may initialize).
+    initializer: Optional[str] = None  # fixed | normal | uniform | zero | None
+    std: Optional[float] = None
+    value: Optional[float] = None
+    bounds: Bounds = (-0.5, 0.5)  # mutation/search bounds
+    init_bounds: Optional[Bounds] = None  # init-time clipping bounds (optional)
 
-    initializer: Literal["fixed", "normal", "uniform", "zero"] = "normal"
-    bounds: tuple[float, float] = Field(default=(-1.0, 1.0))
-    std: Optional[float] = (
-        None  # required if initializer == "normal" (optional for now)
-    )
+    @model_validator(mode="after")
+    def _validate(self) -> "BiasConfig":
+        # Validate bounds
+        lo, hi = self.bounds
+        if lo >= hi:
+            raise ValueError("bias.bounds must satisfy lower < upper")
+
+        if self.init_bounds is not None:
+            ilo, ihi = self.init_bounds
+            if ilo >= ihi:
+                raise ValueError("bias.init_bounds must satisfy lower < upper")
+            if not (lo <= ilo and ihi <= hi):
+                raise ValueError("bias.init_bounds must lie within bias.bounds")
+
+        # Validate initializer-specific fields
+        if self.initializer is None:
+            # Preset-based initialization
+            if self.std is not None:
+                raise ValueError(
+                    "bias.std is not allowed when bias.initializer is not set"
+                )
+            if self.value is not None:
+                raise ValueError(
+                    "bias.value is not allowed when bias.initializer is not set"
+                )
+            return self
+
+        if self.initializer == "fixed":
+            if self.value is None:
+                raise ValueError("bias.value is required for initializer=fixed")
+            if self.std is not None:
+                raise ValueError("bias.std is not allowed for initializer=fixed")
+
+        elif self.initializer == "normal":
+            if self.std is None or self.std <= 0:
+                raise ValueError("bias.std must be set and > 0 for initializer=normal")
+            if self.value is not None:
+                raise ValueError("bias.value is only allowed for initializer=fixed")
+
+        elif self.initializer in ("uniform", "zero"):
+            if self.std is not None:
+                raise ValueError("bias.std is only allowed for initializer=normal")
+            if self.value is not None:
+                raise ValueError("bias.value is only allowed for initializer=fixed")
+
+        else:
+            raise ValueError(f"Unknown bias initializer: {self.initializer}")
+
+        return self
 
 
 class DelayConfig(BaseModel):
@@ -102,15 +189,15 @@ class EvoNetComponentConfig(BaseModel):
             type: evonet
             dim: [4, 6, 2]                       # input, hidden, output
             activation: [linear, relu, sigmoid]  # single activation or list per layer
-            initializer: normal_evonet           # weight/bias initializer
 
             weights:
               initializer: normal
+              std: 0.5
               bounds: [-1.0, 1.0]
 
             bias:
-                initializer: uniform
-                bounds: [-0.5, 0.5]
+              initializer: uniform
+              bounds: [-0.5, 0.5]
 
             mutation:
               strategy: constant
@@ -140,7 +227,9 @@ class EvoNetComponentConfig(BaseModel):
     recurrent: Optional[Literal["none", "direct", "local", "all"]] = "none"
 
     # Name of the initializer function (resolved via initializer registry)
-    initializer: str = Field(..., description="Name of the initializer to use")
+    initializer: str = Field(
+        default="default_evonet", description="Name of the initializer to use"
+    )
 
     # Connection topology for initialization
     connection_scope: Literal["adjacent", "crosslayer"] = Field(
@@ -178,6 +267,29 @@ class EvoNetComponentConfig(BaseModel):
     structural: Optional[StructuralMutationConfig] = None
 
     # Validators
+    @field_validator("initializer")
+    @classmethod
+    def validate_initializer(cls, name: str) -> str:
+        """
+        Validate that the initializer is one of the allowed topology presets.
+
+        Parameter initialization is handled exclusively via weights/bias/delay blocks.
+        """
+        allowed = {
+            "default_evonet",
+            "unconnected_evonet",
+            "identity_evonet",
+        }
+
+        if name not in allowed:
+            raise ValueError(
+                f"Unknown EvoNet initializer '{name}'. "
+                f"Allowed values: {sorted(allowed)}. "
+                "Parameter initialization is configured via "
+                "'weights', 'bias', and 'delay'."
+            )
+
+        return name
 
     @field_validator("neuron_dynamics")
     @classmethod

{evolib-0.2.0b4.dev6 → evolib-0.2.0b4.dev8}/evolib/config/vector_component_config.py

@@ -101,7 +101,7 @@ class VectorComponentConfig(BaseModel):
     )
 
     # Evolution (mutation / crossover)
-    mutation: Optional[MutationConfig] = Field(
+    mutation: MutationConfig = Field(
         default=None,
         description=(
             "Mutation configuration. By default, 'probability' is an element-wise rate "