# odd-tortoise/plocky architecture

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

- Interactive diagram: https://gitdiagram.com/odd-tortoise/plocky
- Repository: https://github.com/odd-tortoise/plocky

## Overview

##### Project type and purpose
- PlockY is a header-only C++ library (no client “frontend”). Its purpose is to load block-structured matrices and vectors from custom file formats (.blk/.vblk), decompose them according to user-defined splitting strategies, and solve the resulting linear systems iteratively.

##### File structure
- Top‐level:
- /PlockY: core headers (loader factories, block types, solver base, strategy, step, regrouper, etc.)
- examples/: consumer code showing how to load files, define strategies, run the solver
- test/: unit & integration tests (uses Catch2)
- benchmarks/: performance tests against various block sizes and data sets
- docs/: Doxygen config; CMake target to generate API docs
- data/ & benchmarks_data/: sample .blk/.vblk and CSV/MTX files to feed into the library
- CMakeLists.txt + GitHub workflows: build, test, profile on multiple platforms

##### README for additional insights
- Confirms architecture layers: File I/O, Data model, Splitting strategy, Solver
- Highlights dependencies: Eigen for numerics, Catch2 for testing, gperftools for profiling

a. Main components
1. Data Input Layer
– .blk Parser (BlockMatrixLoader + AbstractBlockLoaderFactory + CSV/MTX factory)
– .vblk Parser (BlockVectorLoader + same factory)
2. Data Model
– Block (abstract) → DenseBlock, SparseBlock, VecBlock
– BlockMatrix, BlockVector
3. Splitting Strategy Layer
– Step (one splitting operation)
– Strategy (sequence of Steps + Regrouper for block reordering)
4. Solver Layer
– Solver (or BlockSolverBase subclass)
– Iterative loop (tolerance, max iterations, relaxation factor)
5. Linear Algebra Engine
– Eigen (linked internally; all matrix operations delegate to Eigen types)
6. Support & Integration
– loader_helper (common I/O utilities)
– Logging/Profiling hooks (gperftools integration)
7. Build & Test Infrastructure
– CMake
– CI workflows (.github/workflows)
– Tests (Catch2)
– Examples & Benchmarks

b. Relationships and interactions
- Data files → parsed by Loader → instantiated as BlockMatrix/BlockVector
- BlockMatrix/BlockVector → passed to Strategy to generate an ordered sequence of Steps
- Strategy + Data Model → feed into Solver
- Solver ↔ Eigen (matrix‐vector operations)
- Regrouper can reorder Data Model between Steps
- Tests/examples/benchmarks invoke Loader → Strategy → Solver
- CMake orchestrates build/test/doc generation; CI automates builds on push

c. Architectural patterns/design principles
- Factory Method (AbstractBlockLoaderFactory → CSV | MTX)
- Strategy Pattern (Strategy + Steps encapsulate algorithm choices)
- Header‐only modularity (single‐header inclusion)
- Separation of concerns: I/O vs. data model vs. algorithm vs. build/test

