Documentation

GRBsetpwlobj


GRBsetpwlobj

int GRBsetpwlobj ( GRBmodel *model,
    int var,
    int npoints,
    double *x,
    double *y )

Set a piecewise-linear objective function for a variable.

The arguments to this method specify a list of points that define a piecewise-linear objective function for a single variable. Specifically, the $x$ and $y$ arguments give coordinates for the vertices of the function.

For example, suppose we want to define the function $f(x)$ shown below:

Image pwl

The vertices of the function occur at the points $(1, 1)$, $(3,2)$ and $(5,4)$, so npoints is 3, $x$ is {1, 3, 5}, and $y$ is {1, 2, 4}. With these arguments we define $f(1) = 1$, $f(3) = 2$ and $f(5) = 4$. Other objective values are linearly interpolated between neighboring points. The first pair and last pair of points each define a ray, so values outside the specified $x$ values are extrapolated from these points. Thus, in our example, $f(-1)=0$ and $f(6)=5$.

More formally, a set of $n$ points

\begin{displaymath}
\mathtt{x} = \{x_1, \ldots, x_n\}, \quad \mathtt{y} = \{y_1, \ldots, y_n\}
\end{displaymath}

define the following piecewise-linear function:

\begin{displaymath}
f(v) =
\left\{
\begin{array}{ll}
y_1 + \frac{y_2-y_1}{x_2-x_...
...- x_n), & \mathrm{if}\; v \ge x_n. \ [7pt]
\end{array}\right.
\end{displaymath}

The $x$ entries must appear in non-decreasing order. Two points can have the same $x$ coordinate -- this can be useful for specifying a discrete jump in the objective function.

Note that a piecewise-linear objective can change the type of a model. Specifically, including a non-convex piecewise linear objective function in a continuous model will transform that model into a MIP. This can significantly increase the cost of solving the model.

Setting a piecewise-linear objective for a variable will set the Obj attribute on that variable to 0. Similarly, setting the Obj attribute will delete the piecewise-linear objective on that variable.

Each variable can have its own piecewise-linear objective function. They must be specified individually, even if multiple variables share the same function.

Note that, due to our lazy update approach, the new piecewise-linear objective won't actually be added until you update the model (using GRBupdatemodel), optimize the model (using GRBoptimize), or write the model to disk (using GRBwrite).

Return value:

A non-zero return value indicates that a problem occurred while setting the piecewise-linear objective. Refer to the Error Code table for a list of possible return values. Details on the error can be obtained by calling GRBgeterrormsg.

Arguments:

model: The model to modify.

var: The variable whose objective function is being changed.

npoints: The number of points that define the piecewise-linear function.

x: The $x$ values for the points that define the piecewise-linear function. Must be in non-decreasing order.

y: The $y$ values for the points that define the piecewise-linear function.

Example usage:

  double x[] = {1, 3, 5};
  double y[] = {1, 2, 4};
  error = GRBsetpwlobj(model, var, 3, x, y);