kaiwu-coding-skill

Modelagem e Solução com Kaiwu

Primeiro, confirme o interpretador alvo, a distribuição e a versão; quando o problema já for fornecido e a licença estiver instalada, utilize diretamente, sem reinstalar ou perguntar. Se não estiver instalado, use python -m pip install kaiwu (Enterprise) ou python -m pip install kaiwu-community (apenas modelagem) no ambiente alvo. O nome de importação para ambos é kaiwu. A solução local com Enterprise requer uma licença já instalada; a CIM em nuvem só deve ser usada quando solicitada pelo usuário e com as credenciais fornecidas. Ao chamar hardware real através deste skill, o task_name deve começar com kaiwu_skill, por exemplo kaiwu_skill_tsp.

Primeiro, Garanta a Equivalência do Modelo

Diferencie o objetivo original do negócio, o espaço factível e a energia de solução. Use fórmulas curtas para descrever variáveis, objetivos e todas as restrições; o código deve expressar o mesmo modelo. Quando o objetivo original for de maximização, pode-se tomar seu negativo para construir o QUBO, mas o valor reportado ainda deve ser calculado de acordo com o objetivo original. Para identificação da família de problemas e modelagem de variantes, consulte o Catálogo de Problemas conforme necessário.

Requisito Original	Codificação Quadrática; P é o coeficiente de penalidade forte e positivo
Exatamente um / Igualdade	P * (sum(x) - c)**2
No máximo um	P * sum(x[i]*x[j] for i<j)
Escolher a implica escolher b / Ambos escolhidos ou ambos não escolhidos	P*a*(1-b) / P*(a-b)**2
OR de dois literais: pelo menos um verdadeiro	P * (1-a)*(1-b); não (a+b-1)**2
OR suave ponderado	Peso multiplicado pelo indicador de violação; para um único literal é 1-a, para dois literais é (1-a)*(1-b)
Limite superior de recurso inteiro load <= C	P*(load+s-C)**2, onde a folga inteira não negativa s cobre todo 0..C
Pelo menos um (múltiplas variáveis)	P*(sum(x)-1-s)**2, s cobre 0..n-1

O valor verdadeiro de um literal positivo é x, de um literal negativo é 1-x. O indicador de violação de um OR é 1 apenas quando todos os literais são falsos; não use 1-sum(literals) (pode ser negativo), nem sum(1-literals)**2 (altera a preferência). Produtos de três ou mais literais são termos de alta ordem e não podem ser usados diretamente como um modelo quadrático; são necessárias variáveis auxiliares apropriadas e redução de ordem equivalente.

Variáveis de folga podem ser usadas diretamente com Integer('slack', min_value=0, max_value=C), ou codificadas com pesos binários. Por exemplo, para um limite superior C=5, os pesos [1,2,2] podem representar exatamente 0..5; C=0 não cria bits de folga. Geralmente para C>0, tome k=C.bit_length()-1, pesos [2**j for j in range(k)] + [C-(2**k-1)]. A capacidade permite folga; não se pode usar (load-C)**2 como uma restrição de limite superior.

Os coeficientes de penalidade devem cobrir a faixa de melhoria possível do objetivo original: se o valor mínimo não nulo do termo de penalidade forte for 1, tome P maior que a diferença entre o limite superior e inferior do objetivo original. Para regras suaves ponderadas, pode-se tomar P maior que a soma dos pesos; para custos de alocação não negativos, pode-se tomar P maior que a soma dos limites superiores de cada custo. Coeficientes muito grandes aumentam a faixa dinâmica e dificultam a amostragem; a justificativa deve ser fornecida, e não se pode corrigir um modelo errado aumentando P indefinidamente. Quando existir um limite de reparo local demonstrável, use o limite mais restrito. Por exemplo, para Cobertura de Vértices com pesos não negativos, o objetivo é sum(w[i]*x[i]), termo de penalidade P*sum((1-x[u])*(1-x[v])): tomar P>max(w) é suficiente. Quando os pesos são inteiros não negativos, por padrão, tome diretamente P=max(w)+1, sem aumentar o coeficiente de penalidade por intuição. Porque qualquer aresta descoberta pode ter um extremidade adicionada, o objetivo aumenta no máximo max(w), o termo de penalidade diminui em pelo menos P, e nenhuma nova violação é criada. Isso se aplica apenas a este tipo de restrição de cobertura monotônica; não pode ser aplicado a restrições de capacidade, exclusão mútua ou igualdade; deve-se explicar que o reparo não quebra outras restrições.

Enterprise 1.4.0: Use Diretamente Este Fluxo de API

