Export Format
==============

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

.. code-block:: python

   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:

.. code-block:: text

   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 :math:`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.

.. code-block:: python

   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).

.. autoclass:: prophys.export.ModelPackage
   :members:
.. autoclass:: prophys.export.AttributeExport
   :members:
.. autofunction:: prophys.export.export_model