# damask-multiphysics/damask architecture

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

- Interactive diagram: https://gitdiagram.com/damask-multiphysics/damask
- Repository: https://github.com/damask-multiphysics/damask

## Overview

Based on our analysis of the file tree and README, DAMASK (the Düsseldorf Advanced Material Simulation Kit) is a scientific simulation package aimed at advanced material modeling and multi-physics simulations. It is written largely in Fortran (with its core in the src directory) and provides Python interfaces for scripting, configuration, and post‐processing. The project also includes extensive example configurations, build and installation scripts (using CMake and Makefiles), integration with other simulation tools (e.g., MarcMentat in the install directory), and automated testing and CI/CD pipelines (via GitHub and GitLab configuration files).

##### Main Components
- Core Simulation Engine:
– Located primarily in “src” (Fortran files), including numerical solvers, grid and mesh management (src/grid and src/mesh), material, phase, homogenization, and physical process modules.
– “src/Marc” suggests a specialized module to interface or extend functionality with the Marc software.
- Pre-/Post-Processing and Interfaces:
– Python modules under the “python” directory (including damask package, tests, and associated build configuration) act as a front-end/wrapper for configuration, orchestration, and result analysis.
– Processing scripts (in the “processing” directory) further support legacy and integration tasks.
- Input Configurations and Examples:
– The “examples” directory provides numerous YAML configuration files for different simulation cases (mechanical, thermal, damage, crystal phases, etc.) and mesh/grid files that guide the simulation runs.
- Build, Testing, and Integration Infrastructure:
– Build and configuration files (CMakeLists.txt, Makefile, and various cmake scripts) coordinate how the Fortran core and auxiliary components are compiled.
– CI/CD configurations in .github/workflows, .gitlab-ci.yml, and similar files manage automated building and testing.
- Installation and Deployment Support:
– The “install” directory (with its many MarcMentat versions and patches) shows integrations with external client software, ensuring a flexible installation path across various environments.

##### Relationships and Data/Control Flows
- The core engine (in Fortran) calls specific modules within “src” for numerical solvers, grid computations, homogenization, and material phases.
- Post-processing is managed by separate Python modules (including tests and utility scripts) that analyze simulation output (VTK, HDF5, etc.).
- Continuous integration pipelines are shown as separate components that automatically trigger builds and test runs through various workflow configurations.
- An “Installation/Integration” component shows the interaction with Marc tools that may patch or extend functionality; these are separately maintained in the “install” directory.

##### Architectural Patterns and Design Principles
- Separation of Concerns: The project is divided clearly between the core simulation engine (Fortran code) and the user/interface layer (Python and configuration files). Separate modules for grid/mesh, material behavior, homogenization, and phase definitions allow modular development.
- Extensibility: The availability of numerous configuration files and “examples” indicates that the simulation parameters can be easily varied, while the Python wrappers provide hooks for extending functionality or integrating post-processing.
- Build and Deployment Automation: The use of CMake and CI configurations reflects a design that stresses automation and platform-independent builds.

- Drill down to show further subdivisions in the simulation core such as grid management, solver modules, homogenization modules, and material/phase processing.
- Similarly, show in the UI layer that input configuration (YAML, mesh files) is processed by Python scripts, which eventually communicate with the simulation engine.
- Components responsible for pre-processing, simulation execution, and post-processing of results.
- Annotations on external dependencies (such as libraries like FFTW, LAPACK, HDF5) if needed for detail.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Simulation Core (Fortran)"
        A["Core Simulation Engine"]:::core
        A1["Grid Management (src/grid)"]:::core
        A2["Mesh Management (src/mesh)"]:::core
        A3["Homogenization Modules (src/homogenization.f90)"]:::core
        A4["Material & Phase Modules (src/material.f90, src/phase.f90)"]:::core
        A5["Marc Integration Module (src/Marc)"]:::core
    end

    subgraph "User Interface & Post-Processing"
        B1["Python Interface (damask)"]:::python
        B2["Python Tests"]:::python
        B3["Legacy Processing Scripts"]:::python
    end

    subgraph "Input Configurations & Examples"
        C1["Examples Configurations (YAML)"]:::config
        C2["Example Grid Files"]:::config
        C3["Example Mesh Files"]:::config
    end

    subgraph "Build & CI Infrastructure"
        D1["CMakeLists.txt"]:::build
        D2["cmake Config"]:::build
        D3["Makefile"]:::build
        D4["GitHub Workflows"]:::build
        D5["GitLab CI"]:::build
    end

    subgraph "Installation & External Tools"
        E1["MarcMentat Integration"]:::install
    end

    %% Data/Control Flow Connections
    C1 -->|"input"| A
    C2 -->|"grid_input"| A
    C3 -->|"mesh_input"| A

    B1 -->|"control"| A
    B2 -->|"test"| A
    B3 -->|"legacy"| A

    D1 -->|"build"| A
    D2 -->|"build"| A
    D3 -->|"build"| A
    D4 -->|"trigger"| D1
    D5 -->|"trigger"| D1

    E1 -->|"integrate"| A5

    %% Internal Simulation Core Structure
    A --> A1
    A --> A2
    A --> A3
    A --> A4
    A --> A5

    %% Click Events for File/Directory Mappings
    click A "https://github.com/damask-multiphysics/damask/tree/master/src"
    click A1 "https://github.com/damask-multiphysics/damask/tree/master/src/grid"
    click A2 "https://github.com/damask-multiphysics/damask/tree/master/src/mesh"
    click A3 "https://github.com/damask-multiphysics/damask/blob/master/src/homogenization.f90"
    click A4 "https://github.com/damask-multiphysics/damask/blob/master/src/material.f90"
    click A5 "https://github.com/damask-multiphysics/damask/tree/master/src/Marc"
    click B1 "https://github.com/damask-multiphysics/damask/tree/master/python/damask"
    click B2 "https://github.com/damask-multiphysics/damask/tree/master/python/tests"
    click B3 "https://github.com/damask-multiphysics/damask/tree/master/processing"
    click C1 "https://github.com/damask-multiphysics/damask/tree/master/examples/config"
    click C2 "https://github.com/damask-multiphysics/damask/tree/master/examples/grid"
    click C3 "https://github.com/damask-multiphysics/damask/tree/master/examples/mesh"
    click D1 "https://github.com/damask-multiphysics/damask/blob/master/CMakeLists.txt"
    click D2 "https://github.com/damask-multiphysics/damask/tree/master/cmake/"
    click D3 "https://github.com/damask-multiphysics/damask/tree/master/Makefile"
    click D4 "https://github.com/damask-multiphysics/damask/tree/master/.github/workflows"
    click D5 "https://github.com/damask-multiphysics/damask/blob/master/.gitlab-ci.yml"
    click E1 "https://github.com/damask-multiphysics/damask/tree/master/install/MarcMentat"

    %% Styling Definitions
    classDef core fill:#FFDDCC,stroke:#D35400,stroke-width:2px;
    classDef python fill:#CCF5FF,stroke:#1F618D,stroke-width:2px;
    classDef config fill:#D5F5E3,stroke:#239B56,stroke-width:2px;
    classDef build fill:#FDEBD0,stroke:#CA6F1E,stroke-width:2px;
    classDef install fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
```
