experiment

ExperimentPrototype - The instance of experiment (qurry.qurrium.experiment.experiment)

class qurry.qurrium.experiment.experiment.ExperimentPrototype(arguments: _A | dict[str, Any], commonparams: Commonparams | dict[str, Any], outfields: dict[str, Any], beforewards: Before | None = None, afterwards: After | None = None, reports: AnalysesContainer | None = None)[source]

The instance of experiment.

afterwards: After

The afterwards of the experiment.

abstract property analysis_instance: Type[_R]

The analysis instance for this experiment.

abstract analyze() → _R[source]

Analyzing the example circuit results in specific method. Where should be overwritten by each construction of new measurement.

If the analysis requires additional parameters, they should be passed as arguments to this method. Also, they should be defined in the input_type() in the :cls:`AnalysisPrototype` for result() will count the input fields from the analysis to determine whether to call this method for no input required.

Returns:

The result of the analysis.

Return type:

_R

args: _A

The arguments of the experiment.

abstract property arguments_instance: Type[_A]

The arguments instance for this experiment.

beforewards: Before

The beforewards of the experiment.

classmethod build(targets: list[tuple[Hashable, QuantumCircuit]], shots: int = 1024, backend: Backend | None = None, exp_name: str = 'experiment', run_args: BaseRunArgs | dict[str, Any] | None = None, transpile_args: TranspileArgs | None = None, passmanager_pair: tuple[str, PassManager] | None = None, tags: tuple[str, ...] | None = None, serial: int | None = None, summoner_id: Hashable | None = None, summoner_name: str | None = None, qasm_version: Literal['qasm2', 'qasm3'] = 'qasm3', export: bool = False, save_location: str | Path | None = None, pbar: tqdm | None = None, multiprocess: bool = True, **custom_and_main_kwargs: Any)[source]

Construct the experiment.

Parameters:

  • targets (list[tuple[Hashable, QuantumCircuit]]) – The circuits of the experiment.

  • shots (int, optional) – Shots of the job. Defaults to 1024.

  • backend (Optional[Backend], optional) – The quantum backend. Defaults to None.

  • exp_name (str, optional) – The name of the experiment. Naming this experiment to recognize it when the jobs are pending to IBMQ Service. This name is also used for creating a folder to store the exports. Defaults to ‘experiment’.

  • run_args (RunArgsType, optional) – Arguments for Backend.run(). Defaults to None.

  • transpile_args (Optional[TranspileArgs], optional) – Arguments of transpile() from qiskit.compiler.transpiler. Defaults to None.

  • passmanager_pair (Optional[tuple[str, PassManager]], optional) – The passmanager pair for transpile. Defaults to None.

  • tags (Optional[tuple[str, ...]], optional) – Given the experiment multiple tags to make a dictionary for recongnizing it. Defaults to None.

  • serial (Optional[int], optional) – Index of experiment in a multiOutput. !!ATTENTION, this should only be used by `Multimanager`!! Defaults to None.

  • summoner_id (Optional[Hashable], optional) – ID of experiment of :cls:`MultiManager`. !!ATTENTION, this should only be used by `Multimanager`!! Defaults to None.

  • summoner_name (Optional[str], optional) – Name of experiment of :cls:`MultiManager`. !!ATTENTION, this should only be used by `Multimanager`!! _description_. Defaults to None.

  • qasm_version (Literal["qasm2", "qasm3"], optional) – The export version of OpenQASM. Defaults to ‘qasm3’.

  • export (bool, optional) – Whether to export the experiment. Defaults to False.

  • save_location (Optional[Union[Path, str]], optional) – The location to save the experiment. Defaults to None.

  • pbar (Optional[tqdm.tqdm], optional) – The progress bar for showing the progress of the experiment. Defaults to None.

  • multiprocess (bool, optional) – Whether to use multiprocessing. Defaults to True.

  • custom_and_main_kwargs (Any) – Other custom arguments.

Returns:

The experiment.

Return type:

ExperimentPrototype

classmethod build_for_multiprocess(config: dict[str, Any])[source]

Build wrapper for multiprocess.

Parameters:

config (dict[str, Any]) – The arguments of the experiment.

Returns:

The experiment.

Return type:

ExperimentPrototype

commons: Commonparams

The common parameters of the experiment.

property exp_id: str

ID of experiment.

export(save_location: str | Path | None = None, export_transpiled_circuit: bool = False) → Export[source]

Export the data of experiment into specific namedtuples for exporting.

Parameters:

  • save_location (Optional[Union[Path, str]], optional) – The location to save the experiment. Defaults to None.

  • export_transpiled_circuit (bool, optional) – Whether to export the transpiled circuit as txt. Defaults to False. When set to True, the transpiled circuit will be exported as txt. Otherwise, the circuit will be not exported but circuit qasm remains.

Returns:

A namedtuple containing the data of experiment

which can be more easily to export as json file.

Return type:

Export

property is_auto_analysis: bool

Check if the experiment has auto analysis.

Returns:

True if the experiment has auto analysis, False otherwise.

Return type:

bool

property is_hold_by_multimanager: bool

Check if the experiment is hold by a multimanager.

Returns:

True if the experiment is hold by a multimanager, False otherwise.

Return type:

bool

memory_usage_factor: int = -1

