This chapter documents the various commands available in Gurobify. Each command begins with "Gurobi", which in some instances helps to avoid conflict with other GAP commands, and is used for consistancy in other instances. It is important to note that many changes to a model do not become active until the model is updated. This can be done by either optimising the model, or calling GurobiUpdateModel. It is often unnecessary to update the model if it will later be optimised, and in fact can be more efficient to only update when necessary. However, one may occasionally wish to perform a command which is dependent on previous changes to the model. In this case it is necessary to call the update command first.
This section deals with reading, writing, and creating models, as well as working with the model variables.
‣ GurobiReadModel( ModelFile ) | ( function ) |
Returns: a Gurobi model.
Takes a model file, reads it and creates a Gurobi model from it. ModelFile is the name of the file as a string, with the appropriate extension, and including the path if the file is not located in the current GAP working directory. Gurobi accepts files of type .mps, .rew, .lp, .rlp, .ilp, or .opb. Refer to the gurobi documentation for more infomation on which file types can be read.
‣ GurobiWriteToFile( Model, FileName ) | ( function ) |
Returns: true
Takes a model and writes it to a file. File type written is determined by the FileName suffix. File types include .mps, .rew, .lp, .rlp, .ilp, .sol, or .prm. Refer to the gurobi documentation for more infomation on which file types can be written.
‣ GurobiNewModel( VariableTypes[, VariableNames] ) | ( operation ) |
Returns: A Gurobi model
Creates a gurobi model with variables defined by VariableTypes. VariableTypes must be a list of strings, where each entry is the type of the corresponding variable. Accepted variable types are "CONTINUOUS", "BINARY", "INTEGER", "SEMICONT", or "SEMIINT". The variable types are not case sensitive. Refer to the Gurobi documentation for more information on the variable types. Optionally takes the names of the variables as a list of strings.
‣ GurobiNewModel( n, VariableType ) | ( operation ) |
Returns: A Gurobi model
Creates a new Gurobi model, with n variables, all of type VariableType. Accepted variable types are "CONTINUOUS", "BINARY", "INTEGER", "SEMICONT", or "SEMIINT". The variable types are not case sensitive. Refer to the Gurobi documentation for more information on the variable types.
‣ GurobiSetVariableNames( Model, VariableNames ) | ( operation ) |
Returns: true
Assigns each variable a new name from a list of names. The names must be strings.
This section deals with adding linear constraints, both individually and in bulk, and also naming and deleting constraints.
‣ GurobiDeleteSingleConstraintWithName( Model, ConstraintName ) | ( function ) |
Returns: true
Deletes a single constraint from a model with the name ConstraintName. If multiple constraints have this name, then one will be deleted at random.
‣ GurobiDeleteConstraints( Model, ConstraintName ) | ( function ) |
Returns: true
Deletes all constraints from a model which are indexed by the values of ConstraintList. Requires an update to the model to take effect.
‣ GurobiDeleteConstraintsWithName( Model, ConstraintName ) | ( operation ) |
Returns: true/false
Deletes all constraints with the name ConstraintName
‣ GurobiAddConstraint( Model, ConstraintEquation, ConstraintSense, ConstraintRHSValue[, ConstraintName] ) | ( operation ) |
Returns: true
Same as below, except that ConstraintRHS value takes an integer value.
‣ GurobiAddConstraint( Model, ConstraintEquation, ConstraintSense, ConstraintRHSValue[, ConstraintName] ) | ( operation ) |
Returns: true
Adds a constraint to a gurobi model. ConstraintEquation must be a list, such that each entry is the coefficient (including 0 coefficents) of the corresponding variable in the constraint equation. The ConstraintSense must be one of "<", ">" or "=", where Gurobi interprets < as <= and > as >=. The ConstraintRHSValue is the value on the right hand side of the constraint. A constraint may optionally be given a name, which helps to identify the constraint if it is to be deleted at some point. If no constraint name is given, then a constraint is simply assigned the name "UnNamedConstraint". Note that a model must be updated or optimised before any additional constraints become effective.
‣ GurobiAddMultipleConstraints( Model, ConstraintEquations, ConstraintSenses, ConstraintRHSValues[, ConstraintNames] ) | ( operation ) |
Returns: true
Add multiple constraints to a model at one time. The arguments (except Model) are lists, such that the i-th entries of each list determine a single constraint in the same manner as for the operation GurobiAddConstraint. ConstraintNames is an optional argument, and must be given for all constraints, or not at all.
‣ GurobiAddMultipleConstraints( Model, ConstraintEquations, ConstraintSense, ConstraintRHSValue[, ConstraintName] ) | ( operation ) |
Returns: true
Add multiple constraints to a model at one time, where the sense, rhs, and optionally name, of each constraint is the same. ConstraintEquations must be a list of constraints, ConstraintSense must be a string, ConstraintRHSValue must be a float or an integer. ConstraintName is an optional argument, which if given, must be a string.
This section deals with adding and modifying objective functions to a model, and changing between maximising and minimising objective functions.
‣ GurobiMaximiseModel( Model ) | ( operation ) |
Returns: true
Sets the model sense to maximise. When the model is optimised, it will try to maximise the objective function.
‣ GurobiMinimiseModel( Model ) | ( operation ) |
Returns: true
Sets the model sense to minimise. When the model is optimised, it will try to minimise the objective function.
‣ GurobiSetObjectiveFunction( Model, ObjectiveValues ) | ( operation ) |
Returns: true
Set the objective function for a model. ObjectiveValues is a list of coefficients (including 0 coefficeints) corresponding to each of the variables
‣ GurobiObjectiveFunction( Model ) | ( operation ) |
Returns: List of coefficients of the objective function
View the objective function for a model.
This section deals with optimising a model, and handling solution information.
‣ GurobiOptimiseModel( Model ) | ( function ) |
Returns: Optimisation status code.
Takes a Gurobi model and optimises it. Returns the optimisation status code which indicates the outcome of the optimisation. A status code of 2 indicates that a feasible solution was found, a status code of 3 indicates the model is infeasible. There a number of other status codes. Refer to the Gurobi documentation for more information about status codes, or alternatively see the Appendix of this manual. The model itself is altered to reflect the optimisation, and more information about it can be obatained using other commands, in particular the GurobiSolution and GurobiObjectiveValue functions.
‣ GurobiReset( Model ) | ( function ) |
Returns: true
Reset all information associated with an optimisation of the model, such as the optimisation status, the solution and the objective value.
‣ GurobiUpdateModel( Model ) | ( function ) |
Returns: true
Takes a model and updates it. Changes to a model (such as changes to parameters or constraints) are not processed until the model is either updated or optimised.
‣ GurobiSolution( Model ) | ( operation ) |
Returns: Solution
Display the solution found for a successfuly optimised model. Note that if a solution has not been optimised, is infeasible, or the optimisation was not completed, then this will return an error. Thus it is advisable to first check the optimisation status.
‣ GurobiObjectiveValue( Model ) | ( operation ) |
Returns: objective value
Returns the objective value of the current solution.
‣ GurobiOptimisationStatus( Model ) | ( operation ) |
Returns: optimisation status code
Returns the optimisation status code of the most recent optimisation. Refer to the Gurobi documentation for more on the optimisation statuses, or alternatively refer to the Appendix of this manual.
‣ GurobiFindAllBinarySolutions( Model, Size ) | ( operation ) |
Returns: Set of all solutions.
This function finds all possible solutions of a given size, for a model with only binary variables. Takes a Gurobi model and repeatedly optimises it, each time adding the previous solution as a constraint so that it isn't found again. This continues until all solutions are found, and then they are returned as a set. During the process the number of found solutions is displayed. Note: - Only for models where every variable is a binary variable. - Only finds solution sets of a given size.
‣ GurobiFindAllBinarySolutions( Model, Size, Group ) | ( operation ) |
Returns: Set of all solutions.
This function finds all possible solutions of a given size, for a model with only binary variables. Same as above, except that it also takes a permutation group acting on the index set of variables. Instead of finding all solutions directly, the group is used to find the orbit of each new solution, and these are then all returned at the end, and used as constraints until then. An option value may also be given which will only return the representatives of each orbit of the solutions. Hence it returns all the unique solutions up to equivalence under the group. This saves on memory, and the remaing solutions may be refound by generating the orbit under the group. To invoke this option place a colon after the group argument and then put representatives:=true so for example GurobiFindAllSolutions(model, size, gp : representatives:=true);
This section deals with obtaining information about attributes and parameters of a Gurobi model. Note that a model must be updated or optimised before parameters and attributes are updated - any queries will return the values at the time the model was last updated or optimised. Note also that the attributes are Gurobi attributes, and are not true attributes in the GAP sense. Crucially, attributes for a model constantly change, either as a result of optimisation or from manually setting them. Thus attributes for Gurobi models are approximated by Gurobify using GAP operations or functions. Their usage should still be comfortable for users familiar with GAP attributes.
‣ GurobiNumberOfVariables( Model ) | ( operation ) |
Returns: Number of variables
Returns the number of variables in the model.
‣ GurobiNumberOfConstraints( Model ) | ( operation ) |
Returns: Number of linear constraints
Returns the number of linear constraints in the model.
‣ GurobiObjectiveBound( Model ) | ( operation ) |
Returns: objective bound
Returns the best known bound on the objective value of the model.
‣ GurobiRunTime( Model ) | ( operation ) |
Returns: run time of optimisation
Returns the wall clock runtime in seconds for the most recent optimisation.
‣ GurobiNumericFocus( Model ) | ( operation ) |
Returns: numeric focus
Returns the numeric focus value of the model. The numeric focus is a value in the set [0,1,2,3]. A numeric focus of 0 sets the numeric focus automatically, preferencing speed. Values between 1 and 3 increase the care taken in computations as the value increases, but also take longer. The default value is 0.
‣ GurobiTimeLimit( Model ) | ( operation ) |
Returns: time limit
Returns the time limit for the model. The default value is infinity.
‣ GurobiCutOff( Model ) | ( operation ) |
Returns: cutoff value
Returns the cutoff value for the model. Optimisation will terminate if the objective value is worse than CutOff. The default value is infinity for minimisation, and negative infinity for maximisation.
‣ GurobiBestObjectiveBoundStop( Model ) | ( operation ) |
Returns: best objective bound limit value
Returns the best objective bound limit value for the model. Optimisation will terminate if a feasible solution is found with objective value at least as good as the best objective bound. The default value is negative infinity.
‣ GurobiMIPFocus( Model ) | ( operation ) |
Returns: MIP focus
Returns the MIP focus value for the model. The mip focus must be in the set [0,1,2,3], and the default value is 0. The MIP focus alows you to prioritise finding solutions or proving their optimality. See the Gurobi documentation for more information.
‣ GurobiBestBoundStop( Model ) | ( operation ) |
Returns: Best bound stopping value
Returns the best bound stopping value for the model. Optimisation terminates as soon as the value of the best bound is determined to be at least as good as the best bound stopping value. Default value is infinity.
‣ GurobiSolutionLimit( Model ) | ( operation ) |
Returns: solution limit value
Returns the solution limit value for the model. This value limits the maximum number of MIP solutions that will be found. Default value is 2,000,000,000.
‣ GurobiIterationLimit( Model ) | ( operation ) |
Returns: Iteration limit
Returns the iteration limit value for the model, which limits the number of simplex iterations performed during optimisation. Default value is infinity.
‣ GurobiNodeLimit( Model ) | ( operation ) |
Returns: Node limit
Returns the node limit value for the model, which limits the number of MIP nodes explored during optimisation. The default value is infinity.
‣ GurobiVariableNames( Model ) | ( operation ) |
Returns the names of the variables in the model. This list acts as the index set for any lists of variable coefficients, such as in GurobiAddConstraint or GurobiSetObjectiveFunction.
‣ GurobiLogToConsole( Model ) | ( operation ) |
Returns: true/false
Returns true if the Gurobi output is set to display to the screen, and false if the output is supressed. Gurobify suppresses the output by default.
‣ GurobiVariableTypes( Model ) | ( operation ) |
Returns the types of the variables in the model.
‣ GurobiMethod( Model ) | ( operation ) |
Returns: MethodType
Returns the method used to solve a model. See the Gurobi documentation for more details.
‣ GurobiThreads( Model ) | ( operation ) |
Returns: ThreadCount
Returns number of threads Gurobi is allowed to use. See the Gurobi documentation for more details.
In addition to the specific queries given in the previous section, other gurobi parameters and attributes of specific value types can also be queried. The parameter or attribute name must be given as a string exactly as stated in the Gurobi documentation. See the Appendix for links to the relevant documentation.
‣ GurobiIntegerParameter( Model, ParameterName ) | ( function ) |
Returns: parameter value
Takes a Gurobi model and retrieves the value of a integer-valued parameter. Refer to the Gurobi documentation for a list of parameters and their types.
‣ GurobiDoubleParameter( Model, ParameterName ) | ( function ) |
Returns: parameter value
Takes a Gurobi model and retrieves the value of a double-valued parameter. Refer to the Gurobi documentation for a list of parameters and their types.
‣ GurobiIntegerAttribute( Model, AttributeName ) | ( function ) |
Returns: attribute value
Takes a Gurobi model and retrieves the value of an integer-valued attribute. Refer to the Gurobi documentation for a list of attributes and their types.
‣ GurobiStringAttributeElement( Model, position, AttributeName ) | ( function ) |
Returns: attribute value
Takes a Gurobi model and retrieves the value of a string attribute element at a given position. For example to get the names of constraints with "ConstrName". Refer to the Gurobi documentation for a list of attributes and their types.
‣ GurobiDoubleAttribute( Model, AttributeName ) | ( function ) |
Returns: attribute value
Takes a Gurobi model and retrieves the value of a double-valued attribute. Refer to the Gurobi documentation for a list of attributes and their types.
‣ GurobiIntegerAttributeArray( Model, AttributeName ) | ( function ) |
Returns: attribute array
Takes a Gurobi model and retrieves an attribute array. Can only get values of attributes arrays which take integer values. Refer to the Gurobi documentation for a list of attributes and their types.
‣ GurobiDoubleAttributeArray( Model, AttributeName ) | ( function ) |
Returns: attribute array
Takes a Gurobi model and retrieves an attribute array. Can only get values of attributes arrays which take double values. Refer to the Gurobi documentation for a list of attributes and their types.
‣ GurobiStringAttributeArray( Model, AttributeName ) | ( function ) |
Returns: attribute array
Takes a Gurobi model and retrieves an attribute array. Can only get values of attributes arrays which have string values. Refer to the Gurobi documentation for a list of attributes and their types.
‣ GurobiCharAttributeArray( Model, AttributeName ) | ( function ) |
Returns: attribute array
Takes a Gurobi model and retrieves an attribute array. Can only get values of attributes arrays which have char values. Refer to the Gurobi documentation for a list of attributes and their types.
This section deals with modifying the values of attributes and parameters of Gurobi models. Note that a model must be updated or optimised before parameters and attributes are updated. Any queries or commands which depend on these values will use the values at the time the model was last updated or optimised, even if the values have since been modified.
‣ GurobiSetTimeLimit( Model, TimeLimit ) | ( operation ) |
Returns: true
Set a time limit for a Gurobi model. Note that TimeLimit should be a float, however an integer value can be given which will be automatically converted to a float.
‣ GurobiSetBestObjectiveBoundStop( Model, BestObjectiveBoundStop ) | ( operation ) |
Returns: true
Optimisation will terminate if a feasible solution is found with objective value at least as good as BestObjectiveBoundStop. Note that BestObjectiveBoundStop should be a float, however an integer value can be given which will be automatically converted to a float.
‣ GurobiSetCutOff( Model, CutOff ) | ( operation ) |
Returns: true
Optimisation will terminate if the objective value is worse than CutOff. Note that CutOff should be a float, an integer value can be given which will be automatically converted to a float.
‣ GurobiSetNumericFocus( Model, NumericFocus ) | ( operation ) |
Returns: true
Set the numeric focus for a model. Numeric focus must be in the set [0,1,2,3]. A numeric focus of 0 sets the numeric focus automatically, preferencing speed. Values between 1 and 3 increase the care taken in computations as the value increases, but also take longer. The default value is 0.
‣ GurobiSetMIPFocus( Model, MIPFocus ) | ( operation ) |
Returns: true
Set the MIP focus for a model. The mip focus must be in the set [0,1,2,3], and the default value is 0. The MIP focus alows you to prioritise finding solutions or proving their optimality. See the Gurobi documentation for more information.
‣ GurobiSetBestBoundStop( Model, BestBdStop ) | ( operation ) |
Returns: true
Set the best bound stopping value for a model. Terminates optimisation as soon as the value of the best bound is determined to be at least as good as the best bound stopping value. Default value is infinity.
‣ GurobiSetSolutionLimit( Model, BestBdStop ) | ( operation ) |
Returns: true
Set the limit for the maximum number of MIP solutions to find. Default value is 2,000,000,000.
‣ GurobiSetIterationLimit( Model, IterationLimit ) | ( operation ) |
Returns: true
Set the limit for the maximum number of simplex iterations performed. Default value is infinity.
‣ GurobiSetNodeLimit( Model, NodeLimit ) | ( operation ) |
Returns: true
Set the limit for the maximum number of MIP nodes explored. The default value is infinity.
‣ GurobiSetLogToConsole( Model, Switch ) | ( operation ) |
Returns: true
Turns console logging on or off. If Switch is true the output of Gurobi will be printed to the screen, and if it is false the output will be supressed. The default for Gurobify is to supress the output.
‣ GurobiSetMethod( Model, MethodType ) | ( operation ) |
Returns: true
Set the method used to solve a model. -1=automatic (this is the default), 0=primal simplex, 1=dual simplex, 2=barrier, 3=concurrent, 4=deterministic concurrent, 5=deterministic concurrent simplex. See the Gurobi documentation for more details.
‣ GurobiSetThreads( Model, ThreadCount ) | ( operation ) |
Returns: true
Set the number of threads Gurobi is allowed to use. The default value is 0, which will use as many cores as it wants. See the Gurobi documentation for more details.
In addition to these specific commands given in the previous section, other gurobi parameters and attributes of specific value types can be modified. The parameter or attribute name must be given as a strings exactly as stated in the Gurobi documentation. See the Appendix for links to the relevant documentation.
‣ GurobiSetIntegerParameter( Model, ParameterName, ParameterValue ) | ( function ) |
Takes a Gurobi model and assigns a value to a given integer-valued parameter. ParameterValue must be a integer value. Refer to the Gurobi documentation for a list of parameters and their types.
‣ GurobiSetDoubleParameter( Model, ParameterName, ParameterValue ) | ( function ) |
Takes a Gurobi model and assigns a value to a given double-valued parameter. ParameterValue must be a double value. Refer to the Gurobi documentation for a list of parameters and their types.
‣ GurobiSetIntegerAttribute( Model, AttributeName, AttributeValue ) | ( function ) |
Takes a Gurobi model and assigns a value to a given integer-valued attribute. AttributeValue must be a double value. Refer to the Gurobi documentation for a list of attributes and their types.
‣ GurobiSetDoubleAttribute( Model, AttributeName, AttributeValue ) | ( function ) |
Takes a Gurobi model and assigns a value to a given double-valued attribute. AttributeValue must be a double value. Refer to the Gurobi documentation for a list of attributes and their types.
‣ GurobiSetDoubleAttributeArray( Model, AttributeName, AttributeValueArray ) | ( function ) |
Takes a Gurobi model and assigns a value to a given attribute which takes an array of floats. AttributeValue must be an array of floats. Refer to the Gurobi documentation for a list of attributes and their types.
This section provides information on some additional functionality which does not directly relate to Gurobi but may assist in using the Gurobify package. In particular, it details functions which convert between characteristic vectors (which are more desirable for use with Gurobi) and sets (which may be more desirable for use in GAP).
‣ IndexSetToCharacteristicVector( IndexSet, NumberOfIndices ) | ( operation ) |
Returns: Characterisitc vector
Takes a list of integers which form a subset of the set [1 .. n], where n is the second argument, and converts the set of indices to its characteristic vector. For example, if n = 5, the set [1,3] would be converted to [1, 0, 1, 0, 0]. It is useful to be able to convert between the two, since Gurobify always takes the characteristic vector (for example when taking constraints), yet the set of indices is generally more helpful for the user.
‣ CharacteristicVectorToIndexSet( CharacteristicVector ) | ( operation ) |
Returns: Index set
Takes a characteristic vector and returns the set of indices corresponding to it. This reverses the process which occurs with IndexSetToCharacteristicVector. It is particularly useful to convert the output of a Gurobi solution back in terms of the variables. For example, the characteristic vector [1, 0, 1, 0, 0] would return the index set [1,3]. Note that since the function expects a characteristic vector it doesn't account for any weightings, and is only interested in whether or not the corresponding index is present, and as such it rounds each entry to the nearest integer and checks that it is non-zero. Hence it is particularly suitable for use with binary variables.
‣ SubsetToCharacteristicVector( Subset, FullSet ) | ( operation ) |
Returns: Characterisitc vector
Takes a subset of some set, and returns the characteristic vector where the entries of the characteristic vector are indexed by the full set. For example, the subset ["c"] of ["a", "c", "n", "q"] would give the characteristic vector [0, 1, 0, 0]. This removes the need to first find the index set of the subset.
‣ SubsetToIndexSet( Subset, FullSet ) | ( operation ) |
Returns: Index set
Takes a subset of some set, and returns the set of indices corresponding to it. For example, the subset ["a", "d"] of the set ["a", "b", "c", "d", "e"], would return the index set [1,4]. Note that since the method expects a subset (not a multiset) vector it doesn't account for any weightings or repetition.
‣ CharacteristicVectorToSubset( CharacteristicVector ) | ( operation ) |
Returns: Subset
Takes a characteristic vector and some set which it takes to be indexing the entries of the characteristic vector. It then returns the subset of the full set corresponding to the non-zero entries of the characteristic vector. This is the reverse process to SubsetToCharacteristicVector. Note again that the characteristic vector is rounded to an integer before being compared to 0. As an example, the characteristic vector [0, 1, 0, 0] with the set ["a", "c", "n", "q"] would return ["c"]. This removes the need to first return an index set before finding the subset.
This section documents Gurobify functionality not belonging in any of the other sections.
‣ GurobiVersion( ) | ( function ) |
Returns: [ major_version, minor_version, technical_version ]
This function returns a list [ major_version, minor_version, technical_version ] which indicates the Gurobi library version. For example, if using Gurobi Version 7.5.1, then GurobiVersion() would return [ 7, 5, 1 ].
generated by GAPDoc2HTML