How uiocompcat/tmcinvdes works
Project Type and Purpose
• This is a scientific data‐processing and machine‐learning pipeline for the inverse design of transition metal ligands and complexes (“tmcinvdes”).
• It integrates data preparation, generative modeling (JT-VAE), quantum‐chemistry calculations (ORCA), and analysis steps to produce labeled ligand datasets and optimized complexes.
High-Level Architecture Overview
The system can be represented as a linear, modular pipeline with five main stages:
a. Environment & Dependencies
• Conda environment (environment/tmcinvdes.yml)
• External repositories:
– tmQMg-L (raw ligand library)
– JT-VAE-tmcinvdes (training & generative model)
• ORCA quantum‐chemistry executable
b. Data Ingestion & Preparation
• Bash scripts (bash/*.sh) orchestrate calls to Python modules
• Input: raw tmQMg-L datasets
• Output: cleaned, encoded SMILES and sampled ligand subsets
c. Ligand Generation Module (tmcinvdes/ligand_generation)
• Python scripts: get_encoded_smiles.py, sample_ligands_to_optimize.py, etc.
• Purpose: produce training sets for JT-VAE and generate new ligands
d. Structure Generation Module (tmcinvdes/structure_generation)
• assemble_tmcs.py, batch_add_ligands.py, molsimplify_tools.py
• Purpose: build 3D TMC structures (XYZ) from ligand SMILES
e. Quantum‐Chemistry Module (tmcinvdes/quantum_chemistry)
• Scripts: orca_parsers.py, parse_orca_to_labels.py, CM5 charge analysis
• Purpose: generate ORCA input, submit ORCA jobs, parse DFT results
• Output: labeled datasets with target properties
f. Analysis Module (tmcinvdes/analysis)
• exclude_outliers.py, SA score code under analysis/sa/
• Purpose: post‐processing, outlier filtering, synthetic accessibility scoring
Interactions and Data Flow
• Directional flow: Raw Dataset → Data Prep → Ligand Generation → Structure Generation → ORCA Execution → Label Parsing → Analysis → Final Datasets
• Bash scripts glue the Python modules together and manage filesystem artifacts under datasets/
• Python modules communicate via files (CSV, TXT, XYZ) in the datasets hierarchy
• External processes:
• ORCA (quantum chemistry) invoked from bash or Python
• JT-VAE training and sampling invoked via separate codebase (external)
Architectural Patterns & Principles
• Modular “stage‐based” pipeline: each directory is a clear logical component
• File‐based message passing: modules read/write artifacts in datasets/NN_*
• Shell‐script orchestration keeps Python code focused on single responsibility
• Use of configuration files: pyproject.toml for packaging, conda .yml for reproducibility
Checklist
[ ] Clouds for ORCA and external model code
[ ] Callouts for environment setup (conda .yml) and version control (pyproject.toml)