Name: kaiwu-코딩-스킬
Author: Community

Kaiwu 모델링 및 솔루션

먼저 대상 인터프리터, 배포판 및 버전을 확인합니다. 문제가 이미 주어지고 라이선스가 설치된 경우 그대로 사용하고, 재설치하거나 묻지 않습니다. 설치되지 않은 경우 대상 환경에서 python -m pip install kaiwu (Enterprise) 또는 python -m pip install kaiwu-community (모델링 전용)를 실행합니다. 두 경우 모두 임포트 이름은 kaiwu입니다. 로컬 Enterprise 솔루션은 기존 라이선스가 필요합니다. 클라우드 CIM은 사용자가 요청하고 자격 증명을 제공하는 경우에만 사용합니다. 이 스킬을 통해 실제 하드웨어를 호출할 때 task_name은 kaiwu_skill로 시작해야 합니다(예: kaiwu_skill_tsp).

먼저 모델 동등성 보장

원래 비즈니스 목표, 실행 가능한 영역 및 솔루션 에너지를 구분합니다. 간단한 공식을 사용하여 변수, 목표 및 모든 제약 조건을 설명하고, 코드는 동일한 모델을 표현해야 합니다. 원래 목표가 최대화인 경우 음수를 취하여 QUBO를 구성할 수 있으며, 보고된 값은 여전히 원래 목표를 기준으로 계산합니다. 문제 패밀리 식별 및 변형 모델링은 필요에 따라 문제 카탈로그를 참조하십시오.

원래 요구사항	2차 인코딩; P는 양의 하드 제약 페널티 계수
정확히 하나 / 등식	`P * (sum(x) - c)**2`
최대 하나	`P * sum(x[i]*x[j] for i<j)`
a를 선택하면 b를 선택해야 함 / 동시 선택 또는 미선택	`Pa(1-b)` / `P(a-b)*2`
두 리터럴 OR: 적어도 하나는 참	`P * (1-a)(1-b)`; `(a+b-1)*2` 아님
가중 소프트 OR	가중치 * 위반 표시; 단일 리터럴은 `1-a`, 두 리터럴은 `(1-a)*(1-b)`
정수 자원 상한 `load <= C`	`P(load+s-C)*2`, 음이 아닌 정수 완화 s는 모든 `0..C`를 커버
적어도 하나 (다중 변수)	`P(sum(x)-1-s)*2`, s는 `0..n-1`을 커버

부울 양 리터럴의 진리값은 x, 음 리터럴은 1-x입니다. OR의 위반 표시는 모든 리터럴이 거짓일 때만 1입니다. 1-sum(literals) (음수가 될 수 있음) 또는 sum(1-literals)**2 (선호도를 변경함)를 사용할 수 없습니다. 세 개 이상의 리터럴의 곱은 고차 항이므로 2차 모델로 직접 사용할 수 없습니다. 적절한 보조 변수와 등가 차수 축소가 필요합니다.

완화 변수는 Integer('slack', min_value=0, max_value=C)를 직접 사용하거나 이진 가중치 인코딩을 사용할 수 있습니다. 예를 들어 상한 C=5인 경우 가중치 [1,2,2]로 0..5를 정확히 표현할 수 있습니다. C=0이면 완화 비트를 생성하지 않습니다. 일반적으로 C>0인 경우 k=C.bit_length()-1, 가중치는 [2**j for j in range(k)] + [C-(2**k-1)]입니다. 용량은 잉여를 허용하므로 (load-C)**2를 상한 제약 조건으로 사용할 수 없습니다.

