Metadata-Version: 2.4
Name: quark-plugin-koreaq
Version: 0.1.0
Summary: KoreaQuantum quantum-inspired simulated-annealing solver plugin for the QUARK 3.0 benchmark framework
Author: QuantumAI Solutions Inc. (KoreaQuantum)
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/liveplex-cpu/koreaq
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: quark-framework>=0.4.6
Requires-Dist: numpy>=1.26

# 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 규격 준수 (실제 소스 대조)

| 요소 | 구현 |
|---|---|
| 모듈 | `@dataclass class SimulatedAnnealerKoreaq(Core)` (`quark.core`) |
| 입력 | `preprocess(self, data: Qubo) -> Result` — `Qubo.as_matrix()`로 일반 QUBO 수용 |
| 출력 | `postprocess(...) -> Data(Other(비트스트링))` |
| 등록 | `__init__.py`의 `register()` → `factory.register("simulated_annealer_koreaq", ...)` |
| config | 데이터클래스 필드(`sweeps`/`chains`/`seed`)가 곧 config 파라미터 |
| 메트릭 | `get_metrics()` → `objective_value` 등 |

## 설치

```bash
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`** 로 검증한다:

```bash
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`가 쓰는 경로)로도 등록·생성·구동 확인:

```python
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를 받는다).

```bash
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* 에

| 항목 | 값 |
|---|---|
| PyPI Project Name | `quark-plugin-koreaq` |
| Owner | `liveplex-cpu` |
| Repository name | `koreaq` |
| Workflow filename | `publish-quark-plugin.yml` |
| Environment name | `pypi` |

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

### 방법 B — 수동 배포

```bash
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 자립본.
