artlib 0.1.7

A Python library for Adaptive Resonance Theory (ART) algorithms.

AdaptiveResonanceLib

Welcome to AdaptiveResonanceLib, a comprehensive and modular Python library for Adaptive Resonance Theory (ART) algorithms. Based on scikit-learn, our library offers a wide range of ART models designed for both researchers and practitioners in the field of machine learning and neural networks. Whether you're working on classification, clustering, or pattern recognition, AdaptiveResonanceLib provides the tools you need to implement ART algorithms efficiently and effectively.

Adaptive Resonance Theory (ART)

Adaptive Resonance Theory (ART) is both

1. A neuroscientific theory of how the brain balances plasticity (learning new information) with stability (retaining what it already knows), and
2. A family of machine‑learning algorithms that operationalise this idea for clustering, classification, continual‑learning, and other tasks.

First proposed by Stephen Grossberg and Gail Carpenter in the mid‑1970s , ART models treat learning as an interactive search between bottom‑up evidence and top‑down expectations:

1. Activation. A new input pattern activates stored memories (categories) in proportion to their similarity to the input.

2. Candidate selection. The most active memory (call it J) is tentatively chosen to represent the input.

3. Vigilance check (resonance test). The match between the input and memory J is compared to a user‑chosen threshold (ρ) (the vigilance parameter).

   • If the match ≥ (ρ) → Resonance. The memory and input are deemed compatible; J is updated to incorporate the new information.
   • If the match < (ρ) → Mismatch‑reset. Memory J is temporarily inhibited, and the next best candidate is tested.
   • If no memory passes the test → a new category is created directly from the input.

4. Output. In clustering mode, the index of the resonant (or newly created) memory is returned as the cluster label.

A step-by-step flow chart depicting the generalized ART algorithm can be found here.

Vigilance

ρ sets an explicit upper bound on how dissimilar two inputs can be while still ending up in the same category:

Vigilance (ρ)	Practical effect
( ρ = 0 )	All inputs merge into a single, broad category
Moderate (( 0 < ρ < 1 ))	Finer granularity as (ρ) increases
( ρ = 1 )	Every distinct input forms its own category (memorisation)

This single knob lets practitioners trade off specificity against generality without retraining from scratch.

Notable Variants

Variant	Input type	Task	Trait
ART 1	Binary	Unsupervised clustering	Original model
Fuzzy ART	Real‑valued ([0,1])	Unsupervised clustering	Uses fuzzy AND operator for analog inputs, resulting in rectagular categories
ARTMAP	Paired inputs ((X, y))	Supervised classification	Two ART modules linked by an associative map field
Gaussian ART	Real‑valued	Clustering	Replace rectangular category fields with Gaussian ones for smoother decision boundaries
FALCON	Paired inputs ((State, Action, Reward))	Reinforcement Learning	Uses three ART modules to create a dynamic SARSA grid for solving reinforcement learning tasks

All variants share the same resonance‑test backbone, so you can grasp one and quickly extend to the others.

Strengths and Things to Watch

• Online / incremental learning – adapts one sample at a time without replay.
• Explicit category prototypes – easy to inspect and interpret.
• Built‑in catastrophic‑forgetting control via (ρ).
• Parameter sensitivity – vigilance (and, in many variants, the learning rate (\beta)) must be tuned to your data.
• Order dependence – the sequence of inputs can affect category formation; shuffling your training data is recommended for unbiased results.

Available Models

AdaptiveResonanceLib includes implementations for the following ART models:

• Elementary Clustering

  • ART1
  • ART2
  • Bayesian ART
  • Gaussian ART
  • Hypersphere ART
  • Ellipsoid ART
  • Fuzzy ART
  • Quadratic Neuron ART
  • Binary Fuzzy ART

• Metric Informed

  • CVI ART
  • iCVI Fuzzy ART

• Topological

  • Topo ART
  • Dual Vigilance ART

• Classification

  • Simple ARTMAP

• Regression

  • ARTMAP
  • Fusion ART

• Hierarchical

  • DeepARTMAP
  • SMART

• Data Fusion

  • Fusion ART

• Reinforcement Learning

  • FALCON
  • TD-FALCON

• Biclustering

  • Biclustering ARTMAP

• C++ Accelerated

  • Fuzzy ARTMAP
  • Hypersphere ARTMAP
  • Gaussian ARTMAP
  • Binary Fuzzy ARTMAP

