pyphi.optimization.optimize#

pyphi.optimization.optimize(builder, state, bounds, *, seed, quantity='signed_normalized_phi', goal='maximize', x0=None, popsize=15, maxiter=100, tol=0.01, subset=None, formalism=None, parallel=None, progress=None)[source]#

Search a substrate’s weights for a maximizer of an IIT quantity.

Runs a seeded, population-based black-box optimizer (scipy.optimize.differential_evolution()) over a bounded box of parameters, evaluating each candidate as one system irreducibility analysis. The default quantity, signed normalized φₛ, is continuous across minimum-information-partition switches, so the gradient-free search sees no discontinuities.

Parameters:

  • builder (Callable[[NDArray], Substrate]) – The parameter axis: a vector → substrate map. weight_axes() builds one for the single-substrate weight case.

  • state (tuple[int, ...]) – The substrate state analyzed at every candidate.

  • bounds (Sequence[tuple[float, float]]) – (low, high) per parameter dimension. len(bounds) fixes the search dimension.

  • seed (int) – Seeds an isolated np.random.default_rng driving the optimizer, and is recorded on the result. Required.

  • quantity (str or Callable) – The quantity to optimize: "signed_normalized_phi" (default), "phi", "signed_phi", or "normalized_phi" by name, as in perturb(), or a callable SIA → float for any other quantity.

  • goal (str) – "maximize" (default) or "minimize".

  • x0 (NDArray, optional) – Seeds one member of the initial population, e.g. a known-good substrate’s weights.

  • popsize (int) – Differential-evolution population multiplier.

  • maxiter (int) – Maximum number of generations.

  • tol (float) – Relative convergence tolerance.

  • subset (Sequence[int], optional) – Candidate system node indices; None uses the whole substrate.

  • formalism (str, optional) – Leave unset to compute IIT under the active configuration. Pass an earlier version’s name only to reproduce published results; it applies to these evaluations only, as in pyphi.analyze().

  • parallel (bool, optional) – Evaluate each generation’s population through map_reduce; defaults to config.infrastructure.parallel. Requires builder and a callable quantity to be picklable (weight_axes() and the named quantities are).

  • progress (bool, optional) – Show a progress bar; defaults to config.infrastructure.progress_bars.

Returns:

OptimizationResult

Raises:

ValueError – If quantity is a name that is not one of the four φₛ variants; if goal is neither "maximize" nor "minimize"; or if builder cannot build a substrate from len(bounds) parameters, or state or subset does not fit that substrate. These are checked once, at the midpoint of bounds, before the search.

Return type:

OptimizationResult

Notes

The driver reads only the scalar objective to choose a move. It never branches on a selection identity (the chosen partition or state), because that identity flips between near-tied candidates from one grid point to the next even where the objective is smooth. Selection identities and margins are logged for inspection only.

With parallel=True the builder and quantity are sent to worker processes, so both must be picklable. A closure builder or a lambda quantity must be run with parallel=False.