compute_schedule#

compute_schedule(shape, max_memory, max_workers, matching_method, mode='uniform', padding=None, analyzer_method=None, backend=None, float_nbytes=4, complex_nbytes=8, integer_nbytes=4, verbose=True, target_subset=None, n_sat=16777216, min_improvement=1.5, **mode_kwargs)[source]#

Plan a parallelization schedule that fits max_memory and max_workers.

Parameters:

shapetuple of int

Shape of the target array.

max_memoryint

Maximum memory usage allowed in bytes.

max_workersint

Maximum number of concurrent workers.

matching_methodstr

Scoring metric for template matching (e.g., ‘CC’, ‘NCC’, ‘FLC’).

mode{‘uniform’, ‘subdivide’}

Scheduling strategy:

uniform : Regular-grid split of shape via integer factorization.
subdivideRecursive bisection of mask to find tighter bounding
boxes around regions of interest. Falls back to uniform when the improvement is below threshold.

paddingtuple of int, optional

Padding applied to target in each dimension.

analyzer_methodstr, optional

Analyzer class name (e.g., ‘MaxScoreOverRotations’).

backendstr, optional

Computation backend (e.g., ‘cupy’, ‘pytorch’).

float_nbytesint

Bytes per float element (4 for float32).

complex_nbytesint

Bytes per complex element (8 for complex64).

integer_nbytesint

Bytes per integer element (4 for int32).

verbosebool

Print scheduling statistics and diagnostic information.

target_subsettuple of slice, optional

Restrict scheduling to a subregion of shape. When combined with mask, the mask is first cropped to this subset, then further refined to its tight bounding box. Returned boxes are in the original shape coordinates.

n_satint, optional

FFT saturation voxel count: boxes below this size are scored as if their volume were n_sat (overhead-bound regime). Default DEFAULT_N_SAT.

min_improvement: float, optional

Minimum fractional improvement over uniform fallback.

**mode_kwargs

Additional mode-specific parameters.

Returns:

tuple of tuple of slice: Per-box slices in the coordinates of shape.
tuple of int, int: (n_outer_jobs, n_inner_workers).

Other Parameters:

For mode ‘uniform’
split_axestuple of int, optional: Axes along which splitting is allowed. Default is all axes.
split_only_outerbool, default False: If True, parallelize only the outer loop (all workers process the same chunk sequentially). If False, explore nested parallelization strategies.
max_splitsint, default 256: Maximum number of boxes to create.
For mode ‘subdivide’
maskNDArray: Binary mask indicating regions of interest.
mask_spacingfloat or tuple of float, optional: Voxel spacing of mask relative to shape (scalar or per-axis). E.g., shape at 4 and mask at 8 Angstrom per voxel gives 2.0.
min_box_sizeint, optional: Minimum box dimension along any axis, defaults to 32. None disables the check.

Raises:

ValueError: If no valid schedule fits the constraints, or mode is unsupported.

Examples

>>> boxes, (n_outer, n_inner) = compute_schedule(
>>>     shape=(512, 512, 512),
>>>     padding=(64, 64, 64),
>>>     max_memory=8e9,  # 8 GB
>>>     max_workers=4,
>>>     matching_method='NCC',
>>>     mode='uniform'
>>> )