How neuralnetworkverification/marabou works
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.