faber_nn_nifs (faber_tweann v2.0.1)
View SourceHigh-performance Rust NIFs for faber_tweann.
This module provides native implementations of compute-intensive operations for neuroevolution. It was absorbed into faber_tweann in v2.0.0 from the separate faber-nn-nifs package, and is built from source by priv/build-nifs.sh during compilation.
Do not call this module directly. Use tweann_nif, which dispatches to either this module or tweann_nif_fallback according to the {faber_tweann, [{nif_impl, _}]} setting, and reports the active path via tweann_nif:impl/0.
Every function here that also exists in tweann_nif_fallback must produce the same result. That is enforced by test/unit/nif_fallback_conformance_tests.erl, which exists because the two implementations silently disagreed for months while both test suites passed.
Summary
Functions
Apply specified activation function to batch of values. Activation: tanh | sigmoid | relu | linear | sin | cos | gaussian
Align genes by innovation number.
Assign genomes to species in batch.
Compute weight counts per layer from topology.
Count excess and disjoint genes between two genomes.
Evaluate multiple CfC neurons in parallel.
Evaluate CfC over a sequence of inputs with state persistence.
Find representative for a species.
Batch Hebbian weight update.
Check if NIF is loaded successfully.
K-means clustering for genomes.
Single layer forward pass with activation.
Batch LTC state update for multiple neurons.
Matrix multiply with bias addition.
Batch modulated Hebbian update with reward signal.
Multi-layer forward pass through network.
Mutate weights with different rates for reservoir vs readout layers.
NEAT-style crossover between two genomes.
Batch Oja's rule update (normalized Hebbian).
Compute all pairwise distances in batch.
Compute population diversity metrics.
Apply ReLU activation to a batch of values elementwise.
Apply sigmoid activation to a batch of values elementwise.
Apply softmax to a batch of values (normalized exponential).
Spike-Timing Dependent Plasticity (STDP) update.
Apply tanh activation to a batch of values elementwise.
Compute weight covariance matrix.
Functions
Apply specified activation function to batch of values. Activation: tanh | sigmoid | relu | linear | sin | cos | gaussian
-spec align_genes_by_innovation([{integer(), float(), boolean()}], [{integer(), float(), boolean()}]) -> [{term(), term()}].
Align genes by innovation number.
Returns aligned gene lists for crossover or comparison. Each position contains {GeneA, GeneB} where Gene is either the actual gene or 'none' if missing.
Returns: [{GeneA | none, GeneB | none}, ...]
-spec assign_species_batch([[float()]], [[float()]], float()) -> [non_neg_integer()].
Assign genomes to species in batch.
Assigns each genome to the most compatible existing species, or creates a new species if no compatible species exists.
Genomes: list of weight vectors Representatives: current species representatives Threshold: compatibility threshold for same-species assignment
Returns: list of species indices (0-based)
-spec benchmark_evaluate(reference(), [float()], pos_integer()) -> float().
-spec compile_network(list(), non_neg_integer(), [non_neg_integer()]) -> reference().
-spec compute_layer_weight_counts([non_neg_integer()]) -> [non_neg_integer()].
Compute weight counts per layer from topology.
Given a topology structure (list of layer sizes), returns the number of weights in each layer. Useful for layer-specific mutation.
Topology format: [InputSize, Hidden1Size, Hidden2Size, ..., OutputSize] Returns: [Layer1Weights, Layer2Weights, ...] where Layer N weights = LayerN_size * LayerN-1_size (fully connected assumption)
-spec count_excess_disjoint([{integer(), float(), boolean()}], [{integer(), float(), boolean()}]) -> {non_neg_integer(), non_neg_integer(), non_neg_integer()}.
Count excess and disjoint genes between two genomes.
Excess genes: genes with innovation > max of other genome Disjoint genes: non-matching genes within shared innovation range
Returns: {ExcessCount, DisjointCount, MatchingCount}
-spec euclidean_distance_batch([float()], [[float()]]) -> [{non_neg_integer(), float()}].
-spec evaluate_cfc_parallel(float(), [{float(), float(), float()}], [float()], [float()]) -> [{float(), float()}].
Evaluate multiple CfC neurons in parallel.
Processes the same input through multiple CfC neurons with different parameters. Useful for ensemble or population-based evaluation.
Input: single input value NeuronParams: list of {State, Tau, Bound} for each neuron Returns: list of {NewState, Output} for each neuron
-spec evaluate_cfc_sequence([float()], float(), float(), float(), [float()]) -> [{float(), float()}].
Evaluate CfC over a sequence of inputs with state persistence.
Processes a time series through the CfC neuron, maintaining state across timesteps. More efficient than calling evaluate_cfc repeatedly.
Inputs: list of input values (time series) InitialState: starting state value Tau: time constant Bound: output bound BackboneWeights: optional backbone network weights
Returns: list of {State, Output} tuples for each timestep
-spec find_representative([[float()]], atom()) -> non_neg_integer().
Find representative for a species.
Finds the genome closest to the centroid (most representative) of the given species members.
Members: list of weight vectors in the species Method: centroid | random | fittest
Returns: index of representative in members list
Batch Hebbian weight update.
Implements Hebbian learning rule: dW = eta * pre * post Where eta is the learning rate, pre is presynaptic activity, post is postsynaptic activity.
Input: list of {Weight, PreActivity, PostActivity} tuples LearningRate: global learning rate multiplier Returns: list of updated weights
-spec histogram([float()], pos_integer(), float(), float()) -> [non_neg_integer()].
-spec is_loaded() -> boolean().
Check if NIF is loaded successfully.
-spec kmeans_cluster([[float()]], pos_integer(), pos_integer()) -> [non_neg_integer()].
K-means clustering for genomes.
Clusters genomes into K groups using k-means algorithm. Useful for diversity-based speciation.
Genomes: list of weight vectors K: number of clusters MaxIterations: maximum iterations for convergence
Returns: list of cluster assignments (0 to K-1)
-spec knn_novelty([float()], [[float()]], [[float()]], pos_integer()) -> float().
-spec knn_novelty_batch([[float()]], [[float()]], pos_integer()) -> [float()].
Single layer forward pass with activation.
Computes layer output: activation(X * W + B)
X: input vector W: weight matrix (flattened) B: bias vector Activation: tanh | sigmoid | relu | linear
Returns: activated output vector
Batch LTC state update for multiple neurons.
Efficiently updates states for multiple LTC neurons given inputs. Used when simulating a layer of LTC neurons.
Inputs: input values for each neuron States: current states for each neuron Taus: time constants for each neuron Dt: time step size
Returns: list of new states
Matrix multiply with bias addition.
Computes Y = X * W + B efficiently for neural network forward pass.
X: input vector (1 x N) W: weight matrix (N x M, flattened row-major) B: bias vector (1 x M) Dims: {N, M} dimensions
Returns: output vector (1 x M)
-spec modulated_hebbian_batch([{float(), float(), float()}], float(), float(), float(), float()) -> [float()].
Batch modulated Hebbian update with reward signal.
Implements reward-modulated Hebbian: dW = eta * reward * pre * post Used for reinforcement learning where weight updates are gated by reward.
-spec multi_layer_forward([float()], [{[float()], [float()], atom()}], [non_neg_integer()]) -> [float()].
Multi-layer forward pass through network.
Efficiently processes input through multiple layers. Avoids crossing NIF boundary for each layer.
Input: input vector Layers: list of {Weights, Biases, Activation} for each layer
Returns: final output vector
-spec mutate_weights_layered([float()], non_neg_integer(), float(), float(), float(), float()) -> [float()].
Mutate weights with different rates for reservoir vs readout layers.
Applies different mutation parameters to reservoir (hidden) layers and readout (output) layer, supporting the reservoir computing paradigm where readout weights often benefit from more aggressive mutation.
ReservoirWeightCount specifies how many weights belong to reservoir layers. The remaining weights are treated as readout layer.
-spec neat_crossover([{integer(), float(), boolean()}], [{integer(), float(), boolean()}], float(), float()) -> [{integer(), float(), boolean()}].
NEAT-style crossover between two genomes.
Performs NEAT crossover where genes are aligned by innovation number: - Matching genes: randomly select from either parent - Disjoint/Excess genes: taken from more fit parent
Genome format: list of {InnovationNum, Weight, Enabled} tuples FitnessA, FitnessB: fitness values to determine which parent's disjoint/excess genes to use
Returns: offspring genome
Batch Oja's rule update (normalized Hebbian).
Implements Oja's rule: dW = eta * (post * pre - post^2 * W) This is a normalized Hebbian rule that prevents unbounded weight growth and extracts principal components.
Compute all pairwise distances in batch.
Efficiently computes distances between all pairs in a population. DistType: l1 | l2 | euclidean
Returns: flattened distance matrix (upper triangular, row-major)
Compute population diversity metrics.
Analyzes a population of weight vectors and computes diversity metrics: - Mean pairwise distance - Standard deviation of pairwise distances - Minimum distance (most similar pair) - Maximum distance (most different pair)
Returns: {MeanDist, StdDist, MinDist, MaxDist}
-spec random_weights(non_neg_integer()) -> [float()].
-spec random_weights_batch([{non_neg_integer(), float(), float()}]) -> [[float()]].
-spec random_weights_gaussian(non_neg_integer(), float(), float()) -> [float()].
-spec random_weights_seeded(non_neg_integer(), integer()) -> [float()].
Apply ReLU activation to a batch of values elementwise.
-spec roulette_select([float()], float(), float()) -> non_neg_integer().
-spec roulette_select_batch([float()], float(), [float()]) -> [non_neg_integer()].
Apply sigmoid activation to a batch of values elementwise.
Apply softmax to a batch of values (normalized exponential).
Spike-Timing Dependent Plasticity (STDP) update.
Implements STDP rule where weight change depends on relative timing of pre and post synaptic spikes: - Pre before post (positive delta_t): potentiation (strengthen) - Post before pre (negative delta_t): depression (weaken)
A_plus, A_minus: amplitude of potentiation/depression Tau_plus, Tau_minus: time constants for decay
Apply tanh activation to a batch of values elementwise.
-spec tournament_select([non_neg_integer()], [float()]) -> non_neg_integer().
Compute weight covariance matrix.
Computes the covariance matrix of weights across a population. Used for CMA-ES and other covariance-aware evolution strategies.
Population: list of weight vectors (all same length) Returns: flattened covariance matrix (row-major order)