Comparison of Elementary Models

Installation

To install AdaptiveResonanceLib, simply use pip:

pip install artlib

Or to install directly from the most recent source:

pip install git+https://github.com/NiklasMelton/AdaptiveResonanceLib.git@develop

Ensure you have Python 3.9 or newer installed.

Quick Start

Here are some quick examples to get you started with AdaptiveResonanceLib:

Clustering Data with the Fuzzy ART model

from artlib import FuzzyART
import numpy as np
from tensorflow.keras.datasets import mnist

# Load the MNIST dataset
n_dim = 28*28
(X_train, _), (X_test, _) = mnist.load_data()
X_train = X_train.reshape((-1, n_dim)) # flatten images
X_test = X_test.reshape((-1, n_dim))

# Initialize the Fuzzy ART model
model = FuzzyART(rho=0.7, alpha = 0.0, beta=1.0)

# (Optional) Tell the model the data limits for normalization
lower_bounds = np.array([0.]*n_dim)
upper_bounds = np.array([255.]*n_dim)
model.set_data_bounds(lower_bounds, upper_bounds)

# Prepare Data
train_X_prep = model.prepare_data(X_train)
test_X_prep = model.prepare_data(X_test)

# Fit the model
model.fit(train_X_prep)

# Predict data labels
predictions = model.predict(test_X_prep)

Fitting a Classification Model with SimpleARTMAP

from artlib import GaussianART, SimpleARTMAP
import numpy as np
from tensorflow.keras.datasets import mnist

# Load the MNIST dataset
n_dim = 28*28
(X_train, y_train), (X_test, y_test) = mnist.load_data()
X_train = X_train.reshape((-1, n_dim)) # flatten images
X_test = X_test.reshape((-1, n_dim))

# Initialize the Gaussian ART model
sigma_init = np.array([0.5]*X_train.shape[1]) # variance estimate for each feature
module_a = GaussianART(rho=0.0, sigma_init=sigma_init)

# (Optional) Tell the model the data limits for normalization
lower_bounds = np.array([0.]*n_dim)
upper_bounds = np.array([255.]*n_dim)
module_a.set_data_bounds(lower_bounds, upper_bounds)

# Initialize the SimpleARTMAP model
model = SimpleARTMAP(module_a=module_a)

# Prepare Data
train_X_prep = model.prepare_data(X_train)
test_X_prep = model.prepare_data(X_test)

# Fit the model
model.fit(train_X_prep, y_train)

# Predict data labels
predictions = model.predict(test_X_prep)

Fitting a Regression Model with FusionART

from artlib import FuzzyART, HypersphereART, FusionART
import numpy as np

# Your dataset
X_train = np.array([...]) # shape (n_samples, n_features_X)
y_train = np.array([...]) # shape (n_samples, n_features_y)
test_X = np.array([...])

# Initialize the Fuzzy ART model
module_x = FuzzyART(rho=0.0, alpha = 0.0, beta=1.0)

# Initialize the Hypersphere ART model
r_hat = 0.5*np.sqrt(X_train.shape[1]) # no restriction on hyperpshere size
module_y = HypersphereART(rho=0.0, alpha = 0.0, beta=1.0, r_hat=r_hat)

# Initialize the FusionARTMAP model
gamma_values = [0.5, 0.5] # eqaul weight to both channels
channel_dims = [
  2*X_train.shape[1], # fuzzy ART complement codes data so channel dim is 2*n_features
  y_train.shape[1]
]
model = FusionART(
  modules=[module_x, module_y],
  gamma_values=gamma_values,
  channel_dims=channel_dims
)

# Prepare Data
train_Xy = model.join_channel_data(channel_data=[X_train, y_train])
train_Xy_prep = model.prepare_data(train_Xy)
test_Xy = model.join_channel_data(channel_data=[X_train], skip_channels=[1])
test_Xy_prep = model.prepare_data(test_Xy)

# Fit the model
model.fit(train_Xy_prep)

# Predict y-channel values and clip X values outside previously observed ranges
pred_y = model.predict_regression(test_Xy_prep, target_channels=[1], clip=True)

Data Normalization

AdaptiveResonanceLib models require feature data to be normalized between 0.0 and 1.0 inclusively. This requires identifying the boundaries of the data space.

If the first batch of your training data is representative of the entire data space, you dont need to do anything and artlib will identify the data bounds automatically. However, this will often not be sufficient and the following work-arounds will be needed:

