classiq 0.83.0__py3-none-any.whl → 0.84.0__py3-none-any.whl

classiq/execution/execution_session.py

@@ -1,24 +1,36 @@
+import inspect
 import random
 from types import TracebackType
 from typing import Callable, Optional, Union, cast
 
-import numpy as np
-
 from classiq.interface.chemistry.operator import PauliOperator, pauli_integers_to_str
 from classiq.interface.exceptions import ClassiqError, ClassiqValueError
-from classiq.interface.execution.primitives import EstimateInput, PrimitivesInput
+from classiq.interface.execution.primitives import (
+    EstimateInput,
+    MinimizeClassicalCostInput,
+    MinimizeQuantumCostInput,
+    PrimitivesInput,
+)
+from classiq.interface.executor.estimate_cost import estimate_cost
 from classiq.interface.executor.execution_preferences import ExecutionPreferences
+from classiq.interface.executor.execution_result import TaggedMinimizeResult
 from classiq.interface.executor.result import (
     EstimationResult,
     ExecutionDetails,
     ParsedState,
 )
 from classiq.interface.generator.arith import number_utils
+from classiq.interface.generator.expressions.expression import Expression
 from classiq.interface.generator.functions.qmod_python_interface import QmodPyStruct
 from classiq.interface.generator.quantum_program import (
     QuantumProgram,
 )
-from classiq.interface.model.quantum_type import QuantumBit, QuantumNumeric
+from classiq.interface.helpers.custom_pydantic_types import PydanticPauliList
+from classiq.interface.model.quantum_type import (
+    QuantumBit,
+    QuantumNumeric,
+    RegisterQuantumTypeDict,
+)
 
 from classiq._internals import async_utils
 from classiq._internals.api_wrapper import ApiWrapper
@@ -27,38 +39,24 @@ from classiq.applications.combinatorial_helpers.pauli_helpers.pauli_utils import
     _pauli_dict_to_pauli_terms,
 )
 from classiq.execution.jobs import ExecutionJob
-from classiq.qmod.builtins import PauliTerm
 from classiq.qmod.builtins.classical_execution_primitives import (
     CARRAY_SEPARATOR,
     ExecutionParams,
 )
+from classiq.qmod.builtins.structs import PauliTerm, SparsePauliOp
+from classiq.qmod.qmod_variable import (
+    QmodExpressionCreator,
+    create_qvar_from_quantum_type,
+)
 
-Hamiltonian = Union[list[QmodPyStruct], list[PauliTerm]]
-ParsedExecutionParams = dict[str, Union[float, int]]
+Hamiltonian = SparsePauliOp
 ExecutionParameters = Optional[Union[ExecutionParams, list[ExecutionParams]]]
+ParsedExecutionParams = dict[str, Union[float, int]]
 ParsedExecutionParameters = Optional[
     Union[ParsedExecutionParams, list[ParsedExecutionParams]]
 ]
 
 
-def hamiltonian_to_pauli_terms(hamiltonian: Hamiltonian) -> list[PauliTerm]:
-    if isinstance(hamiltonian[0], PauliTerm):
-        return cast(list[PauliTerm], hamiltonian)
-    else:
-        return _pauli_dict_to_pauli_terms(cast(list[QmodPyStruct], hamiltonian))
-
-
-def _hamiltonian_to_pauli_operator(hamiltonian: Hamiltonian) -> PauliOperator:
-    pauli_list = [
-        (
-            pauli_integers_to_str(elem.pauli),  # type: ignore[arg-type]
-            elem.coefficient,
-        )
-        for elem in hamiltonian_to_pauli_terms(hamiltonian)
-    ]
-    return PauliOperator(pauli_list=pauli_list)
-
-
 def parse_params(params: ExecutionParams) -> ParsedExecutionParams:
     result = {}
     for key, values in params.items():
