TUTORIAL MD KOMPUTASI V1.0.0
================================

A. TUJUAN
---------
MD Komputasi adalah aplikasi OpenMM untuk menyusun workflow Molecular Dynamics
yang dapat ditelusuri, dihentikan dengan aman, dilanjutkan dari checkpoint,
dianalisis, dan diekspor.

Port default:
    http://localhost:8805

B. INSTALASI DI WSL/UBUNTU
--------------------------
1. Letakkan file:
       md-komputasi_1.0.0_all.deb

   di folder yang mudah diakses.

2. Jalankan:
       sudo apt update
       sudo apt install ./md-komputasi_1.0.0_all.deb

3. Jalankan aplikasi:
       md-komputasi

4. Buka:
       http://localhost:8805

5. Port lain, misalnya 8810:
       MDKOMPUTASI_PORT=8810 md-komputasi

6. Cek versi paket:
       dpkg -s md-komputasi | grep '^Version:'

C. DATA RUNTIME
---------------
Data pengguna TIDAK disimpan di /opt. Data disimpan di:
    ~/.local/share/md-komputasi/

Subfolder utama:
    runs/
    imports/
    cache/

Database:
    md_komputasi.sqlite3

Lokasi dapat diubah:
    MDKOMPUTASI_HOME=/lokasi/baru md-komputasi

D. URUTAN PENGGUNAAN
--------------------
1. MENU "SISTEM & PREPARASI"
   Pilih salah satu:
   - 20 contoh jurnal;
   - PDB ID;
   - upload PDB/mmCIF.

   Untuk uji awal gunakan sistem kecil, misalnya:
   - Chignolin (1UAO)
   - Crambin (1CRN)
   - Trp-cage (2JOF)

2. PILIH PREPARASI
   "Struktur as-is + addHydrogens"
   cocok bila struktur sudah dipersiapkan dan heterogen/ligand perlu dipertahankan.

   "PDBFixer protein-only"
   digunakan untuk protein saja. Mode ini menghapus heterogen non-air.
   JANGAN pilih mode ini jika ligand harus dipertahankan.

3. FORCE FIELD
   Preset tersedia:
   - Amber14 + TIP3P-FB
   - Amber14 + TIP3P
   - Amber19 + TIP3P-FB
   - CHARMM36 + TIP3P
   - FFXML kustom dapat ditambahkan.

4. PROTEIN-LIGAND
   Jika residue ligand tidak dikenal force field:
   a. sediakan SDF/MOL2 ligand yang sesuai dengan struktur di PDB;
   b. pilih GAFF atau SMIRNOFF;
   c. atau unggah FFXML parameter yang sudah divalidasi.

   Aplikasi akan menolak job jika terdapat unmatched residues yang tidak memiliki
   template parameter.

5. MENU "JOB SPECIFICATION"
   Atur:
   - water model;
   - box padding;
   - ionic strength;
   - ion positif/negatif;
   - PME/Ewald/cutoff;
   - constraints;
   - temperature;
   - pressure;
   - integrator;
   - timestep;
   - NVT;
   - NPT;
   - panjang production;
   - interval DCD;
   - interval state log;
   - interval checkpoint;
   - platform CPU/CUDA/OpenCL;
   - jumlah replikasi dan seed.

   Bagian Job Specification menggunakan panel putih dengan teks gelap supaya
   seluruh parameter dapat dibaca dengan jelas.

6. MENU "JALANKAN MD"
   Klik:
       Mulai Job

   Tahap:
       Preparasi
       -> Energy minimization
       -> NVT equilibration
       -> NPT equilibration
       -> Production MD
       -> Analisis

E. STOP DAN RESUME
------------------
Klik:
    Stop aman

Worker akan berhenti pada batas chunk/checkpoint. File trajectory yang sudah
dibuat tidak dihapus.

Saat Resume:
    production_seg001.dcd   = sesi awal
    production_seg002.dcd   = sesi resume pertama
    production_seg003.dcd   = sesi resume berikutnya

Dengan desain ini trajectory lama tidak ditimpa.

Checkpoint:
    checkpoints/checkpoint_XXXXXXXXXXXX.chk