페널티 계수는 원래 목표가 개선될 수 있는 범위를 포함해야 합니다. 하드 페널티 항의 최소 비제로 값이 1인 경우 P를 원래 목표의 상한과 하한의 차이보다 크게 취합니다. 가중 소프트 규칙의 경우 가중치 합계보다 큰 값을 취할 수 있습니다. 비음수 할당 비용의 경우 각 항목 비용의 상한 합계보다 큰 값을 취할 수 있습니다. 너무 큰 계수는 동적 범위를 늘리고 샘플링을 어렵게 만들 수 있으므로 근거를 명시해야 하며, 잘못된 모델을 수정하기 위해 P를 무한정 늘릴 수 없습니다. 입증 가능한 국소 수정 한계가 있는 경우 더 엄격한 한계를 우선 사용합니다. 예를 들어 비음수 가중 정점 커버 문제의 경우 목표는 sum(w[i]*x[i]), 페널티 항은 P*sum((1-x[u])*(1-x[v]))입니다: P>max(w)를 취하면 됩니다. 가중치가 음이 아닌 정수인 경우 기본적으로 P=max(w)+1을 직접 취하고, 느낌에 따라 페널티 계수를 더 키우지 않습니다. 커버되지 않은 모서리가 있으면 끝점을 하나 추가할 수 있고, 목표 증가는 max(w)를 초과하지 않으며, 페널티 항은 최소 P만큼 감소하며, 새 위반이 발생하지 않습니다. 이는 단조 커버 제약 조건에만 적용되며, 용량, 상호 배타 또는 등식 제약 조건에 적용할 수 없습니다. 수정이 다른 제약 조건을 위반하지 않음을 설명해야 합니다.

Enterprise 1.4.0: 다음 API 흐름을 직접 사용

다음은 실행 가능한 세 가지 선택지 중 하나의 예시로, SDK 호출 및 디코딩만 보여줍니다. 실제 문제를 처리하려면 목표, 페널티 항 및 원래 비즈니스 검증을 대체하십시오. kaiwu.seed, QuboModel.add_variable, vartype 또는 iterations_per_temperature 등의 인터페이스를 만들지 마십시오.

import numpy as np
from kaiwu.core import (ndarray, Binary, QuboModel, PenaltyMethodConstraint,
                        qubo_matrix_to_ising_matrix, qubo_model_to_ising_model,
                        get_sol_dict, get_val)
from kaiwu.classical import SimulatedAnnealingOptimizer

x = ndarray(3, 'x', Binary)
original = 3*x[0] + 2*x[1] + 4*x[2]
model = QuboModel()
model.set_objective(original + 10*(x.sum()-1)**2)
model.set_constraint_handler(PenaltyMethodConstraint)  # 클래스를 전달, 인스턴스화하지 않음
q = model.get_matrix()
h, offset = qubo_matrix_to_ising_matrix(q)  # offset은 상수, 변수 딕셔너리가 아님
variables = qubo_model_to_ising_model(model).get_variables()
solver = SimulatedAnnealingOptimizer(
    initial_temperature=100, alpha=0.99, cutoff_temperature=0.001,
    iterations_per_t=100, size_limit=32, rand_seed=20261001)
pool = np.asarray(solver.solve(h))
valid = []
for row in pool:
    sol = get_sol_dict(row[:-1]*row[-1], variables)
    bits = [int(round(get_val(x[i], sol))) for i in range(3)]
    if sum(bits) == 1:  # 실제 문제에서는 여기서 모든 원래 비즈니스 제약 조건을 다시 계산해야 함
        valid.append((int(round(get_val(original, sol))), bits))
if not valid:
    raise RuntimeError('SDK 후보 중 실행 가능한 해가 없습니다')
cost, decision = min(valid)
print({'bits': decision, 'objective': cost, 'feasible': True})

확인된 SA 매개변수: initial_temperature, alpha, cutoff_temperature, iterations_per_t, size_limit, flag_evolution_history, verbose, rand_seed, process_num. seed, time_limit, num_reads를 전달하지 마십시오. 실행 시간을 제어하려면 외부에서 배치를 관리해야 하며, 생성자를 위조할 수 없습니다. 예제의 bits는 이진 결정이며, 모든 작업의 solution 필드와 같지 않습니다. 출력 필드와 번호 규칙은 현재 작업을 따릅니다. JSON이 필요한 경우 json.dumps를 사용하고, 예제의 출력 방식을 그대로 따르지 마십시오. 중소 규모의 제약이 있는 문제의 경우 iterations_per_t를 늘리거나, 다른 rand_seed를 가진 여러 배치의 SDK 후보를 사용할 수 있습니다. 동시에 실제 소요 시간을 기록하고 사용자 시간 제한을 준수해야 합니다. 예제 매개변수는 시작점이며, 각 문제에 대해 최적을 보장하지 않습니다.

