Keras-first optimizer documentation

NEAT

Nash-Equilibrium Adaptive Training is a conflict-aware optimizer library for Keras and scientific Python workflows.

Start building View API

Keras 3 optimizer API NumPy reference core Python 3.10-3.13

Overview

Simple docs for the NEAT package

NEAT is not neural architecture search and not a full game-theory solver. It is a small optimizer package with a Keras adapter, a NumPy reference engine, player-aware TensorFlow helpers, and an explicit math spec.

Keras Drop-In

Use neat_optim.NEAT inside model.compile(...) with Keras 3 and a backend such as TensorFlow.

Reference Engine

Validate the update rule with deterministic NumPy code before moving into framework-specific training.

Player-Aware Mode

Treat each example, task, or objective head as a gradient contributor in a custom TensorFlow training loop.

Find docs

Search this page

Quickstart

Install and train

Install the Keras extra when training models. Install the core package only when you need the NumPy/reference engine.

Install Keras integration

pip install "neat-optim[keras]" tensorflow

Install core package

pip install neat-optim

Keras ecosystem

Use NEAT in `model.compile`

The main workflow is intentionally familiar to Keras users: create a model, pass NEAT as the optimizer, then inspect diagnostics after training.

Supported Python: 3.10 to 3.13
Package extra: neat-optim[keras]
Keras dependency: keras>=3.13,<4
Backend runtime: TensorFlow or another Keras backend

Keras training example

import keras
from neat_optim import NEAT

model = keras.Sequential([
    keras.layers.Input((32,)),
    keras.layers.Dense(64, activation="relu"),
    keras.layers.Dense(10),
])

optimizer = NEAT(
    learning_rate=1e-3,
    alpha=0.25,
    beta=0.9,
    nce_mode="projection",
    opponent_source="gradient_ema",
    correction_warmup_steps=5,
)

model.compile(
    optimizer=optimizer,
    loss=keras.losses.SparseCategoricalCrossentropy(from_logits=True),
    metrics=["accuracy"],
)

model.fit(x_train, y_train, epochs=5)
print(optimizer.diagnostic_snapshot())

Choose a mode

Pick the right entry point

Keras optimizer

Use NEAT when you want a drop-in optimizer for regular Keras model training.

Diagnostics

Use diagnostic_snapshot() to see conflict ratio, correction ratio, update alignment, and active correction fraction.

Reference engine

Use neat_step(...) for deterministic debugging, algorithm experiments, and framework-independent validation.

Player-aware loop

Use player_train_step(...) when each example or task should contribute its own gradient.

API

Public surface

The package keeps a narrow public API so optimizer behavior is easier to inspect, serialize, benchmark, and test.

`neat_optim.NEAT`

Keras optimizer implementation for model.compile.

`NEATConfig` and `ArrayState`

Reference engine configuration and per-parameter state.

`PlayerNEATConfig`

Configuration for explicit per-player gradient updates.

`neat_step`

Framework-agnostic one-step API for NumPy-style updates.

`neat_player_step`

Player-aware one-step API with conflict and sparsity metrics.

`player_train_step`

TensorFlow helper for custom loops with per-example losses.

Configuration

Important optimizer arguments

Argument	Use
`learning_rate`	Optimizer step size.
`alpha`	Scale of the Nash correction estimate.
`beta`	Momentum mixing factor.
`nce_mode`	`projection`, `cosine`, or `off`.
`opponent_source`	`momentum`, `previous_gradient`, or `gradient_ema`.
`correction_warmup_steps`	Delay correction until a configured number of steps pass.
`conflict_threshold`	Minimum measured conflict before correction is applied.
`sparsity_l1` and `prune_threshold`	Optional pressure toward sparse or pruned weights.

Research

How the update works

NEAT detects directional conflict between a gradient and an opponent proxy. When conflict is present, it applies a bounded correction before momentum and weight decay.

Math spec: nce_spec_v1

conflict_t = relu(-cos(g_t, o_t))
proj_t     = proj_{o_t}(g_t)
nce_t      = -alpha * conflict_t * proj_t
u_t        = g_t + nce_t
m_t        = beta * m_{t-1} + (1 - beta) * u_t
theta_t+1  = (1 - lr * wd) * theta_t - lr * m_t

Player-aware NEAT

Per-example and per-task gradients

In player-aware mode, each element along the leading dimension of player_grads is treated as a player. The default opponent signal is the mean of the other players.

Custom TensorFlow loop

import keras
from neat_optim import PlayerNEATConfig
from neat_optim.training import create_player_states, player_train_step

loss_fn = keras.losses.SparseCategoricalCrossentropy(
    from_logits=True,
    reduction="none",
)

states = create_player_states(model)
config = PlayerNEATConfig(
    learning_rate=1e-2,
    alpha=0.25,
    beta=0.9,
    sparsity_l1=1e-4,
    prune_threshold=1e-3,
)

result = player_train_step(model, x_batch, y_batch, loss_fn, states, config)
states = result.states

Benchmarks

Measured results

NEAT includes benchmark harnesses for sanity checks, synthetic conflict tasks, Keras MLPs, Keras vision tasks, CIFAR-10, and GLUE SST-2. The current results are early and should be read as evidence, not a universal superiority claim.

0.9861

MNIST mean test accuracy

Adaptive NEAT, two epochs, seeds 7, 11, and 19.

0.8786

Fashion-MNIST mean test accuracy

Adaptive NEAT on the same short Keras CNN setup.

0.9472

Digits MLP mean test accuracy

Standard NEAT trailed SGD, Adam, and AdamW in this run.

Reproduce locally

python benchmarks/run.py
python benchmarks/sweep_neat.py

Contributing

Development workflow

Local development uses an editable install with the development and Keras extras. Run linting, formatting, tests, build checks, and MkDocs validation before releases.

Local setup and checks

python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev,keras]"

ruff check .
ruff format .
pytest
python -m build
mkdocs build --strict

All docs

Source documentation map

Use these links when you need the complete source files, long-form research notes, release workflow, or project policies.

README Quickstart API reference Algorithm Math spec Player-aware mode Benchmarks Examples Development Architecture Release Changelog Contributing Code of conduct Security

Questions

Need help with NEAT?

Open an issue on GitHub for repo discussions, or email the project contact for direct questions.

Email contact GitHub issues