Solver Parameters#
The problems you send to D-Wave
solvers include
problem parameters (e.g., linear biases,
h
, of an Ising problem) and solver parameters
that control how the problem is run (e.g., an annealing schedule,
anneal_schedule).
This chapter describes, in alphabetical order, the solver parameters[1] accepted by SAPI solvers[2].
anneal_offsets#
Provides offsets to annealing paths, per qubit.
Default is no offsets.
Relevant Properties#
anneal_offset_ranges defines the ranges of valid anneal offset values.
anneal_offset_step and anneal_offset_step_phi0 define the quantization steps.
Example#
This example offsets the anneal of a qubit in a two-qubit illustrative Ising problem.
>>> from dwave.system import FixedEmbeddingComposite, DWaveSampler
>>> qpu = DWaveSampler(solver={'topology__type': 'pegasus'})
>>> J = {(1, 2): -1}
>>> embedding = {1: [30], 2: [2940]}
>>> print(qpu.properties['anneal_offset_ranges'][2940])
[-0.7012257815714587, 0.6717794151250857]
>>> sampler = FixedEmbeddingComposite(qpu, embedding)
>>> offset = [0]*qpu.properties['num_qubits']
>>> offset[2940]=0.2
>>> sampleset = FixedEmbeddingComposite(qpu, embedding).sample_ising({}, J,
... num_reads=1000, anneal_offsets=offset)
The D-Wave system used for this example is an Advantage that has couplers between active qubits 30 and 2940. Select a suitable embedding for the QPU you run examples on.
anneal_schedule#
Introduces variations to the global anneal schedule.
For a reverse anneal, use this parameter with the initial_state and reinitialize_state parameters.
For the fast-anneal protocol, set the fast_anneal
to True
.
An anneal schedule variation is defined by a series of pairs of floating-point numbers identifying points in the schedule at which to change slope. The first element in the pair is time \(t\) and the second is anneal fraction \(s\) in the range [0,1]. The resulting schedule is the piecewise-linear curve that connects the provided points.
Time is specified in microseconds. For standard anneals, input times are rounded to two decimal places (a granularity of 0.01 \(\mu s\)); for the fast-anneal protocol, you can specify times to a maximum resolution of 5%.[3]
For the fast-anneal protocol, if you are interested in annealing times of
about 2 ns ([[0.0, 0.0], [0.002, 1.0]]
), for example, specify no more
than six decimal places for the time (a granularity of 1 ps), while for
anneals of about 20 ns, specify no more than five decimal places (a
granularity of 10 ps). Specifying additional decimal places is not
meaningful.
The following rules apply to the set of anneal schedule points provided:
Time \(t\) must increase for all points in the schedule.
For forward annealing, the first point must be \((0, 0)\).
For reverse annealing, the anneal fraction \(s\) must start and end at \(s = 1\).
In the final point, anneal fraction \(s\) must equal 1 and time \(t\) must not exceed the maximum value in the annealing_time_range property.
The number of points must be \(\geq 2\).
The upper bound on the number of points is system-dependent; check the max_anneal_schedule_points property. For reverse annealing, the maximum number of points allowed is one more than the number given by this property.
The steepest slope of any curve segment, \(\frac{s_i - s_{i-1}}{t_i - t_{i-1}}\) must not be greater than the inverse of the minimum anneal time. For example, for a QPU with a annealing_time_range value of
[ 0.5, 2000 ]
, the minimum anneal time is 0.5 \(\mu s\), so the steepest supported slope is 2 \(\mu s^{-1}\). If you want a section of the piecewise-linear curve that starts at time point \(t_4 = 30 \mu s\) to increase from \(s_4=0.7\) to \(s_5=0.8\), this example QPU supports a schedule that contains \(t_5 = 30.06 \mu s\) ([... [30.0, 0.7], [30.06, 0.8], ...]
), which has a maximum slope of \(1 \frac{2}{3}\), but not one that contains \(t_5 = 30.04 \mu s\) ([... [30.0, 0.7], [30.04, 0.8], ...]
), which has a maximum slope of \(2 \frac{1}{2}\).Note that the I/O system that delivers the anneal waveform—the \(\Phi_{\rm CCJJ}(s)\) term of equation (3) in the QPU Solver Datasheet guide—to a QPU limits bandwidth with a 30 MHz low-pass filter for Advantage and Advantage2 systems; if you configure a too-rapidly changing curve, even with supported slopes, expect distorted values of h and J for your problem.
Only two points can be specified when fast_anneal is
True
.
Default anneal schedules are described in the QPU-specific anneal schedules documents.
Relevant Properties#
max_anneal_schedule_points shows the maximum number of points permitted in an anneal schedule.
default_annealing_time shows the default annealing time for the solver.
annealing_time_range and fast_anneal_time_range define the limits of the allowable time range for the anneal schedule.
Interacts with Parameters#
annealing_time and anneal_schedule parameters are mutually exclusive.
anneal_schedule (or annealing_time), readout_thermalization, num_reads (samples), and programming_thermalization values taken together must meet the limitations specified in problem_run_duration_range.
anneal_schedule can have only two points for the fast-anneal protocol (when fast_anneal is set to
True
).
Example#
This illustrative example configures a reverse-anneal schedule on a random native problem.
>>> from dwave.system import DWaveSampler
>>> import random
>>> qpu = DWaveSampler()
>>> J = {coupler: random.choice([-1, 1]) for coupler in qpu.edgelist}
>>> initial = {qubit: random.randint(0, 1) for qubit in qpu.nodelist}
>>> reverse_schedule = [[0.0, 1.0], [5, 0.45], [99, 0.45], [100, 1.0]]
>>> reverse_anneal_params = dict(anneal_schedule=reverse_schedule,
... initial_state=initial,
... reinitialize_state=True)
>>> sampleset = qpu.sample_ising({}, J, num_reads=1000, **reverse_anneal_params)
annealing_time#
Sets the duration of quantum annealing time, per read.
Time is specified in microseconds. For standard anneals, input times are rounded to two decimal places (a granularity of 0.01 \(\mu s\)); for the fast-anneal protocol, you can specify times to a maximum resolution of 5%.[4]
For the fast-anneal protocol, if you are interested in annealing times of
about 2 ns ([[0.0, 0.0], [0.002, 1.0]]
), for example, specify no more
than six decimal places for the time (a granularity of 1 ps), while for
anneals of about 20 ns, specify no more than five decimal places (a
granularity of 10 ps). Specifying additional decimal places is not
meaningful.
This value populates the qpu_anneal_time_per_sample field returned in the timing structure. Supported values are positive floating-point numbers.
The allowed range of times depends on the annealing protocol: standard or fast (activated with fast_anneal).
Default value is shown by default_annealing_time.
Relevant Properties#
annealing_time_range defines the supported range of valid times for the standard-annealing protocol.
fast_anneal_time_range defines the supported range of valid times for the fast-anneal protocol.
Interacts with Parameters#
annealing_time and anneal_schedule parameters are mutually exclusive. Configuring a value of
T
for annealing_time is equivalent to configuringanneal_schedule=[[0, 0], [T, 1]]
.annealing_time (or anneal_schedule), readout_thermalization, num_reads (samples), and programming_thermalization values taken together must meet the limitations specified in problem_run_duration_range.
fast_anneal switches the allowable range between annealing_time_range (default) and fast_anneal_time_range ranges.
Example#
This illustrative example configures the anneal time on a random native problem.
>>> from dwave.system import DWaveSampler
>>> import random
>>> qpu = DWaveSampler()
>>> J = {coupler: random.choice([-1, 1]) for coupler in qpu.edgelist}
>>> long_time = qpu.properties["annealing_time_range"][1]
>>> sampleset = qpu.sample_ising({}, J, num_reads=10, annealing_time=long_time)
answer_mode#
Indicates how answers are returned from the solver[5]. Supported values are,
raw
: Answers returned individually in the order they were read from the solver. Use this setting if the returned time sequences are an important part of the solution data.The answer contains two fields, solutions and energies. The solutions field is a list of lists; the inner lists all have length num_qubits and entries from \({-1, +1}\) for Ising problems or \({0, 1}\) for QUBO problems. Values of \(3\) denote unused or inactive qubits. The energies field contains the energy of each corresponding solution.
histogram
: Answers returned as a histogram sorted in order of increasing energies. Answers contain the solutions and energies fields, but solutions are unique and sorted in increasing-energy order. Duplicate answers are merged and include a num_occurrences field, which indicates how many times each solution appeared.
Ocean tools receive these answers from SAPI and process them. For example,
if you submit a problem using Ocean’s
EmbeddingComposite
, the answer is mapped
from qubits to the logical variables of your problem.
Default value is histogram
.
Interacts with Parameters#
initial_state (which sets the anneal schedule to a reverse anneal) returns answers in
raw
mode unless you explicitly set the answer mode tohistogram
.max_answers specifies the maximum number of answers.
num_reads defines the number of reads.
Example#
This illustrative example sets the answer format to raw
.
>>> from dwave.system import DWaveSampler, EmbeddingComposite
>>> J = {('s1', 's2'): 0.5, ('s1', 's3'): 0.5, ('s2', 's3'): 0.5}
>>> sampleset = EmbeddingComposite(DWaveSampler()).sample_ising({}, J,
... num_reads=100, answer_mode='raw')
auto_scale#
Indicates whether \(h\) and \(J\) values are rescaled:
True
: \(h\) and \(J\) values in the problem are rescaled to use as much of the range of \(h\) (h_range) and the range of extended \(J\) (extended_j_range) as possible; furthermore, the \(h\) and \(J\) values need not lie within the solver’s range of \(h\) and extended \(J\), but must still be finite.False
: \(h\) and \(J\) values in the problem are used as is. If the \(h\) and \(J\) values are outside the ranges of \(h\) (h_range) and the extended \(J\) (extended_j_range) of the solver, problem submission fails.
By default, this parameter is enabled.
Auto-scaling works as follows. Each QPU has an allowed range of values for the biases and strengths of qubits and couplers. Unless you explicitly disable auto-scaling, the values defined in your problem are adjusted to fit the entire available range and the permitted per-qubit and per-group coupling ranges specified by the per_qubit_coupling_range (for Advantage solvers) or per_group_coupling_range (for Advantage2 solvers) properties, respectively.
The auto-scaled \(h\) and \(J\) values are determined by dividing the \(h\) and \(J\) values in the problem by a positive (non-zero) factor defined as follows:
The coupling_limit element takes into consideration the per_qubit_coupling_range (for Advantage solvers) and per_group_coupling_range (for Advantage2 solvers) properties as follows:
Advantage
\[ \begin{align}\begin{aligned}coupling\_limit = \max \bigl\{& \max \left( \frac{\max (total\_J\_per\_qubit)}{\max (per\_qubit\_coupling\_range)}, 0 \right),\\ & \max \left( \frac{\min (total\_J\_per\_qubit)}{\min (per\_qubit\_coupling\_range)}, 0 \right) \bigr\}\end{aligned}\end{align} \]Advantage2
\[ \begin{align}\begin{aligned}coupling\_limit = \max \bigl\{& \max \left( \frac{\max (total\_J\_per\_group)}{\max (per\_group\_coupling\_range)}, 0 \right),\\ & \max \left( \frac{\min (total\_J\_per\_group)}{\min (per\_group\_coupling\_range)}, 0 \right) \bigr\}\end{aligned}\end{align} \]
where the total_J_per_qubit and total_J_per_group elements represent the total and per-group total, respectively, of the coupling strength applied to each qubit.
Ocean software’s samplers often have a chain strength parameter: because the QPU’s qubits are sparsely connected, problem variables might be represented by more than one physical qubit (a “chain” of qubits), strongly coupled so as to return the same value. Typically, chains are generated by minor-embedding tools such as Ocean’s minorminer. Setting a value for chain strength determines the values set for the couplers used in forming these chains. When using auto-scaling, the \(J\) values of chain couplers are scaled together with the given or converted \(J\) values. Similarly, if you disable auto-scaling, any chain strength you specify must result in coupling values within the allowed range for the QPU.
Problems specified in QUBO form are always converted to Ising for the submitted QMIs. When using auto-scaling, the converted problem’s \(h\) and \(J\) values are rescaled as described above. Note that bias values in the converted form, which have a dependency on the number of quadratic interactions in the QUBO, can be larger than the maximum bias of the original form. For example, the four-variable QUBO below, which has a maximum bias value of 2,
when converted to an Ising model, has a bias with a value greater than 2.0, \(h_1=2.375\), as shown below:
>>> import dimod
>>> Q = {(1, 1): 2, (2, 2): 1.5, (3, 3): -0.5, (4, 4): -1.0,
... (1, 2): 2, (1, 3): 1.5, (1, 4): 2}
>>> dimod.qubo_to_ising(Q)
({1: 2.375, 2: 1.25, 3: 0.125, 4: 0.0}, {(1, 2): 0.5, (1, 3): 0.375, (1, 4): 0.5}, 2.375)
Interacts with Parameters#
auto_scale cannot be used with flux_biases.
Example#
The example checks a QPU’s range of \(h\) and \(J\) before submitting a
two-variable Ising problem to a QPU. The auto_scale parameter is
implicitly True for the DWaveSampler
class, so
the \(h\) and \(J\) values are automatically rescaled by
\(\frac{-7.2}{-4} = 1.8\).
>>> from dwave.system import DWaveSampler, EmbeddingComposite
>>> sampler = EmbeddingComposite(DWaveSampler())
...
>>> sampler.child.properties['extended_j_range']
[-2.0, 1.0]
>>> sampler.child.properties['h_range']
[-4.0, 4.0]
>>> h = {'a': -7.2, 'b': 2.3}
>>> J = {('a', 'b'): 1.5}
>>> sampleset = sampler.sample_ising(h, J)
fast_anneal#
When set to True
, the fast-anneal protocol is
used instead of the standard anneal.
By default, standard anneal is used (fast_anneal=False
).
Relevant Properties#
fast_anneal_time_range defines the supported range of valid times when using the fast-anneal protocol.
Interacts with Parameters#
annealing_time (or anneal_schedule), readout_thermalization, num_reads (samples), and programming_thermalization values taken together must meet the limitations specified in problem_run_duration_range.
h values and Q diagonal values must be zero when
fast_anneal=True
(likewise, you cannot configure the h_gain_schedule parameter).anneal_schedule cannot specify more than two points when
fast_anneal=True
(which means you also cannot use annealing features such as pause or reverse anneal).
Example#
This example samples a ferromagnetic chain for an anneal time of 8 ns.
>>> from dwave.system import DWaveSampler, EmbeddingComposite
>>> qpu_advantage2 = DWaveSampler(solver={"topology__type": "zephyr"})
>>> sampler = EmbeddingComposite(qpu_advantage2)
>>> h = 0
>>> J = {(i, i + 1): -1.5 for i in range(20)}
>>> sampleset = sampler.sample_ising(h, J, num_reads=1000,
... fast_anneal=True, annealing_time=0.008)
flux_biases#
List of flux-bias offset values, in units of \(\Phi_0\), with which to refine calibration.
Ideally, qubits with \(h_i=0\) should have equal probability of annealing to classical states \(+1\) or \(-1\) until coupled to a biased qubit. However, non-idealities in QPU calibration and coupling to its environment result in some asymmetry. This asymmetry typically increases under strong coupling (such as when the extended_j_range is used) for chains. While the effect may be minor for many optimization problems, for others, such as material simulation, it may be significant. Flux biases can be used to refine the standard calibration as described in section Calibration Refinement of the QPU Solver Datasheet guide.
Flux biases are also useful as a way of biasing qubits indirectly when you cannot set a bias on the qubit, as in the case of fast anneal.
Provide an array of flux-bias offset values for all qubits, working or not.
Use 0 for no offset. Note that by convention the sign for flux biases is
opposite to that for linear biases h. Ocean software provides
tools for conversions between equivalent values of h and flux-bias
offsets: fluxbias_to_h()
and
h_to_fluxbias()
.
Default is no flux-bias offsets.
The applied flux bias appears in Hamiltonian equation (3) as a term \(I_p \phi_{\rm flux bias} \sigma_z\) that grows with the applied problem energy as \(\sqrt{B(s)}\). Although the dynamics of h and flux bias (constant in time) differ, equivalence at a specific point in the anneal is valid under some assumptions. Ocean software provides conversion functions between h and flux biases.
See this example in the D-Wave Problem-Solving Handbook for more-detailed usage information.
Relevant Properties#
extended_j_range defines the extended range of values possible for the coupling strengths.
per_qubit_coupling_range defines the coupling range permitted per qubit for Advantage solvers.
per_group_coupling_range defines the coupling range permitted per group of qubits for Advantage2 solvers.
flux_drift_compensation indicates whether the D-Wave system compensates for flux drift.
Interacts with Parameters#
Cannot be used with auto_scale.
Example#
This example sets flux-bias values for a two-qubit chain in an illustrative Ising problem.
>>> from dwave.system import FixedEmbeddingComposite, DWaveSampler
>>> qpu = DWaveSampler(solver={'topology__type': 'pegasus'})
>>> h = {0: 0, 1: 0.9, 2: -1}
>>> J = {(0, 1): -1, (1, 2): -1}
>>> embedding = {0: [30], 1: [45, 46], 2: [31]}
>>> fb = [0]*qpu.properties['num_qubits']
>>> fb[45] = -0.00005
>>> fb[46] = -0.00005
>>> sampleset = FixedEmbeddingComposite(qpu, embedding).sample_ising(h, J,
... num_reads=8000, flux_biases=fb)
>>> print(f"{sampleset.record.energy}\n{sampleset.record.num_occurrences}")
[-2.1 -1.9 -1.9 0.1 0.1]
[ 720 3047 4230 2 1]
>>> fb[45] = +0.00005
>>> fb[46] = +0.00005
>>> sampleset = FixedEmbeddingComposite(qpu, embedding).sample_ising(h, J,
... num_reads=8000, flux_biases=fb)
>>> print(f"{sampleset.record.energy}\n{sampleset.record.num_occurrences}")
[-2.1 -1.9 -1.9 -0.1 0.1 0.1]
[3461 2546 1987 2 1 3]
The D-Wave system used for this example is an Advantage that has particular couplers. Select a suitable embedding for the QPU you run examples on.
flux_drift_compensation#
Boolean flag indicating whether the D-Wave system compensates for flux drift. The procedure it follows to do so is described in detail in the Error-Correction Features section of the QPU Solver Datasheet guide.
flux_drift_compensation=True
: Compensate for flux drift.flux_drift_compensation=False
: Do not compensate for flux drift.
Default is to compensate for flux drift.
Interacts with Parameters#
flux_biases enables you to apply flux-bias offsets manually, which you may want to do if you disable this parameter.
Example#
This example disables flux-drift compensation.
>>> from dwave.system import EmbeddingComposite, DWaveSampler
>>> sampler = EmbeddingComposite(DWaveSampler())
>>> J = {('s1', 's2'): 0.5, ('s1', 's3'): 0.5, ('s2', 's3'): 0.5}
>>> sampleset = sampler.sample_ising({}, J, num_reads=100,
... flux_drift_compensation=False)
h_gain_schedule#
Sets a time-dependent gain for linear coefficients (qubit biases, see the h parameter) in the Hamiltonian.
This parameter enables you to specify the \(g(t)\) function in the Hamiltonian,
where \({\hat\sigma_{x,z}^{(i)}}\) are Pauli matrices operating on a qubit \(q_i\) and \(h_i\) and \(J_{i,j}\) are the qubit biases and coupling strengths.
This time-dependent gain, \(g(t)\), is specified, similarly to the anneal_schedule parameter, by a series of pairs of floating-point numbers identifying points in the schedule at which to change the gain applied to h. The first element in the pair is time, \(t\) in microseconds with a resolution of 0.01 \(\mu s\); the second, the unitless \(g\) in the range h_gain_schedule_range. The resulting time-dependent gain is the piecewise-linear curve that connects the provided points over the same range of times as the anneal_schedule.
The following rules apply to the set of gain points provided:
Time \(t\), in microseconds, must increase for all points in the schedule.
The first point of time must be zero, \(t=0.0\).
The last point of time must match the last time in the anneal_schedule or the annealing_time.
The number of points must be \(\geq 2\).
The steepest slope of any curve segment, \(\frac{g_i - g_{i-1}}{t_i - t_{i-1}}\), must be within the bounds supported by the selected QPU.[6] Note that the I/O system that delivers the h-controlling waveform—the \(\Phi^x_i(s)\) term of equation (3) in the QPU Solver Datasheet guide—to a QPU limits bandwidth using a low-pass filter with a cutoff frequency of 3 MHz for Advantage and 30 MHz for Advantage2 systems; if you configure a too-rapidly changing curve, even within the supported bounds, expect distorted values of h for your problem.
To see the supported slope for a particular QPU, submit a test problem with slopes that are expected to violate any limitations; you can then read the range of supported slopes in the returned error message. (Your Leap account is not charged for rejected problems.)
Supported slopes are typically under \(\frac{G_{max} - G_{min}}{0.02}\),
where \(G_{min}\) and \(G_{max}\) here stand for the range limits
of the time-dependent gain for the QPU. For example, for a QPU with
h_gain_schedule_range value of [-3, 3]
, a slope above
\(\frac{3 - (-3)}{0.02} = 300\), which occurs for a schedule that
contains [... [10.0, 0], [10.01, 3], ...]
, is likely to return an
error message with the maximum allowed slope.
Default \(g(t)\), when left unspecified, is 1, which can be explicitly coded as
h_gain_schedule=[[0,1],[t_final,1]]
where t_final is the requested annealing time.
Relevant Properties#
h_gain_schedule_range defines the range of the time-dependent gain values permitted for the solver.
Note
In conjunction with the auto_scale parameter, the h_gain_schedule parameter enables you to extend the range of your submitted problem’s linear coefficients (h) beyond the advertised h_range. Such use is not recommended for standard problem solving: the QPU is calibrated for linearity only within the advertised h_range and j_range. Increased integrated control errors (ICE) are expected outside that range.
If you configure
auto_scale=False
when using this parameter, ensure that \(\max_i(h\_gain*h_i)\) and \(\min_i(h\_gain*h_i)\) are within h_range.max_anneal_schedule_points defines the maximum number of anneal-schedule points permitted.
max_h_gain_schedule_points defines the maximum number of gain changes allowed.
Interacts with Parameters#
h defines the linear biases for the problem.
anneal_schedule defines the anneal schedule.
Cannot be used with the fast-anneal protocol (activated by the fast_anneal parameter).
Example#
This illustrative example sets an h-gain schedule.
>>> from dwave.system import EmbeddingComposite, DWaveSampler
>>> sampler = EmbeddingComposite(DWaveSampler())
>>> h = {'s1': 1, 's2': 1.5, 's3': -0.75}
>>> J = {('s1', 's2'): 0.5, ('s1', 's3'): 0.5, ('s2', 's3'): 0.5}
>>> anneal_schedule = [[0.0, 0.0], [40.0, 0.4], [140.0, 0.4], [150, 1.0]]
>>> h_schedule = [[0.0, 1], [40.0, 1], [140.0, 2], [143.0, 0], [150, 0]]
>>> sampleset = sampler.sample_ising(h, J, num_reads=500,
... anneal_schedule=anneal_schedule,
... h_gain_schedule=h_schedule)
initial_state#
Initial state to which the system is set for reverse annealing. Specifies the initial classical state of all qubits.
Provide (qubit, state) pairs, where qubit is the qubit index, i, and state is:
-1 or 1: Ising problems, active qubits
0 or 1: QUBO problems, active qubits
3: Unused or inactive qubits
Interacts with Parameters#
anneal_schedule defines the anneal schedule. When initial_state is provided, indicates that the requested anneal schedule change is a reverse anneal.
answer_mode is
raw
by default for reverse anneals.reinitialize_state reinitializes for each anneal. Note that this impacts timing.
Cannot be used with the fast-anneal protocol (activated by the fast_anneal parameter).
Example#
This illustrative example configures a reverse-anneal schedule on a random native problem.
>>> from dwave.system import DWaveSampler
>>> import random
>>> qpu = DWaveSampler()
>>> J = {coupler: random.choice([-1, 1]) for coupler in qpu.edgelist}
>>> initial = {qubit: random.randint(0, 1) for qubit in qpu.nodelist}
>>> reverse_schedule = [[0.0, 1.0], [5, 0.45], [99, 0.45], [100, 1.0]]
>>> reverse_anneal_params = dict(anneal_schedule=reverse_schedule,
... initial_state=initial,
... reinitialize_state=True)
>>> sampleset = qpu.sample_ising({}, J, num_reads=1000, **reverse_anneal_params)
max_answers#
Specifies the maximum number of answers returned from the solver. Must be an integer greater than 0.
If answer_mode is
histogram
: Total number of distinct answers. Because answers in this mode are sorted by energy, these are the bestmax_answers
answers.If answer_mode is
raw
: Limits the returned values to the first max_answers of num_reads samples. In this mode, max_answers should never be more than num_reads.
Default value is num_reads.
Interacts with Parameters#
num_reads defines the maximum number of requested answers.
answer_mode defines the answer mode.
Example#
This illustrative example resulted in fewer samples than the configured num_reads.
>>> from dwave.system import EmbeddingComposite, DWaveSampler
>>> sampler = EmbeddingComposite(DWaveSampler())
>>> J = {('s1', 's2'): 0.5, ('s1', 's3'): 0.5, ('s2', 's3'): 0.5}
>>> sampleset = sampler.sample_ising({}, J, num_reads=1000,
... max_answers=5)
>>> print(sampleset)
s1 s2 s3 energy num_oc. chain_.
0 +1 -1 -1 -0.5 202 0.0
1 -1 -1 +1 -0.5 132 0.0
2 +1 -1 +1 -0.5 112 0.0
3 -1 +1 -1 -0.5 248 0.0
4 -1 +1 +1 -0.5 95 0.0
['SPIN', 5 rows, 789 samples, 3 variables]
num_reads#
Indicates the number of states (output solutions) to read[7] from the solver. Must be a positive integer in the range given by the num_reads_range solver property.
Terms synonymous to reads are anneals and samples.
Default value is 1
.
Interacts with Parameters#
max_answers sets the maximum number of answers to be returned from the solver.
anneal_schedule or annealing_time, readout_thermalization, num_reads (samples), and programming_thermalization values taken together must meet the limitations specified in problem_run_duration_range.
Example#
This illustrative example requests 1250 samples.
>>> from dwave.system import EmbeddingComposite, DWaveSampler
>>> sampler = EmbeddingComposite(DWaveSampler())
>>> Q = {('x1', 'x2'): 1, ('x1', 'z'): -2, ('x2', 'z'): -2, ('z', 'z'): 3}
>>> sampleset = sampler.sample_qubo(Q, answer_mode='raw', num_reads=1250)
>>> len(sampleset)
1250
num_spin_reversal_transforms#
This parameter is obsolete.
For Spin-Reversal (Gauge) Transforms, use
Ocean software’s
SpinReversalTransformComposite
composite
instead.
programming_thermalization#
Sets the time, in microseconds with a resolution of 0.01 \(\mu s\), to wait after programming the QPU for it to cool back to base temperature (i.e., post-programming thermalization time). Lower values accelerate solving at the expense of solution quality. Supported values are positive floating-point numbers. This value contributes to the total qpu_programming_time, which is returned by SAPI in the timing structure.
Default value for a solver is given in the default_programming_thermalization property.
Relevant Properties#
programming_thermalization_range defines the range of allowed values.
Interacts with Parameters#
anneal_schedule or annealing_time, readout_thermalization, num_reads (samples), and programming_thermalization values taken together must meet the limitations specified in problem_run_duration_range.
Example#
This illustrative example sets a value of half the supported maximum.
>>> from dwave.system import EmbeddingComposite, DWaveSampler
>>> sampler = EmbeddingComposite(DWaveSampler())
>>> Q = {('x1', 'x2'): 1, ('x1', 'z'): -2, ('x2', 'z'): -2, ('z', 'z'): 3}
>>> pt = int(sampler.child.properties["programming_thermalization_range"][1]/2)
>>> sampleset = sampler.sample_qubo(Q, num_reads=10,
... programming_thermalization=pt)
readout_thermalization#
Sets the time, in microseconds with a resolution of 0.01 \(\mu s\), to wait after each state is read from the QPU for it to cool back to base temperature (i.e., post-readout thermalization time). This value contributes to the qpu_delay_time_per_sample time returned by SAPI in the timing structure. Supported values are positive floating-point numbers.
Default value for a solver is given in the default_readout_thermalization property.
Relevant Properties#
readout_thermalization_range defines the range of allowed values.
Interacts with Parameters#
anneal_schedule or annealing_time, readout_thermalization, num_reads (samples), and programming_thermalization values taken together must meet the limitations specified in problem_run_duration_range.
Example#
This illustrative example sets a value of half the supported maximum.
>>> from dwave.system import EmbeddingComposite, DWaveSampler
>>> sampler = EmbeddingComposite(DWaveSampler())
>>> Q = {('x1', 'x2'): 1, ('x1', 'z'): -2, ('x2', 'z'): -2, ('z', 'z'): 3}
>>> rt = int(sampler.child.properties["readout_thermalization_range"][1]/2)
>>> sampleset = sampler.sample_qubo(Q, num_reads=10,
... readout_thermalization=rt)
reduce_intersample_correlation#
Reduces sample-to-sample correlations caused by the spin-bath polarization effect[8] by adding a delay between reads.
See the QPU Solver Datasheet for more information on this effect.
Boolean flag indicating whether the system adds a delay.
reduce_intersample_correlation=True
: Adds delay.reduce_intersample_correlation=False
(default): Does not add delay.
Important
Enabling this parameter drastically increases problem run times. To avoid exceeding the maximum problem run time configured for your system, limit the number of reads when using this feature. For more information on timing, see the QPU Solver Datasheet guide.
Default is to not add delay between reads.
Example#
This illustrative example configures a delay between reads.
>>> from dwave.system import EmbeddingComposite, DWaveSampler
>>> sampler = EmbeddingComposite(DWaveSampler())
>>> Q = {('x1', 'x2'): 1, ('x1', 'z'): -2, ('x2', 'z'): -2, ('z', 'z'): 3}
>>> sampleset = sampler.sample_qubo(Q, num_reads=10,
... reduce_intersample_correlation=True)
reinitialize_state#
When using the reverse annealing feature, you must supply the initial state to which the system is set; see the initial_state parameter. If multiple reads are requested in a single call to the Solver API, you have two options for the starting state of the system. These are controlled by the reinitialize_state Boolean parameter:
reinitialize_state=True
: Reinitialize to the specified initial state for every anneal-readout cycle. Each anneal begins from the state given in the initial_state parameter. The amount of time required to reinitialize varies by system; see the problem_timing_data property for this information.reinitialize_state=False
: Initialize only at the beginning, before the first anneal cycle. Each anneal (after the first) is initialized from the final state of the qubits after the previous cycle. Be aware that even if this parameter is disabled, reverse annealing adds a small amount of time (\(\approx 10 \ \mu s\)) for each read.
See also anneal_schedule.
Default is to reinitialize to the specified initial state for every anneal in reverse-anneal submissions.
Interacts with Parameters#
anneal_schedule defines the anneal schedule.
anneal_schedule or annealing_time, readout_thermalization, num_reads (samples), and programming_thermalization values taken together must meet the limitations specified in problem_run_duration_range.
Cannot be used with the fast-anneal protocol (activated by the fast_anneal parameter).
Example#
This illustrative example configures a reverse-anneal schedule on a random native problem with each anneal initialized from the final state of the previous cycle.
>>> from dwave.system import DWaveSampler
>>> import random
>>> qpu = DWaveSampler()
>>> J = {coupler: random.choice([-1, 1]) for coupler in qpu.edgelist}
>>> initial = {qubit: random.randint(0, 1) for qubit in qpu.nodelist}
>>> reverse_schedule = [[0.0, 1.0], [5, 0.45], [99, 0.45], [100, 1.0]]
>>> reverse_anneal_params = dict(anneal_schedule=reverse_schedule,
... initial_state=initial,
... reinitialize_state=False)
>>> sampleset = qpu.sample_ising({}, J, num_reads=1000, **reverse_anneal_params)
time_limit#
Specifies the maximum runtime, in seconds, the solver is allowed to work on the given problem. Can be a float or integer.
Default value is problem dependent.
Attention
The Leap hybrid nonlinear-program solver does not prevent you from setting
a time_limit smaller than the minimum time estimated by the Ocean
sampler's
estimated_min_time_limit()
method; however, runtime (and charge time) is not guaranteed to be shorter
than the estimated time.
Relevant Properties#
minimum_time_limit defines the range of supported values for a given BQM or DQM problem.
minimum_time_limit_s defines the minimum supported value for any given CQM problem. The specified time_limit cannot be lower than the smaller of this value and the calculated default runtime for the submitted problem.
For CQM solvers, num_biases_multiplier, num_constraints_multiplier, and num_variables_multiplier define multipliers used in the internal calculation of the default run time for a given problem. The specified time_limit cannot be lower than the smaller of the calculated default runtime for the submitted problem and minimum_time_limit_s.
For nonlinear-program solvers, state_size_multiplier, num_nodes_multiplier, num_nodes_state_size_multiplier, and time_constant are used in the internal estimate of the problem’s minimum runtime.
Example#
This illustrative example configures a time limit of 6 seconds.
>>> from dwave.system import LeapHybridSampler
>>> Q = {('x1', 'x2'): 1, ('x1', 'z'): -2, ('x2', 'z'): -2, ('z', 'z'): 3}
>>> sampleset = LeapHybridSampler().sample_qubo(Q, time_limit=6)