cengines
The ProjectQ compiler engines package.
The parent class from which all mappers should be derived. |
|
Module containing the basic definition of a compiler engine. |
|
A CommandModifier engine that can be used to apply a user-defined transformation to all incoming commands. |
|
Contains a compiler engine to map to the 5-qubit IBM chip. |
|
Mapper for a quantum circuit to a linear chain of qubits. |
|
The main engine of every compiler engine pipeline, called MainEngine. |
|
A compiler engine to add mapping information. |
|
A local optimizer engine. |
|
A compiler engine which flips the directionality of CNOTs according to the given connectivity graph. |
|
The TagRemover compiler engine. |
|
TestEngine and DummyEngine. |
|
Mapper for a quantum circuit to a 2D square grid. |
|
|
A compiler engine to automatically replace certain commands. |
Basic compiler engine: All compiler engines are derived from this class. |
|
Parent class for all Mappers. |
|
|
Compiler engine applying a user-defined transformation to all incoming commands. |
Command list comparison compiler engine for testing purposes. |
|
@contextmanager decorator. |
|
|
A rule for breaking down specific gates into sequences of simpler gates. |
A collection of indexed decomposition rules. |
|
|
DummyEngine used for testing. |
|
Context manager to flush the given engine at the end of the 'with' context block. |
|
A ForwarderEngine is a trivial engine which forwards all commands to the next engine. |
|
Mapper to a 2-D grid graph. |
|
Mapper for the 5-qubit IBM backend. |
|
A compiler engine that implements a user-defined is_available() method. |
Exception thrown when the last engine tries to access the next one. |
|
|
Map a quantum circuit to a linear chain of nearest neighbour interactions. |
|
Circuit optimization compiler engine. |
|
The MainEngine class provides all functionality of the main compiler engine. |
|
Manual Mapper which adds QubitPlacementTags to Allocate gate commands according to a user-specified mapping. |
Exception raised when trying to access the measurement value of a qubit that has not yet been measured. |
|
Return the circuit depth to execute these swaps. |
|
Flip CNOTs and translates Swaps to CNOTs where necessary. |
|
|
Compiler engine that remove temporary command tags. |
Exception raised when a non-supported compiler engine is encountered. |
Submodules
_basicmapper
The parent class from which all mappers should be derived.
There is only one engine currently allowed to be derived from BasicMapperEngine. This allows the simulator to automatically translate logical qubit ids to mapped ids.
_basics
Module containing the basic definition of a compiler engine.
- class projectq.cengines._basics.BasicEngine[source]
Basic compiler engine: All compiler engines are derived from this class.
It provides basic functionality such as qubit allocation/deallocation and functions that provide information about the engine’s position (e.g., next engine).
This information is provided by the MainEngine, which initializes all further engines.
- next_engine
Next compiler engine (or the back-end).
- Type:
- main_engine
Reference to the main compiler engine.
- Type:
- is_last_engine
True for the last engine, which is the back-end.
- Type:
bool
- allocate_qubit(dirty=False)[source]
Return a new qubit as a list containing 1 qubit object (quantum register of size 1).
Allocates a new qubit by getting a (new) qubit id from the MainEngine, creating the qubit object, and then sending an AllocateQubit command down the pipeline. If dirty=True, the fresh qubit can be replaced by a pre-allocated one (in an unknown, dirty, initial state). Dirty qubits must be returned to their initial states before they are deallocated / freed.
All allocated qubits are added to the MainEngine’s set of active qubits as weak references. This allows proper clean-up at the end of the Python program (using atexit), deallocating all qubits which are still alive. Qubit ids of dirty qubits are registered in MainEngine’s dirty_qubits set.
- Parameters:
dirty (bool) – If True, indicates that the allocated qubit may be dirty (i.e., in an arbitrary initial state).
- Returns:
Qureg of length 1, where the first entry is the allocated qubit.
- allocate_qureg(n_qubits)[source]
Allocate n qubits and return them as a quantum register, which is a list of qubit objects.
- Parameters:
n (int) – Number of qubits to allocate
- Returns:
Qureg of length n, a list of n newly allocated qubits.
- deallocate_qubit(qubit)[source]
Deallocate a qubit (and sends the deallocation command down the pipeline).
If the qubit was allocated as a dirty qubit, add DirtyQubitTag() to Deallocate command.
- Parameters:
qubit (BasicQubit) – Qubit to deallocate.
- Raises:
ValueError – Qubit already deallocated. Caller likely has a bug.
- is_available(cmd)[source]
Test whether a Command is supported by a compiler engine.
Default implementation of is_available: Ask the next engine whether a command is available, i.e., whether it can be executed by the next engine(s).
- Parameters:
cmd (Command) – Command for which to check availability.
- Returns:
True if the command can be executed.
- Raises:
LastEngineException – If is_last_engine is True but is_available is not implemented.
- is_meta_tag_supported(meta_tag)[source]
Check if there is a compiler engine handling the meta tag.
- Parameters:
engine – First engine to check (then iteratively calls getNextEngine)
meta_tag – Meta tag class for which to check support
- Returns:
True if one of the further compiler engines is a meta tag handler, i.e., engine.is_meta_tag_handler(meta_tag) returns True.
- Return type:
supported (bool)
- class projectq.cengines._basics.ForwarderEngine(engine, cmd_mod_fun=None)[source]
A ForwarderEngine is a trivial engine which forwards all commands to the next engine.
It is mainly used as a substitute for the MainEngine at lower levels such that meta operations still work (e.g., with Compute).
- exception projectq.cengines._basics.LastEngineException(engine)[source]
Exception thrown when the last engine tries to access the next one. (Next engine does not exist).
The default implementation of isAvailable simply asks the next engine whether the command is available. An engine which legally may be the last engine, this behavior needs to be adapted (see BasicEngine.isAvailable).
_cmdmodifier
A CommandModifier engine that can be used to apply a user-defined transformation to all incoming commands.
A CommandModifier engine can be used to, e.g., modify the tags of all commands which pass by (see the AutoReplacer for an example).
- class projectq.cengines._cmdmodifier.CommandModifier(cmd_mod_fun)[source]
Compiler engine applying a user-defined transformation to all incoming commands.
CommandModifier is a compiler engine which applies a function to all incoming commands, sending on the resulting command instead of the original one.
_ibm5qubitmapper
Contains a compiler engine to map to the 5-qubit IBM chip.
- class projectq.cengines._ibm5qubitmapper.IBM5QubitMapper(connections=None)[source]
Mapper for the 5-qubit IBM backend.
Maps a given circuit to the IBM Quantum Experience chip.
Note
The mapper has to be run once on the entire circuit.
Warning
If the provided circuit cannot be mapped to the hardware layout without performing Swaps, the mapping procedure raises an Exception.
- is_available(cmd)[source]
Check if the IBM backend can perform the Command cmd and return True if so.
- Parameters:
cmd (Command) – The command to check
- receive(command_list)[source]
Receive a list of commands.
Receive a command list and, for each command, stores it until completion.
- Parameters:
command_list (list of Command objects) – list of commands to receive.
- Raises:
Exception – If mapping the CNOT gates to 1 qubit would require Swaps. The current version only supports remapping of CNOT gates without performing any Swaps due to the large costs associated with Swapping given the CNOT constraints.
_linearmapper
Mapper for a quantum circuit to a linear chain of qubits.
- Input: Quantum circuit with 1 and 2 qubit gates on n qubits. Gates are assumed to be applied in parallel if they act
on disjoint qubit(s) and any pair of qubits can perform a 2 qubit gate (all-to-all connectivity)
- Output: Quantum circuit in which qubits are placed in 1-D chain in which only nearest neighbour qubits can perform a 2
qubit gate. The mapper uses Swap gates in order to move qubits next to each other.
- class projectq.cengines._linearmapper.LinearMapper(num_qubits, cyclic=False, storage=1000)[source]
Map a quantum circuit to a linear chain of nearest neighbour interactions.
Maps a quantum circuit to a linear chain of qubits with nearest neighbour interactions using Swap gates. It supports open or cyclic boundary conditions.
- current_mapping[source]
Stores the mapping: key is logical qubit id, value is mapped qubit id from 0,…,self.num_qubits
- cyclic
If chain is cyclic or not
- Type:
Bool
- storage
Number of gate it caches before mapping.
- Type:
int
- num_mappings
Number of times the mapper changed the mapping
- Type:
int
- depth_of_swaps
Key are circuit depth of swaps, value is the number of such mappings which have been applied
- Type:
dict
- num_of_swaps_per_mapping
Key are the number of swaps per mapping, value is the number of such mappings which have been applied
- Type:
dict
Note
Gates are cached and only mapped from time to time. A FastForwarding gate doesn’t empty the cache, only a FlushGate does.
Only 1 and two qubit gates allowed.
Does not optimize for dirty qubits.
- receive(command_list)[source]
Receive a list of commands.
Receive a command list and, for each command, stores it until we do a mapping (FlushGate or Cache of stored commands is full).
- Parameters:
command_list (list of Command objects) – list of commands to receive.
- static return_new_mapping(num_qubits, cyclic, currently_allocated_ids, stored_commands, current_mapping)[source]
Build a mapping of qubits to a linear chain.
It goes through stored_commands and tries to find a mapping to apply these gates on a first come first served basis. More compilicated scheme could try to optimize to apply as many gates as possible between the Swaps.
- Parameters:
num_qubits (int) – Total number of qubits in the linear chain
cyclic (bool) – If linear chain is a cycle.
currently_allocated_ids (set of int) – Logical qubit ids for which the Allocate gate has already been processed and sent to the next engine but which are not yet deallocated and hence need to be included in the new mapping.
stored_commands (list of Command objects) – Future commands which should be applied next.
current_mapping – A current mapping as a dict. key is logical qubit id, value is placement id. If there are different possible maps, this current mapping is used to minimize the swaps to go to the new mapping by a heuristic.
- Returns: A new mapping as a dict. key is logical qubit id,
value is placement id
- projectq.cengines._linearmapper.return_swap_depth(swaps)[source]
Return the circuit depth to execute these swaps.
- Parameters:
swaps (list of tuples) – Each tuple contains two integers representing the two IDs of the qubits involved in the Swap operation
- Returns:
Circuit depth to execute these swaps.
_main
The main engine of every compiler engine pipeline, called MainEngine.
- class projectq.cengines._main.MainEngine(backend=None, engine_list=None, verbose=False)[source]
The MainEngine class provides all functionality of the main compiler engine.
It initializes all further compiler engines (calls, e.g., .next_engine=…) and keeps track of measurement results and active qubits (and their IDs).
- next_engine
Next compiler engine (or the back-end).
- Type:
- main_engine
Self.
- Type:
- active_qubits
WeakSet containing all active qubits
- Type:
WeakSet
- dirty_qubits
Containing all dirty qubit ids
- Type:
Set
- backend
Access the back-end.
- Type:
- mapper
Access to the mapper if there is one.
- Type:
- n_engines
Current number of compiler engines in the engine list
- Type:
int
- n_engines_max
Maximum number of compiler engines allowed in the engine list. Defaults to 100.
- Type:
int
- flush(deallocate_qubits=False)[source]
Flush the entire circuit down the pipeline, clearing potential buffers (of, e.g., optimizers).
- Parameters:
deallocate_qubits (bool) – If True, deallocates all qubits that are still alive (invalidating references to them by setting their id to -1).
- get_measurement_result(qubit)[source]
Return the classical value of a measured qubit, given that an engine registered this result previously.
See also setMeasurementResult.
- Parameters:
qubit (BasicQubit) – Qubit of which to get the measurement result.
Example
from projectq.ops import H, Measure from projectq import MainEngine eng = MainEngine() qubit = eng.allocate_qubit() # quantum register of size 1 H | qubit Measure | qubit eng.get_measurement_result(qubit[0]) == int(qubit)
- get_new_qubit_id()[source]
Return a unique qubit id to be used for the next qubit allocation.
- Returns:
New unique qubit id.
- Return type:
new_qubit_id (int)
- receive(command_list)[source]
Forward the list of commands to the first engine.
- Parameters:
command_list (list<Command>) – List of commands to receive (and then send on)
- send(command_list)[source]
Forward the list of commands to the next engine in the pipeline.
It also shortens exception stack traces if self.verbose is False.
- set_measurement_result(qubit, value)[source]
Register a measurement result.
The engine being responsible for measurement results needs to register these results with the master engine such that they are available when the user calls an int() or bool() conversion operator on a measured qubit.
- Parameters:
qubit (BasicQubit) – Qubit for which to register the measurement result.
value (bool) – Boolean value of the measurement outcome (True / False = 1 / 0 respectively).
_manualmapper
A compiler engine to add mapping information.
- class projectq.cengines._manualmapper.ManualMapper(map_fun=<function ManualMapper.<lambda>>)[source]
Manual Mapper which adds QubitPlacementTags to Allocate gate commands according to a user-specified mapping.
- map
The function which maps a given qubit id to its location. It gets set when initializing the mapper.
- Type:
function
_optimize
A local optimizer engine.
- class projectq.cengines._optimize.LocalOptimizer(cache_size=5, m=None)[source]
Circuit optimization compiler engine.
LocalOptimizer is a compiler engine which optimizes locally (merging rotations, cancelling gates with their inverse) in a local window of user- defined size.
It stores all commands in a dict of lists, where each qubit has its own gate pipeline. After adding a gate, it tries to merge / cancel successive gates using the get_merged and get_inverse functions of the gate (if available). For examples, see BasicRotationGate. Once a list corresponding to a qubit contains >=m gates, the pipeline is sent on to the next engine.
_replacer
_swapandcnotflipper
A compiler engine which flips the directionality of CNOTs according to the given connectivity graph.
It also translates Swap gates to CNOTs if necessary.
- class projectq.cengines._swapandcnotflipper.SwapAndCNOTFlipper(connectivity)[source]
Flip CNOTs and translates Swaps to CNOTs where necessary.
Warning
This engine assumes that CNOT and Hadamard gates are supported by the following engines.
Warning
This engine cannot be used as a backend.
- is_available(cmd)[source]
Check if the IBM backend can perform the Command cmd and return True if so.
- Parameters:
cmd (Command) – The command to check
- receive(command_list)[source]
Receive a list of commands.
Receive a command list and if the command is a CNOT gate, it flips it using Hadamard gates if necessary; if it is a Swap gate, it decomposes it using 3 CNOTs. All other gates are simply sent to the next engine.
- Parameters:
command_list (list of Command objects) – list of commands to receive.
_tagremover
The TagRemover compiler engine.
A TagRemover engine removes temporary command tags (such as Compute/Uncompute), thus enabling optimization across meta statements (loops after unrolling, compute/uncompute, …)
- class projectq.cengines._tagremover.TagRemover(tags=None)[source]
Compiler engine that remove temporary command tags.
TagRemover is a compiler engine which removes temporary command tags (see the tag classes such as LoopTag in projectq.meta._loop).
Removing tags is important (after having handled them if necessary) in order to enable optimizations across meta-function boundaries (compute/ action/uncompute or loops after unrolling)
- receive(command_list)[source]
Receive a list of commands.
Receive a list of commands from the previous engine, remove all tags which are an instance of at least one of the meta tags provided in the constructor, and then send them on to the next compiler engine.
- Parameters:
command_list (list<Command>) – List of commands to receive and then (after removing tags) send on.
_testengine
TestEngine and DummyEngine.
- class projectq.cengines._testengine.CompareEngine[source]
Command list comparison compiler engine for testing purposes.
CompareEngine is an engine which saves all commands. It is only intended for testing purposes. Two CompareEngine backends can be compared and return True if they contain the same commands.
- class projectq.cengines._testengine.DummyEngine(save_commands=False)[source]
DummyEngine used for testing.
The DummyEngine forwards all commands directly to next engine. If self.is_last_engine == True it just discards all gates. By setting save_commands == True all commands get saved as a list in self.received_commands. Elements are appended to this list so they are ordered according to when they are received.
_twodmapper
Mapper for a quantum circuit to a 2D square grid.
- Input: Quantum circuit with 1 and 2 qubit gates on n qubits. Gates are assumed to be applied in parallel if they act
on disjoint qubit(s) and any pair of qubits can perform a 2 qubit gate (all-to-all connectivity)
- Output: Quantum circuit in which qubits are placed in 2-D square grid in which only nearest neighbour qubits can
perform a 2 qubit gate. The mapper uses Swap gates in order to move qubits next to each other.
- class projectq.cengines._twodmapper.GridMapper(num_rows, num_columns, mapped_ids_to_backend_ids=None, storage=1000, optimization_function=<function return_swap_depth>, num_optimization_steps=50)[source]
Mapper to a 2-D grid graph.
Mapped qubits on the grid are numbered in row-major order. E.g. for 3 rows and 2 columns:
0 - 1 | | 2 - 3 | | 4 - 5
The numbers are the mapped qubit ids. The backend might number the qubits on the grid differently (e.g. not row-major), we call these backend qubit ids. If the backend qubit ids are not row-major, one can pass a dictionary translating from our row-major mapped ids to these backend ids.
Note: The algorithm sorts twice inside each column and once inside each row.
- storage
Number of gate it caches before mapping.
- Type:
int
- num_rows
Number of rows in the grid
- Type:
int
- num_columns
Number of columns in the grid
- Type:
int
- num_qubits
num_rows x num_columns = number of qubits
- Type:
int
- num_mappings
Number of times the mapper changed the mapping
- Type:
int
- depth_of_swaps
Key are circuit depth of swaps, value is the number of such mappings which have been applied
- Type:
dict
- num_of_swaps_per_mapping
Key are the number of swaps per mapping, value is the number of such mappings which have been applied
- Type:
dict
- receive(command_list)[source]
Receive a list of commands.
Receive a command list and, for each command, stores it until we do a mapping (FlushGate or Cache of stored commands is full).
- Parameters:
command_list (list of Command objects) – list of commands to receive.
- return_swaps(old_mapping, new_mapping, permutation=None)[source]
Return the swap operation to change mapping.
- Parameters:
old_mapping – dict: keys are logical ids and values are mapped qubit ids
new_mapping – dict: keys are logical ids and values are mapped qubit ids
permutation – list of int from 0, 1, …, self.num_rows-1. It is used to permute the found perfect matchings. Default is None which keeps the original order.
- Returns:
List of tuples. Each tuple is a swap operation which needs to be applied. Tuple contains the two mapped qubit ids for the Swap.
Module contents
ProjectQ module containing all compiler engines.
- class projectq.cengines.AutoReplacer(decomposition_rule_se, decomposition_chooser=<function AutoReplacer.<lambda>>)[source]
A compiler engine to automatically replace certain commands.
The AutoReplacer is a compiler engine which uses engine.is_available in order to determine which commands need to be replaced/decomposed/compiled further. The loaded setup is used to find decomposition rules appropriate for each command (e.g., setups.default).
- __init__(decomposition_rule_se, decomposition_chooser=<function AutoReplacer.<lambda>>)[source]
Initialize an AutoReplacer.
- Parameters:
decomposition_chooser (function) – A function which, given the Command to decompose and a list of potential Decomposition objects, determines (and then returns) the ‘best’ decomposition.
The default decomposition chooser simply returns the first list element, i.e., calling
repl = AutoReplacer()
Amounts to
def decomposition_chooser(cmd, decomp_list): return decomp_list[0] repl = AutoReplacer(decomposition_chooser)
- class projectq.cengines.BasicEngine[source]
Basic compiler engine: All compiler engines are derived from this class.
It provides basic functionality such as qubit allocation/deallocation and functions that provide information about the engine’s position (e.g., next engine).
This information is provided by the MainEngine, which initializes all further engines.
- next_engine
Next compiler engine (or the back-end).
- Type:
- main_engine
Reference to the main compiler engine.
- Type:
- is_last_engine
True for the last engine, which is the back-end.
- Type:
bool
- __init__()[source]
Initialize the basic engine.
Initializes local variables such as _next_engine, _main_engine, etc. to None.
- allocate_qubit(dirty=False)[source]
Return a new qubit as a list containing 1 qubit object (quantum register of size 1).
Allocates a new qubit by getting a (new) qubit id from the MainEngine, creating the qubit object, and then sending an AllocateQubit command down the pipeline. If dirty=True, the fresh qubit can be replaced by a pre-allocated one (in an unknown, dirty, initial state). Dirty qubits must be returned to their initial states before they are deallocated / freed.
All allocated qubits are added to the MainEngine’s set of active qubits as weak references. This allows proper clean-up at the end of the Python program (using atexit), deallocating all qubits which are still alive. Qubit ids of dirty qubits are registered in MainEngine’s dirty_qubits set.
- Parameters:
dirty (bool) – If True, indicates that the allocated qubit may be dirty (i.e., in an arbitrary initial state).
- Returns:
Qureg of length 1, where the first entry is the allocated qubit.
- allocate_qureg(n_qubits)[source]
Allocate n qubits and return them as a quantum register, which is a list of qubit objects.
- Parameters:
n (int) – Number of qubits to allocate
- Returns:
Qureg of length n, a list of n newly allocated qubits.
- deallocate_qubit(qubit)[source]
Deallocate a qubit (and sends the deallocation command down the pipeline).
If the qubit was allocated as a dirty qubit, add DirtyQubitTag() to Deallocate command.
- Parameters:
qubit (BasicQubit) – Qubit to deallocate.
- Raises:
ValueError – Qubit already deallocated. Caller likely has a bug.
- is_available(cmd)[source]
Test whether a Command is supported by a compiler engine.
Default implementation of is_available: Ask the next engine whether a command is available, i.e., whether it can be executed by the next engine(s).
- Parameters:
cmd (Command) – Command for which to check availability.
- Returns:
True if the command can be executed.
- Raises:
LastEngineException – If is_last_engine is True but is_available is not implemented.
- is_meta_tag_supported(meta_tag)[source]
Check if there is a compiler engine handling the meta tag.
- Parameters:
engine – First engine to check (then iteratively calls getNextEngine)
meta_tag – Meta tag class for which to check support
- Returns:
True if one of the further compiler engines is a meta tag handler, i.e., engine.is_meta_tag_handler(meta_tag) returns True.
- Return type:
supported (bool)
- class projectq.cengines.BasicMapperEngine[source]
Parent class for all Mappers.
- self.current_mapping
Keys are the logical qubit ids and values are the mapped qubit ids.
- Type:
dict
- class projectq.cengines.CommandModifier(cmd_mod_fun)[source]
Compiler engine applying a user-defined transformation to all incoming commands.
CommandModifier is a compiler engine which applies a function to all incoming commands, sending on the resulting command instead of the original one.
- class projectq.cengines.CompareEngine[source]
Command list comparison compiler engine for testing purposes.
CompareEngine is an engine which saves all commands. It is only intended for testing purposes. Two CompareEngine backends can be compared and return True if they contain the same commands.
- class projectq.cengines.DecompositionRule(gate_class, gate_decomposer, gate_recognizer=<function DecompositionRule.<lambda>>)[source]
A rule for breaking down specific gates into sequences of simpler gates.
- __init__(gate_class, gate_decomposer, gate_recognizer=<function DecompositionRule.<lambda>>)[source]
Initialize a DecompositionRule object.
- Parameters:
gate_class (type) –
The type of gate that this rule decomposes.
The gate class is redundant information used to make lookups faster when iterating over a circuit and deciding “which rules apply to this gate?” again and again.
Note that this parameter is a gate type, not a gate instance. You supply gate_class=MyGate or gate_class=MyGate().__class__, not gate_class=MyGate().
gate_decomposer (function[projectq.ops.Command]) – Function which, given the command to decompose, applies a sequence of gates corresponding to the high-level function of a gate of type gate_class.
(function[projectq.ops.Command] (gate_recognizer) –
boolean): A predicate that determines if the decomposition applies to the given command (on top of the filtering by gate_class).
For example, a decomposition rule may only to apply rotation gates that rotate by a specific angle.
If no gate_recognizer is given, the decomposition applies to all gates matching the gate_class.
- class projectq.cengines.DecompositionRuleSet(rules=None, modules=None)[source]
A collection of indexed decomposition rules.
- __init__(rules=None, modules=None)[source]
Initialize a DecompositionRuleSet object.
- Parameters:
list[DecompositionRule] (rules) – Initial decomposition rules.
modules (iterable[ModuleWithDecompositionRuleSet]) – A list of things with an “all_defined_decomposition_rules” property containing decomposition rules to add to the rule set.
- class projectq.cengines.DummyEngine(save_commands=False)[source]
DummyEngine used for testing.
The DummyEngine forwards all commands directly to next engine. If self.is_last_engine == True it just discards all gates. By setting save_commands == True all commands get saved as a list in self.received_commands. Elements are appended to this list so they are ordered according to when they are received.
- class projectq.cengines.ForwarderEngine(engine, cmd_mod_fun=None)[source]
A ForwarderEngine is a trivial engine which forwards all commands to the next engine.
It is mainly used as a substitute for the MainEngine at lower levels such that meta operations still work (e.g., with Compute).
- __init__(engine, cmd_mod_fun=None)[source]
Initialize a ForwarderEngine.
- Parameters:
engine (BasicEngine) – Engine to forward all commands to.
cmd_mod_fun (function) – Function which is called before sending a command. Each command cmd is replaced by the command it returns when getting called with cmd.
- class projectq.cengines.GridMapper(num_rows, num_columns, mapped_ids_to_backend_ids=None, storage=1000, optimization_function=<function return_swap_depth>, num_optimization_steps=50)[source]
Mapper to a 2-D grid graph.
Mapped qubits on the grid are numbered in row-major order. E.g. for 3 rows and 2 columns:
0 - 1 | | 2 - 3 | | 4 - 5
The numbers are the mapped qubit ids. The backend might number the qubits on the grid differently (e.g. not row-major), we call these backend qubit ids. If the backend qubit ids are not row-major, one can pass a dictionary translating from our row-major mapped ids to these backend ids.
Note: The algorithm sorts twice inside each column and once inside each row.
- storage
Number of gate it caches before mapping.
- Type:
int
- num_rows
Number of rows in the grid
- Type:
int
- num_columns
Number of columns in the grid
- Type:
int
- num_qubits
num_rows x num_columns = number of qubits
- Type:
int
- num_mappings
Number of times the mapper changed the mapping
- Type:
int
- depth_of_swaps
Key are circuit depth of swaps, value is the number of such mappings which have been applied
- Type:
dict
- num_of_swaps_per_mapping
Key are the number of swaps per mapping, value is the number of such mappings which have been applied
- Type:
dict
- __init__(num_rows, num_columns, mapped_ids_to_backend_ids=None, storage=1000, optimization_function=<function return_swap_depth>, num_optimization_steps=50)[source]
Initialize a GridMapper compiler engine.
- Parameters:
num_rows (int) – Number of rows in the grid
num_columns (int) – Number of columns in the grid.
mapped_ids_to_backend_ids (dict) – Stores a mapping from mapped ids which are 0,…,self.num_qubits-1 in row-major order on the grid to the corresponding qubit ids of the backend. Key: mapped id. Value: corresponding backend id. Default is None which means backend ids are identical to mapped ids.
storage – Number of gates to temporarily store
optimization_function – Function which takes a list of swaps and returns a cost value. Mapper chooses a permutation which minimizes this cost. Default optimizes for circuit depth.
num_optimization_steps (int) – Number of different permutations to of the matching to try and minimize the cost.
- Raises:
RuntimeError – if incorrect mapped_ids_to_backend_ids parameter
- receive(command_list)[source]
Receive a list of commands.
Receive a command list and, for each command, stores it until we do a mapping (FlushGate or Cache of stored commands is full).
- Parameters:
command_list (list of Command objects) – list of commands to receive.
- return_swaps(old_mapping, new_mapping, permutation=None)[source]
Return the swap operation to change mapping.
- Parameters:
old_mapping – dict: keys are logical ids and values are mapped qubit ids
new_mapping – dict: keys are logical ids and values are mapped qubit ids
permutation – list of int from 0, 1, …, self.num_rows-1. It is used to permute the found perfect matchings. Default is None which keeps the original order.
- Returns:
List of tuples. Each tuple is a swap operation which needs to be applied. Tuple contains the two mapped qubit ids for the Swap.
- class projectq.cengines.IBM5QubitMapper(connections=None)[source]
Mapper for the 5-qubit IBM backend.
Maps a given circuit to the IBM Quantum Experience chip.
Note
The mapper has to be run once on the entire circuit.
Warning
If the provided circuit cannot be mapped to the hardware layout without performing Swaps, the mapping procedure raises an Exception.
- __init__(connections=None)[source]
Initialize an IBM 5-qubit mapper compiler engine.
Resets the mapping.
- is_available(cmd)[source]
Check if the IBM backend can perform the Command cmd and return True if so.
- Parameters:
cmd (Command) – The command to check
- receive(command_list)[source]
Receive a list of commands.
Receive a command list and, for each command, stores it until completion.
- Parameters:
command_list (list of Command objects) – list of commands to receive.
- Raises:
Exception – If mapping the CNOT gates to 1 qubit would require Swaps. The current version only supports remapping of CNOT gates without performing any Swaps due to the large costs associated with Swapping given the CNOT constraints.
- class projectq.cengines.InstructionFilter(filterfun)[source]
A compiler engine that implements a user-defined is_available() method.
The InstructionFilter is a compiler engine which changes the behavior of is_available according to a filter function. All commands are passed to this function, which then returns whether this command can be executed (True) or needs replacement (False).
- __init__(filterfun)[source]
Initialize an InstructionFilter object.
Initializer: The provided filterfun returns True for all commands which do not need replacement and False for commands that do.
- Parameters:
filterfun (function) – Filter function which returns True for available commands, and False otherwise. filterfun will be called as filterfun(self, cmd).
- exception projectq.cengines.LastEngineException(engine)[source]
Exception thrown when the last engine tries to access the next one. (Next engine does not exist).
The default implementation of isAvailable simply asks the next engine whether the command is available. An engine which legally may be the last engine, this behavior needs to be adapted (see BasicEngine.isAvailable).
- class projectq.cengines.LinearMapper(num_qubits, cyclic=False, storage=1000)[source]
Map a quantum circuit to a linear chain of nearest neighbour interactions.
Maps a quantum circuit to a linear chain of qubits with nearest neighbour interactions using Swap gates. It supports open or cyclic boundary conditions.
- current_mapping[source]
Stores the mapping: key is logical qubit id, value is mapped qubit id from 0,…,self.num_qubits
- cyclic
If chain is cyclic or not
- Type:
Bool
- storage
Number of gate it caches before mapping.
- Type:
int
- num_mappings
Number of times the mapper changed the mapping
- Type:
int
- depth_of_swaps
Key are circuit depth of swaps, value is the number of such mappings which have been applied
- Type:
dict
- num_of_swaps_per_mapping
Key are the number of swaps per mapping, value is the number of such mappings which have been applied
- Type:
dict
Note
Gates are cached and only mapped from time to time. A FastForwarding gate doesn’t empty the cache, only a FlushGate does.
Only 1 and two qubit gates allowed.
Does not optimize for dirty qubits.
- __init__(num_qubits, cyclic=False, storage=1000)[source]
Initialize a LinearMapper compiler engine.
- Parameters:
num_qubits (int) – Number of physical qubits in the linear chain
cyclic (bool) – If 1D chain is a cycle. Default is False.
storage (int) – Number of gates to temporarily store, default is 1000
- receive(command_list)[source]
Receive a list of commands.
Receive a command list and, for each command, stores it until we do a mapping (FlushGate or Cache of stored commands is full).
- Parameters:
command_list (list of Command objects) – list of commands to receive.
- static return_new_mapping(num_qubits, cyclic, currently_allocated_ids, stored_commands, current_mapping)[source]
Build a mapping of qubits to a linear chain.
It goes through stored_commands and tries to find a mapping to apply these gates on a first come first served basis. More compilicated scheme could try to optimize to apply as many gates as possible between the Swaps.
- Parameters:
num_qubits (int) – Total number of qubits in the linear chain
cyclic (bool) – If linear chain is a cycle.
currently_allocated_ids (set of int) – Logical qubit ids for which the Allocate gate has already been processed and sent to the next engine but which are not yet deallocated and hence need to be included in the new mapping.
stored_commands (list of Command objects) – Future commands which should be applied next.
current_mapping – A current mapping as a dict. key is logical qubit id, value is placement id. If there are different possible maps, this current mapping is used to minimize the swaps to go to the new mapping by a heuristic.
- Returns: A new mapping as a dict. key is logical qubit id,
value is placement id
- class projectq.cengines.LocalOptimizer(cache_size=5, m=None)[source]
Circuit optimization compiler engine.
LocalOptimizer is a compiler engine which optimizes locally (merging rotations, cancelling gates with their inverse) in a local window of user- defined size.
It stores all commands in a dict of lists, where each qubit has its own gate pipeline. After adding a gate, it tries to merge / cancel successive gates using the get_merged and get_inverse functions of the gate (if available). For examples, see BasicRotationGate. Once a list corresponding to a qubit contains >=m gates, the pipeline is sent on to the next engine.
- class projectq.cengines.MainEngine(backend=None, engine_list=None, verbose=False)[source]
The MainEngine class provides all functionality of the main compiler engine.
It initializes all further compiler engines (calls, e.g., .next_engine=…) and keeps track of measurement results and active qubits (and their IDs).
- next_engine
Next compiler engine (or the back-end).
- Type:
- main_engine
Self.
- Type:
- active_qubits
WeakSet containing all active qubits
- Type:
WeakSet
- dirty_qubits
Containing all dirty qubit ids
- Type:
Set
- backend
Access the back-end.
- Type:
- mapper
Access to the mapper if there is one.
- Type:
- n_engines
Current number of compiler engines in the engine list
- Type:
int
- n_engines_max
Maximum number of compiler engines allowed in the engine list. Defaults to 100.
- Type:
int
- __init__(backend=None, engine_list=None, verbose=False)[source]
Initialize the main compiler engine and all compiler engines.
Sets ‘next_engine’- and ‘main_engine’-attributes of all compiler engines and adds the back-end as the last engine.
- Parameters:
backend (BasicEngine) – Backend to send the compiled circuit to.
engine_list (list<BasicEngine>) – List of engines / backends to use as compiler engines. Note: The engine list must not contain multiple mappers (instances of BasicMapperEngine). Default: projectq.setups.default.get_engine_list()
verbose (bool) – Either print full or compact error messages. Default: False (i.e. compact error messages).
Example
from projectq import MainEngine eng = MainEngine() # uses default engine_list and the Simulator
Instead of the default engine_list one can use, e.g., one of the IBM setups which defines a custom engine_list useful for one of the IBM chips
Example
import projectq.setups.ibm as ibm_setup from projectq import MainEngine eng = MainEngine(engine_list=ibm_setup.get_engine_list()) # eng uses the default Simulator backend
Alternatively, one can specify all compiler engines explicitly, e.g.,
Example
from projectq.cengines import ( TagRemover, AutoReplacer, LocalOptimizer, DecompositionRuleSet, ) from projectq.backends import Simulator from projectq import MainEngine rule_set = DecompositionRuleSet() engines = [AutoReplacer(rule_set), TagRemover(), LocalOptimizer(3)] eng = MainEngine(Simulator(), engines)
- flush(deallocate_qubits=False)[source]
Flush the entire circuit down the pipeline, clearing potential buffers (of, e.g., optimizers).
- Parameters:
deallocate_qubits (bool) – If True, deallocates all qubits that are still alive (invalidating references to them by setting their id to -1).
- get_measurement_result(qubit)[source]
Return the classical value of a measured qubit, given that an engine registered this result previously.
See also setMeasurementResult.
- Parameters:
qubit (BasicQubit) – Qubit of which to get the measurement result.
Example
from projectq.ops import H, Measure from projectq import MainEngine eng = MainEngine() qubit = eng.allocate_qubit() # quantum register of size 1 H | qubit Measure | qubit eng.get_measurement_result(qubit[0]) == int(qubit)
- get_new_qubit_id()[source]
Return a unique qubit id to be used for the next qubit allocation.
- Returns:
New unique qubit id.
- Return type:
new_qubit_id (int)
- receive(command_list)[source]
Forward the list of commands to the first engine.
- Parameters:
command_list (list<Command>) – List of commands to receive (and then send on)
- send(command_list)[source]
Forward the list of commands to the next engine in the pipeline.
It also shortens exception stack traces if self.verbose is False.
- set_measurement_result(qubit, value)[source]
Register a measurement result.
The engine being responsible for measurement results needs to register these results with the master engine such that they are available when the user calls an int() or bool() conversion operator on a measured qubit.
- Parameters:
qubit (BasicQubit) – Qubit for which to register the measurement result.
value (bool) – Boolean value of the measurement outcome (True / False = 1 / 0 respectively).
- class projectq.cengines.ManualMapper(map_fun=<function ManualMapper.<lambda>>)[source]
Manual Mapper which adds QubitPlacementTags to Allocate gate commands according to a user-specified mapping.
- map
The function which maps a given qubit id to its location. It gets set when initializing the mapper.
- Type:
function
- __init__(map_fun=<function ManualMapper.<lambda>>)[source]
Initialize the mapper to a given mapping.
If no mapping function is provided, the qubit id is used as the location.
- Parameters:
map_fun (function) – Function which, given the qubit id, returns an integer describing the physical location (must be constant).
- exception projectq.cengines.NotYetMeasuredError[source]
Exception raised when trying to access the measurement value of a qubit that has not yet been measured.
- class projectq.cengines.SwapAndCNOTFlipper(connectivity)[source]
Flip CNOTs and translates Swaps to CNOTs where necessary.
Warning
This engine assumes that CNOT and Hadamard gates are supported by the following engines.
Warning
This engine cannot be used as a backend.
- __init__(connectivity)[source]
Initialize the engine.
- Parameters:
connectivity (set) – Set of tuples (c, t) where if (c, t) is an element of the set means that a CNOT can be performed between the physical ids (c, t) with c being the control and t being the target qubit.
- is_available(cmd)[source]
Check if the IBM backend can perform the Command cmd and return True if so.
- Parameters:
cmd (Command) – The command to check
- receive(command_list)[source]
Receive a list of commands.
Receive a command list and if the command is a CNOT gate, it flips it using Hadamard gates if necessary; if it is a Swap gate, it decomposes it using 3 CNOTs. All other gates are simply sent to the next engine.
- Parameters:
command_list (list of Command objects) – list of commands to receive.
- class projectq.cengines.TagRemover(tags=None)[source]
Compiler engine that remove temporary command tags.
TagRemover is a compiler engine which removes temporary command tags (see the tag classes such as LoopTag in projectq.meta._loop).
Removing tags is important (after having handled them if necessary) in order to enable optimizations across meta-function boundaries (compute/ action/uncompute or loops after unrolling)
- __init__(tags=None)[source]
Initialize a TagRemover object.
- Parameters:
tags – A list of meta tag classes (e.g., [ComputeTag, UncomputeTag]) denoting the tags to remove
- receive(command_list)[source]
Receive a list of commands.
Receive a list of commands from the previous engine, remove all tags which are an instance of at least one of the meta tags provided in the constructor, and then send them on to the next compiler engine.
- Parameters:
command_list (list<Command>) – List of commands to receive and then (after removing tags) send on.
- exception projectq.cengines.UnsupportedEngineError[source]
Exception raised when a non-supported compiler engine is encountered.
- projectq.cengines.contextmanager(func)[source]
@contextmanager decorator.
Typical usage:
@contextmanager def some_generator(<arguments>):
<setup> try:
yield <value>
- finally:
<cleanup>
This makes this:
- with some_generator(<arguments>) as <variable>:
<body>
equivalent to this:
<setup> try:
<variable> = <value> <body>
- finally:
<cleanup>
- projectq.cengines.flushing(engine)[source]
Context manager to flush the given engine at the end of the ‘with’ context block.
Example
- with flushing(MainEngine()) as eng:
qubit = eng.allocate_qubit() …
Calling ‘eng.flush()’ is no longer needed because the engine will be flushed at the end of the ‘with’ block even if an exception has been raised within that block.