Simulators

Submodules

simulator api module

class tequila_code.simulators.simulator_api.BackendTypes(CircType, ExpValueType)

Bases: tuple

CircType

Alias for field number 0

ExpValueType

Alias for field number 1

tequila_code.simulators.simulator_api.compile(objective: Objective | QCircuit | QTensor, variables: Dict[Variable | Hashable, Real] = None, samples: int = None, backend: str = None, noise: NoiseModel = None, device: str = None, *args, **kwargs) → BackendCircuit | Objective

Compile a tequila objective or circuit to a backend

Parameters:

• objective (Objective:) – tequila objective or circuit

• variables (dict, optional:) – The variables of the objective given as dictionary with keys as tequila Variables and values the corresponding real numbers

• samples (int, optional:) – if None a full wavefunction simulation is performed, otherwise a fixed number of samples is simulated

• backend (str, optional:) – specify the backend or give None for automatic assignment

• noise (NoiseModel, optional:) – the noise model to apply to the objective or QCircuit.

• device (optional:) – a device on which (or in emulation of which) to sample the circuit.

Returns:

the compiled object.

Return type:

simulators.BackendCircuit or Objective

tequila_code.simulators.simulator_api.compile_circuit(abstract_circuit: QCircuit, variables: Dict[Variable, RealNumber] = None, backend: str = None, samples: int = None, noise: NoiseModel = None, device: str = None, *args, **kwargs) → BackendCircuit

compile a circuit to render it callable and return it. :param abstract_circuit: the circuit to compile :type abstract_circuit: QCircuit: :param variables: the variables to compile the circuit with. :type variables: dict, optional: :param backend: the backend to compile the circuit to. :type backend: str, optional: :param samples: only matters if not None; compile the circuit for sampling/verify backend can do so :type samples: int, optional: :param device: the device on which the circuit should (perhaps emulatedly) sample. :type device: optional: :param noise: the noise to apply to the circuit :type noise: str or NoiseModel, optional: :param args: :param kwargs:

Returns:

the compiled circuit.

Return type:

BackendCircuit

tequila_code.simulators.simulator_api.compile_objective(objective: Objective, variables: Dict[Variable, Real] = None, backend: str = None, samples: int = None, device: str = None, noise: NoiseModel = None, *args, **kwargs) → Objective

compile an objective to render it callable and return it. :param objective: the objective to compile :type objective: Objective: :param variables: the variables to compile the objective with. Will autogenerate zeros for all variables if not supplied. :type variables: dict, optional: :param backend: the backend to compile the objective to. :type backend: str, optional: :param samples: only matters if not None; compile the objective for sampling/verify backend can do so :type samples: int, optional: :param device: the device on which the objective should (perhaps emulatedly) sample. :type device: optional: :param noise: the noise to apply to all circuits in the objective. :type noise: str or NoiseModel, optional: :param args: :param kwargs:

Returns:

the compiled objective.

Return type:

Objective

tequila_code.simulators.simulator_api.compile_to_function(objective: Objective | QCircuit, *args, **kwargs) → BackendCircuit | Objective

Notes

Same as compile but gives back callable wrapper where parameters are passed down as arguments instead of dictionaries the order of those arguments is the order of the parameter dictionary given here. If not given it is the order returned by objective.extract_variables()

See compile for more information on the parameters of this function

Returns:

wrapper over a compiled objective/circuit can be called like: function(0.0,1.0,…,samples=None)

Return type:

BackendCircuit or Objective

tequila_code.simulators.simulator_api.draw(objective, variables=None, backend: str = None, name=None, *args, **kwargs)

Pretty output (depends on installed backends) for jupyter notebooks or similar HTML environments

Parameters:

• objective – the tequila objective to print out

• variables (optional:) – Give variables if the objective is parametrized (not necesarry for displaying)

• name (optional:) – Name the objective (changes circuit filenames for qpic backend)

• backend (str, optional:) – chose preferred backend (of None or not found it will be automatically picked)

tequila_code.simulators.simulator_api.pick_backend(backend: str = None, samples: int = None, noise: NoiseModel = None, device=None, exclude_symbolic: bool = True) → str

