Documentation

The Template class

The Inverse Optimization Problem can be specified using the template class PartialInvParamOpt. The template class takes in five parameter classes:

Input
A class to specify the input to the Forward Optimization problem. Should have the following function:

double length()
Returns the length of the input.

PartialOutput
A class to specify the ouput to the Forward Optimization problem. Should have the following functions:

PartialOutput getTrivialCompletion()
Returns an output that is a trivial completion for the partial output. A trivial completion is one that is not based on any parameter setting. In case of Inverse Alignment, a trivial completion is just the complete alignment given by both the unreliable and reliable columns of the partial example.

double distance(PartialOutput otherOutput)
This is the recovery error in the discrepancy criterion. It is defined to be the error in recovering the partial output (the output on which it is called) by otherOutput. In case of alignment this is the number of reliable columns of the example partial output that are not present in otherOutput, divided by the total number of reliable columns in the example partial output.

DiscrepancySolver
This class should have an overloaded operator, (), defined as follows:

PartialOutput operator() (PartialOutput partialOutput, Input input, double *P, int plength, double blend)
This returns the partial output $B_i$ that maximizes the discrepancy value for the partial output $A_i$ (in this case partialOutput): $$(1 - \alpha)\frac{f_x(A_i) - f_x(B_i)}{L(I_i)} + \alpha d(A_i, B_i)$$

ParamCoeff
This class should have an overloaded operator (), defined as follows:

double* operator()(PartialOutput O, int numParams)
This function should take in a PartialOutput, and the number of parameters and return an array of doubles containing the coefficients for the parameters for the output when evaluating the objective function value.

Completion This class should have an overloaded operator (), defined as follows:

PartialOutput operator()(Input input, PartialOutput partialOutput, double* parameterVector, int numParam)
This function should take in an input, a partialOutput, a parameter vector, and return a completed output. Note that we use the same class to denote the completed as well as the partial output. In case of alignment this function uses the parameter values to find an optimal aligments for the unreliable parts of the alignment and stiches the optimal solutions with the reliable parts to produce a complete example.

Method summary

bool solve(double *solution, int numParam, int numDomainIneqs, double** domainIneqsLHS, double* domainIneqsRHS, int numExamples, Input* input, PartialOutput* partialOutput, DiscrepancySolver discrepancySolver, ParamCoeff paramCoeffs, Completion completion)
This function solves the Inverse Parametric Optimization problem from partial examples. It returns true if all cutting plane iterations are solved to optimality. The parameters can be described as follows:
solution - an array into which the solution values will be placed
numParam - the number of parameters, size of solution array

The Domain Inequalities:
numDomainIneqs - the number of domain inequalities provided
domainIneqsLHS - the coefficients for the domain inequalities specified as a 2d array of doubles, the column specfies the parameter, the row specifies the inequality
domainIneqRHS - the right hand side of the domain inequalities specified as an array

The Examples:
numExamples - the number of examples
input - an array of inputs of type Input and size numExamples
partialOutput - an array of outputs of type PartialOutput and size numExamples

The Forward Solver and Parameter Coefficients Classes:
discrepancySolver - an instance of the DiscrepancySolver type, see above for details.
paramCoeffs - an instance of a the ParamCoeffs class, see above for details.
completion - an instance of the Completion class, see above for details.


void set_blend(double newBlend)
Blend is the constant that controls the weight between score error and recovery error in the discrepancy formula.

void set_solveToOptimality(bool solveIterationsToOptimality)
If set to true, this would force each cutting plane iteration to be solved to optimality.

bool* get_optimalityVector()
This gets the optimality vector, which is an array with size equal to the number of iterations that stores information about whether or not each cutting plane iteration was solved to optimality.

void set_x0(double* x, int numParam)
Set an (optional) initial parameter choice.

void set_error(double error)
This is the threshold value for discrepancy, and can be used as a stopping criteria for the solve function (if this error is achieved, the solve function halts).

void set_numCuttingPlaneIterations(int numIterations)
This is the maximum number of cutting plane iterations that will be executed for finding the optimal parameter choice when solving the inverse optimization problem from complete examples.

void set_numIterations(int numIterations)
Set the number of iterations for the solver.

For any questions regarding the documentation or the code, please email inverseopt@cs.arizona.edu.