Target

class Target(description=None, num_qubits=0, dt=None, granularity=1, min_length=1, pulse_alignment=1, aquire_alignment=1, qubit_properties=None)

GitHub

Bases: collections.abc.Mapping

The intent of the Target object is to inform Qiskit’s compiler about the constraints of a particular backend so the compiler can compile an input circuit to something that works and is optimized for a device. It currently contains a description of instructions on a backend and their properties as well as some timing information. However, this exact interface may evolve over time as the needs of the compiler change. These changes will be done in a backwards compatible and controlled manner when they are made (either through versioning, subclassing, or mixins) to add on to the set of information exposed by a target.

As a basic example, let’s assume backend has two qubits, supports UGate on both qubits and CXGate in both directions. To model this you would create the target like:

from qiskit.transpiler import Target, InstructionProperties
from qiskit.circuit.library import UGate, CXGate
from qiskit.circuit import Parameter
 
gmap = Target()
theta = Parameter('theta')
phi = Parameter('phi')
lam = Parameter('lambda')
u_props = {
    (0,): InstructionProperties(duration=5.23e-8, error=0.00038115),
    (1,): InstructionProperties(duration=4.52e-8, error=0.00032115),
}
gmap.add_instruction(UGate(theta, phi, lam), u_props)
cx_props = {
    (0,1): InstructionProperties(duration=5.23e-7, error=0.00098115),
    (1,0): InstructionProperties(duration=4.52e-7, error=0.00132115),
}
gmap.add_instruction(CXGate(), cx_props)

Each instruction in the Target is indexed by a unique string name that uniquely identifies that instance of an Instruction object in the Target. There is a 1:1 mapping between a name and an Instruction instance in the target and each name must be unique. By default the name is the name attribute of the instruction, but can be set to anything. This lets a single target have multiple instances of the same instruction class with different parameters. For example, if a backend target has two instances of an RXGate one is parameterized over any theta while the other is tuned up for a theta of pi/6 you can add these by doing something like:

import math
 
from qiskit.transpiler import Target, InstructionProperties
from qiskit.circuit.library import RXGate
from qiskit.circuit import Parameter
 
target = Target()
theta = Parameter('theta')
rx_props = {
    (0,): InstructionProperties(duration=5.23e-8, error=0.00038115),
}
target.add_instruction(RXGate(theta), rx_props)
rx_30_props = {
    (0,): InstructionProperties(duration=1.74e-6, error=.00012)
}
target.add_instruction(RXGate(math.pi / 6), rx_30_props, name='rx_30')

Then in the target object accessing by rx_30 will get the fixed angle RXGate while rx will get the parameterized RXGate.

Note

This class assumes that qubit indices start at 0 and are a contiguous set if you want a submapping the bits will need to be reindexed in a new``Target`` object.

Note

This class only supports additions of gates, qargs, and qubits. If you need to remove one of these the best option is to iterate over an existing object and create a new subset (or use one of the methods to do this). The object internally caches different views and these would potentially be invalidated by removals.

Create a new Target object

Parameters

description (str) – An optional string to describe the Target.
num_qubits (int) – An optional int to specify the number of qubits the backend target has. If not set it will be implicitly set based on the qargs when add_instruction() is called. Note this must be set if the backend target is for a noiseless simulator that doesn’t have constraints on the instructions so the transpiler knows how many qubits are available.
dt (float) – The system time resolution of input signals in seconds
granularity (int) – An integer value representing minimum pulse gate resolution in units of dt. A user-defined pulse gate should have duration of a multiple of this granularity value.
min_length (int) – An integer value representing minimum pulse gate length in units of dt. A user-defined pulse gate should be longer than this length.
pulse_alignment (int) – An integer value representing a time resolution of gate instruction starting time. Gate instruction should start at time which is a multiple of the alignment value.
acquire_alignment (int) – An integer value representing a time resolution of measure instruction starting time. Measure instruction should start at time which is a multiple of the alignment value.
qubit_properties (list) – A list of QubitProperties objects defining the characteristics of each qubit on the target device. If specified the length of this list must match the number of qubits in the target, where the index in the list matches the qubit number the properties are defined for. If some qubits don’t have properties available you can set that entry to None

Raises

