Target
class qiskit.transpiler.Target(description=None, num_qubits=0, dt=None, granularity=1, min_length=1, pulse_alignment=1, acquire_alignment=1, qubit_properties=None, concurrent_measurements=None)
Bases: 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
.
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.
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
qiskit.transpiler.target.Target.__init__()
’s argument aquire_alignment
is deprecated as of qiskit-terra 0.23.0. It will be removed in the Qiskit 1.0 release. Instead, use the argument acquire_alignment
, which behaves identically.
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 toNone
- concurrent_measurements (list) – A list of sets of qubits that must be measured together. This must be provided as a nested list like
[[0, 1], [2, 3, 4]]
.
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
.
Attributes
num_qubits
description
dt
granularity
min_length
pulse_alignment
acquire_alignment
qubit_properties
concurrent_measurements
aquire_alignment
Alias of deprecated name. This will be removed.
The property qiskit.transpiler.target.Target.aquire_alignment
is deprecated as of qiskit-terra 0.24.0. It will be removed in the Qiskit 1.0 release. Use the property acquire_alignment
instead.
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.
Methods
add_instruction
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 parameterized any value of the parameter can be set. Optionally for variable width instructions (such as control flow operations such as
ForLoop
orMCXGate
) you can specify the class. If the class is specified than thename
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 noInstructionProperties
available for the backend the value can be None. If there are no constraints on the instruction (as in a noiseless/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 firstNone
indicates it applies to all qubits and the secondNone
indicates there are noInstructionProperties
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 ofgate
will be used. All gates in theTarget
need unique names. Backends can differentiate between different parameterization of a single gate by providing a unique name for each (e.g. “rx30”, “rx60”, `”rx90”`` similar to the example in the documentation for theTarget
class).
Raises
- AttributeError – If gate is already in map
- TranspilerError – If an operation class is passed in for
instruction
and no name is specified orproperties
is set.
build_coupling_map
build_coupling_map(two_q_gate=None, filter_idle_qubits=False)
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 constraint 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. - filter_idle_qubits (bool) – If set to
True
the outputCouplingMap
will remove any qubits that don’t have any operations defined in the target. Note that using this argument will result in an outputCouplingMap
object which has holes in its indices which might differ from the assumptions of the class. The typical use case of this argument is to be paired withCouplingMap.connected_components()
which will handle the holes as expected.
Returns
The CouplingMap
object
for this target. If there are no connectivity constraints in the target this will return None
.
Return type
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 fortwo_q_gate
.
durations
durations()
Get an InstructionDurations object from the target
Returns
The instruction duration represented in the
target
Return type
from_configuration
classmethod from_configuration(basis_gates, num_qubits=None, coupling_map=None, inst_map=None, backend_properties=None, instruction_durations=None, concurrent_measurements=None, dt=None, timing_constraints=None, custom_name_mapping=None)
Create a target object from the individual global configuration
Prior to the creation of the Target
class, the constraints of a backend were represented by a collection of different objects which combined represent a subset of the information contained in the Target
. This function provides a simple interface to convert those separate objects to a Target
.
This constructor will use the input from basis_gates
, num_qubits
, and coupling_map
to build a base model of the backend and the instruction_durations
, backend_properties
, and inst_map
inputs are then queried (in that order) based on that model to look up the properties of each instruction and qubit. If there is an inconsistency between the inputs any extra or conflicting information present in instruction_durations
, backend_properties
, or inst_map
will be ignored.
Parameters
- basis_gates (list[str]) – The list of basis gate names for the backend. For the target to be created these names must either be in the output from
get_standard_gate_name_mapping()
or present in the specifiedcustom_name_mapping
argument. - num_qubits (int | None) – The number of qubits supported on the backend.
- coupling_map (CouplingMap | None) – The coupling map representing connectivity constraints on the backend. If specified all gates from
basis_gates
will be supported on all qubits (or pairs of qubits). - inst_map (InstructionScheduleMap | None) – The instruction schedule map representing the pulse
Schedule
definitions for each instruction. If this is specifiedcoupling_map
must be specified. Thecoupling_map
is used as the source of truth for connectivity and ifinst_map
is used the schedule is looked up based on the instructions from the pair ofbasis_gates
andcoupling_map
. If you want to define a custom gate for a particular qubit or qubit pair, you can manually buildTarget
. - backend_properties (BackendProperties | None) – The
BackendProperties
object which is used for instruction properties and qubit properties. If specified and instruction properties are intended to be used then thecoupling_map
argument must be specified. This is only used to lookup error rates and durations (unlessinstruction_durations
is specified which would take precedence) for instructions specified viacoupling_map
andbasis_gates
. - instruction_durations (InstructionDurations | None) – Optional instruction durations for instructions. If specified it will take priority for setting the
duration
field in theInstructionProperties
objects for the instructions in the target. - concurrent_measurements (list) – A list of sets of qubits that must be measured together. This must be provided as a nested list like
[[0, 1], [2, 3, 4]]
. - dt (float | None) – The system time resolution of input signals in seconds
- timing_constraints (TimingConstraints | None) – Optional timing constraints to include in the
Target
- custom_name_mapping (dict[str, Any] | None) – An optional dictionary that maps custom gate/operation names in
basis_gates
to anOperation
object representing that gate/operation. By default, most standard gates names are mapped to the standard gate object fromqiskit.circuit.library
this only needs to be specified if the inputbasis_gates
defines gates in names outside that set.
Returns
the target built from the input configuration
Return type
Raises
- TranspilerError – If the input basis gates contain > 2 qubits and
coupling_map
is - specified. –
- KeyError – If no mapping is available for a specified
basis_gate
.
get
get(k[, d]) → D[k] if k in D, else d. d defaults to None.
get_calibration
get_calibration(operation_name, qargs, *args, **kwargs)
Get calibrated pulse schedule for the instruction.
If calibration is templated with parameters, one can also provide those values to build a schedule with assigned parameters.
Parameters
- operation_name (str) – The name of the operation for the instruction.
- qargs (tuple[int, ...]) – The tuple of qubit indices for the instruction.
- args (ParameterValueType) – Parameter values to build schedule if any.
- kwargs (ParameterValueType) – Parameter values with name to build schedule if any.
Returns
Calibrated pulse schedule of corresponding instruction.
Return type
get_non_global_operation_names
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 multi-qubit 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 significant). 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]
has_calibration
has_calibration(operation_name, qargs)
Return whether the instruction (operation + qubits) defines a calibration.
Parameters
- operation_name (str) – The name of the operation for the instruction.
- qargs (tuple[int, ...]) – The tuple of qubit indices for the instruction.
Returns
Returns True
if the calibration is supported and False
if it isn’t.
Return type
instruction_properties
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
instruction_schedule_map
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
instruction_supported
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 specifiedoperation_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 theparameters
on any qubits. -
operation_class (Type[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 aRXGate
was supported on a specific qubit with a fixed angle. That fixed angle variant will typically have a name different from the object’sname
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 returnFalse
. If this argument is not specified this method will returnTrue
if the instruction is supported independent of the instruction parameters. If specified with anyParameter
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 returnTrue
). For example, if called with:parameters = [Parameter("theta")] target.instruction_supported("rx", (0,), parameters=parameters)
will return
True
if anRXGate
is supported 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 theoperation_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
items
items() → a set-like object providing a view on D's items
keys
keys() → a set-like object providing a view on D's keys
operation_from_name
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
operation_names_for_qargs
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
Raises
KeyError – If qargs
is not in target
operations_for_qargs
operations_for_qargs(qargs)
Get the operation class object 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 any globally defined operations in the target.
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
Raises
KeyError – If qargs is not in target
qargs_for_operation_name
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
timing_constraints
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
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. If not provided, instruction is pulled from the standard Qiskit gates, and finally custom gate instance is created with schedule name. -
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) –
update_instruction_properties
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 instruction
Raises
KeyError – If instruction
or qarg
are not in the target
values
values() → an object providing a view on D's values