jlietz93/adaptive_modular_network

Adaptive Modular Network (AMN)

Neuroca Research

This repository preserves the surviving implementation artifacts of the Adaptive Modular Network (AMN), an early 2025 research architecture built around modular spiking neural units, local plasticity, dynamic coordination, and a bespoke Self-Improvement Engine (SIE).

The repository is kept primarily for research provenance, but the source is executable and can also be used as a starting point for independent experiments.

Research lineage

AMN → FUM → VDM

AMN is the generation preserved here. FUM and VDM are separate successor models.

Repository contents

File	Role
amn_prototype.py	Early AMN prototype associated with the March 2025 development period
amn_model.pth	Surviving AMN model checkpoint
amn_prototype_v2.py	Later experimental AMN refactor
_legacy/amn_prototype.py	Later expanded AMN development branch
.gitattributes	Hugging Face / Git LFS configuration, including *.pth
.gitignore	Local environment exclusions

The surviving files do not represent one single frozen source revision. They preserve multiple points in AMN's development and should be read as historical implementation states.

Quick start

Create an isolated Python environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install torch norse numpy

Exact historical dependency versions were not preserved, so current-library execution should be treated as a compatibility experiment rather than a byte-identical reconstruction of the original 2025 environment.

Hardware note

The preserved amn_prototype.py explicitly uses two CUDA devices:

device_primary = torch.device("cuda:0")
device_secondary = torch.device("cuda:1")

Running that file unchanged therefore expects two CUDA-visible GPUs. If you are adapting AMN to one GPU or CPU, make an experimental copy instead of editing the provenance source in place:

mkdir -p experiments
cp amn_prototype.py experiments/amn_single_device.py

Then change device selection in the copy for your environment.

Generate a fresh AMN checkpoint

The preserved prototype contains its own training loop and model save path. Running:

python amn_prototype.py

attempts the built-in training experiment and saves the best recovered state to:

amn_model.pth

The built-in example uses:

input:  3
target: 5
relationship under test: x + 2

Training runs for at most 200 epochs and stops early when both conditions are met:

loss < 0.01
48 Hz <= output rate <= 52 Hz

The script then runs two built-in generalization checks:

1 → 3
4 → 6

and reports learning, SIE, generalization, and runtime checks.

Important provenance distinction

The surviving amn_prototype.py is a recovered implementation snapshot, not proven to be the exact source revision that produced every contemporaneous March 2025 result. It also contains experiment-specific x + 2 assistance in its forward path. Therefore a model generated from this exact file should be described as a run of the preserved recovered snapshot, not automatically as a reproduction of the original independently learned x + 2 result.

That distinction is one reason independent experiments are useful.

Try your own training experiment

Do not overwrite the preserved source. Start from a copy:

mkdir -p experiments
cp amn_prototype.py experiments/my_amn_experiment.py

The built-in task is defined near the bottom of the file:

input_spikes = encode_number(3)
target_spikes = encode_number(5)

The built-in test cases are:

test_cases = [(1, 3), (4, 6)]

Those are the first places to change when constructing a new experiment.

For a genuinely new mapping or inference task, also inspect and remove or disable any experiment-specific direct-mapping logic in your experimental copy. Otherwise the test can accidentally measure the built-in task rule rather than AMN's learning behavior.

Example experiment: withheld x + 2 values

A stronger version of the original toy task would:

1. train on several values rather than one;
2. keep a separate set of values completely withheld from training;
3. disable the experiment-specific direct mapping in the experimental copy;
4. evaluate the withheld values only after training;
5. repeat the experiment across multiple random seeds.

For example:

train:  0→2, 2→4, 5→7, 8→10
holdout: 1→3, 3→5, 6→8, 9→11

Record loss, decoded output rate, absolute error, runtime, spike rate, and whether convergence survives across seeds.

Suggested experiments

AMN is more interesting as an experimental architecture than as a frozen checkpoint. Useful tests include:

1. Reproducibility across seeds

Run the same task under multiple seeds and record:

• convergence rate;
• final loss;
• output error;
• number of epochs;
• runtime;
• variance across runs.

A single successful run is much weaker than a stable distribution of successful runs.

2. SIE ablation

Compare otherwise identical runs with:

• the original SIE enabled;
• SIE learning-rate updates disabled;
• a fixed STDP learning rate.

This tests whether the bespoke SIE is actually contributing beyond the base learning dynamics.

3. STDP ablation

Compare:

• STDP enabled;
• STDP disabled;
• fixed modular-unit weights.

Track whether performance, convergence, or stability changes.

4. Coordinator ablation

The early AMN architecture contains a separate coordinator network. Compare:

• full AMN with coordinator;
• fixed inter-unit connectivity;
• no learned coordinator;
• alternative distributed routing.

This is particularly useful historically because later FUM generations moved away from a fixed coordinator module.

5. Scale sweep

Vary one parameter at a time:

num_units
neurons_per_unit
timesteps

Measure:

• wall-clock runtime;
• peak memory;
• spike rate;
• convergence;
• output error.

Do not change all three simultaneously if the goal is to understand which structural variable caused the effect.

6. New functional mappings

After removing task-specific direct assistance in an experimental copy, test mappings such as:

x + 1
2x
x - 3
piecewise mappings
multiple-output mappings

Use held-out inputs rather than only replaying training examples.

7. Failure tests

Useful negative controls include:

• shuffled targets;
• impossible/inconsistent mappings;
• frozen coordinator;
• randomized connectivity after training;
• SIE forced to an intentionally poor learning rate;
• STDP weights reset before evaluation.

A good experiment should establish not only what succeeds, but what causes the behavior to disappear.

Experimental use of exact historical FUM-derived variants

This repository may optionally include two later FUM-era analysis packages under:

experiments/
└── fum_derived/
    ├── README.md
    ├── LICENSE
    ├── EXACT_VARIANT_MANIFEST.sha256
    ├── SIE_Analysis/
    └── Knowledge_Graph_Analysis/

These are later FUM-derived experimental instruments, not original AMN components. They are included specifically to invite cross-generation experiments on AMN.

Exact-generation boundary

The public-use grant applies only to the exact historical variants distributed in SIE_Analysis/ and Knowledge_Graph_Analysis/ and identified by EXACT_VARIANT_MANIFEST.sha256.

These files predate later VDM development. They must not be represented as the newer VDM versions of similarly named mechanisms. In particular, the grant does not cover later/current VDM SIE implementations, VDM graph/topology machinery, Void Dynamics mechanisms, unpublished successor code, or other VDM-era descendants merely because they share names, concepts, or ancestry.

Shared lineage is not implementation identity.

Historical FUM SIE analysis

The released SIE_Analysis/ package examines a later-than-AMN FUM multi-objective SIE formulation involving TD error, novelty, habituation, self-benefit, synaptic scaling, and decay.

A useful AMN crossover experiment would compare:

• the original AMN SIE;
• a fixed-learning-rate control;
• this exact historical FUM SIE formulation;

under the same AMN task, seeds, and network configuration.

The package is a standalone NumPy-oriented simulation/analysis rather than a drop-in AMN module, so integration should occur through an explicit experimental adapter.

Historical FUM knowledge-graph/TDA analysis

The released Knowledge_Graph_Analysis/ package analyzes graph topology and persistent-homology-style structure.

AMN's coordinator produces an inter-unit connection matrix, making a crossover experiment plausible: export AMN connectivity snapshots during training and analyze their changing topology with this historical FUM instrument.

The package expects its own snapshot schema, including w_ij, efficiency_score, and pathology_score. An AMN adapter should define any AMN-specific meanings for those fields explicitly rather than silently inheriting later FUM semantics.

Permission to experiment

The exact copies in this subtree are released under the scoped MIT notice in experiments/fum_derived/LICENSE. Their embedded historical "written permission required" notices are satisfied and superseded for these packaged copies only by that license.

This permission is intentionally narrow: it makes these stale historical FUM variants available for experimentation without opening or relicensing newer VDM technology.

Original prototype

amn_prototype.py contains the early AMN architecture built around:

• modular Leaky Integrate-and-Fire spiking units using Norse;
• custom Spike-Timing-Dependent Plasticity (STDP);
• a global CoordinatorPolicyNetwork for dynamic inter-unit connectivity;
• a SelfImprovementEngine that adjusts learning behavior from loss trends;
• temporal spike-rate encoding and decoding;
• a dual-GPU execution layout using cuda:0 and cuda:1.

The surviving source is a research prototype rather than a polished library. It contains experiment-specific logic, extensive diagnostics, and development material accumulated while the architecture was being explored.

Surviving checkpoint

amn_model.pth is the surviving model artifact associated with the early AMN development period.

It can be inspected with a current PyTorch installation using restricted loading:

import torch

checkpoint = torch.load(
    "amn_model.pth",
    map_location="cpu",
    weights_only=True,
)

print(checkpoint.keys())

Inspection of the preserved checkpoint records:

Field	Value
epoch	193
loss	0.008590729907155037
output rate	50.21013641357421
SIE learning rate	0.1

These values describe this checkpoint only; they are not used here to infer the exact state of every AMN experiment.

Later AMN variants

_legacy/amn_prototype.py

_legacy/amn_prototype.py is a larger July 2025 AMN development branch. It retains recognizable AMN components while expanding the code toward multi-task processing and a broader architecture.

It is preserved because it documents how AMN was being extended before the research line moved into FUM.

Repository layout

.
├── README.md
├── .gitattributes
├── .gitignore
├── amn_prototype.py
├── amn_prototype_v2.py
├── amn_model.pth
└── _legacy/
    └── amn_prototype.py

If optional FUM-derived crossover experiments are later added, they should live under experiments/fum_derived/ and remain outside this historical AMN tree.

Provenance status

This repository is intended to preserve AMN, not retroactively rewrite it into the architecture that came later.

What is directly preserved here:

• the early AMN prototype source;
• the surviving AMN checkpoint;
• two later AMN implementation variants;
• the original file-level development structure supplied for this archive.

FUM and VDM remain separate successor models. Later mechanisms may be imported into experiments/ specifically for cross-generation testing without being reclassified as original AMN components.

Successor

AMN was followed by FUM, which developed through multiple generations before the research line became VDM.

This repository preserves AMN while leaving room for clearly isolated experiments that ask what later mechanisms do when applied back onto it.