Users can manually set the bounds using the following code snippet or similar:

# Set the boundaries of your data for normalization
lower_bounds = np.array([0.]*n_features)
upper_bounds = np.array([1.]*n_features)
model.set_data_bounds(lower_bounds, upper_bounds)

Or users can present all batches of data to the model for automatic boundary identification:

# Find the boundaries of your data for normalization
all_data = [train_X, test_X]
_, _ = model.find_data_bounds(all_data)

If only the boundaries of your testing data are unknown, you can call model.predict() with clip=True to clip testing data to the bounds seen during training. Only use this if you understand what you are doing.

C++ Optimizations

Most ARTlib classes rely on NumPy / SciPy for linear-algebra routines, but several go further:

Level	Accelerated components	Implementations
Python (Numba JIT)	Activation & vigilance kernels	ART1, Fuzzy ART, Binary Fuzzy ART
Native C++ (Pybind11)	Entire fit / predict pipelines	Fuzzy ARTMAP, Hypersphere ARTMAP, Gaussian ARTMAP, Binary Fuzzy ARTMAP

How the C++ variants work

1. End-to-end native execution – Training and inference run entirely in C++, eliminating Python-level overhead.
2. State hand-off – After fitting, the C++ routine exports cluster weights and metadata back to the corresponding pure-Python class. You can therefore: • inspect attributes (weights_, categories_, …) • serialize with pickle • plug them into any downstream ARTlib or scikit-learn pipeline exactly as you would with the Python-only models.
3. Trade-off – The C++ versions sacrifice some modularity (you cannot swap out internal ART components) in exchange for significantly shorter run-times.

C++ Acceleration Quick reference

Class	Acceleration method	Primary purpose
ART1	Numba JIT kernels	Clustering
Fuzzy ART	Numba JIT kernels	Clustering
Binary Fuzzy ART	Numba JIT kernels	Clustering
Fuzzy ARTMAP	Full C++ implementation	Classification
Hypersphere ARTMAP	Full C++ implementation	Classification
Gaussian ARTMAP	Full C++ implementation	Classification
Binary Fuzzy ARTMAP	Full C++ implementation	Classification

Example Usage

from artlib import FuzzyARTMAP
import numpy as np
from tensorflow.keras.datasets import mnist

# Load the MNIST dataset
n_dim = 28*28
(X_train, y_train), (X_test, y_test) = mnist.load_data()
X_train = X_train.reshape((-1, n_dim)) # flatten images
X_test = X_test.reshape((-1, n_dim))

# Initialize the Fuzzy ART model
model = FuzzyARTMAP(rho=0.7, alpha = 0.0, beta=1.0)

# (Optional) Tell the model the data limits for normalization
lower_bounds = np.array([0.]*n_dim)
upper_bounds = np.array([255.]*n_dim)
model.set_data_bounds(lower_bounds, upper_bounds)

# Prepare Data
train_X_prep = model.prepare_data(X_train)
test_X_prep = model.prepare_data(X_test)

# Fit the model
model.fit(train_X_prep, y_train)

# Predict data labels
predictions = model.predict(test_X_prep)

Timing Comparison

The below figures demonstrate the acceleration seen by the C++ ARTMAP variants in comparison to their baseline Python versions for a 1000 sample subset of the MNIST dataset.

From the above plots, it becomes apparent that the C++ variants are superior in their runtime performance and should be the default choice of practitioners wishing to work with these specific compound models.

While the current selection remains limited, future releases will expand the native C++ implementation as user demand for them increases.

Documentation

For more detailed documentation, including the full list of parameters for each model, visit our Read the Docs page.

Examples

For examples of how to use each model in AdaptiveResonanceLib, check out the /examples directory in our repository.

Contributing

We welcome contributions to AdaptiveResonanceLib! If you have suggestions for improvements, or if you'd like to add more ART models, please see our CONTRIBUTING.md file for guidelines on how to contribute.

You can also join our Discord server and participate directly in the discussion.

License

AdaptiveResonanceLib is open source and available under the MIT license. See the LICENSE file for more info.

Contact

For questions and support, please open an issue in the GitHub issue tracker or message us on our Discord server. We'll do our best to assist you.

Happy Modeling with AdaptiveResonanceLib!

Citing this Repository

If you use this project in your research, please cite it as:

Melton, N. (2025). AdaptiveResonanceLib (Version 0.1.7)