solprop.driver.scan#

Describe indexed parameter scans and dispatch independent simulations.

Functions

run_scan(scan, build, *, output[, executor, ...])

Run selected points and return a reader for their collected file.

class solprop.driver.scan.Scan(name, *, base_seed=None, **variables)#

Bases: Displayed

Declare an ordered Cartesian product of one-dimensional variable arrays.

Parameters:

namestr: Nonempty scan name; must not contain path separators.
base_seedint or None, optional: Non-negative root entropy. An explicit seed variable takes precedence.
**variablesarray_like: One-dimensional arrays in declaration order. Values use the builder’s documented units; no unit conversions are performed by the scan.

Attributes:

namestr: Name used in metadata and durable point filenames.
base_seedint or None: Root entropy used for index-based seed derivation.

Examples

>>> scan = Scan("example", pressure=[1., 2.], energy=[1e-6, 2e-6])
>>> scan.shape, scan.point(2).multi_index
((2, 2), (1, 0))
>>> [point.index for point in scan.chunk(1, 2).points()]
[1, 3]

add(name, values)#

Append an axis before selecting or running the scan.

Parameters:

namestr: Unique nonempty variable name without path separators.
valuesarray_like: One-dimensional axis in the builder’s units; may be empty.

Raises:

DriverError: If the name repeats, the values are not an axis or this is a subset.

chunk(k, n)#

Select one round-robin chunk by the global index modulo its count.

Parameters:

kint: Zero-based chunk number, smaller than n.
nint: Positive number of chunks.

Returns:

Scan: Points whose global index modulo n equals k.

Raises:

DriverError: If the chunk count or number is invalid.

point(index)#

Look up a point by its scan-wide index without building the product.

Parameters:

indexint: Global index, from zero through size - 1.

Returns:

ScanPoint: Coordinates, values and resolved noise seed.

Raises:

DriverError: If the index is outside the complete product.

points()#

Iterate over the selected points in selection order.

Yields:

ScanPoint: A point retaining its global index.

property shape: tuple[int, ...]#

Return the complete Cartesian shape, including for a subset.

Returns:

tuple of int: Axis lengths in declaration order; empty before any variable is added.

property size: int#

Return the number of points in the complete scan.

Returns:

int: Non-negative Cartesian product size; zero for no variables.

subset(indices)#

Select unique global indices without changing the Cartesian axes.

Parameters:

indicessequence of int: Global indices, in requested order, within the current selection.

Returns:

Scan: Independent selection with the original shape and root seed.

Raises:

DriverError: If an index is repeated, out of range or outside this selection.

property variables: Mapping[str, ndarray]#

Return copies of the named axes in declaration order.

Returns:

collections.abc.Mapping: One-dimensional arrays; changing them cannot alter this scan.

class solprop.driver.scan.ScanPoint(index, values, multi_index, seed=None)#

Bases: object

Identify one combination independently of its executor.

Attributes:

indexint: Zero-based index in the complete Cartesian product.
valuesdict: Variable names and scalar values, in declaration order and user units.
multi_indextuple of int: Zero-based coordinates in the complete scan shape.
seedint or None: Explicit seed-axis value or derived non-negative integer noise seed.

index: int#

multi_index: tuple[int, ...]#

seed: int | None = None#

values: dict[str, object]#

solprop.driver.scan.run_scan(scan, build, *, output, executor=None, reductions=(), fields='none', field_planes=(), stats='all', retry_failed=False, stale_age=600.0, progress='auto')[source]#

Run selected points and return a reader for their collected file.

Parameters:

scanScan: Complete scan or selection of global indices.
buildcallable: Build a Simulation from a ScanPoint, using point.seed for active noise. Pool builders must be pickleable module-level callables. Cache a base simulation lazily inside this callable for one translation per worker.
outputpathlib.Path or str: Collected HDF5 path. Matching completed points are skipped on rerun.
executorExecutor or None, optional: Execution policy. None uses the CLI policy, or Local outside the CLI.
reductionssequence of Reduction, optional: Worker-side calculations with declared shape, dtype, units and provenance.
fields{‘none’, ‘planes’, ‘all’}, optional: Retain no fields, selected planes, or every saved plane.
field_planessequence of int, optional: Saved-plane indices for fields='planes'; negative indices are allowed.
stats{‘all’, ‘none’} or sequence of str, optional: Retained statistics; all includes periodic rows. None is discouraged: statistics are the diagnostics needed to assess a scan.
retry_failedbool, optional: Retry previously failed points; false leaves them recorded as failures.
stale_agefloat, optional: Positive lease age in seconds before abandoned running points are recovered.
progress{‘auto’, ‘bar’, ‘log’, ‘none’}, optional: One outer progress display; individual runs never draw their own bars.

Returns:

solprop.processing.scans.ScanOutput: Reader with global indices, masked incomplete points and exact statistics.

Raises:

DriverError: If controls are invalid or the executor cannot run the builder.
OutputError: If the file belongs to a different scan or stored configuration.