페널티 계수로 인해 Ising 행렬의 진폭이 예제 온도보다 훨씬 큰 경우 초기 온도 100으로는 탐색이 충분하지 않을 수 있습니다. 작업이 매개변수를 고정하지 않은 경우 먼저 initial_temperature=max(100, 2*np.max(np.abs(h)))를 취할 수 있습니다. 수십 개 변수의 로컬 제약 문제의 경우 iterations_per_t=200, size_limit=128을 시작점으로 사용하고, 실제 후보 품질 및 시간 제한에 따라 판단합니다. 작은 예제의 온도 및 해 풀 크기를 그대로 복사하면서 최적을 보장한다고 주장하지 마십시오.

백 개 이상의 변수가 있고 문제가 고정 샘플링 매개변수를 제공하지 않는 최적화 전달의 경우, 작은 예제의 낮은 샘플링 구성만 실행하고 끝내지 마십시오. 예를 들어 품질을 목표로 하고 약 40초의 실행 예산이 있는 경우, 128~512개 변수이고 결합이 희소한(비제로 비율이 10% 미만) 기본 배치는 iterations_per_t=(200,800,2400), size_limit=128입니다. 다른 매개변수는 동일하게 유지하고 항상 지정된 시드를 사용하며, 원래 행렬은 한 번만 컴파일됩니다. 변수가 더 많거나 행렬이 조밀하거나 예산이 더 짧은 경우 (200,400,800)과 같은 작은 배치부터 실제 측정을 시작합니다. 각 배치 후 실제 소요 시간과 다음 배치 반복 횟수의 비율을 기반으로 오버헤드를 추정하고, 최소 20%의 여유와 2초의 디코딩 출력 시간을 확보합니다. 이번 배치가 남은 시간 내에 완료될 것으로 예상되면 기본 배치를 계속 진행하고, 중단 여부는 여전히 다음의 후보 품질 및 시간 제한 기준에 따라 판단합니다. 시간 초과가 예상되면 즉시 지금까지 찾은 최상의 실행 가능한 후보를 반환하고, 고정된 배치 횟수를 채우기 위해 시간 초과하지 않습니다. 전체 프로그램은 하나의 통일된 마감 시간만 유지합니다. 사용자 실행 시간 제한 내에서 모든 실제 반환된 후보에 대해 원래 비즈니스 목표를 다시 계산하고, 비용이 가장 낮은 실행 가능한 후보를 유지합니다. 이는 프로그램 내 예산이 있는 솔루션 전략에 해당합니다. 첫 번째 실행 가능한 후보를 최상의 결과로 간주하지 마십시오. 소프트 선호도는 하드 제약 조건이 아닙니다. 하드 제약 조건이 없는 경우 인위적으로 큰 페널티 계수를 도입하거나 문제에서 요구하지 않은 균형 제한을 추가하지 마십시오.

규모와 복잡성에 따라 기본 매개변수를 조정하십시오. 위 수치는 경험적 시작점이며, 모든 문제에 대한 고정된 레시피가 아닙니다. 먼저 변수 수, 비제로 결합 수, 계수 범위 및 하드 제약 조건 강도를 확인한 다음, 실행 시간 제한과 함께 단일 배치 규모를 계획합니다. 조밀한 행렬 또는 많은 보조 변수는 각 솔루션 비용을 증가시킵니다. 먼저 작은 배치로 실제 측정을 하고, 컴파일, 디코딩 및 출력 시간을 예약합니다. 반복 횟수를 늘리거나, 냉각 속도를 늦추거나, 해 풀을 확장한다고 해서 더 나은 비즈니스 결과가 보장되는 것은 아닙니다. 지금까지 발견된 최상의 실행 가능한 SDK 후보를 누적하여 유지하고, 후보의 실행 가능한 비율, 원래 비즈니스 비용 및 실제 소요 시간을 비교한 후 계속 진행 여부를 결정합니다. 더 나은 이전 후보를 덮어쓰지 마십시오. 잘못된 모델링이나 너무 큰 페널티 계수를 먼저 수정한 다음 매개변수를 조정합니다. 사용된 매개변수와 중지 조건을 기록하고, 최적을 보장한다고 주장하지 마십시오.

