# kvernet/cml architecture

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

- Interactive diagram: https://gitdiagram.com/kvernet/cml
- Repository: https://github.com/kvernet/cml

## Overview

##### Main Components and Their Roles
a. Core Library Modules:
- cml_matrix: Implements matrix operations (allocation, inversion, multiplication, etc.), as seen in both src/cml_matrix.c and examples/matrix.
- cml_layer & cml_activation: Handle neural network layers and activations (ReLU, Sigmoid, Softmax, etc.) – with corresponding code in src/cml_layer.c, include/cml_activation.h, and examples/layer.
- cml_loss: Manages loss functions (MSE, Softmax Cross-Entropy) used during training.
- cml_optimizer: Contains the gradient descent algorithm (with plans for additional optimizers like ADAM).
- cml_data: Responsible for dataset management and possibly preprocessing (as indicated by the presence of various datasets in the data directory).
- cml_algorithm & cml_sequential: Likely coordinates the overall network training process, structuring the sequential model.
- cml_prng: Provides pseudo-random number generation for operations such as weight initialization (with supporting examples in the prng directory).

b. Examples & Scripts:
- The examples directory contains runnable C files for demonstrating specific functionalities:
- “layer”: Example implementations of different layers/activations.
- “matrix”: Demonstrates matrix-related computations.
- “sequential”: Provides end-to-end examples for training on different datasets.
- “prng”: Contains tests for randomness functions.
- The scripts directory holds Python wrappers or test scripts that parallel the C examples, which can be used to compare the CML library’s results with TensorFlow.

c. Data Directories:
- The “data” folder stores datasets required for training and testing the library (Iris, Heart Disease, Wine Quality, Lattice-Physics, etc.).
- The “examples/data” folder may include auxiliary data or demonstration-specific datasets.

##### Relationships and Interactions
- The core library functions (in src and include directories) are used by the example applications.
- For a typical neural network run, data flows from the Data module (cml_data) into the Sequential model (cml_sequential) that uses Layers (cml_layer), Activations (cml_activation), and Matrix Operations (cml_matrix) to perform feed-forward computations.
- The Optimizer (cml_optimizer) and Loss functions (cml_loss) compute error gradients and update weights accordingly.
- The PRNG module helps initialize the parameters in a reproducible (or at least statistically sound) fashion.
- Python scripts (in the scripts directory) interface with the underlying functionalities to compare results, likely orchestrating data preprocessing or comparing performance against TensorFlow.

##### Architectural Patterns & Technologies
- The project follows a modular design where each mathematical or logical concern (matrix ops, activations, optimizers, etc.) is isolated into its own module.
- It uses a “sequential” architecture that mirrors many deep learning frameworks, where layers are stacked sequentially.
- A Makefile is used for building both the core library and the examples, indicating a compile-time configured build process.
- The structure supports separation of core library functionality (in src and include) from experimental/demonstrative use cases (in examples and scripts).

## Diagram (Mermaid)

```mermaid
flowchart TD

    %% Data Management
    subgraph "Data Management"
        D1["cml_data"]:::core
        D2["Datasets"]:::data
    end

    %% Core Computation Engine
    subgraph "Core Computation Engine"
        M1["cml_matrix"]:::core
        L1["cml_layer"]:::core
        A1["cml_activation"]:::core
        Alg["cml_algorithm"]:::core
    end

    %% Loss & Optimization
    subgraph "Loss & Optimization"
        Loss["cml_loss"]:::loss
        Opt["cml_optimizer"]:::loss
        PRNG["cml_prng"]:::loss
    end

    %% Model Orchestration
    subgraph "Model Orchestration"
        Seq["cml_sequential"]:::orchestrate
    end

    %% Examples & Companion Scripts
    subgraph "Examples & Scripts"
        Ex_Layer["Example: Layer"]:::example
        Ex_Matrix["Example: Matrix"]:::example
        Ex_Sequential["Example: Sequential"]:::example
        Ex_PRNG["Example: PRNG"]:::example
        Py_Scripts["Python Scripts"]:::example
    end

    %% Relationships & Data Flow
    D1 -->|"InputData"| Seq
    D2 -->|"ProvidesData"| D1

    M1 -->|"Operations"| Alg
    L1 -->|"AppliesActivation"| A1
    L1 -->|"FeedsData"| Alg
    A1 -->|"Transforms"| Alg

    Alg -->|"Coordinates"| Seq

    Seq -->|"LossCalc"| Loss
    Loss -->|"ErrorSignal"| Opt
    Opt -->|"UpdatesWeights"| Seq

    PRNG -->|"InitWeights"| L1

    %% Examples demonstrating modules
    Ex_Matrix -->|"Demonstrates"| M1
    Ex_Layer -->|"Demonstrates"| L1
    Ex_Layer -->|"Demonstrates"| A1
    Ex_Sequential -->|"Demonstrates"| Seq
    Ex_PRNG -->|"Demonstrates"| PRNG
    Py_Scripts -->|"InterfacesWith"| Seq

    %% Click Events
    click M1 "https://github.com/kvernet/cml/blob/main/src/cml_matrix.c"
    click Ex_Matrix "https://github.com/kvernet/cml/tree/main/examples/matrix/"
    click L1 "https://github.com/kvernet/cml/blob/main/src/cml_layer.c"
    click A1 "https://github.com/kvernet/cml/blob/main/include/cml_activation.h"
    click Ex_Layer "https://github.com/kvernet/cml/tree/main/examples/layer/"
    click Loss "https://github.com/kvernet/cml/blob/main/src/cml_loss.c"
    click Opt "https://github.com/kvernet/cml/blob/main/src/cml_optimizer.c"
    click D1 "https://github.com/kvernet/cml/blob/main/src/cml_data.c"
    click Seq "https://github.com/kvernet/cml/blob/main/src/cml_sequential.c"
    click Alg "https://github.com/kvernet/cml/blob/main/src/cml_algorithm.c"
    click PRNG "https://github.com/kvernet/cml/blob/main/src/cml_prng.c"
    click Ex_Sequential "https://github.com/kvernet/cml/tree/main/examples/sequential/"
    click Ex_PRNG "https://github.com/kvernet/cml/tree/main/examples/prng/"
    click Py_Scripts "https://github.com/kvernet/cml/tree/main/scripts/"

    %% Styles
    classDef core fill:#a2d2ff,stroke:#084298,stroke-width:2px;
    classDef data fill:#ffd6a5,stroke:#ff7f00,stroke-width:2px;
    classDef loss fill:#ffadad,stroke:#ff0000,stroke-width:2px;
    classDef orchestrate fill:#caffbf,stroke:#008000,stroke-width:2px;
    classDef example fill:#fdffb6,stroke:#e9d8a6,stroke-width:2px;
```
