Current section
Files
Jump to
Current section
Files
include/records.hrl
%% @doc Core data structure definitions for Macula TWEANN
%%
%% This file contains all record definitions for the TWEANN system.
%% Each record is fully documented with field-level comments explaining
%% purpose, format, and usage.
%%
%% == Record Organization ==
%% - Network components: sensor, neuron, actuator, cortex
%% - Evolution components: agent, specie, population
%% - Substrate: substrate (for HyperNEAT)
%% - Environment: polis, scape
%% - Configuration: constraint, pmp (population manager parameters)
%%
%% @copyright 2025 Macula.io
%% @license Apache-2.0
-ifndef(MACULA_TWEANN_RECORDS_HRL).
-define(MACULA_TWEANN_RECORDS_HRL, true).
-include("types.hrl").
%%==============================================================================
%% Configuration Defines
%%==============================================================================
%% @doc Enable behavioral tracing for debugging
-define(BEHAVIORAL_TRACE, false).
%% @doc Enable interactive selection mode
-define(INTERACTIVE_SELECTION, false).
%%==============================================================================
%% Network Component Records
%%==============================================================================
%% @doc Sensor record - Input interface to the neural network
%%
%% Sensors gather information from the environment (scape) and feed
%% signals to neurons in the network.
%%
%% Field Documentation:
%% id - Unique identifier: {{-1.0, UniqueFloat}, sensor}
%% The -1.0 layer coordinate indicates sensor layer
%% name - Atom naming the sensor type (e.g., rng, distance_scanner)
%% type - Sensor category (standard, etc.)
%% cx_id - Parent cortex identifier for ownership
%% scape - Environment spec: {private|public, ScapeName}
%% vl - Vector length: number of signals produced per sense
%% fanout_ids - List of neuron IDs that receive signals from this sensor
%% generation - Generation when this sensor was added to the network
%% format - Signal format: {no_geo|geo, [Resolution...]}
%% parameters - Sensor-specific configuration parameters
%% gt_parameters - Genotype parameters (for substrate sensors)
%% phys_rep - Physical representation in the environment
%% vis_rep - Visual representation for rendering
%% pre_f - Pre-processing function name (atom)
%% post_f - Post-processing function name (atom)
-record(sensor, {
id,
name,
type,
cx_id,
scape,
vl,
fanout_ids = [],
generation,
format,
parameters,
gt_parameters,
phys_rep,
vis_rep,
pre_f,
post_f
}).
%% @doc Actuator record - Output interface from the neural network
%%
%% Actuators receive signals from the network and perform actions
%% in the environment (scape).
%%
%% Field Documentation:
%% id - Unique identifier: {{1.0, UniqueFloat}, actuator}
%% The 1.0 layer coordinate indicates actuator layer
%% name - Atom naming the actuator type (e.g., pts, differential_drive)
%% type - Actuator category (standard, etc.)
%% cx_id - Parent cortex identifier for ownership
%% scape - Environment spec: {private|public, ScapeName}
%% vl - Vector length: number of input signals expected
%% fanin_ids - List of neuron IDs that send signals to this actuator
%% generation - Generation when this actuator was added
%% format - Signal format: {no_geo|geo, [Resolution...]}
%% parameters - Actuator-specific configuration parameters
%% gt_parameters - Genotype parameters (for substrate actuators)
%% phys_rep - Physical representation in the environment
%% vis_rep - Visual representation for rendering
%% pre_f - Pre-processing function name (atom)
%% post_f - Post-processing function name (atom)
-record(actuator, {
id,
name,
type,
cx_id,
scape,
vl,
fanin_ids = [],
generation,
format,
parameters,
gt_parameters,
phys_rep,
vis_rep,
pre_f,
post_f
}).
%% @doc Neuron record - Core computational unit of the network
%%
%% Neurons receive weighted inputs, aggregate them, apply an activation
%% function, and forward the output. They can also apply plasticity
%% rules to modify their weights during operation.
%%
%% Field Documentation:
%% id - Unique identifier: {{LayerCoord, UniqueFloat}, neuron}
%% LayerCoord is between 0.0 and 1.0 for hidden layers
%% generation - Generation when this neuron was created
%% cx_id - Parent cortex identifier for ownership
%% pre_processor - Pre-processing function for inputs (atom or undefined)
%% signal_integrator - How to combine multiple signals (atom or undefined)
%% af - Activation function: tanh|cos|sin|gaussian|etc.
%% (Old name, should be activation_function)
%% post_processor - Post-processing function for output (atom or undefined)
%% pf - Plasticity function: {FunctionName, Parameters}
%% (Old name, should be plasticity_function)
%% aggr_f - Aggregation function: dot_product|mult_product|diff
%% (Old name, should be aggregation_function)
%% input_idps - Weighted inputs list:
%% [{SourceId, [{Weight, DeltaWeight, LearningRate, ParamList}...]}...]
%% This is the main weight storage using weight_spec() format
%% (Old name, should be weighted_inputs)
%% input_idps_modulation - Modulatory inputs for neuromodulation
%% (Old name, should be weighted_inputs_modulation)
%% output_ids - List of neuron/actuator IDs to send output to
%% ro_ids - Recurrent output IDs (feedback connections)
%% (Old name, should be recurrent_output_ids)
-record(neuron, {
id,
generation,
cx_id,
pre_processor,
signal_integrator,
af, %% activation_function
post_processor,
pf, %% plasticity_function
aggr_f, %% aggregation_function
input_idps = [], %% weighted_inputs
input_idps_modulation = [], %% weighted_inputs_modulation
output_ids = [],
ro_ids = [] %% recurrent_output_ids
}).
%% @doc Cortex record - Network coordinator
%%
%% The cortex coordinates the sense-think-act cycle of the neural network.
%% It triggers sensors, waits for neurons to process, and collects actuator outputs.
%%
%% Field Documentation:
%% id - Unique identifier: {{0.0, UniqueFloat}, cortex}
%% agent_id - Owning agent identifier
%% neuron_ids - List of all neuron IDs in this network
%% sensor_ids - List of all sensor IDs in this network
%% actuator_ids - List of all actuator IDs in this network
-record(cortex, {
id,
agent_id,
neuron_ids = [],
sensor_ids = [],
actuator_ids = []
}).
%%==============================================================================
%% Substrate Records (HyperNEAT)
%%==============================================================================
%% @doc Substrate record - Geometric neural network substrate
%%
%% Used in HyperNEAT for evolving larger-scale networks through
%% compositional pattern producing networks (CPPNs).
%%
%% Field Documentation:
%% id - Unique substrate identifier
%% agent_id - Owning agent identifier
%% densities - Substrate resolution/density parameters
%% linkform - Link pattern: l2l_feedforward|jordan_recurrent|fully_connected
%% plasticity - Substrate plasticity type: none|hebbian|ojas
%% cpp_ids - Compositional Pattern Producing neuron IDs
%% cep_ids - Coordinate Encoder Pattern neuron IDs
-record(substrate, {
id,
agent_id,
densities,
linkform,
plasticity = none,
cpp_ids = [],
cep_ids = []
}).
%%==============================================================================
%% Evolution Records
%%==============================================================================
%% @doc Agent record - Individual in the evolutionary population
%%
%% An agent represents one candidate solution with its neural network,
%% evolutionary history, fitness scores, and evolutionary parameters.
%%
%% Field Documentation:
%% id - Unique identifier: {UniqueFloat, agent}
%% encoding_type - Network type: neural|substrate
%% generation - Current generation number
%% population_id - Parent population identifier
%% specie_id - Assigned specie identifier
%% cx_id - Cortex (neural network) identifier
%% fingerprint - Structural signature for speciation
%% constraint - Evolution constraint record
%% evo_hist - List of applied mutation operators
%% [{MutationName, ElementIds...}...]
%% fitness - Current fitness score
%% innovation_factor - Measure of topological novelty
%% pattern - Network topology: [{LayerCoord, NeuronIds}...]
%% tuning_selection_f - Weight selection for tuning: all|recent|dynamic_random
%% annealing_parameter - Simulated annealing temperature
%% tuning_duration_f - Duration function: {FuncName, Param}
%% perturbation_range - Weight perturbation magnitude
%% mutation_operators - Available mutations: [{Name, Probability}...]
%% tot_topological_mutations_f - Mutation count function: {FuncName, Param}
%% heredity_type - Evolution type: darwinian|lamarckian
%% substrate_id - Substrate identifier (for HyperNEAT)
%% offspring_ids - List of child agent IDs
%% parent_ids - List of parent agent IDs
%% champion_flag - Whether this is a specie champion
%% evolvability - Measure of evolutionary potential
%% brittleness - Sensitivity to weight perturbation
%% robustness - Stability across perturbations
%% evolutionary_capacitance - Ability to accumulate beneficial mutations
%% behavioral_trace - Recorded behavior for analysis
%% fs - Fitness scaling factor
%% main_fitness - Primary optimization target
-record(agent, {
id,
encoding_type,
generation,
population_id,
specie_id,
cx_id,
fingerprint,
constraint,
evo_hist = [],
fitness = 0,
innovation_factor = 0,
pattern = [],
tuning_selection_f,
annealing_parameter,
tuning_duration_f,
perturbation_range,
mutation_operators,
tot_topological_mutations_f,
heredity_type,
substrate_id,
offspring_ids = [],
parent_ids = [],
champion_flag = [false],
evolvability = 0,
brittleness = 0,
robustness = 0,
evolutionary_capacitance = 0,
behavioral_trace,
fs = 1,
main_fitness
}).
%% @doc Champion record - Hall of fame entry
%%
%% Records information about top-performing agents for the hall of fame.
%%
%% Field Documentation:
%% hof_fingerprint - Hall of fame categorization fingerprint
%% id - Champion agent ID
%% fitness - Training fitness score
%% validation_fitness - Validation set fitness
%% test_fitness - Test set fitness
%% main_fitness - Primary fitness measure
%% tot_n - Total number of neurons
%% evolvability - Evolutionary potential measure
%% robustness - Stability measure
%% brittleness - Sensitivity measure
%% generation - Generation when achieved
%% behavioral_differences - Behavioral novelty scores
%% fs - Fitness scaling factor
-record(champion, {
hof_fingerprint,
id,
fitness,
validation_fitness,
test_fitness,
main_fitness,
tot_n,
evolvability,
robustness,
brittleness,
generation,
behavioral_differences,
fs
}).
%% @doc Specie record - Species for NEAT speciation
%%
%% Groups similar agents together for protected innovation.
%%
%% Field Documentation:
%% id - Specie identifier
%% population_id - Parent population identifier
%% fingerprint - Representative structural fingerprint
%% constraint - Evolution constraint record
%% all_agent_ids - All agents ever in this specie
%% agent_ids - Currently active agents
%% dead_pool - Recently removed agents
%% champion_ids - Top performers in this specie
%% fitness - Specie-level fitness (usually average)
%% innovation_factor - Topological innovation measure: {Novelty, Count}
%% stats - Historical statistics
%% seed_agent_ids - Initial seed agents
%% hof_distinguishers - Hall of fame categorization criteria
%% specie_distinguishers - Speciation criteria
%% hall_of_fame - List of champion records
-record(specie, {
id,
population_id,
fingerprint,
constraint,
all_agent_ids = [],
agent_ids = [],
dead_pool = [],
champion_ids = [],
fitness,
innovation_factor = {0, 0},
stats = [],
seed_agent_ids = [],
hof_distinguishers = [tot_n],
specie_distinguishers = [tot_n],
hall_of_fame = []
}).
%% @doc Trace record - Evolution statistics trace
%%
%% Tracks statistics across generations for analysis.
%%
%% Field Documentation:
%% stats - List of stat records
%% tot_evaluations - Total fitness evaluations performed
%% step_size - Evaluation interval for recording stats
-record(trace, {
stats = [],
tot_evaluations = 0,
step_size = 500
}).
%% @doc Population record - Top-level evolutionary container
%%
%% Contains all species and manages the overall evolutionary process.
%%
%% Field Documentation:
%% id - Population identifier
%% polis_id - Parent polis (world) identifier
%% specie_ids - List of specie identifiers
%% morphologies - Available network morphologies
%% innovation_factor - Population-level innovation measure
%% evo_alg_f - Evolution algorithm: generational|steady_state
%% fitness_postprocessor_f - Fitness adjustment: none|size_proportional
%% selection_f - Parent selection: competition|top3|hof_competition
%% trace - Statistics trace record
%% seed_agent_ids - Initial population seeds
%% seed_specie_ids - Initial species seeds
-record(population, {
id,
polis_id,
specie_ids = [],
morphologies = [],
innovation_factor,
evo_alg_f,
fitness_postprocessor_f,
selection_f,
trace = #trace{},
seed_agent_ids = [],
seed_specie_ids = []
}).
%% @doc Stat record - Generation statistics
%%
%% Records statistics for a single generation or evaluation point.
%%
%% Field Documentation:
%% morphology - Network morphology type
%% specie_id - Specie being measured
%% avg_neurons - Average neuron count
%% std_neurons - Standard deviation of neuron count
%% avg_fitness - Average fitness score
%% std_fitness - Standard deviation of fitness
%% max_fitness - Maximum fitness achieved
%% min_fitness - Minimum fitness in population
%% validation_fitness - Fitness on validation set
%% test_fitness - Fitness on test set
%% avg_diversity - Average behavioral diversity
%% evaluations - Number of evaluations performed
%% time_stamp - When this stat was recorded
-record(stat, {
morphology,
specie_id,
avg_neurons,
std_neurons,
avg_fitness,
std_fitness,
max_fitness,
min_fitness,
validation_fitness,
test_fitness,
avg_diversity,
evaluations,
time_stamp
}).
%%==============================================================================
%% Configuration Records
%%==============================================================================
%% @doc Constraint record - Evolution constraints
%%
%% Defines what evolutionary operations are allowed and what
%% network components can be used.
%%
%% (See original file for full default values)
-record(constraint, {
morphology = xor_mimic,
connection_architecture = recurrent,
neural_afs = [tanh, cos, gaussian],
neural_pfns = [none],
substrate_plasticities = [none],
substrate_linkforms = [l2l_feedforward],
neural_aggr_fs = [dot_product],
tuning_selection_fs = [dynamic_random],
tuning_duration_f = {wsize_proportional, 0.5},
annealing_parameters = [0.5],
perturbation_ranges = [1],
agent_encoding_types = [neural],
heredity_types = [darwinian],
mutation_operators = [
{add_bias, 10},
{add_outlink, 40},
{add_inlink, 40},
{add_neuron, 40},
{outsplice, 40},
{add_sensorlink, 1},
{add_sensor, 1},
{add_actuator, 1},
{add_cpp, 1},
{add_cep, 1}
],
tot_topological_mutations_fs = [{ncount_exponential, 0.5}],
population_evo_alg_f = generational,
population_fitness_postprocessor_f = size_proportional,
population_selection_f = hof_competition,
specie_distinguishers = [tot_n],
hof_distinguishers = [tot_n],
objectives = [main_fitness, inverse_tot_n]
}).
%% @doc Experiment record - Experiment configuration
%%
%% Tracks an evolutionary experiment across multiple runs.
%%
%% Field Documentation:
%% id - Experiment identifier
%% backup_flag - Whether to backup population state
%% pm_parameters - Population manager parameters (pmp record)
%% init_constraints - Initial constraint record
%% progress_flag - Status: in_progress|completed|interrupted
%% trace_acc - Accumulated traces from all runs
%% run_index - Current run number
%% tot_runs - Total runs to perform
%% notes - Experiment notes/description
%% started - Start timestamp: {date(), time()}
%% completed - Completion timestamp
%% interruptions - List of interruption events
-record(experiment, {
id,
backup_flag = true,
pm_parameters,
init_constraints,
progress_flag = in_progress,
trace_acc = [],
run_index = 1,
tot_runs = 10,
notes,
started = {date(), time()},
completed,
interruptions = []
}).
%% @doc PMP record - Population Manager Parameters
%%
%% Configuration for the population manager process.
%%
%% Field Documentation:
%% op_mode - Operation mode: gt (ground truth) |test
%% population_id - Population to manage
%% survival_percentage - Fraction of population that survives selection
%% specie_size_limit - Maximum agents per specie
%% init_specie_size - Initial specie population
%% polis_id - Parent polis identifier
%% generation_limit - Maximum generations to evolve
%% evaluations_limit - Maximum fitness evaluations
%% fitness_goal - Target fitness (inf for no limit)
%% benchmarker_pid - Process for benchmark reporting
%% committee_pid - Process for ensemble decisions
-record(pmp, {
op_mode = gt,
population_id = test,
survival_percentage = 0.5,
specie_size_limit = 10,
init_specie_size = 20,
polis_id = mathema,
generation_limit = 100,
evaluations_limit = 100000,
fitness_goal = inf,
benchmarker_pid,
committee_pid
}).
%%==============================================================================
%% Environment/Scape Records
%%==============================================================================
%% @doc Polis record - World container
%%
%% A polis is a world that contains populations and scapes.
%%
%% Field Documentation:
%% id - Polis identifier
%% scape_ids - List of environment identifiers
%% population_ids - List of population identifiers
%% specie_ids - List of specie identifiers
%% dx_ids - List of agent identifiers
%% parameters - Polis configuration parameters
-record(polis, {
id,
scape_ids = [],
population_ids = [],
specie_ids = [],
dx_ids = [],
parameters = []
}).
%% @doc Scape record - Environment/simulation
%%
%% A scape is the environment where agents are evaluated.
%%
%% Field Documentation:
%% id - Scape identifier
%% type - Scape type/category
%% physics - Physics simulation parameters
%% metabolics - Energy/metabolism rules
%% sector2avatars - Mapping of sectors to avatars
%% avatars - List of avatar entities
%% plants - List of plant entities
%% walls - List of wall obstacles
%% pillars - List of pillar obstacles
%% laws - Environmental rules
%% anomolies - Special environmental effects
%% artifacts - Interactive objects
%% objects - Generic objects
%% elements - Environmental elements
%% atoms - Basic particles
%% scheduler - Scheduling counter
-record(scape, {
id,
type,
physics,
metabolics,
sector2avatars,
avatars = [],
plants = [],
walls = [],
pillars = [],
laws = [],
anomolies = [],
artifacts = [],
objects = [],
elements = [],
atoms = [],
scheduler = 0
}).
%% @doc Avatar record - Agent's physical presence in scape
-record(avatar, {
id,
sector,
morphology,
type,
specie,
energy = 0,
health = 0,
food = 0,
age = 0,
kills = 0,
loc,
direction,
r,
mass,
objects,
vis = [],
state,
stats,
actuators,
sensors,
sound,
gestalt,
spear
}).
%%==============================================================================
%% Topology Summary Records
%%==============================================================================
%% @doc Topology summary for fingerprinting
-record(topology_summary, {
type,
tot_neurons,
tot_n_ils, %% total input links
tot_n_ols, %% total output links
tot_n_ros, %% total recurrent outputs
af_distribution %% activation function distribution
}).
%% @doc Signature record for speciation
-record(signature, {
generalized_Pattern,
generalized_EvoHist,
generalized_Sensors,
generalized_Actuators,
topology_summary
}).
%%==============================================================================
%% Circuit Records (Deep Learning Components)
%%==============================================================================
%% Note: Circuit, layer, and neurode records are used for
%% deep learning components. See original DXNN2 documentation.
-record(circuit, {
id,
i, %% input_idps
ovl, %% output vector length
ivl, %% input vector length
training,
output,
parameters,
dynamics,
layers,
type = standard,
noise,
noise_type = zero_mask,
lp_decay = 0.999999,
lp_min = 0.0000001,
lp_max = 0.1,
memory = [],
memory_size = {0, 100000},
validation,
testing,
receptive_field = full,
step = 0,
block_size = 100,
err_acc = 0,
backprop_tuning = off,
training_length = 1000
}).
-record(layer, {
id,
type,
noise,
neurode_type = tanh,
dynamics = dynamic,
neurodes = [],
tot_neurodes,
input,
output,
ivl,
encoder = [],
decoder = [],
backprop_tuning = off,
index_start,
index_end,
parameters = []
}).
-record(neurode, {
id,
weights,
i,
af,
bias,
parameters = [],
dot_product
}).
-endif. %% MACULA_TWEANN_RECORDS_HRL