ValueError – If both num_qubits and qubit_properties are both
defined and the value of num_qubits differs from the length of –
qubit_properties` –

Methods

add_instruction

Target.add_instruction(instruction, properties=None, name=None)

Add a new instruction to the Target

As Target objects are strictly additive this is the primary method for modifying a Target. Typically you will use this to fully populate a Target before using it in BackendV2. For example:

from qiskit.circuit.library import CXGate
from qiskit.transpiler import Target, InstructionProperties
 
target = Target()
cx_properties = {
    (0, 1): None,
    (1, 0): None,
    (0, 2): None,
    (2, 0): None,
    (0, 3): None,
    (2, 3): None,
    (3, 0): None,
    (3, 2): None
}
target.add_instruction(CXGate(), cx_properties)

Will add a CXGate to the target with no properties (duration, error, etc) with the coupling edge list: (0, 1), (1, 0), (0, 2), (2, 0), (0, 3), (2, 3), (3, 0), (3, 2). If there are properties available for the instruction you can replace the None value in the properties dictionary with an InstructionProperties object. This pattern is repeated for each Instruction the target supports.

Parameters

instruction (qiskit.circuit.Instruction) – The operation object to add to the map. If it’s paramerterized any value of the parameter can be set. Optionally for variable width instructions (such as control flow operations such as ForLoop or MCXGate) you can specify the class. If the class is specified than the name argument must be specified. When a class is used the gate is treated as global and not having any properties set.
properties (dict) – A dictionary of qarg entries to an InstructionProperties object for that instruction implementation on the backend. Properties are optional for any instruction implementation, if there are no InstructionProperties available for the backend the value can be None. If there are no constraints on the instruction (as in a noisless/ideal simulation) this can be set to {None, None} which will indicate it runs on all qubits (or all available permutations of qubits for multi-qubit gates). The first None indicates it applies to all qubits and the second None indicates there are no InstructionProperties for the instruction. By default, if properties is not set it is equivalent to passing {None: None}.
name (str) – An optional name to use for identifying the instruction. If not specified the name attribute of gate will be used. All gates in the Target need unique names. Backends can differentiate between different parameterizations of a single gate by providing a unique name for each (e.g. “rx30”, “rx60”, `”rx90”`` similar to the example in the documentation for the Target class).

Raises

AttributeError – If gate is already in map
TranspilerError – If an operation class is passed in for instruction and no name is specified or properties is set.

build_coupling_map

Target.build_coupling_map(two_q_gate=None)

Get a CouplingMap from this target.

If there is a mix of two qubit operations that have a connectivity constraint and those that are globally defined this will also return None because the globally connectivity means there is no contstraint on the target. If you wish to see the constraints of the two qubit operations that have constraints you should use the two_q_gate argument to limit the output to the gates which have a constraint.

Parameters

two_q_gate (str) – An optional gate name for a two qubit gate in the Target to generate the coupling map for. If specified the output coupling map will only have edges between qubits where this gate is present.

Returns

The CouplingMap object

for this target. If there are no connectivity constraints in the target this will return None.

Return type

CouplingMap

Raises

ValueError – If a non-two qubit gate is passed in for two_q_gate.
IndexError – If an Instruction not in the Target is passed in for two_q_gate.

durations

Target.durations()

Get an InstructionDurations object from the target

Returns

The instruction duration represented in the

target

Return type

InstructionDurations

get

Target.get(k[, d]) → D[k] if k in D, else d. d defaults to None.

get_non_global_operation_names

Target.get_non_global_operation_names(strict_direction=False)

Return the non-global operation names for the target

The non-global operations are those in the target which don’t apply on all qubits (for single qubit operations) or all multiqubit qargs (for multi-qubit operations).

Parameters

strict_direction (bool) – If set to True the multi-qubit operations considered as non-global respect the strict direction (or order of qubits in the qargs is signifcant). For example, if cx is defined on (0, 1) and ecr is defined over (1, 0) by default neither would be considered non-global, but if strict_direction is set True both cx and ecr would be returned.

Returns

A list of operation names for operations that aren’t global in this target

Return type

List[str]

instruction_properties

Target.instruction_properties(index)

Get the instruction properties for a specific instruction tuple

This method is to be used in conjunction with the instructions attribute of a Target object. You can use this method to quickly get the instruction properties for an element of instructions by using the index in that list. However, if you’re not working with instructions directly it is likely more efficient to access the target directly via the name and qubits to get the instruction properties. For example, if instructions returned:

[(XGate(), (0,)), (XGate(), (1,))]

you could get the properties of the XGate on qubit 1 with:

props = target.instruction_properties(1)

but just accessing it directly via the name would be more efficient:

props = target['x'][(1,)]

(assuming the XGate’s canonical name in the target is 'x') This is especially true for larger targets as this will scale worse with the number of instruction tuples in a target.

Parameters

index (int) – The index of the instruction tuple from the instructions attribute. For, example if you want the properties from the third element in instructions you would set this to be 2.

Returns

The instruction properties for the specified instruction tuple

Return type

InstructionProperties

instruction_schedule_map

Target.instruction_schedule_map()

Return an InstructionScheduleMap for the instructions in the target with a pulse schedule defined.

Returns

The instruction schedule map for the instructions in this target with a pulse schedule defined.

Return type

InstructionScheduleMap

instruction_supported

Target.instruction_supported(operation_name=None, qargs=None, operation_class=None, parameters=None)

Return whether the instruction (operation + qubits) is supported by the target

Parameters

