macula_neuroevolution

%% @doc Genetic operators for neuroevolution.
%%
%% This module provides crossover and mutation operators for evolving
%% neural networks. Supports two modes:
%%
%% == NEAT Topology Evolution ==
%%
%% When individuals have genomes (connection_genes with innovation numbers),
%% uses NEAT-style crossover and structural mutations via genome_factory.
%% This enables topology-evolving networks.
%%
%% == Fixed Topology (Legacy) ==
%%
%% For backward compatibility, when individuals don't have genomes,
%% uses weight-only evolution with uniform crossover and perturbation mutation.
%%
%% Reference: Stanley, K.O. and Miikkulainen, R. (2002). "Evolving Neural
%% Networks through Augmenting Topologies." Evolutionary Computation, 10(2).
%%
%% @author Macula.io
%% @copyright 2025 Macula.io
-module(neuroevolution_genetic).

-include("neuroevolution.hrl").

%% API
-export([
    crossover_uniform/2,
    mutate_weights/3,
    create_offspring/4,
    create_offspring_neat/4
]).

%%% ============================================================================
%%% API Functions
%%% ============================================================================

%% @doc Uniform crossover of two weight lists.
%%
%% For each weight position, randomly selects from either parent with
%% equal probability (50/50).
%%
%% Both weight lists must be the same length.
%%
%% Example:
%% Parent1 = [1.0, 2.0, 3.0, 4.0],
%% Parent2 = [5.0, 6.0, 7.0, 8.0],
%% %% Might produce: [1.0, 6.0, 3.0, 8.0]
%% Child = neuroevolution_genetic:crossover_uniform(Parent1, Parent2).
-spec crossover_uniform(Weights1, Weights2) -> ChildWeights when
    Weights1 :: [float()],
    Weights2 :: [float()],
    ChildWeights :: [float()].
crossover_uniform(Weights1, Weights2) ->
    lists:zipwith(
        fun(W1, W2) ->
            case rand:uniform() < 0.5 of
                true -> W1;
                false -> W2
            end
        end,
        Weights1,
        Weights2
    ).

%% @doc Mutate weights with given rate and strength.
%%
%% Each weight has MutationRate probability of being perturbed.
%% When mutated, a random value in [-Strength, +Strength] is added.
%%
%% Example:
%% Weights = [1.0, 2.0, 3.0],
%% Rate = 0.1,      %% 10% of weights mutated
%% Strength = 0.3,  %% Changes up to +/- 0.3
%% Mutated = neuroevolution_genetic:mutate_weights(Weights, Rate, Strength).
-spec mutate_weights(Weights, MutationRate, MutationStrength) -> MutatedWeights when
    Weights :: [float()],
    MutationRate :: float(),
    MutationStrength :: float(),
    MutatedWeights :: [float()].
mutate_weights(Weights, MutationRate, MutationStrength) ->
    lists:map(
        fun(W) ->
            case rand:uniform() < MutationRate of
                true ->
                    %% Perturb: add random value in [-Strength, +Strength]
                    Delta = (rand:uniform() - 0.5) * 2 * MutationStrength,
                    W + Delta;
                false ->
                    W
            end
        end,
        Weights
    ).

%% @doc Create offspring from two parent individuals.
%%
%% Automatically selects the appropriate mode:
%% - NEAT mode: When both parents have genomes and topology_mutation_config is set
%% - Legacy mode: Weight-only evolution with uniform crossover
%%
%% For NEAT mode:
%% 1. Determine fitter parent
%% 2. Perform NEAT crossover (gene alignment by innovation number)
%% 3. Apply structural and weight mutations
%% 4. Convert genome to network for evaluation
%%
%% For Legacy mode:
%% 1. Extract weights from both parent networks
%% 2. Perform uniform crossover
%% 3. Apply mutation
%% 4. Create new network with child weights
%%
%% Returns a new individual record with lineage tracking.
-spec create_offspring(Parent1, Parent2, Config, Generation) -> Offspring when
    Parent1 :: individual(),
    Parent2 :: individual(),
    Config :: neuro_config(),
    Generation :: generation(),
    Offspring :: individual().
create_offspring(Parent1, Parent2, Config, Generation) ->
    %% Check if NEAT mode should be used
    case should_use_neat(Parent1, Parent2, Config) of
        true ->
            create_offspring_neat(Parent1, Parent2, Config, Generation);
        false ->
            create_offspring_legacy(Parent1, Parent2, Config, Generation)
    end.

