# ratinabox-lab/ratinabox architecture

> Architecture diagram of the GitHub repository ratinabox-lab/ratinabox, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-07-29). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ratinabox-lab/ratinabox
- Repository: https://github.com/ratinabox-lab/ratinabox

## Overview

##### 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.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "ratinabox Core"
        direction TB
        Env["Environment"]:::core
        Agent["Agent"]:::core
        Neurons["Neurons"]:::core
        History["History Store"]:::core
        Utils["Utils"]:::core
        Data["Example Data"]:::core
    end

    subgraph "ratinabox Contribs"
        direction TB
        ThetaSeq["ThetaSequenceAgent"]:::ext
        PhasePre["PhasePrecessingPlaceCells"]:::ext
        PlaneWave["PlaneWaveNeurons"]:::ext
        NNNeurons["NeuralNetworkNeurons"]:::ext
        SubAg["SubAgent"]:::ext
        SuccFeat["SuccessorFeatures"]:::ext
        ValNeuron["ValueNeuron"]:::ext
        TaskEnv["TaskEnvironment"]:::ext
        TaskEnvFiles["TaskEnv_example_files"]:::ext
    end

    subgraph "Project Infrastructure"
        direction TB
        Demos["Demos (notebooks)"]:::infra
        Docs["Documentation (Sphinx)"]:::infra
        Tests["Unit Tests"]:::infra
        CI_Test["CI: test.yml"]:::infra
        CI_Docs["CI: docs_build_and_deploy.yml"]:::infra
        Packaging["Packaging (PyPI)"]:::infra
    end

    %% Core flows
    Env -->|"queries boundaries"| Agent
    Agent -->|"samples next position"| Env
    Agent -->|"state feed"| Neurons
    Neurons -->|"records rates/spikes"| History
    History -->|"plot/save"| Utils

    %% Demos and Docs
    Demos -->|"imports"| Env
    Demos -->|"imports"| Agent
    Demos -->|"imports"| Neurons
    Docs -->|"references"| Env
    Docs -->|"references"| Agent
    Docs -->|"references"| Neurons
    Tests -->|"validates"| Env
    Tests -->|"validates"| Agent
    Tests -->|"validates"| Neurons

    %% Extensibility
    ThetaSeq -->|"subclass of"| Agent
    PhasePre -->|"subclass of"| Neurons
    PlaneWave -->|"subclass of"| Neurons
    NNNeurons -->|"plugin for"| Neurons
    SubAg -->|"subclass of"| Agent
    SuccFeat -->|"subclass of"| Neurons
    ValNeuron -->|"subclass of"| Neurons
    TaskEnv -->|"example env"| Env

    %% CI/CD and Packaging
    Env -.->|deploy/test| CI_Test
    Agent -.->|deploy/test| CI_Test
    Neurons -.->|deploy/test| CI_Test
    Docs -.->|build/deploy| CI_Docs
    Packaging -.->|publish| CI_Test
    Packaging -.->|publish| CI_Docs

    %% Click Events
    click Env "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/Environment.py"
    click Agent "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/Agent.py"
    click Neurons "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/Neurons.py"
    click Utils "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/utils.py"
    click Data "https://github.com/ratinabox-lab/ratinabox/tree/main/ratinabox/data/"
    click ThetaSeq "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/contribs/ThetaSequenceAgent.py"
    click PhasePre "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/contribs/PhasePrecessingPlaceCells.py"
    click PlaneWave "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/contribs/PlaneWaveNeurons.py"
    click NNNeurons "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/contribs/NeuralNetworkNeurons.py"
    click SubAg "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/contribs/SubAgent.py"
    click SuccFeat "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/contribs/SuccessorFeatures.py"
    click ValNeuron "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/contribs/ValueNeuron.py"
    click TaskEnv "https://github.com/ratinabox-lab/ratinabox/blob/main/ratinabox/contribs/TaskEnvironment.py"
    click TaskEnvFiles "https://github.com/ratinabox-lab/ratinabox/tree/main/ratinabox/contribs/TaskEnv_example_files/"
    click Demos "https://github.com/ratinabox-lab/ratinabox/tree/main/demos/"
    click Docs "https://github.com/ratinabox-lab/ratinabox/tree/main/docs/source/"
    click Tests "https://github.com/ratinabox-lab/ratinabox/tree/main/tests/"
    click CI_Test "https://github.com/ratinabox-lab/ratinabox/blob/main/.github/workflows/test.yml"
    click CI_Docs "https://github.com/ratinabox-lab/ratinabox/blob/main/.github/workflows/docs_build_and_deploy.yml"
    click Packaging "https://github.com/ratinabox-lab/ratinabox/blob/main/setup.py"

    %% Styles
    classDef core fill:#AED6F1,stroke:#21618C,color:#1B2631;
    classDef ext fill:#ABEBC6,stroke:#1D8348,color:#1B2631;
    classDef infra fill:#FCF3CF,stroke:#B7950B,color:#1B2631;
```