Abaixo está um exemplo executável de três opções, mostrando apenas a chamada do SDK e a decodificação; substitua o objetivo, as penalidades e a validação do negócio original para lidar com o problema real. Não invente interfaces como kaiwu.seed, QuboModel.add_variable, vartype ou 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)  # Passa a classe, não instancia
q = model.get_matrix()
h, offset = qubo_matrix_to_ising_matrix(q)  # offset é uma constante, não um dicionário de variáveis
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:  # No problema real, recalcule todas as restrições originais do negócio aqui
        valid.append((int(round(get_val(original, sol))), bits))
if not valid:
    raise RuntimeError('Nenhuma solução factível entre os candidatos do SDK')
cost, decision = min(valid)
print({'bits': decision, 'objective': cost, 'feasible': True})

Parâmetros SA verificados: initial_temperature, alpha, cutoff_temperature, iterations_per_t, size_limit, flag_evolution_history, verbose, rand_seed, process_num. Não passe seed, time_limit, num_reads. O controle do tempo de execução deve ser feito gerenciando lotes externamente; não se pode fabricar parâmetros de construção. Os bits do exemplo são decisões binárias, não iguais ao campo solution de cada tarefa. Os campos de saída e convenções de numeração dependem da tarefa atual; ao exigir JSON, use json.dumps, não copie a forma de impressão do exemplo. Para problemas de médio porte com restrições, pode-se aumentar iterations_per_t, ou usar múltiplos lotes com diferentes rand_seed de candidatos do SDK; registre simultaneamente o tempo real gasto e respeite o prazo do usuário. Os parâmetros do exemplo são um ponto de partida, não garantem otimalidade para cada problema.

Se os coeficientes de penalidade fizerem a magnitude da matriz Ising ser muito maior do que a temperatura do exemplo, a temperatura inicial de 100 pode ser insuficiente para exploração. Quando a tarefa não fixar os parâmetros, pode-se primeiro definir initial_temperature=max(100, 2*np.max(np.abs(h))); para problemas locais com restrições de dezenas de variáveis, pode-se usar iterations_per_t=200, size_limit=128 como ponto de partida, ejulgue com base na qualidade real dos candidatos e no prazo. Não reutilize diretamente a temperatura e o tamanho do pool de soluções do pequeno exemplo, alegando garantir otimalidade.

Para problemas com mais de cem variáveis, onde a tarefa não fixou parâmetros de amostragem, não se pode encerrar executando apenas a configuração de baixa amostragem do pequeno exemplo. Por exemplo, com qualidade como objetivo e um orçamento de execução de cerca de 40 segundos, para 128 a 512 variáveis com acoplamento esparso (proporção não nula abaixo de 10%), o lote padrão é iterations_per_t=(200,800,2400), size_limit=128. Mantenha outros parâmetros consistentes, use sempre a semente especificada, e compile a matriz original apenas uma vez. Para mais variáveis, matriz densa ou orçamento mais curto, comece com lotes pequenos como (200,400,800) e teste. Após cada lote, estime o custo com base na proporção entre o tempo real gasto e o número de iterações do próximo lote; reserve pelo menos 20% de margem e 2 segundos para decodificação e saída. Se o próximo lote for estimado para caber no tempo restante, continue com o lote padrão; a decisão de continuar ainda deve ser baseada no julgamento de qualidade do candidato e prazo abaixo; se houver previsão de exceder o tempo, retorne imediatamente o melhor candidato factível encontrado até agora, não exceda o prazo para executar um número fixo de lotes. Todo o programa deve ter apenas um tempo limite unificado. Dentro do prazo de execução do usuário, recalcule o objetivo original do negócio para todos os candidatos reais retornados, retendo o candidato factível de menor custo; isso é uma estratégia de solução com orçamento dentro do programa. Não considere o primeiro candidato factível como o melhor resultado. Preferências suaves não são restrições rígidas: na ausência de restrições rígidas, não introduza artificialmente grandes coeficientes de penalidade, nem adicione restrições de balanceamento não exigidas pelo problema.

Ajuste os parâmetros padrão de acordo com a escala e complexidade. Os valores acima são pontos de partida empíricos, não uma receita fixa para todos os problemas. Primeiro veja o número de variáveis, o número de acoplamentos não nulos, a faixa de coeficientes e a força das restrições rígidas; depois, combine com o prazo de execução para organizar o tamanho de cada lote. Matrizes densas ou muitas variáveis auxiliares aumentam o custo de cada solução; comece com lotes pequenos, reserve tempo para compilação, decodificação e saída. Aumentar iterações, desacelerar o resfriamento ou expandir o pool de soluções não garante melhores resultados de negócio; acumule o melhor candidato factível do SDK até agora, compare a proporção factível dos candidatos, o custo do objetivo original e o tempo real gasto para decidir se continua; não substitua candidatos antigos melhores. Priorize corrigir modelagem errada ou coeficientes de penalidade muito grandes, depois ajuste os parâmetros; registre os parâmetros usados e a condição de parada; não é permitido alegar garantia de otimalidade.