@@ -251,7 +249,7 @@ class ExecutionSession:
         """
         execution_primitives_input = PrimitivesInput(
             estimate=EstimateInput(
-                hamiltonian=_hamiltonian_to_pauli_operator(hamiltonian),
+                hamiltonian=self._hamiltonian_to_pauli_operator(hamiltonian),
                 parameters=(
                     [parse_params(parameters)] if parameters is not None else [{}]
                 ),
@@ -293,12 +291,109 @@ class ExecutionSession:
         """
         execution_primitives_input = PrimitivesInput(
             estimate=EstimateInput(
-                hamiltonian=_hamiltonian_to_pauli_operator(hamiltonian),
+                hamiltonian=self._hamiltonian_to_pauli_operator(hamiltonian),
                 parameters=[parse_params(params) for params in parameters],
             )
         )
         return self._execute(execution_primitives_input)
 
+    def minimize(
+        self,
+        cost_function: Union[Hamiltonian, QmodExpressionCreator],
+        initial_params: ExecutionParams,
+        max_iteration: int,
+        quantile: float = 1.0,
+    ) -> list[tuple[float, ExecutionParams]]:
+        """
+        Minimizes the given cost function using the quantum program.
+        Args:
+            cost_function: The cost function to minimize. It can be one of the following:
+                - A quantum cost function defined by a Hamiltonian.
+                - A classical cost function represented as a callable that returns a Qmod expression.
+                  The callable should accept `QVar`s as arguments and use names matching the Model outputs.
+            initial_params: The initial parameters for the minimization.
+                Only Models with exactly one execution parameter are supported. This parameter must be of type
+                `CReal` or `CArray`. The dictionary must contain a single key-value pair, where:
+                    - The key is the name of the parameter.
+                    - The value is either a float or a list of floats.
+            max_iteration: The maximum number of iterations for the minimization.
+            quantile: The quantile to use for cost estimation.
+        Returns:
+            A list of tuples, each containing the estimated cost and the corresponding parameters for that iteration.
+            `cost` is a float, and `parameters` is a dictionary matching the execution parameter format.
+        """
+        job = self.submit_minimize(
+            cost_function=cost_function,
+            initial_params=initial_params,
+            max_iteration=max_iteration,
+            quantile=quantile,
+        )
+        result = job.get_minimization_result(_http_client=self._async_client)
+
+        return self._minimize_result_to_result(
+            result=result, initial_params=initial_params
+        )
+
+    def submit_minimize(
+        self,
+        cost_function: Union[Hamiltonian, QmodExpressionCreator],
+        initial_params: ExecutionParams,
+        max_iteration: int,
+        quantile: float = 1.0,
+    ) -> ExecutionJob:
+        """
+        Initiates an execution job with the `minimize` primitive.
+
+        This is a non-blocking version of `minimize`: it gets the same parameters and initiates the same execution job, but instead
+        of waiting for the result, it returns the job object immediately.
+
+        Args:
+            cost_function: The cost function to minimize. It can be one of the following:
+                - A quantum cost function defined by a Hamiltonian.
+                - A classical cost function represented as a callable that returns a Qmod expression.
+                  The callable should accept `QVar`s as arguments and use names matching the Model outputs.
+            initial_params: The initial parameters for the minimization.
+                Only Models with exactly one execution parameter are supported. This parameter must be of type
+                `CReal` or `CArray`. The dictionary must contain a single key-value pair, where:
+                    - The key is the name of the parameter.
+                    - The value is either a float or a list of floats.
+            max_iteration: The maximum number of iterations for the minimization.
+            quantile: The quantile to use for cost estimation.
+
+        Returns:
+            The execution job.
+        """
+        if len(initial_params) != 1:
+            raise ClassiqValueError(
+                "The initial parameters must be a dictionary with a single key-value pair."
+            )
+
+        _cost_function: Union[PauliOperator, Expression]
+        _initial_params = parse_params(initial_params)
+        minimize: Union[MinimizeQuantumCostInput, MinimizeClassicalCostInput]
+        if callable(cost_function):
+            circuit_output_types = self.program.model.circuit_output_types
+            _cost_function = self._create_qmod_expression(
+                circuit_output_types, cost_function
+            )
+            minimize = MinimizeClassicalCostInput(
+                cost_function=_cost_function,
+                initial_params=_initial_params,
+                max_iteration=max_iteration,
+                quantile=quantile,
+            )
+        else:
+            _cost_function = self._hamiltonian_to_pauli_operator(cost_function)
+            minimize = MinimizeQuantumCostInput(
+                cost_function=_cost_function,
+                initial_params=_initial_params,
+                max_iteration=max_iteration,
+                quantile=quantile,
+            )
+
+        execution_primitives_input = PrimitivesInput(minimize=minimize)
+        return self._execute(execution_primitives_input)
+
     def estimate_cost(
         self,
         cost_func: Callable[[ParsedState], float],
@@ -319,23 +414,8 @@ class ExecutionSession:
         See Also:
             sample
         """
-        if quantile < 0 or quantile > 1:
-            raise ClassiqValueError("'quantile' must be between 0 and 1")
         res = self.sample(parameters)
-
-        counts = np.array(res.parsed_counts)
-        costs = np.vectorize(lambda sample: cost_func(sample.state))(counts)
-        shots = np.vectorize(lambda sample: sample.shots)(counts)
-
-        if quantile == 1:
-            return float(np.average(costs, weights=shots))
-        costs = np.repeat(costs, shots)
-        sort_idx = costs.argsort()
-        sort_idx = sort_idx[: int(quantile * len(costs))]
-        costs = costs[sort_idx]
-        if costs.size == 0:
-            return np.nan
-        return float(np.average(costs))
+        return estimate_cost(cost_func, res.parsed_counts, quantile=quantile)
 
     def set_measured_state_filter(
         self,
@@ -387,3 +467,69 @@ class ExecutionSession:
             )
 
         self.program.model.register_filter_bitstrings[output_name] = legal_bitstrings
+
+    @staticmethod
+    def _hamiltonian_to_pauli_operator(hamiltonian: Hamiltonian) -> PauliOperator:
+        pauli_list: PydanticPauliList
+        # FIXME: Remove compatibility (CLS-2912)
+        if isinstance(hamiltonian, list):  # type:ignore[unreachable]
+            pauli_list = [  # type:ignore[unreachable]
+                (
+                    pauli_integers_to_str(elem.pauli),
+                    cast(complex, elem.coefficient),
+                )
+                for elem in ExecutionSession._hamiltonian_to_pauli_terms(hamiltonian)
+            ]
+            return PauliOperator(pauli_list=pauli_list)
+        pauli_list = []
+        for term in cast(list, hamiltonian.terms):
+            paulis = ["I"] * cast(int, hamiltonian.num_qubits)
+            for indexed_pauli in term.paulis:
+                paulis[len(paulis) - indexed_pauli.index - 1] = indexed_pauli.pauli.name
+            pauli_list.append(("".join(paulis), term.coefficient))
+        return PauliOperator(pauli_list=pauli_list)
+
+    @staticmethod
+    def _create_qmod_expression(
+        circuit_output_types: RegisterQuantumTypeDict,
+        qmod_expression_creator: QmodExpressionCreator,
+    ) -> Expression:
+        symbolic_output = {
+            name: create_qvar_from_quantum_type(reg.quantum_types, name)
+            for name, reg in circuit_output_types.items()
+        }
+        for name in inspect.signature(qmod_expression_creator).parameters.keys():
+            if name not in symbolic_output:
+                raise ClassiqValueError(
+                    f"The provided QVar: {name} does not match the model outputs: {tuple(circuit_output_types.keys())}. "
+                )
+
+        qmod_expression = qmod_expression_creator(**symbolic_output)
+        return Expression(expr=str(qmod_expression))
+
+    @staticmethod
+    def _hamiltonian_to_pauli_terms(hamiltonian: list) -> list[PauliTerm]:
+        if isinstance(hamiltonian[0], PauliTerm):
+            return cast(list[PauliTerm], hamiltonian)
+        else:
+            return _pauli_dict_to_pauli_terms(cast(list[QmodPyStruct], hamiltonian))
+
+    @staticmethod
+    def _minimize_result_to_result(
+        result: TaggedMinimizeResult, initial_params: ExecutionParams
+    ) -> list[tuple[float, ExecutionParams]]:
+        param_name = next(iter(initial_params.keys()))
+        param_value = initial_params[param_name]
+        return [
+            (
+                res.expectation_value,
+                {
+                    param_name: (
+                        res.parameters[0]
+                        if isinstance(param_value, (float, int))
+                        else res.parameters
+                    )
+                },
+            )
+            for res in result.value
+        ]

classiq/execution/jobs.py

@@ -10,7 +10,10 @@ from classiq.interface.exceptions import (
     ClassiqError,
 )
 from classiq.interface.executor.execution_request import ExecutionJobDetails, JobCost
-from classiq.interface.executor.execution_result import ResultsCollection
+from classiq.interface.executor.execution_result import (
+    ResultsCollection,
+    TaggedMinimizeResult,
+)
 from classiq.interface.executor.result import (
     EstimationResult,
     EstimationResults,
@@ -244,6 +247,28 @@ class ExecutionJob:
 
         raise ClassiqExecutionResultError("batch_estimate")
 
+    def get_minimization_result(
+        self, _http_client: Optional[httpx.AsyncClient] = None
+    ) -> TaggedMinimizeResult:
+        """
+        Returns the job's result as a single minimization result after validation. If the result is not yet available, waits for it.
+
+        Returns:
+            The minimization result of the execution job.
+
+        Raises:
+            ClassiqExecutionResultError: In case the result does not contain a single minimization result.
+            ClassiqAPIError: In case the job has failed.
+        """
+        results = self.result(_http_client=_http_client)
+        if len(results) != 1:
+            raise ClassiqExecutionResultError("minimization")
+
+        result = results[0]
+        if isinstance(result, TaggedMinimizeResult):
+            return result
+        raise ClassiqExecutionResultError("minimization")
+
     async def poll_async(
         self,
         timeout_sec: Optional[float] = None,

classiq/execution/qnn.py

@@ -15,7 +15,7 @@ from classiq.interface.executor.quantum_code import Arguments, MultipleArguments
 
 from classiq import QuantumProgram
 from classiq.applications.combinatorial_helpers.pauli_helpers.pauli_utils import (
-    pauli_operator_to_hamiltonian,
+    pauli_operator_to_sparse_hamiltonian,
 )
 from classiq.execution.execution_session import ExecutionSession
 
@@ -27,7 +27,7 @@ def _execute_qnn_estimate(
     arguments: list[Arguments],
     observable: PauliOperator,
 ) -> ResultsCollection:
-    hamiltonian = pauli_operator_to_hamiltonian(observable.pauli_list)
+    hamiltonian = pauli_operator_to_sparse_hamiltonian(observable.pauli_list)
     return [
         TaggedEstimationResult(
             name=DEFAULT_RESULT_NAME,

classiq/execution/user_budgets.py

@@ -36,3 +36,42 @@ async def get_budget_async(
 
 
 get_budget = syncify_function(get_budget_async)
+
+
+async def set_budget_limit_async(
+    provider_vendor: ProviderVendor,
+    limit: float,
+) -> UserBudgets:
+    provider = PROVIDER_MAPPER.get(provider_vendor, None)
+    if not provider:
+        raise ValueError(f"Unsupported provider: {provider_vendor}")
+
+    budget = get_budget(provider_vendor)
+    if budget is None:
+        raise ValueError(f"No budget found for provider: {provider_vendor}")
+
+    if limit <= 0:
+        raise ValueError("Budget limit must be greater than zero.")
+
+    if limit > budget.budgets[0].available_budget:
+        print(  # noqa: T201
+            f"Budget limit {limit} exceeds available budget {budget.budgets[0].available_budget} for provider {provider_vendor}.\n"
+            "Setting budget limit to the maximum available budget."
+        )
+    budgets_list = await ApiWrapper().call_set_budget_limit(provider, limit)
+    return UserBudgets(budgets=[budgets_list])
+
+
+set_budget_limit = syncify_function(set_budget_limit_async)
+
+
+async def clear_budget_limit_async(provider_vendor: ProviderVendor) -> UserBudgets:
+    provider = PROVIDER_MAPPER.get(provider_vendor, None)
+    if not provider:
+        raise ValueError(f"Unsupported provider: {provider_vendor}")
+
+    budgets_list = await ApiWrapper().call_clear_budget_limit(provider)
+    return UserBudgets(budgets=[budgets_list])
+
+
+clear_budget_limit = syncify_function(clear_budget_limit_async)

classiq/interface/_version.py

@@ -3,5 +3,5 @@ from packaging.version import Version
 # This file was generated automatically
 # Please don't track in version control (DONTTRACK)
 
-SEMVER_VERSION = '0.83.0'
+SEMVER_VERSION = '0.84.0'
 VERSION = str(Version(SEMVER_VERSION))

classiq/interface/constants.py

@@ -0,0 +1 @@
+DEFAULT_DECIMAL_PRECISION = 4

classiq/interface/execution/primitives.py

@@ -1,9 +1,10 @@
-from typing import Optional
+from typing import Annotated, Literal, Optional, Union
 
 from pydantic import BaseModel, Field
 
 from classiq.interface.chemistry.operator import PauliOperator
 from classiq.interface.executor.quantum_code import Arguments
+from classiq.interface.generator.expressions.expression import Expression
 from classiq.interface.helpers.custom_encoders import CUSTOM_ENCODERS
 
 
@@ -12,7 +13,34 @@ class EstimateInput(BaseModel, json_encoders=CUSTOM_ENCODERS):
     parameters: list[Arguments]
 
 
+class MinimizeCostInput(BaseModel, json_encoders=CUSTOM_ENCODERS):
+    initial_params: Arguments
+    max_iteration: int
+    quantile: float
+
+
+class MinimizeClassicalCostInput(MinimizeCostInput):
+    cost_function: Expression
+    kind: Literal["MinimizeClassicalCostInput"] = Field(
+        default="MinimizeClassicalCostInput"
+    )
+
+
+class MinimizeQuantumCostInput(MinimizeCostInput):
+    cost_function: PauliOperator
+    kind: Literal["MinimizeQuantumCostInput"] = Field(
+        default="MinimizeQuantumCostInput"
+    )
+
+
+ConcreteMinimizeCostInput = Annotated[
+    Union[MinimizeQuantumCostInput, MinimizeClassicalCostInput],
+    Field(discriminator="kind"),
+]
+
+
 class PrimitivesInput(BaseModel, json_encoders=CUSTOM_ENCODERS):
     sample: Optional[list[Arguments]] = Field(default=None)
     estimate: Optional[EstimateInput] = Field(default=None)
+    minimize: Optional[ConcreteMinimizeCostInput] = Field(default=None)
     random_seed: Optional[int] = Field(default=None)

classiq/interface/executor/estimate_cost.py

@@ -0,0 +1,35 @@
+from typing import Callable
+
+import numpy as np
+
+from classiq.interface.exceptions import ClassiqValueError
+from classiq.interface.executor.result import ParsedCounts, ParsedState
+
+
+def estimate_cost(
+    cost_func: Callable[[ParsedState], float],
+    parsed_counts: ParsedCounts,
+    quantile: float = 1.0,
+) -> float:
+    if quantile < 0 or quantile > 1:
+        raise ClassiqValueError("'quantile' must be between 0 and 1")
+    costs = np.fromiter((cost_func(sample.state) for sample in parsed_counts), float)
+    shots = np.fromiter((sample.shots for sample in parsed_counts), int)
+
+    if quantile == 1:
+        return float(np.average(costs, weights=shots))
+    return float(estimate_quantile_cost(costs, shots, quantile=quantile))
+
+
+def estimate_quantile_cost(
+    costs: np.ndarray,
+    shots: np.ndarray,
+    quantile: float,
+) -> np.floating:
+    repeated_costs = np.repeat(costs, shots)
+    sort_idx = repeated_costs.argsort()
+    cutoff_idx = sort_idx[: int(quantile * len(repeated_costs))]
+    sorted_costs = repeated_costs[cutoff_idx]
+    if sorted_costs.size == 0:
+        sorted_costs = repeated_costs[sort_idx[0]]
+    return np.average(sorted_costs)

classiq/interface/executor/execution_result.py

@@ -25,6 +25,7 @@ class SavedResultValueType(StrEnum):
     EstimationResult = "EstimationResult"
     EstimationResults = "EstimationResults"
     IQAEResult = "IQAEResult"
+    MinimizeResult = "MinimizeResult"
     Unstructured = "Unstructured"
 
 
@@ -88,6 +89,17 @@ class TaggedUnstructured(BaseModel):
     value: Any = None
 
 
+class SingleMinimizeResult(BaseModel):
+    expectation_value: float
+    parameters: list[float]
+
+
+class TaggedMinimizeResult(BaseModel):
+    value_type: Literal[SavedResultValueType.MinimizeResult]
+    name: str
+    value: list[SingleMinimizeResult]
+
+
 SavedResult = Annotated[
     Union[
         TaggedInteger,
@@ -100,6 +112,7 @@ SavedResult = Annotated[
         TaggedEstimationResults,
         TaggedIQAEResult,
         TaggedUnstructured,
+        TaggedMinimizeResult,
     ],
     Field(..., discriminator="value_type"),
 ]

classiq/interface/executor/result.py

@@ -10,11 +10,16 @@ from typing import (
     Union,
 )
 
+import pandas as pd
 import pydantic
 from pydantic import BaseModel
 from typing_extensions import Self, TypeAlias
 
-from classiq.interface.exceptions import ClassiqError
+from classiq.interface.exceptions import (
+    ClassiqError,
+    ClassiqInternalError,
+    ClassiqValueError,
+)
 from classiq.interface.executor.quantum_code import OutputQubitsMap, Qubits
 from classiq.interface.generator.arith import number_utils
 from classiq.interface.generator.complex_type import Complex
@@ -22,6 +27,7 @@ from classiq.interface.generator.functions.classical_type import QmodPyObject
 from classiq.interface.helpers.custom_pydantic_types import PydanticNonNegIntTuple
 from classiq.interface.helpers.datastructures import get_sdk_compatible_python_object
 from classiq.interface.helpers.versioned_model import VersionedModel
+from classiq.interface.model.quantum_type import RegisterQuantumTypeDict
 
 _ILLEGAL_QUBIT_ERROR_MSG: str = "Illegal qubit index requested"
 _REPEATED_QUBIT_ERROR_MSG: str = "Requested a qubit more than once"
@@ -36,6 +42,11 @@ ParsedStates: TypeAlias = Mapping[State, ParsedState]
 Counts: TypeAlias = dict[State, MeasuredShots]
 StateVector: TypeAlias = Optional[dict[str, Complex]]
 
+BITSTRING = "bitstring"
+PROBABILITY = "probability"
+AMPLITUDE = "amplitude"
+COUNT = "count"
+
 if TYPE_CHECKING:
     DotAccessParsedState = Mapping[Name, Any]
 else:
@@ -150,6 +161,36 @@ def prepare_parsed_state_vector(
     return sorted(parsed_state_vector, key=lambda k: abs(k.amplitude), reverse=True)
 
 
+def _flatten_columns(df: pd.DataFrame, columns_to_flatten: list[str]) -> pd.DataFrame:
+    if len(df.columns) == 0:
+        return df
+
+    flattened_data = {}
+
+    for col in columns_to_flatten:
+        if col not in df.columns:
+            continue
+
+        flat_df = pd.json_normalize(df[col]).add_prefix(f"{col}.")
+        flat_df.index = df.index
+        flattened_data[col] = flat_df
+
+    new_df_columns = []
+    dfs_to_concat = []
+
+    for col_name in df.columns:
+        if col_name in flattened_data:
+            new_df_columns.extend(flattened_data[col_name].columns)
+            dfs_to_concat.append(flattened_data[col_name])
+        elif col_name not in columns_to_flatten:
+            new_df_columns.append(col_name)
+            dfs_to_concat.append(df[[col_name]])
+
+    final_df = pd.concat(dfs_to_concat, axis=1)
+    valid_final_columns = [c for c in new_df_columns if c in final_df.columns]
+    return final_df[valid_final_columns]
+
+
 class ExecutionDetails(BaseModel, QmodPyObject):
     vendor_format_result: dict[str, Any] = pydantic.Field(
         ..., description="Result in proprietary vendor format"
@@ -192,6 +233,8 @@ class ExecutionDetails(BaseModel, QmodPyObject):
         default=None, description="The total number of shots the circuit was executed"
     )
 
+    output_type_map: RegisterQuantumTypeDict = pydantic.Field(default_factory=dict)
+
     @pydantic.field_validator("counts", mode="after")
     @classmethod
     def _clean_spaces_from_counts_keys(cls, v: Counts) -> Counts:
@@ -302,6 +345,78 @@ class ExecutionDetails(BaseModel, QmodPyObject):
         )[::-1]
         return number_utils.binary_to_float_or_int(bin_rep=register_binary_string)
 
+    def _counts_df(self) -> pd.DataFrame:
+        data: dict[str, Any] = defaultdict(list)
+
+        for bitstring, count in self.counts.items():
+            data[BITSTRING].append(bitstring)
+            data[COUNT].append(count)
+            if self.probabilities:
+                data[PROBABILITY].append(self.probabilities[bitstring])
+            elif self.num_shots:
+                data[PROBABILITY].append(count / self.num_shots)
+
+            for name, value in self.parsed_states[bitstring].items():
+                data[name].append(value)
+
+        final_columns = [COUNT, PROBABILITY, BITSTRING]
+        columns = [
+            col for col in data.keys() if col not in final_columns
+        ] + final_columns
+
+        return pd.DataFrame(data, columns=columns)
+
+    def _state_vector_df(self) -> pd.DataFrame:
+        data: dict[str, Any] = defaultdict(list)
+
+        if not self.state_vector:
+            raise ClassiqInternalError("No state vector")
+        if not self.parsed_state_vector_states:
+            raise ClassiqInternalError("No parsed state vector states")
+
+        for bitstring, amplitude in self.state_vector.items():
+            data[BITSTRING].append(bitstring)
+            data[AMPLITUDE].append(amplitude)
+            data[PROBABILITY].append(abs(amplitude) ** 2)
+            for name, value in self.parsed_state_vector_states[bitstring].items():
+                data[name].append(value)
+
+        final_columns = [AMPLITUDE, PROBABILITY, BITSTRING]
+        columns = [
+            col for col in data.keys() if col not in final_columns
+        ] + final_columns
+
+        return pd.DataFrame(data, columns=columns)
+
+    @functools.cached_property
+    def dataframe(self) -> pd.DataFrame:
+        reserved_words = frozenset([BITSTRING, PROBABILITY, COUNT, AMPLITUDE])
+        _invalid_output_names = reserved_words.intersection(
+            self.output_qubits_map.keys()
+        )
+        if _invalid_output_names:
+            raise ClassiqValueError(f"Invalid output names: {_invalid_output_names}")
+
+        if self.state_vector:
+            df = self._state_vector_df()
+        else:
+            df = self._counts_df()
+
+        df.sort_values(
+            by=[AMPLITUDE if self.state_vector else COUNT, BITSTRING],
+            inplace=True,
+            ascending=[False, True],
+            ignore_index=True,
+        )
+
+        outputs_to_flatten = [
+            output
+            for output, type in self.output_type_map.items()
+            if type.quantum_types.kind == "struct_instance"
+        ]
+        df = _flatten_columns(df, outputs_to_flatten)
+        return df
+
 
 class MultipleExecutionDetails(VersionedModel):
     details: list[ExecutionDetails]