evolib 0.2.0b4.dev7__tar.gz → 0.2.0b4.dev9__tar.gz

{evolib-0.2.0b4.dev7/evolib.egg-info → evolib-0.2.0b4.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: evolib
-Version: 0.2.0b4.dev7
+Version: 0.2.0b4.dev9
 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.dev7 → evolib-0.2.0b4.dev9}/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.dev7 → evolib-0.2.0b4.dev9}/docs/config_guide.md

@@ -30,7 +30,7 @@ evolution:
 modules:
   test-vector:              # logical module name
     type: vector
-    initializer: random_vector
+    initializer: uniform
     dim: 2
     bounds: [-1.0, 1.0]
 
@@ -89,7 +89,7 @@ modules:
   xs:
     type: vector
     dim: 6
-    initializer: random_vector
+    initializer: uniform
     bounds: [0.0, 6.283185307]   # [0, 2π]
     mutation:
       strategy: adaptive_individual
@@ -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.dev7 → evolib-0.2.0b4.dev9}/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. `uniform`, `zero`, `normal`, `fixed`). |
+| `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: uniform
     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 | Topology preset (e.g. `default`, `unconnected`, `identity`). 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`       | 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.dev7 → evolib-0.2.0b4.dev9}/evolib/config/evonet_component_config.py

@@ -30,6 +30,7 @@ from evolib.config.base_component_config import (
     EvoNetNeuronDynamicsConfig,
     StructuralMutationConfig,
 )
+from evolib.interfaces.enums import RepresentationType
 
 Bounds = Tuple[float, float]
 
@@ -189,7 +190,6 @@ 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
@@ -209,7 +209,10 @@ class EvoNetComponentConfig(BaseModel):
     model_config = ConfigDict(extra="forbid")
 
     # Module type is fixed to "evonet"
-    type: Literal["evonet"] = "evonet"
+    type: RepresentationType = Field(
+        default=RepresentationType.EVONET,
+        description='Fixed module discriminator; must be "evonet" for this schema.',
+    )
 
     # Layer structure: list of neuron counts per layer [input, hidden..., output]
     dim: list[int]
@@ -228,7 +231,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", description="Name of the initializer to use"
+    )
 
     # Connection topology for initialization
     connection_scope: Literal["adjacent", "crosslayer"] = Field(
@@ -266,6 +271,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",
+            "unconnected",
+            "identity",
+        }
+
+        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.dev7 → evolib-0.2.0b4.dev9}/evolib/config/vector_component_config.py

@@ -1,7 +1,14 @@
 # SPDX-License-Identifier: MIT
 from typing import Any, Literal, Optional, Tuple, Union
 
-from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+from pydantic import (
+    BaseModel,
+    ConfigDict,
+    Field,
+    ValidationInfo,
+    field_validator,
+    model_validator,
+)
 
 from evolib.config.base_component_config import CrossoverConfig, MutationConfig
 from evolib.interfaces.enums import RepresentationType
@@ -21,7 +28,7 @@ class VectorComponentConfig(BaseModel):
             type: vector
             structure: flat              # "flat" | "net"
             dim: 16                      # or a list for structured cases
-            initializer: random_vector   # name from the initializer registry
+            initializer: normal          # name from the initializer registry
             bounds: [-1.0, 1.0]
             mutation:
               strategy: constant
@@ -86,7 +93,7 @@ class VectorComponentConfig(BaseModel):
     values: Optional[list[float]] = Field(
         default=None,
         description=(
-            "Explicit values for 'fixed_vector' initializer. If 'dim' is absent it "
+            "Explicit values for 'fixed' initializer. If 'dim' is absent it "
             "will be inferred from the length of 'values'."
         ),
     )
@@ -101,8 +108,7 @@ class VectorComponentConfig(BaseModel):
     )
 
     # Evolution (mutation / crossover)
