### Install NEAT Project

Source: https://github.com/lucidrains/neat/blob/main/README.md

Run this script in the project root to install the NEAT project dependencies.

```bash
$ sh install.sh
```

--------------------------------

### Install NEAT Library

Source: https://context7.com/lucidrains/neat/llms.txt

Clone the repository and run the install script to set up Nim and Python dependencies.

```bash
git clone https://github.com/lucidrains/neat
cd neat
sh install.sh
```

--------------------------------

### Complete NEAT Training Example - Lunar Lander

Source: https://context7.com/lucidrains/neat/llms.txt

Trains a NEAT population on the Lunar Lander environment using vectorized environments, island migration, and logging. Requires gymnasium.

```python
import numpy as np
import gymnasium as gym
from neat.neat import NEAT

# Configuration
num_generations = 250
pop_size = 250
max_episode_len = 250

# Create vectorized environments
envs = gym.make_vec("LunarLander-v3", num_envs=pop_size, vectorization_mode='sync')
dim_state = envs.observation_space.shape[-1]  # 8
num_actions = 4

# Initialize population with island-based evolution
population = NEAT(
    dim_state, num_actions,
    pop_size=pop_size,
    num_islands=5,
    mutation_hyper_params=dict(
        mutate_prob=0.95,
        use_fast_ga=False,
        add_novel_edge_prob=0.05,
        change_edge_weight_prob=0.5,
        grow_edge_prob=1e-3,
        grow_node_prob=5e-4,
        num_preserve_elites=2
    ),
    selection_hyper_params=dict(
        frac_natural_selected=0.15,
        tournament_size=3
    )
)

# Training loop
for gen in range(num_generations):
    # Reset environments
    state, _ = envs.reset()
    total_rewards = np.zeros(pop_size, dtype=np.float32)
    done = np.zeros(pop_size, dtype=bool)

    # Rollout
    for t in range(max_episode_len):
        # Get actions from population
        actions = population.forward(state, sample=True)
        next_state, reward, truncated, terminated, _ = envs.step(actions)

        # Accumulate rewards for non-done agents
        total_rewards += reward * (~done).astype(np.float32)
        done |= truncated | terminated
        state = next_state

        if done.all():
            break

    # Evolution step with periodic migration
    migrate = 5 if (gen + 1) % 25 == 0 else 0
    reset_islands = 1 if (gen + 1) % 50 == 0 else 0

    population.genetic_algorithm_step(
        total_rewards,
        migrate_num=migrate,
        reset_islands_num=reset_islands
    )

    # Logging
    stats = population.stats()[0]
    print(f"Gen {gen+1}: max={total_rewards.max():.1f}, "
          f"mean={total_rewards.mean():.1f}, "
          f"nodes={stats['total_innovated_nodes']}, "
          f"edges={stats['total_innovated_edges']}")

# Save final population
population.save_json('./final_population')
```

--------------------------------

### Get NEAT Population Statistics

Source: https://context7.com/lucidrains/neat/llms.txt

Retrieves statistics about the evolved population, such as the total number of innovated nodes and edges. Useful for monitoring evolutionary progress.

```python
from neat.neat import NEAT

population = NEAT(8, 4, pop_size=100)

# After several generations of evolution...
stats = population.stats()
# Returns list of dicts, one per topology
# stats[0] == {
#     'total_innovated_nodes': 42,
#     'total_innovated_edges': 156
# }

print(f"Nodes: {stats[0]['total_innovated_nodes']}, Edges: {stats[0]['total_innovated_edges']}")
```

--------------------------------

### GET /stats

Source: https://context7.com/lucidrains/neat/llms.txt

Retrieves the current evolutionary statistics for the population, including node and edge counts.

```APIDOC
## GET /stats

### Description
Returns information about the evolved topology, including total innovated nodes and edges across the population.

### Method
GET

### Response
#### Success Response (200)
- **stats** (list) - A list of dictionaries, one per topology, containing 'total_innovated_nodes' and 'total_innovated_edges'.
```

--------------------------------

### Run Quick Test for NEAT Project

Source: https://github.com/lucidrains/neat/blob/main/README.md

Execute this command to run a quick test of the NEAT project, specifically training Lunar Lander.

```bash
$ uv run train_lunar.py
```

--------------------------------

### Initialize NEAT Population

Source: https://context7.com/lucidrains/neat/llms.txt