choose, or verify, a backend for the user. :param backend: what backend to choose or verify. if None: choose for the user. :type backend: str, optional: :param samples: if int and not None, choose (verify) a simulator which supports sampling. :type samples: int, optional: :param noise: if not None, choose (verify) a simulator supports the specified noise. :type noise: str or NoiseModel, optional: :param device: verify that a given backend supports the specified device. MUST specify backend, if not None.

if None: do not emulate or use real device.

Parameters:

exclude_symbolic (bool, optional:) – whether or not to exclude the tequila debugging simulator from the available simulators, when choosing.

Returns:

the name of the chosen (or verified) backend.

Return type:

str

tequila_code.simulators.simulator_api.show_available_simulators()

tequila_code.simulators.simulator_api.simulate(objective: Objective | QCircuit | QTensor, variables: Dict[Variable | Hashable, Real] = None, samples: int = None, backend: str = None, noise: NoiseModel = None, device: str = None, *args, **kwargs) → Real | QubitWaveFunction

Simulate a tequila objective or circuit

Parameters:

• objective (Objective:) – tequila objective or circuit

• variables (Dict:) – The variables of the objective given as dictionary with keys as tequila Variables/hashable types and values the corresponding real numbers

• samples (int, optional:) – if None a full wavefunction simulation is performed, otherwise a fixed number of samples is simulated

• backend (str, optional:) – specify the backend or give None for automatic assignment

• noise (NoiseModel, optional:) – specify a noise model to apply to simulation/sampling

• device – a device upon which (or in emulation of which) to sample

• *args

• **kwargs – read_out_qubits = list[int] (define the qubits which shall be measured, has only effect on pure QCircuit simulation with samples)

Returns:

the result of simulation.

Return type:

float or QubitWaveFunction

simulator base module

class tequila_code.simulators.simulator_base.BackendCircuit(abstract_circuit: QCircuit, variables, noise=None, device=None, qubit_map=None, optimize_circuit=True, *args, **kwargs)

Bases: object

Base class for circuits compiled to run on specific backends.

no_translation

set this attribute in the derived __init__ to prevent translation of abstract_circuits needed for simulators that use native tequila types. Default is false

abstract_circuit

the tequila circuit from which the backend circuit is built.

circuit

the compiled circuit in the backend language.

compiler_arguments

dictionary of arguments for compilation needed for chosen backend. Overwritten by inheritors.

device

instantiated device (or None) for executing circuits.

n_qubits

the number of qubits this circuit operates on.

noise

the NoiseModel applied to this circuit when sampled.

qubit_map

the mapping from tequila qubits to the qubits of the backend circuit. Dicationary with keys being integers that enumerate the abstract qubits of the abstract_circuit and values being data-structures holding number and instance where number enumerates the backend qubits and instance is the instance of a backend qubit

qubits

a list of the qubits operated on by the circuit.

create_circuit()

generate a backend circuit from an abstract tequila circuit

check_device:

see if a given device is valid for the backend.

retrieve_device:

get an instance of or necessary informaton about a device, for emulation or use.

add_parametrized_gate()

add a parametrized gate to a backend circuit.

add_basic_gate()

add an unparametrized gate to a backend circuit.

add_measurement()

add a measurement gate to a backend circuit.

initialize_circuit:

generate an empty circuit object for the backend.

update_variables:

overwrite the saved values of variables for backend execution.

simulate:

perform simulation, simulated sampling, or execute the circuit, e.g. with some hamiltonian for measurement.

sample_paulistring:

sample a circuit with one paulistring of a larger hamiltonian

sample:

sample a circuit, measuring an entire hamiltonian.

do_sample:

subroutine for sampling. must be overwritten by inheritors.

do_simulate:

subroutine for wavefunction simulation. must be overwritten by inheritors.

convert_measurements:

transform the result of simulation from the backend return type.

make_qubit_map:

create a dictionary to map the tequila qubit ordering to the backend qubits.

optimize_circuit:

use backend features to improve circuit depth.

extract_variables:

return a list of the variables in the abstract tequila circuit this backend circuit corresponds to.

property abstract_qubits: Iterable[Integral]

add_basic_gate(gate, circuit, *args, **kwargs)

add_measurement(circuit, target_qubits, *args, **kwargs)

