DynexSampler

Submit annealing jobs and retrieve results from the Dynex platform

DynexSampler

DynexSampler is the core interface for running quantum annealing computations on the Dynex platform. It accepts any model type (BQM, CQM, DQM), submits jobs via gRPC, and returns a dimod SampleSet.

from dynex import DynexSampler

Constructor

DynexSampler(
    model,                      # dynex.BQM | CQM | DQM
    config: DynexConfig,        # Backend and credentials
    description: str = "",      # Job description (shown in dashboard)
    logging: bool = True,       # Enable SDK logging output
)

Parameters

model · BQM | CQM | DQM · required

The problem model to sample. Must be a Dynex model wrapper — not a raw dimod object.

config · DynexConfig · required

Configuration object specifying the compute backend, credentials, and SDK settings.

description · str

Human-readable job description. Appears in the Dynex job dashboard and network explorer.

logging · bool · default: "True"

Whether to emit SDK log messages during sampling. Set to False for parallel workers or automated pipelines.

sample() method

sampleset = sampler.sample(
    num_reads: int,
    annealing_time: int,
    shots: int = 1,
    preprocess: bool = False,
    debugging: bool = False,
    # Advanced ODE parameters:
    alpha: float = None,
    beta: float = None,
    gamma: float = None,
    delta: float = None,
    epsilon: float = None,
    zeta: float = None,
    minimum_stepsize: float = None,
    block_fee: int = None,
)

Parameters

num_reads · int · required

Number of independent parallel samples. Higher values give broader coverage of the solution space.

Backend	Recommended
GPU	1000–10000
CPU	500–5000
QPU	1–100
LOCAL	100–1000

annealing_time · int · required

ODE integration depth (number of integration steps). Higher values allow the system more time to find lower-energy states.

Backend	Recommended
GPU	200–1000
CPU	100–500
QPU	10–1000
LOCAL	50–500

shots · int · default: "1"

For network backends, the minimum number of solutions to collect from workers before returning. Use shots > 1 when you need multiple diverse solutions. Current recommended maximum: 5.

qpu_max_coeff · float · default: "9.0"

Maximum allowed absolute value for BQM coefficients when using a QPU backend. If any linear or quadratic coefficient exceeds this threshold, the entire BQM is automatically scaled down proportionally so the maximum coefficient equals qpu_max_coeff. Solutions are returned in the original variable space. Has no effect on GPU/CPU/LOCAL backends or on circuit BQMs (QASM), where scaling is handled by the Apollo API.

preprocess · bool · default: "False"

Apply automatic preprocessing (coefficient scaling, normalization). Recommended for QPU backends to stay within hardware bounds.

debugging · bool · default: "False"

Show verbose progress output including worker responses and integration metrics.

alpha · float

Upper bound for automatic alpha parameter tuning in ODE integration. Range: [0.00000001, 100.0].

beta · float

Upper bound for automatic beta parameter tuning. Range: [0.00000001, 100.0].

gamma · float

Upper bound for automatic gamma parameter tuning. Range: [0.0, 1.0].

delta · float

Upper bound for automatic delta parameter tuning. Range: [0.0, 1.0].

epsilon · float

Upper bound for automatic epsilon parameter tuning. Range: [0.0, 1.0].

zeta · float

Upper bound for automatic zeta parameter tuning. Range: [0.0, 1.0].

minimum_stepsize · float

Minimum adaptive ODE step size. Range: [1e-16, 1.0]. Smaller values increase precision but slow computation.

block_fee · int

Priority fee in nanoDNX (1 DNX = 1,000,000,000 nanoDNX). Higher fees prioritize your job on the network. If not specified, the current average network fee is used.

Returns

Returns a dimod SampleSet:

sampleset.first                          # Sample with lowest energy
sampleset.first.sample                   # dict: {variable: value}
sampleset.first.energy                   # float

sampleset.samples()                      # Iterator (sorted by energy)
sampleset.data(['sample', 'energy'])     # Iterator over named fields
sampleset.to_pandas_dataframe()          # pandas DataFrame
sampleset.record                         # numpy structured array

Thread safety

DynexSampler is thread-safe and can be used from multiple threads or processes simultaneously. See Parallel Sampling for examples.

Full example

import dynex
import dimod
from dynex import DynexConfig, ComputeBackend, QPUModel

# Build problem
bqm = dimod.BinaryQuadraticModel(
    {i: float(i % 3 - 1) for i in range(20)},
    {(i, i+1): 0.5 for i in range(19)},
    0.0,
    'BINARY'
)

# Configure QPU
config = DynexConfig(
    compute_backend=ComputeBackend.QPU,
    qpu_model=QPUModel.APOLLO_RC1,
    default_timeout=300.0
)

# Wrap and sample
model = dynex.BQM(bqm)
sampler = dynex.DynexSampler(
    model,
    config=config,
    description="Production optimization run"
)
sampleset = sampler.sample(
    num_reads=50,       # QPU: keep in range 1–100
    annealing_time=200, # QPU: keep in range 10–1000
    shots=1,            # QPU: up to 5
    preprocess=True
)

# Analyze results
print(f"Best energy: {sampleset.first.energy:.4f}")
print(f"Best sample: {sampleset.first.sample}")
print(f"Total samples: {len(sampleset)}")

df = sampleset.to_pandas_dataframe()
print(df.sort_values('energy').head(5))