Create a NEAT population for a control task with specified input/output dimensions, population size, and evolution hyperparameters.

```python
import numpy as np
from neat.neat import NEAT

# Create a NEAT population for a control task
# Input: 8-dimensional state, Output: 4 actions
population = NEAT(
    8, 4,                    # input dim, output dim
    pop_size=100,            # population size
    num_islands=5,           # island-based evolution for diversity
    mutation_hyper_params=dict(
        mutate_prob=0.95,
        add_novel_edge_prob=0.05,
        change_edge_weight_prob=0.5,
        grow_edge_prob=1e-3,
        grow_node_prob=5e-4,
        num_preserve_elites=2,
        max_weight_magnitude=5.0
    ),
    selection_hyper_params=dict(
        frac_natural_selected=0.15,
        tournament_size=3
    ),
    crossover_hyper_params=dict(
        prob_child_disabled_given_parent_cond=0.75,
        prob_inherit_all_excess_genes=1.0
    )
)
```

--------------------------------

### NEAT Initialization

Source: https://context7.com/lucidrains/neat/llms.txt

Initializes the NEAT population with specified dimensions and evolutionary hyperparameters.

```APIDOC
## NEAT Initialization

### Description
Initializes a new NEAT population with defined input/output dimensions and evolutionary configuration.

### Parameters
#### Request Body
- **input_dim** (int) - Required - Dimensionality of the input state.
- **output_dim** (int) - Required - Dimensionality of the output actions.
- **pop_size** (int) - Optional - Number of individuals in the population.
- **num_islands** (int) - Optional - Number of islands for population management.
- **mutation_hyper_params** (dict) - Optional - Configuration for mutation rates and probabilities.
- **selection_hyper_params** (dict) - Optional - Configuration for selection strategies.
- **crossover_hyper_params** (dict) - Optional - Configuration for crossover behavior.
```

--------------------------------

### Selection and Crossover Hyperparameters for NEAT

Source: https://context7.com/lucidrains/neat/llms.txt

Configures parameters for selecting parents and inheriting genes during crossover. Includes settings for the fraction of survivors, tournament size, queen bee GA variant, and probabilities related to disabling/removing genes and inheriting excess genes.

```python
selection_hyper_params = dict(
    frac_natural_selected=0.15,        # fraction surviving selection
    tournament_size=3,                  # parents per tournament
    use_queen_bee=False,                # queen bee GA variant
    queen_strong_mutation_rate=0.25    # extra mutation for queen offspring
)
```

```python
crossover_hyper_params = dict(
    prob_child_disabled_given_parent_cond=0.75,  # disable gene if parent has it disabled
    prob_remove_disabled_node=0.01,               # remove disabled genes entirely
    prob_inherit_all_excess_genes=1.0             # inherit disjoint genes from fitter parent
)
```

--------------------------------

### NEAT.genetic_algorithm_step - Evolve Population

Source: https://context7.com/lucidrains/neat/llms.txt

Performs one generation of evolution including selection, crossover, and mutation.

```APIDOC
## NEAT.genetic_algorithm_step

### Description
Executes one generation of the genetic algorithm based on provided fitness scores.

### Parameters
#### Request Body
- **fitnesses** (np.ndarray) - Required - Fitness scores for the population.
- **migrate_num** (int) - Optional - Number of individuals to migrate between islands.
- **reset_islands_num** (int) - Optional - Number of islands to reset.
- **reset_islands_tournament_size** (int) - Optional - Tournament size for island reset.
- **mutation_hyper_params** (dict) - Optional - Override mutation hyperparameters.
- **selection_hyper_params** (dict) - Optional - Override selection hyperparameters.
```

--------------------------------

### Evolve NEAT Population

Source: https://context7.com/lucidrains/neat/llms.txt

Perform one generation of evolution including selection, crossover, and mutation. Optionally includes island migration and island resetting.

```python
import numpy as np
from neat.neat import NEAT

population = NEAT(8, 4, pop_size=100, num_islands=5)

# Simulate fitness evaluation (higher = better)
fitnesses = np.random.randn(100).astype(np.float32)

# Perform one evolutionary step
population.genetic_algorithm_step(
    fitnesses,
    migrate_num=5,                    # migrate 5 individuals between islands
    reset_islands_num=1,              # reset worst island with crossovers from best
    reset_islands_tournament_size=3,  # tournament size for island reset
    # Optionally override hyperparams per-step:
    mutation_hyper_params=dict(
        mutate_prob=0.95,
        change_edge_weight_prob=0.6
    ),
    selection_hyper_params=dict(
        frac_natural_selected=0.2,
        tournament_size=4
    )
)
```

