# ojimenezn/geometry-optim architecture

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

- Interactive diagram: https://gitdiagram.com/ojimenezn/geometry-optim
- Repository: https://github.com/ojimenezn/geometry-optim

## Overview

##### Project type and purpose
- This repository implements an ML-driven geometry‐optimization and clustering workflow for molecular simulation. It is not a web or full‐stack app but a research tool comprising:
- Google Colab notebooks (Python/Jupyter) as the user interface
- A set of Python “utils” scripts for data processing, ML training, and orchestration
- C++ fingerprint libraries (Behler–Parrinello module from SIMPLE-NN) wrapped into Python via FFI
- An external EMT potential engine (Effective Medium Theory) used in place of DFT

##### File structure
- Top‐level items:
- images/ – static assets (workflow illustration)
- optim-emt.ipynb – main Colab notebook driving the active‐learning workflow
- utils/ – supporting scripts and modules:
– NN_calc.py, fp_calculator.py, train_agent_surf_frs.py (Python logic for ML and data pipelines)
– gen_ffi.py, libsymf_builder.py, mpiclass.py (FFI wrapper generation, build helpers)
– calculate_sf.cpp/h, symmetry_functions.cpp/h (C++ fingerprint implementations)
– calculate_sf.h (header), calculate_sf.cpp (implementation)

##### Extract key architecture insights from README
- Central workflow: active‐learning loop in the Colab notebook, alternating between:
a. Geometry‐optimization via ML surrogate
b. EMT potential evaluation (external engine)
c. Data‐collection & fingerprint generation (C++ library)
d. Model retraining (Python ML agent)
e. Clustering analysis on adsorption site space
- Dependencies: Python 3.x, Jupyter, C++ toolchain, SIMPLE-NN C++ fingerprint code

a. Main components
1. User Interface: Google Colab Notebook (optim-emt.ipynb)
2. Python Orchestrator: utils/*.py scripts
3. C++ Fingerprint Library: calculate_sf.cpp/h, symmetry_functions.* wrapped by gen_ffi
4. ML Agent: train_agent_surf_frs.py (model training/inference)
5. EMT Potential Engine (external binary)
6. Data Storage: dataset files, model weights, clustering results
7. Visualization: inline plots in notebook

b. Relationships & interactions
- Notebook invokes Python modules (NN_calc, fp_calculator, train_agent_surf_frs).
- Python modules call into the C++ fingerprint lib via FFI (gen_ffi outputs .so/.pyd).
- ML Agent reads fingerprints and feeds predictions to the geometry‐optimizer.
- Geometry‐optimizer calls EMT engine (shell process or Python binding) for energy/force evaluations.
- Results flow back to Python for data aggregation, retraining, and clustering.
- Final outputs (optimized structures, clusters, plots) are rendered in the notebook.

c. Architectural patterns & design principles
– Modular separation: notebooks (UI/orchestration) vs. utils (business logic) vs. C++ libs (compute kernels)
– FFI boundary clearly separates high‐performance code from Python logic
– Active-learning feedback loop (data → train → predict → update)
– Reproducibility focus: encapsulate environment in Colab

d. Key technologies/frameworks
– Python ecosystem: NumPy/Pandas, Jupyter, scikit-learn (clustering), PyTorch or TensorFlow (if used)
– C++ (Behler–Parrinello fingerprint code from SIMPLE-NN)
– FFI tooling: SWIG or custom bindings generated by gen_ffi.py
– EMT potential (external compiled library)

##### Detail & coverage
- Every essential piece: FFI generation (gen_ffi.py → dynamic library), fingerprint source files, ML training pipeline, clustering scripts
- Configuration/build steps (libsymf_builder.py compiles C++ code)
- Versioning or environment notes (Python 3.x, required pip packages)

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "UI Layer"
        UI["Google Colab Notebook"]:::ui
    end

    subgraph "Python Orchestrator"
        NN["NN_calc.py"]:::python
        FP["fp_calculator.py"]:::python
        MPI["mpiclass.py"]:::python
        AG["train_agent_surf_frs.py"]:::python
        GFI["gen_ffi.py"]:::python
        LB["libsymf_builder.py"]:::python
    end

    subgraph "C++ Fingerprint Library"
        CSrc["calculate_sf.cpp/h"]:::cpp
        SD["symmetry_functions.cpp/h"]:::cpp
        Dyn["Fingerprint .so/.pyd"]:::cpp
    end

    Ext["EMT Potential Engine"]:::external

    DB1[(Datasets)]:::data
    DB2[(Model Weights)]:::data
    DB3[(Clustering Results)]:::data

    %% Workflow arrows
    UI --> NN
    UI --> FP
    UI --> AG

    NN -->|"generate fingerprints"| Dyn
    FP -->|"orchestrate fingerprints"| Dyn
    Dyn -->|"loaded via FFI"| NN
    Dyn -->|"loaded via FFI"| FP

    GFI -->|"generate FFI bindings"| Dyn
    LB -->|"compile C++ libs"| Dyn

    NN -->|"writes"| DB1
    FP -->|"reads/writes"| DB1
    AG -->|"trains model on"| DB1
    AG -->|"outputs weights to"| DB2
    FP -->|"performs clustering on"| DB1
    FP -->|"writes clusters to"| DB3

    FP -->|"calls for energy eval"| Ext
    Ext -->|"returns energies/forces"| FP

    AG -->|"model metrics & checkpoints"| UI
    FP -->|"visualization plots"| UI

    %% Click Events
    click UI "https://github.com/ojimenezn/geometry-optim/blob/master/optim-emt.ipynb"
    click NN "https://github.com/ojimenezn/geometry-optim/blob/master/utils/NN_calc.py"
    click FP "https://github.com/ojimenezn/geometry-optim/blob/master/utils/fp_calculator.py"
    click MPI "https://github.com/ojimenezn/geometry-optim/blob/master/utils/mpiclass.py"
    click AG "https://github.com/ojimenezn/geometry-optim/blob/master/utils/train_agent_surf_frs.py"
    click GFI "https://github.com/ojimenezn/geometry-optim/blob/master/utils/gen_ffi.py"
    click LB "https://github.com/ojimenezn/geometry-optim/blob/master/utils/libsymf_builder.py"
    click CSrc "https://github.com/ojimenezn/geometry-optim/blob/master/utils/calculate_sf.cpp"
    click SD "https://github.com/ojimenezn/geometry-optim/blob/master/utils/symmetry_functions.cpp"

    %% Styles
    classDef ui fill:#cce5ff,stroke:#333,stroke-width:1px
    classDef python fill:#ccffcc,stroke:#333,stroke-width:1px
    classDef cpp fill:#ffddcc,stroke:#333,stroke-width:1px
    classDef external fill:#e0e0e0,stroke:#333,stroke-width:1px
    classDef data fill:#ffffcc,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
```
