> ## Documentation Index
> Fetch the complete documentation index at: https://dynex.mintlify.app/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`.

```python theme={null}
from dynex import DynexSampler
```

## Constructor

```python theme={null}
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

<ParamField path="model" type="BQM | CQM | DQM" required>
  The problem model to sample. Must be a Dynex model wrapper — not a raw dimod object.
</ParamField>

<ParamField path="config" type="DynexConfig" required>
  Configuration object specifying the compute backend, credentials, and SDK settings.
</ParamField>

<ParamField path="description" type="str" optional>
  Human-readable job description. Appears in the Dynex job dashboard and network explorer.
</ParamField>

<ParamField path="logging" type="bool" default="True">
  Whether to emit SDK log messages during sampling. Set to `False` for parallel workers or automated pipelines.
</ParamField>

## `sample()` method

```python theme={null}
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

<ParamField path="num_reads" type="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    |
</ParamField>

<ParamField path="annealing_time" type="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      |
</ParamField>

<ParamField path="shots" type="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**.
</ParamField>

<ParamField path="qpu_max_coeff" type="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.
</ParamField>

<ParamField path="preprocess" type="bool" default="False">
  Apply automatic preprocessing (coefficient scaling, normalization). Recommended for QPU backends to stay within hardware bounds.
</ParamField>

<ParamField path="debugging" type="bool" default="False">
  Show verbose progress output including worker responses and integration metrics.
</ParamField>

<ParamField path="alpha" type="float" optional>
  Upper bound for automatic alpha parameter tuning in ODE integration. Range: `[0.00000001, 100.0]`.
</ParamField>

<ParamField path="beta" type="float" optional>
  Upper bound for automatic beta parameter tuning. Range: `[0.00000001, 100.0]`.
</ParamField>

<ParamField path="gamma" type="float" optional>
  Upper bound for automatic gamma parameter tuning. Range: `[0.0, 1.0]`.
</ParamField>

<ParamField path="delta" type="float" optional>
  Upper bound for automatic delta parameter tuning. Range: `[0.0, 1.0]`.
</ParamField>

<ParamField path="epsilon" type="float" optional>
  Upper bound for automatic epsilon parameter tuning. Range: `[0.0, 1.0]`.
</ParamField>

<ParamField path="zeta" type="float" optional>
  Upper bound for automatic zeta parameter tuning. Range: `[0.0, 1.0]`.
</ParamField>

<ParamField path="minimum_stepsize" type="float" optional>
  Minimum adaptive ODE step size. Range: `[1e-16, 1.0]`. Smaller values increase precision but slow computation.
</ParamField>

<ParamField path="block_fee" type="int" optional>
  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.
</ParamField>

## Returns

Returns a dimod [`SampleSet`](https://docs.ocean.dwavesys.com/en/stable/docs_dimod/reference/sampleset.html):

```python theme={null}
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](/annealing/parallel) for examples.

## Full example

```python theme={null}
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))
```