# gams-dev/cuoptlink-builder architecture

> Architecture diagram of the GitHub repository gams-dev/cuoptlink-builder, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-05). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gams-dev/cuoptlink-builder
- Repository: https://github.com/gams-dev/cuoptlink-builder

## Overview

##### Project type and purpose
- This is an open‐source “solver link” project whose sole purpose is to build, package, and distribute a GAMS/GAMSPy plugin that allows users to call NVIDIA’s cuOpt solver from within the GAMS modeling environment.
- Key indicators: a single C source file (gmscuopt.c) under the root, an assets folder containing configuration for GAMS, a GitHub Actions workflow, and examples demonstrating usage in a Jupyter notebook.

##### File structure
- Top-level artifacts:
- .github/workflows/main.yml → CI build & packaging pipeline
- gmscuopt.c           → the core native code that implements the solver link API for GAMS
- assets/              → GAMS configuration files (gamsconfig.yaml, .def, .run) needed at runtime
- examples/            → demonstration code (Python/Jupyter) using GAMSPy + cuOpt
- No “frontend” or “backend”—this is a build‐and‐integration tool.
- Packaging relies on GitHub Actions to compile the C code, assemble assets, zip them into cuopt-link-release.zip, and tag a GitHub Release.

##### README for additional insights
- Describes OS and dependency requirements (Linux, GAMS ≥49, GAMSPy ≥1.12.1, CUDA ≥12.0, NVIDIA GPU).
- Spell out installation: unzip the released ZIP into the GAMS system directory (or GAMSPy base).
- Runtime test: model → GAMS “trnsport” example uses solver “cuopt.”

##### Elements
- Source → Build → Artifact → Unzip → GAMS System Dir → Runtime loads → cuOpt → GPU → Results → GAMS
- Blue for build-time components
- Green for runtime plugin components
- Orange for external dependencies (CUDA/cuOpt)
- Parallelogram for configuration files

##### Detail without over-splitting
- Call out the five specific CUDA libraries under assets to show exactly what runtime binaries are needed.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Build-time components
    subgraph "Build Environment"
        CI["GitHub Actions Runner"]:::build
        Compiler["Compiler Toolchain (GCC/Clang + CUDA)"]:::build
        Packager["Packager"]:::build
        Repo[(GitHub Releases)]:::artifact
    end

    %% Source artifacts
    subgraph "Source Artifacts"
        Source["gmscuopt.c"]:::build
        Doc["README.md"]:::build
        License["LICENSE"]:::build
        Assets["assets/"]:::build
    end

    %% Runtime plugin components
    subgraph "Runtime Plugin"
        Unzip["Unpacked ZIP"]:::runtime
        GAMSDir["GAMS System Directory"]:::runtime
        SolverLib["gmscuopt.so"]:::runtime
        subgraph "Configuration Files"
            YAML[/gamsconfig.yaml/]:::runtime
            Run[/gmscuopt.run/]:::runtime
            Def[/optcuopt.def/]:::runtime
        end
    end

    %% Examples
    subgraph "Examples"
        Notebook["trnsport_cuopt.ipynb"]:::runtime
        Req["requirements.txt"]:::runtime
        ExReadme["README.md"]:::runtime
    end

    %% External dependencies
    subgraph "External Dependencies"
        cuOpt["NVIDIA cuOpt Libraries"]:::external
        CUDA["CUDA Runtime"]:::external
        GPU["GPU Hardware"]:::external
        GAMS["GAMS/GAMSPy"]:::runtime
    end

    %% Build workflow
    CI -->|"fetch source"| Source
    CI --> Compiler
    Source --> Compiler
    CI --> Packager
    Compiler --> Packager
    Packager --> Repo

    %% Runtime workflow
    Repo -->|"download ZIP"| Unzip
    Unzip --> GAMSDir
    GAMSDir --> GAMS
    GAMS -->|"loads"| SolverLib
    SolverLib --> YAML
    SolverLib --> Run
    SolverLib --> Def
    SolverLib --> cuOpt
    SolverLib --> CUDA
    CUDA --> GPU
    GPU -->|"results"| SolverLib
    SolverLib -->|"returns results"| GAMS

    %% Documentation examples
    Examples --> GAMS

    %% Click events
    click CI "https://github.com/gams-dev/cuoptlink-builder/blob/main/.github/workflows/main.yml"
    click Source "https://github.com/gams-dev/cuoptlink-builder/blob/main/gmscuopt.c"
    click Assets "https://github.com/gams-dev/cuoptlink-builder/tree/main/assets/"
    click YAML "https://github.com/gams-dev/cuoptlink-builder/blob/main/assets/gamsconfig.yaml"
    click Run "https://github.com/gams-dev/cuoptlink-builder/blob/main/assets/gmscuopt.run"
    click Def "https://github.com/gams-dev/cuoptlink-builder/blob/main/assets/optcuopt.def"
    click Notebook "https://github.com/gams-dev/cuoptlink-builder/blob/main/examples/trnsport_cuopt.ipynb"
    click Req "https://github.com/gams-dev/cuoptlink-builder/blob/main/examples/requirements.txt"
    click ExReadme "https://github.com/gams-dev/cuoptlink-builder/blob/main/examples/README.md"
    click Doc "https://github.com/gams-dev/cuoptlink-builder/blob/main/README.md"
    click License "https://github.com/gams-dev/cuoptlink-builder/tree/main/LICENSE"

    %% Styles
    classDef build fill:#D0E6FF,stroke:#4D89F3,color:#000;
    classDef runtime fill:#DFFFE0,stroke:#3CB043,color:#000;
    classDef external fill:#FFE5B4,stroke:#F5A623,color:#000;
    classDef artifact fill:#E6E6FA,stroke:#8A2BE2,color:#000;
```
