How bessagroup/f3dasm works
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).