먼저 작업에 지정된 실험 매개변수를 따르십시오. 문제가 난수 시드를 고정하는 경우, 솔버를 생성할 때마다 동일한 지정된 rand_seed를 명시적으로 사용하고, 시드를 증가시키거나, 다른 시드 목록을 만들거나, 시간으로 시드를 생성하지 마십시오. 위의 여러 시드 제안은 작업이 허용하는 경우에만 사용하십시오. 고정된 시드에서 작업이 허용하는 경우에만 온도, 반복 횟수 등의 매개변수를 조정합니다. 실제 구성을 기록합니다.

solve는 에너지별로 정렬되지 않은 스핀 풀을 반환하며, 마지막 열은 기준 스핀입니다. 각 행을 반복하면서 먼저 기준 스핀을 곱하여 정규화한 다음, Ising 모델의 변수 딕셔너리를 사용하여 디코딩합니다. get_val을 사용하여 변수에 액세스하고, 내부 문자열 키를 추측하지 마십시오. 실제 후보에서 디코딩되고 원래 문제를 검증한 결정만 출력할 수 있습니다. 완전 탐색, 하드코딩된 답변 또는 타사 솔버를 SDK 출력으로 대체하지 마십시오.

자체적으로 목표에 추가한 페널티 항은 등록된 제약 조건과 같지 않습니다. add_constraint가 없으면 verify_constraint가 0을 반환하더라도 원래 문제의 실행 가능성을 증명할 수 없습니다. 등록 여부와 관계없이 모든 비즈니스 제약 조건을 결정에서 다시 계산합니다. verify_constraint를 호출하는 경우 먼저 unsatisfied, details = model.verify_constraint(sol)을 언패킹합니다. 비즈니스 비용과 QUBO/Ising 에너지를 별도로 출력하고, 페널티 항, 상수 오프셋 또는 최대화 음수 부호를 비즈니스 지표로 사용하지 마십시오. 계수를 전달할 때 변수 순서, 상수, 선형 항, 2차 항 및 보조 변수 매핑을 저장합니다. P는 실제로 계수에 곱해지며, 각 항목의 기여도가 누적됩니다. SDK 행렬 순서가 배열 생성 순서와 반드시 일치하는 것은 아닙니다. 변환기 offset에는 표현식 컴파일 중에 제거된 비즈니스 상수가 포함되지 않으므로 별도로 저장합니다. 동일 상태 비용은 w*(1-x[i]-x[j]+2*x[i]*x[j]), 다른 상태 비용은 w*(x[i]+x[j]-2*x[i]*x[j])이며, 00, 01, 10, 11로 방향을 확인하여 동일 채널 간섭과 최대 컷 목표를 혼동하지 않도록 합니다.

가중 소프트 규칙의 보고 기준은 문제를 따릅니다. "위반 비용 최소화"를 요구하는 경우 sum(weight for rule in soft if not satisfied(rule))을 보고하고, 후보도 이 값이 가장 작은 합법적인 계획을 선택합니다. "충족된 가중치 합"과 "위반 비용"을 더하면 소프트 가중치 총합과 같으며, 두 최적화 방향은 반대이므로 objective 필드 이름을 혼용할 수 없습니다. 출력 전에 최종 bits를 기반으로 원래 목표를 다시 계산합니다. 결정이 동일하더라도 반대 기준의 값을 보고하는 것은 전달 오류에 해당합니다.

버전 및 주제별 자료: 관련 부분만 읽기

