Class ExpressionsBasedModel
- All Implemented Interfaces:
Optimisation
,Optimisation.Model
Lets you construct optimisation problems by combining (mathematical) expressions in terms of variables. Each expression or variable can be a constraint and/or contribute to the objective function. An expression or variable is turned into a constraint by setting a lower and/or upper limit. Use ModelEntity.lower(Comparable), ModelEntity.upper(Comparable) or ModelEntity.level(Comparable). An expression or variable is made part of (contributing to) the objective function by setting a contribution weight. Use ModelEntity.weight(Comparable).
You may think of variables as simple (the simplest possible) expressions, and of expressions as weighted combinations of variables. They are both model entities and it is as such they can be turned into constraints and set to contribute to the objective function. Alternatively you may choose to disregard the fact that variables are model entities and simply treat them as index values. In this case everything (constraints and objective) needs to be defined using expressions.
Basic instructions:
- Define (create) a set of variables. Set contribution weights and lower/upper limits as needed.
- Create a model using that set of variables.
- Add expressions to the model. The model is the expression factory. Set contribution weights and lower/upper limits as needed.
- Solve your problem using either minimise() or maximise()
When using this class you do not need to worry about which solver will actually be used. The docs of the various solvers describe requirements on input formats and similar. This is handled for you and should absolutely NOT be considered here! Compared to using the various solvers directly this class actually does something for you:
- You can model your problems without worrying about specific solver requirements.
- It knows which solver to use.
- It knows how to use that solver.
- It has a presolver that tries to simplify the problem before invoking a solver (sometimes it turns out there is no need to invoke a solver at all).
- When/if needed it scales problem parameters, before creating solver specific data structures, to minimise numerical problems in the solvers.
- It's the only way to access the integer solver.
Different solvers can be used, and ojAlgo comes with collection built in. The default built-in solvers can handle anything you can model with a couple of restrictions:
- No quadratic constraints (The plan is that future versions should not have this limitation.)
- If you use quadratic expressions make sure they're convex. This is most likely a requirement even with 3:d party solvers.
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescription(package private) static final class
static final class
Counts of different kinds of model entities.static interface
Connects solver constraints and variables back to model entities.static enum
static class
Optimisation.Solver
:s that should be usabale fromExpressionsBasedModel
needs to implement a subclass of this.static class
(package private) static class
ExpressionsBasedModel.Simplifier<ME extends ModelEntity<?>,
S extends ExpressionsBasedModel.Simplifier<?, ?>> static final class
(package private) static class
(package private) static final class
Nested classes/interfaces inherited from interface org.ojalgo.optimisation.Optimisation
Optimisation.Constraint, Optimisation.ConstraintType, Optimisation.Model, Optimisation.Objective, Optimisation.Options, Optimisation.ProblemStructure, Optimisation.Result, Optimisation.Sense, Optimisation.Solver, Optimisation.State
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate static final List
<ExpressionsBasedModel.Integration<?>> private final Map
<String, Expression> private final Set
<Structure1D.IntIndex> private boolean
private boolean
private Optimisation.Result
private BigDecimal
private Optimisation.Sense
private final Set
<Structure1D.IntIndex> private boolean
private final boolean
A shallow copy may share complex/large data structures with other models - typically the Map:s holding Expression parameters.private final Set
<Structure1D.IntIndex> Temporary storage for some expression specific subset of variablesprivate BiConsumer
<ExpressionsBasedModel, Access1D<BigDecimal>> private final ExpressionsBasedModel.VariablesCategorisation
private static final String
private static final String
private static final String
final Optimisation.Options
(package private) static final TreeSet
<ExpressionsBasedModel.Presolver> private static final String
-
Constructor Summary
ConstructorsConstructorDescriptionExpressionsBasedModel
(ExpressionsBasedModel modelToCopy, boolean shallow, boolean prune) ExpressionsBasedModel
(Optimisation.Options optimisationOptions) -
Method Summary
Modifier and TypeMethodDescriptionaddExpression
(String name) static boolean
addIntegration
(ExpressionsBasedModel.Integration<?> integration) Add an integration for a solver that will be used rather than the built-in solvers(package private) void
addObjectiveConstant
(BigDecimal addition) static boolean
addPresolver
(ExpressionsBasedModel.Presolver presolver) (package private) void
addReference
(Structure1D.IntIndex index) void
addSpecialOrderedSet
(Collection<Variable> orderedSet, int min, int max) Calling this method will create 2 things: A simple expression meassuring the sum of the (binary) variable values (the number of binary variables that are "ON").void
addSpecialOrderedSet
(Collection<Variable> orderedSet, int type, Expression linkedTo) Creates a special ordered set (SOS) presolver instance and links that to the supplied expression.addVariable
(String name) bounds()
boolean
checkSimilarity
(Expression potential) static void
static void
Returns a prefiltered stream of expressions that are constraints and have not been markes as redundant.copy()
copy
(boolean relax) copy
(boolean shallow, boolean prune) int
int
(package private) int
deriveAdjustmentRange
(Expression expression) describe()
Counts variables and expressions of different categories.void
dispose()
Cleanup when a model instance is no longer needed.(package private) Stream
<Expression> getExpression
(String name) (package private) ExpressionsBasedModel.Integration
<?> (package private) Optimisation.Result
(package private) BigDecimal
The default optimisation sense isOptimisation.Sense.MIN
If this model was read from a file and that file format contained information about being a minimisation or maximisation model, that info is reflected here.Returns a list of the variables that are not fixed at a specific value and whos range include positive values and/or zero(package private) Set
<Structure1D.IntIndex> (package private) BiConsumer
<ExpressionsBasedModel, Access1D<BigDecimal>> getVariable
(int index) getVariable
(Structure1D.IntIndex index) getVariableValues
(NumberContext validationContext) Null variable values are replaced with 0.0.int
int
indexOfFreeVariable
(int globalIndex) int
indexOfFreeVariable
(Variable variable) int
indexOfFreeVariable
(Structure1D.IntIndex variableIndex) int
indexOfIntegerVariable
(int globalIndex) int
indexOfIntegerVariable
(Variable variable) int
indexOfIntegerVariable
(Structure1D.IntIndex variableIndex) int
indexOfNegativeVariable
(int globalIndex) int
indexOfNegativeVariable
(Variable variable) int
indexOfNegativeVariable
(Structure1D.IntIndex variableIndex) int
indexOfPositiveVariable
(int globalIndex) int
indexOfPositiveVariable
(Variable variable) int
indexOfPositiveVariable
(Structure1D.IntIndex variableIndex) boolean
boolean
Objective or any constraint has quadratic part.boolean
boolean
boolean
(package private) boolean
isFixed()
(package private) boolean
(package private) boolean
isInteger
(Set<Structure1D.IntIndex> variables) (package private) boolean
(package private) boolean
isReferenced
(Variable variable) (package private) boolean
(package private) boolean
(package private) boolean
limitObjective
(BigDecimal lower, BigDecimal upper) maximise()
minimise()
newExpression
(String name) newVariable
(String name) This is generated on demand – you should not cache this.private Optimisation.Result
optimise()
static ExpressionsBasedModel
Apart from the "native" EBM file format, currently only supports the MPS file format, but with some of the various extensions.static ExpressionsBasedModel
parse
(InputStream input, ExpressionsBasedModel.FileFormat format) <T extends IntermediateSolver>
Tprepare
(Function<ExpressionsBasedModel, T> factory) The general recommendation is to NOT call this method directly.(package private) void
presolve()
reduce()
Will try to indentify constraints with equal variables set, and check if those can be combined or not.void
relax()
void
relax
(boolean soft) void
removeExpression
(String name) static boolean
removeIntegration
(ExpressionsBasedModel.Integration<?> integration) static boolean
removePresolver
(ExpressionsBasedModel.Presolver presolver) static void
private void
(package private) void
(package private) void
setIntegrationSwitch
(boolean value) void
setKnownSolution
(Optimisation.Result knownSolution) Same assetKnownSolution(org.ojalgo.optimisation.Optimisation.Result, BiConsumer)
but with a no-op handler.void
setKnownSolution
(Optimisation.Result knownSolution, BiConsumer<ExpressionsBasedModel, Access1D<BigDecimal>> handler) For test/validation during solver development.(package private) void
setOptimisationSense
(Optimisation.Sense optimisationSense) simplify()
Will perform presolve and then create a copy removing redundant constraint expressions, and pruning the remaining ones to no longer include fixed variables.snapshot()
Will create a shallow copy flagged as relaxed.(package private) Structure1D.IntIndex
toIntIndex
(int index) (package private) Structure2D.IntRowColumn
toIntRowColumn
(int row, int column) toString()
boolean
validate()
This methods validtes model construction only.boolean
validate
(BasicLogger appender) boolean
validate
(Access1D<BigDecimal> solution) boolean
validate
(Access1D<BigDecimal> solution, BasicLogger appender) boolean
validate
(Access1D<BigDecimal> solution, NumberContext context) boolean
validate
(Access1D<BigDecimal> solution, NumberContext context, BasicLogger appender) boolean
validate
(NumberContext context) boolean
validate
(NumberContext context, BasicLogger appender) Returns a stream of variables that are not fixed.void
Save this instance to file.void
writeTo
(InMemoryFile file)
-
Field Details
-
INTEGRATIONS
-
NEW_LINE
- See Also:
-
OBJ_FUNC_AS_CONSTR_KEY
-
OBJECTIVE
- See Also:
-
START_END
- See Also:
-
PRESOLVERS
-
options
-
myExpressions
-
myFixedVariables
-
myInfeasible
private transient boolean myInfeasible -
myIntegrationSwitch
private boolean myIntegrationSwitch -
myKnownSolution
-
myObjectiveConstant
-
myOptimisationSense
-
myReferences
-
myRelaxed
private boolean myRelaxed -
myShallowCopy
private final boolean myShallowCopyA shallow copy may share complex/large data structures with other models - typically the Map:s holding Expression parameters. -
myTemporary
Temporary storage for some expression specific subset of variables -
myValidationFailureHandler
-
myVariables
-
myVariablesCategorisation
-
-
Constructor Details
-
ExpressionsBasedModel
public ExpressionsBasedModel() -
ExpressionsBasedModel
-
ExpressionsBasedModel
ExpressionsBasedModel(ExpressionsBasedModel modelToCopy, boolean shallow, boolean prune)
-
-
Method Details
-
addIntegration
Add an integration for a solver that will be used rather than the built-in solvers -
addPresolver
-
clearIntegrations
public static void clearIntegrations() -
clearPresolvers
public static void clearPresolvers() -
parse
Apart from the "native" EBM file format, currently only supports the MPS file format, but with some of the various extensions. In particular it is possible to parse QP models using QUADOBJ or QMATRIX file sections. -
parse
public static ExpressionsBasedModel parse(InputStream input, ExpressionsBasedModel.FileFormat format) -
removeIntegration
-
removePresolver
-
resetPresolvers
public static void resetPresolvers() -
addExpression
-
addExpression
-
addSpecialOrderedSet
Creates a special ordered set (SOS) presolver instance and links that to the supplied expression. When/if the presolver concludes that the SOS "constraints" are not possible the linked expression is marked as infeasible. -
addSpecialOrderedSet
Calling this method will create 2 things:- A simple expression meassuring the sum of the (binary) variable values (the number of binary
variables that are "ON"). The upper, and optionally lower, limits are set as defined by the
max
andmin
parameter values. - A custom presolver (specific to this SOS) to be used by the MIP solver. This presolver help to keep track of which combinations of variable values or feasible, and is the only thing that enforces the order.
- Parameters:
orderedSet
- The set members in correct order. Each of these variables must be binary.min
- The minimum number of binary varibales in the set that must be "ON" (Set this to 0 if there is no minimum.)max
- The SOS type or maximum number of binary varibales in the set that may be "ON"
- A simple expression meassuring the sum of the (binary) variable values (the number of binary
variables that are "ON"). The upper, and optionally lower, limits are set as defined by the
-
addVariable
-
addVariable
-
bounds
- Returns:
- A prefiltered stream of variables that are constraints and not fixed
-
checkSimilarity
-
constraints
Returns a prefiltered stream of expressions that are constraints and have not been markes as redundant. -
copy
-
copy
-
copy
-
countExpressions
public int countExpressions() -
countVariables
public int countVariables() -
describe
Counts variables and expressions of different categories. -
dispose
public void dispose()Description copied from interface:Optimisation.Model
Cleanup when a model instance is no longer needed.- Specified by:
dispose
in interfaceOptimisation.Model
-
getExpression
-
getExpressions
-
getFixedVariables
-
getFreeVariables
- Returns:
- A list of the variables that are not fixed at a specific value
-
getIntegerVariables
- Returns:
- A list of the variables that are not fixed at a specific value and are marked as integer variables
-
getNegativeVariables
- Returns:
- A list of the variables that are not fixed at a specific value and whos range include negative values
-
getOptimisationSense
- The default optimisation sense is
Optimisation.Sense.MIN
- If this model was read from a file and that file format contained information about being a minimisation or maximisation model, that info is reflected here.
- In general you are expected to know whether to call
minimise()
ormaximise()
. Once you have called one of those methods this method's return value will match that.
- The default optimisation sense is
-
getPositiveVariables
Returns a list of the variables that are not fixed at a specific value and whos range include positive values and/or zero -
getVariable
-
getVariable
-
getVariables
-
getVariableValues
-
getVariableValues
Null variable values are replaced with 0.0. If any variable value is null the state is set to INFEASIBLE even if zero would actually be a feasible value. The objective function value is not calculated for infeasible variable values. -
indexOf
-
indexOfFreeVariable
public int indexOfFreeVariable(int globalIndex) - Parameters:
globalIndex
- General, global, variable index- Returns:
- Local index among the free variables. -1 indicates the variable is not a free variable.
-
indexOfFreeVariable
-
indexOfFreeVariable
-
indexOfIntegerVariable
public int indexOfIntegerVariable(int globalIndex) - Parameters:
globalIndex
- General, global, variable index- Returns:
- Local index among the integer variables. -1 indicates the variable is not an integer variable.
-
indexOfIntegerVariable
-
indexOfIntegerVariable
-
indexOfNegativeVariable
public int indexOfNegativeVariable(int globalIndex) - Parameters:
globalIndex
- General, global, variable index- Returns:
- Local index among the negative variables. -1 indicates the variable is not a negative variable.
-
indexOfNegativeVariable
-
indexOfNegativeVariable
-
indexOfPositiveVariable
public int indexOfPositiveVariable(int globalIndex) - Parameters:
globalIndex
- General, global, variable index- Returns:
- Local index among the positive variables. -1 indicates the variable is not a positive variable.
-
indexOfPositiveVariable
-
indexOfPositiveVariable
-
isAnyConstraintQuadratic
public boolean isAnyConstraintQuadratic() -
isAnyExpressionQuadratic
public boolean isAnyExpressionQuadratic()Objective or any constraint has quadratic part. -
isAnyObjectiveQuadratic
public boolean isAnyObjectiveQuadratic() -
isAnyVariableFixed
public boolean isAnyVariableFixed() -
isAnyVariableInteger
public boolean isAnyVariableInteger() -
limitObjective
-
maximise
- Specified by:
maximise
in interfaceOptimisation.Model
-
minimise
- Specified by:
minimise
in interfaceOptimisation.Model
-
newExpression
-
newVariable
-
objective
This is generated on demand – you should not cache this. More specifically, modifications made to this expression will not be part of the optimisation model. You define the objective by setting theModelEntity.weight(Comparable)
/ModelEntity.weight(Comparable)
on one or more variables and/or expressions.- Returns:
- The generated/aggregated objective function
-
prepare
The general recommendation is to NOT call this method directly. Instead you should use/call
maximise()
orminimise()
.The primary use case for this method is as a callback method for solvers that iteratively modifies the model and solves at each iteration point.
With direct usage of this method:
- Maximisation/Minimisation is undefined (you don't know which it is)
- The solution is not written back to the model
- The solution is not validated by the model
-
reduce
Will try to indentify constraints with equal variables set, and check if those can be combined or not. This is a relatively slow process with small chance to actually achieve somthing. Therefore it is not part of the default presolve ochsimplify()
functionality.- See Also:
-
relax
public void relax() -
relax
public void relax(boolean soft) - Parameters:
soft
- If true the integer variables are still identified as such, but the model is flagged as non-integer (will not use theIntegerSolver
, but presolve and validation may still recognise the variables' integer property). If false the integer property of any/all variables are removed.
-
removeExpression
-
setKnownSolution
Same assetKnownSolution(org.ojalgo.optimisation.Optimisation.Result, BiConsumer)
but with a no-op handler. -
setKnownSolution
public void setKnownSolution(Optimisation.Result knownSolution, BiConsumer<ExpressionsBasedModel, Access1D<BigDecimal>> handler) For test/validation during solver development.- Parameters:
knownSolution
- The optimal solutionhandler
- What to do if validation fails
-
simplify
Will perform presolve and then create a copy removing redundant constraint expressions, and pruning the remaining ones to no longer include fixed variables. -
snapshot
Will create a shallow copy flagged as relaxed. -
toString
-
validate
public boolean validate()This methods validtes model construction only. All the other validate(...) method validates the solution (one way or another).- Specified by:
validate
in interfaceOptimisation.Model
- Returns:
- true If eveything is ok. false The model is structurally ok, but the "value" breaks constraints - the solution is infeasible.
- See Also:
-
validate
-
validate
-
validate
-
validate
-
validate
-
validate
-
validate
-
variables
Returns a stream of variables that are not fixed. -
writeTo
Save this instance to file. The file format isExpressionsBasedModel.FileFormat.EBM
and the file name is therefore recommended to end with ".ebm".- Parameters:
file
- The path/name of the file to write.
-
writeTo
-
optimise
-
scanEntities
private void scanEntities() -
addObjectiveConstant
-
addReference
-
deriveAdjustmentRange
-
expressions
Stream<Expression> expressions() -
getIntegration
ExpressionsBasedModel.Integration<?> getIntegration() -
getKnownSolution
Optimisation.Result getKnownSolution() -
getObjectiveConstant
BigDecimal getObjectiveConstant() -
getReferences
Set<Structure1D.IntIndex> getReferences() -
getValidationFailureHandler
BiConsumer<ExpressionsBasedModel,Access1D<BigDecimal>> getValidationFailureHandler() -
isFixed
boolean isFixed() -
isInfeasible
boolean isInfeasible() -
isInteger
-
isIntegrationSwitch
boolean isIntegrationSwitch() -
isReferenced
-
isRelaxed
boolean isRelaxed() -
isShallowCopy
boolean isShallowCopy() -
isUnbounded
boolean isUnbounded() -
presolve
void presolve() -
setInfeasible
void setInfeasible() -
setIntegrationSwitch
void setIntegrationSwitch(boolean value) -
setOptimisationSense
-
toIntIndex
-
toIntRowColumn
-