# neuralnetworkverification/marabou architecture

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

- Interactive diagram: https://gitdiagram.com/neuralnetworkverification/marabou
- Repository: https://github.com/neuralnetworkverification/marabou

## Overview

##### Project type and purpose
- Marabou is a research-grade, open-source SMT-based verification tool for deep neural networks.
- It ships as a C++ command-line executable (`Marabou`) and as a Python package (`maraboupy`).
- Its core function: load a network + property, encode it as an SMT/LP query, solve it (returning SAT/UNSAT or a counterexample), optionally generate proofs/certificates.

##### File structure
- Top-level directories:
– `src/`: C++ modules broken into sub-packages (input_parsers, engine, nlr, proofs, cegar, basis_factorization, configuration, common, query_loader, system_tests, etc.).
– `maraboupy/`: Python bindings built on top of the C++ core (pybind11). Contains API modules, examples, docs, tests.
– `resources/`: sample networks (`.nnet`, ONNX) and properties (VNNLIB, text), plus guides (SplitAndConquer Jupyter notebook).
– `regress/`: regression test descriptions.
– `deps/`: vendored CVC4 SMT solver.
– `tools/`: build/test utilities (CXXTEST, download scripts).
- Build system: CMake at top level and in each `src/*` and `tools/*`.
- Config files: `pyproject.toml`, `setup.py`, CI workflows, pre-commit, linters, test definitions.

##### README for additional insights
- Architecture: layered (parsing → query building → solving → output/proofs).
- Technical stack: C++17, CMake, Boost, OpenBLAS, pybind11, CVC4 (optional Gurobi), ONNX parser.
- Usage modes: CLI with SNC (Split-and-Conquer) or Python API, multi-threading, optional Gurobi LP solver.

##### Main components and their relationships
A. Entry points
- CLI `Marabou` (C++ `main.cpp`)
- Python API (`maraboupy/__init__.py`, `Marabou.py`, `MarabouMain.py`)
B. Configuration manager
- `src/configuration/OptionParser` & `GlobalConfiguration` → parses CLI flags or Python arguments, holds solver settings.
C. Input parsing & query loading
- `src/input_parsers/*` → ONNX, .nnet, MPS, VNNLIB, generic `InputQueryBuilder`.
- `src/query_loader/QueryLoader` → wraps parsers, constructs `InputQuery` objects.
D. Core engine
- `src/engine` → SMT/LP encoding: constraint classes (ReLU, Sigmoid, Max, etc.), `Engine` orchestrator, search strategies (DNC, DeepPoly, CEGAR), case split manager.
- `src/basis_factorization` & `src/common/GurobiWrapper` → linear solver backend (native simplex or Gurobi).
- `src/nlr` (Network Level Reasoner) → DeepPoly bound tightening modules.
- `src/cegar` (Counterexample-guided abstraction refinement) → incremental linearization.
- `deps/CVC4/` → optional SMT backend.
E. Proof/certificate generation
- `src/proofs` → unsat certificate writer (JSON, SMT-LIB).
F. Output & user interface
- CLI stdout/stderr, exit codes, Python return objects (solutions, counterexamples).
- Optional Jupyter notebook integration.
G. Testing frameworks
- `tools/cxxtest` → C++ unit tests.
- `src/*/tests` & `src/system_tests` → unit/system tests.
- `regress/` → regression tests.
- `maraboupy/test` → Python tests.

##### Architectural patterns and design principles
- Layered/pipeline architecture (parse → build query → solve → output).
- Strategy pattern for solver components (bound tightening, case splitting, cost functions).
- Factory pattern in `src/engine/T` and other `T/*Factory` modules for pluggable implementations.
- Separation of concerns: input, core solver, LP backend, configuration, binding layer.
- Extensibility via new parser or new constraint type: drop into `input_parsers` or `engine`.

