API reference#

Everything below is exported from the xsweep top-level namespace. Nothing else is public.

Declaring a sweep#

xsweep.sweep(contract, *, version='0', **policy_fields)#

Lift a point function into a sweep.

Parameters:

  • contract (str | Contract) – The contract describing one call. Parsed immediately, so a malformed contract raises at import rather than after minutes of runs.

  • version (str) – Physics revision; bump it whenever the computation changes for reasons xsweep cannot observe.

  • **policy_fields (Any) – Decorator-level policy defaults.

Returns:

A decorator producing a Sweeper.

Return type:

callable

class xsweep.Sweeper(contract, func, policy=None, *, version='0', name=None)#

Bind a contract and a default policy around a callable.

Parameters:

  • contract (str | Contract) – The contract describing one call, as a string or an object.

  • func (Callable[..., Any]) – The callable to lift.

  • policy (SweepPolicy | None) – Decorator-level defaults, overridable per instance and per call.

  • version (str) – Physics revision, when the contract is given as a string.

  • name (str | None)

explain(space, /, *, policy=None, **statics)#

Resolve the sweep and stop, without calling the function once.

Parameters:

  • space (Dataset) – The Dataset describing the whole sweep.

  • policy (SweepPolicy | None) – Call-level policy overrides.

  • **statics (Any) – Configuration forwarded to every call.

Returns:

The resolved plan, ready to inspect.

Return type:

Plan

__call__(space, /, *, policy=None, **statics)#

Plan the sweep, then execute it.

Parameters:

  • space (Dataset) – The Dataset describing the whole sweep.

  • policy (SweepPolicy | None) – Call-level policy overrides.

  • **statics (Any) – Configuration forwarded to every call.

Returns:

The declared outputs plus the status sidecar variable.

Return type:

xr.Dataset

class xsweep.SweepModule(policy=None)#

Base class for a sweep packaged as an object.

Subclasses declare a contract class attribute and implement forward. Intermediate bases that declare nothing pass abstract=True.

Parameters:

policy (SweepPolicy | None) – Instance-level run policy, overridable per call.

forward(*args, **kwargs)#

Compute one point. Pure physics, testable on its own.

Parameters:

  • args (Any)

  • kwargs (Any)

Return type:

Any

explain(space, /, *, policy=None, **statics)#

Resolve the sweep without calling forward once.

Parameters:

  • space (Dataset)

  • policy (SweepPolicy | None)

  • statics (Any)

Return type:

Plan

__call__(space, /, *, policy=None, **statics)#

Plan the sweep, then execute it.

Parameters:

  • space (Dataset)

  • policy (SweepPolicy | None)

  • statics (Any)

Return type:

Dataset

Configuring a run#

class xsweep.SweepPolicy(store=UNSET, chunks=UNSET, store_chunks=UNSET, batch_size=UNSET, dedup=UNSET, executor=UNSET, max_workers=UNSET, on_error=UNSET, retries=UNSET, skip_where=UNSET, load=UNSET, force_unlock=UNSET)#

Run configuration, with every field optional.

Parameters:

  • store (str | pathlib.Path | None | Literal[xsweep.policy._Sentinel.UNSET]) – Where results are persisted. None runs in memory, without cache or resume.

  • chunks (collections.abc.Mapping[str, int | Literal['auto']] | Literal[xsweep.policy._Sentinel.UNSET]) – Batch sizes keyed by DIM, overriding any @ N in the contract. A dim must still be named explicitly to be batched at all, which is what lets a function that needs its whole axis (a convolution, a moving average) stay correct by simply not being named; the value for a named dim may be "auto" to size it from a memory budget instead of a fixed number.

  • store_chunks (collections.abc.Mapping[str, int] | Literal[xsweep.policy._Sentinel.UNSET]) – Chunk width per loop dim in the store, overriding the automatic memory-budget sizing. Affects write cost only, never results: a wider chunk means fewer, larger writes, at the price of buffering more computed points in memory before they are flushed.

  • batch_size (int | Literal[xsweep.policy._Sentinel.UNSET]) – How many points a batch-delivered call receives at once. One number rather than one per dim: a batched call carries whole points, which span the product of every loop dim, not positions along one of them. Ignored by a contract that declares no batch clause.

  • dedup (bool | tuple[str, ...] | Literal[xsweep.policy._Sentinel.UNSET]) – True deduplicates over every loop dim, a tuple over the named ones.

  • executor (str | Any | Literal[xsweep.policy._Sentinel.UNSET]) – "serial", "process", or an object satisfying the executor protocol.

  • max_workers (int | None | Literal[xsweep.policy._Sentinel.UNSET]) – Worker count for the process executor.

  • on_error (Literal['nan', 'raise', xsweep.policy._Sentinel.UNSET]) – "nan" records a failure and continues, "raise" fails fast.

  • retries (int | Literal[xsweep.policy._Sentinel.UNSET]) – Attempts per point before it is marked failed.

  • skip_where (collections.abc.Callable[[collections.abc.Mapping[str, Any]], bool] | None | Literal[xsweep.policy._Sentinel.UNSET]) – Predicate on a point’s values; True marks it skipped without calling. There is no automatic NaN-skip: an unexpected NaN is more often a bug than a mask.

  • load (bool | Literal[xsweep.policy._Sentinel.UNSET]) – Materialise the result instead of returning a lazy handle.

  • force_unlock (bool | Literal[xsweep.policy._Sentinel.UNSET]) – Break a lock left behind by a dead run.

Inspecting a run before it happens#

