How ojimenezn/geometry-optim works
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)