The factor of the memory usage of the experiment. When the experiment is created, it will be set to -1 for no measurement yet. When the experiment is built, it will be set to the memory usage of the experiment.

The memory usage is estimated by the number of instructions in the circuits and the number of shots. The factor is calculated by the formula:

where target_circuit_instructions_num is the number of instructions in the target circuits, transpiled_circuit_instructions_num is the number of instructions in the circuits which has been transpiled and will be run on the backend, and shots is the number of shots.

The factor is rounded to the nearest integer. The factor is used to estimate the memory usage of the experiment.

abstract classmethod method(targets: list[tuple[Hashable, QuantumCircuit]], arguments: _A, pbar: tqdm | None = None, multiprocess: bool = True) → tuple[list[QuantumCircuit], dict[str, Any]][source]

The method to construct circuit. Where should be overwritten by each construction of new measurement.

Parameters:

  • targets (list[tuple[Hashable, QuantumCircuit]]) – The circuits of the experiment.

  • arguments (_Arg) – The arguments of the experiment.

  • pbar (Optional[tqdm.tqdm], optional) – The progress bar for showing the progress of the experiment. Defaults to None.

  • multiprocess (bool, optional) – Whether to use multiprocessing. Defaults to True.

Returns:

The circuits of the experiment and the outfields.

Return type:

tuple[list[QuantumCircuit], dict[str, Any]]

outfields: dict[str, Any]

The outfields of the experiment.

abstract classmethod params_control(targets: list[tuple[Hashable, QuantumCircuit]], exp_name: str, **custom_kwargs: Any) → tuple[_A, Commonparams, dict[str, Any]][source]

Control the experiment’s parameters.

Parameters:

  • targets (list[tuple[Hashable, QuantumCircuit]]) – The circuits of the experiment.

  • exp_name (str) – Naming this experiment to recognize it when the jobs are pending to IBMQ Service. This name is also used for creating a folder to store the exports.

  • custom_kwargs (Any) – Other custom arguments.

Raises:

NotImplementedError – This method should be implemented.

abstract classmethod quantities() → dict[str, Any][source]

Computing specific squantity. Where should be overwritten by each construction of new measurement.

classmethod read(name_or_id: Path | str, save_location: Path | str = PosixPath('.'))[source]

Read the experiment from file.

Parameters:

  • name_or_id (Union[Path, str]) – The name or id of the experiment to be read.

  • save_location (Union[Path, str], optional) – The location of the experiment to be read. Defaults to Path(‘./’).

Raises:

  • ValueError – ‘save_location’ needs to be the type of ‘str’ or ‘Path’.

  • FileNotFoundError – When save_location is not available.

Returns:

The experiment to be read.

Return type:

list[ExperimentPrototype]

replace_backend(backend: Backend) → None[source]

Replace the backend of the experiment.

Parameters:

backend (Backend) – The new backend.

Raises:

  • ValueError – If the new backend is not a valid backend.

  • ValueError – If the new backend is not a runnable backend.

reports: AnalysesContainer[_R]

The reports of the experiment.

result(export: bool = False, save_location: str | Path | None = None, pbar: tqdm | None = None) → str[source]

Export the result of the experiment.

Parameters:

  • export (bool, optional) – Whether to export the experiment. Defaults to False.

  • save_location (Optional[Union[Path, str]], optional) – The location to save the experiment. Defaults to None.

  • pbar (Optional[tqdm.tqdm], optional) – The progress bar for showing the progress of the experiment. Defaults to None.

Returns:

The ID of the experiment.

Return type:

str

run(pbar: tqdm | None = None) → str[source]

Export the result after running the job.

Parameters:

pbar (Optional[tqdm.tqdm], optional) – The progress bar for showing the progress of the experiment. Defaults to None.

Raises:
Returns:

The ID of the experiment.

Return type:

str

statesheet(report_expanded: bool = False, hoshi: bool = False) → Hoshi[source]

Show the state of experiment.

Parameters:

  • report_expanded (bool, optional) – Show more infomation. Defaults to False.

  • hoshi (bool, optional) – Showing name of Hoshi. Defaults to False.

Returns:

Statesheet of experiment.

Return type:

Hoshi

write(save_location: str | Path | None = None, export_transpiled_circuit: bool = False, qurryinfo_hold_access: str | None = None, multiprocess: bool = True, pbar: tqdm | None = None) → tuple[str, dict[str, str]][source]

Export the experiment data, if there is a previous export, then will overwrite.

Parameters:

  • save_location (Optional[Union[Path, str]], optional) – Where to save the export content as json file. If save_location == None, then use the value in self.commons to be exported, if it’s None too, then raise error. Defaults to None.

  • export_transpiled_circuit (bool, optional) – Whether to export the transpiled circuit as txt. Defaults to False. When set to True, the transpiled circuit will be exported as txt. Otherwise, the circuit will be not exported but circuit qasm remains.

  • qurryinfo_hold_access (str, optional) – Whether to hold the I/O of qurryinfo, then export by :cls:`MultiManager`, it should be control by :cls:`MultiManager`. Defaults to None.

  • multiprocess (bool, optional) – Whether to use multiprocessing. Defaults to True.

  • pbar (Optional[tqdm.tqdm], optional) – The progress bar for showing the progress of the experiment. Defaults to None.

Returns:

The id of the experiment and the files location.

Return type:

tuple[str, dict[str, str]]