JOM (Java Optimization Modeler)

The syntax of JOM Expressions is quite similar to that of MATLAB or Octave languages, and the manner in which they handle matrices and multidimensional arrays. For those familiar with MATLAB or Octave, the main point to remember is that JOM uses 0-indexing for all the arrays (of variables or input parameters). Then, the first element in any coordinate of an array has the index 0 and not the index 1. E.g. in an 5x5x5 array the first element is (0,0,0), and the last element is (4,4,4).

In the next subsections we will try to cover the key concepts within JOM Expressions: scalar constants, ...

1. Numerical constants

Numerical constants are of course valid JOM expressions themselves, and take part of other expressions. The following code uses the parseExpression method to create an Expression object with an scalar constant, and then prints it.

Expression e = new OptimizationProblem ().parseExpression("1.34");

System.out.println("Value of e: " + e.evaluate().get(0)); // e is an scalar expression, I take its first cell which is a double

2. 2-D Matrix constants

Two dimensional matrices, composed of constants or of other expressions, can be created in JOM, using a slightly different syntax than MATLAB. As in MATLAB, matrices start with the [ character and end with the ] character. The difference is that in JOM we use the character ; for separating elements in the same row, and ;; for separating rows among them. As an example, the matrix:

\( c = \left( \begin{array}{cc} 7 & 1 & 4 \\ 5 & 2 & 6 \end{array} \right) \)

Can be defined as a JOM Expression with the code:

Expression c = new OptimizationProblem ().parseExpression("[7 ; 1 ; 4 ;; 5 ; 2 ; 6]");

System.out.println("Value of c: " + c.evaluate()); 

3. Accessing the elements in an array: indexing

Given an array of decision variables, or an input parameter, it is possible to access individual cells of the array in two different forms: (i) providing the coordinates or subindexes of the cell (recall the 0-indexing!!), and (ii) directly specifying the so-called linear index of the cell (again first cell of an array has index 0, not 1). JOM syntax and behaviour in this, is very much similar to MATLAB and Octave.

Let c be the same input parameter as in previous section. The following code illustrate some examples on how to access a cell from its coordinates:

System.out.println ("c(0,2) = " + op.parseExpression("c(0,2)").evaluate()); // this prints number 4

System.out.println ("c(1,2) = " + op.parseExpression("c(1,2)").evaluate()); // this prints number 6

System.out.println ("c(0,0) = " + op.parseExpression("c(0,0)").evaluate()); // this prints number 7

As in MATLAB and Octave, each cell in an array has a linear index associated. In JOM , first index is index 0 (while in MATLAB start in 1). As in MATLAB, indexes grow first filling the first dimension, then the second, then the third.... For instance, in a 2x3x2 array x, the indexes are:

System.out.println ("c(0) = " + op.parseExpression("c(0)").evaluate()); // this prints number 7

System.out.println ("c(3) = " + op.parseExpression("c(3)").evaluate()); // this prints number 2

System.out.println ("c(6) = " + op.parseExpression("c(6)").evaluate()); // error index out of bounds

3. Accessing ranges of elements in an array: subarrays

Given an array (of decision variables or an input parameter), it is possible to access ranges of cells (subarrays), in a very similar manner as MATLAB makes (see this page for details on the MATLAB syntax). Let's continue with the c input parameter before. There are two manners of creating subarrays:

• Providing one array of linear indexes. For instance c([1 ; 0 ; 5]) returns a 1x3 vector with three elements of c, with the given indexes. The clausule "all" means all the indexes of the array. c(all) is the same as c. Ranges of indexes can be defined with the operator :, as in MATLAB. For instance, c(1:4) is the same as c([1; 2 ; 3 ;4]).

System.out.println ("c([1 ; 4 ; 1]) = " + op.parseExpression("c([1 ; 4 ; 1])").evaluate()); // returns [5 ; 4 ; 5]

System.out.println ("c([1 ;; 4 ;; 1]) = " + op.parseExpression("c([1 ;; 4 ;; 1])").evaluate()); // returns [5 ;; 4 ;; 5]

System.out.println ("c([0 ; 2 ;; 1 ; 2]) = " + op.parseExpression("c([0 ; 2 ;; 1 ; 2])").evaluate()); // returns [7 ; 1 ;; 5 ; 1]

System.out.println ("c(2:4) = " + op.parseExpression("c(2:4)").evaluate()); // returns [1 ; 2 ; 4]

System.out.println ("c(all) = " + op.parseExpression("c([all])").evaluate()); // returns [7 ; 5 ; 1 ; 2 ; 4 ; 6]

• Providing arrays of subindices, one for each coordinate. For instance c ([0 ; 0 ] , [1 ; 2]) returns an array of size 2x2, with the first row of c repeated twice, but with only the last two columns. In a coordinate, the clausule "all" is equivalent to all the subindexes in that coordinate. For instance, c(1,all) is the same as c(1,[0 ; 1 ; 2]). The operator : can be used also here to define ranges. c(0 , 0:2) is equivalent to c(0 , [0 ; 1 ; 2])

System.out.println ("c(1 , all) = " + op.parseExpression("c(1,all)").evaluate()); // returns [5 ; 2 ; 6]

System.out.println ("c(0:1 , 0:1) = " + op.parseExpression("c(0:1,0:1)").evaluate()); // returns [7 ; 1 ;; 5 ; 2]

System.out.println ("c([0 ; 1 ; 0] , [1 ; 1 ; 2]) = " + op.parseExpression("c([0 ; 1 ; 0] , [1 ; 1 ; 2])").evaluate()); // returns [7;1;4 ;; 2;2;6 ;; 1;1;4]

As a final remark, we note the differences between MATLAB and JOM syntax when handling indexing of arrays:

• JOM uses 0-indexing, and MATLAB 1-indexing
• Both in MATLAB and JOM you can use the operator : to specify ranges. For instance 0:3 is equal to the expression [0 ; 1 ; 2 ; 3]. However, MATLAB permits using the operator : twice like in 0:2:8, which means "the numbers from 0 to 8, in steps of 2". In JOM it is not possible to define the step, and the previous expression raises an error.
• In MATLAB, using : as the single index in an coordinate means "all the elements in this coordinate". The same meaning exists in JOM using the reserved word all.
• The end tag in MATLAB is a reference to the index of the last element in a dimension. JOM has no such end tag.

4. Operators

Operators combine one or more expressions, producing another expression. The JOM parser applies the operators following a set priorities (for instance, product of expressions is evaluated before the sum). These priorities are the usual ones (similar as in MATLAB and "all" programming languages), and can be modified using parenthesis in the typical form (i.e. x + y * 5 is equivalent to x + (y * 5), if we want to apply the sum first we have to write (x+y)*5).

Internally, JOM computes for each expression (i) which are the decision variables involved, and thus knows if the expression is a constant (depends on no decision variable), and (ii) if it is linear with respet to the decision variables. In this latter case the expression is stored internally in a compact numerical format. Tracking this information is needed to effectively handle the interface with the solvers.

The following table summarizes the operators in JOM and their main information. In our examples, c is the same 2x3 matrix as the one used above, and x is a decision variable of the same size as c.

5. Functions

Similarly to operators, functions combine one or more expressions, producing another expression. Functions must be derivable. JOM is able to automatically compute the first derivative (jacobian matrix) for each expression. This is needed to autonomously interact with non-linear solvers like IPOPT.

The following table summarizes the built-in functions in JOM and their main information. The amount if functions in JOM is expected to keep growing in future releases.