faber-tweann

Topology and Weight Evolving Artificial Neural Networks for Erlang

Evolutionary neural networks that evolve both topology and weights, now with Liquid Time-Constant (LTC) neurons for adaptive temporal processing. Based on DXNN2 by Gene Sher.

Highlights

• First TWEANN library with LTC neurons in Erlang/OTP
• CfC closed-form approximation - ~100x faster than ODE-based LTC
• Rust NIF acceleration - Native implementations of fitness statistics, novelty search, selection and network evaluation (speedup not yet measured; see below)
• Pure Erlang reference implementation - Selected explicitly, held in agreement with the native path by a conformance test
• Hybrid networks - Mix standard and LTC neurons in the same network
• Production ready - Comprehensive logging, error handling, and process safety

Quick Start

%% Add to rebar.config
{deps, [{faber_tweann, "~> 2.0"}]}.

%% Create and evolve a standard network
genotype:init_db(),
SpecieId = genotype:generate_id(specie),
AgentId  = genotype:generate_id(agent),
Constraint = #constraint{morphology = xor_mimic},
genotype:construct_Agent(SpecieId, AgentId, Constraint),
genome_mutator:mutate(AgentId).

%% Use LTC dynamics directly
{NewState, Output} = ltc_dynamics:evaluate_cfc(Input, State, Tau, Bound).

LTC Neurons

Liquid Time-Constant neurons enable adaptive temporal processing with input-dependent time constants:

%% CfC evaluation (fast, closed-form)
{State1, _} = ltc_dynamics:evaluate_cfc(1.0, 0.0, 1.0, 1.0),
{State2, _} = ltc_dynamics:evaluate_cfc(1.0, State1, 1.0, 1.0).
%% State persists between evaluations - temporal memory!

Key equations:

• LTC ODE: dx/dt = -[1/τ + f(x,I,θ)]·x + f(x,I,θ)·A
• CfC: x(t+Δt) = σ(-f)·x(t) + (1-σ(-f))·h (100x faster)

See the LTC Neurons Guide for details.

Documentation

• Installation - Add to your project
• Quick Start - Basic usage
• LTC Neurons - Temporal dynamics
• LTC Usage Guide - Practical examples
• Architecture - System design
• Full Documentation - All guides and module docs

Features

Neural Network Evolution

• Topology Evolution: Networks add/remove neurons and connections
• Weight Evolution: Synaptic weights optimized through selection
• Speciation: Behavioral diversity preservation (NEAT-style)
• Multi-objective: Pareto dominance optimization

LTC/CfC Neurons

• Temporal Memory: Neurons maintain persistent internal state
• Adaptive Dynamics: Input-dependent time constants
• CfC Mode: ~100x faster than ODE-based evaluation
• Hybrid Networks: Mix standard and LTC neurons

Production Quality

• Process Safety: Timeouts and crash handling
• Comprehensive Logging: Structured logging throughout
• Rust NIF (optional): High-performance network evaluation
• ETS Storage: Fast in-memory genotype storage (see ROADMAP.md for planned Mnesia persistence)

Native Acceleration

Rust NIFs for the numeric hot paths ship with this package and are built from source at compile time. A Rust toolchain is required.

There is one edition. The faber-nn-nifs package was absorbed into faber_tweann in v2.0.0; if you depended on faber_nn_nifs directly, depend on faber_tweann instead.

tweann_nif:impl().       %% faber_nn_nifs | tweann_nif_fallback
tweann_nif:is_loaded().  %% true when the native path is active

The native path is the default. If the library is missing or fails to load, faber_tweann raises on first use rather than quietly falling back. To use the pure Erlang implementation deliberately:

[{faber_tweann, [{nif_impl, fallback}]}].

See the Native Acceleration guide.

On performance claims: earlier versions of this README quoted speedups between 30x and 200x, while the faber-nn-nifs README quoted 10-15x for the same code. Neither figure was backed by a committed measurement, and the two were mutually inconsistent. No speedup figures are published here until a benchmark runs and its output is committed. test/benchmark/bench_nif_vs_erlang.erl exists for this purpose.

Architecture

Process-based neural networks with evolutionary operators. See Architecture Guide for details.

Testing

rebar3 eunit          # Unit tests (971 tests)
rebar3 dialyzer       # Static analysis
rebar3 ex_doc         # Generate documentation

Academic References

TWEANN/NEAT

• Sher, G.I. (2013). Handbook of Neuroevolution Through Erlang. Springer.

  • Primary reference for DXNN2 architecture and Erlang implementation patterns.

• Stanley, K.O. & Miikkulainen, R. (2002). Evolving Neural Networks through Augmenting Topologies. Evolutionary Computation, 10(2), 99-127.

  • Foundational NEAT paper introducing speciation and structural innovation protection.

• Stanley, K.O. (2004). Efficient Evolution of Neural Network Topologies. Proceedings of the 2002 Congress on Evolutionary Computation (CEC).

  • Complexity analysis and efficiency improvements for topology evolution.

LTC/CfC Neurons

• Hasani, R., Lechner, M., et al. (2021). Liquid Time-constant Networks. Proceedings of the AAAI Conference on Artificial Intelligence, 35(9), 7657-7666.

  • Introduces adaptive time-constant neurons with continuous-time dynamics.

• Hasani, R., Lechner, M., et al. (2022). Closed-form Continuous-time Neural Networks. Nature Machine Intelligence, 4, 992-1003.

  • CfC closed-form approximation enabling ~100x speedup over ODE-based LTC.

Weight Initialization

• Glorot, X. & Bengio, Y. (2010). Understanding the difficulty of training deep feedforward neural networks. Proceedings of AISTATS.
  • Xavier initialization theory used for network weight initialization.

Evolutionary Algorithms

• Holland, J.H. (1975). Adaptation in Natural and Artificial Systems. MIT Press.

  • Foundational text on genetic algorithms.

• Yao, X. (1999). Evolving Artificial Neural Networks. Proceedings of the IEEE, 87(9), 1423-1447.

  • Comprehensive survey of neuroevolution approaches.

ONNX Export

• ONNX Consortium (2017-present). Open Neural Network Exchange.
  • Open standard for neural network interoperability enabling cross-platform inference.

Related Projects

Faber Ecosystem

• macula - HTTP/3 mesh networking platform with NAT traversal, Pub/Sub, and async RPC. Enables distributed neuroevolution across edge devices.

• faber_neuroevolution - Population-based evolutionary training engine that orchestrates neural network evolution using this library.

Inspiration & Related Work

• DXNN2 - Gene Sher's original TWEANN implementation in Erlang, the foundation for this library.

• NEAT-Python - Popular Python implementation of NEAT.

• SharpNEAT - High-performance C# NEAT implementation.

• PyTorch-NEAT - Uber's PyTorch-based NEAT implementation.

• LTC/CfC Reference Implementation - MIT/ISTA reference implementation of LTC networks.

License

Apache License 2.0 - See LICENSE

Credits

Based on DXNN2 by Gene Sher. Adapted with LTC extensions by R.G. Lefever.