# scipopt/russcip architecture

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

- Interactive diagram: https://gitdiagram.com/scipopt/russcip
- Repository: https://github.com/scipopt/russcip

## Overview

##### Project type and purpose
- This is a Rust library crate (“russcip”) providing a safe, high-level interface on top of the SCIP C solver. It is not a full-stack app or microservice but an SDK/FFI wrapper with extensibility points (plugin traits).

##### File structure
- Top-level:
- Cargo.toml, README.md, INSTALL.md, CONTRIBUTING.md, LICENSE
- .github/workflows/build_and_test.yml (CI pipeline)
- data/ (test-data folder)
- examples/ (consumer code demonstrating library usage)
- src/:
- lib.rs (entry point, re-exports)
- scip.rs (initialization, global parameters)
- Modules for each wrapper: model.rs, variable.rs, constraint.rs, row.rs, solution.rs, status.rs, retcode.rs, col.rs, param.rs, probing.rs, diving.rs, eventhdlr.rs, heuristic.rs, separator.rs, pricer.rs, branchrule.rs, sepa.rs, …
- builder/ subdirectory: builder.rs plus plugin-specific builders (branchrule.rs, pricer.rs, eventhdlr.rs, heur.rs, cons.rs, row.rs, sepa.rs, var.rs)
- No networking or database—core dependency is the external SCIP C library accessed through FFI.

##### README for additional insights
- Confirms two layers:
- `ffi` module (raw C-API bindings)
- Safe wrappers over SCIP entities (Model, Variable, Constraint, etc.)
- Defines plugin-trait modules (BranchRule, Pricer, Eventhdlr, Heuristic, Separator, Conshdlr) and shows how to attach custom data via anymap.
- Examples directory holds standalone Rust programs that call into the library.

