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, backend: str = 'threads') → list[Any]#

Applies a function to groups of arguments in parallel.

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

Parameters:

  • worker – Function applied to each entry in arg_tuples (called as worker(*args)).

  • arg_tuples – Argument tuples; each tuple is expanded into one worker(*args) call.

  • outer_workers – Parallelism level for outer execution.

  • inner_workers – Inner derivative worker setting to propagate via contextvar.

  • backend – Parallel backend. Currently supported: “threads”.

Returns:

List of worker return values.

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).