Export Format

prophys defines a single, neutral, versioned interchange format for a compiled model — the ModelPackage. It carries no dependency on any downstream consumer; a consumer (Qalibri or any other system) implements its own import against this documented shape.

compiled = model.compile()
pkg = compiled.export()          # ModelPackage
pkg.save("model.json")

loaded = prp.export.ModelPackage.load("model.json")

Structure

ModelPackage is a plain dataclass, serializable to JSON:

ModelPackage
  format_version: str            # "1.0"
  model_name: str
  params: dict[str, Any]         # calibrated parameters, constrained space
  correlation: dict | None       # reserved for joint/copula metadata
  attributes: list[AttributeExport]

AttributeExport
  name: str
  unit: str
  domain: str                    # free-text description
  representation: "quantized" | "histogram" | "sampler"
  support: (float, float)        # observed [min, max] over the sample
  mean: float
  # representation == "quantized":
  grid: list[float]              # bin-center support points
  probs: list[float]             # normalized probabilities, same length as grid
  # representation == "histogram":
  edges: list[float]             # bin edges, length len(probs) + 1
  probs: list[float]
  # representation == "sampler":
  samples: list[float]           # raw Monte-Carlo draws, JAX-free

Choosing a representation

• "quantized" — a probability mass function on \(2^n\) support points. The natural format for consumers that need a discretized distribution over a fixed grid (e.g. state-preparation for quantum amplitude estimation).

• "histogram" — equal-width bins with edges and probabilities; a gridding-free summary when the consumer just needs a coarse density.

• "sampler" — raw NumPy floats, no JAX dependency at all; the simplest possible handoff for a consumer that wants to resample or refit.

pkg = compiled.export(representation="sampler", n_samples=8192)

Round-tripping

ModelPackage.save/.load round-trip through JSON losslessly for all three representations; the symbolic graph itself is not serialized (the package intentionally only carries the calibrated numeric artifacts a downstream consumer needs, not the engine internals used to produce them).

class prophys.export.ModelPackage(format_version: 'str', model_name: 'str', params: 'dict[str, Any]', attributes: 'list[AttributeExport]', correlation: 'dict[str, Any] | None' = None)

Parameters:

• format_version (str)

• model_name (str)

• params (dict[str, Any])

• attributes (list[AttributeExport])

• correlation (dict[str, Any] | None)

class prophys.export.AttributeExport(name: 'str', unit: 'str', domain: 'str', representation: 'str', support: 'tuple[float, float]', grid: 'list[float] | None' = None, probs: 'list[float] | None' = None, edges: 'list[float] | None' = None, samples: 'list[float] | None' = None, mean: 'float | None' = None)

Parameters:

• name (str)

• unit (str)

• domain (str)

• representation (str)

• support (tuple[float, float])

• grid (list[float] | None)

• probs (list[float] | None)

• edges (list[float] | None)

• samples (list[float] | None)

• mean (float | None)

prophys.export.export_model(compiled, attribute_names=None, representation='quantized', n_qubits=8, n_samples=4096, seed=0)

Build a ModelPackage from a CompiledModel.

representation controls how each attribute’s marginal distribution is serialized:

• "quantized": PMF on 2**n_qubits support points (e.g. for quantum-amplitude-estimation-style consumers).

• "histogram": variable-width-free histogram with 2**n_qubits equal-width bins.

• "sampler": raw Monte-Carlo samples, JAX-free (plain floats), for consumers that just want data to resample from.

Parameters:

• attribute_names (list[str] | None)

• representation (str)

• n_qubits (int)

• n_samples (int)

• seed (int)

Return type:

ModelPackage