--------------------------------

### Selection and Crossover Hyperparameters

Source: https://context7.com/lucidrains/neat/llms.txt

Configuration settings for parent selection strategies and genetic inheritance rules.

```APIDOC
## Selection and Crossover Hyperparameters

### Description
Defines how parents are selected for reproduction and how genetic material is inherited by offspring.

### Parameters
- **frac_natural_selected** (float) - Fraction of population surviving selection.
- **tournament_size** (int) - Number of parents per tournament.
- **use_queen_bee** (bool) - Whether to use the queen bee GA variant.
- **queen_strong_mutation_rate** (float) - Extra mutation rate for queen offspring.
- **prob_child_disabled_given_parent_cond** (float) - Probability to disable a gene if the parent has it disabled.
- **prob_remove_disabled_node** (float) - Probability to remove disabled genes entirely.
- **prob_inherit_all_excess_genes** (float) - Probability to inherit disjoint genes from the fitter parent.
```

--------------------------------

### Save NEAT Population to JSON

Source: https://context7.com/lucidrains/neat/llms.txt

Saves the entire NEAT population, including network structures, to JSON files. This allows for later inspection or resuming training.

```python
from neat.neat import NEAT

population = NEAT(8, 4, pop_size=100)

# After evolution...
population.save_json('./checkpoints/population.gen.100')
# Creates: ./checkpoints/population.gen.100.id.0.json
```

--------------------------------

### NEAT.forward - Batch Evaluate Population

Source: https://context7.com/lucidrains/neat/llms.txt

Evaluates the entire population on a batch of inputs in parallel.

```APIDOC
## NEAT.forward

### Description
Processes a batch of states through the entire population of neural networks.

### Parameters
#### Request Body
- **states** (np.ndarray) - Required - Batch of input states (shape: pop_size, input_dim).
- **sample** (bool) - Optional - Whether to sample actions or return raw logits.
- **temperature** (float) - Optional - Temperature for Gumbel-softmax sampling.
```

--------------------------------

### Batch Evaluate NEAT Population

Source: https://context7.com/lucidrains/neat/llms.txt

Evaluate the entire population on a batch of inputs in parallel. Can return raw action logits or sampled actions.

```python
import numpy as np
from neat.neat import NEAT

population = NEAT(8, 4, pop_size=100)

# Create batch of states (one per individual in population)
states = np.random.randn(100, 8).astype(np.float32)

# Get raw action logits for entire population
action_logits = population.forward(states, sample=False)
# action_logits.shape == (100, 4)

# Or sample discrete actions using Gumbel-softmax
actions = population.forward(states, sample=True, temperature=1.0)
# actions is a list of 100 integers in [0, 3]
```

--------------------------------

### NEAT.single_forward - Evaluate Single Network

Source: https://context7.com/lucidrains/neat/llms.txt

Evaluates a specific individual network from the population.

```APIDOC
## NEAT.single_forward

### Description
Evaluates a single neural network identified by its index in the population.

### Parameters
#### Request Body
- **index** (int) - Required - Index of the individual in the population.
- **state** (np.ndarray) - Required - Input state for the network.
- **sample** (bool) - Optional - Whether to sample actions.
- **temperature** (float) - Optional - Temperature for sampling.
```

--------------------------------

### Mutation Hyperparameters for NEAT

Source: https://context7.com/lucidrains/neat/llms.txt

Defines global mutation probability, fast GA mode, structural mutations, weight and bias mutations, activation mutations, and elitism settings. Use these to control the evolutionary process of neural network architectures and weights.

