The DP Specification Language gDPS
3.3 Detailed Description of the gDPS Sections
This section focuses on the details of how to generate a specification file in the “general DP specification” (gDPS) language. Such a file constitutes one possible input format for the DP2PN2Solver software. Section 3 already gave an overview of the gDPS language. Here we examine each language construct in more detail. A gDPS source file always begins with key word BEGIN and ends with the keyword END and its body consists of several structured sections, each of which we will consider in more detail now.
At any point in the body of the gDPS file, one may have block comments that start with /* and end with */ and one-line comments that start with // and extend to the end of the line. Comments and white-space characters such as blanks, tabs and newlines (CR and LF) do not have any functionality associated with them, except that they act as token separators for the parser of the DP2PN module.
3.3.1 Name Section
The mandatory Name section begins with the keyword NAME followed by the name you would like to assign to your particular model, followed by a semi-colon. This is a logical name, which does not have to match the file name of your gDPS source; however it seems good practice to match them. For exam-ple, you might have a gDPS file named tsp2005.dp and your name section might read
NAME TravelingSalesperson;
Since the logical model name is used for naming intermediate files and output files, it is prudent to use only names that do not cause trouble for your oper-ating system’s file name conventions (i.e. avoid special symbols and blanks).
3.3.2 General Variables Section
The optional General Variables section begins with the keyword GENERAL_
VARIABLES_BEGIN and ends with the keyword GENERAL_VARIABLES_END. It allows the definition of variables and constants in a C++/Java style syntax.
A legal variable name starts with a character from the alphabet{a, . . . , z, A, . . . , Z} and may be followed by any number of alphanumerical charac-ters from the alphabet{a, . . . , z, A, . . . , Z, 0, 1, . . . , 9}. Variable names are case sensitive.
As a general rule, if a variable definition is legal in Java, then it is also legal in gDPS. In order to emphasize the global scope of the variables defined in this section, we adopted the Java convention to declare variables as static, and in order to emphasize that the variables defined in this section are to be accessed exclusively within a gDPS file, we adopted the convention to declare variables as private. Constants carry the qualifier final.
Integer Type
In order to define and initialize a variable of integral type, the int keyword is used, followed by a legal variable name, the equation (or equal-sign) character, an integer literal and a semicolon. For example,
private static int n=5;
defines an integer variable n which is initialized to the value 5.
Constants of Java classes can be used as well, as can be seen in the example private static final int infty=Integer.MAX_VALUE;
where we define an infinity constant infty to be the maximally representable integer as provided in java.lang.Integer.MAX_VALUE.
Floating Point Type
In order to define and initialize a variable of floating point type, the double keyword is used, followed by a legal variable name, the equal-sign character, a floating point literal and a semicolon. For example,
private static double x3=3.14;
defines a floating point variable x3 which is initialized to the value 3.14.
String Type
In order to define and initialize a variable of String type, the String keyword is used, followed by a legal variable name, the equal-sign character, a string literal (in quotes) and a semicolon. For example,
private static String s="Hello";
defines a string variable s which is initialized to “Hello”.
Array Types
Array variables can be defined and initialized by placing a pair of brackets for each dimension after the type declaration, and by using (nested) lists, enclosed in braces, for initialization purposes. For example,
private static double[][] myMatrix=
{
{ -2.5, 13 , -0.2 }, { 3 , 4.0, 1.234}, };
defines and initializes a 2-dimensional array of doubles, representing a 2× 3 matrix. We can reference the value 1.234 via myMatrix[1][2] in the usual way.
As is typical for Java arrays, the index count or subscript in each dimension starts with 0, not 1.
The length of an array dimension can be determined using the length con-struct. Thus, the number of rows and columns of myMatrix can be determined as follows:
private static int m=myMatrix.length; //m=2 private static int n=myMatrix[0].length; //n=3
3.3.3 Set Variables Section
The optional Set Variables section begins with the keyword SET_VARIABLES_
BEGIN and ends with the keyword SET_VARIABLES_END. It provides a compact and flexible way to define and initialize set variables and constants.
A legal set variable name follows the same rules as a general variable name, it cannot start with a numerical chracter. Set definitions do not take private and static modifiers. Those are added internally by the compiler, which generates NodeSet objects for each variable or constant defined as Set in this section. The NodeSet type is a subclass of java.util.TreeSet; we discuss this further in the next section.
A variable or constant defined in this section starts with the keyword Set, an equals character, and then a variety of notations are available to specify the set.
1. To resemble the common mathematical notation, all elements may be enumerated within braces. Duplicate elements are ignored. The order in which elements are enumerated is irrelevant.
2. Ellipsis is supported with the following subrange syntax: an opening brace, followed by the smallest element to be in the set, followed by two dots, followed by the largest element to be in the set, followed by a closing brace.
3. The empty set∅ is defined as {}.
4. If s1 and s2 are correctly defined sets, then the set union s1∪ s2 is ex-pressed using the keyword SETUNION instead of the mathematical symbol
∪.
5. If s1 and s2 are correctly defined sets, then the set intersection s1∩ s2 is expressed using the keyword SETINTERSECTION instead of the mathemat-ical symbol∩.
6. If s1 and s2 are correctly defined sets, then the set difference s1− s2 is expressed using the keyword SETMINUS instead of the mathematical symbol−.
7. The binary set operators mentioned above can be nested, the default hi-erarchy (set difference has highest priority, then set intersection, then set union) can be overridden by using parenthesization.
All sets are assumed to contain a finite number of integer typed elements.
Each set variable definition is terminated with a semicolon. For example, Set enumeratedSet={5,2,2,3,7,2};
defines and initializes the set{2, 3, 5, 7}.
In another example,
Set subrangeSet={1,..,n};
defines and initializes a set that contains all positive integers up to (and including) n, where n must be defined in the General Variables section.
3.3.4 General Functions Section
The optional General Functions section begins with the keyword GENERAL_
FUNCTIONS_BEGIN and ends with the keyword GENERAL_FUNCTIONS_END. It provides a flexible way to define functions in Java syntax.
As a general rule, if a function (method) definition is legal in Java, then it is also legal in gDPS. In order to emphasize the global, non-object oriented character of the functions defined in this section, we adopted the Java con-vention to declare functions as “static”, and in order to emphasize that the functions defined in this section are to be accessed exclusively within a gDPS file, we adopted the convention to declare functions as “private”.
For set types the use of class type NodeSet (which is subclassed from the standard Java class java.util.TreeSet and named so for legacy rea-son) is recommended in order to be most compatible with sets specified in the set variables section. Since java.util.TreeSet implements the stan-dard Java interface java.util.SortedSet all sets are actually understood as sorted sets, which is sometimes advantageous. For instance, in the gDPS source of the BST problem (Sect. 2.6) we can conveniently split a set using the headSet() method. Additional useful methods such as tailSet(), subSet(), etc., are documented in the Java 2 SDK 1.4.2 API specification (available at http://java.sun.com).
For example, assume we are given the adjacency matrix distance[][] of a directed graph in the general variables section, where ∞-entries represent edges that are not present in the graph. Given a node node we can compute the set of adjacent nodes using the function
private static NodeSet possibleNextNodes(int node) { NodeSet result = new NodeSet();
for (int i=0; i<distance[node].length; i++) { if (distance[node][i]!=infty) {
result.add(new Integer(i));
} }
return result;
}
where infty is a constant declared in the general variables section. This function uses a conventional Java for-loop and an if-statement to detect whether an index should be included in the resulting set result which is eventually returned. The NodeSet object result inherits the methods from java.util.TreeSet, so we use the add() method to add integers to the re-sulting set result. Since in Java sets are containers of objects, we need to wrap the primitive int type into an Integer object.
3.3.5 State Type Section
The mandatory State Type section begins with the keyword STATE_TYPE, followed by a colon, the parameter list, and ends with a semicolon. For our definition of DP, a state is considered to be an ordered, fixed-length tuple of parameters. Each parameter has a type and a name. Permissible parameter types are int and Set. The parameter list is enclosed in a pair of parenthe-ses and parameters are separated by commas; this resembles the Java style parameter list for functions. For example,
STATE_TYPE: (int stage, Set s1, int x, Set s2);
defines a DP problem where a state is an ordered quadruple (stage, s1, x, s2) consisting of an integer, a set, an integer, and another set, respectively.
3.3.6 Decision Variable Section
The mandatory Decision Variable section begins with the keyword DECISION_
VARIABLE, followed by a colon, the decision variable type, the decision variable name, and ends with a semicolon. All decisions are considered to be choices from a finite set, so at this point we can assume without loss of generality that the decision variable type be int. The decision variable name follows the usual requirement for Java identifiers (cannot start with a digit). For example, DECISION_VARIABLE: int d;
declares the decision variable for this DP problem to be d.
3.3.7 Decision Space Section
The mandatory Decision Space section begins with the keyword DECISION_
SPACE, followed by a colon, the decision set function name and parameter list, the equal-sign symbol, the decision set (which can expressed in various ways), and ends with a semicolon. Since the current decision set under consideration depends on the current state, the parameter list is populated with precisely those variables that make up a state (see state type section). The decision set is the space of alternatives, one of which gets to be chosen to be in the optimal policy; it has to be of type Set and can be expressed in one of the following ways.
1. Explicitly build a set using complete enumeration or subrange syntax, possibly using variables from the parameter list. For example, if a state is a pair of integers, then
DECISION_SPACE: decisionSet(i,j)={i,..,j - 1};
characterizes the decision set as the set containing all integers between the first index i and the second index j, including i but excluding j.
2. Delegate the task of building the decision set, or parts of it, to a function specified in the general functions section, which provides a set-typed re-turn value. For example, if a state consists of a single integer representing the current node, then
DECISION_SPACE: possibleAlternatives(currentNode)
=possibleNextNodes(currentNode);
delegates the task of computing the decision set possibleAlternatives to the function possibleNextNodes() defined in the General Functions section.
3. If S1 and S2 are correctly defined sets, it is possible to form the union S1∪ S2, the intersection S1∩ S2and the set difference S1− S2using the keywords SETUNION, SETINTERSECTION and SETMINUS, respectively, as was the case in the Set Variables section.
3.3.8 Goal Section
The mandatory Goal section describes the computational goal of the DP in-stance at hand. It begins with the keyword GOAL, followed by a colon, the identifier of the DPFE functional, and then, within parentheses, a goal state is declared by providing a suitable value for each parameter of the state. This can be done by either providing an explicit numerical value, or by providing a symbolic variable or constant defined in the general variables section. The section ends with a semicolon. For example, if a state is a triple consisting of two integers, followed by a set, then
GOAL: f(7,n,goalSet);
assumes that n is predefined integer variable or constant and that goalSet is a predefined set variable or constant. The goal of our computation has been reached once we have evaluated f (7, n, goalSet).
3.3.9 DPFE Base Section
The mandatory DPFE Base section is used to define base cases or conditions to terminate the recursive evaluation of a DPFE. There are two alternative ways of specifying the base of a DPFE. Exactly one of these two possibilities must be present in a gDPS file.
The first possibility is to express the base cases in a conditional fashion.
The section begins with the keyword DPFE_BASE_CONDITIONS, followed by a colon, followed by one or more base condition statements. Each base condition statement starts with the DPFE functional and its parameter list (see DPFE section), followed by an equal-sign character and an arithmetic expression that evaluates to a floating point number (see the reward function section for details about arithmetic expressions). This is followed by the keyword WHEN, a conditional expression in parentheses and a semicolon, which designates the end of a base condition statement. The conditional expression may consist of numerical conditions involving Java style operators to compare numbers (or numerical variables or constants), such as <, <=, >, >=, !=, ==. Sets (or set variables) can be compared for equality using the keyword SETEQUALS.
Atomic conditions can be combined using the logical boolean operators &&
(“and”), || (“or”), ! (“not”); conditions can be nested, if desired, and the default hierarchy for evaluating the logical operations can be influenced by using parentheses. Every conditional expression evaluates to either “true” or
“false”. For example, if a state is a pair of integers, then DPFE_BASE_CONDITIONS:
f(i,j)=0.0 WHEN (i==j);
f(i,j)=1.0 WHEN (i>j) && (i<9) && (j>5);
designates states such as (1, 1), (2, 2), etc. as base states which get assigned the value 0.0 (by the first base condition statement). The second base condition statement designates the states (8, 6), (8, 7), and (7, 6) as base states, which get assigned the value 1.0. If a state is a set, then
DPFE_BASE_CONDITIONS:
f(currentSet)=4.0 WHEN (currentSet SETEQUALS {3,4});
f(currentSet)=8.0 WHEN (currentSet SETEQUALS {5,..,8});
designates the state ({3, 4}) as a base state, which gets assigned the value 4.0 and designates the state ({5, 6, 7, 8}) as a base state, which gets assigned the value 8.0.
The second possibility is to express the base cases in an enumerative way.
The section begins with the keyword DPFE_BASE, followed by a colon, followed by one or more DPFE base statements. A DPFE base statement can be an
assignment statement, or a block of possibly nested for-loops that contain as-signment statements within its body. Each asas-signment statement starts with the DPFE functional and an argument list, enclosed in parentheses, that pro-vides suitable values for each of the components that make up a state. This is followed by an equal-sign symbol, an expression that evaluates to a floating point number, and a semicolon, which designates the end of an assignment statement. For example, assuming the set variable setOfAll defined in the set variables section is valued {0, 1, 2, 3} and the array distance is defined and initialized in the general variables section with distance[1][0] equaling 7.5, then
DPFE_BASE:
f(0,setOfAll)=0.0 ;
f(1,setOfAll)=distance[1][0];
designates the state (0,{0, 1, 2, 3}) to be a base state, which gets assigned the value 0.0 (by the first assignment statement). The second assignment state-ment designates the state (1,{0, 1, 2, 3}) as a base state, which gets assigned the value 7.5.
The for-loop notation allows a convenient shortcut when consecutive inte-gers are involved in assignment statements:
DPFE_BASE:
FOR(i=2;i<=10;i++) { f(emptySet,i)=0.0;
}
In a DP model, one has to be careful to make sure that every DPFE base case that can occur during the computation is actually covered in this section.
No damage is done, if a base case is covered more than once, provided that the same value is assigned.
3.3.10 DPFE Section
The mandatory DPFE section describes the recursive equation that is at the center of a DP model. It begins with the keyword DPFE, followed by a colon, the DP functional name and parameter list which is populated with precisely those variables that make up a state (see state type section). Then there is an equal-sign symbol, followed by either the MAX_ or MIN_ operator indicating the direction of optimization, followed by an opening brace, the decision variable as defined in the decision variable section, the keyword IN, the decision set identifier as defined in the decision space section, followed by a closing brace.
Then, within the next pair of braces, will be the DP functional, possibly more than once, performing the recursive call(s) after applying a transformation function to it, and also the call to the reward function. All these function-als must be connected by either the addition or multiplication operator. The parameter lists of the transformation functions and of the reward function is
populated with precisely those variables that make up a state (see state type section) and in addition with the decision variable, since the transformation function value and the reward function value are in general dependent on both the state and the decision. The DPFE section ends with a semicolon. Option-ally, each recursively invoked functional may be multiplied with a weight, which must itself be expressed as a function in the transition weight section.
The multiplication symbol for these weights is “.” (dot), to distinguish it from the “*” (star) symbol used in other contexts.
As a first example, if a state consists of a pair (i, j) of integers, then DPFE: f(i,j)
=MIN_{k IN decisionSet}
{ f(t1(i,j,k)) +f(t2(i,j,k)) +r(i,j,k) };
specifies a DPFE whose functional is named f . There are two recursive calls via the two transformation functions t1 and t2. The reward function is named r, and all functionals are connected by “+” resulting in an additive DPFE.
In the following example DPFE: fun(a,b)
=MAX_{m IN myAlternatives}
{ fun(t(a,b,m))
*cost(a,b,m) };
there is only a single recursive call to fun via the transformation function t.
It is connected to the reward functional cost by the multiplication operator
“*” resulting in a multiplicative DPFE.
Assuming there are transition weights p1and p2specified in the transition weight section, the following example
DPFE: f(i,j)
=MAX_{d IN decisionSet}
{ p1.f(t1(i,j,d)) +p2.f(t2(i,j,d)) +r(i,j,d)
};
shows an additive DPFE with two recursive calls via the transformation func-tions t1 and t2 the result of each of which is weighted with the floating point values p1and p2respectively. For details about the calculation of the weights, please refer to the Transition Weight section.
3.3.11 Cost/Reward Function Section
The mandatory Reward Function section defines the cost or profit function referenced in the DPFE. If a DP model does not need a reward function, it can be defined to be a constant function, equaling the identity element of addition (i.e. 0) or multiplication (i.e. 1), depending on whether we have an additive or multiplicative DPFE. The section begins with the keyword REWARD_FUNCTION, followed by a colon, the identifier of the reward function as used in the DPFE section and the parameter list which contains the identifiers of the state components, and the decision variable. Then there is an equal-sign symbol followed by an arithmetic expression that evaluates to a floating point number. This expression may involve the parameters. A semicolon denotes the end of the Reward Function section. For example, in
REWARD_FUNCTION: rew(i,j,k)
=myArr[i]*myArr[j]*myArr[k];
the reward function is named rew and the expression it evaluates to is a product of three array variables from the array myArr.
In addition to the usual arithmetic operators such as addition (+), sub-traction (-), multiplication (*), integer or real-vauled division (/), and integer remainder (%) there is the possibility to delegate more complicated arithmetic to a helper function defined in the general functions section. For example, in REWARD_FUNCTION: r(stage,remainingMoney,m)
=reliabilityOfStage(stage,m);
the calculation of the reward is performed by a helper function named reliabilityOfStage, which happens to require only two of the three pa-rameters as arguments (i.e. the reward is independent of the parameter remainingMoney). The helper function is assumed to return a floating-point value of type double.
3.3.12 Transformation Function Section
The mandatory Transformation Function section defines the one or more next-state transformation (or transition) functions referenced in the DPFE. It be-gins with the keyword TRANSFORMATION_FUNCTION, followed by a colon, and a semicolon separated list of function definitions.
Since a transformation function computes the next-state when provided with the current state and the decision taken, a suitable definition starts with the function identifier as used in the DPFE section and the parameter list, which contains the identifiers of the state components and the decision variable. Then there is an equal-sign symbol followed by a parenthesized list of expressions, each of which evaluates to an integer or to a set, depending on the definition of what constitutes a state. Any expression may involve the parameters. A semicolon denotes the end of a transformation function definition. In the example
TRANSFORMATION_FUNCTION: t1(i,j,k)
=(i,k);
t2(i,j,k)
=(k+1,j);
there are two transformation functions t1and t2, each of which maps a state, represented by a pair of integers (i, j) and a decision k to a new state. The new state is (i, k) in case of t1and it is (k + 1, j) in case of t2. The arithmetic operators +,-,*,/,% can be used for state components that are integers.
For state components that are sets it is possible to use the set operator keywords SETUNION, SETINTERSECTION and SETMINUS. For example, if the state is a pair of an integer x and a set nSet, and y is the decision variable, then
TRANSFORMATION_FUNCTION: t(x,nSet,y)
=(y, nSet SETUNION {y});
defines the transformation function t in the following way: the new state’s first component is the integer y and the second component is the set that results from adding the element y to the set nSet. More complex transformation functions may require use of helper functions. For example, exponentiation, maximization, minimization, etc. have to be delegated to a helper function in the General Functions section. There, methods of java.lang.Math such as abs(), ceil(), floor(), exp(), max(), min(), pow(), etc., can be used.
3.3.13 Transition Weight Section
The optional Transition Weight section describes the transition weights that may precede the recursive function calls in the DPFE. It is assumed that the number of transition weights and the order in which the transition weights are defined in this section matches the number and order of the corresponding transformation functions, according to the DPFE.
The section begins with the keyword TRANSITION_WEIGHTS, followed by a colon, and a semicolon separated list of real-valued transition weight function definitions.
A transition weight function definition begins with the identifier of the transition weight as used in the DPFE section, followed by the parameter list which contains the identifiers of the state components, and the decision vari-able. Then there is an equal-sign symbol followed by an arithmetic expression that evaluates to a floating point number (see the reward function section for details about legal arithmetic expressions). A semicolon denotes the end of the transition weight function definition. For example,
TRANSITION_WEIGHTS: p1(n,sn,xn)=1.0-winProbability;
p2(n,sn,xn)=winProbability;
defines the two transition weight functions p1 and p2 which in this case are both constant functions independent of the state and the decision.