![]() |
MAiNGO
|
The most convenient way of modeling with MAiNGO is to use ALE (https://git.rwth-aachen.de/avt.svt/public/libale.git), which provides a framework for writing logical-algebraic expressions. The input can be written as .txt files in ALE syntax. An exemplary problem.txt file can be found in exampleAleParser/problem.txt
.
The ALE syntax uses data types to decide which expressions can appear in which context. All data types are constructed from the basic types real, index, and boolean and potentially derived types such as set and tensor. Every expression has one of the following types:
In the context of modeling in MAiNGO, optimization variables are real scalars or tensors, while the objective function is a real scalar. Furthermore, constraints are boolean scalars, which result from comparison operations (inequalities and equalities) on real scalars. Finally, indexes are used to dereference tensors and sets can be used in expressions that expand over all their elements.
The input file is structured into sections, which are initiated with an appropriate keyword (e.g., definitions) followed by a colon (:). Within each section, there may be zero, one, or more statements, which are each terminated by a semicolon (;). At any point in the input file, the pound symbol (#) may be used to initiate an end-of-line comment, meaning that all input between the pound symbol and the end of the current line is ignored. Finally, whitespace characters have no meaning except that they serve to separate keywords.
Symbols are named entities that refer to fixed values, variables, or expressions of a particular type. The names used are allowed to contain letters, numbers, and underscores and must start with a letter. All symbols must be defined in a definitions section of an input file which is initiated by
A single input file may have arbitrarily many definitions sections that may be empty or contain arbitrarily many definitions. However, since symbols can only be used once they have been defined, it is advisable to collect all definitions in a single definitions section at the beginning of the input file.
All definitions begin with a declarator indicating the desired data type (e.g., real, index, or boolean) and are terminated with a semicolon.
The following are valid definitions of different scalar parameters (fixed values), which are assigned using the definition operator (:=) operator:
For the definition of a tensor parameter its length in each dimension must be provided in square brackets after the declarator. Furthermore, vector values are written in parentheses as a comma-separated list of entries. Similarly, tensor values are written in terms of their subvectors (i.e., matrices are vectors of vectors, and so on). The following are valid definitions of different tensor parameters:
For convenience, tensors can also be initialized with a scalar:
Particular entries of tensors or values of scalars can later be changed using the assignment operator (<-). A colon (:) can be used to indicate an assignment for all values of a particular index:
In the context of assignments, it is important to note that all expressions provided for modeling are evaluated late, meaning that only the final value of a parameter symbol has any impact on the model.
For the definition of sets, the declarator is composed of the keyword set and the desired element type in braces. Therein, tensor-valued elements are denoted using the same notation as above with a colon instead of the tensor lengths. Similarly, set values are denoted as comma-separated lists in braces. Contiguous index set values can be denoted in short-hand as shown below. The following are valid definitions of different set parameters:
Variable symbols can be defined using largely the same syntax as parameters with the difference that variables are not assigned values but bound intervals using the in operator. Furthermore, variables can only be real scalars or tensors. The following are valid definitions of different scalar and tensor variables:
Note in the above example that one or both bounds of a tensor variable may be provided as a single scalar.
Integral variables can be defined by replacing the real declarator by either binary or integer. In the case of a binary variable, no bounds can be assigned ass they are implicit. The following are valid definitions of different binary and integer variables:
Similar to the assignment of parameter values, the lower bound, upper bound, and initial point of a variable symbol can be assigned using the assignment operator (<-) and the appropriate suffix for the variable name (lb, ub, or init):
Expression symbols are similar to parameter symbols with the difference that they do not hold a basic value but rather an arbitrary expression of the appropriate type. In contrast to parameter symbols, expression symbols can only be real, index, or boolean scalars. The syntax for defining expression symbols is identical to the one for parameter symbols with the difference an expression is assigned instead of a constant. For further information on what constitutes a valid expression, refer to Expressions. The following are valid definitions of different scalar expressions:
Note that upon evaluating the input, expression symbols are substituted by their expression and don't become optimization variables. As such, they can be used to write reduced-space formulations in a procedural way.
Beyond the definitions section, there are several sections for defining expressions such as the objective function. While the examples provided here should be self-explanatory, a more detailed discussion of possible expressions is provided in Expressions.
The objective function to be minimized must be defined in an objective section of an input file which is initiated by
Each objective section may only contain a single real scalar expression with an optional description in quotes (" ") and terminated by a semicolon (;):
If multiple objective sections are present in a file, the last defined objective function will be used.
Optionally, additional outputs can be defined in an outputs section of an input file which is initiated by
Each outputs section may contain arbitrarily many scalar real expressions, each with an optional description in quotes (" ") and terminated by a semicolon (;):
Upon completion of an optimization, the additional outputs will be evaluated at the optimal solution and reported.
Constraints must be defined in a constraints section of an input file which is initiated by
Each constraints section may contain arbitrarily many boolean scalar expressions, each with an optional description in quotes (" ") and terminated by a semicolon (;). MAiNGO will only accept constraints that either result from a weak inequality, an equality, or a set-based expansion over a weak inequality or an equality (see Scalar Boolean Expressions). Note that this restriction does not preclude the use of general boolean expressions in the context of indicator sets (see Set Expressions)
Relaxation-only constraints (see Advanced Modeling) must be defined in a relaxation only constraints section of an input file which is initiated by
These constraints must satisfy the same conditions as regular constraints and are denoted in the same way (see Constraints Section).
Squashing constraints (see Advanced Modeling) must be defined in a squashing constraints section of an input file which is initiated by
These constraints must satisfy the same conditions as regular constraints and are denoted in the same way (see Constraints Section). Furthermore, they must result from a weak inequality or a set-based expansion over a weak inequality.
The following are the contents of a valid input file
The ALE syntax for denoting expressions is similar to other established modeling languages and should be mostly intuitive. In the following, the different expression types and the allowed operators are discussed:
The basic building blocks of real scalar expressions are constants, symbol names, and entries of real tensors. Constants can be any real number written in floating-point or scientific notation as shown above in the definition of symbols. Entries of tensors are accessed by bracket notation as shown above for the assignment of tensor entries. Operators are defined for addition (+), subtraction (-), multiplication (*), division (/), and exponentiation (^). Parentheses are used to enforce precedence and to denote arguments to functions. For a complete list of implemented functions beyond the standard functions (exp(), log(), sin(), asin(), etc.), refer to doc/implementedFunctions/Implemented_functions.pdf. The following are valid real expressions:
For convenience, ALE provides the following set-based expressions that expand over a set of any given type:
Note however, that the min and max function can also be used without set expansion:
Similar to real expressions, the basic building blocks of index expressions are constants, symbol names, and entries of real tensors. However, index expressions and therefore also constants and the values of symbols can only take whole values. By the same token, only the operators for addition (+), subtraction (-), and multiplication (*) are defined for indexes. Parentheses are used to enforce precedence.
The basic building blocks of boolean expressions are constants, symbol names, and entries of real tensors. Furthermore, boolean expressions result from the comparison operators (<, <=, =, >=, >). Boolean expressions and therefore also constants and the values of symbols can only be true or false. Operators are defined for conjunction (&), disjunction (|), and negation (!). Parentheses are used to enforce precedence. The following are valid boolean expressions:
Furthermore, ALE provides a set-based conjunction similar to the set-based real expressions:
The basic building blocks of set expressions are constants and symbol names. These basic sets can be refined by employing an indicator set, which only contains those elements that satisfy a logical condition:
Another way of modeling with MAiNGO is to directly work with the C++ API. If you are not interested in the development of an own Model class simply use the exemplary C++
implementation, that can be found in exampleCppApi/problem.h
and proceed with the next subsection.
For communicating an optimization problem to MAiNGO, you need to implement a specialization of the MAiNGOmodel class. Your specialization of the MAiNGOmodel class needs to implement at least the following functions:
Additionally, you may do the following in your specialization of MAiNGOmodel:
Within the evaluate function, you can do almost any type of computation (including calling other functions / libraries), as long as they are implemented with mc::FFVar. It is not allowed to use loops with a number of iteration not known a priori (such as, e.g., solving a nonlinear equation system), and to use conditional statements. For a list of intrinsic functions supported by MAiNGO, refer to the documentation in doc/implementedFunctions/Implemented_functions.pdf
.
If your model does contain equations that would require iterative solution, you need to leave appropriate optimization variables and equations to the optimizer instead (cf. Bongartz & Mitsos, J. Global Optim 69 (2017) 761).
Using conditional statements that give non-smooth or discontinuous functions is not possible directly, since computing valid relaxations always requires information on the entire domain. Such statements can however be reformulated, either through the use of implemented non-smooth functions like the maximum of two functions, or using the methods for relaxation of discontinuous functions introduced by Wechsung et al., J. Global Optim. 63 (2015) 1. As an alternative, one can also resort to mixed integer formulations.
For the constraints, it is important to manually scale all constraints for the relevant terms to be of the order of one, since constraint tolerances are only implemented as absolute values.
You can also specify constraints that are to be used only in the relaxation, not in the original problem (cf. Sahinidis & Tawarmalani, J. Global Optim. 32 (2005) 259). To this end, the EvaluationContainer returned by the evaluate function contains the vectors ineqRelaxationOnly and eqRelaxationOnly. This can be useful when adding redundant constraints that would complicate the local solution of the original problem but might tighten the relaxations. Note that adding incorrect relaxation-only constraints may lead to false infeasibility claims or other spurious behavior of the optimization process.
You may add OutputVariables to the output vector in the EvaluationContainer. This can be used to compute and return information that is not needed during the optimization but that you are interested in at the optimal solution.
If you are using the squash_node function, it is neccessary to introduce appropriate squash inequalities in order to maintain correctness of the optimization problem. For more information refer to doc/implementedFunctions/Implemented_functions.pdf
.
We also provide a tool for parsing GAMS convert files to ALE problem.txt or MAiNGO problem.h files. For detailed description please refer to utilities/MAiNGO_Reader_Writer/
and the documentation found therein.