add_parametrized_gate(gate, circuit, *args, **kwargs)

check_device(device)

Verify if a device can be used in the selected backend. Overwritten by inheritors. :param device: the device to verify.

Raises:

TequilaException –

compiler_arguments = {'cc_max': True, 'controlled_exponential_pauli': True, 'controlled_phase': True, 'controlled_power': True, 'controlled_rotation': True, 'exponential_pauli': True, 'generalized_rotation': True, 'hadamard_power': True, 'multitarget': True, 'phase': True, 'phase_to_z': True, 'power': True, 'swap': True, 'toffoli': True, 'trotterized': True}

convert_measurements(backend_result) → QubitWaveFunction

create_circuit(abstract_circuit: QCircuit, circuit=None, *args, **kwargs)

build the backend specific circuit from the abstract tequila circuit.

Parameters:

• abstract_circuit (QCircuit:) – the circuit to build in the backend

• circuit (BackendCircuitType (optional):) – Add to this already initialized circuit (not all backends support + operation)

• args

• kwargs

Returns:

The circuit, compiled to the backend.

Return type:

type varies

do_sample(samples, circuit, noise, abstract_qubits=None, *args, **kwargs) → QubitWaveFunction

helper function for sampling. MUST be overwritten by inheritors.

Parameters:

• samples (int:) – the number of samples to take

• circuit – the circuit to sample from. Note: Not necessarily self.circuit!

• noise – the noise to apply to the sampled circuit.

• abstract_qubits – specify which qubits to measure. Default is all

• args

• kwargs

Returns:

the result of sampling.

Return type:

QubitWaveFunction

do_simulate(variables, initial_state, *args, **kwargs) → QubitWaveFunction

helper for simulation. MUST be overwritten by inheritors.

Parameters:

• variables – the variables with which the circuit may be simulated.

• initial_state – the initial state in which the system is in prior to the application of the circuit.

• args

• kwargs

Returns:

the result of simulating the circuit.

Return type:

QubitWaveFunction

extract_variables() → Dict[str, Real]

extract the tequila variables from the circuit. :returns: the variables of the circuit. :rtype: dict

initialize_circuit(*args, **kwargs)

initialize_qubit(number: int)

In case the backend has its own Qubit Types, this function should be overwritten by inheritors.

Parameters:

number – the qubit number

Return type:

Initialized backend qubit type

make_qubit_map(qubits: dict)

Build the mapping between abstract qubits.

Must be overwritten by inheritors to do anything other than check the validity of the map. :param qubits: the qubits to map onto.

If given as a dictionary, the map is already defined If given as a list the map will be those qubits mapped to 0 …. n_qubit-1 of the backend

Returns:

the dictionary that maps the qubits of the abstract circuits to an ordered sequence of integers. keys are the abstract qubit integers values are the backend qubits those are data structures which contain name and instance where number is the qubit identifier and instance the instance of the backend qubit if the backend does not require a special object for qubits the instance should be the same as number

Return type:

Dict

property n_qubits: Integral

optimize_circuit(circuit, *args, **kwargs)

Optimize a circuit using backend tools. Should be overwritten by inheritors. :param circuit: the circuit to optimize :param args: :param kwargs:

Returns:

Optimized version of the circuit.

Return type:

Type

qubit(abstract_qubit)

Convenience. Gives back a qubit instance of the corresponding backend :param abstract_qubit: the abstract tequila qubit

Return type:

instance of backend qubit

retrieve_device(device)

get the instantiated backend device object, from user provided object (e.g, a string).

Must be overwritten by inheritors, to use devices.

Parameters:

device – object which points to the device in question, to be returned.

Returns:

varies by backend.

Return type:

Type

sample(variables, samples, read_out_qubits=None, circuit=None, *args, **kwargs)

Sample the circuit. If circuit natively equips paulistrings, sample therefrom. :param variables: the variables with which to sample the circuit. :param samples: the number of samples to take. :type samples: int: :param read_out_qubits: target qubits to measure (default is all) :type read_out_qubits: int: :param args: :param kwargs:

Returns:

The result of sampling, a recreated QubitWaveFunction in the sampled basis.

Return type:

QubitWaveFunction

