# neoml-lib/neoml architecture

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

- Interactive diagram: https://gitdiagram.com/neoml-lib/neoml
- Repository: https://github.com/neoml-lib/neoml

## Overview

##### Project Type and Purpose
- NeoML is an open-source ML framework (not a web or mobile app).
- Purpose: provide a C++-based algorithms library (NeoML), a separate math-engine module (NeoMathEngine), language wrappers (Python, Java/Kotlin, Objective-C/Swift), ONNX import support, and sample/test applications.
- Key use cases: training and inference of neural networks and traditional ML algorithms across CPU/GPU and multiple platforms (Windows, Linux, macOS, iOS, Android).

##### High-Level File Structure
- Top-level modules/directories:
- Build/ & CMake scripts – build orchestration
- NeoML/ – core algorithms (C++, wrappers, docs, samples, tests)
- NeoMathEngine/ – low-level compute backends (CPU, CUDA, Vulkan, Metal)
- NeoOnnx/ – ONNX importer
- NeoProxy/ – a lightweight proxy layer
- Samples (Python, Kotlin, Swift) and Test suites (unit tests, desktop/mobile)
- Notice layering: algorithms library → math-engine backends → language bindings → client/sample apps.

##### README Insights
- Two main C++ libraries: “NeoML” (algorithms) and “NeoMathEngine” (compute).
- Multiple build profiles: full C++ (training + inference) vs. inference only (Java/ObjC).
- External dependencies: CMake, Intel MKL, CUDA, Vulkan, Google Test, Protocol Buffers, xbyak.

##### Main Components
a. NeoML Algorithms Library
– Neural networks (100+ layer types)
– Traditional ML (20+ algorithms)
– ONNX importer (NeoOnnx)
b. NeoMathEngine Backends
– CPU (plain C++, MKL)
– GPU: CUDA, Vulkan, Metal
– Plugin/strategy pattern for engine selection
c. Language Bindings
– Python wrapper (SWIG/C++ extension via setup.py)
– Java/Kotlin JNI inference API
– Objective-C/Swift inference API
d. Build & Packaging
– CMake scripts, build pipelines (Azure DevOps & shell/cmd scripts)
– Output artifacts: libNeoML, libNeoMathEngine, Python wheel, JAR, frameworks
e. Client/Sample Applications
– Python scripts (tutorials)
– Android (Java/Kotlin) demo
– iOS (Swift/ObjC) demo
– Desktop “full test” app
f. External Services/Dependencies
– Intel MKL, CUDA runtime, Vulkan SDK, Protocol Buffers, xbyak JIT

##### Relationships & Data Flows
- Algorithms Library invokes MathEngine through a common interface.
- At runtime the application selects a MathEngine implementation (CPU or GPU).
- Language bindings call into the C++ libraries via JNI or C-API.
- ONNX importer feeds a graph into the NeoML library before executing with a MathEngine.
- Build system coordinates compilation of all components and links external libraries.

##### Architectural Patterns & Principles
- Layering: Presentation (samples/bindings) → Business logic (NeoML) → Compute (NeoMathEngine)
- Plugin/Strategy for math engines
- Separation of interface vs. implementation for cross-platform portability
- Bridge pattern in language bindings (C++ core bridged to Python, Java, ObjC)

