Xpress NonLinear Formulae

Topics covered in this chapter:

Xpress NonLinear can handle formulae described in three different ways:

Character strings

The formula is written exactly as it would appear in, for example, the Extended MPS format used for text file input.

Internal unparsed format

The tokens within the formula are replaced by a
{token type, token value} pair. The list of types and values is in the table below.

Internal parsed format

The tokens are converted as in the unparsed format, but the order is changed so that the resulting array forms a reverse-Polish execution stack for direct evaluation by the system.

Parsed and unparsed formulae

All formulae input into Xpress NonLinear are parsed into a reverse-Polish execution stack. Tokens are identified by their type and a value. The table below shows the values used in interface functions.

All formulae are provided in the interface functions as two parallel arrays:
 an integer array of token types;
 a double array of token values.

The last token type in the array should be an end-of-formula token (XSLP_EOF, which evaluates to zero).

If the value required is an integer, it should still be provided in the array of token values as a double precision value.

Even if a token type requires no token value, it is best practice to initialize such values as zeros. In particular, any other provided values will generally not be preserved when queried later.

Type	Description	Value
XSLP_COL	column	index of matrix column.
XSLP_CON	constant	(double) value.
XSLP_DEL	delimiter	XSLP_COMMA (1) = comma (",")
		XSLP_COLON (2) = colon (":")
XSLP_EOF	end of formula	not required: use zero
XSLP_FUN	user function	index of function
XSLP_IFUN	internal function	index of function
XSLP_LB	left bracket	not required: use zero
XSLP_OP	operator	XSLP_UMINUS (1) = unary minus ("-")
		XSLP_EXPONENT (2) = exponent ("**" or "^")
		XSLP_MULTIPLY (3) = multiplication ("*")
		XSLP_DIVIDE (4) = division ("/")
		XSLP_PLUS (5) = addition ("+")
		XSLP_MINUS (6) = subtraction ("-")
XSLP_RB	right bracket	not required: use zero

When a formula is passed to Xpress NonLinear in "internal unparsed format" — that is, with the formula already converted into tokens — the full range of token types is permitted.

When a formula is passed to Xpress NonLinear in "parsed format" — that is, in reverse Polish — the following rules apply:

XSLP_DEL	comma is optional.
XSLP_FUN	implies a following left-bracket, which is not included explicitly.
XSLP_IFUN	implies a following left-bracket, which is not included explicitly.
XSLP_LB	never used.
XSLP_RB	only used to terminate the list of arguments to a function.

Brackets are not used in the reverse Polish representation of the formula: the order of evaluation is determined by the order of the items on the stack. Functions which need the brackets — for example XPRSslpgetcoefstr — fill in brackets as required to achieve the correct evaluation order. The result may not match the formula as originally provided.

Example of an arithmetic formula

x²+4y(z-3)

Written as an unparsed formula, each token is directly transcribed as follows:

Type	Value
XSLP_COL	index of x
XSLP_OP	XSLP_EXPONENT
XSLP_CON	2
XSLP_OP	XSLP_PLUS
XSLP_CON	4
XSLP_OP	XSLP_MULTIPLY
XSLP_COL	index of y
XSLP_OP	XSLP_MULTIPLY
XSLP_LB	0
XSLP_COL	index of z
XSLP_OP	XSLP_MINUS
XSLP_CON	3
XSLP_RB	0
XSLP_EOF	0

Written as a parsed formula (in reverse Polish), an evaluation order is established first, for example:

x  2  ^  4  y  *  z  3  -  *  +

and this is then transcribed as follows:

Type	Value
XSLP_COL	index of x
XSLP_CON	2
XSLP_OP	XSLP_EXPONENT
XSLP_CON	4
XSLP_COL	index of y
XSLP_OP	XSLP_MULTIPLY
XSLP_COL	index of z
XSLP_CON	3
XSLP_OP	XSLP_MINUS
XSLP_OP	XSLP_MULTIPLY
XSLP_OP	XSLP_PLUS
XSLP_EOF	0

Notice that the brackets used to establish the order of evaluation in the unparsed formula are not required in the parsed form.

Example of a formula involving a simple function

y*MyFunc(z,3)

Written as an unparsed formula, each token is directly transcribed as follows:

Type	Value
XSLP_COL	index of y
XSLP_OP	XSLP_MULTIPLY
XSLP_FUN	index of MyFunc
XSLP_LB	0
XSLP_COL	index of z
XSLP_DEL	XSLP_COMMA
XSLP_CON	3
XSLP_RB	0
XSLP_EOF	0

Written as a parsed formula (in reverse Polish), an evaluation order is established first, for example:

y  )  3  ,  z  MyFunc(  *

and this is then transcribed as follows:

Type	Value
XSLP_COL	index of y
XSLP_RB	0
XSLP_CON	3
XSLP_DEL	XSLP_COMMA
XSLP_COL	index of z
XSLP_FUN	index of MyFunc
XSLP_OP	XSLP_MULTIPLY
XSLP_EOF	0

Notice that the function arguments are in reverse order, and that a right bracket is used as a delimiter to indicate the end of the argument list. The left bracket indicating the start of the argument list is implied by the XSLP_FUN token.