API	Enterprise 1.3.1	Enterprise 1.4.0
QuboModel	`kaiwu.qubo`	`kaiwu.core`
두 개의 QUBO/Ising 변환기	`kaiwu.conversion`	`kaiwu.core`
ndarray/Binary/Integer/quicksum/get_val/get_sol_dict/PenaltyMethodConstraint	`kaiwu.core`	`kaiwu.core`
배열 값 읽기	요소별 `get_val` 또는 `get_array_val`	`get_val`이 배열 지원; `get_array_val` 없음
PrecisionReducer	`kaiwu.cim`	`kaiwu.preprocess`
페널티 함수법 솔버	`kaiwu.solver.PenaltyMethodSolver`	`kaiwu.hybrid.PenaltyMethodOptimizer`

버전을 알고 있으면 해당 모듈을 직접 임포트합니다. 명시적으로 크로스 버전이 요구되거나 확인할 수 없는 경우에만 실제 마이그레이션된 임포트에 대해 호환성 분기를 만듭니다. quicksum은 크로스 버전에서 list를 전달합니다. ndarray((n,m), 'x', Binary)는 위치 매개변수를 사용합니다. Community는 로컬 클래식 솔버가 있다고 가정할 수 없습니다.

1.3.x 또는 더 완전한 시그니처: Enterprise API, API 개요.
1.3.x TSP 기록 예제: SDK 예제; 1.4.x로 마이그레이션하려면 위 표에 따라 임포트를 변경해야 합니다.
정밀도 처리: PrecisionReducer는 최적화기 데코레이터이며, 버전 간 기본값이 변경되므로 only_feasible_solution을 명시적으로 작성합니다. perform_precision_adaption_split은 (split_matrix, last_var_idx)를 반환하며, 매핑에 따라 원래 행렬 에너지를 복원하고 검증합니다.
실제 하드웨어 연결: 프로세스 보충, 작업이 실제 하드웨어를 요구하는 경우에만 읽습니다.
기타 인터페이스: 모듈 인덱스, Community.
연속량과 이산 결정이 동시에 존재하는 경우: 먼저 완전한 결합 제약 조건을 작성합니다. Kaiwu가 이산 후보를 구하고, 이산량을 고정한 후 연속/흐름 하위 문제로 결정합니다. 많은 연속량을 전체 이진 전개하지 말고, "활성화되지 않으면 흐름이 0"과 같은 결합 제약 조건을 삭제하지 마십시오.

전달 및 검증

처음부터 생성하는 경우 완전한 스크립트를 제공합니다. 기존 코드를 수정하는 경우 필요한 변경 사항만 제공합니다. 문제의 데이터, 출력 프로토콜 및 시간 제한을 준수하고, 코드 완전성을 우선시합니다. 실행 조건이 허용되는 경우 먼저 임포트를 확인한 다음, 실제로 컴파일, 솔루션, 디코딩 및 원래 비즈니스를 확인합니다. 작업이 실행을 금지하는 경우 실행했다고 주장하지 마십시오.

수학적 자체 점검은 두 가지에 중점을 둡니다: 모든 합법적인 비즈니스 상태가 보조 변수를 취하여 하드 페널티 항을 0으로 만들 수 있는지; 이때 에너지가 원래 목표에 상수를 더한 것과 같은지. 독립적인 개발 검증에서 진리표 또는 작은 인스턴스의 완전 탐색을 사용하여 인코딩 오류를 확인할 수 있지만, 이 열거 결과를 SDK 반환 결과와 혼동해서는 안 됩니다. 참조 경계 또는 독립적인 증명이 있는 경우에만 최적을 주장합니다. 그렇지 않으면 찾은 실행 가능한 해, 실제 목표 값 및 최적이 입증되지 않았음을 보고합니다.

보충: 코드 전달 규칙

다음 규칙은 새로 추가되거나 수정된 SDK 코드를 제한합니다. 위의 모델링 및 버전 요구 사항을 유지합니다.