%% @doc Create offspring using NEAT topology evolution.
%%
%% Uses genome_factory to perform NEAT-style crossover and mutation.
%% Both parents must have genomes for this to work.
%%
%% @param Parent1 First parent individual (must have genome)
%% @param Parent2 Second parent individual (must have genome)
%% @param Config Configuration with topology_mutation_config
%% @param Generation Current generation number
%% @returns Offspring individual with genome
-spec create_offspring_neat(Parent1, Parent2, Config, Generation) -> Offspring when
    Parent1 :: individual(),
    Parent2 :: individual(),
    Config :: neuro_config(),
    Generation :: generation(),
    Offspring :: individual().
create_offspring_neat(Parent1, Parent2, Config, Generation) ->
    %% Determine fitter parent for NEAT crossover
    FitterParent = determine_fitter_parent(Parent1, Parent2),

    %% NEAT crossover via genome_factory (aligns genes by innovation number)
    ChildGenome = genome_factory:crossover(
        Parent1#individual.genome,
        Parent2#individual.genome,
        FitterParent
    ),

    %% Apply mutations (structural + weight)
    MutConfig = get_mutation_config(Config),
    MutatedGenome = genome_factory:mutate(ChildGenome, MutConfig),

    %% Convert genome to network for evaluation
    ChildNetwork = genome_factory:to_network(MutatedGenome),

    %% Create offspring individual with lineage and genome
    ChildId = make_ref(),
    #individual{
        id = ChildId,
        network = ChildNetwork,
        genome = MutatedGenome,
        parent1_id = Parent1#individual.id,
        parent2_id = Parent2#individual.id,
        generation_born = Generation,
        is_offspring = true
    }.

%%% ============================================================================
%%% Internal Functions
%%% ============================================================================

%% @private Check if NEAT mode should be used for offspring creation.
should_use_neat(Parent1, Parent2, Config) ->
    HasGenomes = Parent1#individual.genome =/= undefined andalso
                 Parent2#individual.genome =/= undefined,
    HasMutConfig = Config#neuro_config.topology_mutation_config =/= undefined,
    HasGenomes andalso HasMutConfig.

%% @private Determine which parent is fitter for NEAT crossover.
%%
%% Returns: 1 if Parent1 is fitter, 2 if Parent2 is fitter, equal if same
determine_fitter_parent(Parent1, Parent2) ->
    F1 = Parent1#individual.fitness,
    F2 = Parent2#individual.fitness,
    if
        F1 > F2 -> 1;
        F2 > F1 -> 2;
        true -> equal
    end.

%% @private Get mutation config, with defaults if not specified.
get_mutation_config(Config) ->
    case Config#neuro_config.topology_mutation_config of
        undefined ->
            %% Default mutation config based on legacy rates
            #mutation_config{
                weight_mutation_rate = Config#neuro_config.mutation_rate,
                weight_perturb_rate = 0.9,
                weight_perturb_strength = Config#neuro_config.mutation_strength,
                add_node_rate = 0.03,
                add_connection_rate = 0.05,
                toggle_connection_rate = 0.01
            };
        MutConfig ->
            MutConfig
    end.

%% @private Create offspring using legacy weight-only evolution.
create_offspring_legacy(Parent1, Parent2, Config, Generation) ->
    %% Extract weights from parent networks
    Weights1 = network_evaluator:get_weights(Parent1#individual.network),
    Weights2 = network_evaluator:get_weights(Parent2#individual.network),

    %% Crossover
    ChildWeights = crossover_uniform(Weights1, Weights2),

    %% Mutation
    MutatedWeights = mutate_weights(
        ChildWeights,
        Config#neuro_config.mutation_rate,
        Config#neuro_config.mutation_strength
    ),

    %% Create new network with child weights
    {InputSize, HiddenLayers, OutputSize} = Config#neuro_config.network_topology,
    Network = network_evaluator:create_feedforward(InputSize, HiddenLayers, OutputSize),
    ChildNetwork = network_evaluator:set_weights(Network, MutatedWeights),

    %% Create offspring individual with lineage
    ChildId = make_ref(),
    #individual{
        id = ChildId,
        network = ChildNetwork,
        parent1_id = Parent1#individual.id,
        parent2_id = Parent2#individual.id,
        generation_born = Generation,
        is_offspring = true
    }.