﻿DiffDock Batch — 사용법
========================

[실행]
  Windows : DiffDock_Windows.bat 더블클릭
  Mac     : DiffDock_Mac.command 더블클릭
            처음 한 번은 "확인되지 않은 개발자" 경고가 뜰 수 있습니다.
            → 파일을 우클릭(Control+클릭) → "열기" → "열기"
            그래도 안 되면 터미널에서:  chmod +x DiffDock_Mac.command
  Linux   : run_linux.sh 실행

  처음 실행할 때만 실행 환경(Python 가상환경, requests, keyring)을 자동으로 준비합니다.
  Python 3.9 이상이 필요합니다. 없으면 설치 페이지가 열립니다.

  실행하면 검은 창(실행 창)과 브라우저가 함께 열립니다.
  프로그램을 끝내려면 실행 창을 닫으세요. 작업 중에 닫으면 작업도 멈춥니다.

[사용 순서]
  1. API 키 입력 (한 번 저장해 두면 다음부터 생략)
  2. "파일 선택…"으로 .pdb / .sdf / .mol2 파일을 여러 개 고르거나, 점선 영역에 끌어다 놓기
     - 확장자에 따라 단백질/리간드 목록으로 자동 분류됩니다
     - 같은 이름의 파일을 다시 추가하면 새 파일로 교체됩니다
     - 여러 분자가 든 .sdf/.mol2는 분자별 리간드로 자동으로 나눕니다
       (이름: 원본파일명_분자이름, 분자 이름이 없거나 겹치면 번호)
     - 고른 파일은 프로그램을 끄면 목록에서 사라집니다 (원본 파일은 그대로)
  3. 결과 저장 폴더 지정 (비워두면 문서/DiffDock_results)
  4. 옵션 확인 후 "실행"

[2D 리간드 — 결과가 나오지 않음]
  DiffDock은 리간드의 3D 좌표가 필요합니다. z 좌표가 모두 0인 2D 구조 파일
  (ChemDraw에서 저장한 파일, PubChem의 2D SDF 등)은 API가 응답해도 결과가 비어 있습니다.
  - 파일을 추가하면 2D 구조를 자동으로 찾아 목록에 [2D]로 표시합니다.
  - 실행할 때는 API를 호출하지 않고 건너뛰며, summary.csv에 skipped_2d로 남깁니다.
  - 3D로 바꾸는 방법 (하나 골라 쓰세요):
      · PubChem: 화합물 페이지 → Download → 3D Conformer → SDF
      · RCSB 리간드: ..._ideal.sdf (이상 좌표, 3D)
      · Open Babel:  obabel 입력.sdf -O 출력_3d.sdf --gen3d
      · RDKit(파이썬): AllChem.EmbedMolecule(Chem.AddHs(mol)) 후 저장
  - 3D 파일인데도 결과가 비면 로그에 "결과가 비어 있습니다"로 표시됩니다.
    (금속 착물·아주 큰 분자 등 DiffDock이 처리하지 못하는 분자일 수 있음)

[API 호출 한도]
  - NVIDIA 무료 체험(build.nvidia.com)은 크레딧이 아니라 분당 요청 수로 제한됩니다.
    흔히 분당 40회로 알려져 있지만 모델·시간대에 따라 다를 수 있으니
    build.nvidia.com 오른쪽 위 계정 화면에서 본인 한도를 확인하세요.
  - "분당 최대 API 요청"(기본 30)으로 상태 확인 요청까지 포함해 속도를 맞춥니다.
  - 그래도 한도 초과(429)가 나면 서버가 알려준 시간만큼 기다렸다가 자동으로 다시 시도합니다.