class xsweep.Plan(name, contract, policy, axes, n_points, n_unique, batches, work_items, call_signature, result, store, executor, grid, space, statics, source_of=None)#

The resolved description of a sweep, inspectable before it runs.

Execution consumes this object, which is what guarantees the report and the run cannot diverge.

Parameters:

  • name (str)

  • contract (Contract)

  • policy (ResolvedPolicy)

  • axes (tuple[LoopAxis, ...])

  • n_points (int)

  • n_unique (int | None)

  • batches (Mapping[str, tuple[slice, ...]])

  • work_items (tuple[WorkItem, ...])

  • call_signature (tuple[ArgSpec, ...])

  • result (tuple[VarSpec, ...])

  • store (StoreSpec | None)

  • executor (str)

  • grid (LoopGrid)

  • space (Dataset)

  • statics (Mapping[str, Any])

  • source_of (ndarray[tuple[int, ...], dtype[int64]] | None)

property loop_dims: tuple[str, ...]#

Return the loop dims, which are also the result’s leading dims.

property n_calls: int#

Return how many calls a full run would make.

property n_cached: int#

Return how many work items the store already satisfies.

property n_to_compute: int#

Return how many calls this run will actually make.

property n_skipped: int#

Return how many points the skip predicate excluded.

property determined: bool#

Return whether every result size is known without a probe call.

The parsed contract#

class xsweep.Contract(loop=(), vec=(), const=(), out=(), version='0')#

Frozen description of one call, including its physics revision.

Parameters:

  • loop (tuple[xsweep.contract.LoopVar, ...]) – Variables consumed one value per call, whatever their delivery: a batch-delivered variable lives here too, since batching changes how a point reaches the callable and not what a point is.

  • vec (tuple[xsweep.contract.VecVar, ...]) – Variables consumed as vectors, possibly in batches.

  • const (tuple[xsweep.contract.ConstVar, ...]) – Variables handed whole to every call, except any dim also carried by a batched vec variable, which is auto-aligned to the active batch unless the dim is declared protected on that ConstVar.

  • out (tuple[xsweep.contract.OutVar, ...]) – Named outputs with their call-level dims.

  • version (str) – User-declared revision of the computation. Bump it whenever the result of the wrapped callable changes for reasons xsweep cannot observe: the function body, an external engine binary, a data file. It enters the fingerprint, so bumping it invalidates the cache.

property batched: tuple[LoopVar, ...]#

Return the loop variables delivered a group at a time.

property is_batched: bool#

Return True when any loop variable is delivered in groups.

property inputs: tuple[str, ...]#

Return every input variable name, in clause order.

property outputs: tuple[str, ...]#

Return every declared output name.

property out_dims: tuple[str, ...]#

Return the union of the declared output dims, in order of first use.

classmethod parse(spec, *, version='0')#

Build a contract from its string form.

Parameters:

  • spec (str) – Contract string, e.g. "loop(aot, rh) vec(wl @ 8) -> t(wl)".

  • version (str) – Physics revision, see the class docstring.

Returns:

The parsed and validated contract.

Return type:

Contract

Raises:

ContractError – If the string cannot be parsed or is incoherent.

render()#

Return the canonical string form, used in reports and fingerprints.

Return type:

str

class xsweep.LoopVar(name, deliver='scalar')#

A variable consumed one value per call.

Parameters:

  • name (str) – Variable name in the space.

  • deliver (Literal['scalar', 'array', 'batch']) –

    "scalar" hands the callable a native Python scalar, which is what external engines want; "array" keeps a 0-d DataArray; "batch" hands several points at once, as a 1-D array over the group.

    "batch" changes only the delivery. The variable stays a sweep axis, so the space, deduplication, the store and resumption treat it exactly as a scalar-delivered loop variable.

class xsweep.VecVar(name, max_batch=None)#

A variable whose axes the callable accepts as a vector.

Parameters:

  • name (str) – Variable name in the space.

  • max_batch (int | None) – Default batch size along the variable’s single dim. None means the whole axis in one call. Only meaningful for 1-D variables; multi-dim vec variables take their sizes from the policy instead.

class xsweep.OutVar(name, dims, sizes=())#

A named output with its call-level dims.

Parameters:

  • name (str) – Name the produced variable takes in the result.

  • dims (tuple[str, ...]) – Dims one call produces, excluding the loop dims that the sweeper prepends itself.

  • sizes (tuple[int | None, ...]) – Declared sizes, aligned with dims. None entries are discovered by a probe call at execution time.

Errors#

Every error raised by xsweep derives from XsweepError, so a caller can catch the whole family with one except.

exception xsweep.XsweepError#

Base class for every error raised by xsweep.

exception xsweep.ContractError#

Raise when a contract is malformed, incoherent, or violated.

Raised at definition time (decoration or class creation) for grammar and coherence problems, and at execution time when a wrapped callable returns something the contract did not declare.

exception xsweep.PolicyError#

Raise when a run policy cannot apply to this space.

Raised during planning: an unknown dim in dedup or chunks, a reserved name used as a static, an out-of-range field.

exception xsweep.SpaceError#

Raise when the sweep space cannot serve the contract.

Raised during planning: a missing variable, a non-primitive dtype, coordinates that do not align exactly.

exception xsweep.StoreError#

Raise when a store cannot be used as requested.

Raised on open or during writes: fingerprint mismatch, changed space, output shape incompatible with the allocation.

exception xsweep.StoreLockedError#

Raise when a store is already being written by another run.

exception xsweep.PointFailed#

Raise when a point call fails and the policy is to fail fast.