IsingModelIR¶
from cascaqit import IsingModelIR
IsingModelIR ¶
IsingModelIR(
problem_id: str,
spins: tuple[str, ...],
fields: tuple[tuple[str, float], ...] = (),
couplings: tuple[tuple[str, str, float], ...] = (),
offset: float = 0.0,
schema_version: str = SCHEMA_VERSION,
metadata: dict[str, Any] = dict(),
)
Store a classical Ising objective: E(s) = offset + sum(h_i*s_i) + sum(J_ij*s_i*s_j), where s is −1 or +1. spins fixes spin and result-bit order, fields holds single-spin terms and couplings holds interactions between distinct spins. Coefficients can have either sign; offset retains constant energy.
This API decodes 0→−1 and 1→+1, or s=2*x-1. Computational-basis Pauli Z instead has 0→+1 and 1→−1. Do not copy a classical field coefficient directly to a same-sign Pauli Z term. Use the SDK’s model-to-Hamiltonian conversion and verify small instances by enumeration.
Usually obtain this from from_terms() or QUBOProblemIR.to_ising_model(). Direct construction and deserialization do not automatically validate structure. Supply finite real coefficients and call validate(). metadata can retain source problem information without generating atom coordinates or control waveforms.
from cascaqit import IsingModelIR
from cascaqit.problems import evaluate_ising_bitstring
model = IsingModelIR.from_terms(problem_id="field", fields={"a": 2.0}, offset=0.5)
assert not model.validate()
assert evaluate_ising_bitstring(model, "0") == -1.5
assert evaluate_ising_bitstring(model, "1") == 2.5
assert model.to_ahs_candidate_metadata()["schedule_status"] == "not_generated"
assert IsingModelIR.from_json(model.to_json()) == model
from_terms ¶
from_terms(
*,
problem_id: str,
fields: dict[str, float] | None = None,
couplings: dict[tuple[str, str], float] | None = None,
offset: float = 0.0,
spins: list[str] | tuple[str, ...] | None = None,
metadata: dict[str, Any] | None = None,
) -> IsingModelIR
Build a deterministically ordered model from field and coupling dictionaries. Union term references with explicit spins, convert to strings and sort. Order coupling endpoints and add reversed entries. Self-couplings are not automatically moved into offset; simplify with s²=1 before checking validate().
Return structural diagnostics for empty/duplicate spins, unknown references and self-couplings. This does not comprehensively validate coefficient/offset finiteness or embeddability on a physical target.
Return a dictionary of spin order, fields, couplings, offset and provenance, explicitly recording that layout/pulses were not generated and no optimizer was requested. Existing source_problem_id/hash metadata is reused, otherwise the current model identity is used. This dictionary is not an executable AHSProgram.
Return ProblemResultDecodingIR with spins order and the 0→−1, 1→+1 convention. source_problem_hash prefers existing provenance metadata, allowing a QUBO conversion to retain its origin. No energy is computed.
Return an Ising objective-summary ProblemCandidateIR with term counts, coefficients, constant and provenance. No optimizer, layout or pulse generation is performed. The candidate is not an optimal solution or execution record.
Restore IsingModelIR from a dictionary. Preserve saved spin and term order without merging reversed couplings. Call validate() explicitly after restoration. Missing required fields or invalid values can raise KeyError, TypeError or ValueError.
Parse a JSON object and call from_dict(), returning IsingModelIR. Invalid JSON raises a parsing error; a non-object root raises TypeError.
Return a JSON-compatible dictionary, serializing nested objects and converting tuples to arrays. This stores the declaration, not an execution result.
Return a JSON string without writing a file. indent=None uses compact formatting; supply an indentation width for readable output.
Return the SHA-256 hex digest of canonical JSON. Fields, identifiers and metadata can affect it. Use it to compare saved content, not to decide physical equivalence.