TUTORIAL MOLPREP V1.0.0
=======================

MOLPREP: CONFORMER & MOLECULAR PREPARATION STUDIO
Port default: http://localhost:8806

A. INSTALASI DI WSL/UBUNTU
--------------------------
1. Salin file berikut ke folder yang mudah diakses:
       molprep_1.0.0_all.deb

2. Instal:
       sudo apt update
       sudo apt install ./molprep_1.0.0_all.deb

3. Jalankan:
       molprep

4. Buka browser:
       http://localhost:8806

5. Bila ingin port lain:
       MOLPREP_PORT=8811 molprep

6. Cek versi:
       dpkg -s molprep | grep '^Version:'

B. LOKASI DATA
--------------
Kode aplikasi dipasang di /opt/molprep, tetapi data runtime tidak ditulis ke /opt.
Data pengguna berada di:
       ~/.local/share/molprep/

Lokasi dapat diganti:
       MOLPREP_HOME=/lokasi/data molprep

C. URUTAN PENGGUNAAN
--------------------
1. INPUT MOLEKUL
   Pilih salah satu:
   - 20 contoh jurnal FreeSolv;
   - SMILES;
   - InChI;
   - upload SDF;
   - upload MOL/MOL2;
   - upload XYZ;
   - upload CSV dengan kolom smiles atau inchi.

   Format teks yang didukung:
       Nama=SMILES
       Nama=InChI=...

2. VALIDASI INPUT
   Tabel Input aktif menampilkan antara lain:
   - canonical SMILES;
   - formula;
   - molecular weight;
   - formal charge;
   - rotatable bonds;
   - stereocenter yang belum didefinisikan.

   Struktur yang gagal sanitization ditolak dengan pesan koreksi.

3. JOB SPECIFICATION
   Atur parameter berikut.

   STANDARDIZATION
   - Cleanup RDKit
   - Largest fragment / FragmentParent
   - Normalize
   - Reionize opsional
   - Uncharger opsional

   TAUTOMER
   - Preserve input
   - Canonical only
   - Enumerate

   Batasi jumlah tautomer untuk mencegah ledakan kombinatorial.

   PROTONATION
   - Preserve input
   - Neutralize where possible
   - Reionize RDKit
   - pH range (Dimorphite-DL optional)

   PENTING:
   RDKit standardization bukan prediksi pKa. Mode pH-aware hanya dijalankan bila
   Dimorphite-DL tersedia. Bila library tidak tersedia, state input dipertahankan
   dan warning dicatat.

   STEREOCHEMISTRY
   - Enumerate stereoisomers
   - Only unassigned stereo
   - Max stereoisomers

   CONFORMER
   - ETKDGv3 (default)
   - ETKDGv2
   - ETDG
   - jumlah conformer
   - random seed
   - prune RMS
   - small-ring torsions
   - macrocycle torsions

   RELAXATION
   - MMFF94s (default)
   - MMFF94
   - UFF
   - UFF fallback
   - max iterations
   - energy window

   CLUSTERING
   - RMSD cutoff
   - representative cluster only
   - max output conformer/state

   xTB REFINEMENT
   - default OFF
   - aktifkan hanya bila executable xtb tersedia
   - pilih GFN2-xTB atau GFN1-xTB
   - tentukan top N conformer

4. PERIKSA JOB SPECIFICATION
   Panel Job Specification sengaja tidak memakai warna theme otomatis.
   Tampilannya:
       background putih
       teks biru-hitam gelap
       border biru
       font monospace

   Tujuannya agar seluruh teks ruang kanan selalu terlihat.

5. JALANKAN MOLPREP
   Klik:
       Mulai Job Baru

   Tahapan utama:
       Parsing
       -> Sanitization / Standardization
       -> Tautomer
       -> Protonation
       -> Stereoisomer
       -> ETKDG conformer
       -> UFF/MMFF relaxation
       -> Energy filtering
       -> RMSD clustering
       -> xTB optional
       -> Export

D. STOP DAN RESUME
------------------
Klik "Stop aman" di Pusat Hasil.

MolPrep mengecek stop flag pada batas tahap/state. Checkpoint disimpan setelah
setiap molekul selesai. Resume tidak mengulang molekul yang sudah ada pada
checkpoint.

