How ratinabox-lab/ratinabox works
Project Type and Purpose
• RatInABox is an open-source Python toolkit (library) for simulating agent trajectories and neural firing in continuous 1D/2D environments.
• It provides core classes (Environment, Agent, Neurons) plus extension points for custom cell types and demos illustrating usage.
Key Architectural Elements
A. Core Package (ratinabox/)
• Environment module – defines maze boundaries, walls, objects, and sampling methods
• Agent module – policies for random motion, imported trajectories, policy control, multiple agents
• Neurons module – base Neurons class plus subclasses (PlaceCells, GridCells, BoundaryVectorCells, ObjectVectorCells, VelocityCells, SpeedCells, FieldOfViewNeurons, FeedForwardLayer, NeuralNetworkNeurons, SuccessorFeatures, ValueNeuron, etc.)
• Utils – global settings (figure directory), save and styling helpers
• Data – bundled example datasets (e.g., sargolini.npz)
• Contribs – user-contributed/custom agents or neurons (e.g., ThetaSequenceAgent, PhasePrecessingPlaceCells)
B. Supporting Infrastructure
• demos/ – Jupyter notebooks and scripts demonstrating core features, plotting, deep learning, RL, path integration
• docs/ – Sphinx documentation sources, configuration, and deployment workflows
• tests/ – unit tests covering core classes and APIs
• CI/CD – GitHub Actions workflows for tests and docs build/deploy
• Packaging – setup.py, pyproject.toml, setup.cfg for pip distribution
Component Relationships and Data Flow
• User code or demo notebooks import Environment, Agent, Neurons classes.
• Environment provides spatial structure; Agent queries Environment for valid moves and updates position.
• Agent updates trigger Neurons.update(), where each neuron population reads Agent state (position, velocity) and Environment context to compute firing rates (and optionally spikes).
• Neurons store history (rates, spikes) for downstream plotting or analysis.
• FeedForwardLayer and NeuralNetworkNeurons form directed acyclic graphs of neuron populations (layered architecture).
• Utils handle figure generation and saving, controlled by global flags.
• Tests validate interactions among these components.
Architectural Patterns and Principles
• Object-oriented design: clear separation of concerns among Environment, Agent, Neuron types.
• Plugin/extensibility: base Neurons class with well-defined interface for subclassing. Contribs folder for community extensions.
• Data-flow graphs among neuron populations (feed-forward / deep network patterns).
• Continuous simulation loop pattern: for each time step, Agent.update() → Neurons.update() → record history → optional plotting.
• Dependency injection: user passes neural network models (PyTorch) into NeuralNetworkNeurons for arbitrary function approximation.
• Modular demos and docs integrated via Sphinx and CI workflows for automated build and deployment.