# This code is part of Qiskit.
#
# (C) Copyright IBM 2021-2022.
#
# This code is licensed under the Apache License, Version 2.0. You may
# obtain a copy of this license in the LICENSE.txt file in the root directory
# of this source tree or at http://www.apache.org/licenses/LICENSE-2.0.
#
# Any modifications or derivative works of this code must retain this
# copyright notice, and modified files need to carry a notice indicating
# that they have been altered from the originals.
"""Analysis result class."""
import copy
import logging
import math
import uuid
import traceback
from typing import Optional, List, Union, Dict, Any
import uncertainties
from qiskit_ibm_experiment import IBMExperimentService, AnalysisResultData
from qiskit_ibm_experiment import ResultQuality
from qiskit.exceptions import QiskitError
from qiskit_experiments.framework.json import (
ExperimentEncoder,
ExperimentDecoder,
_serialize_safe_float,
)
from qiskit_experiments.database_service.device_component import DeviceComponent, to_component
from qiskit_experiments.database_service.exceptions import ExperimentDataError
from qiskit_experiments.framework.package_deps import qiskit_version
LOG = logging.getLogger(__name__)
[docs]
class AnalysisResult:
"""Class representing an analysis result for an experiment.
Analysis results can also be stored using the experiments service.
The field ``db_data`` is a dataclass (`ExperimentDataclass`) containing
all the data that can be stored with the service and loaded from it, and
as such is subject to strict conventions.
Other data fields can be added and used freely, but they won't be saved
to the database.
Note that the ``result_data`` field of the dataclass is by itself a dictionary
capable of holding arbitrary values (in a dictionary indexed by a string).
The data fields in the ``db_data`` dataclass are:
* ``experiment_id``: ``str``
* ``result_id``: ``str``
* ``result_type``: ``str``
* ``device_components``: ``List[str]``
* ``quality``: ``str``
* ``verified``: ``bool``
* ``tags``: ``List[str]``
* ``backend_name``: ``str``
* ``chisq``: ``float``
* ``result_data``: ``Dict[str]``
Analysis data that does not fit into the other fields should be added to
the ``result_data`` dict, e.g. curve parameters in experiments doing a curve fit.
"""
version = 1
_data_version = 1
_json_encoder = ExperimentEncoder
_json_decoder = ExperimentDecoder
_extra_data = {}
RESULT_QUALITY_TO_TEXT = {
ResultQuality.GOOD: "good",
ResultQuality.BAD: "bad",
ResultQuality.UNKNOWN: "unknown",
}
def __init__(
self,
name: str = None,
value: Any = None,
device_components: List[Union[DeviceComponent, str]] = None,
experiment_id: str = None,
result_id: Optional[str] = None,
chisq: Optional[float] = None,
quality: Optional[str] = RESULT_QUALITY_TO_TEXT[ResultQuality.UNKNOWN],
extra: Optional[Dict[str, Any]] = None,
verified: bool = False,
tags: Optional[List[str]] = None,
service: Optional[IBMExperimentService] = None,
source: Optional[Dict[str, str]] = None,
) -> "AnalysisResult":
"""AnalysisResult constructor.
Args:
name: analysis result name.
value: main analysis result value.
device_components: Target device components this analysis is for.
experiment_id: ID of the experiment.
result_id: Result ID. If ``None``, one is generated.
chisq: Reduced chi squared of the fit.
quality: Quality of the analysis. Refer to the experiment service
provider for valid values.
extra: Dictionary of extra analysis result data
verified: Whether the result quality has been verified.
tags: Tags for this analysis result.
service: Experiment service to be used to store result in database.
source: Class and Qiskit version information when loading from an
experiment service.
Returns:
The AnalysisResult object.
"""
# Data to be stored in DB.
self._db_data = AnalysisResultData(
experiment_id=experiment_id,
result_id=result_id or str(uuid.uuid4()),
result_type=name,
chisq=chisq,
quality=quality,
verified=verified,
tags=tags or [],
)
self._db_data.result_data = self.format_result_data(value, extra, chisq, source)
if device_components is not None:
for comp in device_components:
if isinstance(comp, str):
comp = to_component(comp)
self._db_data.device_components.append(comp)
self._service = service
self._created_in_db = False
self._auto_save = False
if self._service:
try:
self.auto_save = self._service.preferences["auto_save"]
except AttributeError:
pass
[docs]
def set_data(self, data: AnalysisResultData):
"""Sets the analysis data stored in the class"""
self._db_data = data
new_device_components = [to_component(comp) for comp in self._db_data.device_components]
self._db_data.device_components = new_device_components
self._db_data.quality = self.RESULT_QUALITY_TO_TEXT.get(self._db_data.quality, "unknown")
[docs]
@classmethod
def default_source(cls) -> Dict[str, str]:
"""The default source dictionary to generate"""
return {
"class": f"{cls.__module__}.{cls.__name__}",
"data_version": cls._data_version,
"qiskit_version": qiskit_version(),
}
[docs]
@classmethod
def load(cls, result_id: str, service: IBMExperimentService) -> "AnalysisResult":
"""Load a saved analysis result from a database service.
Args:
result_id: Analysis result ID.
service: the database service.
Returns:
The loaded analysis result.
"""
# Load data from the service
data = service.analysis_result(result_id, json_decoder=cls._json_decoder)
result = cls()
result.set_data(data)
result._created_in_db = True
result.service = service
return result
[docs]
def save(self, suppress_errors: bool = True) -> None:
"""Save this analysis result in the database.
Args:
suppress_errors: should the method catch exceptions (true) or
pass them on, potentially aborting the experiment (false).
Raises:
ExperimentDataError: If the analysis result contains invalid data.
QiskitError: If the save to the database failed.
"""
if not self.service:
LOG.warning(
"Analysis result cannot be saved because no experiment service is available."
)
return
try:
self.service.create_or_update_analysis_result(
self._db_data, json_encoder=self._json_encoder, create=not self._created_in_db
)
self._created_in_db = True
except Exception as ex: # pylint: disable=broad-except
# Don't automatically fail the experiment just because its data cannot be saved.
LOG.error("Unable to save the experiment data: %s", traceback.format_exc())
if not suppress_errors:
raise QiskitError(f"Analysis result save failed\nError Message:\n{str(ex)}") from ex
[docs]
def copy(self) -> "AnalysisResult":
"""Return a copy of the result with a new result ID"""
new_instance = AnalysisResult(
name=self.name,
value=self.value,
device_components=self.device_components,
experiment_id=self.experiment_id,
)
new_instance._db_data = self._db_data.copy()
new_instance._db_data.result_id = str(uuid.uuid4())
return new_instance
@property
def name(self) -> str:
"""Return analysis result name.
Returns:
Analysis result name.
"""
return self._db_data.result_type
@property
def value(self) -> Any:
"""Return analysis result value.
Returns:
Analysis result value.
"""
return self._db_data.result_data["_value"]
@value.setter
def value(self, new_value: Any) -> None:
"""Set the analysis result value."""
self._db_data.result_data["_value"] = new_value
if self.auto_save:
self.save()
@property
def extra(self) -> Dict[str, Any]:
"""Return extra analysis result data.
Returns:
Additional analysis result data.
"""
return self._db_data.result_data["_extra"]
@extra.setter
def extra(self, new_value: Dict[str, Any]) -> None:
"""Set the analysis result value."""
if not isinstance(new_value, dict):
raise ExperimentDataError(f"The `extra` field of {type(self).__name__} must be a dict.")
self._db_data.result_data["_extra"] = new_value
if self.auto_save:
self.save()
@property
def device_components(self) -> List[DeviceComponent]:
"""Return target device components for this analysis result.
Returns:
Target device components.
"""
return self._db_data.device_components
@device_components.setter
def device_components(self, components: List[Union[DeviceComponent, str]]):
"""Set the device components"""
self._db_data.device_components = []
for comp in components:
if isinstance(comp, str):
comp = to_component(comp)
self._db_data.device_components.append(comp)
@property
def result_id(self) -> str:
"""Return analysis result ID.
Returns:
ID for this analysis result.
"""
return self._db_data.result_id
@property
def experiment_id(self) -> str:
"""Return the ID of the experiment associated with this analysis result.
Returns:
ID of experiment associated with this analysis result.
"""
return self._db_data.experiment_id
@experiment_id.setter
def experiment_id(self, new_id: str) -> None:
"""Sets the experiment id"""
self._db_data.experiment_id = new_id
@property
def chisq(self) -> Optional[float]:
"""Return the reduced χ² of this analysis."""
return self._db_data.chisq
@chisq.setter
def chisq(self, new_chisq: float) -> None:
"""Set the reduced χ² of this analysis."""
self._db_data.chisq = new_chisq
if self.auto_save:
self.save()
@property
def quality(self) -> str:
"""Return the quality of this analysis.
Returns:
Quality of this analysis.
"""
return self._db_data.quality
@quality.setter
def quality(self, new_quality: str) -> None:
"""Set the quality of this analysis.
Args:
new_quality: New analysis quality.
"""
self._db_data.quality = new_quality
if self.auto_save:
self.save()
@property
def verified(self) -> bool:
"""Return the verified flag.
The ``verified`` flag is intended to indicate whether the quality
value has been verified by a human.
Returns:
Whether the quality has been verified.
"""
return self._db_data.verified
@verified.setter
def verified(self, verified: bool) -> None:
"""Set the verified flag.
Args:
verified: Whether the quality is verified.
"""
self._db_data.verified = verified
if self.auto_save:
self.save()
@property
def tags(self):
"""Return tags associated with this result."""
return self._db_data.tags
@tags.setter
def tags(self, new_tags: List[str]) -> None:
"""Set tags for this result."""
if not isinstance(new_tags, list):
raise ExperimentDataError(f"The `tags` field of {type(self).__name__} must be a list.")
self._db_data.tags = new_tags
if self.auto_save:
self.save()
@property
def service(self) -> Optional[IBMExperimentService]:
"""Return the database service.
Returns:
Service that can be used to store this analysis result in a database.
``None`` if not available.
"""
return self._service
@service.setter
def service(self, service: IBMExperimentService) -> None:
"""Set the service to be used for storing result data in a database.
Args:
service: Service to be used.
Raises:
ExperimentDataError: If an experiment service is already being used.
"""
if self._service:
raise ExperimentDataError("An experiment service is already being used.")
self._service = service
@property
def source(self) -> Dict:
"""Return the class name and version."""
if "_source" in self._db_data.result_data:
return self._db_data.result_data["_source"]
return None
@property
def auto_save(self) -> bool:
"""Return current auto-save option.
Returns:
Whether changes will be automatically saved.
"""
return self._auto_save
@auto_save.setter
def auto_save(self, save_val: bool) -> None:
"""Set auto save preference.
Args:
save_val: Whether to do auto-save.
"""
if save_val and not self._auto_save:
self.save()
self._auto_save = save_val
@staticmethod
def _display_format(value):
"""Format values for supported types for display in database service"""
if value is None or isinstance(value, (int, bool, str)):
# Pass supported value types directly
return value
if isinstance(value, float):
# Safe handling on NaN float values that serialize to invalid JSON
if math.isfinite(value):
return value
else:
return _serialize_safe_float(value)["__value__"]
if isinstance(value, complex):
# Convert complex floats to strings for display
return f"{value}"
# For all other value types that cannot be natively displayed
# we return the class name
return f"({type(value).__name__})"
def __str__(self):
ret = f"{type(self).__name__}"
ret += f"\n- name: {self.name}"
ret += f"\n- value: {str(self.value)}"
if self.chisq is not None:
ret += f"\n- χ²: {str(self.chisq)}"
if self.quality is not None:
ret += f"\n- quality: {self.quality}"
if self.extra:
ret += f"\n- extra: <{len(self.extra)} items>"
ret += f"\n- device_components: {[str(i) for i in self.device_components]}"
ret += f"\n- verified: {self.verified}"
return ret
def __repr__(self):
out = f"{type(self).__name__}("
out += f"name={self.name}"
out += f", value={repr(self.value)}"
out += f", device_components={repr(self.device_components)}"
out += f", experiment_id={self.experiment_id}"
out += f", result_id={self.result_id}"
out += f", chisq={self.chisq}"
out += f", quality={self.quality}"
out += f", verified={self.verified}"
out += f", extra={repr(self.extra)}"
out += f", tags={self.tags}"
out += f", experiment id={repr(self.experiment_id)}"
for key, val in self._extra_data.items():
out += f", {key}={repr(val)}"
out += ")"
return out
def __json_encode__(self):
return {
"name": self._db_data.result_type,
"value": self._db_data.result_data.get("_value", None),
"device_components": self._db_data.device_components,
"experiment_id": self._db_data.experiment_id,
"result_id": self._db_data.result_id,
"chisq": self._db_data.chisq,
"quality": self._db_data.quality,
"extra": self.extra,
"verified": self._db_data.verified,
"tags": self._db_data.tags,
"source": self.source,
}