tweann_nif (macula_tweann v0.18.1)
View SourceNative Implemented Functions for high-performance network evaluation.
This module provides accelerated network evaluation for TWEANN.
Implementation Priority
1. **Enterprise (macula_nn_nifs)**: If the macula_nn_nifs dependency is available (private git repo), its Rust NIFs are used automatically. This provides 10-15x speedup for compute-intensive operations.
2. **Pure Erlang (tweann_nif_fallback)**: If enterprise NIFs are not available, pure Erlang implementations are used. Always works.
Usage
1. Compile a genotype to a network reference: Network = tweann_nif:compile_network(Nodes, InputCount, OutputIndices)
2. Evaluate the network: Outputs = tweann_nif:evaluate(Network, Inputs)
3. For batch evaluation (many inputs, same network): OutputsList = tweann_nif:evaluate_batch(Network, InputsList)
Network Compilation Format
Nodes are provided as a list of tuples: [{Index, Type, Activation, Bias, [{FromIndex, Weight}, ...]}, ...]
Where: - Index: integer node index (0-based) - Type: atom (input | hidden | output | bias) - Activation: atom (tanh | sigmoid | relu | etc.) - Bias: float - Connections: list of {FromIndex, Weight} tuples
Nodes MUST be in topological order (inputs first, then hidden, then outputs).
Summary
Functions
Benchmark network evaluation.
Build cumulative fitness array for roulette selection.
Calculate compatibility distance between two genomes.
Compile a network for fast evaluation.
Compute reward component with normalization.
Batch compute weighted reward.
Batch dot product for multiple neurons.
Fast dot product for signal aggregation.
Dot product with pre-flattened data.
Compute Euclidean distance between two behavior vectors.
Batch Euclidean distance from one vector to many.
Evaluate a compiled network with given inputs.
Evaluate a network with multiple input sets.
CfC (Closed-form Continuous-time) evaluation.
Batch CfC evaluation for time series.
CfC evaluation with custom backbone and head weights.
ODE-based LTC evaluation.
ODE evaluation with custom weights.
Compute fitness statistics in single pass.
Flatten weights for efficient dot product.
Create histogram bins.
Check if enterprise NIFs are loaded.
Compute k-nearest neighbor novelty score.
Batch kNN novelty for multiple behaviors.
Mutate weights using gaussian perturbation.
Batch mutate multiple genomes with per-genome parameters.
Batch mutate with uniform parameters.
Mutate weights with explicit seed for reproducibility.
Generate random weights uniformly distributed in [-1, 1].
Batch generate random weights for multiple genomes.
Generate gaussian random weights from N(Mean, StdDev).
Generate random weights with explicit seed.
Roulette wheel selection with binary search.
Batch roulette selection.
Compute Shannon entropy.
Tournament selection.
Batch compute weight distances from target to many others.
Compute L1 (Manhattan) distance between weight vectors.
Compute L2 (Euclidean) distance between weight vectors.
Compute weighted moving average.
Compute z-score normalization.
Functions
-spec benchmark_evaluate(Network :: reference() | map(), Inputs :: [float()], Iterations :: pos_integer()) -> float().
Benchmark network evaluation.
Build cumulative fitness array for roulette selection.
-spec compatibility_distance(ConnectionsA :: [{non_neg_integer(), float()}], ConnectionsB :: [{non_neg_integer(), float()}], C1 :: float(), C2 :: float(), C3 :: float()) -> float().
Calculate compatibility distance between two genomes.
-spec compile_network(Nodes :: [{non_neg_integer(), atom(), atom(), float(), [{non_neg_integer(), float()}]}], InputCount :: non_neg_integer(), OutputIndices :: [non_neg_integer()]) -> reference() | map().
Compile a network for fast evaluation.
-spec compute_reward_component(History :: [float()], Current :: float()) -> {float(), float(), float()}.
Compute reward component with normalization.
Batch compute weighted reward.
Batch dot product for multiple neurons.
Fast dot product for signal aggregation.
-spec dot_product_preflattened(Signals :: [float()], Weights :: [float()], Bias :: float()) -> float().
Dot product with pre-flattened data.
Compute Euclidean distance between two behavior vectors.
-spec euclidean_distance_batch(Target :: [float()], Others :: [[float()]]) -> [{non_neg_integer(), float()}].
Batch Euclidean distance from one vector to many.
Evaluate a compiled network with given inputs.
Evaluate a network with multiple input sets.
-spec evaluate_cfc(Input :: float(), State :: float(), Tau :: float(), Bound :: float()) -> {float(), float()}.
CfC (Closed-form Continuous-time) evaluation.
-spec evaluate_cfc_batch(Inputs :: [float()], InitialState :: float(), Tau :: float(), Bound :: float()) -> [{float(), float()}].
Batch CfC evaluation for time series.
-spec evaluate_cfc_with_weights(Input :: float(), State :: float(), Tau :: float(), Bound :: float(), BackboneWeights :: [float()], HeadWeights :: [float()]) -> {float(), float()}.
CfC evaluation with custom backbone and head weights.
-spec evaluate_ode(Input :: float(), State :: float(), Tau :: float(), Bound :: float(), Dt :: float()) -> {float(), float()}.
ODE-based LTC evaluation.
-spec evaluate_ode_with_weights(Input :: float(), State :: float(), Tau :: float(), Bound :: float(), Dt :: float(), BackboneWeights :: [float()], HeadWeights :: [float()]) -> {float(), float()}.
ODE evaluation with custom weights.
-spec fitness_stats(Fitnesses :: [float()]) -> {float(), float(), float(), float(), float(), float()}.
Compute fitness statistics in single pass.
-spec flatten_weights(WeightedInputs :: [{non_neg_integer(), [{float(), float(), float(), [float()]}]}]) -> {[float()], [non_neg_integer()]}.
Flatten weights for efficient dot product.
-spec histogram(Values :: [float()], NumBins :: pos_integer(), MinVal :: float(), MaxVal :: float()) -> [non_neg_integer()].
Create histogram bins.
-spec is_loaded() -> boolean().
Check if enterprise NIFs are loaded.
-spec knn_novelty(Target :: [float()], Population :: [[float()]], Archive :: [[float()]], K :: pos_integer()) -> float().
Compute k-nearest neighbor novelty score.
-spec knn_novelty_batch(Behaviors :: [[float()]], Archive :: [[float()]], K :: pos_integer()) -> [float()].
Batch kNN novelty for multiple behaviors.
-spec mutate_weights(Weights :: [float()], MutationRate :: float(), PerturbRate :: float(), PerturbStrength :: float()) -> [float()].
Mutate weights using gaussian perturbation.
Batch mutate multiple genomes with per-genome parameters.
-spec mutate_weights_batch_uniform(Genomes :: [[float()]], MutationRate :: float(), PerturbRate :: float(), PerturbStrength :: float()) -> [[float()]].
Batch mutate with uniform parameters.
-spec mutate_weights_seeded(Weights :: [float()], MutationRate :: float(), PerturbRate :: float(), PerturbStrength :: float(), Seed :: non_neg_integer()) -> [float()].
Mutate weights with explicit seed for reproducibility.
-spec random_weights(N :: non_neg_integer()) -> [float()].
Generate random weights uniformly distributed in [-1, 1].
-spec random_weights_batch(Sizes :: [non_neg_integer()]) -> [[float()]].
Batch generate random weights for multiple genomes.
-spec random_weights_gaussian(N :: non_neg_integer(), Mean :: float(), StdDev :: float()) -> [float()].
Generate gaussian random weights from N(Mean, StdDev).
-spec random_weights_seeded(N :: non_neg_integer(), Seed :: non_neg_integer()) -> [float()].
Generate random weights with explicit seed.
-spec roulette_select(Cumulative :: [float()], Total :: float(), RandomVal :: float()) -> non_neg_integer().
Roulette wheel selection with binary search.
-spec roulette_select_batch(Cumulative :: [float()], Total :: float(), RandomVals :: [float()]) -> [non_neg_integer()].
Batch roulette selection.
Compute Shannon entropy.
-spec tournament_select(Contestants :: [non_neg_integer()], Fitnesses :: [float()]) -> non_neg_integer().
Tournament selection.
-spec weight_distance_batch(Target :: [float()], Others :: [[float()]], UseL2 :: boolean()) -> [{non_neg_integer(), float()}].
Batch compute weight distances from target to many others.
Compute L1 (Manhattan) distance between weight vectors.
Compute L2 (Euclidean) distance between weight vectors.
Compute weighted moving average.
Compute z-score normalization.