# annarchy/annarchy architecture

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

- Interactive diagram: https://gitdiagram.com/annarchy/annarchy
- Repository: https://github.com/annarchy/annarchy

## Overview

##### Overview: Identify Project Type and Purpose
- ANNarchy is a hybrid Python/C++ library for simulating rate‐coded or spiking neural networks.
- Purpose: Provide a user‐friendly Python API for defining neural networks, convert that definition into optimized C++ code (via OpenMP, CUDA or single‐threaded backends), compile it at runtime, and execute high‐performance simulations.
- Key indicators:
- README emphasizes “parallel and hybrid simulator” and “code generation approach.”
- File tree shows Python package “ANNarchy” alongside directories for “cython_ext,” C++ headers (“include”), code generators and templates.

##### File Structure Analysis
- Top‐level:
- .github, CI workflow
- setup.py / pyproject.toml / requirements.txt: Python packaging & dependencies
- ANNarchy/ (main Python package)
- / (C++ matrix implementations)
- tests/ (unit and integration tests)
- Inside ANNarchy/:
- core/: Python classes for Network, Neuron, Population, Projection, Monitor, I/O
- cython_ext/: Cython definitions (.pxd/.pyx) exposing C++ interfaces to Python
- generator/: Modules for parsing user equations, generating C++ code, compiling with OpenMP, CUDA, single‐thread backends, and creating shared libraries
- inputs/, extensions/, models/, parser/: Support for input sources, optional extensions (e.g. tensorboard, convolution), neuron/synapse models, equation parsing & reporting
- intern/: Runtime support—configuration management, profiler, network manager, global objects
- /: C++ headers implementing sparse/dense matrix formats on CPU/GPU
- Architectural Patterns:
- Layered design: Python API layer → Cython binding → C++ core simulation
- Code‐generation & plug‐in templates for multiple backends
- Modular extensions and parsers

##### README Insights
- Core written in C++, distributed under OpenMP/CUDA.
- Python interface for network definition and control.
- Dependencies emphasize C/C++ build tools (cmake, g++, cython) and Python scientific stack.

##### Main Components and Their Relationships
a. Python User Layer
- User scripts import ANNarchy
- Network, Populations, Projections, Monitors, Inputs
b. ANNarchy Python API (core/, inputs/, models/, extensions/)
- High‐level classes translate user definitions into intermediate representation (AST of equations, connectivity)
- Parser modules analyze neuron/synapse equations
c. Code Generation Engine (generator/)
- Consumes IR → uses template files (OpenMP, CUDA, SingleThread) to produce C++ source and Pyx wrapper code
- Invokes CMake/Compiler to build shared library for target backend
d. Cython Extension Layer (cython_ext/)
- Statically or dynamically binds generated C++ simulation functions to Python
- Exposes low‐level API to drive simulation steps
e. C++ Simulation Core (include/ + compiled generated code)
- Matrix implementations (dense/sparse on CPU/GPU)
- Connector, Neuron update kernels, Synapse update kernels, global simulation loop
- Backends: OpenMP, CUDA, single‐thread
f. Runtime Manager (intern/)
- Manages configurations, profiling, network lifecycle, resource cleanup
g. Data Flow & Monitoring
- Simulation results streamed through Monitor classes back to Python
- Optional storage via XML/HDF5/reporting extensions

##### Architectural Patterns and Principles
- Layered Abstraction: clear separation of user API, code generation, bindings, and execution engine
- Plugin Pattern: templates for multiple backends, extensions for new models or logging
- Builder/Factory: code‐generator creates backend‐specific code artifacts
- Dependency Inversion: Python API depends on abstract backend interfaces, concrete implementation is generated

##### Technologies, Frameworks, and Libraries
- Python 3.10+, Cython 3.0+, NumPy, Sympy, SciPy, Matplotlib
- C++17 (or later), OpenMP, CUDA
- Build tools: CMake, setuptools
- Testing: PyTest (tests/ directories)
- Optional: TensorFlow (ANN→SNN conversion), tensorboardX

