qpanda3_runtime.toolbox.checkpoint#

Exceptions#

VersionMismatchError

Exception raised for version mismatch errors.

Classes#

CheckPoint

Manual checkpointing and recovery tool for quantum computation states.

Module Contents#

exception qpanda3_runtime.toolbox.checkpoint.VersionMismatchError#

Bases: Exception

Exception raised for version mismatch errors.

Variables:

message (str) – Explanation of the error

class qpanda3_runtime.toolbox.checkpoint.CheckPoint#

Manual checkpointing and recovery tool for quantum computation states.

A non-semantic key-value container where users are responsible for knowing what they store and how to interpret it. No automatic operations are performed, and no decisions are made on behalf of the user.

Notes

  • Two access channels: recovery (load) with strict version checking, and export (export_data) without version checking

  • Version strategy: uses global package version, immutable per instance

  • Storage strategy: local filesystem only, no backend abstraction

  • Task state acquisition: supports dict or objects with get_task_state()

See also

qpanda3_runtime.runtime_service

Main runtime service client.

qpanda3_runtime.device

Quantum device interfaces.

Examples

>>> from qpanda3_runtime.toolbox import CheckPoint
>>> checkpoint = CheckPoint()
>>> filepath = checkpoint.save(task_state=quantum_state, user_data={'algorithm': 'VQE'})
>>> loaded_data = checkpoint.load(filepath)
property version#

Current software version, read-only.

Type:

str

save(filepath: str | None = None, task_state: Any = None, user_data: Dict | None = None) → str#

Save checkpoint data to file.

Parameters:

  • filepath (str, optional) – Checkpoint file save path. If None, generates default filename in current working directory.

  • task_state (any, optional) – Task state. Supports: - dict: Direct reference, no copy performed - Object with get_task_state() method: Returns state dict - None or other types: Treated as no task state

  • user_data (dict, optional) – User-defined data dictionary. Values must be JSON-serializable.

Returns:

Actual written file path (absolute path).

Return type:

str

Raises:

TypeError – If task_state is non-dict and does not implement get_task_state() method, or if user_data is not a dict.

Notes

  • System does not manage checkpoint identifiers or guarantee filename uniqueness

  • Default filename format: checkpoint_YYYYMMDD_HHMMSS.json

  • When task_state is dict, it is directly referenced (no copy)

  • Version is automatically injected into metadata

  • Existing files are overwritten

  • Not thread-safe for concurrent writes to same file

load(filepath: str) → Dict#

Load checkpoint data with strict version checking (recovery channel).

Parameters:

filepath (str) – Checkpoint file path, must exist and be readable.

Returns:

Dictionary with three fixed keys: - ‘meta’: dict - Read-only metadata, including version, creation time - ‘task_state’: dict - Task state dictionary, may be empty - ‘user_data’: dict - User-defined data

Return type:

dict

Raises:

  • VersionMismatchError – If checkpoint version does not match self.version.

  • FileNotFoundError – If checkpoint file not found.

  • JSONDecodeError – If file content is not valid JSON format.

Notes

  • Strict version checking: version in metadata must equal self.version

  • System does not maintain checkpoint index

  • No automatic recovery operations performed

export_data(filepath: str) → Dict#

Export checkpoint data without version checking (export channel).

Parameters:

filepath (str) – Checkpoint file path, must exist and be readable.

Returns:

Dictionary with following keys: - ‘meta’: dict - Complete built-in metadata, including version - ‘user_data’: dict - Complete user-defined data - ‘task_state_available’: bool - Whether task state data exists

Return type:

dict

Raises:

  • FileNotFoundError – If checkpoint file not found.

  • JSONDecodeError – If file content is not valid JSON format.

Notes

  • No version checking: can be called across versions

  • Never returns task_state content

  • Read-only operation, does not modify data

  • Metadata includes version information for version comparison