##### Details to capture
- Module names exactly as on disk (e.g., `src/engine/Engine.cpp`) for clarity.
- Factories (`ConstraintMatrixAnalyzerFactory`, `ProjectedSteepestEdgeFactory`) to show plugin pattern.
- The test harness separate from the production pipeline.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% User Entry
    User["User"]:::user

    %% Frontend Layer
    subgraph "Frontend Layer"
        direction TB
        CLI["Marabou CLI"]:::cppcore
        PYAPI["Python API"]:::python
    end

    %% Configuration Manager
    Config["Configuration Manager"]:::cppcore

    %% Input Layer
    subgraph "Input Parsers & Query Loader"
        direction TB
        Parsers["Input Parsers"]:::cppcore
        Loader["Query Loader"]:::cppcore
    end

    %% Core Engine
    subgraph "Core Engine"
        direction TB
        EngineCore["Engine Orchestrator"]:::cppcore
        subgraph "Constraint Modules"
            direction TB
            CM["Factories & Constraints"]:::cppcore
        end
        subgraph "Search Manager"
            direction TB
            DnC["DNC Manager"]:::cppcore
            Sim["Simulator"]:::cppcore
        end
        subgraph "LP Solver Interface & Basis Factorization"
            direction TB
            Gurobi["Gurobi Wrapper"]:::cppcore
            Basis["BasisFactorizationFactory"]:::cppcore
        end
        subgraph "NLR"
            direction TB
            NLR["Network Level Reasoner"]:::cppcore
        end
        subgraph "CEGAR"
            direction TB
            CEGAR["Incremental Linearization"]:::cppcore
        end
    end

    %% Proof Generation
    Proof["Proof/Certificate Generator"]:::cppcore

    %% External Solvers & Resources
    subgraph "External & Resources"
        direction TB
        ExtSolvers["External Solvers"]:::external
        Resources["Resource Store"]:::data
    end

    %% Tests & Build
    subgraph "Testing & Build"
        direction TB
        TestsCpp["C++ Tests"]:::tests
        TestsPy["Python Tests"]:::tests
        Regr["Regression Tests"]:::tests
        Build["Build Config"]:::build
    end

    %% Data Flow
    User -->|"invoke"| CLI
    User -->|"import"| PYAPI
    PYAPI -->|"pybind11 binding"| CLI
    CLI -->|"flags"| Config
    PYAPI -->|"args"| Config
    Config -->|"settings"| Parsers
    Parsers -->|"parsed network & property"| Loader
    Loader -->|"InputQuery"| EngineCore
    EngineCore -->|"bounds & constraints"| CM
    CM -->|"decision points"| DnC
    DnC -->|"subproblems"| Sim
    EngineCore -->|"linear system"| Basis
    Basis -->|"matrix solve"| Gurobi
    EngineCore -->|"bounds tightening"| NLR
    EngineCore -->|"abstraction refinement"| CEGAR
    EngineCore -->|"SAT/UNSAT result"| Proof
    Proof -->|"certificate"| CLI
    Proof -->|"certificate"| PYAPI
    Gurobi -->|"LP solve"| EngineCore
    ExtSolvers -->|"SMT queries"| EngineCore
    Resources -->|"sample files"| Parsers
    TestsCpp -->|"unit & system tests"| EngineCore
    TestsPy -->|"Python tests"| PYAPI
    Regr -->|"regression inputs"| Loader
    Build -->|"CMake & pyproject"| CLI
    Build -->|"CMake & pyproject"| PYAPI

    %% Click Events
    click CLI "https://github.com/neuralnetworkverification/marabou/blob/master/src/engine/main.cpp"
    click PYAPI "https://github.com/neuralnetworkverification/marabou/blob/master/maraboupy/__init__.py"
    click PYAPI "https://github.com/neuralnetworkverification/marabou/blob/master/maraboupy/Marabou.py"
    click PYAPI "https://github.com/neuralnetworkverification/marabou/blob/master/maraboupy/MarabouMain.py"
    click Config "https://github.com/neuralnetworkverification/marabou/blob/master/src/configuration/OptionParser.cpp"
    click Config "https://github.com/neuralnetworkverification/marabou/blob/master/src/configuration/OptionParser.h"
    click Config "https://github.com/neuralnetworkverification/marabou/blob/master/src/configuration/GlobalConfiguration.cpp"
    click Config "https://github.com/neuralnetworkverification/marabou/blob/master/src/configuration/GlobalConfiguration.h"
    click Parsers "https://github.com/neuralnetworkverification/marabou/tree/master/src/input_parsers/"
    click Loader "https://github.com/neuralnetworkverification/marabou/blob/master/src/query_loader/QueryLoader.cpp"
    click Loader "https://github.com/neuralnetworkverification/marabou/blob/master/src/query_loader/QueryLoader.h"
    click EngineCore "https://github.com/neuralnetworkverification/marabou/blob/master/src/engine/Engine.cpp"
    click EngineCore "https://github.com/neuralnetworkverification/marabou/blob/master/src/engine/Engine.h"
    click EngineCore "https://github.com/neuralnetworkverification/marabou/blob/master/src/engine/Marabou.cpp"
    click EngineCore "https://github.com/neuralnetworkverification/marabou/blob/master/src/engine/Marabou.h"
    click CM "https://github.com/neuralnetworkverification/marabou/tree/master/src/engine/T/"
    click DnC "https://github.com/neuralnetworkverification/marabou/blob/master/src/engine/DnCManager.cpp"
    click DnC "https://github.com/neuralnetworkverification/marabou/blob/master/src/engine/DnCManager.h"
    click Sim "https://github.com/neuralnetworkverification/marabou/blob/master/src/engine/Simulator.cpp"
    click Sim "https://github.com/neuralnetworkverification/marabou/blob/master/src/engine/Simulator.h"
    click Gurobi "https://github.com/neuralnetworkverification/marabou/blob/master/src/common/GurobiWrapper.cpp"
    click Gurobi "https://github.com/neuralnetworkverification/marabou/blob/master/src/common/GurobiWrapper.h"
    click Basis "https://github.com/neuralnetworkverification/marabou/tree/master/src/basis_factorization/"
    click NLR "https://github.com/neuralnetworkverification/marabou/blob/master/src/nlr/NetworkLevelReasoner.cpp"
    click NLR "https://github.com/neuralnetworkverification/marabou/blob/master/src/nlr/NetworkLevelReasoner.h"
    click NLR "https://github.com/neuralnetworkverification/marabou/blob/master/src/nlr/DeepPolyAnalysis.cpp"
    click NLR "https://github.com/neuralnetworkverification/marabou/blob/master/src/nlr/DeepPolyAnalysis.h"
    click CEGAR "https://github.com/neuralnetworkverification/marabou/blob/master/src/cegar/IncrementalLinearization.cpp"
    click CEGAR "https://github.com/neuralnetworkverification/marabou/blob/master/src/cegar/IncrementalLinearization.h"
    click Proof "https://github.com/neuralnetworkverification/marabou/blob/master/src/proofs/JsonWriter.cpp"
    click Proof "https://github.com/neuralnetworkverification/marabou/blob/master/src/proofs/JsonWriter.h"
    click Proof "https://github.com/neuralnetworkverification/marabou/blob/master/src/proofs/SmtLibWriter.cpp"
    click Proof "https://github.com/neuralnetworkverification/marabou/blob/master/src/proofs/SmtLibWriter.h"
    click ExtSolvers "https://github.com/neuralnetworkverification/marabou/tree/master/deps/CVC4/"
    click Resources "https://github.com/neuralnetworkverification/marabou/tree/master/resources/nnet/"
    click Resources "https://github.com/neuralnetworkverification/marabou/tree/master/resources/onnx/"
    click Resources "https://github.com/neuralnetworkverification/marabou/tree/master/resources/properties/"
    click Regr "https://github.com/neuralnetworkverification/marabou/tree/master/regress/"
    click TestsCpp "https://github.com/neuralnetworkverification/marabou/tree/master/tools/cxxtest/"
    click TestsCpp "https://github.com/neuralnetworkverification/marabou/tree/master/src/*/tests/"
    click TestsCpp "https://github.com/neuralnetworkverification/marabou/tree/master/src/system_tests/"
    click TestsPy "https://github.com/neuralnetworkverification/marabou/tree/master/maraboupy/test/"
    click Build "https://github.com/neuralnetworkverification/marabou/blob/master/CMakeLists.txt"
    click Build "https://github.com/neuralnetworkverification/marabou/blob/master/src/CMakeLists.txt"
    click Build "https://github.com/neuralnetworkverification/marabou/blob/master/pyproject.toml"
    click Build "https://github.com/neuralnetworkverification/marabou/blob/master/setup.py"

    %% Styles
    classDef cppcore fill:#E0F7FA,stroke:#0288D1,color:#000
    classDef python fill:#FFF3E0,stroke:#FB8C00,color:#000
    classDef external fill:#E8F5E9,stroke:#2E7D32,color:#000
    classDef data fill:#F3E5F5,stroke:#8E24AA,color:#000
    classDef tests fill:#FCE4EC,stroke:#C2185B,color:#000
    classDef build fill:#ECEFF1,stroke:#546E7A,color:#000
    classDef user fill:#FFFFFF,stroke:#000000,color:#000000,stroke-width:2px
```