##### Summary of Elements
- Components: Python API, Parser & IR, Code Generator, Cython Bindings, C++ Core, Backends, Runtime Manager, Extensions
- Data Flows: AST/equations → C++ source → Shared library → Simulation calls → Data return
- External Dependencies: Python libs, compilers, OpenMP, CUDA

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Python Layer
    User["Python User Layer"]:::pythonapi
    click User "https://github.com/annarchy/annarchy/blob/master/ANNarchy/__init__.py"

    %% API Layer
    subgraph "API Layer"
        Core["Core Classes (ANNarchy/core/)"]:::pythonapi
        click Core "https://github.com/annarchy/annarchy/tree/master/ANNarchy/core/"
        Inputs["Inputs Module (ANNarchy/inputs/)"]:::pythonapi
        click Inputs "https://github.com/annarchy/annarchy/tree/master/ANNarchy/inputs/"
        Models["Models Module (ANNarchy/models/)"]:::pythonapi
        click Models "https://github.com/annarchy/annarchy/tree/master/ANNarchy/models/"
        Parser["Parser & IR (ANNarchy/parser/)"]:::codegen
        click Parser "https://github.com/annarchy/annarchy/tree/master/ANNarchy/parser/"
    end

    %% Generation Layer
    CodeGen["Code Generation Engine (ANNarchy/generator/)"]:::codegen
    click CodeGen "https://github.com/annarchy/annarchy/tree/master/ANNarchy/generator/"

    %% Binding Layer
    Cython["Cython Binding Layer (ANNarchy/cython_ext/)"]:::cython
    click Cython "https://github.com/annarchy/annarchy/tree/master/ANNarchy/cython_ext/"

    %% Execution Layer
    subgraph "Execution Layer"
        CppCore["C++ Simulation Core (ANNarchy/include/)"]:::cppcore
        click CppCore "https://github.com/annarchy/annarchy/tree/master/ANNarchy/include/"
        Runtime["Runtime Manager (ANNarchy/intern/)"]:::runtime
        click Runtime "https://github.com/annarchy/annarchy/tree/master/ANNarchy/intern/"
    end

    %% Extensions & Storage
    Ext["Extensions (ANNarchy/extensions/)"]:::extension
    click Ext "https://github.com/annarchy/annarchy/tree/master/ANNarchy/extensions/"
    Storage1["HDF5/XML Storage"]:::storage
    External1["OpenMP Runtime"]:::external
    External2["CUDA Runtime"]:::external

    %% Flows
    User -->|"import & define network"| Core
    Core -->|"definitions & equations"| Parser
    Parser -->|"AST/IR"| CodeGen
    CodeGen -->|"generate C++ & Pyx"| Cython
    Cython -->|"invoke simulation"| CppCore
    CppCore -->|"manage lifecycle"| Runtime
    CppCore -->|"simulation results"| Core
    CppCore -->|"write data"| Storage1
    CodeGen -->|"template plugins"| Ext
    CppCore -->|"parallel kernels"| External1
    CppCore -->|"GPU kernels"| External2

    %% Styles
    classDef pythonapi fill:#D6EAF8,stroke:#21618C,color:#1B4F72;
    classDef codegen fill:#FCF3CF,stroke:#B7950B,color:#7D6608;
    classDef cython fill:#E8DAEF,stroke:#884EA0,color:#512E5F;
    classDef cppcore fill:#FADBD8,stroke:#C0392B,color:#78281F;
    classDef runtime fill:#D1F2EB,stroke:#117A65,color:#0B5345;
    classDef extension fill:#EBDEF0,stroke:#7D3C98,color:#4A235A;
    classDef storage fill:#F5EEF8,stroke:#6C3483,color:#4A235A,shape:cylinder;
    classDef external fill:#F2F3F4,stroke:#566573,color:#1C2833,shape:cloud;
```
