Optimisation API

Abacus exposes the retained optimisation surface through abacus.mmm.optimization.

For workflow guidance and interpretation, see Optimisation.

Primary wrapper

Recommended import path:

from abacus.mmm.optimization import PanelBudgetOptimizerWrapper

PanelBudgetOptimizerWrapper adapts a fitted PanelMMM to the generic budget optimiser.

Constructor:

wrapper = PanelBudgetOptimizerWrapper(
    model=mmm,
    start_date="2025-03-03",
    end_date="2025-03-31",
)

Main constructor arguments:

Argument	Meaning
`model`	Fitted `PanelMMM`
`start_date`	Optimisation window start date
`end_date`	Optimisation window end date
`compile_kwargs`	Optional compilation settings

Useful attributes:

Attribute	Meaning
`start_date`	Requested window start
`end_date`	Requested window end
`num_periods`	Number of periods in the optimisation window
`zero_data`	Synthetic zero-spend future dataset
`channel_columns`	Modelled channels
`dims`	Budget dims beyond date

Main methods

PanelBudgetOptimizerWrapper exposes two user-facing methods:

Method	Purpose
`optimize_budget(...)`	Optimise allocation over the future window
`sample_response_distribution(...)`	Simulate spend and contribution outcomes for an allocation

`optimize_budget(...)`

Key arguments:

Argument	Meaning
`budget`	Total spend across all optimised cells for one model period
`budget_bounds`	Optional per-cell lower and upper bounds
`response_variable`	Objective variable to optimise
`utility_function`	Utility function applied to the response distribution
`constraints`	Extra custom constraints
`default_constraints`	Whether to add the default sum constraint
`budgets_to_optimize`	Optional boolean mask over budget cells
`budget_distribution_over_period`	Optional date flighting weights
`callback`	Whether to return iteration diagnostics

Return values:

allocation, result
allocation, result, callback_info when callback=True

allocation is an xarray.DataArray over the non-date budget dimensions. result is SciPy OptimizeResult.

`sample_response_distribution(...)`

Key arguments:

Argument	Meaning
`allocation_strategy`	Optimised or manually supplied allocation
`noise_level`	Relative noise added to the synthetic future spend
`additional_var_names`	Extra posterior predictive variables to include
`include_last_observations`	Pass lag context into posterior predictive sampling
`include_carryover`	Extend and zero the tail to capture carryover
`budget_distribution_over_period`	Optional date flighting weights

It returns an xarray.Dataset containing:

allocation
one variable per channel for realised spend
the model output variable
channel_contribution
total_media_contribution_original_scale
any extra requested variables

Advanced exported helpers

The same module also exports:

from abacus.mmm.optimization import (
    CustomModelWrapper,
    MinimizeException,
    OptimizerCompatibleModelWrapper,
    optimizer_xarray_builder,
)

These are advanced surfaces for custom optimiser integrations.

Name	Purpose
`CustomModelWrapper`	Wrap a custom PyMC model for optimisation
`OptimizerCompatibleModelWrapper`	Protocol for compatible wrappers
`optimizer_xarray_builder(...)`	Build shaped xarray inputs for optimisation
`MinimizeException`	Exception raised when optimisation fails

Import-path note

abacus.mmm.panel also re-exports PanelBudgetOptimizerWrapper, but the recommended reference import path is abacus.mmm.optimization.