[대량 실행]
  프로그램은 수천 개 파일·수십만 건 작업도 처리하도록 만들었습니다.
    - 고른 파일은 메모리가 아니라 임시 폴더(~/.diffdock_batch/staging)에 두고, 끄면 지웁니다
    - 결과 표는 최근 300건만, 화면 로그는 최근 것만 보여줍니다 (전체: confidence_summary.csv, run_log.txt)
    - 결과 폴더는 단백질별 하위 폴더로 나눠 저장합니다
    - 작업 중에는 컴퓨터가 절전 모드로 들어가지 않게 합니다 (Windows·macOS)
    - 네트워크 장애로 연속 10건이 실패하거나 저장 공간이 부족하면 멈춥니다.
      다시 "실행"하면 이미 끝난 것은 건너뛰고 남은 것부터 이어서 합니다.
    - 실행 중 상태 줄에 남은 예상 시간이 표시됩니다.
  하지만 걸리는 시간은 NVIDIA 무료 API가 정합니다. 한 건씩 차례로 보내므로
    총 시간 ≈ 작업 수 × 한 건당 시간 (예: 30초/건이면 1만 건에 약 3.5일)
  단백질 3,000개 × 리간드 500개 = 150만 건은 무료 체험 API로는 현실적이지 않습니다
  (30초/건이면 약 1.4년, 분당 40회를 꽉 채워도 최소 26일).
  이 규모는 DiffDock을 연구실 GPU에 직접 설치해서 돌리는 것을 권합니다.
  "파일 확인"을 누르면 실제 작업 수, 예상 저장 용량, 최소 소요 시간을 먼저 보여줍니다.
  대량 작업이면 "포즈 구조(.sdf) 저장"을 '합친 파일만'이나 '저장 안 함'으로 바꾸면
  파일 수와 용량이 크게 줄어듭니다.

[API 키 보안]
  - 키는 이 PC의 프로그램 안에만 있고, 브라우저 화면에는 끝 4자리만 표시됩니다.
  - "이 PC에 안전하게 저장"을 켜면 Windows 자격 증명 관리자 / macOS 키체인에 저장됩니다.
    (키체인을 쓸 수 없는 환경에서만 ~/.diffdock_batch/api_key 파일에 본인 전용 권한으로 저장)
  - 저장을 끄고 새 키를 넣으면, 예전에 저장된 키는 삭제됩니다.
  - "저장된 키 삭제" 버튼으로 언제든 지울 수 있습니다.
  - 키는 NVIDIA API(HTTPS)로만 전송되며, 로그와 summary.csv에는 마스킹되어 남습니다.
  - 프로그램은 이 컴퓨터(127.0.0.1)에서만 접속할 수 있고, 실행할 때마다 새 접속 주소가 만들어집니다.
  - 키를 코드나 파일에 직접 적지 마세요. 키가 노출되면 build.nvidia.com에서 즉시 폐기하세요.

[결과]
  출력 폴더/
    summary.csv                         전체 작업 요약 (엑셀에서 바로 열림)
    run_log.txt                         전체 실행 기록
    confidence_summary.csv              통합 결과: 단백질, 리간드, 옵션, 순위별 confidence
                                        (한 행 = 도킹 1건, confidence_rank01 ~ 포즈 수만큼)
    results_index.jsonl                 통합 CSV를 만드는 데 쓰는 기록 파일 (지우지 마세요)
    단백질/                              예) 8G43
      단백질-리간드-옵션/                예) 8G43-ZU6_ideal-poses10_td20_st18
        단백질-리간드-옵션.json          예) 8G43-ZU6_ideal-poses10_td20_st18.json
                                        기본: position_confidence 값만 저장
                                        ("JSON에는 position_confidence만 저장"을 끄면 API 응답 전체)
        rank01.sdf ...                  포즈별 구조      ┐ "포즈 구조(.sdf) 저장"으로 조절
        all_poses.sdf                   모든 포즈 합친 것 │  · 포즈별 파일 + 합친 파일 (기본)
        confidence.csv                  포즈별 confidence ┘  · 합친 파일만 / 저장 안 함
      ("저장 안 함"이면 하위 폴더 없이 단백질 폴더에 JSON만 저장)

  옵션 표기: poses=포즈 수, td=time_divisions, st=steps, _traj=trajectory 저장
  옵션을 바꿔 다시 돌리면 다른 이름으로 저장되므로 이전 결과를 덮어쓰지 않습니다.

[설정 파일 위치]
  ~/.diffdock_batch/  (Windows: C:\Users\사용자\.diffdock_batch\)
  이 폴더를 지우면 설정과 실행 환경이 초기화됩니다. (키체인에 저장된 키는 "저장된 키 삭제"로 지우세요)
