BudgetOptimizer.allocate_budget#

BudgetOptimizer.allocate_budget(total_budget, budget_bounds=None, x0=None, minimize_kwargs=None, return_if_fail=False, callback=False)[source]#

Allocate the budget based on total_budget, optional budget_bounds, and custom constraints.

The default sum constraint ensures that the sum of the optimized budget equals total_budget. If budget_bounds are not provided, each channel will be constrained to lie in [0, total_budget].

Parameters:
total_budgetfloat

The total budget to allocate.

budget_boundsDataArray or dict, optional

  • If None, default bounds of [0, total_budget] per channel are assumed.

  • If a dict, must map each channel to (low, high) budget pairs (only valid if there’s one dimension).

  • If an xarray.DataArray, must have dims (*budget_dims, "bound"), specifying [low, high] per channel cell.

x0np.ndarray, DataArray or dict, optional

Initial guess. A labelled DataArray over the budget dims (e.g. a previous solution or a current spend plan) is packed into the flat decision vector automatically; a dict maps decision-variable names to labelled DataArray objects. A flat np.ndarray of size (n,) is also accepted. If None, the total budget is spread uniformly across all drivers to be optimized.

minimize_kwargsdict, optional

Extra kwargs for scipy.optimize.minimize. Defaults to method=”SLSQP”, ftol=1e-9, maxiter=1_000.

return_if_failbool, optional

Return output even if optimization fails. Default is False.

callbackbool, optional

Whether to track optimization progress. When True, result.callback_info is populated with a list of dictionaries with optimization information at each iteration including ‘x’ (parameter values), ‘fun’ (objective value), ‘jac’ (gradient), and constraint information. Default is False.

Returns:
BudgetOptimizationResult

Result object with budgets (the optimized allocation across channels, monetary units), scipy_result (the raw scipy optimization result), optimized_vars (empty for now), and callback_info (per-iteration diagnostics when callback=True, else None). Iterating the result yields (budgets, scipy_result), so optimal, res = optimizer.allocate_budget(...) keeps working.

Raises:
MinimizeException

If the optimization fails for any reason, the exception message will contain the details.

Notes

Units and cost_per_unit:

  • All budget inputs (total_budget, budget_bounds) are in monetary units.

  • If cost_per_unit is provided, the optimizer converts internally: budget_in_original_units[t] = budget_in_dollars[t] / cost_per_unit[t]

  • Each time period uses its own cost_per_unit value (no averaging).

  • Output optimal_budgets are in monetary units for user convenience.