Example 8 — FOCEI Optimizer Controls from Python

Script: examples/25_focei_optimizer_controls.py

This example shows how to enable the new FOCEI robustness controls directly from the Python API and run a complete fit.

Goal

Use FOCEI with:

  • multiple starts

  • an explicit outer optimizer

  • a fallback polish optimizer

  • best-iterate retention

  • structured retry after abnormal termination

Example

from openpkpd.api.model_builder import ModelBuilder

built = (
    ModelBuilder()
    .data("examples/shared_data/theophylline/theophylline.csv")
    .subroutines(advan=2, trans=2)
    .pk(
        """
        KA = THETA(1) * EXP(ETA(1))
        CL = THETA(2) * EXP(ETA(2))
        V  = THETA(3) * EXP(ETA(3))
        """
    )
    .error("Y = F * (1 + EPS(1))")
    .theta([(0.01, 1.5, 20.0), (0.001, 0.08, 5.0), (0.1, 30.0, 500.0)])
    .omega([0.5, 0.3, 0.3])
    .sigma(0.1)
    .estimation(
        method="FOCEI",
        maxeval=40,
        n_starts=2,
        outer_optimizer="L-BFGS-B",
        outer_fallback_optimizer="Powell",
        outer_fallback_maxeval=15,
        retain_best_iterate=True,
        retry_on_abnormal=True,
        retry_omega_scales=(0.5, 0.25),
    )
    .build()
)

result = built.fit()
print(result.summary())

When to use these controls

  • n_starts: when the fit is sensitive to initials or shows clear local minima

  • outer_fallback_optimizer: when gradient-based termination is acceptable but a short derivative-free polish can recover a slightly better basin

  • retain_best_iterate: when the terminal iterate is not always the best point visited

  • retry_on_abnormal and retry_omega_scales: when FOCEI fails or terminates abnormally