# opensemba/tulip architecture

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

- Interactive diagram: https://gitdiagram.com/opensemba/tulip
- Repository: https://github.com/opensemba/tulip

## Overview

##### Project type and purpose
- Tulip is an open-source, command-line, scientific/engineering solver written in C++.
- It computes per-unit-length capacitance (C) and inductance (L) matrices for multiconductor transmission lines (MTL) using finite element methods (FEM).
- It integrates with external tools (MFEM for FEM engine, step2gmsh for CAD→mesh conversion) and exports results for visualization (ParaView, VisIt).

##### File structure
Top-level directories and key files:
- src/   – core C++ modules
- external/ – submodules (mfem-geg, step2gmsh)
- test/ – unit tests (GoogleTest style)
- testData/ – sample JSON, .msh, .step inputs
- docs/  – developer/user documentation and figures
- .github/workflows/ – CI build & test pipelines
- CMakeLists.txt, vcpkg.json – build and dependency manifest
Notable patterns:
- Modular C++ headers+sources per domain concept (Parser, Model, Domain, Solver, Results).
- Use of submodule for MFEM and external mesh preprocessor.
- Tests mirror each src component with TestUtils and data fixtures.

##### README for architecture hints
- Core workflow: CLI → parse JSON → set up “model” (mesh+materials) → call electrostatic solver per conductor → compute C/L matrices → write JSON + optional ParaView/VisIt files.
- Dependencies: MFEM library, vcpkg packages, step2gmsh workflow.

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Main data flow
    JSONIn["JSON Input"]:::io
    User["User (CLI)"]:::external
    CLI["pulmtln & Driver"]:::core
    Parser["Parser"]:::core
    Preprocessor["step2gmsh"]:::external
    MeshFile[".msh Mesh File"]:::io
    Model["Model"]:::core
    Domain["Domain & DirectedGraph"]:::core
    Materials["Materials Assignment"]:::core
    ElectroSolver["ElectrostaticSolver"]:::core
    FES["Finite Element Support (FES)"]:::core
    SolverOpts["SolverOptions"]:::core
    Multipolar["MultipolarExpansion"]:::core
    Results["Results & Export"]:::io
    JSONOut["JSON Output"]:::io
    VTK["VTK Export (.vtk)"]:::io
    VP["ParaView/VisIt"]:::external

    JSONIn -->|reads| CLI
    User -->|invokes| CLI
    CLI -->|parses| Parser
    Parser -->|generates| Preprocessor
    Preprocessor -->|outputs| MeshFile
    MeshFile -->|loads| Model
    Model -->|defines mesh| Domain
    Domain -->|assigns| Materials
    Materials -->|configures| ElectroSolver
    Domain -->|provides mesh| ElectroSolver
    ElectroSolver -->|calls| ExternalMFEM
    ElectroSolver -->|uses options| SolverOpts
    ElectroSolver -->|builds FE matrices| FES
    FES -->|fields data| Multipolar
    Multipolar -->|computes C/L| Results
    Results -->|writes| JSONOut
    Results -->|writes| VTK
    VTK -->|view in| VP

    %% External Tools
    subgraph "External Tools & Libraries"
        ExternalMFEM["MFEM Library"]:::external
        Preprocessor
        VP
    end

    %% Build System & CI
    subgraph "Build & CI Infrastructure"
        BuildSys["CMakeLists.txt"]:::infra
        CPresets["CMakePresets.json"]:::infra
        Vcpkg["vcpkg.json"]:::infra
        SrcCMake["src/CMakeLists.txt"]:::infra
        CI1["builds-and-tests.yml"]:::infra
        CI2["create-dist.bat"]:::infra
        CI3["windows-automated-releases.yml"]:::infra
    end
    BuildSys --> CPresets
    BuildSys --> Vcpkg
    BuildSys --> SrcCMake
    BuildSys --> CI1
    BuildSys --> CI2
    BuildSys --> CI3

    %% Testing & Docs
    subgraph "Testing & Documentation"
        Tests["Test Suite"]:::infra
        TestData["Test Data Fixtures"]:::infra
        Docs["Documentation & Figures"]:::infra
    end
    Tests -->|uses| TestData
    Tests -->|validates| Parser
    Tests -->|validates| Model
    Tests -->|validates| ElectroSolver

    %% Click Events
    click CLI "https://github.com/opensemba/tulip/blob/master/src/pulmtln.cpp"
    click CLI "https://github.com/opensemba/tulip/blob/master/src/Driver.cpp"
    click Parser "https://github.com/opensemba/tulip/blob/master/src/Parser.cpp"
    click Preprocessor "https://github.com/opensemba/tulip/tree/master/external/step2gmsh"
    click Model "https://github.com/opensemba/tulip/blob/master/src/Model.cpp"
    click Domain "https://github.com/opensemba/tulip/blob/master/src/Domain.cpp"
    click Materials "https://github.com/opensemba/tulip/blob/master/src/Materials.cpp"
    click ElectroSolver "https://github.com/opensemba/tulip/blob/master/src/ElectrostaticSolver.cpp"
    click FES "https://github.com/opensemba/tulip/blob/master/src/FES.cpp"
    click SolverOpts "https://github.com/opensemba/tulip/blob/master/src/SolverOptions.h"
    click Multipolar "https://github.com/opensemba/tulip/blob/master/src/multipolarExpansion.h"
    click Results "https://github.com/opensemba/tulip/blob/master/src/Results.cpp"
    click ExternalMFEM "https://github.com/opensemba/tulip/tree/master/external/mfem-geg"
    click BuildSys "https://github.com/opensemba/tulip/blob/master/CMakeLists.txt"
    click CPresets "https://github.com/opensemba/tulip/blob/master/CMakePresets.json"
    click Vcpkg "https://github.com/opensemba/tulip/blob/master/vcpkg.json"
    click SrcCMake "https://github.com/opensemba/tulip/blob/master/src/CMakeLists.txt"
    click CI1 "https://github.com/opensemba/tulip/blob/master/.github/workflows/builds-and-tests.yml"
    click CI2 "https://github.com/opensemba/tulip/blob/master/.github/workflows/create-dist.bat"
    click CI3 "https://github.com/opensemba/tulip/blob/master/.github/workflows/windows-automated-releases.yml"
    click Tests "https://github.com/opensemba/tulip/tree/master/test/"
    click TestData "https://github.com/opensemba/tulip/tree/master/testData/"
    click Docs "https://github.com/opensemba/tulip/tree/master/docs/"

    %% Styles
    classDef core fill:#a0f2a0,stroke:#333,stroke-width:1px
    classDef external fill:#a0aaff,stroke:#333,stroke-width:1px
    classDef io fill:#f2a050,stroke:#333,stroke-width:1px
    classDef infra fill:#cccccc,stroke:#333,stroke-width:1px
```
