multispecies_environment behaviour (faber_neuroevolution v1.2.4)

Multi-Species Environment Behaviour.

Extends agent_environment to support multiple species coevolving in a shared environment.

Overview

A multi-species environment manages:

Multiple agent types with different capabilities
Species-specific spawning rules
Inter-species interactions (predation, cooperation)
Per-species metrics extraction

Agent State Extension

Each agent state must include:

  #{
      id := term(),
      species := atom(),          %% Species identifier
      species_data := map(),      %% Species-specific state
      ...                         %% Standard agent fields
  }

Interaction Types

  ┌─────────────────────────────────────────────────────┐
  │              Interaction Matrix                      │
  ├─────────────────────────────────────────────────────┤
  │              │ Forager │ Predator │ Scavenger       │
  ├──────────────┼─────────┼──────────┼─────────────────┤
  │ Forager      │ compete │ prey     │ ignore          │
  │ Predator     │ hunt    │ compete  │ ignore          │
  │ Scavenger    │ follow  │ avoid    │ compete         │
  └─────────────────────────────────────────────────────┘

See also: agent_environment, agent_species.

Summary

Types

interaction/0

species_spawn_config/0

Callbacks

apply_action/3

extract_metrics/2

extract_species_metrics/3

handle_interaction/3

init/1

interaction_type/2

is_terminal/2

name/0

spawn_agent/3

supported_species/0

tick/2

Functions

extract_all_metrics(Module, State)

Extracts metrics for all species.

process_interactions(Module, State)

Processes interactions between all agent pairs.

spawn_population(Module, SpeciesConfigs, EnvState)

Spawns a population of agents for each species.

validate(Module)

Validates a multi-species environment module.

Types

interaction/0

-type interaction() :: hunt | prey | compete | cooperate | ignore | avoid | follow.

species_spawn_config/0

-type species_spawn_config() ::
          #{energy := float(),
            spawn_zone := center | edge | random | {hex, {integer(), integer()}},
            max_count => pos_integer(),
            spawn_delay => non_neg_integer()}.

Callbacks

apply_action/3

-callback apply_action(Action :: map(), AgentState :: map(), EnvState :: map()) ->
                          {ok, AgentState :: map(), EnvState :: map()}.

extract_metrics/2

-callback extract_metrics(AgentState :: map(), EnvState :: map()) -> map().

extract_species_metrics/3

(optional)

-callback extract_species_metrics(SpeciesId :: atom(), AgentStates :: [map()], EnvState :: map()) -> map().

handle_interaction/3

(optional)

-callback handle_interaction(Agent1 :: map(), Agent2 :: map(), EnvState :: map()) ->
                                {ok, Agent1New :: map(), Agent2New :: map(), EnvState :: map()}.

init/1

-callback init(Config :: map()) -> {ok, EnvState :: map()} | {error, term()}.

interaction_type/2

(optional)

-callback interaction_type(Species1 :: atom(), Species2 :: atom()) ->
                              hunt | prey | compete | cooperate | ignore | avoid | follow.

is_terminal/2

-callback is_terminal(AgentState :: map(), EnvState :: map()) -> boolean().

name/0

-callback name() -> binary().

spawn_agent/3

-callback spawn_agent(AgentId :: term(), SpeciesId :: atom(), EnvState :: map()) ->
                         {ok, AgentState :: map(), EnvState :: map()} | {error, term()}.

supported_species/0

-callback supported_species() -> [atom()].

tick/2

-callback tick(AgentState :: map(), EnvState :: map()) -> {ok, AgentState :: map(), EnvState :: map()}.

Functions

extract_all_metrics(Module, State)

-spec extract_all_metrics(Module, State) -> #{atom() => map()}
                             when Module :: module(), State :: {[map()], map()}.

Extracts metrics for all species.

process_interactions(Module, State)

-spec process_interactions(Module, State) -> {ok, NewAgents, NewEnv}
                              when
                                  Module :: module(),
                                  State :: {[map()], map()},
                                  NewAgents :: [map()],
                                  NewEnv :: map().

Processes interactions between all agent pairs.

spawn_population(Module, SpeciesConfigs, EnvState)

-spec spawn_population(Module, SpeciesConfigs, EnvState) -> {ok, AgentStates, EnvState}
                          when
                              Module :: module(),
                              SpeciesConfigs :: #{atom() => {pos_integer(), species_spawn_config()}},
                              EnvState :: map(),
                              AgentStates :: [map()].

Spawns a population of agents for each species.

validate(Module)

-spec validate(Module) -> ok | {error, Reasons} when Module :: module(), Reasons :: [term()].

Validates a multi-species environment module.

Note: This does NOT call agent_environment:validate/1 because multi-species environments use spawn_agent/3 instead of spawn_agent/2.