brainstate

Build stateful BrainState modules with State-aware JAX transforms and simulation environments.

1|Updated Jul 23, 2026
One-click install
npx skills add https://github.com/chaobrain/BrainX-skill --skill brainstate-chaobrain
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: brainstate
Source: https://github.com/chaobrain/BrainX-skill/tree/main/brainx-display-cases/creative-experiment-verification/06-seizure-recruitment/run2/.agents/skills/brainstate
Command: npx skills add https://github.com/chaobrain/BrainX-skill --skill brainstate-chaobrain

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill requires brainstate, brainunit, braintools, jax, numpy, matplotlib, and includes scripts (resource) and references (resource) components.

What problem does it solve? Building neural models in JAX requires threading mutable state through functional transforms, which is error-prone. This Skill guides the construction of BrainState models where mutable State, Module graphs, environment-scoped simulations, and state-aware jit/grad/vmap transforms work together correctly. ## Core Features & Use Cases - Stateful Module Construction: Create Modules with State roles (HiddenState, ShortTermState, ParamState), registered child graphs, and size-aware Sequential composition with .desc() inference. - State-Aware Transforms: Apply brainstate.transform jit, grad, and vmap that track State reads and writes, enabling compiled training steps and batched ensembles. - Simulation Environments: Run environment-scoped simulations with dt, time, and fit-mode contexts, collective state initialization/reset, and reproducible randomness. - Use Case: Train a custom RNN on temporal integration tasks by defining a Module with trainable ParamState weights, wrapping the loss in brainstate.transform.grad, and compiling the training step with jit. ## Quick Start Use the brainstate skill to build a stateful RNN module with trainable parameters and a jit-compiled training step.

Frequently Asked Questions about brainstate

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I build a stateful neural network with BrainState?

Subclass brainstate.nn.Module, assign State objects and child Modules as attributes, and implement computation in update(). Initialize states with brainstate.nn.init_all_states before the first rollout, then run the model inside a brainstate.environ.context with dt and fit settings.

How do I compute gradients over BrainState model parameters?

Collect trainable weights with model.states(brainstate.ParamState), then call brainstate.transform.grad(loss_fn, params, return_value=True) to get gradients keyed by State paths. Wrap the update in brainstate.transform.jit for a compiled training step.

Can BrainState models convert to Flax or Equinox?

Yes, brainstate.interop converts supported layers and Sequential stacks to and from Flax NNX, Flax Linen, and Equinox with numerical output equivalence. Check interop.supported_layers() in your installed version, and pass sample_input when importing spatial layers like Conv.

Why does raw jax.jit lose BrainState State mutations?

Raw JAX transforms do not track State reads and writes, so mutations inside the transformed function are lost. Use brainstate.transform.jit, grad, and vmap instead, which discover State effects and handle write-back automatically.

How do I reset BrainState hidden states between sequences?

Call brainstate.nn.reset_all_states(model) at each sequence boundary to reset states across the whole module graph. For batched ensembles, use vmap_reset_all_states but verify each mapped State retains its leading lane axis afterward.