derivkit.utils.concurrency module

Concurrency management for derivative computations.

derivkit.utils.concurrency.normalize_workers(n_workers: Any) → int

Ensures n_workers is a positive integer, defaulting to 1.

Parameters:

n_workers – Input number of workers (can be None, float, negative, etc.)

Returns:

A positive integer number of workers (at least 1).

Return type:

int

Raises:

None – Invalid inputs are coerced to 1.

derivkit.utils.concurrency.parallel_execute(worker: Callable[[...], Any], arg_tuples: Sequence[Tuple[Any, ...]], *, outer_workers: int = 1, inner_workers: int | None = None) → list[Any]

Runs worker(*args) for each tuple in arg_tuples with outer threads.

Inner worker setting is applied to the context, so calls inside worker will see the resolved inner worker count.

derivkit.utils.concurrency.resolve_inner_from_outer(w_params: int) → int | None

Resolves the number of inner derivative workers based on outer workers and defaults.

Parameters:

w_params – Number of outer derivative workers.

Returns:

Number of inner derivative workers, or None for automatic policy.

derivkit.utils.concurrency.resolve_workers(n_workers: Any, dk_kwargs: dict[str, Any]) → tuple[int, int | None, dict[str, Any]]

Decides how parallel work is split between outer calculus routines and the inner derivative engine.

Outer workers parallelize across independent derivative tasks (e.g. parameters, output components, Hessian entries). Inner workers control parallelism inside each derivative evaluation (within DerivativeKit).

If both levels spawn workers simultaneously, nested parallelism can cause oversubscription. By default, the inner worker count is derived from the outer worker count to avoid that. You can override this by passing inner_workers=<int> via dk_kwargs.

Parameters:

• n_workers – Number of outer workers. If None, defaults to 1.

• dk_kwargs – Keyword arguments forwarded to DerivativeKit.differentiate. May include inner_workers to override the default policy.

Returns:

(outer_workers, inner_workers, dk_kwargs_cleaned), where dk_kwargs_cleaned has any inner_workers entry removed.

derivkit.utils.concurrency.set_default_inner_derivative_workers(n: int | None) → None

Sets the module-wide default for inner derivative workers.

Parameters:

n – Number of inner derivative workers, or None for automatic policy.

Returns:

None

derivkit.utils.concurrency.set_inner_derivative_workers(n: int | None) → Iterator[int | None]

Temporarily sets the number of inner derivative workers.

Parameters:

n – Number of inner derivative workers, or None for automatic policy.

Yields:

int | None – The previous worker setting (restored on exit).