# dlr-wf/crackpy architecture

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

- Interactive diagram: https://gitdiagram.com/dlr-wf/crackpy
- Repository: https://github.com/dlr-wf/crackpy

## Overview

##### Project Type and Purpose
- CrackPy is a scientific Python library/pipeline (not a web or mobile app) for automated fatigue crack detection and fracture‐mechanical analysis.
- It ingests full‐field displacement/strain data (“nodemap” files) from DIC or simulation, detects crack paths/tips (via image‐based ML or line-intercept), then computes fracture parameters (J-integral, stress intensity factors, Williams and CJP fits).

##### File Structure
Top‐level:
- crackpy/                                  ← core Python package
– structure_elements/                     ← domain model (Material, data file classes)
– crack_detection/                        ← crack path & tip detection module
- data/                                 ← data preparation, preprocessing, interpolation
- deep_learning/                        ← CNN architectures, training scripts (PyTorch)
- pipeline/                             ← high-level orchestration of detection steps
- utils/                                ← plotting, evaluation, generic helpers
– fracture_analysis/                      ← fracture mechanics algorithms & pipelines
– tests/                                  ← extensive unit tests
- scripts/                                  ← ready-to-run CLI scripts for demos & pipelines
- test_data/                                ← sample input files & expected outputs
- setup.py, requirements.txt, CI configs

##### README for Additional Insights
- Illustrates data flow: from nodemap input → crack detection → fracture analysis → plots/outputs
- Mentions external dependencies: GOM Aramis (DIC) and Ansys (simulation) as data sources
- Lists core modules: structure_elements, dic, simulation, crack_detection, fracture_analysis

##### Main Components and Their Interactions
A. Data Ingestion
- External Sources:
– DIC software (GOM Aramis)
– Finite‐element software (Ansys)
- “dic” & “simulation” submodules (not in code tree but referenced) transform raw outputs into standardized nodemap files (.txt)

B. Domain Model
- structure_elements.Material & .DataFile classes
- Nodemap class defines the schema for node coordinates, displacements, strains, metadata

C. Crack Detection Module
1. Data preprocessing (transforms, interpolation, normalization)
2. Two detection routes:
– Line‐intercept + iterative Williams‐based correction
– CNN‐based detection (attention, nets.py, train.py)
3. Pipeline orchestrator to sequence steps and save detected crack tip/path metadata

D. Fracture Analysis Module
- Takes nodemap + crack tip metadata → computes:
– J-integral (Rice’s path‐independent integral)
– Interaction integral (mixed mode SIFs)
– Conjugate‐work integral (Williams coefficients)
– Higher‐order term fits (HOST/HORT)
– CJP model fits
- Provides pipeline.py to run selected analysis methods over time‐series

E. Utilities & Output
- Plotting (matplotlib; plot.py)
- Evaluation metrics (evaluate.py)
- File I/O (read/write modules in fracture_analysis)
- Scripts folder wraps pipelines into CLI tools for batch processing

##### Architectural Patterns & Design Principles
- Domain modeling: structure_elements module encapsulates core types
- Plugin/extension: new detection methods or fracture‐analysis routines can drop into pipelines
- Test‐driven: comprehensive tests ensure each component’s correctness
- Data flow oriented: directional, stage‐by‐stage transformations

##### Technologies & Frameworks to Annotate
- Python 3.x
- PyTorch (deep_learning/nets.py, attention, train.py)
- NumPy/SciPy (numeric ops, interpolation, fitting)
- Matplotlib (plotting)
- pandas (results.csv reading)
- CLI scripts (entry points using Python scripts under scripts/)