-    mutation: Optional[MutationConfig] = Field(
-        default=None,
+    mutation: MutationConfig = Field(
         description=(
             "Mutation configuration. By default, 'probability' is an element-wise rate "
             "(per gene) in [0,1]; operators may optionally treat it as an apply gate."
@@ -143,18 +149,16 @@ class VectorComponentConfig(BaseModel):
     @classmethod
     def set_dim_for_fixed_vector(cls, config: dict[str, Any]) -> dict[str, Any]:
         """
-        If using 'fixed_vector', ensure 'values' is provided and infer 'dim' if absent.
+        If using 'fixed', ensure 'values' is provided and infer 'dim' if absent.
 
         This keeps YAML concise and catches common mistakes early.
         """
         initializer = config.get("initializer")
         values = config.get("values")
 
-        if initializer == "fixed_vector":
+        if initializer == "fixed":
             if not values:
-                raise ValueError(
-                    "When using 'fixed_vector', 'values' must be provided."
-                )
+                raise ValueError("When using 'fixed', 'values' must be provided.")
             if "dim" not in config:
                 config["dim"] = len(values)
         return config
@@ -181,3 +185,30 @@ class VectorComponentConfig(BaseModel):
         else:
             raise TypeError("dim must be an int or list of ints")
         return dim
+
+    @field_validator("initializer")
+    @classmethod
+    def validate_initializer(cls, name: str, info: ValidationInfo) -> str:
+        """Validate allowed initializer names and provide clear errors for deprecated
+        names."""
+        if not isinstance(name, str) or not name.strip():
+            raise ValueError("initializer must be a non-empty string")
+
+        name = name.strip()
+
+        allowed = {"normal", "uniform", "zero", "fixed", "adaptive"}
+        if name not in allowed:
+            raise ValueError(
+                f"Unknown initializer '{name}'. " f"Allowed: {sorted(allowed)}"
+            )
+
+        # structure-aware check (only if structure is available in the data)
+        data = info.data or {}
+        structure = data.get("structure") or "flat"
+        if structure == "net" and name != "normal":
+            raise ValueError(
+                "For structure='net', initializer must be 'normal' "
+                "(use initializer: normal and structure: net)."
+            )
+
+        return name

{evolib-0.2.0b4.dev7 → evolib-0.2.0b4.dev9}/evolib/initializers/evonet_initializers.py

@@ -173,28 +173,7 @@ def _build_architecture(
         )
 
 
-def initializer_unconnected_evonet(config: FullConfig, module: str) -> EvoNet:
-    """
-    Initializes an EvoNet without connections.
-
-    Args:
-        config (FullConfig): Full experiment configuration
-        module (str): Module name (e.g. "brain")
-
-    Returns:
-        EvoNet: Initialized EvoNet representation
-    """
-    para = EvoNet()
-    cfg = config.modules[module].model_copy(deep=True)
-    para.apply_config(cfg)
-
-    _build_architecture(para, cfg, connection_init="none")
-    _apply_bias_init(para, cfg)
-
-    return para
-
-
-def initializer_normal_evonet(config: FullConfig, module: str) -> EvoNet:
+def initializer_default_evonet(config: FullConfig, module: str) -> EvoNet:
     """
     Build a standard EvoNet architecture and initialize parameters according to the
     explicit configuration blocks.
@@ -203,9 +182,6 @@ def initializer_normal_evonet(config: FullConfig, module: str) -> EvoNet:
     - Weights are initialized using `cfg.weights`.
     - Biases are initialized using `cfg.bias`.
     - Delay (if configured) is initialized using `cfg.delay`.
-
-    No implicit parameter initialization is performed here.
-    All parameter distributions are controlled explicitly via the config.
     """
 
     para = EvoNet()
@@ -219,36 +195,23 @@ def initializer_normal_evonet(config: FullConfig, module: str) -> EvoNet:
     return para
 
 
-def initializer_random_evonet(config: FullConfig, module: str) -> EvoNet:
-    """
-    Backward-compatible alias for the standard EvoNet initializer. Will be removed.
-
-    Parameter initialization is controlled by `cfg.weights`, `cfg.bias`,
-    and `cfg.delay`.
-    """
-    return initializer_normal_evonet(config, module)
-
-
-def initializer_zero_evonet(config: FullConfig, module: str) -> EvoNet:
+def initializer_unconnected_evonet(config: FullConfig, module: str) -> EvoNet:
     """
-    Build a standard EvoNet architecture and initialize all parameters to zero.
+    Initializes an EvoNet without connections.
 
-    - All connection weights are set to 0.
-    - All biases are set to 0.
-    - Delay initialization follows `cfg.delay` if applicable.
+    Args:
+        config (FullConfig): Full experiment configuration
+        module (str): Module name (e.g. "brain")
 
-    This initializer ignores `cfg.weights` and `cfg.bias` distributions.
+    Returns:
+        EvoNet: Initialized EvoNet representation
     """
-
     para = EvoNet()
     cfg = config.modules[module].model_copy(deep=True)
     para.apply_config(cfg)
 
-    _build_architecture(para, cfg, connection_init="zero")
-    _apply_delay_init(para, cfg)
-
-    para.net.set_weights(np.zeros(para.net.num_weights))
-    para.net.set_biases(np.zeros(para.net.num_biases))
+    _build_architecture(para, cfg, connection_init="none")
+    _apply_bias_init(para, cfg)
 
     return para