# devcompsy/cpm architecture

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

- Interactive diagram: https://gitdiagram.com/devcompsy/cpm
- Repository: https://github.com/devcompsy/cpm

## Overview

##### Project type and purpose
- This is a Python-only library (“cpm”) for Computational Psychiatry research.
- It provides data generators, models, optimisers, diagnostics, export tools and ready-to-run applications (e.g., reinforcement learning tasks).
- No front-end or web server; it’s a scientific toolkit packaged for PyPI, with docs generated via mkdocs and CI/tests driven by pytest.

##### File structure
- Top-level module: `cpm/`
- `cpm/core/` Orchestrates data flow, diagnostics, exports, parallel execution.
- `cpm/datasets/` Data loaders & CSV fixtures.
- `cpm/generators/` Simulators & parameter sets.
- `cpm/models/` Activation functions, decision rules, learning updates.
- `cpm/hierarchical/` Empirical and variational inference layers.
- `cpm/optimisation/` Algorithm implementations (BADS, fmin, genetic, free energy, etc.).
- `cpm/applications/` Higher-level scripts (e.g., reinforcement_learning.py) that tie everything together.
- `cpm/utils/` General helper functions.
- Other parts:
- `docs/` mkdocs source for documentation & tutorials.
- `test/` pytest suite mirroring module structure.
- Packaging/config: `setup.py`, `setup.cfg`, `LICENSE`, `mkdocs.yml`, `CHANGELOG.md`.

##### README for additional insights
- Confirms scientific focus, beta status, install from GitHub, docs with mkdocs, testing with pytest, packaging and publishing steps.

##### Elements
- Blue for core computational layers (models, optimisers).
- Green for data/generators.
- Orange for orchestration & applications.
- Gray for documentation, testing, and deployment.

##### Final advice
- **build & release** pipeline: doc build (mkdocs → GitHub Pages), test (pytest), packaging (setup.py → twine → PyPI).

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Data & Generation Layers
    subgraph "Data & Generation" 
        direction TB
        DL["Data Layer\n(cpm/datasets/)"]:::datagen
        GL["Simulation/Generation Layer\n(cpm/generators/)"]:::datagen
    end

    %% Core Computational Layers
    subgraph "Core Computational" 
        direction TB
        ML["Model Layer\n(cpm/models/)"]:::compute
        OL["Optimisation Engine\n(cpm/optimisation/)"]:::compute
        HL["Hierarchical Inference Layer\n(cpm/hierarchical/)"]:::compute
    end

    %% Orchestration & Entry Points
    CO["Core Orchestrator\n(cpm/core/)"]:::orchestrator
    APP["Applications\n(reinforcement_learning.py)"]:::orchestrator

    %% Support Layers
    UT["Utilities & Helpers\n(cpm/utils/utils.py)"]:::support
    LE["Library Entry Point\n(cpm/cpm.py)"]:::support
    DD["Documentation & Deployment\n(docs/, mkdocs.yml, setup.py, etc)"]:::support
    TH["Test Harness\n(test/)"]:::support

    %% Data flow and interactions
    DL -->|"load_data()"| GL
    GL -->|"simulate()"| ML
    ML -->|"fit()"| OL
    OL -->|"update()"| ML
    ML -->|"infer_group()"| HL
    OL -->|"infer_group()"| HL

    %% Workflow orchestration
    GL -->|"submit_task()"| CO
    ML -->|"submit_task()"| CO
    OL -->|"submit_task()"| CO
    HL -->|"submit_task()"| CO
    APP -->|"invoke()"| CO
    CO -->|"export_csv()/export_fig()"| DD

    %% Utility usage
    CO -->|"uses"| UT
    APP -->|"uses"| UT
    CO -->|"entry()"| LE

    %% Testing pipeline
    TH -.-> DL
    TH -.-> GL
    TH -.-> ML
    TH -.-> OL
    TH -.-> HL
    TH -.-> CO
    TH -.-> APP
    TH -.-> UT

    %% Click Events
    click DL "https://github.com/devcompsy/cpm/tree/main/cpm/datasets/"
    click GL "https://github.com/devcompsy/cpm/tree/main/cpm/generators/"
    click ML "https://github.com/devcompsy/cpm/tree/main/cpm/models/"
    click OL "https://github.com/devcompsy/cpm/tree/main/cpm/optimisation/"
    click HL "https://github.com/devcompsy/cpm/tree/main/cpm/hierarchical/"
    click CO "https://github.com/devcompsy/cpm/tree/main/cpm/core/"
    click APP "https://github.com/devcompsy/cpm/blob/main/cpm/applications/reinforcement_learning.py"
    click UT "https://github.com/devcompsy/cpm/blob/main/cpm/utils/utils.py"
    click LE "https://github.com/devcompsy/cpm/blob/main/cpm/cpm.py"
    click DD "https://github.com/devcompsy/cpm/tree/main/docs/"
    click TH "https://github.com/devcompsy/cpm/tree/main/test/"

    %% Styles
    classDef datagen fill:#e0f7e9,stroke:#2d6a4f,color:#1b4332;
    classDef compute fill:#e0f3ff,stroke:#1b4f72,color:#1d3557;
    classDef orchestrator fill:#fff4e6,stroke:#d97706,color:#9c4221;
    classDef support fill:#f0f0f0,stroke:#666666,color:#333333;
    class DL,GL datagen
    class ML,OL,HL compute
    class CO,APP orchestrator
    class UT,LE,DD,TH support
```
