# ucns3d-team/ucns3d architecture

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

- Interactive diagram: https://gitdiagram.com/ucns3d-team/ucns3d
- Repository: https://github.com/ucns3d-team/ucns3d

## Overview

##### Project type and purpose
- UCNS3D is a high-performance, MPI+OpenMP hybrid parallel, command-line Computational Fluid Dynamics (CFD) solver written in Fortran. It is not a typical client-server or web app but a scientific HPC application designed to run on Linux, macOS, Windows/WSL, or inside Docker, and to be submitted to batch schedulers (PBS, SLURM) on supercomputers.
- The README makes clear that UCNS3D ingests unstructured meshes and parameter files, runs compressible flow simulations, and writes output for post-processing in Tecplot/ParaView/Visit.

##### File structure
- Top-level:
- bin/          – pre-built compiler toolchains and static libraries (metis, parmetis, tecplot)
- src/          – Fortran source modules and Makefiles
- scripts/      – HPC submission scripts (PBS/SLURM), translators for mesh formats
- tests/        – sample cases (input meshes & DAT files) and test runners
- Dockerfile    – container recipe including dependencies
- docs/         – manuals, whitepaper, API docs
- .github/      – issue templates
- Build system:
- src/Makefile_common & Makefile_docker
- bin/<compiler>/Makefile
- Deployment:
- Docker image
- HPC scheduler scripts in scripts/submission-script/

##### README for additional insights
- Dependencies: MPI (e.g., mpirun), OpenMP, Fortran compiler (GNU or Intel), BLAS (MKL/OpenBLAS), METIS for mesh partition.
- Execution: set OMP_NUM_THREADS, then mpirun ‑np M ./ucns3d_p
- Visualization: writes outputs compatible with Tecplot, ParaView, Visit
- Examples and tests: tests/ directory and scripts/run-docker-test.sh, execute-tests.sh

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "Development & Build Environment"
        GNU["GNU Compiler Toolchain"]:::build
        Intel["Intel Compiler Toolchain"]:::build
        macos["macOS Compiler Toolchain"]:::build
        METIS["METIS Static Lib"]:::build
        ParMETIS["ParMETIS Static Lib"]:::build
        TecIO["TecIO Library"]:::build
    end

    subgraph "Source Code & Build System"
        CommonMk["Makefile_common"]:::build
        DockerMk["Makefile_docker"]:::build
        Modules["Fortran Modules (src/*.f90)"]:::build
    end

    subgraph "Containerization"
        Dockerfile["Dockerfile"]:::infra
        DockerImage["Docker Image (ucns3d)"]:::infra
    end

    subgraph "Job Submission Layer"
        PBS["PBS/SLURM Scripts"]:::infra
    end

    subgraph "Translators"
        STAR2NAT["STAR2NAT Converter"]:::infra
        UGRID2NAT["UGRID2NAT Converter"]:::infra
    end

    subgraph "Test Harness"
        ExecTests["execute-tests.sh"]:::infra
        RunDockerTests["run-docker-test.sh"]:::infra
        Samples["Sample Input Cases"]:::data
    end

    subgraph "Runtime Execution"
        Exec["ucns3d_p Executable"]:::runtime
        MPI["MPI Processes"]:::runtime
        OMP["OpenMP Threads"]:::runtime
    end

    subgraph "Inputs"
        Mesh["Mesh Files"]:::data
        DAT["Parameter File (UCNS3D.DAT)"]:::data
    end

    subgraph "Outputs"
        OutputFiles["Solution Outputs"]:::data
    end

    subgraph "Visualization/Post-processing"
        Tecplot["Tecplot"]:::infra
        ParaView["ParaView"]:::infra
        Visit["Visit"]:::infra
    end

    subgraph "Documentation"
        DocInputs["Input File Formats"]:::docs
        DocOutputs["Output File Formats"]:::docs
        DocTests["Test Descriptions"]:::docs
    end

    subgraph "Infrastructure"
        Cloud["HPC Cluster"]:::infra
        DockerHost["Docker Host"]:::infra
    end

    %% Build flow
    GNU --> CommonMk
    Intel --> CommonMk
    macos --> CommonMk
    METIS --> CommonMk
    ParMETIS --> CommonMk
    TecIO --> CommonMk

    CommonMk --> Modules
    DockerMk --> Modules
    Modules --> Exec

    Dockerfile --> DockerImage
    DockerImage --> Exec

    %% Runtime flow
    Mesh --> Exec
    DAT --> Exec
    Exec --> MPI
    MPI --> OMP
    MPI --> Cloud
    Cloud --> Exec

    Exec --> OutputFiles
    OutputFiles --> Tecplot
    OutputFiles --> ParaView
    OutputFiles --> Visit

    PBS --> Cloud

    STAR2NAT --> Mesh
    UGRID2NAT --> Mesh

    ExecTests --> Exec
    RunDockerTests --> DockerImage
    Samples --> ExecTests

    DocInputs
    DocOutputs
    DocTests

    %% Click Events
    click GNU "https://github.com/ucns3d-team/ucns3d/tree/master/bin/gnu-compiler"
    click Intel "https://github.com/ucns3d-team/ucns3d/tree/master/bin/intel-compiler"
    click macos "https://github.com/ucns3d-team/ucns3d/tree/master/bin/macos"
    click METIS "https://github.com/ucns3d-team/ucns3d/blob/master/bin/lib/metis/libmetis.a"
    click ParMETIS "https://github.com/ucns3d-team/ucns3d/blob/master/bin/lib/parmetis/libparmetis.a"
    click TecIO "https://github.com/ucns3d-team/ucns3d/blob/master/bin/lib/tecplot/libtecio.a"
    click CommonMk "https://github.com/ucns3d-team/ucns3d/tree/master/src/Makefile_common"
    click DockerMk "https://github.com/ucns3d-team/ucns3d/tree/master/src/Makefile_docker"
    click Modules "https://github.com/ucns3d-team/ucns3d/blob/master/src/*.f90"
    click Dockerfile "https://github.com/ucns3d-team/ucns3d/tree/master/Dockerfile"
    click PBS "https://github.com/ucns3d-team/ucns3d/blob/master/scripts/submission-script/ARCHER_IB.pbs"
    click STAR2NAT "https://github.com/ucns3d-team/ucns3d/blob/master/scripts/translators/STAR2NAT.f90"
    click UGRID2NAT "https://github.com/ucns3d-team/ucns3d/blob/master/scripts/translators/UGRID2NAT.f90"
    click ExecTests "https://github.com/ucns3d-team/ucns3d/blob/master/tests/execute-tests.sh"
    click RunDockerTests "https://github.com/ucns3d-team/ucns3d/blob/master/tests/run-docker-test.sh"
    click Samples "https://github.com/ucns3d-team/ucns3d/blob/master/tests/*/*.DAT"
    click DocInputs "https://github.com/ucns3d-team/ucns3d/blob/master/docs/inputs.md"
    click DocOutputs "https://github.com/ucns3d-team/ucns3d/blob/master/docs/outputs.md"
    click DocTests "https://github.com/ucns3d-team/ucns3d/blob/master/docs/tests.md"

    %% Styles
    classDef build fill:#D6E9F8,stroke:#1F78C1,stroke-width:2px
    classDef infra fill:#FFF2CC,stroke:#CC7900,stroke-width:2px
    classDef runtime fill:#DFF0D8,stroke:#3C763D,stroke-width:2px
    classDef data fill:#FCF8E3,stroke:#8A6D3B,stroke-width:2px
    classDef docs fill:#F2DEDE,stroke:#A94442,stroke-width:2px
```
