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 (XPRS_TOK_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
XPRS_TOK_COL	column	index of matrix column.
XPRS_TOK_CON	constant	(double) value.
XPRS_TOK_DEL	delimiter	XPRS_DEL_COMMA (1) = comma (",")
		XPRS_DEL_COLON (2) = colon (":")
XPRS_TOK_EOF	end of formula	not required: use zero
XPRS_TOK_FUN	user function	index of function
XPRS_TOK_IFUN	internal function	index of function
XPRS_TOK_LB	left bracket	not required: use zero
XPRS_TOK_OP	operator	XPRS_OP_UMINUS (1) = unary minus ("-")
		XPRS_OP_EXPONENT (2) = exponent ("**" or "^")
		XPRS_OP_MULTIPLY (3) = multiplication ("*")
		XPRS_OP_DIVIDE (4) = division ("/")
		XPRS_OP_PLUS (5) = addition ("+")
		XPRS_OP_MINUS (6) = subtraction ("-")
XPRS_TOK_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:

XPRS_TOK_DEL	comma is optional.
XPRS_TOK_FUN	implies a following left-bracket, which is not included explicitly.
XPRS_TOK_IFUN	implies a following left-bracket, which is not included explicitly.
XPRS_TOK_LB	never used.
XPRS_TOK_RB	only used to terminate the list of arguments to a function.

Brackets are not used to set the evaluation order 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
XPRS_TOK_COL	index of x
XPRS_TOK_OP	XPRS_OP_EXPONENT
XPRS_TOK_CON	2
XPRS_TOK_OP	XPRS_OP_PLUS
XPRS_TOK_CON	4
XPRS_TOK_OP	XPRS_OP_MULTIPLY
XPRS_TOK_COL	index of y
XPRS_TOK_OP	XPRS_OP_MULTIPLY
XPRS_TOK_LB	0
XPRS_TOK_COL	index of z
XPRS_TOK_OP	XPRS_OP_MINUS
XPRS_TOK_CON	3
XPRS_TOK_RB	0
XPRS_TOK_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
XPRS_TOK_COL	index of x
XPRS_TOK_CON	2
XPRS_TOK_OP	XPRS_OP_EXPONENT
XPRS_TOK_CON	4
XPRS_TOK_COL	index of y
XPRS_TOK_OP	XPRS_OP_MULTIPLY
XPRS_TOK_COL	index of z
XPRS_TOK_CON	3
XPRS_TOK_OP	XPRS_OP_MINUS
XPRS_TOK_OP	XPRS_OP_MULTIPLY
XPRS_TOK_OP	XPRS_OP_PLUS
XPRS_TOK_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
XPRS_TOK_COL	index of y
XPRS_TOK_OP	XPRS_OP_MULTIPLY
XPRS_TOK_FUN	index of MyFunc
XPRS_TOK_LB	0
XPRS_TOK_COL	index of z
XPRS_TOK_DEL	XPRS_DEL_COMMA
XPRS_TOK_CON	3
XPRS_TOK_RB	0
XPRS_TOK_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
XPRS_TOK_COL	index of y
XPRS_TOK_RB	0
XPRS_TOK_CON	3
XPRS_TOK_DEL	XPRS_DEL_COMMA
XPRS_TOK_COL	index of z
XPRS_TOK_FUN	index of MyFunc
XPRS_TOK_OP	XPRS_OP_MULTIPLY
XPRS_TOK_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 XPRS_TOK_FUN token.