##### Final Recommendations
- Be exhaustive but clear: capture every top-level package and script group
- Optional paths (e.g., if using DIC vs. simulation ingestion)
- File‐based interfaces (e.g., “.txt nodemap” passes between stages)
- Extension points (e.g., where new detection or analysis methods plug in)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% External Sources
    subgraph "External Data Sources"
        direction TB
        DIC["GOM Aramis (DIC)"]:::external
        ANSYS["Ansys (FE)"]:::external
    end

    %% Data Ingestion
    subgraph "Data Ingestion" 
        direction TB
        Ingest["nodemap_to_vtk.py"]:::processing
    end

    %% Domain Model
    subgraph "Domain Model" 
        direction TB
        Material["material.py"]:::data
        DataFile["data_files.py"]:::data
    end

    %% Crack Detection Module
    subgraph "Crack Detection" 
        direction TB
        subgraph "Data Preprocessing" 
            direction TB
            Preprocess["preprocess.py"]:::processing
            Interpolate["interpolation.py"]:::processing
            Transforms["transforms.py"]:::processing
        end
        LineIntercept["line_intercept.py"]:::processing
        Correction["correction.py"]:::processing
        subgraph "Deep Learning (ML)" 
            direction TB
            Nets["nets.py"]:::ml
            Attention["attention.py"]:::ml
            Train["train.py"]:::ml
            Loss["loss.py"]:::ml
        end
        PipelineDet["pipeline.py"]:::processing
        subgraph "Detection Utils" 
            direction TB
            CDPlot["plot.py"]:::util
            Evaluate["evaluate.py"]:::util
            Basic["basic.py"]:::util
        end
    end

    %% Fracture Analysis Module
    subgraph "Fracture Analysis" 
        direction TB
        Analysis["analysis.py"]:::processing
        LineInt["line_integration.py"]:::processing
        Optimization["optimization.py"]:::processing
        TipMeta["crack_tip.py"]:::data
        ReadIO["read.py"]:::util
        WriteIO["write.py"]:::util
        PipelineFA["pipeline.py"]:::processing
        FAPlot["plot.py"]:::util
    end

    %% Scripts
    subgraph "CLI Scripts" 
        direction TB
        CDPipe["cd_pipeline.py"]:::util
        CDLI["crack_detection_line_intercept.py"]:::util
        FADIC["fracture_analysis_dic.py"]:::util
        FAPipe["fracture_analysis_pipeline_fem.py"]:::util
    end

    %% Outputs & Tests
    ExampleImgs["example_images"]:::util
    TestDataCD["test_data/crack_detection"]:::external
    TestDataFA["test_data/fracture_analysis"]:::external
    subgraph "Unit Tests"
        direction TB
        TestCD["test_crack_detection"]:::external
        TestFA["test_fracture_analysis"]:::external
        TestSE["test_structure_elements"]:::external
    end

    %% Connections
    DIC -->|".txt nodemap"| Ingest
    ANSYS -->|".txt nodemap"| Ingest
    Ingest --> Material
    Ingest --> DataFile
    Material --> Preprocess
    DataFile --> Preprocess
    Preprocess --> Interpolate
    Interpolate --> Transforms
    Transforms --> LineIntercept
    Transforms --> Nets
    LineIntercept --> Correction
    Correction --> PipelineDet
    Nets --> Train
    Train --> PipelineDet
    Loss --> Train
    Attention --> Train
    PipelineDet --> TipMeta
    TipMeta --> Analysis
    Analysis --> LineInt
    LineInt --> Optimization
    Optimization --> PipelineFA
    ReadIO --> Analysis
    WriteIO --> Analysis
    PipelineFA --> FAPlot
    FAPlot --> ExampleImgs
    PipelineDet --> ExampleImgs
    CDPipe --> PipelineDet
    CDLI --> PipelineDet
    FADIC --> PipelineFA
    FAPipe --> PipelineFA
    ExampleImgs -->|outputs| TestDataCD
    ExampleImgs -->|outputs| TestDataFA
    TestCD --> PipelineDet
    TestFA --> PipelineFA
    TestSE --> Material

    %% Click Events
    click Ingest "https://github.com/dlr-wf/crackpy/blob/main/scripts/vtk_converter/nodemap_to_vtk.py"
    click Material "https://github.com/dlr-wf/crackpy/blob/main/crackpy/structure_elements/material.py"
    click DataFile "https://github.com/dlr-wf/crackpy/blob/main/crackpy/structure_elements/data_files.py"
    click Preprocess "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/data/preprocess.py"
    click Interpolate "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/data/interpolation.py"
    click Transforms "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/data/transforms.py"
    click LineIntercept "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/line_intercept.py"
    click Correction "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/correction.py"
    click Nets "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/deep_learning/nets.py"
    click Attention "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/deep_learning/attention.py"
    click Train "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/deep_learning/train.py"
    click Loss "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/deep_learning/loss.py"
    click PipelineDet "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/pipeline/pipeline.py"
    click CDPlot "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/utils/plot.py"
    click Evaluate "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/utils/evaluate.py"
    click Basic "https://github.com/dlr-wf/crackpy/blob/main/crackpy/crack_detection/utils/basic.py"
    click Analysis "https://github.com/dlr-wf/crackpy/blob/main/crackpy/fracture_analysis/analysis.py"
    click LineInt "https://github.com/dlr-wf/crackpy/blob/main/crackpy/fracture_analysis/line_integration.py"
    click Optimization "https://github.com/dlr-wf/crackpy/blob/main/crackpy/fracture_analysis/optimization.py"
    click TipMeta "https://github.com/dlr-wf/crackpy/blob/main/crackpy/fracture_analysis/crack_tip.py"
    click ReadIO "https://github.com/dlr-wf/crackpy/blob/main/crackpy/fracture_analysis/read.py"
    click WriteIO "https://github.com/dlr-wf/crackpy/blob/main/crackpy/fracture_analysis/write.py"
    click PipelineFA "https://github.com/dlr-wf/crackpy/blob/main/crackpy/fracture_analysis/pipeline.py"
    click FAPlot "https://github.com/dlr-wf/crackpy/blob/main/crackpy/fracture_analysis/plot.py"
    click CDPipe "https://github.com/dlr-wf/crackpy/blob/main/scripts/crack_detection/cd_pipeline.py"
    click CDLI "https://github.com/dlr-wf/crackpy/blob/main/scripts/crack_detection/crack_detection_line_intercept.py"
    click FADIC "https://github.com/dlr-wf/crackpy/blob/main/scripts/fracture_analysis/fracture_analysis_dic.py"
    click FAPipe "https://github.com/dlr-wf/crackpy/blob/main/scripts/fracture_analysis/fracture_analysis_pipeline_fem.py"

    %% Styles
    classDef data fill:#D6EAF8,stroke:#1B4F72,color:#1B2631
    classDef processing fill:#D5F5E3,stroke:#145A32,color:#0B5345
    classDef ml fill:#FAD7A0,stroke:#9A7D0A,color:#7E5109
    classDef util fill:#E5E8E8,stroke:#616A6B,color:#1C2833
    classDef external fill:#FDEDEC,stroke:#943126,color:#641E16
```
