# nvidia-digital-bio/reasyn architecture

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

- Interactive diagram: https://gitdiagram.com/nvidia-digital-bio/reasyn
- Repository: https://github.com/nvidia-digital-bio/reasyn

## Overview

##### Project type and purpose
- This is a research-grade, full-pipeline machine learning framework for molecular synthesizability (“ReaSyn”).
- It provides:
- Data preparation and featurization of chemical building blocks and reaction templates
- A PyTorch-based sequence-to-sequence model (encoder/decoder with chain-of-reaction notation)
- Training (supervised and RL-based finetuning)
- Inference (sampling, reconstruction, optimization, hit expansion, pathway filtering)
- Evaluation scripts

##### File structure
Top-level directories:
- assets, data, data_card, license_data, license_thirdparty, model_card: static assets, data set organization, documentation
- configs: YAML configs for preprocessing, training, finetuning
- reasyn: core Python package with subpackages:
- chem: molecule/reaction representations, featurization, fingerprint indexing
- data: dataset, collate helper, common utilities
- models: encoder, decoder, transformer-style model “reasyn,” classifier/regressor heads
- sampler: parallel sampling engine, state pool
- trainer: supervised (autoregressive) and RL finetuning modules
- utils: mutation, crossover, CLI training loop helpers
- scripts: CLI entrypoints for preprocess, train, finetune, sample, eval, optimize
- env.yml, pyproject.toml: environment and packaging
- data/processed, data/building_blocks, data/rxn_templates etc.: raw vs. preprocessed data hierarchy

##### README for additional insights
- Workflow stages:
1. Data Preparation using `scripts/preprocess.py` + building blocks / reaction templates
2. Supervised training via `scripts/train.py` (distributed with torchrun)
3. RL finetuning with `scripts/finetune.py`
4. Inference/Sampling with `scripts/sample.py` + evaluation (`eval_recon.py`, `eval_hit.py`, `optimize_tdc.py`)
- Key technologies: Python, PyTorch (torchrun), YAML configs, GPU clusters, external SynFormer dependency

