# prisms-center/phasefield architecture

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

- Interactive diagram: https://gitdiagram.com/prisms-center/phasefield
- Repository: https://github.com/prisms-center/phasefield

## Overview

##### Project type and purpose
- This is an open-source, HPC‐oriented C++ library and application suite (PRISMS-PF) for phase-field simulations.
- It exposes a core library for finite-element PDE solves (matrix-free, deal.II‐based), plus ~24 prebuilt “application” executables (each realizing a particular PDE model), accompanied by testing harnesses, documentation, and postprocessing utilities.

##### File‐structure analysis
- Top‐level:
– CMakeLists.txt orchestrates build, versioning, and template expansion
– include/ & src/ contain the “prismspf” library source (modularized into core, solvers, user_inputs, utilities)
– applications/ holds standalone PDE applications (each in its own subfolder with main.cc, parameters.prm, custom_pde.h, etc.)
– tests/ holds automatic_tests (regression), performance_tests (scaling), unit_tests (Catch2‐based)
– contrib/ holds Python postprocessing and shell utilities
– doc/ holds Doxygen config and tutorial files
– GitHub workflows automate linting, compilation, CI, and docs deployment
- Key patterns:
– Modular layered library (core → solvers → problem setup → user I/O)
– Template instantiation macros (cmake/macros) to generate PDE operator code
– Plugin‐style applications linking against the common library
– CI pipelines building library, apps, running tests, generating docs

##### Insights from README
- Depends on external libraries: deal.II, p4est, Caliper, VTK for I/O
- Uses MPI for parallel execution
- Provides both Debug (main-debug) and Release builds
- Visualization via VTK‐format output (pvtu/vtu)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% CI & Build
    subgraph "CI & Build"
        CMake["CMakeLists.txt"]:::build
        Macros["CMake macros & modules"]:::build
        Workflows["GitHub Actions workflows"]:::build
    end

    %% Core Library Modules
    subgraph "Core Library Modules"
        CoreHdr["Core (include/prismspf/core/)"]:::library
        CoreImpl["Core (src/core/)"]:::library
        SolversHdr["Solvers (include/prismspf/solvers/)"]:::library
        SolversImpl["Solvers (src/solvers/)"]:::library
        UserInputsHdr["User Inputs (include/prismspf/user_inputs/)"]:::library
        UserInputsImpl["User Inputs (src/user_inputs/)"]:::library
        UtilitiesHdr["Utilities (include/prismspf/utilities/)"]:::library
        UtilitiesImpl["Utilities (src/utilities/)"]:::library
    end

    %% Applications
    subgraph "Prebuilt Applications"
        Apps["applications/*"]:::app
    end

    %% Tests Suite
    subgraph "Tests Suite"
        Unit["Unit Tests (tests/unit_tests/)"]:::test
        Auto["Automatic Tests (tests/automatic_tests/)"]:::test
        Perf["Performance Tests (tests/performance_tests/)"]:::test
    end

    %% Documentation
    subgraph "Documentation Generator"
        DoxyConf["Doxygen config (doc/doxygen/Doxyfile)"]:::doc
        DoxyLayouts["Layouts & support (doc/doxygen/)"]:::doc
        DoxyTutorial["Tutorial docs (doc/doxygen/tutorial/)"]:::doc
    end

    %% Postprocessing Tools
    subgraph "Postprocessing Tools"
        PostProc["Python scripts (contrib/postprocessing/)"]:::tool
    end

    %% External Dependencies
    subgraph "External Dependencies"
        deal["deal.II"]:::external
        p4est["p4est"]:::external
        Caliper["Caliper"]:::external
        VTK["VTK"]:::external
        MPI["MPI"]:::external
    end

    %% Relationships
    CMake --> CoreHdr
    CMake --> SolversHdr
    CMake --> UserInputsHdr
    CMake --> UtilitiesHdr

    Workflows --> CMake
    Workflows --> CoreHdr
    Workflows --> Apps
    Workflows --> Unit
    Workflows --> Auto
    Workflows --> Perf
    Workflows --> DoxyConf

    Macros --> CoreImpl
    Macros --> SolversImpl
    Macros --> UserInputsImpl
    Macros --> UtilitiesImpl

    Macros --> deal
    Macros --> p4est
    Macros --> Caliper
    Macros --> VTK

    Apps --> CoreHdr
    Apps --> SolversHdr
    Apps --> UserInputsHdr
    Apps --> UtilitiesHdr
    Apps --> deal
    Apps --> p4est
    Apps --> Caliper
    Apps --> VTK
    Apps --> MPI
    Apps --> PostProc

    Unit --> CoreHdr
    Unit --> SolversHdr
    Unit --> UserInputsHdr
    Unit --> UtilitiesHdr

    Auto --> CoreHdr
    Perf --> CoreHdr

    DoxyConf --> CoreHdr
    DoxyConf --> DoxyLayouts
    DoxyConf --> DoxyTutorial

    %% Click Events
    click CMake "https://github.com/prisms-center/phasefield/blob/master/CMakeLists.txt"
    click Macros "https://github.com/prisms-center/phasefield/tree/master/cmake/macros/*"
    click Workflows "https://github.com/prisms-center/phasefield/blob/master/.github/workflows/*.yml"
    click CoreHdr "https://github.com/prisms-center/phasefield/tree/master/include/prismspf/core/"
    click CoreImpl "https://github.com/prisms-center/phasefield/tree/master/src/core/"
    click SolversHdr "https://github.com/prisms-center/phasefield/tree/master/include/prismspf/solvers/"
    click SolversImpl "https://github.com/prisms-center/phasefield/tree/master/src/solvers/"
    click UserInputsHdr "https://github.com/prisms-center/phasefield/tree/master/include/prismspf/user_inputs/"
    click UserInputsImpl "https://github.com/prisms-center/phasefield/tree/master/src/user_inputs/"
    click UtilitiesHdr "https://github.com/prisms-center/phasefield/tree/master/include/prismspf/utilities/"
    click UtilitiesImpl "https://github.com/prisms-center/phasefield/tree/master/src/utilities/"
    click Apps "https://github.com/prisms-center/phasefield/tree/master/applications/"
    click Unit "https://github.com/prisms-center/phasefield/tree/master/tests/unit_tests/"
    click Auto "https://github.com/prisms-center/phasefield/tree/master/tests/automatic_tests/"
    click Perf "https://github.com/prisms-center/phasefield/tree/master/tests/performance_tests/"
    click DoxyConf "https://github.com/prisms-center/phasefield/tree/master/doc/doxygen/Doxyfile"
    click DoxyLayouts "https://github.com/prisms-center/phasefield/tree/master/doc/doxygen/"
    click DoxyTutorial "https://github.com/prisms-center/phasefield/tree/master/doc/doxygen/tutorial/"
    click PostProc "https://github.com/prisms-center/phasefield/tree/master/contrib/postprocessing/"

    %% Styles
    classDef build fill:#D9E6FB,stroke:#1E90FF;
    classDef library fill:#E0F7FA,stroke:#00838F;
    classDef app fill:#E8F5E9,stroke:#2E7D32;
    classDef test fill:#FFF3E0,stroke:#EF6C00;
    classDef doc fill:#F3E5F5,stroke:#6A1B9A;
    classDef tool fill:#FCE4EC,stroke:#C2185B;
    classDef external fill:#ECEFF1,stroke:#607D8B,stroke-dasharray:5 5;
```