sample_all_z_hamiltonian(samples: int, hamiltonian, variables, *args, **kwargs)

Sample from a Hamiltonian which only consists of Pauli-Z and unit operators :param samples: number of samples to take :param hamiltonian: the tequila hamiltonian :param args: arguments for do_sample :param kwargs: keyword arguments for do_sample

Return type:

samples, evaluated and summed Hamiltonian expectationvalue

sample_paulistring(samples: int, paulistring, variables, *args, **kwargs) → Real

Sample an individual pauli word (pauli string) and return the average result thereof. :param samples: how many samples to evaluate. :type samples: int: :param paulistring: the paulistring to be sampled. :param args: :param kwargs:

Returns:

the average result of sampling the chosen paulistring

Return type:

float

simulate(variables, initial_state=0, *args, **kwargs) → QubitWaveFunction

simulate the circuit via the backend.

Parameters:

• variables – the parameters with which to simulate the circuit.

• initial_state (Default = 0:) – one of several types; determines the base state onto which the circuit is applied. Default: the circuit is applied to the all-zero state.

• args

• kwargs

Returns:

the wavefunction of the system produced by the action of the circuit on the initial state.

Return type:

QubitWaveFunction

update_variables(variables)

This is the default, which just translates the circuit again. Overwrite in inheritors if parametrized circuits are supported.

class tequila_code.simulators.simulator_base.BackendExpectationValue(E, variables, noise, device, *args, **kwargs)

Bases: object

Class representing an ExpectationValue for evaluation by some backend.

H

the reduced tequila Hamiltonian(s) of the expectationvalue reduction procedure is tracing out all qubits that are not part of the unitary U stored as a tuple to evaluate multiple Hamiltonians over the same circuit faster in pure simulations

abstract_H

the original (non-reduced) Hamiltonian(s)

n_qubits

how many qubits appear in the expectationvalue.

U

the underlying BackendCircuit of the expectationvalue.

extract_variables:

return the underlying tequila variables of the circuit

initialize_hamiltonian()

prepare the hamiltonian for iteration over as a tuple

initialize_unitary()

compile the abstract circuit to a backend circuit.

simulate:

simulate the unitary to measure H

sample:

sample the unitary to measure H

sample_paulistring()

sample a single term from H

update_variables()

wrapper over the update_variables of BackendCircuit.

BackendCircuitType

alias of BackendCircuit

property H

property U

count_measurements()

extract_variables() → Dict[str, Real]

wrapper over circuit extract variables :returns: Todo: is it really a dict? :rtype: Dict

initialize_hamiltonian(hamiltonians: tuple) → tuple

initialize_unitary(U, variables, noise, device, *args, **kwargs)

return a compiled unitary

property n_qubits

reduce_hamiltonians(abstract_hamiltonians: tuple) → tuple

Parameters:

abstract_hamiltonians – tuple of abstract tequila Hamiltonians

Return type:

reduces Hamiltonians where the qubits that are not defined in self.U are traced out

sample(variables, samples, *args, **kwargs) → array

sample the expectationvalue.

Parameters:

• variables (dict:) – variables to supply to the unitary.

• samples (int:) – number of samples to perform.

• args

• kwargs

Returns:

a numpy array, the result of sampling.

Return type:

numpy.ndarray

simulate(variables, *args, **kwargs)

Simulate the expectationvalue.

Parameters:

• variables – variables to supply to the unitary.

• args

• kwargs

Returns:

the result of simulation.

Return type:

numpy array

update_variables(variables)

wrapper over circuit update_variables

use_mapping = True

simulator cirq module

simulator pyquil module

simulator qibo module

simulator qiskit module

simulator qlm module

simulator qulacs module

class tequila_code.simulators.simulator_qulacs.BackendCircuitQulacs(abstract_circuit, noise=None, *args, **kwargs)

Bases: BackendCircuit

Class representing circuits compiled to qulacs. See BackendCircuit for documentation of features and methods inherited therefrom

counter

counts how many distinct sympy.Symbol objects are employed in the circuit.

has_noise

whether or not the circuit is noisy. needed by the expectationvalue to do sampling properly.

noise_lookup

dict mapping strings to lists of constructors for cirq noise channel objects.

Type:

dict:

op_lookup