operation_name (str) – The name of the operation for the instruction. Either this or operation_class must be specified, if both are specified operation_class will take priority and this argument will be ignored.
qargs (tuple) – The tuple of qubit indices for the instruction. If this is not specified then this method will return True if the specified operation is supported on any qubits. The typical application will always have this set (otherwise it’s the same as just checking if the target contains the operation). Normally you would not set this argument if you wanted to check more generally that the target supports an operation with the parameters on any qubits.
operation_class (qiskit.circuit.Instruction) – The operation class to check whether the target supports a particular operation by class rather than by name. This lookup is more expensive as it needs to iterate over all operations in the target instead of just a single lookup. If this is specified it will supersede the operation_name argument. The typical use case for this operation is to check whether a specific variant of an operation is supported on the backend. For example, if you wanted to check whether a RXGate was supported on a specific qubit with a fixed angle. That fixed angle variant will typically have a name different than the object’s name attribute ("rx") in the target. This can be used to check if any instances of the class are available in such a case.
parameters (list) –

A list of parameters to check if the target supports them on the specified qubits. If the instruction supports the parameter values specified in the list on the operation and qargs specified this will return True but if the parameters are not supported on the specified instruction it will return False. If this argument is not specified this method will return True if the instruction is supported independent of the instruction parameters. If specified with any Parameter objects in the list, that entry will be treated as supporting any value, however parameter names will not be checked (for example if an operation in the target is listed as parameterized with "theta" and "phi" is passed into this function that will return True). For example, if called with:
```
parameters = [Parameter("theta")]
target.instruction_supported("rx", (0,), parameters=parameters)
```
will return True if an RXGate is suporrted on qubit 0 that will accept any parameter. If you need to check for a fixed numeric value parameter this argument is typically paired with the operation_class argument. For example:
```
target.instruction_supported("rx", (0,), RXGate, parameters=[pi / 4])
```
will return True if an RXGate(pi/4) exists on qubit 0.

Returns

Returns True if the instruction is supported and False if it isn’t.

Return type

bool

items

Target.items() → a set-like object providing a view on D's items

keys

Target.keys() → a set-like object providing a view on D's keys

operation_from_name

Target.operation_from_name(instruction)

Get the operation class object for a given name

Parameters

instruction (str) – The instruction name to get the Instruction instance for

Returns

The Instruction instance corresponding to the name. This also can also be the class for globally defined variable with operations.

Return type

qiskit.circuit.Instruction

operation_names_for_qargs

Target.operation_names_for_qargs(qargs)

Get the operation names for a specified qargs tuple

Parameters

qargs (tuple) – A qargs tuple of the qubits to get the gates that apply to it. For example, (0,) will return the set of all instructions that apply to qubit 0. If set to None this will return the names for any globally defined operations in the target.

Returns

The set of operation names that apply to the specified qargs`.

Return type

set

Raises

KeyError – If qargs is not in target

operations_for_qargs

Target.operations_for_qargs(qargs)

Get the operation class object for a specified qargs tuple

Parameters

Returns

The list of Instruction instances that apply to the specified qarg. This may also be a class if a variable width operation is globally defined.

Return type

list

Raises

KeyError – If qargs is not in target

qargs_for_operation_name

Target.qargs_for_operation_name(operation)

Get the qargs for a given operation name

Parameters

operation (str) – The operation name to get qargs for

Returns

The set of qargs the gate instance applies to.

Return type

set

timing_constraints

Target.timing_constraints()

Get an TimingConstraints object from the target

Returns

The timing constraints represented in the Target

Return type

TimingConstraints

update_from_instruction_schedule_map

Target.update_from_instruction_schedule_map(inst_map, inst_name_map=None, error_dict=None)

Update the target from an instruction schedule map.

If the input instruction schedule map contains new instructions not in the target they will be added. However if it contains additional qargs for an existing instruction in the target it will error.

Parameters

inst_map (InstructionScheduleMap) – The instruction
inst_name_map (dict) – An optional dictionary that maps any instruction name in inst_map to an instruction object
error_dict (dict) –

A dictionary of errors of the form:
```
{gate_name: {qarg: error}}
```
example:: (for) – {‘rx’: {(0, ): 1.4e-4, (1, ): 1.2e-4}}
defined (For each entry in the inst_map if error_dict is) –
from (a when updating the Target the error value will be pulled) –
then (this dictionary. If one is not found in error_dict) –
used. (None will be) –

Raises

ValueError – If inst_map contains new instructions and inst_name_map isn’t specified
KeyError – If a inst_map contains a qarg for an instruction that’s not in the target

update_instruction_properties

Target.update_instruction_properties(instruction, qargs, properties)

Update the property object for an instruction qarg pair already in the Target

Parameters

instruction (str) – The instruction name to update
qargs (tuple) – The qargs to update the properties of
properties (InstructionProperties) – The properties to set for this nstruction

Raises

KeyError – If instruction or qarg are not in the target

values

Target.values() → an object providing a view on D's values

Attributes

num_qubits

description

dt

granularity

min_length

pulse_alignment

aquire_alignment

qubit_properties

instructions

Get the list of tuples (:class:`~qiskit.circuit.Instruction`, (qargs)) for the target

For globally defined variable width operations the tuple will be of the form (class, None) where class is the actual operation class that is globally defined.

operation_names

Get the operation names in the target.

operations

Get the operation class objects in the target.

physical_qubits

Returns a sorted list of physical_qubits

qargs

The set of qargs in the target.

Was this page helpful?

Report a bug or request content on GitHub.