# bessagroup/f3dasm architecture

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

- Interactive diagram: https://gitdiagram.com/bessagroup/f3dasm
- Repository: https://github.com/bessagroup/f3dasm

## Overview

##### Project type and purpose
- f3dasm is a Python library/framework (not a web app) for data‐driven design and analysis of structures and materials.
- It provides a command‐line interface (via an internal argparser), a core orchestration engine, modules for data generation, design definition, sampling, optimization, experiment data management, Hydra integration, logging, and parallel execution utilities (MPI).

##### File structure
- `src/f3dasm/_src` contains the core modules:
- `_argparser.py` – CLI entry point
- `_io.py` – reading/writing experiment data
- `core.py` – central orchestrator
- `datageneration/` – factories and implementations for generating input data
- `design/` – domain and parameter definitions
- `optimization/` – sampler and optimizer factories and adapters (NumPy, SciPy)
- `samplers.py` – sampling strategies
- `experimentdata.py` & `experimentsample.py` – data abstractions
- `hydra_utils.py` – Hydra config integration
- `mpi_utils.py` – parallelization support
- `logger.py` – central logging
- The top‐level `src/f3dasm` provides user-facing entry points (wrappers around `_src`).
- `studies/` holds example scripts and configs (e.g., Hydra configs, domain definitions) showing how to run experiments.
- `docs/` and `tests/` are orthogonal to runtime but indicate stable API and examples.

##### Extract insights from the README
- Emphasizes modular design, automatic I/O, parallelization, built‐in benchmarks, Hydra support.

##### Main components & their interactions
a. Components
1. CLI Layer (ArgParser)
2. Configuration Layer (Hydra)
3. Core Engine
4. Design Module (domain, parameter)
5. Data Generation Module (factory + functions/adapters)
6. Sampling Module
7. Optimization Module
8. Experiment Data Management (ExperimentData, ExperimentSample, IO)
9. Parallel Execution (MPI Utils)
10. Logging
11. External Dependencies (NumPy, SciPy, Hydra, file system, HPC cluster)
b. Interactions
- User invokes CLI → ArgParser reads command → Hydra loads & validates config → Core Engine initializes Design, DataGeneration, Sampler, Optimizer
- Design module defines domain & parameters → DataGeneration factory uses functions/adapters to generate input sets
- Sampler module generates sample points (grid, random, categorical)
- Optimizer module selects and runs optimization algorithms on the generated data
- All runs produce ExperimentSample outputs → ExperimentData aggregates samples → IO writes results to disk
- MPI Utils wrap loops to distribute work across local cores or an HPC cluster
- Logger captures progress, warnings, and debug info
c. Architectural patterns & principles
- Factory pattern (datagenerator_factory, optimizer_factory)
- Adapter pattern (wrapping SciPy/Numpy implementations)
- Separation of concerns (design vs. generation vs. sampling vs. optimization vs. I/O)
- Plug‐in / modular architecture (users can supply custom functions, optimizers, samplers)
- Configuration‐driven flow (Hydra integration for experiments)
d. Key technologies
- Python (3.x)
- Hydra (configuration manager)
- NumPy, SciPy (numerical tools)
- MPI4Py or custom MPI utils (parallelization)
- File system (JSON/CSV for experiment data)
- pytest (testing), Sphinx/ReadTheDocs (documentation)

##### Detail
- Module from `src/f3dasm/_src`.
- Core modules (blue),
- Configuration & orchestration (orange),
- External libs/services (green).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Entry and configuration
    CLI["CLI Layer (ArgParser)"]:::orchestration --> HydraUtils["Configuration Layer (Hydra)"]:::orchestration
    click CLI "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/_argparser.py"
    click HydraUtils "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/hydra_utils.py"
    
    %% Core engine and modules
    HydraUtils -.-> CoreEngine
    subgraph "Core Engine" 
        direction TB
        CoreEngine["Core Engine"]:::core
        click CoreEngine "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/core.py"
        
        CoreEngine --> DesignDomain["Design Module: Domain Definitions"]:::core
        click DesignDomain "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/design/domain.py"
        
        CoreEngine --> DesignParam["Design Module: Parameter Definitions"]:::core
        click DesignParam "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/design/parameter.py"
        
        CoreEngine --> DataGenFactory["Data Generation: Factory"]:::core
        click DataGenFactory "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/datageneration/datagenerator_factory.py"
        
        DataGenFactory --> DataGenFunc["Data Generation: Built-in Functions"]:::core
        click DataGenFunc "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/datageneration/functions/function.py"
        
        DataGenFunc --> DataGenAdapter["Data Generation: Adapters"]:::core
        click DataGenAdapter "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/datageneration/functions/adapters/augmentor.py"
        click DataGenAdapter "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/datageneration/functions/adapters/pybenchfunction.py"
        
        CoreEngine --> Sampling["Sampling Module"]:::core
        click Sampling "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/samplers.py"
        
        CoreEngine --> OptFactory["Optimization: Factory"]:::core
        click OptFactory "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/optimization/optimizer_factory.py"
        
        OptFactory --> OptNumPy["Optimization: NumPy Implementations"]:::core
        click OptNumPy "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/optimization/numpy_implementations.py"
        
        OptFactory --> OptSciPy["Optimization: SciPy Adapters"]:::core
        click OptSciPy "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/optimization/adapters/scipy_implementations.py"
        
        CoreEngine --> ExperimentData["Experiment Data Management: ExperimentData"]:::core
        click ExperimentData "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/experimentdata.py"
        
        CoreEngine --> ExperimentSample["Experiment Data Management: ExperimentSample"]:::core
        click ExperimentSample "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/experimentsample.py"
        
        CoreEngine --> IO["I/O Module"]:::core
        click IO "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/_io.py"
        
        CoreEngine --> Logger["Logging"]:::core
        click Logger "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/logger.py"
        
        CoreEngine --> MPIUtils["Parallel Execution (MPI Utils)"]:::core
        click MPIUtils "https://github.com/bessagroup/f3dasm/blob/main/src/f3dasm/_src/mpi_utils.py"
    end

    %% Pipeline flows
    DesignDomain --> DataGenFactory
    DesignParam --> DataGenFactory
    DataGenFactory --> Sampling
    Sampling --> OptFactory
    Sampling --> ExperimentSample
    OptFactory --> ExperimentSample
    ExperimentSample --> ExperimentData
    ExperimentData --> IO
    IO --> Disk["Disk (JSON/CSV)"]:::datastore
    
    %% Cross-cutting
    MPIUtils -.-> Sampling
    MPIUtils -.-> OptFactory
    MPIUtils -.-> IO
    
    %% External dependencies
    subgraph "External Dependencies"
        direction TB
        HydraExt["Hydra"]:::external
        NumPyExt["NumPy"]:::external
        SciPyExt["SciPy"]:::external
        FSExt["File System"]:::external
        HPCExt["HPC Cluster"]:::external
    end
    
    HydraExt -.-> HydraUtils
    NumPyExt -.-> OptNumPy
    SciPyExt -.-> OptSciPy
    FSExt -.-> Disk
    HPCExt -.-> MPIUtils

    %% User extensions (optional)
    CustomGen["Custom DataGen Adapter"]:::external
    DataGenFactory -.-> CustomGen

    %% Styles
    classDef orchestration fill:#f9d19b,stroke:#f4a261,color:#000;
    classDef core fill:#a8dadc,stroke:#457b9d,color:#000;
    classDef external fill:#ccebc5,stroke:#1b5e20,color:#000;
    classDef datastore fill:#e0e0e0,stroke:#4f4f4f,color:#000;
```