```python
mutation_hyper_params = dict(
    # Global mutation probability
    mutate_prob=0.95,              # probability any mutation occurs

    # Fast GA mode (power-law sampling)
    use_fast_ga=False,             # use fast genetic algorithm
    fast_ga_beta=1.5,              # power law exponent

    # Structural mutations (add complexity)
    add_novel_edge_prob=0.05,      # add new connection
    toggle_meta_edge_prob=0.05,    # enable/disable edge
    add_remove_node_prob=1e-5,     # enable/disable node
    grow_edge_prob=1e-3,           # split edge with new node
    grow_node_prob=5e-4,           # duplicate node's connections

    # Weight mutations
    change_edge_weight_prob=0.5,   # perturb weight
    replace_edge_weight_prob=0.2,  # replace weight entirely
    perturb_weight_strength=0.2,   # perturbation magnitude
    max_weight_magnitude=5.0,      # clamp weights

    # Bias mutations
    change_node_bias_prob=0.1,     # perturb bias
    replace_node_bias_prob=0.2,    # replace bias entirely
    perturb_bias_strength=0.2,     # perturbation magnitude

    # Activation mutations
    change_activation_prob=0.001,  # change activation function

    # Elitism
    num_preserve_elites=2          # top N individuals skip mutation
)
```

--------------------------------

### Evaluate Single NEAT Network

Source: https://context7.com/lucidrains/neat/llms.txt

Evaluate a single neural network from the population using its index. Useful for testing specific individuals.

```python
import numpy as np
from neat.neat import NEAT

population = NEAT(8, 4, pop_size=100)

# Evaluate the best individual (index 0 after selection)
state = np.random.randn(8).astype(np.float32)

# Get action logits
logits = population.single_forward(
    index=0,           # individual index in population
    state=state,
    sample=False
)

# Sample an action
action = population.single_forward(
    index=0,
    state=state,
    sample=True,
    temperature=0.5    # lower = more deterministic
)
```

--------------------------------

### Low-Level Topology Management

Source: https://context7.com/lucidrains/neat/llms.txt

Manages network structure and global innovation tracking for nodes and edges. Use this for fine-grained control over network composition.

```python
from neat.neat import Topology

# Create topology with hidden layers
topology = Topology(
    num_inputs=10,
    num_outputs=4,
    pop_size=50,
    num_hiddens=(16, 16),   # two hidden layers of 16 neurons each
    mutation_hyper_params=dict(
        mutate_prob=0.9,
        add_novel_edge_prob=0.1
    ),
    num_islands=3
)

# Manually add structural innovations
new_node_id = topology.add_neuron()
topology.add_synapse(from_id=0, to_id=new_node_id)
```

--------------------------------

### Mutation Hyperparameters

Source: https://context7.com/lucidrains/neat/llms.txt

Configuration settings for controlling the mutation rates and structural evolution of neural networks.

```APIDOC
## Mutation Hyperparameters

### Description
Defines the probabilities and strengths for various mutation types, including structural changes, weight perturbations, and bias adjustments.

### Parameters
- **mutate_prob** (float) - Global probability that any mutation occurs.
- **use_fast_ga** (bool) - Whether to use the fast genetic algorithm mode.
- **fast_ga_beta** (float) - Power law exponent for fast GA.
- **add_novel_edge_prob** (float) - Probability to add a new connection.
- **toggle_meta_edge_prob** (float) - Probability to enable/disable an edge.
- **add_remove_node_prob** (float) - Probability to enable/disable a node.
- **grow_edge_prob** (float) - Probability to split an edge with a new node.
- **grow_node_prob** (float) - Probability to duplicate a node's connections.
- **change_edge_weight_prob** (float) - Probability to perturb an edge weight.
- **replace_edge_weight_prob** (float) - Probability to replace an edge weight entirely.
- **perturb_weight_strength** (float) - Magnitude of weight perturbation.
- **max_weight_magnitude** (float) - Maximum clamp value for weights.
- **change_node_bias_prob** (float) - Probability to perturb a node bias.
- **replace_node_bias_prob** (float) - Probability to replace a node bias entirely.
- **perturb_bias_strength** (float) - Magnitude of bias perturbation.
- **change_activation_prob** (float) - Probability to change a node's activation function.
- **num_preserve_elites** (int) - Number of top individuals to preserve without mutation.
```

--------------------------------

### POST /save_json

Source: https://context7.com/lucidrains/neat/llms.txt

Saves the current population state to a JSON file.

```APIDOC
## POST /save_json

### Description
Saves the entire population (nodes, edges, neural network structures) to JSON files for later inspection or resumption.

### Method
POST

### Parameters
#### Request Body
- **path** (string) - Required - The file path prefix where the population data will be saved.
```

=== COMPLETE CONTENT === This response contains all available snippets from this library. No additional content exists. Do not make further requests.