dwave.cloud.client.Client.get_solvers

Client.get_solvers(refresh=False, order_by='avg_load', **filters)

Return a filtered list of solvers handled by this client.

Parameters:
  • refresh (bool, default=False) – Force refresh of cached list of solvers/properties.
  • order_by (callable/str/None, default='avg_load') –

    Solver sorting key function (or Solver attribute/item dot-separated path). By default, solvers are sorted by average load. To explicitly not sort the solvers (and use the API-returned order), set order_by=None.

    Signature of the key callable is:

    key :: (Solver s, Ord k) => s -> k
    

    Basic structure of the key string path is:

    "-"? (attr|item) ( "." (attr|item) )*
    

    For example, to use solver property named max_anneal_schedule_points, available in Solver.properties dict, you can either specify a callable key:

    key=lambda solver: solver.properties['max_anneal_schedule_points']
    

    or, you can use a short string path based key:

    key='properties.max_anneal_schedule_points'
    

    Solver derived properties, available as Solver properties can also be used (e.g. num_active_qubits, online, avg_load, etc).

    Ascending sort order is implied, unless the key string path does not start with -, in which case descending sort is used.

    Note: the sort used for ordering solvers by key is stable, meaning that if multiple solvers have the same value for the key, their relative order is preserved, and effectively they are in the same order as returned by the API.

    Note: solvers with None for key appear last in the list of solvers. When providing a key callable, ensure all values returned are of the same type (particularly in Python 3). For solvers with undefined key value, return None.

  • **filters – See Filtering forms and Operators below.

Solver filters are defined, similarly to Django QuerySet filters, with keyword arguments of form <key1>__…__<keyN>[__<operator>]=<value>. Each <operator> is a predicate (boolean) function that acts on two arguments: value of feature <name> (described with keys path <key1.key2…keyN>) and the required <value>.

Feature <name> can be:

  1. a derived solver property, available as an identically named Solver’s property (name, qpu, software, online, num_active_qubits, avg_load)
  2. a solver parameter, available in Solver.parameters
  3. a solver property, available in Solver.properties
  4. a path describing a property in nested dictionaries

Filtering forms are:

  • <derived_property>__<operator> (object <value>)

  • <derived_property> (bool)

    This form ensures the value of solver’s property bound to derived_property, after applying operator equals the value. The default operator is eq.

    For example:

    >>> client.get_solvers(avg_load__gt=0.5)
    

    but also:

    >>> client.get_solvers(online=True)
    >>> # identical to:
    >>> client.get_solvers(online__eq=True)
    
  • <parameter>__<operator> (object <value>)

  • <parameter> (bool)

    This form ensures that the solver supports parameter. General operator form can be used but usually does not make sense for parameters, since values are human-readable descriptions. The default operator is available.

    Example:

    >>> client.get_solvers(flux_biases=True)
    >>> # identical to:
    >>> client.get_solvers(flux_biases__available=True)
    
  • <property>__<operator> (object <value>)

  • <property> (bool)

    This form ensures the value of the solver’s property, after applying operator equals the righthand side value. The default operator is eq.

Note: if a non-existing parameter/property name/key given, the default operator is eq.

Operators are:

  • available (<name>: str, <value>: bool):
    Test availability of <name> feature.
  • eq, lt, lte, gt, gte (<name>: str, <value>: any):
    Standard relational operators that compare feature <name> value with <value>.
  • regex (<name>: str, <value>: str):
    Test regular expression matching feature value.
  • covers (<name>: str, <value>: single value or range expressed as 2-tuple/list):
    Test feature <name> value (which should be a range) covers a given value or a subrange.
  • within (<name>: str, <value>: range expressed as 2-tuple/list):
    Test feature <name> value (which can be a single value or a range) is within a given range.
  • in (<name>: str, <value>: container type):
    Test feature <name> value is in <value> container.
  • contains (<name>: str, <value>: any):
    Test feature <name> value (container type) contains <value>.
  • issubset (<name>: str, <value>: container type):
    Test feature <name> value (container type) is a subset of <value>.
  • issuperset (<name>: str, <value>: container type):
    Test feature <name> value (container type) is a superset of <value>.

Derived properies are:

  • name (str): Solver name/id.
  • qpu (bool): Is solver QPU based?
  • software (bool): Is solver software based?
  • online (bool, default=True): Is solver online?
  • num_active_qubits (int): Number of active qubits. Less then or equal to num_qubits.
  • avg_load (float): Solver’s average load (similar to Unix load average).

Common solver parameters are:

  • flux_biases: Should solver accept flux biases?
  • anneal_schedule: Should solver accept anneal schedule?

Common solver properties are:

  • num_qubits (int): Number of qubits available.
  • vfyc (bool): Should solver work on “virtual full-yield chip”?
  • max_anneal_schedule_points (int): Piecewise linear annealing schedule points.
  • h_range ([int,int]), j_range ([int,int]): Biases/couplings values range.
  • num_reads_range ([int,int]): Range of allowed values for num_reads parameter.
Returns:List of all solvers that satisfy the conditions.
Return type:list[Solver]

Note

Client subclasses (e.g. dwave.cloud.qpu.Client or dwave.cloud.sw.Client) already filter solvers by resource type, so for qpu and software filters to have effect, call get_solvers() on base class Client.

Examples:

client.get_solvers(
    num_qubits__gt=2000,                # we need more than 2000 qubits
    num_qubits__lt=4000,                # ... but fewer than 4000 qubits
    num_qubits__within=(2000, 4000),    # an alternative to the previous two lines
    num_active_qubits=1089,             # we want a particular number of active qubits
    vfyc=True,                          # we require a fully yielded Chimera
    vfyc__in=[False, None],             # inverse of the previous filter
    vfyc__available=False,              # we want solvers that do not advertize the vfyc property
    anneal_schedule=True,               # we need support for custom anneal schedule
    max_anneal_schedule_points__gte=4,  # we need at least 4 points for our anneal schedule
    num_reads_range__covers=1000,       # our solver must support returning 1000 reads
    extended_j_range__covers=[-2, 2],   # we need extended J range to contain subrange [-2,2]
    couplers__contains=[0, 128],        # coupler (edge between) qubits (0,128) must exist
    couplers__issuperset=[[0,128], [0,4]],
                                        # two couplers required: (0,128) and (0,4)
    qubits__issuperset={0, 4, 215},     # qubits 0, 4 and 215 must exist
    supported_problem_types__issubset={'ising', 'qubo'},
                                        # require Ising, QUBO or both to be supported
    name='DW_2000Q_3',                  # full solver name/ID match
    name__regex='.*2000.*',             # partial/regex-based solver name match
    chip_id__regex='DW_.*',             # chip ID prefix must be DW_
    topology__type__eq="chimera"        # topology.type must be chimera
)