##### Don’t overthink
- Enumerate each logical component even if it seems small (e.g., utils, sampler)
- The goal is to capture all moving parts in a clear, layered view
- Detail is better than abstraction for maintainability and onboarding

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Layer
    subgraph "Data Layer"
        direction TB
        RawBB["Building Blocks\n(data/building_blocks/)"]:::data
        RawRT["Reaction Templates\n(data/rxn_templates/)"]:::data
        RawZinc["Test Zinc250k\n(data/test_zinc250k.txt)"]:::data
        RawJnk["JNK3 Hits\n(data/jnk3_hit.txt)"]:::data
        RawFilter["Mols to Filter\n(data/mols_to_filter.txt)"]:::data
        ProcessedData["Preprocessed Data\n(data/processed/)"]:::data
    end

    %% Preprocessing
    subgraph "Preprocessing" 
        direction TB
        PreprocessScript["Preprocess Script\n(scripts/preprocess.py)"]:::proc
        Convert1["Convert Step 1\n(scripts/convert_processed_1.py)"]:::proc
        Convert2["Convert Step 2\n(scripts/convert_processed_2.py)"]:::proc
        Featurize["Featurization\n(reasyn/chem/featurize.py)"]:::proc
        FPIndex["Fingerprint Index\n(reasyn/chem/fpindex.py)"]:::proc
        Matrix["Matrix Ops\n(reasyn/chem/matrix.py)"]:::proc
    end

    %% Data Pipeline
    subgraph "Data Pipeline"
        direction TB
        Dataset["Dataset Module\n(reasyn/data/dataset.py)"]:::proc
        Collate["Collate Helper\n(reasyn/data/collate.py)"]:::proc
        Common["Common Utils\n(reasyn/data/common.py)"]:::proc
    end

    %% Model Core
    subgraph "Model Core"
        direction TB
        Encoder["Encoder\n(reasyn/models/encoder.py)"]:::model
        PosEnc["Positional Encoding\n(reasyn/models/positional_encoding.py)"]:::model
        Decoder["Decoder\n(reasyn/models/decoder.py)"]:::model
        ReaSynModel["Chain-of-Reaction Model\n(reasyn/models/reasyn.py)"]:::model
        Classifier["Classifier Head\n(reasyn/models/classifier_head.py)"]:::model
        Regressor["Regressor Head\n(reasyn/models/regressor.py)"]:::model
    end

    %% Trainer Layer
    subgraph "Training Engines"
        direction TB
        SupervisedTrainer["Autoregressive Trainer\n(reasyn/trainer/autoregressive.py)"]:::trainer
        TrainScript["Train Script\n(scripts/train.py)"]:::cli
        TrainConfig["Train Config\n(configs/train.yml)"]:::config
        RLTrainer["RL Finetune Trainer\n(reasyn/trainer/finetune.py)"]:::trainer
        FinetuneScript["Finetune Script\n(scripts/finetune.py)"]:::cli
        FinetuneConfig["Finetune Config\n(configs/finetune.yml)"]:::config
    end

    %% Inference Layer
    subgraph "Sampling & Inference"
        direction TB
        ParallelSampler["Parallel Sampler\n(reasyn/sampler/parallel.py)"]:::inference
        StatePool["State Pool\n(reasyn/sampler/state_pool.py)"]:::inference
        SampleScript["Sample Script\n(scripts/sample.py)"]:::cli
        SampleOne["Sample One\n(scripts/sample_one.py)"]:::cli
    end

    %% Evaluation & Optimization
    subgraph "Evaluation & Optimization"
        direction TB
        EvalRecon["Eval Reconstruction\n(scripts/eval_recon.py)"]:::cli
        EvalHit["Eval Hit Expansion\n(scripts/eval_hit.py)"]:::cli
        OptimizeTDC["Optimize TDC\n(scripts/optimize_tdc.py)"]:::cli
    end

    %% Utilities
    subgraph "Utilities"
        direction TB
        Mutate["Mutate\n(reasyn/utils/mutate.py)"]:::utils
        Crossover["Crossover\n(reasyn/utils/crossover.py)"]:::utils
        TrainHelper["Train Helpers\n(reasyn/utils/train.py)"]:::utils
        HParams["HParams\n(reasyn/utils/hparams_tdc.yml)"]:::config
    end

    %% Configs & Env
    Configs["Configs Directory\n(configs/)"]:::config
    Env["Environment & Packaging\n(env.yml\npyproject.toml)"]:::env

    %% Connections
    RawBB --> PreprocessScript
    RawRT --> PreprocessScript
    RawZinc --> PreprocessScript
    RawJnk --> PreprocessScript
    RawFilter --> PreprocessScript
    PreprocessScript --> Convert1 --> Convert2 --> ProcessedData
    ProcessedData --> Dataset
    Dataset --> Collate
    Collate --> Common
    Common --> Encoder
    Encoder --> PosEnc --> Decoder --> ReaSynModel
    ReaSynModel --> Classifier
    ReaSynModel --> Regressor
    Encoder --> SupervisedTrainer
    Decoder --> SupervisedTrainer
    SupervisedTrainer --> TrainScript
    TrainConfig --> TrainScript
    ReaSynModel --> RLTrainer
    RLTrainer --> FinetuneScript
    FinetuneConfig --> FinetuneScript
    TrainScript --> ProcessedData
    FinetuneScript --> ProcessedData
    Regressor --> ParallelSampler
    Classifier --> ParallelSampler
    ParallelSampler --> StatePool
    StatePool --> SampleScript
    StatePool --> SampleOne
    SampleScript --> EvalRecon
    SampleScript --> EvalHit
    SampleScript --> OptimizeTDC
    EvalRecon --> ProcessedData
    EvalHit --> ProcessedData
    OptimizeTDC --> ProcessedData
    Configs --> PreprocessScript
    Configs --> TrainScript
    Configs --> FinetuneScript
    Env --> PreprocessScript
    Env --> TrainScript
    Env --> FinetuneScript

    %% Click Events
    click RawBB "https://github.com/nvidia-digital-bio/reasyn/tree/main/data/building_blocks/"
    click RawRT "https://github.com/nvidia-digital-bio/reasyn/tree/main/data/rxn_templates/"
    click RawZinc "https://github.com/nvidia-digital-bio/reasyn/blob/main/data/test_zinc250k.txt"
    click RawJnk "https://github.com/nvidia-digital-bio/reasyn/blob/main/data/jnk3_hit.txt"
    click RawFilter "https://github.com/nvidia-digital-bio/reasyn/blob/main/data/mols_to_filter.txt"
    click ProcessedData "https://github.com/nvidia-digital-bio/reasyn/tree/main/data/processed/"
    click PreprocessScript "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/preprocess.py"
    click Convert1 "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/convert_processed_1.py"
    click Convert2 "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/convert_processed_2.py"
    click Featurize "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/chem/featurize.py"
    click FPIndex "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/chem/fpindex.py"
    click Matrix "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/chem/matrix.py"
    click Dataset "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/data/dataset.py"
    click Collate "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/data/collate.py"
    click Common "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/data/common.py"
    click Encoder "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/models/encoder.py"
    click PosEnc "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/models/positional_encoding.py"
    click Decoder "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/models/decoder.py"
    click ReaSynModel "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/models/reasyn.py"
    click Classifier "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/models/classifier_head.py"
    click Regressor "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/models/regressor.py"
    click SupervisedTrainer "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/trainer/autoregressive.py"
    click TrainScript "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/train.py"
    click TrainConfig "https://github.com/nvidia-digital-bio/reasyn/blob/main/configs/train.yml"
    click RLTrainer "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/trainer/finetune.py"
    click FinetuneScript "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/finetune.py"
    click FinetuneConfig "https://github.com/nvidia-digital-bio/reasyn/blob/main/configs/finetune.yml"
    click ParallelSampler "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/sampler/parallel.py"
    click StatePool "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/sampler/state_pool.py"
    click SampleScript "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/sample.py"
    click SampleOne "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/sample_one.py"
    click EvalRecon "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/eval_recon.py"
    click EvalHit "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/eval_hit.py"
    click OptimizeTDC "https://github.com/nvidia-digital-bio/reasyn/blob/main/scripts/optimize_tdc.py"
    click Mutate "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/utils/mutate.py"
    click Crossover "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/utils/crossover.py"
    click TrainHelper "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/utils/train.py"
    click HParams "https://github.com/nvidia-digital-bio/reasyn/blob/main/reasyn/utils/hparams_tdc.yml"
    click Configs "https://github.com/nvidia-digital-bio/reasyn/tree/main/configs/"
    click Env "https://github.com/nvidia-digital-bio/reasyn/blob/main/env.yml"

    %% Styles
    classDef data fill:#D0E4F5,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef proc fill:#DFF5D8,stroke:#28A745,color:#155724,stroke-width:1px;
    classDef model fill:#FFE5B4,stroke:#FF8C00,color:#8B4513,stroke-width:1px;
    classDef trainer fill:#E3D5FF,stroke:#6A0DAD,color:#4B0082,stroke-width:1px;
    classDef inference fill:#FFD1DC,stroke:#FF1493,color:#C71585,stroke-width:1px;
    classDef cli fill:#FFF3CD,stroke:#FFC107,color:#856404,stroke-width:1px;
    classDef utils fill:#F0F0F0,stroke:#6C757D,color:#343A40,stroke-width:1px;
    classDef config fill:#D1ECF1,stroke:#17A2B8,color:#0C5460,stroke-width:1px;
    classDef env fill:#E2E3E5,stroke:#6C757D,color:#495057,stroke-width:1px;
```
