# cambridge-iccs/fortran-tf-lib architecture

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

- Interactive diagram: https://gitdiagram.com/cambridge-iccs/fortran-tf-lib
- Repository: https://github.com/cambridge-iccs/fortran-tf-lib

## Overview

##### Project type and purpose
- This is an open-source library (“Fortran-TF-lib”) that provides Fortran bindings to the TensorFlow C inference API.
- Its goal is to let Fortran programs load pre-trained TensorFlow SavedModel files and perform inference without invoking Python at runtime.

##### File structure
Top-level
- .github/workflows: CI for running tests
- .gitignore, LICENSE, README.md, .gitmodules
- process_model (Python script entry point)
- fortran-tf-lib/
– CMakeLists.txt (build orchestration)
– README.md (library docs)
– my_model/ (example SavedModel files: `saved_model.pb`, variables/)
– src/fortran_tensorflow_lib.F90 (Fortran module implementing the C bindings)
– tests/
· gen_model.py (helper script)
· generated_code_test/ (example CMake + stub Fortran)
· load_model_{c,f,py}.c/F90/py (runtime loading examples)
· load_wavenet.F90
##### README
- Describes installation (CMake flags, dependencies: cmake, Fortran/C compiler, TensorFlow C API)
- Usage pattern:
a. Train/save a model in Python → SavedModel on disk
b. In Fortran: `use TF_Interface; call TF_LoadSessionFromSavedModel(...)` → run inference
- Shows minimal Fortran example + how to integrate with CMake

##### Main components
1. User Workflow Components
- Python Training Environment
– TensorFlow/Keras → SavedModel folder
- process_model CLI (Python script)
– Input: SavedModel
– Output: Fortran module stub (hard-coded ops & dims)
- Fortran Application Code
– Uses generated stub + TF_Interface module
2. Library Components (fortran-tf-lib)
- TF_Types module (Fortran types for C API structs)
- TF_Interface module (Fortran <–> C API binding layer)
- CMake build system (builds and installs `.mod` + `.so`)
- TensorFlow C library (external dependency)
3. Runtime Components
- SavedModel files on disk
- Dynamically linked `libtensorflow.so`
- Fortran executable
- TensorFlow graph execution (SessionRun)

##### Relationships & data flows
- [Python Training] produces → SavedModel folder
- [process_model] reads SavedModel → generates Fortran stub
- [CMake build] compiles → Fortran-TF-lib and user Fortran code, links with `libtensorflow.so`
- [Fortran Executable] at runtime:
- TF_LoadSessionFromSavedModel loads graph from SavedModel into a TF_Graph object
- TF_SessionRun executes inference, reading input tensors and returning output tensors
- Under the hood this calls into the TensorFlow C API (`libtensorflow.so`)

##### Highlighted architectural patterns
- **FFI Bridge**: Fortran modules wrap the C API via the `iso_c_binding` standard
- **Code Generation**: Python script auto-generates boilerplate Fortran interface to opaque model details
- **Modular Library + Examples**: clear separation of core library (src/) vs. examples/tests vs. codegen tool

##### Essential architectural elements to capture
- Separation of build-time (codegen, CMake) vs. run-time (inference)
- FFI boundary between Fortran and C (TensorFlow C API)
- Data flow: model files → Fortran stub → Fortran exe → TensorFlow runtime

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User Workflow
    subgraph "User Workflow"
        PythonTraining["Python Training Environment"]:::tooling
        SavedModelDisk[(SavedModel Folder)]:::external
        processModel["process_model CLI"]:::tooling
        FortranApp["Fortran Application Code + Generated Stub"]:::library
    end

    %% Build-time Components
    subgraph "Build-time"
        CMake["CMake Build System"]:::build
        TFTypes["TF_Types & TF_Interface Module"]:::library
        genModel["Test Helper Script (gen_model.py)"]:::tooling
        stubBuild["Generated Code CMakeLists"]:::build
        stubExample["Generated Fortran Stub"]:::library
    end

    %% Library Core
    subgraph "Core Library"
        fortranModule["fortran_tensorflow_lib.F90 (Bindings)"]:::library
    end

    %% Runtime Components
    subgraph "Runtime"
        FortranExe["Fortran Executable"]:::library
        libtf["libtensorflow.so"]:::external
    end

    %% CI
    subgraph "Continuous Integration (CI)"
        CIWorkflows["GitHub Actions CI"]:::build
    end

    %% Runtime Loading Examples
    subgraph "Runtime Loading Examples"
        CExample["C Example"]:::library
        FExample["Fortran Example"]:::library
        PyExample["Python Example"]:::tooling
        Wavenet["Wavenet Example"]:::library
    end

    %% Documentation
    README_top["Project README.md"]:::doc
    README_lib["Library README.md"]:::doc

    %% Relationships
    PythonTraining -->|"produces"| SavedModelDisk
    SavedModelDisk -->|"input to"| processModel
    processModel -->|"generates stub"| FortranApp
    FortranApp -->|"uses"| TFTypes
    TFTypes -->|"built by"| CMake
    fortranModule -->|"built by"| CMake
    CMake -->|"builds"| FortranExe
    FortranExe -->|"links against"| libtf
    FortranExe -->|"executes"| libtf
    TFTypes -->|"loads graph from"| SavedModelDisk
    CIWorkflows -->|"tests build and run"| CMake
    genModel -->|"generates test stub"| stubExample
    stubBuild -->|"builds test stub"| stubExample
    FortranExe -->|"executes examples"| CExample
    FortranExe -->|"executes examples"| FExample
    FortranExe -->|"executes examples"| PyExample
    FortranExe -->|"executes examples"| Wavenet

    %% Click Events
    click processModel "https://github.com/cambridge-iccs/fortran-tf-lib/tree/main/./process_model"
    click CMake "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/CMakeLists.txt"
    click TFTypes "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/src/fortran_tensorflow_lib.F90"
    click SavedModelDisk "https://github.com/cambridge-iccs/fortran-tf-lib/tree/main/fortran-tf-lib/my_model/"
    click README_top "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/README.md"
    click README_lib "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/README.md"
    click CIWorkflows "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/.github/workflows/tests.yml"
    click genModel "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/tests/gen_model.py"
    click stubExample "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/tests/generated_code_test/test_stub.F90"
    click stubBuild "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/tests/generated_code_test/CMakeLists.txt"
    click CExample "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/tests/load_model_c.c"
    click FExample "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/tests/load_model_f.F90"
    click PyExample "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/tests/load_model_py.py"
    click Wavenet "https://github.com/cambridge-iccs/fortran-tf-lib/blob/main/fortran-tf-lib/tests/load_wavenet.F90"

    %% Styles
    classDef library fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef tooling fill:#d4edda,stroke:#333,stroke-width:1px
    classDef external fill:#ffe5b4,stroke:#333,stroke-width:1px
    classDef build fill:#e2e3e5,stroke:#333,stroke-width:1px
    classDef doc fill:#f0e68c,stroke:#333,stroke-width:1px
```
