Skip to content

api.md

Latest commit

 

History

History
259 lines (198 loc) · 8.06 KB

api.md

File metadata and controls

259 lines (198 loc) · 8.06 KB

API Guide

Use neural_assemblies for maintained package code. Use root imports only when you are running old checkout-oriented scripts.

For scientific claim strength, read scientific_status.md. For code ownership boundaries, read supported_surfaces.md.

Primary Imports

Convenience imports:

from neural_assemblies import Brain, create_engine
from neural_assemblies import project, merge, overlap

Explicit imports are clearer in larger code:

from neural_assemblies.core.brain import Brain
from neural_assemblies.assembly_calculus import (
    Assembly,
    AssemblyTrace,
    Sequence,
    project,
    merge,
    sequence_memorize,
    ordered_recall,
)
from neural_assemblies.assembly_calculus.tracing import (
    merge_trace,
    project_trace,
    projection_sweep,
)

Core Runtime

from neural_assemblies.core.brain import Brain

b = Brain(p=0.05, engine="numpy_sparse", seed=0)
b.add_stimulus("stim", size=100)
b.add_area("A", n=10_000, k=100, beta=0.05)
b.project({"stim": ["A"]}, {})

Main objects:

Object Location Role
Brain core/brain.py Areas, stimuli, routing, projection cycles, and engine delegation.
Area core/area.py Area parameters and winner history.
Stimulus core/stimulus.py Fixed external inputs.
Connectome core/connectome.py Connectivity and learned weights.
ComputeEngine core/engine.py Engine interface used by Brain.
create_engine() core/engine.py Engine factory and registry entry point.

Engines

Engine names accepted by the package include:

  • numpy_sparse
  • numpy_explicit
  • cuda_implicit
  • cupy_sparse
  • torch_sparse

engine="auto" calls detect_best_engine():

  • prefer torch_sparse when n_hint >= 1_000_000 and PyTorch CUDA is available
  • otherwise use numpy_sparse

Treat this as a default, not as a performance claim.

Compute Primitives

import numpy as np

from neural_assemblies.compute import TopKPolicy, WinnerSelector

selector = WinnerSelector(np.random.default_rng(0))
winners = selector.select_with_policy(
    [0.2, 0.8, 0.5, 0.8],
    TopKPolicy(k=2),
)

Important exports:

Object Role
StatisticalEngine Sampling and statistical helpers.
NeuralComputationEngine Input aggregation and activation math.
WinnerSelector Winner-selection logic.
TopKPolicy Fixed-size competition.
ThresholdPolicy Absolute-threshold competition with a k cap.
RelativeThresholdPolicy Variable-size competition based on max-input fraction.
PlasticityEngine Hebbian update logic.

Assembly Calculus

Data types:

Object Role
Assembly Snapshot of winners in one area.
AssemblyTrace Ordered snapshots and per-round metrics from a traced operation.
Sequence Ordered list of assemblies.
Lexicon Mapping from tokens to assemblies.
Transition Typed state transition.
TransitionMap Validated deterministic or probabilistic transitions.

Operations:

Function Purpose
project Form an assembly from a stimulus or upstream area.
project_trace Form an assembly while recording each projection round.
reciprocal_project Copy an assembly between areas with reciprocal support.
reciprocal_project_trace Trace source-area projection into a target area.
associate Link assemblies through shared activation.
associate_trace Trace the three phases of association.
merge Build a conjunctive assembly.
merge_trace Build a conjunctive assembly while recording target dynamics.
pattern_complete_trace Damage a current assembly and trace recurrent recovery.
ordered_recall_trace Replay a sequence with LRI while recording accepted recall steps.
source_response_traces Probe a merged target from each source and compare responses.
projection_sweep Run small independent projection-trace parameter sweeps.
lri_recall_sweep Run small independent LRI recall parameter sweeps.
pattern_complete Recover from partial input.
separate Measure distinctiveness.
snapshot_area Snapshot current winners in an area using comparable neuron IDs.
sequence_memorize Learn an ordered sequence.
ordered_recall Replay a sequence with LRI support.
overlap Measure assembly overlap.
chance_overlap Compute random-overlap baseline.

Structured helpers:

Object Purpose
FSMNetwork Deterministic finite-state helper.
PFANetwork Probabilistic finite automaton helper.
RandomChoiceArea Stochastic choice primitive.
FiberCircuit Declarative projection gating and control.

Visualization

neural_assemblies.viz provides small Matplotlib-based helpers for notebooks and diagnostics. The implementation is split into grid, flow, overlap, and trace-specific modules, while these public imports remain stable:

from neural_assemblies.viz import animate_assembly_trace, plot_assemblies

Use these helpers to make package state inspectable:

  • plot_projection_flow draws the shape of a two-source projection/merge example.
  • plot_assembly and plot_assemblies show winner sets on square neuron grids.
  • animate_assembly_trace animates round-by-round winner turnover from an AssemblyTrace.
  • plot_trace_metrics plots consecutive overlap and new-winner counts.
  • plot_winner_turnover shows which winner IDs persist or rotate over a trace.
  • plot_response_overlap compares same-area responses with a reference assembly and chance overlap.
  • plot_overlap_matrix shows pairwise assembly overlap.
  • plot_recall_trace compares recalled assemblies against known references.
  • plot_parameter_heatmap labels compact sweep matrices.

These helpers are teaching and debugging tools. Use research/ artifacts for scientific evidence.

Simulation Helpers

neural_assemblies.simulation contains runnable helpers for projection, association, merge, pattern completion, density, and Turing-style simulations.

Common imports include:

  • project_sim, project_beta_sim, assembly_only_sim
  • association_sim, association_grand_sim
  • merge_sim, merge_beta_sim
  • pattern_com, pattern_com_repeated
  • density, density_sim
  • fixed_assembly_recip_proj, fixed_assembly_merge, separate
  • larger_k, turing_erase

The Turing-style helpers are exploratory simulation tools. The theoretical claims belong to the sequence-computation papers.

Language

Rule-based parsing:

from neural_assemblies.language import parse

parse("cats chase mice", language="English")

Main exports include ParserBrain, EnglishParserBrain, RussianParserBrain, ReadoutMethod, fixed_map_readout, fiber_readout, ParserDebugger, and parse(...).

Learned-language experiments live under neural_assemblies.nemo and the emergent parser. Tests cover narrow synthetic behaviors; broad acquisition claims need research artifacts.

Lexicon

neural_assemblies.lexicon provides vocabulary and curriculum support:

  • LexiconManager
  • Word
  • WordCategory
  • WordStatistics

The surrounding modules include curriculum data, GPU learners, and assembly-based learners used by language experiments.

NEMO

neural_assemblies.nemo contains experimental language-learning systems.

Common imports from neural_assemblies.nemo.language include:

  • LanguageLearner
  • SentenceGenerator
  • Curriculum
  • CurriculumLearner
  • NemoLanguageLearner
  • NemoBrain
  • NemoParams
  • IntegratedNemoTrainer

Compatibility Imports

Root files such as brain.py, parser.py, and simulations.py remain as compatibility shims. The historical implementations live under legacy/root_modules/.

Prefer package imports for new code.

Useful Commands

uv run pytest neural_assemblies/tests -q
uv run pytest neural_assemblies/tests/test_docs_examples_smoke.py -q
uv run pytest tests/test_legacy_root_shims.py tests/test_legacy_archived_layout.py -q