quark-plugin-koreaq

KoreaQuantum 양자영감 시뮬레이티드 어닐링 솔버를 QUARK 3.0 벤치마크 프레임워크의 공식 플러그인으로 노출한다 (F-167).

QUARK 3.0(quark-framework)은 플러그인을 독립 PyPI 패키지로 배포하는 탈중앙 구조다 (예: quark-plugin-dwave, quark-plugin-mis, 외부 기관의 quark-plugin-mqss·-lrz). 이 플러그인은 그 규격을 따라 우리 솔버를 QUARK 파이프라인의 Solver 단계로 제공한다.

무엇을 하나

QUARK Mapping이 만든 QUBO(quark.interface_types.Qubo)를 받아 양자영감 병렬 SA로 풀고, 해 비트스트링을 quark.interface_types.Other로 반환한다. 운영 플랫폼의 sa-gpu와 동일 계열 알고리즘을 자립형(quark-framework + numpy만 의존) 으로 포팅해, 우리 사설 패키지 없이 pip install만으로 재현 가능하다.

QUARK 3.0 규격 준수 (실제 소스 대조)

설치

pip install quark-framework          # 3.0 코어
pip install -e integrations/quark-plugin-koreaq   # 이 플러그인(개발 설치)
# 배포 후: pip install quark-plugin-koreaq

요구: Python ≥ 3.12 (우리 로컬 3.14에서도 설치·구동 확인).

검증 (실제 quark-framework 3.0으로 재현)

레거시 shim이 아니라 실제 설치된 quark.core/quark.interface_types 로 검증한다:

python integrations/quark-plugin-koreaq/validate_real_quark.py

결과(재현): MIS QUBO를 전탐색 진짜 최적과 대조 — 전 케이스 gap 0·feasible.

  4-cycle       N=4 found=2 optimal=2 feasible=True energy=-2.0 -> OPTIMAL
  5-path        N=5 found=3 optimal=3 feasible=True energy=-3.0 -> OPTIMAL
  petersen-ish  N=6 found=3 optimal=3 feasible=True energy=-3.0 -> OPTIMAL

로더/팩토리(=python -m quark가 쓰는 경로)로도 등록·생성·구동 확인:

from quark.plugin_manager import loader, factory
loader.load_plugins(["quark_plugin_koreaq"])
mod = factory.create("simulated_annealer_koreaq", {"seed": 7})
# mod.preprocess(Qubo...); mod.postprocess(None) → Data(Other([...]))

config 예시

config.example.yml 참조. 파이프라인의 Solver 자리에 simulated_annealer_koreaq를 둔다. Mapping은 QUBO를 산출하는 어떤 QUARK Mapping과도 호환된다(우리 solver는 as_matrix()로 일반 QUBO를 받는다).

python -m quark -c integrations/quark-plugin-koreaq/config.example.yml

PyPI 배포 (공식화 마지막 단계)

이 패키지는 자립형이라 그대로 배포 가능하다. 자동 배포(권장, 토큰 불필요) 를 세팅해 뒀다.

방법 A — 자동 배포 (GitHub Actions + PyPI Trusted Publishing)

.github/workflows/publish-quark-plugin.yml. quark-plugin-koreaq-v* 태그를 밀면 빌드→PyPI 게시까지 자동. 사전 1회: pypi.org → 계정 → Publishing → Add a pending publisher 에

설정 후 태그만 밀면(대신 실행 가능) 게시된다. 장기 토큰을 어디에도 두지 않는다.

방법 B — 수동 배포

cd integrations/quark-plugin-koreaq
python -m build          # dist/*.whl, *.tar.gz (빌드·twine check 통과 확인됨)
twine upload dist/*      # PyPI 토큰 필요

배포되면 pip install quark-plugin-koreaq로 누구나 우리 솔버를 QUARK에서 재현 = QUARK 3.0이 정의한 정식 확장(공인) 방식. 별도 리포로 분리하려면 QUARK-plugin-template을 'Use this template'로 생성 후 이 src/를 옮긴다.

정직 경계

• 이 플러그인은 실제 quark-framework 3.0 클래스로 검증됐다(위 재현 결과). 다만 이는 '어댑터·솔버가 3.0 규격 위에서 정확히 작동함'의 실증이며, PyPI 공개 배포·QUARK-framework org 편입은 별도다(배포는 계정 행위, org 편입은 메인테이너 문의·심사 필요 — 미확정).
• 성능은 양자영감 고전 SA다. 양자 실기기 우위 주장이 아니다.
• 대형·GPU 가속은 운영 sa-gpu(CuPy)로 교체 가능. 본 플러그인은 재현성 우선 NumPy 자립본.