tweann_nif (faber_tweann v2.0.1)
View SourceNative Implemented Functions for high-performance network evaluation.
This module provides accelerated network evaluation for TWEANN.
Implementation Selection
The Rust NIFs ship with faber_tweann (absorbed from the faber-nn-nifs package in v2.0.0) and are built from source at compile time. The native path is therefore the default, and its absence is an error rather than a condition to absorb silently.
Select with {faber_tweann, [{nif_impl, Impl}]}:
nif - require the native path (faber_nn_nifs). Default. Raises on first use if the library is missing or unloadable. fallback - require the pure Erlang path (tweann_nif_fallback). For platforms without a Rust toolchain, and for differential testing of the native path against a reference implementation.
Call tweann_nif:impl/0 to report the active path. Do so in any benchmark.
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.
Report which implementation is active: faber_nn_nifs | tweann_nif_fallback.
Check whether the native NIF path is active.
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 impl() -> faber_nn_nifs | tweann_nif_fallback.
Report which implementation is active: faber_nn_nifs | tweann_nif_fallback.
Call this in any benchmark or experiment log.
-spec is_loaded() -> boolean().
Check whether the native NIF path is active.
-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.