entries_leaving_breakpoints#

pymc_marketing.mmm.price_schedule.entries_leaving_breakpoints(*, right, left, x, low, high, pinned, equalities, active_inequalities, size, rtol=1e-09, tolerance=0.0001)[source]#

Return which pinned entries a first-order improving direction moves off their breakpoint, up and down.

A cell on a breakpoint has two slopes, one each way, and belongs there when the common marginal return of the free entries lies between them; with constraints beyond the budget that is not a comparison of two numbers, so this asks directly whether a feasible direction improves the objective to first order. A linear program with two variables per entry, up and down, priced at the entry’s right and left slope of the objective (the minimiser’s sign) and charged tolerance of that slope, so a cell leaves only for a relative gain above about twice it and solver noise between free cells trades nothing:

  • an entry within rtol * size of one of its own bounds (low, high) cannot move past it; a pinned entry may move one unit either way; any other open direction up to 4 n units, so the program is bounded and zero is feasible;

  • directions satisfy the linearised equalities and the active_inequalities (jac @ d >= 0);

  • costs are divided by the largest absolute cost among the open directions that improve, so a steep entry held on its bound does not shrink the others’ costs below HiGHS’s tolerances.

Parameters:
  • right (ndarray) – Shape (n,): the objective’s gradient with every entry on the piece above it, the slope of moving up.

  • left (ndarray) – Shape (n,): the objective’s gradient with every entry on the piece below it, the slope of moving down.

  • x (ndarray) – Shape (n,): the flat plan the directions start from.

  • low (ndarray) – Shape (n,): each entry’s lower bound, -inf where open.

  • high (ndarray) – Shape (n,): each entry’s upper bound, inf where open.

  • pinned (ndarray) – Shape (n,), bool: the entries held on a breakpoint, the only ones the answer can name.

  • equalities (Sequence[ndarray]) – The Jacobian row of every equality constraint at x; a direction keeps each at zero.

  • active_inequalities (Sequence[ndarray]) – The Jacobian row of every inequality constraint active at x; a direction may only grow each.

  • size (ndarray) – Shape (n,): each entry’s size, against which closeness to a bound is measured.

  • rtol (float) – How close, relative to size, an entry is to a bound it cannot move past.

  • tolerance (float) – The share of its own slope each direction is charged, so only a relative gain above about twice it counts.

Return type:

tuple of (np.ndarray, np.ndarray) or None

Returns:

Two bool arrays of shape (n,): the pinned entries that would leave their breakpoint upwards, and those that would leave it downwards; both all False when no direction improves. None when HiGHS reports anything but an optimum.