dictionary mapping strings (tequila gate names) to cirq.ops objects.

Type:

dict:

variables

a list of the qulacs variables of the circuit.

Type:

list:

add_noise_to_circuit:

apply a tequila NoiseModel to a qulacs circuit, by translating the NoiseModel’s instructions into noise gates.

add_basic_gate(gate, circuit, *args, **kwargs)

add an unparametrized gate to the circuit. :param gate: the gate to be added to the circuit. :type gate: QGateImpl: :param circuit: the circuit, to which a gate is to be added. :param args: :param kwargs:

Return type:

None

add_exponential_pauli_gate(gate, circuit, variables, *args, **kwargs)

Add a native qulacs Exponential Pauli gate to a circuit. :param gate: the gate to add :type gate: ExpPauliGateImpl: :param circuit: the qulacs circuit, to which the gate is to be added. :param variables: dict containing values of the parameters appearing in the pauli gate. :param args: :param kwargs:

Return type:

None

add_measurement(circuit, target_qubits, *args, **kwargs)

Add a measurement operation to a circuit. :param circuit: a circuit, to which the measurement is to be added. :param target_qubits: abstract target qubits :type target_qubits: List[int] :param args: :param kwargs:

Return type:

None

add_noise_to_circuit(noise_model)

Apply noise from a NoiseModel to a circuit. :param noise_model: the noisemodel to apply to the circuit. :type noise_model: NoiseModel:

Returns:

self.circuit, with noise added on.

Return type:

qulacs.ParametrizedQuantumCircuit

add_parametrized_gate(gate, circuit, variables, *args, **kwargs)

add a parametrized gate. :param gate: the gate to add to the circuit. :type gate: QGateImpl: :param circuit: the circuit to which the gate is to be added :param variables: dict that tells values of variables; needed IFF the gate is an ExpPauli gate. :param args: :param kwargs:

Return type:

None

compiler_arguments = {'cc_max': False, 'controlled_exponential_pauli': True, 'controlled_phase': True, 'controlled_power': True, 'controlled_rotation': True, 'exponential_pauli': False, 'generalized_rotation': True, 'hadamard_power': True, 'multitarget': True, 'phase': True, 'phase_to_z': True, 'power': True, 'swap': False, 'toffoli': False, 'trotterized': True}

convert_measurements(backend_result, target_qubits=None) → QubitWaveFunction

Transform backend evaluation results into QubitWaveFunction :param backend_result: the return value of backend simulation.

Returns:

results transformed to tequila native QubitWaveFunction

Return type:

QubitWaveFunction

do_sample(samples, circuit, noise_model=None, initial_state=0, *args, **kwargs) → QubitWaveFunction

Helper function for performing sampling.

Parameters:

• samples (int:) – the number of samples to be taken.

• circuit – the circuit to sample from.

• noise_model (optional:) – noise model to be applied to the circuit.

• initial_state – sampling supports initial states for qulacs. Indicates the initial state to which circuit is applied.

• args

• kwargs

Returns:

the results of sampling, as a Qubit Wave Function.

Return type:

QubitWaveFunction

do_simulate(variables, initial_state, *args, **kwargs)

Helper function to perform simulation.

Parameters:

• variables (dict:) – variables to supply to the circuit.

• initial_state – information indicating the initial state on which the circuit should act.

• args

• kwargs

Returns:

QubitWaveFunction representing result of the simulation.

Return type:

QubitWaveFunction

initialize_circuit(*args, **kwargs)

return an empty circuit. :param args: :param kwargs:

Return type:

qulacs.ParametricQuantumCircuit

initialize_state(n_qubits: int = None) → QuantumState

no_translation(abstract_circuit)

Todo: what is this for? :param abstract_circuit:

numbering = 0

optimize_circuit(circuit, max_block_size: int = 4, silent: bool = True, *args, **kwargs)

reduce circuit depth using the native qulacs optimizer. :param circuit: :param max_block_size: the maximum block size for use by the qulacs internal optimizer. :type max_block_size: int: Default = 4: :param silent: whether or not to print the resullt of having optimized. :type silent: bool: :param args: :param kwargs:

Returns:

optimized qulacs circuit.

Return type:

qulacs.QuantumCircuit

