mimiqcircuits.remote

Remote connection and execution utilities.

Classes

MimiqConnection([url])

Represents a connection to the Mimiq Server via direct cloud connection.

PlanqkConnection([url, consumer_key, ...])

Represents a connection to the Mimiq Server via PlanQK.

QCSError(error)

RemoteConnection(connection)

Base class for connections to the Mimiq Server.
class mimiqcircuits.remote.MimiqConnection(url=None)[source]

Bases: RemoteConnection

Represents a connection to the Mimiq Server via direct cloud connection.

This is a wrapper around mimiqlink.MimiqConnection to provide the circuit execution API.

__init__(url=None)[source]

Initialize a MimiqConnection.

Parameters:

url (str, optional) – The URL of the Mimiq server. Defaults to None (using default cloud URL).

class mimiqcircuits.remote.PlanqkConnection(url=None, consumer_key=None, consumer_secret=None)[source]

Bases: RemoteConnection

Represents a connection to the Mimiq Server via PlanQK.

This is a wrapper around mimiqlink.PlanqkConnection to provide the circuit execution API.

__init__(url=None, consumer_key=None, consumer_secret=None)[source]

Initialize a PlanqkConnection.

Parameters:

  • url (str, optional) – The URL of the PlanQK API. Defaults to None (using default PlanQK URL).

  • consumer_key (str, optional) – The consumer key for PlanQK authentication. Defaults to None.

  • consumer_secret (str, optional) – The consumer secret for PlanQK authentication. Defaults to None.

class mimiqcircuits.remote.RemoteConnection(connection)[source]

Bases: object

Base class for connections to the Mimiq Server.

This class provides common functionality for both MimiqConnection and PlanqkConnection.

__init__(connection)[source]

Initialize a remote connection using a specific connection type.

Parameters:

connection (AbstractConnection) – A mimiqlink connection object (MimiqConnection or PlanqkConnection)

submit(circuits, label='pyapi_v0.21.2', algorithm='auto', nsamples=1000, bitstrings=None, timelimit=None, bonddim=None, entdim=None, mpscutoff=None, remove_swaps=None, canonicaldecompose=None, fuse=None, reorderqubits=None, reorderqubits_seed=None, seed=None, qasmincludes=None, force=False, mpsmethod=None, mpotraversal=None, noisemodel=None, streaming=None)[source]

Submit a circuit or a list of quantum circuits to the Mimiq server. Returns a Job object (non-blocking).

Parameters:

  • circuits (Circuit or list of Circuits or str) – A single Circuit object, a list of Circuit objects, or QASM file paths representing the circuits to be executed.

  • label (str) – A label for the execution. Defaults to “pyapi_v” + __version__.

  • algorithm (str) – The algorithm to use. Defaults to “auto”.

  • nsamples (int) – The number of samples to collect. Defaults to DEFAULT_SAMPLES.

  • seed (int, optional) – A seed for random number generation. Defaults to None.

  • bitstrings (list of str, optional) – Specific bitstrings to measure. Defaults to None.

  • timelimit (int, optional) – The maximum execution time in minutes. Defaults to None.

  • bonddim (int, optional) – The bond dimension to use. Defaults to None.

  • entdim (int, optional) – The entanglement dimension to use. Defaults to None.

  • mpscutoff (float, optional) – Singular value truncation cutoff for MPS simulation. Smaller values give higher accuracy at increased cost. Defaults to None (let the remote service decide).

  • remove_swaps (bool, optional) – Whether to remove SWAP gates. Defaults to None (let the remote service decide).

  • canonicaldecompose (bool, optional) – Whether to decompose the circuit into GateU and GateCX. Defaults to None (let the remote service decide).

  • fuse (bool, optional) – Whether to fuse gates. Defaults to None (let the remote service decide).

  • reorderqubits (bool or str, optional) – Whether to reorder qubits. Can be a boolean or a string specifying the method (e.g., ‘greedy’, ‘spectral’, ‘rcm’, ‘sa_warm_start’, ‘sa_only’, ‘memetic’, ‘multilevel’, ‘grasp’, ‘hybrid’). Defaults to None (let the remote service decide).

  • reorderqubits_seed (int, optional) – Independent seed for the qubit reordering RNG, allowing reproducible reordering independently of the simulation seed. Defaults to None (uses main seed).

  • mpsmethod (str, optional) – whether to use variational (“vmpoa”, “vmpob”) or direct (“dmpo”) methods for MPO application in MPS simulations. Defaults to None (let the remote service decide).

  • mpotraversal (str, optional) – method to traverse the circuit while compressing it into MPOs. Can be “sequential” (default) or “bfs” (Breadth-First Search). Defaults to None.

  • noisemodel (NoiseModel, optional) – A NoiseModel object to be applied to the circuit(s) before execution. Defaults to None.

  • streaming (bool, optional) – whether or not to use the streaming simulator. Defaults to None (let the remote service decide).

  • qasmincludes (list of str, optional) – Additional QASM includes. Defaults to None.

Returns:

A handle to the execution, typically used to retrieve results.

Return type:

object

Raises:

  • ValueError – If nsamples exceeds MAX_SAMPLES, bond/entanglement dimensions are out of bounds, or if a circuit contains unevaluated symbolic parameters.

  • FileNotFoundError – If a QASM file is not found.

  • TypeError – If the circuits argument is not a Circuit object or a valid file path.

execute(*args, **kwargs)[source]
schedule(*args, **kwargs)[source]

Deprecated alias for submit.

check_equivalence(experiment, **kwargs)[source]

Executes a CircuitTesterExperiment and verifies the results. Blocks until execution is complete.

Parameters:

  • experiment (CircuitTesterExperiment) – The experiment to run.

  • **kwargs – Arguments passed to execute.

Returns:

The verification score (probability of all-zero state).

Return type:

float

optimize(experiments, label='pyapi_v0.21.2', algorithm='auto', nsamples=1000, timelimit=None, bonddim=None, entdim=None, mpscutoff=None, remove_swaps=None, canonicaldecompose=None, fuse=None, reorderqubits=None, reorderqubits_seed=None, seed=None, history=False, force=False, debug=False)[source]
__repr__()[source]

Return a string representation of the connection.

__str__()[source]

Return a string representation of the connection.

get_input(execution, **kwargs)

Retrieve the first circuit or experiment and parameters of the execution.

Parameters:

execution (str) – The execution identifier.

Returns:

A tuple containing the first Circuit or OptimizationExperiment object and parameters (dict).

Return type:

tuple

Raises:

RuntimeError – If required files are not found in the inputs.

get_inputs(execution)

Retrieve the inputs (circuits or experiments and parameters) of the execution.

Parameters:

execution (str) – The execution identifier.

Returns:

A tuple containing a list of Circuit or OptimizationExperiment objects and parameters (dict).

Return type:

tuple

Raises:

RuntimeError – If required files are not found in the inputs.

get_result(execution, **kwargs)

Retrieve the first result if multiple are found.

Parameters:

  • execution (str) – The execution identifier.

  • **kwargs – Additional keyword arguments for result retrieval.

Returns:

The first result found.

Return type:

QCSResults | OptimizationRun | OptimizationResults

Raises:

RuntimeWarning – If multiple results are found.

get_results(execution, interval=1)

Retrieve the results of a completed execution.

Parameters:

  • execution (str) – The execution identifier.

  • interval (int) – The interval (in seconds) for checking job status (default: 1).

Returns:

A list of result instances.

Return type:

List[QCSResults | OptimizationRun | OptimizationResults]

Raises:

RuntimeError – If the remote job encounters an error.