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` 등

설치

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 에

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

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

방법 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 자립본.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

quark_plugin_koreaq-0.1.0.tar.gz (6.1 kB view details)

Uploaded Aug 10, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

quark_plugin_koreaq-0.1.0-py3-none-any.whl (6.9 kB view details)

Uploaded Aug 10, 2026 Python 3

File details

Details for the file quark_plugin_koreaq-0.1.0.tar.gz.

File metadata

Download URL: quark_plugin_koreaq-0.1.0.tar.gz
Upload date: Aug 10, 2026
Size: 6.1 kB
Tags: Source
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for quark_plugin_koreaq-0.1.0.tar.gz
Algorithm	Hash digest
SHA256	`8044fe18b2a73a62dff563e3c9abe4652819435dd75d817cc6c47bf4f8ed0df5`
MD5	`da0c9e7898ea4be9ab0e7ab961c0d7ac`
BLAKE2b-256	`8f583ab55d1ea3a88f57e6cb94b27aab16fc2a531838d23dd305196cfcaa48b7`

See more details on using hashes here.

Provenance

The following attestation bundles were made for quark_plugin_koreaq-0.1.0.tar.gz:

Publisher: publish-quark-plugin.yml on liveplex-cpu/koreaq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: quark_plugin_koreaq-0.1.0.tar.gz
- Subject digest: 8044fe18b2a73a62dff563e3c9abe4652819435dd75d817cc6c47bf4f8ed0df5
- Sigstore transparency entry: 2407572586
- Sigstore integration time: Aug 10, 2026
Source repository:
- Permalink: liveplex-cpu/koreaq@c5d6ba54a9a0080708aa5925accefa339e6a0293
- Branch / Tag: refs/tags/quark-plugin-koreaq-v0.1.0
- Owner: https://github.com/liveplex-cpu
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-quark-plugin.yml@c5d6ba54a9a0080708aa5925accefa339e6a0293
- Trigger Event: push

File details

Details for the file quark_plugin_koreaq-0.1.0-py3-none-any.whl.

File metadata

Download URL: quark_plugin_koreaq-0.1.0-py3-none-any.whl
Upload date: Aug 10, 2026
Size: 6.9 kB
Tags: Python 3
Uploaded using Trusted Publishing? Yes
Uploaded via: twine/7.0.0 CPython/3.13.14

File hashes

Hashes for quark_plugin_koreaq-0.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`1772eca4e8b302b1714e425c40902dfe4c1a533cc0ec2326b796df43dc9e3dbd`
MD5	`9c871517d9f24a3ee2e3cbecce6c3c6d`
BLAKE2b-256	`a581dc32a3a7ec00004dd059d03b96c31eb51be1100b810c4faec60e5a030e38`

See more details on using hashes here.

Provenance

The following attestation bundles were made for quark_plugin_koreaq-0.1.0-py3-none-any.whl:

Publisher: publish-quark-plugin.yml on liveplex-cpu/koreaq

Attestations: Values shown here reflect the state when the release was signed and may no longer be current.

Statement:
- Statement type: https://in-toto.io/Statement/v1
- Predicate type: https://docs.pypi.org/attestations/publish/v1
- Subject name: quark_plugin_koreaq-0.1.0-py3-none-any.whl
- Subject digest: 1772eca4e8b302b1714e425c40902dfe4c1a533cc0ec2326b796df43dc9e3dbd
- Sigstore transparency entry: 2407572746
- Sigstore integration time: Aug 10, 2026
Source repository:
- Permalink: liveplex-cpu/koreaq@c5d6ba54a9a0080708aa5925accefa339e6a0293
- Branch / Tag: refs/tags/quark-plugin-koreaq-v0.1.0
- Owner: https://github.com/liveplex-cpu
- Access: private
Publication detail:
- Token Issuer: https://token.actions.githubusercontent.com
- Runner Environment: github-hosted
- Publication workflow: publish-quark-plugin.yml@c5d6ba54a9a0080708aa5925accefa339e6a0293
- Trigger Event: push

Release history Release notifications | RSS feed

This release

0.1.0 This release

Aug 10, 2026 2 files

quark-plugin-koreaq 0.1.0

quark-plugin-koreaq

무엇을 하나

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

설치

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

config 예시

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

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

방법 B — 수동 배포

정직 경계

Project links

Key dates

1 maintainer

Credits

GitHub Statistics

License expression

Requires

Classifiers

Download files

Source Distribution

Built Distribution

File details

File metadata

File hashes

Provenance

File details

File metadata

File hashes

Provenance

Release history Release notifications | RSS feed