State XML juga disimpan sebagai fallback resume.

F. REPLIKASI
------------
Jika "Replicas" = 3, aplikasi membuat tiga run terpisah:
    nama_project_rep01
    nama_project_rep02
    nama_project_rep03

Seed dibuat berbeda. Setelah setiap run dianalisis, menu Analisis dapat
menampilkan ringkasan metrik antar-replika.

G. ANALISIS TRAJECTORY
----------------------
Menu "Analisis Trajectory" menyediakan:

1. RMSD
   Mengukur perubahan struktur relatif terhadap frame acuan.

2. RMSF
   Mengukur fluktuasi atom/residu selama trajectory.

3. Radius of Gyration
   Menggambarkan kekompakan sistem/protein.

4. SASA
   Solvent Accessible Surface Area.

5. H-Bond
   Daftar donor-acceptor dan occupancy berbasis trajectory.

6. Ligand Contact Occupancy
   Aktif bila Ligand Residue Name ditentukan.
   Menampilkan occupancy dan mean minimum distance terhadap residue protein.

Catatan:
Satu RMSD yang tampak datar tidak otomatis membuktikan convergence.
Periksa beberapa metrik, panjang trajectory, equilibration, dan replikasi.

H. PUSAT HASIL
--------------
Menu "Pusat Hasil" menyediakan:
- status/progress;
- job specification;
- provenance;
- log;
- artifacts;
- checkpoint;
- tombol buka folder;
- Stop;
- Resume;
- analisis;
- export.

I. EKSPOR
---------
Tersedia:
- XLSX;
- PDF;
- CSV/JSON di folder run;
- ZIP proyek;
- integration_manifest.json.

J. 20 CONTOH JURNAL
-------------------
File:
    MD_Komputasi_20_Contoh_Jurnal.csv

Berisi 20 starting systems dengan PDB ID, sumber jurnal, DOI, system type,
dan catatan preparasi.

Contoh fast-folding mengacu pada:
Lindorff-Larsen K, Piana S, Dror RO, Shaw DE.
How Fast-Folding Proteins Fold. Science. 2011.
DOI: 10.1126/science.1208351

Contoh lain meliputi BPTI, DHFR, ubiquitin, adenylate kinase, TLR8, ALK2,
dan crambin, masing-masing disertai rujukan/DOI dalam CSV/aplikasi.

PENTING:
Preset hanya merupakan starting structure yang terkait dengan jurnal.
Aplikasi tidak mengklaim mereproduksi trajectory, force field, protonation,
atau protokol jurnal secara otomatis.

K. MASALAH TAMPILAN
--------------------
V1.0.0 telah diberi patch kontras:
- seluruh ruang kanan: background putih/terang + teks biru-hitam gelap;
- alert pastel: teks gelap;
- input/selectbox: putih + teks gelap;
- code/log: background terang + teks gelap;
- dataframe/table: permukaan terang;
- Job Specification: panel JSON statik putih + teks gelap;
- hero hitam: teks putih/kuning.

Jika browser menggunakan dark mode, CSS aplikasi tetap memaksa kontras pada
ruang output kanan.

L. DEPENDENSI
-------------
Core:
    streamlit
    numpy
    pandas
    plotly
    psutil
    openpyxl
    XlsxWriter
    reportlab
    openmm
    mdtraj

Optional:
    pdbfixer
    openmmforcefields
    openff-toolkit
    py3Dmol

Paket DEB membuat virtualenv user-writable pada eksekusi pertama dan memasang
dependensi core secara otomatis. Paket optional dapat dicoba dipasang oleh
aplikasi bila fitur terkait digunakan.

M. CATATAN ILMIAH
-----------------
Sebelum memakai hasil untuk riset:
- periksa struktur awal;
- periksa protonasi;
- periksa missing atom/residue;
- tentukan apakah water/ion struktural harus dipertahankan;
- validasi ligand parameter;
- validasi force field;
- lakukan equilibration yang memadai;
- periksa energy/temperature/pressure/density;
- lakukan convergence analysis;
- gunakan replikasi jika diperlukan;
- simpan provenance dan versi environment.

Copyright © Kasmui, 2026.
