Volume Optimization
Allocates non-negative integer volumes across a set of decision units so that, combined with current inventory projected into the same unit space, the resulting per-attribute supply matches per-attribute supply targets as closely as possible.
The optimization lives in ai_ppm.volume.optimizer (package packages/ai_ppm) and is intentionally generic — it makes no assumption about what one element of the decision vector represents. Each caller supplies:
- the catalog of decision units
- the per-unit baseline derived by projecting inventory into decision-unit space
- the per-attribute target supplies
- (when applicable) the externally-imposed allocation constraints
ai_ppm is currently a standalone library with no Dagster consumer registered in any OEM's DAG.
This page illustrates the concepts with a dealer allocation example: the decision unit is a model line, so x chooses how many additional vehicles to take per model line, and c is the dealer's current inventory counted by model.
Decision Unit
The vector x has length N, where N is the number of decision units. A decision unit is whatever the lowest level of granularity is at which volume is being chosen for a given application. The optimizer is unit-agnostic; the only requirements are that each unit:
- Can be assigned an integer non-negative count.
- Can be classified into one or more attribute groups.
- May participate in zero or more allocation groups.
Common choices in practice — listed roughly in order of decreasing granularity — include:
| Application | Decision unit | Approx N |
|---|---|---|
| Auction-candidate selection | Individual auction listing | 10⁵–10⁶ per model |
| Pre-purchase planning at full build resolution | Build code, or (build_code, QOP) pair | tens to low hundreds |
| Dealer allocation | Model line (model_id) | single-digit per dealer |
| Brand-level rollup | Brand | 1–5 |
The math is identical across all of these. What changes is:
- the meaning of one row of
x - the rows of the attribute matrix
- how inventory is projected into decision-unit space to produce the baseline
c - which allocation constraints, if any, apply
The same optimizer can be reused at whichever level the downstream consumer needs.
Inventory Projection
Inventory in the warehouse is per-vehicle (one row per VIN in consolidated/inventory). Before it can serve as the baseline c, it must be projected into decision-unit space — i.e. aggregated so each decision unit receives a single integer count.
For a model-line decision unit, the projection is typically a group_by(model_id).len() over currently-held (unsold) inventory: c[i] is the count of vehicles whose model_id matches decision unit i, with c[i] = 0 for units with no current inventory.
The projection rule depends entirely on the decision-unit choice — for a build-code-level optimization the same inventory would be projected via group_by(build_code).len(), and for a greenfield decision with no relevant prior inventory it collapses to c = 0.
Problem Statement
We choose how many additional units to acquire so that the realized per-attribute-group supply falls close to a desired target supply, weighted by how much we care about each attribute group.
Variables
| Symbol | Shape | Meaning |
|---|---|---|
x | (N,) integer, ≥ 0 | Decision variable — additional volume per decision unit (for dealer allocation: additional vehicles to take per model_id) |
c | (N,) integer | Baseline — current inventory projected into decision-unit space (for dealer allocation: count of currently-held vehicles per model_id; see Inventory Projection) |
target | (N,) integer | Derived: target = x + c — total per-unit volume after the decision |
Attribute grouping (soft objective)
Units roll up into one or more attribute groupings (e.g. two-door vs four-door, premium vs non-premium, color family, drivetrain). All such indicator rows are stacked into one matrix:
| Symbol | Shape | Meaning |
|---|---|---|
O | (K, N) sparse 0/1 | Row k is an indicator of units belonging to attribute group k |
t | (K,) | Desired total supply per attribute group |
w | (K,) | Per-group importance weight |
K is the total number of attribute-group rows summed across every attribute dimension. Disjoint dimensions (two-door / four-door is one dimension; premium / non-premium is another) coexist in the same O as separate rows. There is no need for a separate matrix per dimension.
This page uses the row-oriented (K × N) convention so O @ (x + c) is the natural sparse matrix-vector product. The equivalent column-oriented (N × K) form would multiply on the right as (x + c)ᵀ · O.
Allocation grouping (hard constraint)
When the application has externally-imposed quotas — for example, OEM-handed-down allocations that assign a number of vehicles to a set of units — these are modeled as hard constraints:
| Case | Description | Constraint |
|---|---|---|
| Single-unit allocation | The allocation is tied to exactly one unit | x_i is fully determined; nothing to optimize for that unit |
| Multi-unit allocation, free distribution | Allocation of a_m spread freely across units in group m | Σ_{i ∈ m} x_i = a_m |
| Multi-unit allocation, restricted distribution | Allocation of a_m with split / max-count rules | not yet supported (see Open Questions) |
Allocations are encoded as a sparse 0/1 matrix A of shape (M, N) plus an allocation-amount integer vector a of shape (M,). Two semantics are currently supported via allocation_mode:
"equality"—A @ x = a, the free-distribution case"upper_bound"(default) —A @ x ≤ a, useful when the allocation is a cap rather than a quota
Applications without hard quotas (e.g. unrestricted auction-candidate selection) leave the allocation inputs unset.
Split / max-count rules are not yet supported. They require auxiliary binary variables and are conditioned on confirmation that the rule actually exists for a given application.
Objective
Minimize the weighted L1 deviation of per-attribute-group supply from the desired target supply:
minimize ‖ w ⊙ ( O @ (x + c) − t ) ‖₁
subject to x ∈ ℤ₊ⁿ
A @ x = a (when allocation_mode="equality")
A @ x ≤ a (when allocation_mode="upper_bound")
The L1 norm is preferred over L2 because it tolerates the integer-rounding artifacts of a MIP without inflating outliers, and because the objective stays linear when allocation constraints are themselves linear.
With surplus_cost="quadratic", the objective charges a group's units above its target with a quadratic term instead of the L1 term. Placing units above target gives that objective. allocation_mode and surplus_cost are independent: one sets the allocation constraint, the other the cost of units above target.
Days-of-supply target
The per-group target supply t is the soft optimization goal — the inventory the MIP steers each group toward. The ai_ppm.volume.allocation wrapper derives it from target_days_supply × daily_sales_rate; target_days_supply defaults to DEFAULT_TARGET_DAYS_SUPPLY (110 days). Consumers of ai_ppm set the value themselves — for the ai_ordering service it lives on the OEM profile (OrderingOEMProfile.target_days_supply), and a run overrides it per-run via VolumeOptimizationConfig.target_days_supply.
Sales rate
daily_sales_rate is a group's sales over the sales_window_days before the as-of date, divided by the length of the window. For the ai_ordering service, the window lives on the OEM profile (OrderingOEMProfile.sales_window_days, 90 days by default), and a run overrides it via VolumeOptimizationConfig.sales_window_days. Candidate selection's SimulationSupplyModel reads the same window.
A group with few or no recorded sales gets one of two floors, depending on what the rate is for:
| Floor | Field | Default | Used by |
|---|---|---|---|
| Forecast floor | VolumeOptimizationConfig.forecast_min_daily_sales_rate | 0.02, about one sale every 50 days | the supply forecast that the supply snapshot and candidate selection's SimulationSupplyModel run |
| Target floor | VolumeOptimizationConfig.min_daily_sales_rate | 0.0001, about one sale every 27 years | the MIP's targets and weights, and the snapshot's daily_sales_rate and projected_days_supply |
The forecast floor keeps a slow seller's stock draining over the horizon, so its projected supply, and candidate selection's weight for each vehicle in it, assumes some sales. The target floor stays tiny: a zero-sales group gets a near-zero target, so adding even one unit oversupplies it and the MIP leaves it at zero. With the forecast floor as the target floor, one unit of a group the dealer does not sell would read as about 50 days of supply, and the MIP would order it.
Stellantis uses a 180-day window. For models with incentives on the outgoing model year, a 90-day window overstates demand. For example, the Pacifica sold about 6 a month over 90 days and about 3 a month over 11 months.
Days-of-supply ceiling
The MIP accepts a K-dim group_ceiling (build_problem param) that upper-bounds post-decision inventory per group: A @ x + baseline ≤ group_ceiling. The ai_ppm.volume.allocation wrapper populates it from max_days_supply × daily_sales_rate when the caller supplies max_days_supply; omit or pass None to disable. Groups already at or above the ceiling clamp to zero additional allocation rather than making the problem infeasible. Consumers of ai_ppm set the value themselves — for the ai_ordering service, it lives on the OEM profile (OrderingOEMProfile.max_days_supply).
Allocation volumes as a suggestion vs. a cap
Allocation.volume is optional. A row with volume=None contributes only eligibility — its model_ids enter the decision space, but no M·x ≤ b row is added for it. A row with a concrete volume still enforces the cap per allocation_mode. Callers whose OEM allocation counts are guidance (Stellantis) emit None; callers with genuine per-allocation caps supply the count. Rows with volume=0 mean "OEM extended zero" and are dropped entirely.
An ai_ordering run with VolumeOptimizationConfig.unconstrained set passes None for every row, so only the days-of-supply ceiling limits volume.
Where the OEM caps each allocation, a run caps it at the units the dealer has not yet submitted. With VolumeOptimizationConfig.original_allocation set, the cap is the original allocation, including submitted units. Without the setting, a dealer that has submitted its whole allocation gets no targets.
OrderingOEMProfile.allocation_override_run_modes lists the run modes that accept either setting.
Filling every allocation
With VolumeOptimizationConfig.fill_allocations set, a run orders each allocation's full cap and
still records what the optimization recommends. It solves twice:
- The usual solve, with
allocation_mode="upper_bound"and the OEM's days-of-supply ceiling. Its volumes are the recommendation. - A solve with
allocation_mode="equality", so the volumes of each allocation's models sum to its cap. It runs without the ceiling and without the run'sgroup_rowsandorder_caps, which support only upper-bound allocations, so it is a per-base-model solve. It setssurplus_cost="quadratic", so where an allocation covers several models, the solve divides its cap among them with the objective in Placing units above target. Its record'soptimizer_nameismip_quadratic_surplus, and itsoptimizer.surplus_costisquadratic. A record of any other solve hasoptimizer.surplus_costlinear. The run builds its targets from this solve's volumes.
VolumeOptimizationInputs.volume_type says which solve a record describes:
| Run | Solve | volume_type | Record key |
|---|---|---|---|
without fill_allocations | the one solve | recommended | run_id:dealer_code |
with fill_allocations | upper-bound solve | recommended | run_id:dealer_code |
with fill_allocations | equality solve | fill | run_id:dealer_code:fill |
The key is the _id of the volume_optimizations document and of the ordering_events volume
event. A record persisted before the field existed parses as recommended. A run orders the
volumes of its fill record where it has one, else those of its recommended record.
Each OrderTarget of a volume-fill run has a volume_type too. Within a model, the units
beyond its recommended volume are fill: the scope's fill_count is the model's fill volume
minus its recommended volume, or zero where that is negative, and the last fill_count of the
scope's targets are fill.
A target's recommendation, validated-candidate and attempt-outcome events have its
volume_type.
fill_allocations cannot be combined with these settings:
unconstrained, which has no cap to fill.fixed_volume, which sets the targets without a solve.
Only an OEM profile with OrderingOEMProfile.supports_fill_allocations set accepts it.
Placing units above target
An equality solve can require more units than it takes to bring every group to its target. The
L1 objective charges each unit above a group's target that group's daily sales rate w, the
same amount for every such unit. An equality solve with that objective puts every unit above
target on the group with the lowest sales rate, whose stock takes longest to sell.
With surplus_cost="quadratic", build_problem instead charges a group pos(d)² / w, where
d is the group's deviation from its target. That equals w times the square of the group's days of supply above target.
Each further unit costs more than the one before. The solve therefore divides an allocation's
units above target so that its groups' days of supply stay close to one another. Units below
target keep the L1 cost.
For example, a dealer sold 2 Q7 and 1 SQ7 in 90 days, projects 1 Q7 and 1.1 SQ7 at the horizon, and has an allocation of 6 units covering both. With the L1 objective, the solve orders 2 Q7 and 4 SQ7, and the dealer ends with 135 and 459 days of supply. With the quadratic term, the solve orders 4 Q7 and 2 SQ7, and the dealer ends with 225 and 279 days.
At the default min_daily_sales_rate floor, one unit above target gives a group about 10,000
days of supply. That unit costs as much as the 100th unit above target of a group that sells
once every 50 days. Where every group of an allocation is at the floor, the solve splits the
units above target evenly among them.
The group-rows solve has no surplus_cost and charges units above target with the L1 term.
HiGHS, the only MIP solver the lockfiles install, does not accept a quadratic objective.
build_problem therefore bounds each group's cost below by the cost's chords between
consecutive whole numbers of added units. A group's added units are a whole number, so the bound equals the cost.
The chords run to one unit past the larger of the allocated units and the largest shortfall.
A group can exceed that range only through a model outside every capped allocation. There the
bound follows the last chord, which lies above every group's target, so each further unit
still adds cost and the solve stays bounded.
A group at the rate floor makes the objective large. Six units above target split evenly between two groups at the floor cost about 180,000. At its default relative MIP gap of 1e-4, HiGHS can then stop at a result about 18 above the optimum, and two ways of dividing another allocation can differ by less than that. The quadratic solve therefore sets the gap to 0, so HiGHS returns the optimum.
Group rows
A run whose VolumeOptimizationConfig.group_rows is set solves volume over a row per model group
and a row per offered base model. ai_ppm.volume.group_rows.solve_group_rows builds and solves
the rows.
With one row per base model, the sales of a discontinued base model leave every target. The group row keeps them in the group, and the base models' rows split them between the base models the dealer can still order. A discontinued base model is a base model of the group with projected stock or sales and no model in the run's allocations, so a base model the OEM does not allocate this run counts as one.
Rows
For each model group of an offered model:
| Row | Members | Target | Weight above target | Weight below target |
|---|---|---|---|---|
| Group | every offered model of the group | target_days_supply × the group's rate | the group's rate | 0 |
| Base model | the offered models of one base model | target_days_supply × the base model's rate | the base model's rate × base_model_weight | the same |
- The group's rate is the dealer's
inferred_sales_count_{n}Dof the group ininventory_stats/model_group_id_dealer, divided byn, which isGroupRowsConfig.group_sales_window_days(360 by default). - A base model's rate is the group's rate times the base model's share of the group's target.
- Both rates are raised to
min_daily_sales_rate. A group without a row in the statistics gets that floor. - A row's baseline is the projected stock of its base models at the order's arrival. The group row's baseline includes the base models nobody can order.
- The group's
max_days_supplyceiling bounds the group row. No other row has a ceiling.
The group row costs only the units above its target, so only the base models' rows ask for
units. A base model below its target gets units while its group is below the group's target.
Once the group reaches its target, a unit costs the group's rate on the group row and saves the
base model's rate times base_model_weight on its own row. So a base model below its target in a
group at or above its target gets units only when its share times base_model_weight exceeds 1.
With the default weight of 1, it gets none.
Base models that leave or arrive
A base model's share of the group's sales is its sales over the sales of the group's base models, both over the supply snapshot's sales window and before any floor. The shares include base models nobody can order any more, so they are adjusted to the base models on offer:
- A base model nobody can order keeps the share that its projected stock covers, at most its share of the sales.
- The rest of its share moves to the offered base models, in proportion to their shares.
- An offered base model without sales has a share of 0. Its rate is the floor, so a unit of it costs more than it saves and the run orders none.
Decision record
The optimizer name is mip_group_rows. A model's daily_sales_rate, target_units and
deviation_after are those of its base model's row. Its ceiling_binding is set when the group
ended within a unit of its ceiling while the base model ended at least a unit below its target.
inputs.optimizer.rows in the volume_optimizations document and the volume event holds every
row as a VolumeRowDecision: its rate, shares, target, weights, ceiling, and the stock before and
after the orders.
Order caps
A run whose VolumeOptimizationConfig.order_caps is set caps how much it orders of each offered
base model and of each model group of an offered model. Either optimizer takes the caps as
upper-bound allocation rows of the MIP. A cap is the mean of the dealer's orders per window plus
sd_multiple sample standard deviations (2 by default), rounded down, and at least min_units
(0 by default).
- The history is
windowsconsecutive windows ofwindow_daysdays. The most recent window ends on the run's partition date. A window without orders counts as 0. - A base model's cap reads its own orders, so a base model the dealer never ordered, or ordered
once in the windows, gets
min_units. - A model group the dealer never ordered, such as a new nameplate, gets
min_unitsin total. - With the default
min_unitsof 0, the run orders none of a base model or model group that getsmin_units. - A model group's cap reads the orders of all of the group's base models, including the ones nobody can order any more.
The orders are the dealer's vehicles in consolidated/inventory that are not cancelled.
arrival_date stands in for the order date, so a vehicle counts in the window of its arrival.
An ai_evaluation Reference with a sliding_window forms the windows, as the
dealer_base_model_windows reference of Order Set Evaluation
does. Unlike the evaluation's population, the cap's history includes the orders we placed. A
dealer whose orders we place would otherwise see its caps fall toward min_units.
inputs.optimizer.order_caps holds every cap as an OrderCapDecision: its window orders, mean,
standard deviation, cap, the volume allocated under it, and whether it bound. A cap binds when
the run allocated the cap and a base model under it ended at least a unit below its target.
order_cap_binding marks the models of a binding cap whose base model ended that far below its
target.
Current Implementation
ai_ppm.volume.optimizer.build_problem(...) returns a VolumeProblem exposing the cvxpy problem, the integer variable x, and the target expression. VolumeProblem.solve(**solver_kwargs) runs the solver (cvxpy auto-selects an installed MIP backend) and returns x as np.int64. VolumeProblem.target_value exposes (x + baseline) as a rounded np.int64 array after solve.
The attribute-soft-penalty matrix O is passed as attribute_matrix; allocation constraints are passed as allocation_matrix + allocation_amounts with semantics chosen via allocation_mode.
Example
A minimal call against the generic optimizer. Three decision units (three model_ids); one attribute group (AWD); one allocation that may be split between two of the model lines.
import numpy as np
import scipy.sparse as sp
from ai_ppm.volume.optimizer import build_problem
# 3 decision units (model_ids); 1 attribute group (is_awd).
# model_ids: ["mid_a", "mid_b", "mid_c"] — AWD for a and c, FWD for b.
attribute_matrix = sp.csr_matrix(np.array([[1, 0, 1]], dtype=np.int64))
# Baseline c: current dealer inventory projected into model space —
# i.e. count of currently-held vehicles per model_id.
# (mid_a → 10 vehicles, mid_b → 5, mid_c → 2.)
baseline = np.array([10, 5, 2], dtype=np.int64)
# Want 15 AWD vehicles in supply after the decision; weight 1.0.
attribute_targets = np.array([15.0])
attribute_weights = np.array([1.0])
# Allocation of 7 vehicles split freely across mid_a and mid_b.
allocation_matrix = sp.csr_matrix(np.array([[1, 1, 0]], dtype=np.int64))
allocation_amounts = np.array([7], dtype=np.int64)
vp = build_problem(
attribute_matrix=attribute_matrix,
baseline=baseline,
attribute_targets=attribute_targets,
attribute_weights=attribute_weights,
allocation_matrix=allocation_matrix,
allocation_amounts=allocation_amounts,
)
x = vp.solve() # additional volume per model_id
supply = vp.target_value # = x + baseline (post-decision supply per model_id)
A consuming OEM project would wrap this with helpers that build attribute_matrix, baseline, and allocation_matrix from its own consolidated tables.
Future Extension: Time Dimension
The current formulation chooses volumes for a single planning horizon. For applications that care about when volume becomes available — e.g. planning across production dates so that supply arrives in the right month — the same formulation extends to an (N × T) decision tensor with no change in structure:
| Symbol | Single-horizon | With T time slots |
|---|---|---|
x, c, target | (N,) | (N, T) — per-unit, per-time-slot volume |
O | (K, N) | (K, N, T) — attribute-group membership of unit i in time slot t |
A | (M, N) | (M, N, T) — allocation m covers (unit, time) pairs |
t (targets) | (K,) | (K, T) per time slot, or (K,) if applied to time-aggregated supply |
w (weights) | (K,) | (K, T) per time slot, or (K,) |
In the typical case where attribute-group membership does not vary across time, the (K, N, T) tensor O collapses to a (K, N) matrix applied independently per slot. Allocations either pin a specific time slot (the usual case for OEM production allocations: "build a_m of these units in month t") or sum across a window.
Implementation is a straight flattening: treat the (N, T) decision as a length-N·T vector and widen O and A to the corresponding (K, N·T) and (M, N·T) block-diagonal forms. The optimizer itself needs no structural change — only the way the caller arranges its inputs. We do not currently expose this, but it is what we would solve once production-date sensitivity becomes a requirement.
Open Questions
- Decision-unit choice for OEM pre-purchase planning. Build code alone,
(build_code, QOP)pair, or model line? The optimizer itself does not depend on this — it only changes how upstream data is rolled up into thexindex. - Multi-unit allocation semantics. When an allocation covers multiple units, are we free to distribute the total however we want, or is there a hard rule (split evenly, take all from one, max-of-2-units, …) that requires auxiliary binary variables?
- Target supply derivation. What inputs determine the per-group target supply
t? - Solver selection. cvxpy auto-selects an installed MIP backend (HiGHS ships free; MOSEK requires a license, no perpetual size-limited tier).
- Candidate-selection scale. At
Nin the 10⁵–10⁶ range, can a single MIP solve replace the current iterative candidate-selection loop within an acceptable wall-clock budget?