Chaperone

단백질 접힘 물리를 직접 만져보는 인터랙티브 샌드박스. 물리 엔진은 Rust 로 밑바닥부터 만들고, 시각화는 Qt Quick 3D 위에 얹었다.

PDB 구조를 읽어 잔기당 비드 하나(CA)로 줄인 Gō 모델을 세우고, 랑주뱅 열욕 안에서 실시간으로 굴린다. 비드를 마우스로 잡아당기거나 온도를 올려 변성시키면서 네이티브 접촉 분율(Q)·회전 반경(Rg)·힘-신장 곡선을 그 자리에서 본다.

화면

네이티브 구조 (1UBQ · 비드 + 결합)	튜브 표시 (Catmull-Rom 스플라인)

가열 변성 (T 1.84 · Q 0.14)	끝 잔기 당기기 (앵커 + 힘-신장 곡선)

구성

경로	역할
crates/chaperone-pdb	PDB 파서 (CA 추출 · 체인 선택)
crates/chaperone-sim	물리 엔진. Gō 힘장(결합·각·이면각·네이티브 접촉·반발·당김), 벨로시티 베를레 적분, 랑주뱅 열욕, 접힘 분석(Q · Rg · 에너지 드리프트), 이차구조 판정(P-SEA), 리본 프레임
crates/chaperone-cli	헤드리스 시나리오 실행기 (chaperone 바이너리)
crates/chaperone_bridge	CXX-Qt 브릿지. 엔진을 QML Simulation 타입으로 노출
gui/	Qt Quick 3D 프론트엔드 (main.cpp 한 파일 + qml/Main.qml)
data/pdb/	입력 구조. gitignore 대상이라 직접 받아야 한다
runs/	CLI 와 GUI 가 남기는 CSV · 로그

설계 원칙은 두 가지다. 업무 로직(물리 · 파싱 · 판정)은 전부 Rust 에 두고 Qt 없이 테스트한다. C++ 은 Qt 가 요구하는 어댑터 자리에만 쓰고 그 안에서 계산하지 않는다.

빌드

요구 사항

• Rust stable (rust-toolchain.toml)
• Qt 6.8 이상 (Core · Gui · Qml · Quick · Quick3D · QuickControls2)
• CMake 3.24 이상, Ninja
• CXX-Qt 는 CMake 가 FetchContent 로 받아온다

입력 구조는 RCSB 에서 받아 data/pdb/1UBQ.pdb 에 둔다. GUI 는 이 경로를 기본으로 연다.

curl -o data/pdb/1UBQ.pdb https://files.rcsb.org/download/1UBQ.pdb
cmake -S . -B build -G Ninja
cmake --build build

CLI 만 쓰려면 Qt 없이 cargo build --release 로 충분하다.

실행

GUI

./build/gui/chaperone-gui

조작	동작
비드 왼쪽 드래그	잡아당기기. 힘 · 신장 · 힘-신장 곡선이 갱신된다
비드 오른쪽 클릭	앵커 토글 (당길 때 반대쪽 끝을 고정)
빈 곳 드래그	카메라 회전 · 이동
Space	재생 / 정지
temperature 슬라이더	열욕 온도 (ε 단위)
tube / sticks	표시 방식
save	힘-신장 궤적을 runs/pull.csv 로 저장

CLI

cargo run --release -- spring [steps]          # 두 비드 조화 진동자, 에너지 보존 검사
cargo run --release -- chain4 [steps]          # 4 비드 사슬 (결합 · 결합각)
cargo run --release -- chain4-open [steps]
cargo run --release -- chain5 [steps]          # 5 비드 사슬 (이면각 포함)
cargo run --release -- nve [steps]             # 1UBQ NVE, 드리프트 · 각운동량 검사
cargo run --release -- fold [steps]            # 1UBQ 유지 → 용융 → 재접힘 시나리오
cargo run --release -- pdb data/pdb/1UBQ.pdb   # 파싱 결과와 네이티브 접촉 요약

시간 순서 CSV 는 stdout 으로, 요약 통계는 stderr 로 나온다.

테스트

cargo test --workspace
cargo test --workspace -- --ignored   # data/pdb/1UBQ.pdb 가 있어야 하는 것

물리 · 랑주뱅 · 접힘 · 이차구조 · 리본 테스트가 Qt 없이 돈다. 골든 궤적은 플랫폼 간 부동소수 차이를 피하려고 비트 단위로 비교한다.

이차구조 테스트의 1UBQ 골든 라벨은 scripts/verify_psea.py 의 파이썬 참조 구현에서 나왔다. 저장소 루트에서 python3 scripts/verify_psea.py 로 돌리면 라벨과 고장 주입 결과를 다시 뽑는다.

상태

• 이차구조 판정과 리본 프레임은 Rust 쪽 데이터만 완성된 상태다. 리본 렌더링은 이 프로젝트에 흥미가 다시 생긴다면 QQuick3DGeometry 커스텀 지오메트리로 붙일 예정이다.