How nicola-decao/molgan works
Main Components
a. External Dependencies (outside your codebase)
• TensorFlow, RDKit, NumPy, scikit-learn (defined in environment.yml and README).
b. Data Layer
• data/download_dataset.sh
• utils/sparse_molecular_dataset.py (converts raw files into graph tensors).
c. Model Layer
• models/gan.py (Generator & Discriminator classes)
• models/vae.py (Encoder & Decoder classes)
d. Optimizer/Training Layer
• optimizers/gan.py (GAN-specific loss, gradient updates, WGAN variant, RL reward)
• optimizers/vae.py (VAE-specific ELBO loss)
• utils/trainer.py (high-level training loop orchestrator)
e. Utility Layer
• utils/layers.py (graph convolutional layers, MLPs)
• utils/molecular_metrics.py (validity, uniqueness, novelty calculators)
• utils/progress_bar.py (CLI progress reporting)
• utils/utils.py (misc helpers)
f. Entry Point
• example.py (demonstrates how to wire Data → Model → Optimizer → Trainer → Metrics)
Relationships & Data Flow
• The user runs example.py, which:
1. Executes download_dataset.sh (optional)
2. Invokes sparse_molecular_dataset to load and preprocess graphs
3. Instantiates a MolGAN model (GAN or VAE) from models/
4. Instantiates the corresponding Optimizer from optimizers/
5. Passes model, optimizer, and dataset into utils/trainer.Trainer
6. Trainer uses utils/layers to build TF graph, runs training loop, calls utils/molecular_metrics after each epoch
7. Outputs trained model checkpoints and metric logs to disk
Architectural Patterns & Principles
• Layered architecture: clear separation of concerns (Data → Model → Optimizer → Trainer → Utilities).
• Dependency Injection: example.py selects implementations and injects into Trainer.
• Modular extensibility: adding a new model or optimizer is as simple as implementing the same abstract interface.
• Functional data pipeline: raw files → sparse graphs → TensorFlow tensors.