# m2dolab/openlsto architecture

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

- Interactive diagram: https://gitdiagram.com/m2dolab/openlsto
- Repository: https://github.com/m2dolab/openlsto

## Overview

##### Project Type and Purpose
- OpenLSTO is a C++-based, CLI-driven scientific application for level-set topology optimization.
- It is not a web or desktop GUI app but a modular command-line tool split into core libraries (LSM core, FEA core, 3D LSM extension) and example “projects” that invoke these libraries to run specific studies (compliance minimization, stress minimization, hole creation, 3D problems).
- Key use cases: minimize compliance or stress under volume constraints in 2D/3D, generate VTK output for visualization in ParaView.

##### File Structure Analysis
- Top-level:
- M2DO_LSM – core level-set solver (headers + src)
- M2DO_FEA – core finite-element routines (headers + src)
- M2DO_3D_LSM – 3D extension of level-set solver
- projects – client “executables” (compliance, hole_creation, stress_min, 3d)
- docs – user/programmer manuals
- vendor – placeholders for any third-party libs
- Each “project” folder contains a Makefile, source for a main() entry point, and links against the three core modules.
- Build artifacts: object files, binaries under bin/, and .vtk result files for visualization.

##### README Insights
- Describes architecture at a high level: the topology optimization loop (level-set update ↔ FEA analysis).
- Mentions external dependency: ParaView for post-processing.

a. Main Components
1. CLI Executables (“projects”):
- Compliance, StressMin, HoleCreation, 3D
- Each invokes the optimization loop
2. Core Libraries:
- M2DO_LSM (level-set operations, narrow band, reinitialization)
- M2DO_FEA (mesh, elements, solver, quadrature, boundary conditions, sensitivity)
- M2DO_3D_LSM (marching cubes, vector utilities, 3D-specific LSM operations)
3. Data I/O
- Input: design domain definitions (e.g., .stl, parameter files)
- Output: .vtk files for ParaView
4. External Tools
- ParaView (visualization)

b. Component Relationships & Data Flow
- Projects → link & call → Core Libraries
- Core Libraries interactions:
- M2DO_LSM calls M2DO_FEA to compute structural response & sensitivities
- M2DO_FEA returns sensitivities → M2DO_LSM updates level set
- M2DO_3D_LSM extends M2DO_LSM with 3D geometry extraction
- Data flow:
Input parameters → Level-Set Module → FEA Module → Sensitivities → Level-Set update → Convergence check → VTK output → ParaView

c. Architectural Patterns & Principles
- Modular separation of concerns: solver core (LSM) vs. analysis core (FEA) vs. 3D extension
- Static libraries (or object modules) reused by multiple executables
- CLI-centric workflow: no runtime GUI, clear I/O layering
- Batch processing pattern: iterative loop controlled by main()

d. Key Technologies & Libraries
- C++17 (or above)
- Custom mesh, element, and level-set implementations
- Makefiles for build automation
- VTK format for output
- Optionally, third-party libraries under “vendor” (e.g., random number generator, fast marching)

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Projects Layer
    subgraph "Projects" 
        style Compliance fill:#A2E8DD,stroke:#333,stroke-width:1px
        style StressMin fill:#A2E8DD,stroke:#333,stroke-width:1px
        style HoleCreation fill:#A2E8DD,stroke:#333,stroke-width:1px
        style Problem3D fill:#A2E8DD,stroke:#333,stroke-width:1px

        Compliance["Compliance"] 
        StressMin["StressMin"]
        HoleCreation["HoleCreation"]
        Problem3D["3DProblem"]
    end

    %% Core Libraries Layer
    subgraph "Core Libraries"
        style LSM fill:#9BC1BC,stroke:#333,stroke-width:1px
        style FEA fill:#9BC1BC,stroke:#333,stroke-width:1px
        style LSM3D fill:#9BC1BC,stroke:#333,stroke-width:1px

        LSM["M2DO_LSM (Level-Set Solver)"]
        FEA["M2DO_FEA (Finite Element Analysis)"]
        LSM3D["M2DO_3D_LSM (3D Extension)"]
    end

    %% Data & Visualization Layer
    subgraph "Data & Visualization"
        style InputFiles fill:#F3C969,stroke:#333,stroke-width:1px
        style VTKOutput fill:#F3C969,stroke:#333,stroke-width:1px
        style ParaView fill:#F3C969,stroke:#333,stroke-width:1px

        InputFiles["Design Domain Input"]
        VTKOutput[".vtk Output"]
        ParaView["ParaView"]
    end

    %% Relationships
    Compliance -->|"links to"| LSM
    Compliance -->|"links to"| FEA
    StressMin -->|"links to"| LSM
    StressMin -->|"links to"| FEA
    HoleCreation -->|"links to"| LSM
    HoleCreation -->|"links to"| FEA
    Problem3D -->|"links to"| LSM
    Problem3D -->|"links to"| FEA
    Problem3D -->|"links to"| LSM3D

    %% Core interaction loop
    LSM -->|"calls analysis"| FEA
    FEA -->|"returns sensitivities"| LSM
    LSM -->|"extends for 3D"| LSM3D

    %% Data flow
    InputFiles -->|"reads parameters"| LSM
    InputFiles -->|"reads mesh"| FEA
    LSM -->|"writes level-set data"| VTKOutput
    FEA -->|"writes results"| VTKOutput
    VTKOutput -->|"visualize"| ParaView

    %% Click Events for Projects
    click Compliance "https://github.com/m2dolab/openlsto/blob/master/projects/compliance/main.cpp"
    click StressMin "https://github.com/m2dolab/openlsto/blob/master/projects/stress_min/lbeam.cpp"
    click HoleCreation "https://github.com/m2dolab/openlsto/blob/master/projects/hole_creation/main.cpp"
    click Problem3D "https://github.com/m2dolab/openlsto/blob/master/projects/3d/comp_min.cpp"

    %% Click Events for Core Libraries
    click LSM "https://github.com/m2dolab/openlsto/blob/master/M2DO_LSM/include/M2DO_LSM.h"
    click FEA "https://github.com/m2dolab/openlsto/blob/master/M2DO_FEA/include/M2DO_FEA.h"
    click LSM3D "https://github.com/m2dolab/openlsto/blob/master/M2DO_3D_LSM/lsm_3d.h"

    %% Styles
    classDef projects fill:#A2E8DD,stroke:#333,stroke-width:1px
    classDef core fill:#9BC1BC,stroke:#333,stroke-width:1px
    classDef data fill:#F3C969,stroke:#333,stroke-width:1px
    class Compliance,StressMin,HoleCreation,Problem3D projects
    class LSM,FEA,LSM3D core
    class InputFiles,VTKOutput,ParaView data
```
