Samples

class Samples

Multiple candidate assignments, each identified by a sample ID.

Each candidate is a State: a mapping from variable IDs to values. Sample IDs identify candidates, independently of the variable IDs within each candidate. Samples does not evaluate an objective or establish feasibility. Pass it to evaluate_samples() to obtain a SampleSet, just as evaluating one State produces a Solution.

Choose sample IDs or assign them automatically

A dictionary from sample IDs to States or variable-value dictionaries preserves the supplied IDs. Use these IDs to associate results with a sampler’s records. An iterable of States or variable-value dictionaries assigns IDs from 0 in iteration order.

>>> from ommx import Samples, State
>>> explicit = Samples({10: {0: 1, 1: 0}, 20: State({0: 0, 1: 1})})
>>> assert explicit.sample_ids() == {10, 20}
>>> assert explicit.get_state(20).entries == {0: 0.0, 1: 1.0}
>>> automatic = Samples([{0: 1, 1: 0}, {0: 0, 1: 1}])
>>> assert automatic.sample_ids() == {0, 1}

Identical assignments may occur under different IDs. num_samples() counts sample IDs, not distinct assignments; the IDs remain available after evaluation.

>>> repeated = Samples([{0: 1}, {0: 1}])
>>> assert repeated.num_samples() == 2
>>> assert repeated.sample_ids() == {0, 1}
>>> assert repeated.get_state(0).entries == repeated.get_state(1).entries

Accepted inputs

The constructor also accepts an existing Samples object, one State, or a nonempty variable-value dictionary. A single assignment receives sample ID 0. An empty dictionary or empty iterable creates no samples; use [{}] or State({}) to represent one empty assignment.

>>> single = Samples({5: 1.0})
>>> assert single.sample_ids() == {0}
>>> assert single.get_state(0).entries == {5: 1.0}
>>> assert Samples({}).num_samples() == 0
>>> assert Samples([{}]).num_samples() == 1
>>> assert Samples(State({})).num_samples() == 1

evaluate_samples() accepts these inputs directly, so an explicit Samples construction is optional. append() adds an assignment under one or more new IDs and rejects duplicate IDs without changing the collection.

__new__(entries: ToSamples) → Samples

append(sample_ids: Sequence[int], state: ToState) → None

Append a sample with the given sample IDs and state.

Raises ValueError if an ID already exists in this collection or occurs more than once in sample_ids. The collection is unchanged when validation fails.

from_v1_bytes(bytes: bytes) → Samples

get_state(sample_id: int) → State

Return an independent State for one sample ID.

Raises KeyError if the sample ID is not present. This returns raw candidate values, not a feasibility assessment; use evaluate_samples() to obtain evaluated results.

num_samples() → int

Number of sample IDs, including separate IDs with identical assignments.

sample_ids() → set[int]

All sample IDs as an independent set of integers.

to_v1_bytes() → bytes