File:
       checkpoint.json
       status.json
       run.log
       job_spec.json
       provenance.json

E. MEMBACA HASIL
----------------
Pusat Hasil memiliki tab:

1. Job Specification
2. Ringkasan
3. Molekul
4. Energi & Cluster
5. Log
6. Artifacts
7. Provenance & Environment

Untuk setiap molekul tersedia:
       standardized.mol
       standardized.smi
       standardization_report.json
       chemical_states.sdf
       chemical_states.csv
       state_XXX/conformer_energies.csv
       state_XXX/rmsd_clusters.csv
       state_XXX/selected_conformers.sdf
       result.json

F. INTERPRETASI ENERGI
----------------------
Energi MMFF/UFF dipakai untuk ranking/filtering pada tingkat force field yang
sama. Jangan membandingkan nilai energi absolut dari force field berbeda sebagai
energi kuantum.

Energy window menentukan conformer yang dipertahankan relatif terhadap minimum
force-field pada state yang sama.

G. RMSD CLUSTERING
------------------
MolPrep memakai RMSD matrix dan Butina clustering. Representative cluster dipilih
sebagai conformer dengan energi force-field terendah dalam cluster tersebut.

RMSD cutoff terlalu kecil -> terlalu banyak cluster.
RMSD cutoff terlalu besar -> conformer berbeda dapat tergabung.
Lakukan sensitivity test bila hasil akan dipakai untuk riset.

H. xTB REFINEMENT
-----------------
Jika executable "xtb" ditemukan dan opsi xTB aktif, MolPrep:
1. menulis XYZ conformer;
2. menjalankan GFN1/GFN2-xTB optimization;
3. menyimpan stdout/stderr mentah;
4. menyimpan xtbopt.xyz bila tersedia;
5. mencatat energy Hartree bila parser menemukan TOTAL ENERGY.

Jika xtb tidak tersedia, stage ditandai SKIPPED. UFF/MMFF tetap dapat selesai.

I. EKSPOR DAN INTEGRASI
-----------------------
Project menghasilkan:
       project_summary.csv
       MolPrep_Report.xlsx
       MolPrep_Report.pdf
       project ZIP

Folder integration/ menghasilkan:
       molprep_for_qmscreen.csv
       molprep_for_dockflow.csv
       molprep_selected_for_qmscreen_dockflow.sdf
       integration_manifest.json

Downstream QMScreen/DockFlow tetap harus mempertahankan provenance tautomer,
protonation, stereochemistry, dan conformer yang dipilih.

J. 20 CONTOH DARI JURNAL VALID
------------------------------
File:
       MolPrep_20_Contoh_FreeSolv.csv

Sumber:
Mobley, D. L.; Guthrie, J. P.
FreeSolv: a database of experimental and calculated hydration free energies,
with input files.
Journal of Computer-Aided Molecular Design 28, 711-720 (2014).
DOI: 10.1007/s10822-014-9747-x

Contoh diambil sebagai struktur/input MolPrep. FreeSolv bukan klaim validasi
untuk semua fitur tautomer/stereo/conformer MolPrep.

K. REFERENSI METODE CONFORMER
-----------------------------
ETKDG:
Riniker & Landrum, J. Chem. Inf. Model. 2015.
DOI: 10.1021/acs.jcim.5b00654

ETKDG small rings/macrocycles:
Wang et al., J. Chem. Inf. Model. 2020.
DOI: 10.1021/acs.jcim.0c00025

GFN2-xTB:
Bannwarth, Ehlert & Grimme, J. Chem. Theory Comput. 2019.
DOI: 10.1021/acs.jctc.8b01176

L. KONTRAS RUANG KANAN
----------------------
MolPrep V1.0.0 memaksa:
- ruang kanan: background terang/putih;
- teks: gelap;
- input: putih + teks gelap;
- expander: putih + teks gelap;
- alert: kuning muda + teks gelap;
- code/log: background terang + teks gelap;
- Job Specification: putih + teks gelap;
- hero: hitam + judul putih + subjudul kuning.

Paket DEB juga menjalankan Streamlit dengan theme BASE LIGHT sehingga tampilan
lebih konsisten walaupun browser/Streamlit pengguna memakai dark mode.

Copyright © Kasmui, 2026.