d. Relevant technologies/frameworks
- Eigen (linear algebra)
- Catch2 (unit/integration tests)
- gperftools (profiling)
- CMake (build system)
- GitHub Actions (CI)
- Doxygen (docs)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources
    subgraph "Data Sources" 
        direction TB
        DS[".blk/.vblk, CSV/MTX Files"]:::dataSources
    end

    %% Data Input Layer
    subgraph "Data Input Layer"
        direction TB
        AbstractFactory["AbstractBlockLoaderFactory"]:::factory
        CSVFactory["CSVBlockLoaderFactory"]:::factory
        MTXFactory["MTXBlockLoaderFactory"]:::factory
        loaderHelper["loader_helper"]:::factory
        blkParser[".blk Parser\nBlockMatrixLoader"]:::factory
        vblkParser[".vblk Parser\nBlockVectorLoader"]:::factory
    end

    %% Data Model Layer
    subgraph "Data Model"
        direction TB
        Block["Block (abstract)"]:::core
        DenseBlock["DenseBlock"]:::core
        SparseBlock["SparseBlock"]:::core
        VecBlock["VecBlock"]:::core
        BlockMatrix["BlockMatrix"]:::core
        BlockVector["BlockVector"]:::core
    end

    %% Splitting Strategy Layer
    subgraph "Splitting Strategy"
        direction TB
        Step["Step"]:::core
        Strategy["Strategy"]:::core
        Regrouper["Regrouper"]:::core
    end

    %% Solver Layer
    subgraph "Solver Layer"
        direction TB
        SolverBase["BlockSolverBase"]:::core
        SolverImpl["Solver"]:::core
        IterLoop["Iterative Loop\n(for iter=1..max_iters)"]:::core
    end

    %% Linear Algebra Engine
    Eigen["Eigen"]:::external

    %% Support & Integration
    Profiling["gperftools Profiling Hooks"]:::external

    %% Build & CI Infrastructure
    subgraph "Build & CI Infrastructure" 
        direction TB
        CMake["CMake"]:::infra
        CI["GitHub Actions CI"]:::infra
        Tests["Catch2 Tests"]:::external
        Examples["Examples"]:::external
        Benchmarks["Benchmarks"]:::external
    end

    %% Data Flow
    DS --> blkParser
    DS --> vblkParser
    AbstractFactory --> blkParser
    AbstractFactory --> vblkParser
    CSVFactory --> blkParser
    CSVFactory --> vblkParser
    MTXFactory --> blkParser
    MTXFactory --> vblkParser
    loaderHelper --> blkParser
    loaderHelper --> vblkParser

    blkParser --> BlockMatrix
    vblkParser --> BlockVector

    Block --> DenseBlock
    Block --> SparseBlock
    Block --> VecBlock

    BlockMatrix --> Strategy
    BlockVector --> Strategy

    Strategy --> Step
    Strategy --> Regrouper
    Step --> Regrouper
    Strategy --> SolverImpl

    SolverImpl --> IterLoop
    IterLoop --> SolverImpl
    SolverImpl --> Eigen
    Eigen --> SolverImpl

    Examples --> blkParser
    Examples --> Strategy
    Examples --> SolverImpl

    Tests --> blkParser
    Tests --> Strategy
    Tests --> SolverImpl

    Benchmarks --> blkParser
    Benchmarks --> Strategy
    Benchmarks --> SolverImpl

    CMake --> Tests
    CMake --> Examples
    CMake --> Benchmarks
    CI --> CMake

    Profiling --> SolverImpl

    %% Click Events
    click blkParser "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/BlockMatrixLoader.hpp"
    click vblkParser "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/BlockVectorLoader.hpp"
    click AbstractFactory "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/AbstractBlockLoaderFactory.hpp"
    click CSVFactory "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/CSVBlockLoaderFactory.hpp"
    click MTXFactory "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/MTXBlockLoaderFactory.hpp"
    click loaderHelper "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/loader_helper.hpp"
    click Block "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/Block.hpp"
    click DenseBlock "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/DenseBlock.hpp"
    click SparseBlock "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/SparseBlock.hpp"
    click VecBlock "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/VecBlock.hpp"
    click BlockMatrix "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/BlockMatrix.hpp"
    click BlockVector "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/BlockVector.hpp"
    click Step "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/Step.hpp"
    click Strategy "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/Strategy.hpp"
    click Regrouper "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/Regrouper.hpp"
    click SolverBase "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/BlockSolverBase.hpp"
    click SolverImpl "https://github.com/odd-tortoise/plocky/blob/main/include/PlockY/Solver.hpp"
    click Examples "https://github.com/odd-tortoise/plocky/tree/main/examples/"
    click Tests "https://github.com/odd-tortoise/plocky/tree/main/test/"
    click Benchmarks "https://github.com/odd-tortoise/plocky/tree/main/benchmarks/"
    click CMake "https://github.com/odd-tortoise/plocky/blob/main/CMakeLists.txt"
    click CI "https://github.com/odd-tortoise/plocky/tree/main/.github/workflows/"

    %% Styles
    classDef dataSources fill:#cfc,stroke:#080;
    classDef core fill:#ccf,stroke:#036;
    classDef factory fill:#fc9,stroke:#952;
    classDef external fill:#dcb,stroke:#640,stroke-dasharray: 5 5;
    classDef infra fill:#eee,stroke:#666,stroke-dasharray: 2 2;
```