update_variables(variables)

set new variable values for the circuit. :param variables: the variables to supply to the circuit. :type variables: dict:

Return type:

None

class tequila_code.simulators.simulator_qulacs.BackendExpectationValueQulacs(E, variables, noise, device, *args, **kwargs)

Bases: BackendExpectationValue

Class representing Expectation Values compiled for Qulacs.

Ovverrides some methods of BackendExpectationValue, which should be seen for details.

BackendCircuitType

alias of BackendCircuitQulacs

initialize_hamiltonian(hamiltonians)

Convert reduced hamiltonians to native Qulacs types for efficient expectation value evaluation. :param hamiltonians: an interable set of hamiltonian objects.

Returns:

initialized hamiltonian objects.

Return type:

list

sample(variables, samples, *args, **kwargs) → array

Sample this Expectation Value. :param variables: variables, to supply to the underlying circuit. :param samples: the number of samples to take. :type samples: int: :param args: :param kwargs:

Returns:

the result of sampling as a number.

Return type:

numpy.ndarray

simulate(variables, *args, **kwargs) → array

Perform simulation of this expectationvalue. :param variables: variables, to be supplied to the underlying circuit. :param args: :param kwargs:

Returns:

the result of simulation as an array.

Return type:

numpy.array

use_mapping = True

exception tequila_code.simulators.simulator_qulacs.TequilaQulacsException(msg)

Bases: TequilaException

simulator qulacs gpu module

class tequila_code.simulators.simulator_qulacs_gpu.BackendCircuitQulacsGpu(abstract_circuit, noise=None, *args, **kwargs)

Bases: BackendCircuitQulacs

initialize_state(n_qubits: int = None) → QuantumState

class tequila_code.simulators.simulator_qulacs_gpu.BackendExpectationValueQulacsGpu(E, variables, noise, device, *args, **kwargs)

Bases: BackendExpectationValueQulacs

BackendCircuitType

alias of BackendCircuitQulacsGpu

exception tequila_code.simulators.simulator_qulacs_gpu.TequilaQulacsGpuException(msg)

Bases: TequilaException

simulator symbolic module

class tequila_code.simulators.simulator_symbolic.BackendCircuitSymbolic(abstract_circuit: QCircuit, variables, noise=None, device=None, qubit_map=None, optimize_circuit=True, *args, **kwargs)

Bases: BackendCircuit

classmethod apply_gate(state: QubitWaveFunction, gate: QGate, qubits: dict, variables) → QubitWaveFunction

classmethod apply_on_standard_basis(gate: QGate, basisfunction: BitString, qubits: dict, variables) → QubitWaveFunction

compiler_arguments = {'cc_max': True, 'controlled_exponential_pauli': True, 'controlled_phase': True, 'controlled_power': True, 'controlled_rotation': False, 'exponential_pauli': True, 'generalized_rotation': True, 'hadamard_power': True, 'multitarget': True, 'phase': True, 'phase_to_z': True, 'power': True, 'swap': True, 'toffoli': True, 'trotterized': True}

convert_to_numpy = True

create_circuit(abstract_circuit: QCircuit, variables=None)

build the backend specific circuit from the abstract tequila circuit.

Parameters:

• abstract_circuit (QCircuit:) – the circuit to build in the backend

• circuit (BackendCircuitType (optional):) – Add to this already initialized circuit (not all backends support + operation)

• args

• kwargs

Returns:

The circuit, compiled to the backend.

Return type:

type varies

do_simulate(variables, initial_state: int = None, *args, **kwargs) → QubitWaveFunction

helper for simulation. MUST be overwritten by inheritors.

Parameters:

• variables – the variables with which the circuit may be simulated.

• initial_state – the initial state in which the system is in prior to the application of the circuit.

• args

• kwargs

Returns:

the result of simulating the circuit.

Return type:

QubitWaveFunction

update_variables(variables)

This is the default, which just translates the circuit again. Overwrite in inheritors if parametrized circuits are supported.

class tequila_code.simulators.simulator_symbolic.BackendExpectationValueSymbolic(E, variables, noise, device, *args, **kwargs)

Bases: BackendExpectationValue

BackendCircuitType

alias of BackendCircuitSymbolic

Module contents