population_monitor (macula_tweann v0.18.1)

View Source

Population-level evolutionary process manager.

This gen_server manages the evolutionary process for a population of neural network agents. It coordinates:

- Agent lifecycle (spawn, evaluate, terminate) - Fitness collection and aggregation - Selection and reproduction - Species formation and management - Termination condition checking

Population Hierarchy

Population contains multiple species. Species contains multiple agents with similar behavior. Agents compete within species for selection.

Evolutionary Generation Loop

Each generation follows these steps: 1. Spawn Phase: Launch all agent processes in parallel 2. Evaluation Phase: Agents run sense-think-act cycles 3. Collection Phase: Gather fitness results 4. Selection Phase: Select survivors based on fitness 5. Reproduction Phase: Replicate and mutate survivors 6. Speciation Phase: Update species assignments 7. Termination Check: Goal reached or max generations?

Multi-Objective Fitness

Fitness is a vector [F1, F2, ...] supporting multi-objective optimization with different aggregation strategies.

Summary

Types

population_state/0

Functions

agent_terminated(Pid, AgentId, Fitness)

Report that an agent has completed evaluation.

handle_call(Request, From, State)

Handle synchronous requests.

handle_cast(Msg, State)

Handle asynchronous messages.

handle_info(Info, State)

Handle info messages.

init(Config)

Initialize population monitor state.

select_survivors(AgentFitnesses, SurvivalRate)

Select survivors based on fitness.

should_terminate(State)

Check if evolution should terminate.

start_evaluation(Pid)

Begin evaluation phase for current generation.

start_link(Config)

Start population monitor process.

stop(Pid)

Stop the population monitor.

terminate(Reason, State)

Cleanup on termination.

Types

population_state/0

-type population_state() ::
          #population_state{operation_mode :: gt | validation | test,
                            population_id :: term(),
                            active_agent_processes :: [{term(), pid()}],
                            agent_ids :: [term()],
                            total_agents :: non_neg_integer(),
                            remaining_agents :: non_neg_integer(),
                            operation_tag :: term(),
                            generation_count :: non_neg_integer(),
                            fitness_goal :: [float()],
                            max_generations :: pos_integer(),
                            evaluation_limit :: pos_integer(),
                            selection_algorithm :: atom(),
                            fitness_postprocessor :: atom(),
                            evolutionary_strategy :: atom(),
                            current_best_fitness :: [float()] | undefined,
                            specie_size_limit :: pos_integer(),
                            species_map :: #{term() => [term()]},
                            timestamp_started :: erlang:timestamp(),
                            survival_rate :: float(),
                            fitness_acc :: [{term(), [float()]}]}.

Functions

agent_terminated(Pid, AgentId, Fitness)

-spec agent_terminated(pid(), term(), [float()]) -> ok.

Report that an agent has completed evaluation.

handle_call(Request, From, State)

-spec handle_call(term(), {pid(), term()}, population_state()) -> {reply, term(), population_state()}.

Handle synchronous requests.

handle_cast(Msg, State)

-spec handle_cast(term(), population_state()) ->
                     {noreply, population_state()} | {stop, normal, population_state()}.

Handle asynchronous messages.

handle_info(Info, State)

-spec handle_info(term(), population_state()) -> {noreply, population_state()}.

Handle info messages.

init(Config)

-spec init(map()) -> {ok, population_state()}.

Initialize population monitor state.

select_survivors(AgentFitnesses, SurvivalRate)

-spec select_survivors([{term(), [float()]}], float()) -> [term()].

Select survivors based on fitness.

Delegates to the selection_algorithm module for configurable selection. Uses the algorithm specified in the population state.

should_terminate(State)

-spec should_terminate(population_state()) -> boolean().

Check if evolution should terminate.

Termination occurs when: - Fitness goal is reached - Maximum generations reached

start_evaluation(Pid)

-spec start_evaluation(pid()) -> ok.

Begin evaluation phase for current generation.

start_link(Config)

-spec start_link(map()) -> {ok, pid()} | {error, term()}.

Start population monitor process.

stop(Pid)

-spec stop(pid()) -> ok.

Stop the population monitor.

terminate(Reason, State)

-spec terminate(term(), population_state()) -> ok.

Cleanup on termination.