- Components: NeoML core, NeoMathEngine variants, NeoOnnx, NeoProxy, Language wrappers, Samples
- Build orchestration: CMake & scripts → artifacts (shared/static libs, wheels, JARs, frameworks)
- External libraries/services

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Core Libraries
    subgraph "Core Library"
        NeoML["NeoML Algorithms Library"]:::core
        Traditional["Traditional ML Algorithms"]:::core
        NeoOnnx["ONNX Importer (NeoOnnx)"]:::core
    end

    %% Compute Engines
    subgraph "Compute Engines"
        CPU["CPU Backend"]:::backend
        CUDA["CUDA Backend"]:::backend
        Vulkan["Vulkan Backend"]:::backend
        Metal["Metal Backend"]:::backend
    end

    %% Proxy Layer
    subgraph "Proxy Layer"
        Proxy["NeoProxy Layer"]:::core
    end

    %% Language Bindings
    subgraph "Language Bindings"
        Python["Python Binding"]:::binding
        Java["Java/Kotlin JNI"]:::binding
        ObjC["Objective-C/Swift API"]:::binding
    end

    %% Sample/Client Applications
    subgraph "Sample/Client Apps"
        PySample["Python Samples"]:::client
        Android["Android Demo"]:::client
        iOS["iOS Demo"]:::client
        DesktopApp["Desktop Test App"]:::client
    end

    %% Build & Packaging
    Build["Build & Packaging"]:::build

    %% External Dependencies
    MKL["Intel MKL"]:::external
    CUDA_RUN["CUDA Runtime"]:::external
    VULKAN_SDK["Vulkan SDK"]:::external
    PROTO["Protocol Buffers"]:::external
    XBYAK["xbyak JIT"]:::external

    %% Relationships
    NeoOnnx -->|"imports graph into"| NeoML
    NeoML -->|"uses API"| CPU
    NeoML -->|"uses API"| CUDA
    NeoML -->|"uses API"| Vulkan
    NeoML -->|"uses API"| Metal
    Proxy -->|"forwards calls"| NeoML
    Python -->|"SWIG/C API"| NeoML
    Java -->|"JNI"| NeoML
    ObjC -->|"C++ Bridge"| NeoML
    Python -->|"runtime"| CPU
    Java -->|"runtime"| CPU
    ObjC -->|"runtime"| CPU
    PySample -->|"uses"| Python
    Android -->|"uses"| Java
    iOS -->|"uses"| ObjC
    DesktopApp -->|"links"| NeoML
    DesktopApp -->|"links"| CPU
    Build -->|"compiles"| NeoML
    Build -->|"compiles"| NeoMathEngine
    Build -->|"packages"| Python
    Build -->|"packages"| Java
    Build -->|"packages"| ObjC
    Build -->|"build scripts"| MKL
    Build -->|"build scripts"| CUDA_RUN
    Build -->|"build scripts"| VULKAN_SDK
    Build -->|"build scripts"| PROTO
    Build -->|"build scripts"| XBYAK

    %% Click Events
    click NeoML "https://github.com/neoml-lib/neoml/tree/master/NeoML/src"
    click Traditional "https://github.com/neoml-lib/neoml/tree/master/NeoML/src/TraditionalML"
    click NeoOnnx "https://github.com/neoml-lib/neoml/tree/master/NeoOnnx/src"
    click CPU "https://github.com/neoml-lib/neoml/tree/master/NeoMathEngine/src/CPU"
    click CUDA "https://github.com/neoml-lib/neoml/tree/master/NeoMathEngine/src/GPU/CUDA"
    click Vulkan "https://github.com/neoml-lib/neoml/tree/master/NeoMathEngine/src/GPU/Vulkan"
    click Metal "https://github.com/neoml-lib/neoml/tree/master/NeoMathEngine/src/GPU/Metal"
    click Proxy "https://github.com/neoml-lib/neoml/tree/master/NeoProxy/src"
    click Python "https://github.com/neoml-lib/neoml/tree/master/NeoML/Python/neoml"
    click Java "https://github.com/neoml-lib/neoml/tree/master/NeoML/Java/inference"
    click ObjC "https://github.com/neoml-lib/neoml/blob/master/NeoML/objc/NeoInference.mm"
    click Build "https://github.com/neoml-lib/neoml/blob/master/Build/build.sh"

    %% Styles
    classDef core fill:#f9f,stroke:#333,stroke-width:1px;
    classDef backend fill:#bbf,stroke:#333,stroke-width:1px;
    classDef binding fill:#bfb,stroke:#333,stroke-width:1px;
    classDef client fill:#ffb,stroke:#333,stroke-width:1px;
    classDef build fill:#fbf,stroke:#333,stroke-width:1px;
    classDef external fill:#def,stroke:#333,stroke-width:1px;
```
