# aitrics/freed architecture

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

- Interactive diagram: https://gitdiagram.com/aitrics/freed
- Repository: https://github.com/aitrics/freed

## Overview

FREED trains fragment-based molecular generators with reinforcement learning: a user selects a target and training variant, the learner proposes fragment edits in a molecule environment, and docking supplies target-dependent reward. Generated molecules can then be assessed for drug-likeness and hit enrichment. The README documents PE, BU, PER, curiosity, vanilla SAC, and PPO; the tree provides their implementation paths. Some orchestration and configuration wiring is not sampled, so uncertain links are omitted.

Main entry points: [`gym_molecule/envs/molecule_graph.py`](https://github.com/aitrics/freed/blob/main/gym_molecule/envs/molecule_graph.py) (Molecule environment), [`run_rl.py`](https://github.com/aitrics/freed/blob/main/run_rl.py) (Training entry), [`core_motif.py`](https://github.com/aitrics/freed/blob/main/core_motif.py) (Graph policy), [`sac_motif_freed_bu.py`](https://github.com/aitrics/freed/blob/main/sac_motif_freed_bu.py) (FREED BU)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_training["RL training"]
  node_runner["Training entry<br/>[run_rl.py]"]
  node_sac["SAC variants<br/>[sac_motif.py]"]
  node_freed_pe["FREED PE"]
  node_freed_bu["FREED BU"]
  node_per["Prioritized replay<br/>[sac_motif_per.py]"]
  node_ppo["PPO baseline<br/>[ppo_motif.py]"]
  node_curiosity["Curiosity variants"]
end

subgraph group_generation["Molecule generation"]
  node_env["Molecule environment<br/>[molecule_graph.py]"]
  node_graph_policy["Graph policy<br/>[core_motif.py]"]
  node_graph_vbased["Value policy"]
  node_graph_mc["MC graph model<br/>[core_motif_mc.py]"]
  node_motifs["Fragment vocabularies<br/>[motifs_91.txt]"]
end

subgraph group_docking["Docking"]
  node_docking_env["Vina docking<br/>[docking_simple.py]"]
  node_vina["QVina executable"]
  node_targets["Target receptors"]
end

subgraph group_evaluation["Results evaluation"]
  node_filters["Molecule quality filters<br/>[filters.py]"]
  node_enrichment["Hit enrichment<br/>[enrichment.py]"]
  node_generated["Generated molecule files"]
end

node_user(("Researcher"))

node_user -->|"starts training"| node_runner
node_runner -->|"selects learner"| node_sac
node_runner -->|"selects PE"| node_freed_pe
node_runner -->|"selects BU"| node_freed_bu
node_runner -->|"selects PER"| node_per
node_runner -->|"selects PPO"| node_ppo
node_runner -->|"selects curiosity"| node_curiosity
node_sac -->|"steps environment"| node_env
node_freed_pe -->|"steps environment"| node_env
node_freed_bu -->|"steps environment"| node_env
node_per -->|"steps environment"| node_env
node_ppo -->|"steps environment"| node_env
node_curiosity -->|"steps environment"| node_env
node_sac -->|"uses actor critic"| node_graph_policy
node_freed_pe -->|"uses actor critic"| node_graph_policy
node_freed_bu -->|"uses actor critic"| node_graph_policy
node_per -->|"uses actor critic"| node_graph_policy
node_ppo -->|"uses value policy"| node_graph_vbased
node_graph_policy -->|"queries observations"| node_env
node_graph_vbased -->|"builds candidates"| node_env
node_graph_mc -.->|"supports uncertainty"| node_freed_bu
node_env -->|"loads fragments"| node_motifs
node_env -->|"scores molecules"| node_docking_env
node_docking_env -->|"runs docking"| node_vina
node_docking_env -->|"uses receptor files"| node_targets
node_runner -->|"writes molecules"| node_generated
node_generated -->|"supplies SMILES"| node_filters
node_generated -->|"supplies docking scores"| node_enrichment

click node_runner "https://github.com/aitrics/freed/blob/main/run_rl.py"
click node_sac "https://github.com/aitrics/freed/blob/main/sac_motif.py"
click node_freed_pe "https://github.com/aitrics/freed/blob/main/sac_motif_freed_pe.py"
click node_freed_bu "https://github.com/aitrics/freed/blob/main/sac_motif_freed_bu.py"
click node_per "https://github.com/aitrics/freed/blob/main/sac_motif_per.py"
click node_ppo "https://github.com/aitrics/freed/blob/main/ppo_motif.py"
click node_curiosity "https://github.com/aitrics/freed/blob/main/sac_motif_freed_pe.py"
click node_env "https://github.com/aitrics/freed/blob/main/gym_molecule/envs/molecule_graph.py"
click node_graph_policy "https://github.com/aitrics/freed/blob/main/core_motif.py"
click node_graph_vbased "https://github.com/aitrics/freed/blob/main/core_motif_vbased.py"
click node_graph_mc "https://github.com/aitrics/freed/blob/main/core_motif_mc.py"
click node_motifs "https://github.com/aitrics/freed/blob/main/gym_molecule/dataset/motifs_91.txt"
click node_docking_env "https://github.com/aitrics/freed/blob/main/gym_molecule/envs/docking_simple.py"
click node_vina "https://github.com/aitrics/freed/blob/main/bin/qvina02"
click node_targets "https://github.com/aitrics/freed/tree/main/ReLeaSE_Vina/docking"
click node_filters "https://github.com/aitrics/freed/blob/main/rl_final_results/libs/filters.py"
click node_enrichment "https://github.com/aitrics/freed/blob/main/rl_final_results/libs/enrichment.py"
click node_generated "https://github.com/aitrics/freed/tree/main/rl_final_results"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_runner,node_sac,node_freed_pe,node_freed_bu,node_per,node_ppo,node_curiosity toneBlue
class node_env,node_graph_policy,node_graph_vbased,node_graph_mc,node_motifs toneAmber
class node_docking_env,node_vina,node_targets toneMint
class node_filters,node_enrichment,node_generated toneRose
class node_user toneIndigo
```

## Components

### RL training

- [Training entry](https://github.com/aitrics/freed/blob/main/run_rl.py): `run_rl.py`
- [SAC variants](https://github.com/aitrics/freed/blob/main/sac_motif.py): `sac_motif.py`
- [FREED PE](https://github.com/aitrics/freed/blob/main/sac_motif_freed_pe.py): `sac_motif_freed_pe.py`
- [FREED BU](https://github.com/aitrics/freed/blob/main/sac_motif_freed_bu.py): `sac_motif_freed_bu.py`
- [Prioritized replay](https://github.com/aitrics/freed/blob/main/sac_motif_per.py): `sac_motif_per.py`
- [PPO baseline](https://github.com/aitrics/freed/blob/main/ppo_motif.py): `ppo_motif.py`
- [Curiosity variants](https://github.com/aitrics/freed/blob/main/sac_motif_freed_pe.py): `sac_motif_freed_pe.py`

### Molecule generation

- [Molecule environment](https://github.com/aitrics/freed/blob/main/gym_molecule/envs/molecule_graph.py): `gym_molecule/envs/molecule_graph.py`
- [Graph policy](https://github.com/aitrics/freed/blob/main/core_motif.py): `core_motif.py`
- [Value policy](https://github.com/aitrics/freed/blob/main/core_motif_vbased.py): `core_motif_vbased.py`
- [MC graph model](https://github.com/aitrics/freed/blob/main/core_motif_mc.py): `core_motif_mc.py`
- [Fragment vocabularies](https://github.com/aitrics/freed/blob/main/gym_molecule/dataset/motifs_91.txt): `gym_molecule/dataset/motifs_91.txt`

### Docking

- [Vina docking](https://github.com/aitrics/freed/blob/main/gym_molecule/envs/docking_simple.py): `gym_molecule/envs/docking_simple.py`
- [QVina executable](https://github.com/aitrics/freed/blob/main/bin/qvina02): `bin/qvina02`
- [Target receptors](https://github.com/aitrics/freed/tree/main/ReLeaSE_Vina/docking): `ReLeaSE_Vina/docking`

### Results evaluation

- [Molecule quality filters](https://github.com/aitrics/freed/blob/main/rl_final_results/libs/filters.py): `rl_final_results/libs/filters.py`
- [Hit enrichment](https://github.com/aitrics/freed/blob/main/rl_final_results/libs/enrichment.py): `rl_final_results/libs/enrichment.py`
- [Generated molecule files](https://github.com/aitrics/freed/tree/main/rl_final_results): `rl_final_results`

### Other components

- **Researcher**

## Connections

- Researcher → Training entry: starts training
- Training entry → SAC variants: selects learner
- Training entry → FREED PE: selects PE
- Training entry → FREED BU: selects BU
- Training entry → Prioritized replay: selects PER
- Training entry → PPO baseline: selects PPO
- Training entry → Curiosity variants: selects curiosity
- SAC variants → Molecule environment: steps environment
- FREED PE → Molecule environment: steps environment
- FREED BU → Molecule environment: steps environment
- Prioritized replay → Molecule environment: steps environment
- PPO baseline → Molecule environment: steps environment
- Curiosity variants → Molecule environment: steps environment
- SAC variants → Graph policy: uses actor critic
- FREED PE → Graph policy: uses actor critic
- FREED BU → Graph policy: uses actor critic
- Prioritized replay → Graph policy: uses actor critic
- PPO baseline → Value policy: uses value policy
- Graph policy → Molecule environment: queries observations
- Value policy → Molecule environment: builds candidates
- MC graph model → FREED BU: supports uncertainty
- Molecule environment → Fragment vocabularies: loads fragments
- Molecule environment → Vina docking: scores molecules
- Vina docking → QVina executable: runs docking
- Vina docking → Target receptors: uses receptor files
- Training entry → Generated molecule files: writes molecules
- Generated molecule files → Molecule quality filters: supplies SMILES
- Generated molecule files → Hit enrichment: supplies docking scores