##### Components
a. Main components
1. Rust Safe-API Layer
– Core types: Model, Variable, Constraint, Row, Solution, Status, Retcode, Column, Parameter.
– Plugin traits: BranchRule, Pricer, EventHdlr, Heuristic, Separator, Conshdlr
2. Builder Subsystem
– builder:: (one builder per plugin type + overall Model builder)
3. FFI Layer
– `ffi` bindings (extern “C” functions matching SCIP’s C-API)
4. External SCIP C Library
– The native solver code (bundled or system-installed)
5. Consumers / Examples / Tests
– examples/*.rs
– data/test input files
6. CI / Packaging
– GitHub Actions workflow
– crates.io (publishing)
– codecov

b. Relationships and interactions
- Safe-API calls into builder and direct wrapper modules.
- Wrapper modules invoke `ffi` functions to perform operations on the SCIP pointer.
- `ffi` layer calls into the external SCIP C library.
- Plugin traits are implemented by user code or examples, registered via builder APIs, and invoked by SCIP during solve.
- anymap used internally by Model to store custom user data.
- CI triggers build/test, publishes coverage, and can deploy to crates.io.

c. Architectural patterns and design principles
- Wrapper/Adapter pattern: Rust types adapt the raw C interface to safe, idiomatic Rust.
- Builder pattern: `builder/` modules let you configure and attach plugins before solving.
- Plugin architecture: Traits define extension points; user code implements them and registers with Model.
- Separation of concerns:
– Core modeling vs. plugin mechanics vs. raw FFI vs. user code (examples/tests).
- Zero-cost abstractions: Safe wrappers have minimal runtime overhead over raw FFI.

d. Key technologies, frameworks, libraries
- Rust, Cargo, crates.io
- FFI (extern “C”)
- anymap for per-Model data storage
- GitHub Actions, codecov for CI/CD
- SCIP C library (bundled feature)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Consumers Layer
    subgraph "Examples & Tests" 
        direction TB
        ex1["bin_packing.rs"]:::consumers
        ex2["clique_separator.rs"]:::consumers
        ex3["create_and_solve.rs"]:::consumers
        ex4["cutting_stock.rs"]:::consumers
        ex5["knapsack.rs"]:::consumers
        ex6["most_infeasible_branching.rs"]:::consumers
        ex7["node_event_handler.rs"]:::consumers
        ex8["random_rounding.rs"]:::consumers
        ex9["tsp.rs"]:::consumers
        td1["simple.lp"]:::consumers
        td2["simple.mps"]:::consumers
        td3["gen-ip054.mps"]:::consumers
        click ex1 "https://github.com/scipopt/russcip/blob/main/examples/bin_packing.rs"
        click ex2 "https://github.com/scipopt/russcip/blob/main/examples/clique_separator.rs"
        click ex3 "https://github.com/scipopt/russcip/blob/main/examples/create_and_solve.rs"
        click ex4 "https://github.com/scipopt/russcip/blob/main/examples/cutting_stock.rs"
        click ex5 "https://github.com/scipopt/russcip/blob/main/examples/knapsack.rs"
        click ex6 "https://github.com/scipopt/russcip/blob/main/examples/most_infeasible_branching.rs"
        click ex7 "https://github.com/scipopt/russcip/blob/main/examples/node_event_handler.rs"
        click ex8 "https://github.com/scipopt/russcip/blob/main/examples/random_rounding.rs"
        click ex9 "https://github.com/scipopt/russcip/blob/main/examples/tsp.rs"
        click td1 "https://github.com/scipopt/russcip/blob/main/data/test/simple.lp"
        click td2 "https://github.com/scipopt/russcip/blob/main/data/test/simple.mps"
        click td3 "https://github.com/scipopt/russcip/blob/main/data/test/gen-ip054.mps"
    end

    %% Core Library
    subgraph "russcip Library Core"
        direction TB
        subgraph "Safe-API Modules" 
            direction TB
            m1["lib.rs"]:::safeapi
            m2["model.rs"]:::safeapi
            m3["variable.rs"]:::safeapi
            m4["constraint.rs"]:::safeapi
            m5["row.rs"]:::safeapi
            m6["solution.rs"]:::safeapi
            m7["status.rs"]:::safeapi
            m8["retcode.rs"]:::safeapi
            m9["col.rs"]:::safeapi
            m10["param.rs"]:::safeapi
            m11["node.rs"]:::safeapi
            m12["probing.rs"]:::safeapi
            m13["diving.rs"]:::safeapi
            m14["eventhdlr.rs"]:::safeapi
            m15["heuristic.rs"]:::safeapi
            m16["separator.rs"]:::safeapi
            m17["pricer.rs"]:::safeapi
            m18["branchrule.rs"]:::safeapi
            m19["conshdlr.rs"]:::safeapi
            click m1 "https://github.com/scipopt/russcip/blob/main/src/lib.rs"
            click m2 "https://github.com/scipopt/russcip/blob/main/src/model.rs"
            click m3 "https://github.com/scipopt/russcip/blob/main/src/variable.rs"
            click m4 "https://github.com/scipopt/russcip/blob/main/src/constraint.rs"
            click m5 "https://github.com/scipopt/russcip/blob/main/src/row.rs"
            click m6 "https://github.com/scipopt/russcip/blob/main/src/solution.rs"
            click m7 "https://github.com/scipopt/russcip/blob/main/src/status.rs"
            click m8 "https://github.com/scipopt/russcip/blob/main/src/retcode.rs"
            click m9 "https://github.com/scipopt/russcip/blob/main/src/col.rs"
            click m10 "https://github.com/scipopt/russcip/blob/main/src/param.rs"
            click m11 "https://github.com/scipopt/russcip/blob/main/src/node.rs"
            click m12 "https://github.com/scipopt/russcip/blob/main/src/probing.rs"
            click m13 "https://github.com/scipopt/russcip/blob/main/src/diving.rs"
            click m14 "https://github.com/scipopt/russcip/blob/main/src/eventhdlr.rs"
            click m15 "https://github.com/scipopt/russcip/blob/main/src/heuristic.rs"
            click m16 "https://github.com/scipopt/russcip/blob/main/src/separator.rs"
            click m17 "https://github.com/scipopt/russcip/blob/main/src/pricer.rs"
            click m18 "https://github.com/scipopt/russcip/blob/main/src/branchrule.rs"
            click m19 "https://github.com/scipopt/russcip/blob/main/src/conshdlr.rs"
        end
        subgraph "Builder & Plugin Traits"
            direction TB
            b1["mod.rs"]:::builder
            b2["branchrule.rs"]:::builder
            b3["pricer.rs"]:::builder
            b4["eventhdlr.rs"]:::builder
            b5["heur.rs"]:::builder
            b6["cons.rs"]:::builder
            b7["row.rs"]:::builder
            b8["sepa.rs"]:::builder
            b9["var.rs"]:::builder
            click b1 "https://github.com/scipopt/russcip/blob/main/src/builder/mod.rs"
            click b2 "https://github.com/scipopt/russcip/blob/main/src/builder/branchrule.rs"
            click b3 "https://github.com/scipopt/russcip/blob/main/src/builder/pricer.rs"
            click b4 "https://github.com/scipopt/russcip/blob/main/src/builder/eventhdlr.rs"
            click b5 "https://github.com/scipopt/russcip/blob/main/src/builder/heur.rs"
            click b6 "https://github.com/scipopt/russcip/blob/main/src/builder/cons.rs"
            click b7 "https://github.com/scipopt/russcip/blob/main/src/builder/row.rs"
            click b8 "https://github.com/scipopt/russcip/blob/main/src/builder/sepa.rs"
            click b9 "https://github.com/scipopt/russcip/blob/main/src/builder/var.rs"
        end
        ffi["FFI Bindings (scip.rs)"]:::ffi
        click ffi "https://github.com/scipopt/russcip/blob/main/src/scip.rs"
    end

    %% External and Internal Dependencies
    anymap["anymap"]:::external
    scipC["SCIP C Library"]:::external
    CI["GitHub Actions"]:::ci
    coverage["codecov"]:::ci
    crate["crates.io"]:::ci

    %% Relationships
    ex1 -->|uses| m1
    ex2 -->|uses| m2
    ex3 -->|uses| m1
    ex4 -->|uses| m1
    ex5 -->|uses| m1
    ex6 -->|uses| m18
    ex7 -->|uses| m14
    ex8 -->|uses| m1
    ex9 -->|uses| m1
    td1 -->|input to| ex3
    td2 -->|input to| ex3
    td3 -->|input to| ex3

    m2 -->|calls| ffi
    m3 -->|calls| ffi
    b1 -->|configures| m2
    b2 -->|registers| m18
    b3 -->|registers| m17
    b4 -->|registers| m14
    b5 -->|registers| m15
    b6 -->|registers| m19
    b8 -->|registers| m16
    b9 -->|registers| m3
    anymap -->|set_data/get_data| m2
    ffi -->|FFI call| scipC

    CI -->|build/test| m1
    CI -->|report| coverage
    CI -->|publish| crate

    %% Styles
    classDef safeapi fill:#cce5ff,stroke:#0000cc,color:#0000cc;
    classDef builder fill:#d4edda,stroke:#006400,color:#006400;
    classDef ffi fill:#ffe5b4,stroke:#cc8400,color:#cc8400;
    classDef external fill:#f8d7da,stroke:#cc0000,color:#cc0000;
    classDef consumers fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef ci fill:#e3e1f7,stroke:#6f42c1,color:#6f42c1;
```
