TUTORIAL INSTALASI DAN PENGGUNAAN SPECTRAQM V1.0.1
===================================================

SpectraQM adalah aplikasi Streamlit untuk analisis spektroskopi komputasi dan
orbital: IR, Raman, UV-Vis/TDDFT, NMR, HOMO-LUMO, DOS/PDOS, perbandingan
teori-eksperimen, provenance, dan ekspor hasil.

VERSI 1.0.1 — PATCH KONTRAS RUANG KANAN
-----------------------------------------
Versi ini memperbaiki tampilan ruang kanan secara menyeluruh. Perbaikan utama:
1. Job specification tidak lagi memakai tampilan JSON bawaan yang dapat menjadi
   gelap dengan teks gelap pada theme tertentu. Job specification dirender pada
   panel putih dengan teks biru-hitam yang kontras.
2. Expander, JSON, code/log, metric, tab, tabel, uploader, select/popover, alert,
   input, dan kartu hasil dipaksa memakai pasangan warna background-teks yang
   kontras.
3. Hero/header gelap tetap menggunakan teks putih/kuning sehingga tidak terkena
   aturan teks gelap ruang kanan.
4. Plot menggunakan template putih dan label/axis berwarna gelap.
5. Patch dirancang agar tetap terbaca walaupun browser atau Streamlit memakai
   preferensi dark theme.

A. FILE DISTRIBUSI
------------------
- SpectraQM_V1.0.1.py
- spectraqm_1.0.1_all.deb
- SpectraQM_20_Contoh_Thiel.csv
- README_SpectraQM_V1.0.1.md
- TUTORIAL_SpectraQM_V1.0.1.txt

B. INSTALASI DI WSL / UBUNTU DENGAN FILE DEB
---------------------------------------------
1. Letakkan file spectraqm_1.0.1_all.deb pada folder yang mudah ditemukan.
2. Buka WSL/Ubuntu.
3. Masuk ke folder file tersebut. Contoh bila file berada di Downloads Windows:

   cd /mnt/c/Users/NAMA_USER/Downloads

4. Instal atau upgrade SpectraQM:

   sudo apt update
   sudo apt install ./spectraqm_1.0.1_all.deb

Jika versi 1.0.0 sudah terpasang, perintah di atas akan meng-upgrade paket menjadi
1.0.1 dan mempertahankan data pengguna di ~/.local/share/spectraqm.

5. Jalankan aplikasi:

   spectraqm

6. Buka browser:

   http://localhost:8804

7. Hentikan server dengan Ctrl+C pada terminal.

C. MENJALANKAN PADA PORT LAIN
-----------------------------
Contoh port 8810:

   SPECTRAQM_PORT=8810 spectraqm

Kemudian buka:

   http://localhost:8810

D. MENJALANKAN LANGSUNG FILE PYTHON
-----------------------------------
Jika menggunakan conda environment, misalnya "kimia":

   conda activate kimia
   python SpectraQM_V1.0.1.py

Atau:

   streamlit run SpectraQM_V1.0.1.py --server.port 8804

File Python memiliki mekanisme auto-install untuk dependensi Python yang belum
tersedia, kecuali SPECTRAQM_NO_AUTO_PIP=1 diaktifkan.

E. DEPENDENSI UTAMA
-------------------
Paket DEB menyiapkan virtual environment pengguna dan memasang dependensi Python
pada eksekusi pertama:
- streamlit
- numpy
- pandas
- scipy
- rdkit
- pyscf
- plotly
- psutil
- openpyxl
- XlsxWriter
- reportlab
- matplotlib
- geometric (opsional)
- py3Dmol (opsional)

Virtual environment default:

   ~/.local/share/spectraqm/venv

Data aplikasi default:

   ~/.local/share/spectraqm

F. JIKA DEPENDENSI BERMASALAH
-----------------------------
Reset virtual environment SpectraQM:

   spectraqm-reset-deps

Kemudian jalankan kembali:

   spectraqm

Aplikasi akan membuat virtual environment baru dan memasang dependensi kembali.

G. MEMILIH CONTOH INPUT
-----------------------
SpectraQM menyediakan 20 contoh input benchmark. Pilih molekul dari katalog di
sidebar, lalu periksa struktur, charge, multiplicity, method, basis, dan modul
analisis yang akan dijalankan.

File tambahan contoh:

   /opt/spectraqm/examples/SpectraQM_20_Contoh_Thiel.csv

H. WORKFLOW DASAR
-----------------
1. Pilih atau masukkan struktur molekul.
2. Generate/validasi geometri 3D.
3. Atur charge dan multiplicity.
4. Pilih metode HF/DFT dan basis set.
5. Pilih modul:
   - Electronic structure
   - Frequency/IR
   - Raman
   - UV-Vis/TDA/TDDFT
   - NMR
   - Orbital/HOMO-LUMO
   - DOS/PDOS
   - Theory vs experiment
6. Atur scaling, broadening, dan parameter lain yang relevan.
7. Periksa panel "Job specification". Pada V1.0.1 panel ini harus ber-background
   putih dengan teks gelap dan jelas terbaca.
8. Jalankan job.
9. Pantau progress/log.
10. Buka Pusat Hasil untuk tabel, grafik, QC, provenance, dan ekspor.

I. PEMERIKSAAN TAMPILAN KONTRAS V1.0.1
--------------------------------------
Setelah aplikasi terbuka, lakukan pemeriksaan berikut:
1. Buka halaman penyiapan job.
2. Buka expander "Job specification".
3. Pastikan background panel putih dan seluruh JSON/specification terlihat gelap.
4. Buka tab Log & Provenance; log harus ber-background sangat terang dan teks gelap.
5. Periksa warning/info/success/error; teks harus terbaca pada background pastel.
6. Periksa tab, tabel, metric, select box, uploader dan tombol.
7. Coba browser pada mode terang maupun gelap. Konten utama SpectraQM tetap
   menggunakan skema kontras internal aplikasi.

Jika ada bagian yang masih tidak terbaca, catat nama halaman/tab/komponen dan
sertakan screenshot supaya selector UI dapat diperbaiki secara spesifik.

J. UPGRADE DARI V1.0.0
----------------------
Cukup instal paket baru:

   sudo apt install ./spectraqm_1.0.1_all.deb

Tidak perlu menghapus versi lama terlebih dahulu.

Cek versi paket:

   dpkg -s spectraqm | grep '^Version:'

Hasil yang diharapkan:

   Version: 1.0.1

K. UNINSTALL
------------
Hapus program:

   sudo apt remove spectraqm

Data hasil pengguna tidak otomatis dihapus dari:

   ~/.local/share/spectraqm

Jika memang ingin menghapus seluruh data pengguna juga, lakukan secara manual
setelah memastikan hasil penting telah dibackup.

L. CATATAN ILMIAH
-----------------
- Scaling factor, broadening, metode, basis, reference NMR dan opsi numerik harus
  dibaca bersama hasil.
- Hasil komputasi bukan pengganti data eksperimen.
- Frekuensi imajiner, convergence, dan status QC harus diperiksa sebelum membuat
  interpretasi ilmiah.
- Job specification dan provenance disimpan untuk menjaga reproducibility.

Copyright © Kasmui, 2026