Primeiro, obedeça aos parâmetros experimentais especificados pela tarefa. Se o problema fixar a semente aleatória, use explicitamente o mesmo rand_seed especificado toda vez que criar um solver; não incremente, crie listas de sementes alternativas ou use o tempo para gerar sementes; a sugestão de múltiplas sementes acima é apenas para tarefas que permitem. Com semente fixa, ajuste a temperatura, número de iterações, etc., somente se a tarefa permitir; registre a configuração real.

solve retorna um pool de spins não ordenados por energia, com a última coluna sendo o spin de referência; itere sobre cada linha, primeiro normalize multiplicando pelo spin de referência, depois decodifique usando o dicionário de variáveis do modelo Ising. Use get_val para acessar variáveis; não adivinhe chaves de string internas. Apenas decisões decodificadas de candidatos reais e verificadas pelo problema original podem ser emitidas; não use força bruta, respostas codificadas ou solvers de terceiros para substituir o SDK.

Termos de penalidade adicionados por você ao objetivo não são equivalentes a restrições registradas: sem add_constraint, verify_constraint retornando 0 não prova que o problema original é factível. Independentemente de estar registrado ou não, recalcule todas as restrições de negócio a partir da decisão. Se chamar verify_constraint, primeiro desempacote unsatisfied, details = model.verify_constraint(sol). O custo de negócio e a energia QUBO/Ising devem ser impressos separadamente; não use penalidades, deslocamentos constantes ou sinais negativos de maximização como indicadores de negócio. Ao transferir coeficientes, salve a ordem das variáveis, constantes, termos lineares, termos quadráticos e o mapeamento de variáveis auxiliares; P é realmente multiplicado nos coeficientes, e as contribuições de cada termo são somadas. A ordem da matriz do SDK não é necessariamente igual à ordem de criação do array; o offset do conversor não inclui as constantes de negócio removidas durante a compilação da expressão; ambos devem ser salvos separadamente. O custo para o mesmo estado é w*(1-x[i]-x[j]+2*x[i]*x[j]), o custo para estados diferentes é w*(x[i]+x[j]-2*x[i]*x[j]); verifique a direção com 00, 01, 10, 11 para evitar confundir interferência de mesmo canal com objetivo Max-Cut.

A métrica de relatório para regras suaves ponderadas segue o problema: se for solicitado "minimizar o custo de violação", reporte sum(weight for rule in soft if not satisfied(rule)), e selecione o candidato que minimiza esse valor entre as soluções legais. "Soma de pesos satisfeitos" e "custo de violação" somam o peso total suave; as duas direções de otimização são opostas; não misture os nomes dos campos objective. Antes de gerar a saída, recalcule o objetivo original com base nos bits finais; mesmo que a decisão seja a mesma, relatar o valor da métrica oposta é um erro de entrega.

Versão e Material de Referência: Leia Apenas as Partes Relevantes

API	Enterprise 1.3.1	Enterprise 1.4.0
QuboModel	kaiwu.qubo	kaiwu.core
Dois conversores QUBO/Ising	kaiwu.conversion	kaiwu.core
ndarray/Binary/Integer/quicksum/get_val/get_sol_dict/PenaltyMethodConstraint	kaiwu.core	kaiwu.core
Acesso a valores de array	get_val elemento a elemento ou get_array_val	get_val suporta arrays; não há get_array_val
PrecisionReducer	kaiwu.cim	kaiwu.preprocess
Solver de método de penalidade	kaiwu.solver.PenaltyMethodSolver	kaiwu.hybrid.PenaltyMethodOptimizer

Quando a versão for conhecida, importe o módulo correspondente diretamente. Se houver exigência explícita de versão cruzada ou não for possível confirmar, faça apenas ramificações de compatibilidade para as importações realmente migradas. quicksum passa uma lista entre versões; ndarray((n,m), 'x', Binary) usa argumentos posicionais. O Community não pode assumir a presença de um solver clássico local.

• Para 1.3.x ou assinaturas mais completas: Enterprise API, Visão Geral da API.
• Exemplo histórico TSP 1.3.x: Exemplos de SDK; ao migrar para 1.4.x, substitua as importações conforme a tabela acima.
• Tratamento de precisão: PrecisionReducer é um decorador de otimizador; os valores padrão mudam entre versões; escreva explicitamente only_feasible_solution; perform_precision_adaption_split retorna (split_matrix, last_var_idx), restaure e verifique a energia da matriz original conforme o mapeamento.
• Integração com hardware real: Fluxo Complementar, leia apenas quando a tarefa exigir hardware real.
• Outras interfaces: Índice de Módulos, Community.
• Quando houver simultaneamente quantidades contínuas e decisões discretas: primeiro escreva a restrição de acoplamento completa; o Kaiwu encontra candidatos discretos; depois de fixar as quantidades discretas, decida com um subproblema contínuo/de fluxo. Não expanda grandes quantidades contínuas em binários; não remova restrições de acoplamento como "fluxo zero se não ativado".