단일 책임 유지. 모델링, SDK 솔루션, 후보 디코딩, 원래 비즈니스 검증을 각각 명확한 단계로 구성합니다. 규모가 작으면 하나의 스크립트와 소수의 함수로 충분합니다. SDK를 한 번 호출하기 위해 일반 프레임워크, 플러그인 등록, 다중 계층 상속 또는 많은 전달 래퍼를 도입하지 마십시오. 이번 변경으로 인한 데드 코드, 중복 분기 및 사용되지 않는 종속성을 제거하십시오.
확인된 인터페이스 사용. SDK 버전을 알고 있으면 해당 API를 직접 임포트하고, 전체 패키지를 스캔하거나 추측한 클래스 이름과 매개변수를 번갈아 시도하지 마십시오. 여러 기존 버전과의 호환성이 정말로 필요한 경우에만 실제 마이그레이션된 인터페이스를 중심으로 좁은 분기를 작성하고, 비즈니스 오류를 버전 호환성 문제로 위장하지 마십시오.
예외에는 명확한 처리 결과가 있어야 함. 입력, 권한 부여, 외부 호출 등 실제 경계에서만 처리할 수 있는 구체적인 예외를 캡처합니다. 복구할 수 없는 경우 이유를 유지하고 실패와 함께 종료합니다. except Exception: pass, 다중 중복 캡처, 무한 재시도, 오류 후 가짜 실행 가능한 해 또는 "성공" 기본값 반환을 금지합니다. 고정된 내부 계산에 의미 없는 try/except를 추가하지 마십시오.
실제 경계에 따라 검증. 외부 데이터에 필요한 차원, 값 범위 및 제약 조건 일관성을 확인합니다. 내부에서 이미 검증된 데이터를 계층적으로 반복 확인하지 않고, 로컬 작은 스크립트에 작업과 관련 없는 보안 프레임워크를 추가하지 마십시오. 키는 기존 환경 또는 구성에서 읽고, 하드코딩하거나 로그에 쓰지 마십시오. 데이터를 구문 분석하기 위해 eval, exec 또는 셸 명령어 연결을 사용하지 마십시오. 설치, 네트워킹 및 클라우드 제출은 현재 작업의 권한 범위를 준수합니다.
솔루션 비용을 제어 가능하게 유지. 변수 규모와 시간 제한에 따라 온도 감쇠, 온도당 반복 횟수 및 해 풀 크기를 설정하고, 처음부터 매우 큰 매개변수를 적용하지 마십시오. 외부 검사는 이미 차단된 solve를 중단할 수 없으므로 단일 배치도 충분히 작아야 합니다. 단조 시계를 사용하여 배치를 관리하고 실제 소요 시간을 기록합니다. 호출, 시간 또는 비용 제한에 도달하면 중지하고, 반복적인 재연결로 지연시키지 마십시오.
불필요한 계산 줄이기. 변경되지 않는 행렬, 데이터 및 변수 매핑을 재사용합니다. 후보를 배치별로 디코딩하고 필터링하며, 중복 해를 무제한으로 누적하지 말고, 명확한 계산 대신 거대한 중간 배열을 사용하지 마십시오. 속도를 높이기 위해 실제 제약 조건을 삭제하거나, 원래 목표를 변경하거나, SDK 답변이 아닌 것으로 솔루션 결과를 대체하지 마십시오.
인덱스와 단위를 명확하게 유지. 입력 번호와 배열 첨자는 진입점에서 통일되게 변환합니다. 양/음 리터럴은 idx = abs(literal) - 1로 위치를 찾은 다음 반전 여부를 결정합니다. 비즈니스 목표, 페널티 항 및 에너지 오프셋을 구분하고, 의미를 설명할 수 있는 변수 이름을 사용하며, 여러 함수에서 각각 모순되는 변환을 작성하지 마십시오.
정확성을 설명할 수 있는 검증만 수행. 대표적인 실행 가능/불가능 경계, 원래 비즈니스 목표 및 실제 SDK 후보 출처를 확인합니다. 구현 텍스트와 일치하는 테스트만을 증명으로 간주하지 마십시오. 완전하고 실행 가능한 필수 코드를 전달하고, 실제로 검증한 내용을 명확히 밝힙니다. 실행할 수 없으면 바로 설명하고, 실행 기록을 위조하지 마십시오.

kaiwu-코딩-스킬