[Previous] [Next]

Func (General SLP function)

---

Purpose

Func provides a uniform syntax for implementing functions (particularly user functions) within an SLP problem.

Synopsis

Func (fName:string [, arg1:real|mpvar|linctr|XV|gexp
 [, arg2:real|mpvar|linctr|XV|gexp]] [, rIndex:string]) :gexp

Arguments

fName	string containing the name of the function being evaluated. This can be an Xpress-SLP internal function or a user-defined function
arg1	(optional) first argument to the function. This can be of any type (real, mpvar or expression) acceptable to the function. Arguments of type XV are always acceptable, provided the items in the XV are of the correct type
arg2	(optional) second argument to the function. The requirements are the same as for arg1
rIndex	(optional) string indicating the index or name of the return value from the function. This is only required when the function returns an array of values

Return value

For most purposes, Func can be regarded as returning a gexp which contains the requested evaluation of the function.
Strictly speaking, Func returns a gexp describing how to call the specified function, and the evaluation of the function then returns a real value.

Example

The following code fragment shows two user functions:
mySin takes one input value and returns its sine
myArea takes pairs of values in (r,theta) co-ordinates and calculates the area of the polygon whose vertices are the origin and these points in order.

function mySin(Values:array(vRange:range) of real,
               nValue:integer) :real
  returned:= sin(Values(vRange(1)))
end-function

function myArea (Values:array(vRange:range) of real,
               nValue:integer) :real
 declarations
 	r1,r2: real		! distances
 	t1,t2: real		! angles
 	area: real
 end-declarations
 
 area := 0
 forall (n in 1..nValue-3) do
 	r1 := Values(vRange(n))
 	t1 := Values(vRange(n+1))
 	r2 := Values(vRange(n+2))
 	t2 := Values(vRange(n+3))
 	area += 0.5*r1*r2*sin(t2-t1)
 end-do
 returned := area
end-function

These functions can be used in formulae within the model. Formulae like

declarations
  A:array(1..n) of real
  V:real
end-declarations
  V := mySin(A,1)
  V := myArea(A,6)

are ordinary instances of a Mosel function, and will calculate a value based on the values in A at the time the function is encountered. If we want to include the functions inside a constraint, with values taken from mpvars, then the function needs to be wrapped so that its formula is retained. Func is used for this purpose as the following examples show:

declarations
  A:array(1..n) of xvitem
  R,Theta:array(1..m) of mpvar
  X, Obj:mpvar
  V:real
  BigArray:array(1..n) of real
end-declarations
  SLPDATA("UF","mySin","","DOUBLE,INTEGER","MOSEL","Model","BigArray")
  SLPDATA("UF","myArea","","DOUBLE,INTEGER","MOSEL","Model","BigArray")
  cos(X) <= 0.9
  Func("cos",X) <= 0.9
  Func("mySin",X) >= 0.5
  forall (i in 1..m) do 
    A(i*2-1) := R(i)
    A(i*2) := Theta(i)
  end-do
  Obj = Func("myArea",A)

The constraint
 cos(X) 0.9
is interpreted as a formula rather than a value because (a) the argument X is not a constant and (b) cos is recognized as an SLP intrinsic function.

The first usage of Func is effectively the constraint
 cos(X) 0.9
that is, it is the same as the previous constraint. Func is not required because cos is already known as an SLP intrinsic function.

The second usage of Func is effectively the constraint
 sin(X) 0.5
Func is necessary here, because mySin is not known as an SLP function when the model is compiled (it is defined at execution time by the SLPDATA procedure). Although mySin is defined as receiving an array of values, there is no need to supply an array in the Func implementation.

The third usage sets the variable Obj equal to the area of the polygon whose vertices are defined by the pairs of values (R(i),Theta(i)). Because there are more than two values being passed to the function, the information is passed using an XV (array of xvitems) which can hold any number of items of any type.

[Previous] [Next] [Index]

---

If you have any comments or suggestions about these pages, please send mail to docs@dashoptimization.com.