Entrega e Validação

Ao gerar do zero, forneça um script completo; ao modificar código existente, forneça as alterações necessárias. Siga os dados do problema, o protocolo de saída e o prazo; priorize garantir a integridade do código. Quando as condições de execução permitirem, verifique primeiro a importação, depois compile, resolva, decodifique e verifique o negócio original; quando a tarefa proibir a execução, não alegue que foi executado.

O autoexame matemático foca em dois pontos: cada estado de negócio legal pode escolher variáveis auxiliares para tornar o termo de penalidade forte zero? Nesse caso, a energia é igual ao objetivo original mais a constante? Na verificação de desenvolvimento independente, pode-se usar tabelas verdade ou pequenos exemplos exaustivos para encontrar erros de codificação, mas nunca misture esses resultados de enumeração com os resultados retornados pelo SDK. Apenas ao obter um limite de referência ou uma prova independente, declare otimalidade; caso contrário, relate a solução factível encontrada, o valor real do objetivo e a limitação de que a otimalidade não foi provada.

Complemento: Especificação de Entrega de Código

As seguintes regras restringem código SDK novo e modificado; mantenha os requisitos de modelagem e versão acima.

• Mantenha a responsabilidade única. Organize a modelagem, solução SDK, decodificação de candidatos e verificação do negócio original em etapas claras; para pequena escala, um script e algumas funções são suficientes. Não introduza estruturas genéricas, registro de plugins, herança em vários níveis ou muitos wrappers para chamar o SDK uma vez. Remova código morto, ramificações duplicadas e dependências não utilizadas geradas por esta modificação.
• Use interfaces confirmadas. Quando a versão do SDK for conhecida, importe a API correspondente diretamente; não varra todo o pacote, tentando adivinhar nomes de classe e parâmetros. Se for necessário ser compatível com várias versões existentes, escreva ramificações estreitas apenas em torno das interfaces realmente migradas; não disfarce erros de negócio como problemas de compatibilidade de versão.
• Exceções devem ter um resultado de tratamento claro. Capture apenas exceções específicas que podem ser tratadas em limites reais, como entrada, autorização, chamadas externas; se não puder ser recuperado, mantenha a causa e falhe. Proibido except Exception: pass, captura repetida em vários níveis, repetições infinitas, e retorno de solução factível falsa ou valor padrão "sucesso" após erro. Cálculos internos fixos não devem adicionar try/except sem sentido.
• Valide nos limites reais. Verifique a dimensionalidade, faixa de valores e consistência das restrições para dados externos; não verifique repetidamente dados já validados internamente; não adicione estruturas de segurança não relacionadas à tarefa a um pequeno script local. Chaves devem ser lidas de variáveis de ambiente ou configuração existentes; não codifique, nem registre em log; não use eval, exec ou concatenação de comandos shell para analisar dados. Instalação, rede e submissão em nuvem devem respeitar o escopo de autorização da tarefa atual.
• Torne o custo de solução controlável. Defina o resfriamento da temperatura, iterações por temperatura e tamanho do pool de soluções de acordo com a escala de variáveis e o prazo; evite empilhar parâmetros enormes desde o início. A verificação externa do tempo de corte não pode interromper uma chamada solve já bloqueada; portanto, cada lote também deve ser pequeno o suficiente; use um relógio monotônico para gerenciar lotes e registre o tempo real gasto. Pare após atingir o limite de chamadas, tempo ou custo; não atrase repetindo reconexões.
• Reduza cálculos ineficientes. Reutilize matrizes, dados e mapeamentos de variáveis imutáveis; decodifique e filtre candidatos lote a lote; não acumule soluções duplicadas indefinidamente; não use arrays intermediários enormes em vez de cálculos claros. Não remova restrições reais, altere o objetivo original ou substitua resultados de solução por respostas não SDK para ganhar velocidade.
• Torne os índices e unidades claros. Converta números de entrada e subscritos de array na entrada de forma unificada; localize literais positivos/negativos com idx = abs(literal) - 1 e depois decida se inverte. Diferencie objetivo de negócio, termos de penalidade e deslocamentos de energia; use nomes de variáveis que expliquem o significado; não escreva conversões contraditórias em várias funções.
• Faça apenas validação que demonstre correção. Verifique fronteiras representativas factíveis/infactíveis, o objetivo original do negócio e a fonte real dos candidatos do SDK; não trate testes que apenas correspondem ao texto de implementação como prova. Entregue código necessário, completo e executável; declare explicitamente o que foi realmente verificado; quando não puder ser executado, declare isso diretamente; não forje registros de execução.