# uiocompcat/tmcinvdes architecture

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

- Interactive diagram: https://gitdiagram.com/uiocompcat/tmcinvdes
- Repository: https://github.com/uiocompcat/tmcinvdes

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
graph TB
    %% External Dependencies
    ext1["tmQMg-L Repo"]:::external
    ext2["JT-VAE-tmcinvdes"]:::external
    orca["ORCA"]:::external

    %% Environment & Dependencies
    subgraph "Environment & Dependencies"
        env["environment/tmcinvdes.yml"]:::code
        pj["pyproject.toml"]:::code
    end

    %% Data Ingestion & Preparation
    subgraph "Data Ingestion & Preparation"
        bash1["bash/get_encoded_smiles-*.sh"]:::code
        bash2["bash/sample_ligands_to_optimize-*.sh"]:::code
        bash3["bash/assemble_tmcs-*.sh"]:::code
        bash4["bash/parse_orca_to_labels-*.sh"]:::code
        bash5["bash/exclude_outliers-*.sh"]:::code
        bash6["bash/screen_generated_ligands-*.sh"]:::code
        bash7["bash/select_Xk_smallest_ligands-*.sh"]:::code
    end

    %% Ligand Generation Module
    subgraph "Ligand Generation Module"
        lg1["get_encoded_smiles.py"]:::code
        lg2["sample_ligands_to_optimize.py"]:::code
        lg3["screen_generated_ligands.py"]:::code
        lg4["select_Xk_smallest_ligands.py"]:::code
        lg5["utils.py"]:::code
        lg6["xyz2mol_functionality.py"]:::code
        lg7["discarded_ligand_ids.txt"]:::data
    end

    %% Structure Generation Module
    subgraph "Structure Generation Module"
        sg1["assemble_tmcs.py"]:::code
        sg2["batch_add_ligands.py"]:::code
        sg3["molsimplify_tools.py"]:::code
    end

    %% Quantum-Chemistry Module
    subgraph "Quantum-Chemistry Module"
        qc1["orca_parsers.py"]:::code
        qc2["parse_orca_to_labels.py"]:::code
        qc3["cm5.py"]:::code
        qc4["cm5pars.json"]:::data
    end

    %% Analysis Module
    subgraph "Analysis Module"
        an1["exclude_outliers.py"]:::code
        an2["sa/sascorer.py"]:::code
        an3["sa/neutralize.py"]:::code
        an4["sa/fpscores.pkl.gz"]:::data
        an5["sa/neutralize.json"]:::data
    end

    %% Dataset Storage
    subgraph "Data Stores"
        D01[(01_tmQMg-L-training_sets)]:::data
        D02[(02_uncond-trained_models)]:::data
        D03[(03_uncond-raw50k-generated_ligands)]:::data
        D04[(04_uncond_novel)]:::data
        D05[(05_uncond_minXk)]:::data
        D06[(06_uncond-TMC)]:::data
        D07[(07_uncond-labeled)]:::data
        D08a[(08a_uncond-excluded)]:::data
        D08b[(08b_uncond-included)]:::data
        D09[(09_cond-trained_models)]:::data
        D10[(10_uncond-sampled_from_8b)]:::data
        D11[(11_cond-optimized)]:::data
        D12[(12_cond-TMC)]:::data
        D13[(13_cond-labeled)]:::data
    end

    %% Data and Control Flow
    ext1 -->|raw SMILES| bash1
    bash1 -->|SMILES.csv| lg1
    lg1 --> D01
    D01 --> bash2
    bash2 -->|sampled.csv| lg2
    lg2 --> D03
    D03 --> lg3
    lg3 --> D08a
    lg3 --> D08b
    D08b --> lg4
    lg4 --> D05
    D05 --> sg1
    sg1 --> D06
    D06 --> sg2
    sg2 --> D06
    D06 --> qc1
    qc1 --> qc2
    qc2 --> D07
    D07 --> an1
    an1 --> D08a
    D08b --> an2
    an2 --> D13

    ext2 -->|JT-VAE training/sample| lg2
    orca -->|DFT jobs| qc1

    %% Click Events
    click env "https://github.com/uiocompcat/tmcinvdes/blob/main/environment/tmcinvdes.yml"
    click pj "https://github.com/uiocompcat/tmcinvdes/blob/main/pyproject.toml"
    click bash1 "https://github.com/uiocompcat/tmcinvdes/blob/main/bash/get_encoded_smiles-*.sh"
    click bash2 "https://github.com/uiocompcat/tmcinvdes/blob/main/bash/sample_ligands_to_optimize-*.sh"
    click bash3 "https://github.com/uiocompcat/tmcinvdes/blob/main/bash/assemble_tmcs-*.sh"
    click bash4 "https://github.com/uiocompcat/tmcinvdes/blob/main/bash/parse_orca_to_labels-*.sh"
    click bash5 "https://github.com/uiocompcat/tmcinvdes/blob/main/bash/exclude_outliers-*.sh"
    click bash6 "https://github.com/uiocompcat/tmcinvdes/blob/main/bash/screen_generated_ligands-*.sh"
    click bash7 "https://github.com/uiocompcat/tmcinvdes/blob/main/bash/select_Xk_smallest_ligands-*.sh"
    click lg1 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/ligand_generation/get_encoded_smiles.py"
    click lg2 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/ligand_generation/sample_ligands_to_optimize.py"
    click lg3 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/ligand_generation/screen_generated_ligands.py"
    click lg4 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/ligand_generation/select_Xk_smallest_ligands.py"
    click lg5 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/ligand_generation/utils.py"
    click lg6 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/ligand_generation/xyz2mol_functionality.py"
    click lg7 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/ligand_generation/discarded_ligand_ids.txt"
    click sg1 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/structure_generation/assemble_tmcs.py"
    click sg2 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/structure_generation/batch_add_ligands.py"
    click sg3 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/structure_generation/molsimplify_tools.py"
    click qc1 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/quantum_chemistry/orca_parsers.py"
    click qc2 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/quantum_chemistry/parse_orca_to_labels.py"
    click qc3 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/quantum_chemistry/cm5.py"
    click qc4 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/quantum_chemistry/cm5pars.json"
    click an1 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/analysis/exclude_outliers.py"
    click an2 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/analysis/sa/sascorer.py"
    click an3 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/analysis/sa/neutralize.py"
    click an4 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/analysis/sa/fpscores.pkl.gz"
    click an5 "https://github.com/uiocompcat/tmcinvdes/blob/main/tmcinvdes/analysis/sa/neutralize.json"

    %% Styles
    classDef code fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
    classDef data fill:#90EE90,stroke:#000,stroke-width:1px
```
