Knowing what a run will cost#

explain resolves the whole sweep and stops. It reads the space, applies the policy, opens the store if there is one, and returns a Plan without calling the function once.

plan = layer.explain(space, policy=SweepPolicy(store="runs/layer.zarr"))
print(plan)
╭─ layer ──────────────────────────────────────────────────────────────╮
│ loop(tau, ssa) -> reflectance(), transmittance()                     │
╰──────────────────────────────────────────────────────────────── v0 ──╯

SPACE
tau    axis     12
ssa    axis      5
points          60
dedup  disabled

CALLS
to compute 30
cached     30
skipped     0
total      60

ARGUMENTS
name  kind  dtype    shape
───────────────────────────
tau   loop  float64
ssa   loop  float64

RESULT
name           dims             dtype
────────────────────────────────────────
reflectance    tau: 12, ssa: 5  float64
transmittance  tau: 12, ssa: 5  float64

STORE
path      runs/layer.zarr
chunk tau                    12
chunk ssa                     5
regions                      60
EXECUTOR  serial

Estimating the total time#

The plan gives the count; you supply the cost of one call.

start = time.perf_counter()
engine(one_representative_point)
per_call = time.perf_counter() - start

plan = layer.explain(space, policy=policy)
print(
    f"{plan.n_to_compute} calls x {per_call:.1f} s = {plan.n_to_compute * per_call / 3600:.1f} h"
)

n_to_compute is the honest number: it excludes what the store already has and what skip_where removes. n_points is the size of the grid, n_calls what a full run would take from scratch.

Two caveats worth saying out loud. Per-call cost is rarely uniform across a parameter space, so time a point near the expensive end rather than the cheap corner. And with executor="process" the wall clock divides by something smaller than the worker count, never by the worker count itself.

What else the plan is for#

  • Catching an accidental product. A point count with five too many digits is the symptom; see semantics.

  • Seeing what one call will receive. The arguments block gives the kind, dtype and shape of every argument, including the batch length of a vec variable. If that shape is not what the callee expects, you know now.

  • Checking the store lines up. The store block shows the chunk grid and region count a run will write into.

  • Auditing a finished run. Against a complete store, n_to_compute is zero and every point is cached.

Execution consumes the same plan object that explain returns, which is what guarantees the report and the run cannot drift apart.

Skipping points#

skip_where takes a predicate on a point’s loop values and excludes it without ever calling the function:

SweepPolicy(skip_where=lambda point: point["tau"] > 1.5)

Skipped points get a skipped status rather than a value, and a later run without the predicate will compute them.


Worked in Start here and the store.

Policy#

Everything in SweepPolicy is a cost decision, never a value one. A parametrised suite checks that the result is bit-identical across policy combinations as a release gate.

Three things are decided at three different moments, and keeping them apart is most of what makes a sweep readable a year later:

  • Contract is physics, fixed when the function is written.

  • Policy is run configuration, set at the decorator, the instance, or the call, in that order of increasing precedence.

  • Data is the space and the statics, given at the call.

@sweep("loop(tau, ssa) -> reflectance()", dedup=True)  # default
def layer(tau, ssa): ...


layer(space)  # deduplicated
layer(space, policy=SweepPolicy(dedup=False))  # not

The knobs#

store

A path. Turns the result into a cache and a resume point; see the store.

dedup

Compute each distinct input row once; see deduplication.

chunks={"wl": 500}

Override a vec batch size, keyed by dim. "auto" sizes it from a memory budget instead of a number you pick. The dim still has to be named, because only you know whether the callee is safe to run on pieces of that axis.

store_chunks={"y": 256}

Size the store’s loop-dim chunk grid. Sized from a memory budget by default and not worth touching unless you have measured a reason.

executor="process", max_workers=N

Run points in parallel across processes. The callable has to be picklable, which in practice means defined at module level. A function defined inside another function is not.

on_error="raise"

Stop at the first failure instead of recording it and continuing. Right during development, wrong for a long unattended run.

retries=N

Give a call another attempt before recording a failure. For a transient fault, not for a bug.

skip_where=lambda point: ...

Exclude points from a predicate on their loop values, without ever calling the function.

Choosing between them#

There is no general answer, but the shape of one is:

  • deduplication wins whenever the space repeats, and costs a little when it does not;

  • processes win once a call is expensive enough to dwarf the cost of starting one, and the speed-up is always less than the worker count;

  • a store costs a fraction of a millisecond per point and buys you the ability to stop.

explain tells you the call count for any combination before you run it.


Worked in policy.