\input texinfo @c -*-texinfo-*-
@c %**start of header
@setfilename language
@settitle GLPK/L Modeling Language
@setchapternewpage odd
@exampleindent 0
@c %**end of header

@ifinfo
Sorry, this document is not intended to be formatted as @samp{info}.
@bye
@end ifinfo

@ifhtml
Sorry, this document is not intended to be formatted as @samp{html}.
@bye
@end ifhtml

@titlepage
@title GLPK
@subtitle GNU Linear Programming Kit
@subtitle Version 2.4
@subtitle Modeling Language GLPK/L
@subtitle May 2001
@author Andrew Makhorin
@page
@vskip 0pt plus 1filll
The GLPK package is a part of the GNU project, released under the aegis of GNU.

Copyright @copyright{} 2000, 2001 Andrew Makhorin, Department for Applied
Informatics, Moscow Aviation Institute, Moscow, Russia. All rights reserved.

Free Software Foundation, Inc., 59 Temple Place --- Suite 330, Boston, MA
02111, USA.

Permission is granted to make and distribute verbatim copies of this manual
provided the copyright notice and this permission notice are preserved on all
copies.

Permission is granted to copy and distribute modified versions of this manual
under the conditions for verbatim copying, provided also that the entire
resulting derived work is distributed under the terms of a permission notice
identical to this one.

Permission is granted to copy and distribute translations of this manual into
another language, under the above conditions for modified versions.
@end titlepage

@contents

@chapter Introduction

@tex
GLPK/L modeling language is intended for writing mathematical programming
models. The name GLPK/L is derived from \underbar{G}NU \underbar{L}inear
\underbar{P}rogramming \underbar{K}it \underbar{L}anguage.

Model description written in the GLPK/L language consists of a sequence of
statements constructed by the user from the language elements described in
this document.

In a process called translation, a program called the language processor
analyzes the model description statements and translates them into internal
data structures, which may be then used either for generating mathematical
programming problem data or directly by a program called the solver for
obtaining numerical solution of the problem.

GLPK/L modeling language is a part of the GLPK package.
@end tex

@chapter Basic Concepts

@section Mathematical programming problem

GLPK/L assumes the following formulation of mathematical non-linear
programming (NLP) problem @footnote{Processing model description written in
GLPK/L assumes generating data for mathematical programming problem.
Although currently the GLPK package is designed for linear and mixed integer
linear programming problems only, the GLPK/L modeling language is suitable
to express linear as well as non-linear problems. That's why the general
formulation is given here.}:

@tex
\parindent = 0 in
\leftskip = 1 in
minimize (or maximize)
$$Z = x_{obj} \eqno (2.1)$$
subject to (non-linear) constraints
$$\matrix{
x_1 = f_1(x_{m+1}, x_{m+2}, \dots, x_{m+n}) \cr
x_2 = f_2(x_{m+1}, x_{m+2}, \dots, x_{m+n}) \cr
\dots \dots \dots \cr
x_m = f_m(x_{m+1}, x_{m+2}, \dots, x_{m+n}) \cr
} \eqno (2.2)
$$
and bound of variables
$$\matrix{
l_1 \leq x_1 \leq u_1 \cr
l_2 \leq x_2 \leq u_2 \cr
\dots \cr
l_{m+n} \leq x_{m+n} \leq u_{m+n} \cr
} \eqno (2.3)
$$
\leftskip = 0 in
\settabs
\+ where: & xxxxxxxxxxxxxxxxxxx & \cr
\+ where: & $x_1, x_2, \dots, x_m$ & --- rows or auxiliary variables; \cr
\+ & $x_{m+1}, x_{m+2}, \dots, x_{m+n}$ & --- columns or structural
variables; \cr
\+ & $Z$ & --- objective function; \cr
\+ & $obj$ & --- number of row, which defines the objective function; \cr
\+ & $f_1, f_2, \dots, f_m$ & --- non-linear functions, which define the
equality constraints; \cr
\+ & $l_1, l_2, \dots, l_{m+n}$ & --- lower bounds of variables; \cr
\+ & $u_1, u_2, \dots, u_{m+n}$ & --- upper bounds of variables. \cr
@end tex

@tex
If all the functions $f_1, f_2, \dots, f_m$ are linear, the problem
(2.1)---(2.3) is linear programming (LP) problem. LP differs from NLP only in
the system of equality constraints (2.2), which in case of LP is the
following:
$$\matrix{
x_1 = a_{11} x_{m+1} + a_{12} x_{m+2} + \dots + a_{1n} x_{m+n} \cr
x_2 = a_{21} x_{m+1} + a_{22} x_{m+2} + \dots + a_{2n} x_{m+n} \cr
\dots \dots \dots \cr
x_m = a_{m1} x_{m+1} + a_{m2} x_{m+2} + \dots + a_{mn} x_{m+n} \cr
} \eqno (2.4)
$$
where $a_{11}, a_{12}, \dots, a_{mn}$ are constraints coefficients.

Auxiliary variables are called \it rows\rm, because they correspond to rows of
the constraint matrix (i.e. matrix formed by constraint coefficients as in the
case of LP problem). Analogously, structural variables are called \it
columns\rm, because they correspond to columns of the constraint matrix.

Bounds of variables can be finite as well as infinite. Besides, lower and upper
bounds can be equal to each other. Thus, the following types of variables are
possible:

$$\vbox{
\settabs 3 \columns
\+ \hfil Bounds of variable & Type of variable \cr
\+ \hrulefill & \hrulefill & \cr
\+ \hfil $-\infty < x_k < +\infty$ & Free (unbounded) variable & \cr
\+ \hfil $l_k \leq x_k < +\infty$ & Variable with lower bound & \cr
\+ \hfil $-\infty < x_k \leq u_k$ & Variable with upper bound & \cr
\+ \hfil $l_k \leq x_k \leq u_k$ & Double-bounded variable & \cr
\+ \hfil $l_k = x_k = u_k$ & Fixed variable & \cr
}
$$
@end tex

@noindent
Note that types of variables shown above are applicable to structural as well
as to auxiliary variables.

In addition to LP and NLP problems GLPK/L allows mixed integer linear or
non-linear programming (MIP) problems, in which some variables are required to
be integer. GLPK/L assumes that MIP problem has the same formulation as
ordinary (pure) LP or NLP problem, i.e. includes structural and auxiliary
variables, which may have lower and/or upper bounds. Note that GLPK/L allows
only structural variables to be of integer kind.

@section Model expressions

@tex
Principal constituents of the system of equality constraints (2.2) are
functions $f_1, f_2, \dots, f_m$ of structural variables. In GLPK/L it is
assumed that these functions may be expressed in the form of so called model
expressions.

\it Model expression \rm is an algebraic formula built of numeric constants,
structural variables, and arithmetic operators.

For example, the formula
$$x + 2 \cdot (y - 3 \cdot z) + 4.5$$
is a model expression, where $x, y, z$ are structural variables;
$2, 3, 4.5$ are numeric constants; $+, -, \cdot$ are arithmetic operators.

In GLPK/L model expressions are used as "values", which can be assigned to
some language objects (like, say, floating-point numbers can be assigned to
variables in programming languages). In this sense the language objects are
close to objects of computer algebra systems. Although model expressions
have special internal representation, the user can think them as character
strings that express the corresponding formulae.

Being algebraic objects, model expression allows all the operations, which are
applicable to numbers. Let, for example, $e_1$ and $e_2$ are the following
model expressions:
$$\eqalign{
e_1 &= x + 2 \cdot y \cr
e_2 &= z + 1 \cr
}
$$
@end tex

@noindent
@tex
Then it is possible to compute, say, the sum of $e_1$ and $e_2$:
$$e = e_1 + e_2 = x + 2 \cdot y + z + 1,$$
where $e$ is the resultant model expression.

It is understood that ordinary numeric constants may be considered as a
particular case of model expressions.

Model expression, which contain no structural variables, is called \it
constant model expression\rm. The language processor always reduces constant
model expressions to the form of numeric constants. On the other hand, if at
least one model expression participating in operation is not a constant
expression, the language processor keeps the resultant expression "as is",
preforming no algebraic transformations. Let, for example,
$e_1 = 2 \cdot x + 1$ and $e_2 = 3 \cdot x + 2$. Addition of $e_1$ and $e_2$
will give the resultant expression in the form
$e = e_1 + e_2 = 2 \cdot x + 1 + 3 \cdot x + 2$ in spite of that it can be
reduced to $e = 5 \cdot x + 3$.

In order to attach a model expression to a particular constraint the
assignment statement should be used (see Section 6.1).

So far as currently the GLPK package is able to solve linear problems only,
all model expressions that define equality constraints should be linear.

\it Linear model expression \rm has the following recursive definition:

1. Constant model expression is linear model expression.

2. Structural variable is linear model expression.

3. Let $e_1$ and $e_2$ are linear model expressions, $c$ is constant model
expression. Then expressions $+e_1$, $-e_1$, $e_1 + e_2$, $e_1 - e_2$,
$c \cdot e_1$, $e_1 \cdot c$, and $e_1 / c$ are linear model expressions.

4. No else is linear model expression.

For example, the expression
$$x + 2 \cdot (y - 3 \cdot x) / (10 + 2.5) - 4.5$$
is linear model expression, but the expression
$$x + 2 \cdot (y - 3 \cdot x) / (10 + 2.5 \cdot x) - 4.5$$
is not.
@end tex

@section Model objects

@tex
The GLPK/L modeling language is designed to simplify preparing problem data,
especially in case of large-scale problems.

So far as components of mathematical programming problems are usually
correspond to entities of the real world, composing such problems is called
\it modeling\rm, and a description of such problems expressed in a formal
modeling language is called \it mathematical model \rm or just \it model\rm.

In GLPK/L model is described in terms of sets, parameters, predicates,
variables, and constraints, which are called \it model objects\rm.

The user introduces particular model objects using declaration statements.
Each model object is provided with a symbolic name, which uniquely identifies
this object and is intended for referencing purposes.
@end tex

@subsubheading Sets

@tex
\it Set \rm is a collection of elementary abstract objects called \it items\rm.

Each set and each item have a symbolic name given by the user in the set
declaration statement.

Set can contain arbitrary number of items. Different sets can't contain the
same item.

In GLPK/L sets are used only as index sets (domains).
@end tex

@subsubheading Parameters

@tex
\it Parameter \rm is a multidimensional array built over sets. A particular
element of parameter is called \it parameter member\rm. Within array each
parameter member is uniquely identified by its subscript list called
\it tuple\rm, which is an ordered sequence of items of the corresponding index
sets.

Number of sets, over which a parameter is built (i.e. number of items in each
parameter member), is called \it dimension\rm. In the current version of the
language parameters can be built over up to 6 sets. 0-dimensional parameter is
called \it scalar parameter\rm.

Each parameter has a symbolic name given by the user in the parameter
declaration statement. Parameter members have no individual names.

Parameters have sparse structure. This means that some (or all) parameter
members may be missing.

If a parameter member exist, it always has an assigned value. Values assigned
to parameter members are model expressions (see Section 2.2). So far as model
expressions may have the form of numeric constants, parameters are also able
to represent ordinary arrays of numeric data.

Formally, a parameter $F$ is the mapping
$$F: S_1 \times S_2 \times \dots \times S_n \rightarrow EXPR, \eqno (2.5)$$
where $S_1 \times S_2 \times \dots \times S_n$ is the Cartesian product of
index sets, over which the parameter $F$ is built, $EXPR$ is the set of model
expressions (expanded with the special value $nil$, to which all missing
parameter members are mapped).

Structure of $n$-dimensional model parameter is schematically shown on
Fig. 2.1.

Note that from the formal definition (2.5) it follows that:

a) all members of a parameter should have different tuples, i.e. multiplets
(members with identical tuples) are not allowed;

b) in case of 0-dimensional (scalar) parameter, the Cartesian product formally
has one element. And so far as sparse parameters are allowed, scalar parameter
can have either one member or no member.
@end tex

@sp 1
@image{doc/fig/glplang1}
@center{Fig. 2.1. Structure of @i{n}-dimensional model parameter}
@sp 1

@subsubheading Predicates

@tex
Predicates have the same structure as parameters, i.e. \it predicate \rm is
a multidimensional array built over sets. However, unlike parameters, predicate
members have no assigned values.

Formally, a predicate $P$ is the mapping
$$P: S_1 \times S_2 \times \dots \times S_n \rightarrow \{true, false\},
\eqno (2.6)$$
where $S_1 \times S_2 \times \dots \times S_n$ is the Cartesian product of
index sets, over which the predicate $P$ is built, $\{true, false\}$ is the set
of Boolean values. Existing predicate members are mapped to $true$, and all
other elements of the Cartesian product are mapped to $false$ (thus, predicates
also have sparse structure).

Structure of $n$-dimensional model predicate is schematically shown on
Fig. 2.2.
@end tex

@sp 1
@image{doc/fig/glplang2}
@center{Fig. 2.2. Structure of @i{n}-dimensional model predicate}
@sp 1

@tex
Predicates are mainly intended for expressing relationships between items,
that may be used for constructing various logical conditions.

As a rule predicates appear as intermediate results, but the user can
explicitly declare a named predicate using the predicate declaration
statement.

May note that predicates are similar to Boolean arrays in programming
languages.
@end tex

@subsubheading Variables

@tex
\it Variable \rm is a multidimensional array built over sets like parameters
and predicates.

Members of variables called \it elemental variables \rm play double role.
Firstly, each elemental variable defines the corresponding structural
variables of the problem. And secondly, each elemental variable being a valid
model expression may be used in the same sense as model expressions assigned
to parameter members.

Formally, a variable $V$ is the mapping
$$V: S_1 \times S_2 \times \dots \times S_n \rightarrow SV, \eqno (2.7)$$
where $S_1 \times S_2 \times \dots \times S_n$ is the Cartesian product of
index sets, over which the variable $V$ is built,
$SV = \{x_{m+1}, x_{m+2}, \dots, x_{m+n}\}$ is the set of structural variables
(see Section 2.1).

Structure of $n$-dimensional model variable is schematically shown on
Fig. 2.3.
@end tex

@sp 1
@image{doc/fig/glplang3}
@center{Fig. 2.3. Structure of @i{n}-dimensional model variable}
@sp 1

@tex
The user introduces variables into the model using the variable declaration
statement, which also creates all elemental variables. As a rule there is no
need to have sparse variables, however, the user may declare a sparse
variable using the predicate-controlled declaration. Note that nothing can be
assigned to variables, because variables are unknown quantities.
@end tex

@subsubheading Constraints

@tex
\it Constraint \rm is a multidimensional array built over sets, i.e. this
model object has the same structure as parameters, predicates, and variables.

Members of constraint called \it elemental constraints \rm play double role.
Firstly, each elemental constraint defines the corresponding equality
constraint of the problem. And secondly, so far as each elemental constraint
has an associate model expression (which defines a function of structural
variables), it may be used in the same sense as model expressions assigned to
parameter members.

Formally, a constraint $C$ is the mapping
$$C: S_1 \times S_2 \times \dots \times S_n \rightarrow EC, \eqno (2.8)$$
where $S_1 \times S_2 \times \dots \times S_n$ is the Cartesian product of
index sets, over which the constraint $C$ is built, $EC$ is the set (the
system) of equality constraints (2.2) of the problem.

Structure of $n$-dimensional model constraint is schematically shown on
Fig. 2.4.
@end tex

@sp 1
@image{doc/fig/glplang4}
@center{Fig. 2.4. Structure of @i{n}-dimensional model constraint}
@sp 1

@tex
The user introduces constraints into the model by means of the constraint
declaration statement. Unlike variables, being declared constraints have no
members. In order to create elemental constraints and assign some model
expressions to them the assignment statement should be used in the same way
as for parameters.
@end tex

@subsubheading Implicit parameters

@tex
Being declared each model variable and each model constraint causes three
implicit parameters to be automatically introduced into the model, which are
\it lo-parameter\rm, \it up-parameter\rm, and \it fx-parameter\rm. These three
parameters have the same dimension and are built over the same sets as the
corresponidng model object.

Members of implicit parameters define the type and bounds of the corresponding
elemental structural or auxiliary variable $x_k$ as shown below:
$$\vbox{
\settabs
\+ Free (unbounded) variablexx & \hfil lo-parameterxx &
   \hfil up-parameterxx & \hfil fx-parameterxx & \cr
\+ \hfil Type of variable & \hfil lo-parameter & \hfil up-parameter &
   \hfil fx-parameter & \cr
\+ \hrulefill & \hrulefill & \hrulefill & \hrulefill & \cr
\+ Free (unbounded) variable & \hfil --- & \hfil --- & \hfil --- & \cr
\+ Variable with lower bound & \hfil $l_k$ & \hfil --- & \hfil --- & \cr
\+ Variable with upper bound & \hfil --- & \hfil $u_k$ & \hfil --- & \cr
\+ Double-bounded variable & \hfil $l_k$ & \hfil $u_k$ & \hfil --- & \cr
\+ Fixed variable & \hfil --- & \hfil --- & \hfil $s_k$ & \cr
}$$
where $l_k$ is lower bound, $u_k$ is upper bound, $s_k$ is fixed value, and
"---" denotes missing parameter member (see also Section 2.1).

Implicit parameters may be used in the same way as explicit parameters.
However, all model expressions assigned to members of implicit parameters
should be constant model expressions (see Section 2.2).

Note that creating a member of one implicit parameter may involve deleting
members of other implicit parameters associated with the same model object.
For example, assigning a constant expression to a member of fx-parameter
will cause deleting members with identical tuple from lo- and up-parameter,
and vice versa.

Implicit parameters allow the user to change types and bounds of elemental
variables as well as to use the current bounds as numeric data for computing
other quantities (if necessary).
@end tex

@chapter Elements of the Language

@section Coding model description

Model description is coded in the plain text format using the following
character set:

@example
<upper case letter> ::= A | B | C | D | E | F | G | H | I | J | K | L |
    M | N | O | P | Q | R | S | T | U | V | W | X | Y | Z
<lower case letter> ::= a | b | c | d | e | f | g | h | i | j | k | l |
    m | n | o | p | q | r | s | t | u | v | w | x | y | z
<letter> ::= <upper case letter> | _ | <lower case letter>
<digit> ::= 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9
<graphic character> ::= ! | # | ( | ) | * | + | , | - | . | / | : | ; |
    < | = | > | [ | ]
<white-space character> ::= SP | HT | CR | NL | VT | FF
<valid character> ::= <letter> | <digit> | <graphic character> |
    <white-space character>
@end example

Only <valid characters> are valid in model description. (However, within
comment sequences any printable characters are allowed; see Section 3.5.)

White-space characters are non-significant. They may be used freely between
syntactic units (see below) to improve readability of model description.
They are also used to separate syntactic units from each other when there is
no other way to do that.

Syntactically model description is a sequence of the following syntactic
units composed from letters, digits, and graphic characters:

@example
<syntactic unit> ::= <symbolic name> | <numeric constant> |
    <delimiter> | <comment sequence>
@end example

Syntactic units are described in the next sections.

@section Symbolic names

@subsubheading Syntax

@example
<symbolic name> ::= <letter> | <symbolic name> <letter> |
    <symbolic name> <digit>
@end example

@subsubheading Examples

@example
alpha
this_is_a_name
P123_abc321_
_12345
@end example

@subsubheading Semantics

Symbolic names are used in a model description to identify model objects in the
following categories: sets, items, parameters, predicates, variables, and
constraints. Symbolic names should be unique, i.e. no objects can have the same
symbolic name.

Maximal length of symbolic names is 31 characters. All symbolic names are
distinct (case sensitive).

Symbolic names are introduced into model description by means of declaration
statements.

In GLPK/L there are some reserved key words, which have fixed meaning and
therefore should not be used as symbolic names. These are:

@example
        and         binary      constraint  constraints display
        end         false       in          integer     maximize
        minimize    model       nil         not         or
        parameter   parameters  predicate   predicates  set
        sets        true        variable    variables   where
@end example

@section Numeric constants

@subsubheading Syntax

@example
<integer constant> ::= <digit> | <integer constant> <digit>
<base constant> ::= <integer constant> | . <integer constant> |
    <integer constant> . | <integer constant> . <integer constant>
<exponent> ::= e <integer constant> | e + <integer constant> |
    e - <integer constant>
<numeric constant> ::= <base constant> | <base constant> <exponent>
@end example

(It is allowed to write the letter @samp{E} instead the letter @samp{e}.)

@subsubheading Examples

@example
0
123
3.14159
56.
.78
123.456e-7
@end example

@subsubheading Semantics

Numeric constants are self-defined literals, which have obvious fixed
meaning.

@page
@section Delimiters

@subsubheading Syntax

@example
<delimiter> ::= # | ( | ) | * | + | , | - | . | / | : | ; | < | = | > |
    [ | ] | ++ | -- | := | <= | >= | !=
@end example

(In case of two-character delimiter there should be no white-space characters
between delimiter characters.)

@subsubheading Semantics

Delimiters are used for different purposes. Their meaning will be explained
below.

@section Comment sequences

@subsubheading Syntax

@example
<comment sequence> ::= /* <any printable and white-space characters> */
@end example

@subsubheading Example

@example
/* This is a comment */
@end example

@subsubheading Semantics

Comment sequences are non-significant syntactic units and ignored by the
language processor. They can appear anywhere in a model description, where
white-space characters are allowed.

The user can provide a model description with a comments in order to improve
its readability and for documenting purposes.

@chapter Declaration Statements

Declaration statements are intended to define certain properties of the model
objects used in the model description, and to associate them with symbolic
names.

No symbolic names may be declared more than once.

@section Set statement

@subsubheading Syntax

@example
<set name> ::= <symbolic name>
<item name> ::= <symbolic name>
<item list> ::= <item name> | <item list> , <item name>
<set declaration> ::= <set name> = ( ) | <set name> = ( <item list> )
<set list> ::= <set declaration> | <set list> , <set declaration>
<set statement> ::= set <set list> ; | sets <set list> ;
@end example

@subsubheading Examples

@example
set colors = (red, green, blue);
sets months = (Jan, Feb, Mar, Apr, May, Jun),
     cities = (Boston, Chicago, Dallas, Memphis, Portland),
     empty = ();
@end example

@subsubheading Semantics

The set statement is intended to declare certain symbolic names to represent
sets and to declare certain symbolic names to represent items (see Section
2.3).

@section Parameter statement

@subsubheading Syntax

@example
<parameter name> ::= <symbolic name>
<set name> ::= <symbolic name>
<domain list> ::= <set name> | <domain list> , <set name>
<parameter declaration> ::= <parameter name> |
    <parameter name> [ <domain list> ]
<parameter list> ::= <parameter declaration> |
    <parameter list> , <parameter declaration>
<parameter statement> ::= parameter <parameter list> ; |
    parameters <parameter list> ;
@end example

@subsubheading Examples

@example
parameter pi;
parameters dist[cities,cities], st[cities,months,cities];
@end example

@subsubheading Semantics

The parameter statement is intended to declare certain symbolic names to
represent model parameters, and to specify sets, over which the parameters
should be built (see Section 2.3).

Being declared a parameter initially has no members. In order to create
some parameter members and to assign some values (i.e. model expressions) to
them the assignment statement should be used (see Section 6.1).

@section Predicate statement

@subsubheading Syntax

@example
<predicate name> ::= <symbolic name>
<set name> ::= <symbolic name>
<domain list> ::= <set name> | <domain list> , <set name>
<predicate declaration> ::= <predicate name> |
    <predicate name> [ <domain list> ]
<predicate list> ::= <predicate declaration> |
    <predicate list> , <predicate declaration>
<predicate statement> ::= predicate <predicate list> ; |
    predicates <predicate list> ;
@end example

@subsubheading Examples

@example
predicate cond[cities,cities];
predicates winter[months], p123;
@end example

@subsubheading Semantics

The predicate statement is intended to declare certain symbolic names to
represent model predicates, and to specify sets, over which the predicates
should be built (see Section 2.3).

Being declared a predicate initially has no members (thus, formally, such
predicate has the Boolean value @samp{false} on all elements of the
corresponding Cartesian product). In order to create some predicate members
(i.e. assign the Boolean value @samp{true} to some elements of the Cartesian
product) the assignment statement should be used (see Section 6.1).

@section Variable statement

@subsubheading Syntax

@example
<variable name> ::= <symbolic name>
<set name> ::= <symbolic name>
<domain list> ::= <set name> | <domain list> , <set name>
<mute letter> ::= <lower case letter>
<qualified letter> ::= <mute letter> in <set name>
<qualified list> ::= <qualified letter> |
    <qualified list> , <qualified letter>
<variable declaration> ::= <variable name> |
    <variable name> [ <domain list> ] |
    <variable name> [ <qualified list> ] where <predicate expression>
<variable declaration> ::= <variable list> |
    <variable declaration> , <variable list>
<variable kind> ::= <empty> | integer | binary
<variable statement> ::= <variable kind> variable <variable list> ; |
    <variable kind> variables <variable list> ;
@end example

@subsubheading Examples

@example
variables x[cities,months], z1, z2, z3;
binary variable t[i in cities, k in cities] where dist[k,i] <= 300;
@end example

@subsubheading Semantics

The variable statement is intended to declare certain symbolic names to
represent model variables, and to specify sets, over which the variables should
be built (see Section 2.3).

Unlike parameters and predicates, elemental variables (i.e. members)
associated with a particular model variable are created by the variable
statement. Note that being initially created and attached to a model variable
an array of elemental variables can't be changed later by other statements.

As it follows from the syntactic definition, the variable declaration has two
different forms.

The first form called @i{simple declaration} is the following:

@example
    <variable name> [ <domain list> ]
@end example

If the simple declaration is used, each element of the Cartesian product (of
sets, over which the variable is built) produces exactly one elemental
variable.

The second form called @i{predicate controlled declaration} is the following:

@example
    <variable name> [ <qualified list> ] where <predicate expression>
@end example

If the predicate controlled declaration is used, the following actions are
performed:

1. Qualified list is processed. All mute letters (see Chapter 5) in the
qualified list should be different.

2. Predicate expression is computed and the resultant predcate is determined
(see Chapter 5). All mute letters of the resultant predicate should be
presented in the qualified list.

3. If the qualified list contains mute letter(s), which are missing in the
resultant predicate, the latter is expanded over set(s) that correspond to the
missing mute letters.

4. Each member of the resultant predicate (after expansion) produces exactly
one elemental variable.

Note that simple declaration is equivalent to predicate-controlled declaration,
where predicate expression is the constant @samp{true}.

If neither @samp{integer} nor @samp{binary} key words appear before the key
word @samp{variable}, all variables listed in the statement (more exactly,
all their elemental variables) are considered as @emph{continuous non-negative}
structural variables. In order to declare @emph{integer non-negative} variables
the key word @samp{integer} should be given before the key word
@samp{variable}. Analogously, in order to declare @emph{binary} variables, i.e.
integer variables whose lower bound is zero and upper bound is one, the key
word @samp{binary} should be given before the key word @samp{variable}.

Note that the variable statement doesn't allow to explicitly specify lower
and/or upper bounds of particular elemental variables. In order to do that the
assignment statement (see Section 6.1) should be used.

@section Constraint statement

@subsubheading Syntax

@example
<constraint name> ::= <symbolic name>
<set name> ::= <symbolic name>
<domain list> ::= <set name> | <domain list> , <set name>
<constraint declaration> ::= <constraint name> |
    <constraint name> [ <domain list> ]
<constraint list> ::= <constraint declaration> |
    <constraint list> , <constraint declaration>
<constraint statement> ::= constraint <constraint list> ; |
    constraints <constraint list> ;
@end example

@subsubheading Examples

@example
constraints r1, r2, rd[cities];
constraint rs[months,colors];
@end example

@subsubheading Semantics

The constraint statement is intended to declare certain symbolic names to
represent model constraints, and to specify sets, over which the constraints
should be built (see Section 2.3).

Being declared a constraint initially has no members (elemental constraints).
In order to create some elemental constraints and to attach some model
expressions to them the assignment statement should be used (see Section 6.1).

@chapter Expressions

@section Prelude

@subsubheading Syntax

@example
<expression> ::= <parameter expression> | <predicate expression>
@end example

@subsubheading Semantics

Parameter expression is a rule for computing parameter. Analogously, predicate
expression is a rule for computing predicate. (Should especially emphasize
that parameter and predicate expressions considered in this chapter and model
expressions discussed in Section 2.2 are absolutely different things. Model
expressions are "values" that can be assigned to parameter or constraint
members, but parameter and predicate expressions are language constructions
used as constituents of statements.)

The result of computation of any (intermediate or final) expression is always
either parameter or predicate. Such temporary objects are implicitly
introduced into a model description by the language processor.

Consider, for example, the following parameter expression:

@example
    a + b * c
@end example

@noindent
This expression is computed by the language processor in the following way:

@example
    t1 := a;
    t2 := b;
    t3 := c;
    t4 := t2 * t3;
    t5 := t1 + t4;
@end example

@noindent
where @code{t1}, @dots{}, @code{t5} are temporary parameters.

@section Mute letters

@subsubheading Syntax

@example
<mute letter> ::= <lower case letter>
@end example

@subsubheading Semantics

Being computed each temporary parameter or predicate (see Section 5.1)
acquires so called mute letters (except scalar parameters and predicates
which need no mute letters).

@i{Mute letter} is an auxiliary object, which denotes an index set. The user
can also think mute letters as symbols (or indices), whose values are items
of the set associated with a mute letter.

In case of designators mute letters are introduced by the user. Otherwise, if
a parameter/predicate is the result of an operation, it automatically inherits
mute letters of operands.

All mute letters associated with index positions of a temporary
parameter/predicate are always different.

Let, for example, the following declaration is given:
@tex
$$\vbox{\+ \tt parameter dist[cities,cities]; \rm \cr}$$
@end tex
and consider the expression
@tex
$$\vbox{\+ \tt 0.5 * (dist[i,j] + dist[j,i]) \rm \cr}$$
@end tex
In this expression the letters @samp{i} and @samp{j} are mute letters. They
are used to explain how the language processor should perform addition. Thus,
in the given case the expression is computed as follows:
@tex
$$\vbox{
\+ \tt t1[i,j] := dist[i,j] \ \ \ \ \ \ \ \ \rm
& for all $i \in cities, j \in cities$ \cr
\+ \tt t2[i,j] := dist[j,i] \rm & for all $i \in cities, j \in cities$ \cr
\+ \tt t3[i,j] := t1[i,j] + t2[i,j] \rm
& for all $i \in cities, j \in cities$ \cr
\+ \tt t4[i,j] := 0.5 * t3[i,j]
& for all $i \in cities, j \in cities$ \cr
}
$$
@end tex
where @code{t1}, @code{t2}, @code{t3} are intermediate temporary parameters,
and @code{t4} is a final temporary parameter, which defines the result of
computation.

Now consider another example:
@tex
$$\vbox{\+ \tt 0.5 * (dist[i,j] + dist[j,k]) \rm \cr}$$
@end tex
This expression is computed as follows:
@tex
$$\vbox{
\+ \tt t1[i,j] := dist[i,j] \ \ \ \ \ \ \ \ \ \ \rm
& for all $i \in cities, j \in cities$ \cr
\+ \tt t2[j,k] := dist[j,k] \rm & for all $j \in cities, k \in cities$ \cr
\+ \tt t3[i,j,k] := t1[i,j] + t2[j,k] \rm
& for all $i \in cities, j \in cities, k \in cities$ \cr
\+ \tt t4[i,j,k] := 0.5 * t3[i,j,k]
& for all $i \in cities, j \in cities, k \in cities$ \cr
}
$$
@end tex

Finally, consider yet another example:
@tex
$$\vbox{\+ \tt 0.5 * (dist[i,i] + dist[i,\#Boston]) \rm \cr}$$
@end tex
This expression is computed in the following way:
@tex
$$\vbox{
\+ \tt t1[i] := dist[i,i] \ \ \ \ \ \rm & for all $i \in cities$ \cr
\+ \tt t2[i] := dist[i,j] \rm & for all $i \in cities, j = Boston$ \cr
\+ \tt t3[i] := t1[i] + t2[i] \rm & for all $i \in cities$ \cr
\+ \tt t4[i] := 0.5 * t3[i] & for all $i \in cities$ \cr
}
$$
@end tex

Mute letters needn't to be declared. They are recognized by context.

Note that identical mute letters denote the same sets only within a statement.
If identical mute letters appear in different statements, they may denote
different sets.

@section Designators

@subsubheading Syntax

@example
<set name> ::= <symbolic name>
<parameter name> ::= <symbolic name>
<predicate name> ::= <symbolic name>
<variable name> ::= <symbolic name>
<constraint name> ::= <symbolic name>
<suffix> ::= <empty> | . lo | . up | . fx
<reference> ::= <set name> | <parameter name> | <predicate name> |
    <variable name> <suffix> | <constraint name> <suffix>
<mute letter> ::= <lower case letter>
<item name> ::= <symbolic name>
<offset> ::= <integer constant>
<subscript> ::= <mute letter> | # <item name> |
    <mute letter> + <offset> | <mute letter> - <offset> |
    <mute letter> ++ <offset> | <mute letter> -- <offset>
<subscript list> ::= <subscript> | <subscript list> , <subscript>
<designator> ::= <reference> | <reference> [ <subscript list> ]
@end example

@subsubheading Examples

@example
alpha
x[i,j]
stat[i++2,j--1,#Jan,i]
r.up[#Feb,#white,k+1]
@end example

@subsubheading Semantics

Designator is a primary expression, which allows to refer to sets, parameters
(including implicit parameters), predicates, variables, and constraints.

Number of subscripts in the designator should be equal to dimension of the
corresponding model object. If the object is 0-dimensional (scalar),
subscript list and square brackets [ and ] should be omitted.

The correspondence between subscripts and sets, over which the object is built,
is positional, i.e. the first subscript corresponds to the first set specified
in the object declaration, the second subscript corresponds to the second set,
and so on.

If all subscripts are different mute letters, the result of computation of a
designator is determined as follows:

1. If <reference> is a set, the result is 1-dimensional predicate built over
this set. Members of the resultant predicate correspond to items of this set
(i.e. the resultant predicate has the value @samp{true} on all items). Being
temporary the resultant predicate acquires the mute letter specified in the
subscript list.

2. If <reference> is a parameter, the result is an exact copy of this
parameter, which acquires the mute letters specified in the subscript list.

3. If <reference> is a predicate, the result is an exact copy of this
predicate, which acquires the mute letters specified in the subscript list.

4. If <reference> is a variable, the result is a parameter, which has the
same dimension, built over the same sets, and has the same members as the
specified variable. The model expression assigned to a particular member of
the resultant parameter is the corresponding elemental variable. Being
temporary the resultant parameter acquires the mute letters specified in the
subscript list.

5. If <reference> is a constraint, the result is a parameter, which has the
same dimension, built over the same sets, and has the same members as the
specified constraint. The model expression assigned to a particular member of
the resultant parameter is an exact copy of the model expression assigned to
the corresponding elemental constraint. Being temporary the resultant
parameter acquires the mute letters specified in the subscript list.

6. If <reference> has the suffixed form, it refers to an implicit parameter
associated with the corresponding variable or constraint (see Section 2.3).
In this case the result is an exact copy of the specified implicit parameter
(as if it were an ordinary explicit parameter), which acquires the mute letters
specified in the subscript list.

If some subscripts are identical mute letters, the result of computation of
the designator is determined in the same as above, however, the resultant
object will have only such members, where items that correspond to identical
mute letters are equal to each other (this assumes that identical mute letters
should refer to the same set). Besides, in the resultant object identical mute
letters are replaced by one mute letter that involves decreasing the object
dimension. For example, being computed the designator @code{u[i,j,j,i,j]}
gives a temporary object in the form @code{u'[i,j]}.

If subscript is a prticular item, i.e. has the form @code{#<item name>}, the
result of computation of the designator is determined in the same way as above,
however, the resultant object will have only such members, where items that
correspond to the subscript are equal to the specified item (this assumes that
the specified item should belong to the appropriate set). Using particular
items also involves decreasing dimension of the resultant object. For example,
being computed the designator @code{v[i,#aaa,j,#bbb]} gives a temporary object
in the form @code{v'[i,j]}.

@subsubheading Lag and lead operators

In GLPK/L there are so called @i{lag} and @i{lead operators}, which have the
following syntactic forms:
@tex
$$\vbox{
\+ \tt i + n \ \ \ \rm  & linear lag operator \cr
\+ \tt i - n \ \ \ \rm  & linear lead operator \cr
\+ \tt i ++ n  \ \ \rm & circular lag operator \cr
\+ \tt i -- n  \ \ \rm & circular lead operator \cr
}
$$
@end tex
where @code{i} is a mute letter, @code{n} is an offset (unsigned integer).

@tex
Lag and lead operators assume that items of a set are renumbered by integers
$1, 2, \dots, n$ in the order, in which these items appear in the set
declaration. Thus, a set $S$ may be written as
$$ S = \{i_1, i_2, \dots, i_n\}, $$
where $i_1, i_2, \dots, i_n$ are items. In case of linear lag/lead operators
items preceding the first item $i_1$ and following the last item $i_n$ are
undefined. But in case of circular lag/lead operators it is assumed that the
first item follows the last item and the last item precedes the first item,
thus, for example, $i_{n+1}$ is the same as $i_1$ and $i_0$ is the same as
$i_n$.

The result of computation of a designator, where lag and/or lead operators are
used, is determined in the following way. At first, the intermediate object
(parameter or predicate) is computed in the same way as if there were no
lag/lead operators. Then all elements of the Cartesian products are looked
through. Let $t = (i_p, j_q, k_r, \dots)$ is a tuple, i.e. some element of the
Cartesian product, where $p, q, r, \dots$ are sequential numbers of items in
the corresponding sets. If lag or lead operator is applied, say, to $i_p$,
this means that this item is replaced by $i_{p+n}$ (in case of lag operator)
or by $i_{p-n}$ (in case of lead operator). If there are other lag and/or lead
operators, they are applied in the same way. Such replacement(s) gives a
\it shifted \rm tuple $t' = (i'_p, j'_q, k'_r, \dots)$. If the shifted tuple
$t'$ is undefined (that may happen in case of linear operators as it was
explained above) or if there is no member with the shifted tuple $t'$ in the
intermediate object, no member is included in the final resultant object.
Otherwise, the original tuple $t$ (not the shifted tuple $t'$) and the value
assigned to the member with the shifted tuple $t'$ (not the original tuple
$t$) of the intermediate object give a member, which is included in the final
resultant object.

Let, for example, the set $S$ is declared as follows:
@end tex
@example
    set S = (a, b, c, d, e);
@end example
@tex
\noindent
and the one-dimensional parameter $u$ is built over the set $S$:
@end tex
@example
    parameter u[S];
    u[i] := data(i in S: a 1, b 2, c 3, d 4, e 5);
@end example
@tex
\noindent
Then some resultant parameters are computed as follows:
\tt
$$\vbox{
\settabs 6 \columns
\+ u[i] & u[i+2] & u[i-2] & u[i++2] & u[i--2] \cr
\+ \hrulefill & \hrulefill & \hrulefill & \hrulefill & \hrulefill & \cr
\+ a 1 &\ -  & c 1 & d 1 & c 1 & \cr
\+ b 2 &\ -  & d 2 & e 2 & d 2 & \cr
\+ c 3 & a 3 & e 3 & a 3 & e 3 & \cr
\+ d 4 & b 4 &\ -  & b 4 & a 4 & \cr
\+ e 5 & c 5 &\ -  & c 5 & b 5 & \cr
}
$$
\rm
where "\tt-\rm" means a member, which is not included in the resultant object.
@end tex

@section Parameter expressions

@subsubheading Syntax

@example
<parameter primary> ::= nil | <numeric constant> | <designator> |
    <parameter clause> | ( <parameter expression> )
<parameter term> ::= <parameter primary> |
    <parameter term> * <parameter primary> |
    <parameter term> / <parameter primary>
<simple parameter expression> ::= <parameter term> |
    + <parameter term> | - <parameter term> |
    <simple parameter expression> + <parameter term> |
    <simple parameter expression> - <parameter term>
<parameter expression> ::= <simple parameter expression> |
    <simple parameter expression> where <predicate expression>
@end example

@subsubheading Examples

@example
3 * (x1 + 0.7 * x2 - x3) / 1.5
0.30 * c[#red,k] + 0.45 * c[#green,k] + 0.25 * c[#blue,k]
sum((j,l), x[i,j,k,l] where mh[l,k] != 0) + y[i-1,k] - y[i,k] - z[i,k]
@end example

@subsubheading Semantics

Parameter expression is a rule for computing a parameter. Being temporary the
resultant parameter always has mute letters (see also Sections 5.1 and 5.2).

Depending on what are constituents of a parameter expression the resultant
parameter is computed as it is described below.

@subsubheading Primary parameter expressions

The result of computation of the constant @code{nil} is 0-dimensional (scalar)
parameter, which has no member.

The result of computation of a numeric constant is 0-dimensional (scalar)
parameter, which has the only member. Model expression assigned to this member
is the numeric constant.

In case of a designator the result is computed as it was explained in
Section 5.3. Note that parameter expression requires the resultant object to be
a parameter (not a predicate).

In case of a parameter clause the result is computed as it will be explained
below in Section 5.5.

The result of computation of a paranthesized parameter expression is the result
of computation of the parameter expression enclosed in parentheses.

@subsubheading Unary plus

The resultant parameter is an exact copy of the operand.

@subsubheading Unary minus

The resultant parameter has the same dimension, is built over the same sets,
and has the same members as the operand. If a value assigned to a member of
the operand is the model expression @math{e}, the value assigned to the
corresponding member of the resultant parameter is @math{(-e)}.

@subsubheading Addition

If operands have identical mute letters, these letters should refer to the same
set.

If one operand has a mute letter, which is missing in other operand, the latter
is expanded over the corresponding set. For example:
@tex
$$\vbox{\+ \tt u[i,j] + v[j,k] \rm \cr}$$
@end tex
In this expression the mute letter @samp{i} is missing in the second operand,
therefore the second operand is expanded over the set defined by the letter
@samp{i} as follows:
@tex
$$\vbox{\+ \tt v'[i,j,k] := v[j,k] \rm for all $i \in I$ \cr}$$
@end tex
and then the operand @code{v[j,k]} is replaced by the expanded object
@code{v'[i,j,k]}.

If it is necessary, expansion is applied several times in order that both
operands have the same mute letters.

@tex
After expansion addition is performed. Members included in the resultant
parameter is the union (as sets) of members of operands. If values assigned to
members (with identical tuples) of the first and the second operands are
$e_1$ and $e_2$ respectively, the value assigned to the corresponding member
of the resultant parameter is the model expression $(e_1 + e_2)$. If a member
of one operand has no match in other operand, this member just becomes a member
of the resultant parameter.
@end tex

@subsubheading Subtraction

The result of computation of the expression @code{x - y} is the same as the
result of computation of the expression @code{x + (-y)}.

@subsubheading Multiplication

@tex
If it is necessary, before multiplication expansion is performed in the same
way as for addition in order that both operands have the same mute letters.
Members included in the resultant parameter is the intersection (as sets) of
members of operands. If values assigned to members (with identical tuples) of
the first and the second operands are $e_1$ and $e_2$ respectively, the value
assigned to the corresponding member of the resultant parameter is the model
expression $(e_1 \cdot e_2)$.
@end tex

@subsubheading Division

@tex
Division is performed in the same as multiplication. However, the value
assigned to the corresponding member of the resultant parameter is the model
expression $(e_1 / e_2)$.
@end tex

@subsubheading Selection

All mute letters of the second operand (that follows @samp{where}) should be
represented in the first operand (that precedes @samp{where}). If it is
necessary, expansion is applied to the second operand in order that both
operands have the same mute letters. Then all members of the first operand,
which have no matches in the second operand, are deleted, that gives the
resultant parameter.

@section Parameter clauses

Parameter clause is a primary parameter expression, the syntactic form of
which looks like a function call (in programming languages).

@example
<parameter clause> ::= <data clause> | <table clause> | <sum clause>
@end example

@subsection data() clause

@subsubheading Syntax

@example
<set name> ::= <symbolic name>
<item name> ::= <symbolic name>
<mute letter> ::= <lower case letter>
<qualified letter> ::= <mute letter> in <set name>
<qualified list> ::= <qualified letter> |
    <qualified list> , <qualified letter>
<item reference> ::= <item name> | .
<tuple> ::= <item reference> | <tuple> , <item reference>
<data member> ::= <tuple> , <parameter expression>
<data list> ::= <data member> | <data list> , <data member>
<data clause> ::= data ( <qualified list> : <data list> )
@end example

(If it doesn't involve an ambiguity, the comma between @code{<tuple>} and
@code{<item reference>}, and/or between @code{<tuple>} and
@code{<parameter expression>}, and/or between @code{<data list>} and
@code{<data member>} may be omitted.)

@subsubheading Examples

@example
data(i in cities, j in cities:
     Boston       Chicago      58
     Portland     .            130
     Chicago      Memphis      32
     .            Portland     130
     Dallas       Memphis      28
     .            Boston       75
     Portland     Dallas       48)

data(i in machines, j in modes, k in parts:
     M1,    normal,    nuts,    0.3 * x1 + x2,
     .,     overtime,  .,       0.7 * x1 + x2,
     M2,    normal,    bolts,   0.55 * (x1 + x2),
     M3,    normal,    bolts,   x1 + 0.2 * x2)
@end example

@subsubheading Semantics

The data() clause is intended for constructing a temporary parameter, which
may be used as a primary parameter expression.

From the syntactic definition it follows that the data() clause has the form:
@example
            data(i in S, i in S, ..., i in S:
                 item,   item,   ..., item,   expr,
                 item,   item,   ..., item,   expr,
                  .  .  .  .  .  .  .  .  .  .  .
                 item,   item,   ..., item,   expr)
@end example
@noindent
where @samp{i} is a mute letter, @samp{S} is a set (domain) name, @samp{item}
is an item name, @samp{expr} is a parameter expression.

The resultant temporary parameter, which is the result of computation of the
data() clause, inherits mute letters and index sets specified in
@code{<qualified list>}. Each @code{<data member>} specified in
@code{<data list>} is included in the resultant parameter. All
@code{<parameter expressions>} specified in @code{<data list>} should be
0-dimensional (scalar).

For the sake of convenience it is allowed to write the period (.) instead
@code{<item name>}. In this case the corresponding @code{<item name>} from the
immediately preceding @code{<data member>} is used.

@subsection table() clause

@subsubheading Syntax

@example
<set name> ::= <symbolic name>
<item name> ::= <symbolic name>
<mute letter> ::= <lower case letter>
<qualified letter> ::= <mute letter> in <set name>
<column list> ::= <item name> | <column list> , <item name>
<entry> ::= <parameter expression> | .
<entry list> ::= <entry> | <entry list> , <entry>
<row> ::= <item name> , <entry list>
<row list> ::= <row> | <row list> , <row>
<table clause> ::= table ( <qualified letter> , <qualified letter> :
    <column list> : <row list> )
@end example

(If it doesn't involve an ambiguity, the comma between @code{<column list>}
and @code{<item name>}, and/or between @code{<item name>} and
@code{<entry list>}, and/or between @code{<entry list>} and @code{<entry>} may
be omitted.)

@subsubheading Examples

@example
table(i in cities, j in cities:
          Boston   Chicago  Dallas   Memphis  Portland
Boston    .        58       .        .        .
Chicago   .        .        .        32       130
Dallas    75       .        .        28       .
Memphis   55       .        82       .        .
Portland  130      .        48       .        .       )

table(i in machines, j in modes:
      normal,    overtime:
M1,   x1+x2,     1.5*x1+x2,
M2,   x1+x2,     1.6*x1+x2,
M3,   1.1*x1+x2, 1.8*x1+x2)
@end example

@subsubheading Semantics

The table() clause is intended for constructing a two-dimensional temporary
parameter, which may be used as a primary parameter expression.

From the syntactic definition it follows that the table() clause has the form:
@example
                    table(i in S, i in S:
                          item, item, ..., item:
                    item, expr, expr, ..., expr,
                    item, expr, expr, ..., expr,
                     .  .  .  .  .  .  .  .  .
                    item, expr, expr, ..., expr)
@end example
@noindent
where @samp{i} is a mute letter, @samp{S} is a set (domain) name, @samp{item}
is an item name, @samp{expr} is a parameter expression.

The resultant temporary parameter inherits two mute letters and two index sets
specified in @code{<table clause>}. Each @code{<parameter expression>}, which
should be 0-dimensional (scalar), gives one member included in the resultant
parameter. The first item assigned to a member tuple is the item specified in
the corresponding row of the table, and the second item is the item specified
in the corresponding column of the table. In order @i{not} to include a member
in the resultant parameter, the period (.) should be written instead
@code{<parameter expression>}.

@subsection sum() clause

@subsubheading Syntax

@example
<mute letter> ::= <lower case letter>
<mute list> ::= <mute letter> | <mute list> , <mute letter>
<sum clause> ::= sum ( <mute letter> , <parameter expression> ) |
    sum ( ( <mute list> ) , <parameter expression> )
@end example

@subsubheading Examples

@example
sum(j, a[i,j] * x[j])
sum((i,k), c[i,j,k] + 2.5 * (x[i,j,k] + y[j,k]))
@end example

@subsubheading Semantics

The sum() clause is intended to sum parameter members over given set(s). The
result of computation is a temporary parameter, which may be used as an operand
in a primary parameter expression.

The base form of the sum() clause is
@tex
$$\vbox{\+ \tt sum(i, e) \rm \cr}$$
@end tex
where @samp{i} is a mute letter, @samp{e} is a parameter expression.

@tex
Let $i \in S$, where $S$ is the set, which the letter $i$ refers to. Then the
result of computation of the base form is
$$f_{jk\dots} = \sum_{i \in S} e_{ijk\dots},$$
where $f$ is the resultant parameter, $i, j, k, \dots$ are mute letters bound
to the specified parameter expression. Note that mute letter specified in the
sum() clause drops out from the resultant parameter.
@end tex

The general form of the sum clause
@tex
$$\vbox{\+ \tt sum((i,j,k,...), e) \rm \cr}$$
@end tex
is equivalent to the following base form:
@tex
$$\vbox{\+ \tt sum(i, sum((j,k,...), e)) \rm \cr}$$
@end tex
that gives a recursive rule for computing the resultant parameter in the
general case.

@section Predicate expressions

@subsubheading Syntax

@example
<relational operator> ::= < | <= | = | >= | > | !=
<relation> ::= <simple parameter expression> <relational operator>
    <simple parameter expression>
<predicate primary> ::= true | false | <designator> | <relation> |
    ( <predicate expression> )
<predicate secondary> ::= <predicate primary> | not <predicate primary>
<predicate term> ::= <predicate secondary> |
    <predicate term> and <predicate secondary>
<predicate expression> ::= <predicate term> |
    <predicate expression> or <predicate term>
@end example

@subsubheading Examples

@example
alpha <= 100
f[i,j] >= 2.5 * g[i-1,j+1] and (beta[i] != 0.0 or not p[j,k])
gamma[i,#red,k] and gamma[i,#green,k] and gamma[i,#blue,k]
@end example

@subsubheading Semantics

Predicate expression is a rule for computing a predicate. Being temporary the
resultant predicate always has mute letters (see also Section 5.1 and 5.2).

Depending on what are constituents of a predicate expression the resultant
predicate is computed as it is described below.

@subsubheading Primary predicate expression

The result of computation of the constant @code{true} is 0-dimensional
(scalar) predicate, which has the only member.

The result of computation of the constant @code{false} is 0-dimensional
(scalar) predicate, which has no member.

In case of a designator the result is computed as it was explained in
Section 5.3. Note that predicate expression requires the resultant object to be
a predicate (not a parameter).

In case of a relation the result is computed as it is explained below.

The result of computation of a parenthesized predicate is the result of
computation of the predicate expression enclosed in parentheses.

@subsubheading Numeric comparison

Operands of a relational operator should satisfy to the following two
conditions:

1. The first operand (that precedes the relational operator) should be a
parameter. All model expressions assigned to its members should be constant
model expressions (see Section 2.2).

2. The second operand (that follows the relational operator) should be a
0-dimensional (scalar) parameter. The model expression assigned to its member
(which should exist) should be a constant model expression.

(Note that syntactically @code{<relational operator>} requires both operands
to be @code{<simple parameter expression>}. So, if it is necessary to use
@code{<parameter expression>} that contains @samp{where}, it should be
enclosed in parentheses.)

The resultant predicate has the same dimension and is built over the same sets
as the first operand. If a value (which is a numeric constant) assigned to a
member of the first operand satisfies to the specified relation, the member
with the same tuple is included in the resultant predicate. Otherwise, the
member is not included.

@subsubheading Inversion (logical "not")

The resultant predicate has the same dimension and is built over the same sets
as the operand. The language processor generates all tuples (elements of the
Cartesian product of the corresponding sets) and includes in the resultant
predicate a member, if and only if the member with the same tuple is missing
in the operand.

Note that since sparse parameters are allowed, in general case, for example,
the predicate
@tex
$$\vbox{\+ \tt dist[i,j] >= 70 \rm \cr}$$
@end tex
is @emph{not} equivalent to the predicate
@tex
$$\vbox{\+ \tt not dist[i,j] < 70 \rm \cr}$$
@end tex

@subsubheading Conjunction (logical "and")

If it necessary, before conjunction expansion is performed in the same way as
in case of addition (see Section 5.4) in order that both operands have the same
mute letters. Members included in the resultant predicate is the intersection
(as sets) of members of the operands.

@subsubheading Disjunction (logical "or")

If it necessary, before disjunction expansion is performed in the same way as
in case of addition (see Section 5.4) in order that both operands have the same
mute letters. Members included in the resultant predicate is the union (as
sets) of members of the operands.

@chapter Functional Statements

Functional statements are intended to perform certain operations on the model
objects or to pass the language processor some additional information.

@section Assignment statement

@subsubheading Syntax

@example
<parameter name> ::= <symbolic name>
<predicate name> ::= <symbolic name>
<variable name> ::= <symbolic name>
<constraint name> ::= <symbolic name>
<suffix> ::= <empty> | .lo | .up | .fx
<reference> ::= <parameter name> | <predicate name> |
    <variable name> <suffix> | <constraint name> <suffix>
<mute letter> ::= <lower case letter>
<item name> ::= <symbolic name>
<subscript> ::= <mute letter> | # <item name>
<subscript list> ::= <subscript> | <subscript list> , <subscript>
<destination> ::= <reference> | <reference> [ <subscript list> ]
<assignment statement> ::= <destination> := <expression> ; |
    <destination> where <predicate expression> := <expression> ;
@end example

(Syntactically @code{<destination>} is a particular case of
@code{<designator>} defined is Section 5.3. Therefore the same non-terminals
are used here.)

@subsubheading Examples

@example
alpha := 1;
t[i,j] where d[j] = 1 := sum(k, a[i,j,k]);
x.lo := nil;
y.fx[i,j] where s[i] != 0 := 2.5 * beta[j];
r[i] := sum(j, a[i,j] * x[j]) <= sum(j, b[j] where r[j] >= 0);
@end example

@subsubheading Semantics

The assignment statement is intended to create and/or delete some members of
a parameter (including implicit parameters), or a predicate, or a constraint,
and assign some values (i.e. model expressions) to members of a parameter or
a predicate.

Number of subscripts in the destination should be the same as dimension of the
corresponding object. If the destination object is 0-dimensional (scalar),
subscript list and square brackets [ and ] should be omitted.

The correspondence between subscripts and index sets, over which the
destination object is defined, is positional, i.e. the first subscript
corresponds to the first index set given in the object declaration, the second
subscript corresponds to the second index set, and so on.

All mute letters given in the subscript list should be different.

The result of computation of the expression that follows @samp{where} in the
left part of the assignment statement should be a predicate. All mute letters
of this predicate should be presented in the destination.

@subsubheading Assignment to parameter or predicate

If the destination object is a parameter, @code{<expression>} in the right part
of the assignment statement should be @code{<parameter expression>} (see
Section 5.4). Analogously, if the destination object is a predicate,
@code{<expression>} in the right part should be @code{<predicate expression>}
(see Section 5.6).

In both these cases the assignment statement is performed in the following way:

1. Reference and subscripts specified in the desination are processed.

2. The expression that follows @samp{where} is computed. If no condition is
given, the constant @code{true} is assumed. The result of computation of this
expression should be a predicate, all mute letters of which should be presented
in the destination. If it is necessary, the predicate is expanded (in the same
way as in case of addition; see Section 5.4) in order that it has the same mute
letters as the destination.

3. The expression in the right part of the assignment statement is computed.
All mute letters of the resultant object (which is either a parameter or a
predicate) should be presented in the destination. If it is necessary, the
resultant object is expanded in order that it has the same mute letters as the
destination.

4. The members of the destination object, which fall under specified items
(or all members if no items are specified) and which satisfy to the given
condition, are deleted from the object.

5. The members of the object computed on the step 3, which satisfy to the given
condition, are included in the destination object, and all other members are
ignored. If there are items specified in the destination, they are used to
construct complete tuples of the members included in the destination object.

Consider, for example, the following assignment statement:
@tex
$$\vbox{\+ \tt v[i,\#red,j] where p[j] := u[i]; \rm \cr}$$
@end tex
At first, the language processor computes the predicate @code{p[j]} and expands
it to @code{p'[i,j]}, and computes the object @code{u[i]} and expands it to
@code{u'[i,j]}. Then the language processor deletes from the object @code{v}
all the members, which have the form @code{v[i,#red,j]}
@tex
(for all $i \in I$ and $j \in J$)
@end tex
and for which the predicate @code{p'[i,j]} is @code{true}. Finally, the
language processor includes in the object @code{v} the members of the object
@code{u'[i,j]}, for which the predicate @code{p'[i,j]} is @code{true}. So far
as @code{v} is 3-dimensional object, but @code{u'} is 2-dimensional object,
tuples of each member of @code{u'} are expanded with the item @samp{red}.

Note that members of the destination object are deleted @emph{after} the
right part of the assignment statement has been computed. Therefore the
destination object may be used in the right part expression.

@subsubheading Assignment to variable

Assignment to a variable is not allowed, therefore the destination object
can't be a variable. However, assignment to an implicit parameter associated
with a variable is allowed (see below).

@subsubheading Assignment to constraint

If the destination object is a constraint, the expression in the right part of
the assignment statement should have one of the following four syntactic forms:
@example
    <simple parameter expression>
    <simple parameter expression> >= <simple parameter expression>
    <simple parameter expression> <= <simple parameter expression>
    <simple parameter expression>  = <simple parameter expression>
@end example
@noindent
In other word, the right part expression should syntactically be either
@code{<simple parameter expression>} or a particular form of
@code{<relation>}.

If the right part expression has the form of @code{<relation>}, the language
processor automatically moves the parameter expression, which follows the
relational operator, to the left-hand side with the opposite sign, that allows
to reduce the right part expression to the following four base forms:
@example
    <simple parameter expression>
    <simple parameter expression> >= 0
    <simple parameter expression> <= 0
    <simple parameter expression>  = 0
@end example

Assignment to a constraint is performed exactly in the same way as if there
would be a parameter in the left part of the assignment statement, and the
right part would be just @code{<simple parameter expression>}. However,
relational operator is additionally used to create and initialize some members
of implicit parameters associated with the constraint as shown below:

@tex
$$\vbox{
\settabs
\+ \hfil Relational operatorxx & \hfil lo-parameterxx &
   \hfil up-parameterxx & \hfil fx-parameterxx & \cr
\+ \hfil Relational operator & \hfil lo-parameter & \hfil up-parameter &
   \hfil fx-parameter & \cr
\+ \hrulefill & \hrulefill & \hrulefill & \hrulefill & \cr
\+ \hfil not specified & \hfil --- & \hfil --- & \hfil --- & \cr
\+ \hfil \tt >= \rm & \hfil 0 & \hfil --- & \hfil --- & \cr
\+ \hfil \tt <= \rm & \hfil --- & \hfil 0 & \hfil --- & \cr
\+ \hfil \tt = \rm & \hfil --- & \hfil --- & \hfil 0 & \cr
}$$
@end tex
where 0 is the numeric zero constant assigned to parameter members, and "---"
denotes missing parameter members.

Let, for example, the set @math{S} is declared as follows:
@example
    set S = (a, b, c);
@end example
@noindent
and the following assignment statement is given:
@example
    r[i] := x[i] + y[i] >= z[i] + 2;
@end example
@noindent
where @math{r} is a constraint, @math{x, y, z} are variables.

Then model expression that will be assigned to elemental constraints are the
following:
@example
    r[a] = "(x[a] + y[a]) - (z[a] + 2)"
    r[b] = "(x[b] + y[b]) - (z[b] + 2)"
    r[c] = "(x[c] + y[c]) - (z[c] + 2)"
@end example
@noindent
Besides, the implicit parameter @code{r.lo} will contain three members
@code{r.lo[a]}, @code{r.lo[b]}, and @code{r.lo[c]}, to which the numeric
constant 0 will be assigned, and two other implicit parameters @code{r.up} and
@code{r.fx} will contain no members.

Should note that if a model expression assigned to an elemental constraint
has a constant term (as in the example above), this term is considered as a
part of the expression and doesn't affect on zero numeric constant, which is
assigned to members of implicit parameters.

@subsubheading Assignment to implicit parameters

Assignment to implicit parameters is performed exactly in the same way as in
case of ordinary explicit parameters (see above). However, so far as implicit
parameters represent bounds of structural and auxiliary variables, all model
expressions participating in assignment should be constant model expressions.

@section Objective statement

@subsubheading Syntax

@example
<constraint name> ::= <symbolic name>
<item name> ::= <symbolic name>
<item list> ::= # <item name> | <item list> , # <item name>
<objective function> ::= <constraint name> |
    <constraint name> [ <item list> ]
<objective statement> ::= minimize <objective function> ; |
    maximize <objective function> ;
@end example

@subsubheading Examples

@example
minimize cost;
maximize func[#red,#green];
@end example

@subsubheading Semantics

The objective statement is use: a) to specify the direction of optimization;
and b) to specify the elemental constraint, model expression assigned to which
should be used as the objective function.

Number of items in @code{<objective function>} should be the same as dimension
of the corresponding constraint. If the constraint is 0-dimensional (scalar),
item list and square brackets [ and ] should be omitted.

The correspondence between items and index sets, over which the constraint is
built, is positional, i.e. the first item corresponds to the first index set
given in the constraint declaration, the second item corresponds to the second
set, and so on.

The objective statement may appear in the model description only once.

@section Display statement

@subsubheading Syntax

@example
<object> ::= <symbolic name> | ( <expression> )
<object list> ::= <object> | <object list> , <object>
<display statement> ::= display <object list> ;
@end example

@subsubheading Example

@example
display x, dist, (dist[i,j]), (0.5 * (x[i,j] + x[j,i]));
@end example

@subsubheading Semantics

The display statement allows to display any object or the result of computation
of any expression. This statement is intended mainly for model debugging
purposes.

If an expression is specified, the display statement additionally displays all
mute letters associated with the corresponding temporary object.

In the current implementation of the language processor the display statement
sends all output to @code{stdout}.

@section Model description

@subsubheading Syntax

@example
<statement> ::= <set statement> | <parameter statement> |
    <predicate statement> | <variable statement> |
    <constraint statement> | <objective statement> |
    <display statement>
<statement list> ::= <statement> | <statement list> <statement>
<model> ::= model <symbolic name> ; <statement list> end ;
@end example

(The metasymbol @code{<model>} is main non-terminal that correspond to the
model description.)

@subsubheading Example

See example of a complete model description in Appendix C.

@subsubheading Semantics

Model description is a sequence of statements, which being processed by the
language processor produces a particular mathematical programming model.

Symbolic name that follows the key word @samp{model} is informative.

@appendix Using the Language Processor from GLPK API

The current version of the GLPK package includes the API routine
@code{glp_read_lpm}. This routine is an interface to the GLPK/L language
processor and may be used in the same way as the API routine
@code{glp_read_mps} (for details see "GLPK User's Guide").

@subsubheading Synopsis

@example
#include "glpk.h"
int glp_read_lpm(char *fname);
@end example

@subsubheading Description

The @code{glp_read_lpm} routine reads an LP model written in the modeling
language GLPK/L from the text file, whose name is the character string
@code{fname}, into the workspace.

As a rule the workspace should be empty before a call to the
@code{glp_read_lpm} routine, i.e. the workspace should contain no rows and no
columns.

@subsubheading Control parameters

The behavior of the @code{glp_read_lpm} routine depends on the control
parameter @code{fn_gener} (name of the output file to write generated LP/MIP
problem).

@subsubheading Returns

@table @asis
@item 0
no errors;
@item 1
the operation failed because of errors. All diagnostics was sent to
@code{stderr}.
@end table

@appendix Using GLPK/L Models with the Solver GLPSOL

The current version of the solver GLPSOL (which is a part of the GLPK package)
allows processing models written in the GLPK/L modeling language.

In order to tell the solver that the input file is a model description, the
option @code{--lpm} should be given in the command line. For example:

@sp 1
@example
    glpsol --lpm foobar.lpm
@end example
@sp 1

@noindent
where @samp{.lpm} is a recommended extension (which means "Linear Programming
Model").

In order to see what a problem has been generated from the specified model
description, the option @code{--gener} may be given in the command line. For
example:

@sp 1
@example
    glpsol --lpm foobar.lpm --gener foobar.lst
@end example
@sp 1

@noindent
In this case the solver writes the generatel LP/MIP problem to the output text
file, whose name follows the @code{--gener} option, in plain text format.

In order not to solve the generated problem (that is useful for model
debugging purposes), the option @code{--check} should be passed to the solver.
For example:

@sp 1
@example
    glpsol --lpm foobar.lpm --gener foobar.lst --check
@end example
@sp 1

@noindent
In this case the solver just reads the input text file and writes the output
text file.

@appendix Example of Model Description

@example
model TRNSPORT /* TRANSPORTATION PROBLEM */;

/*----------------------------------------------------------------------
* This problem finds a least cost shipping schedule that meets
* requirements at markets and supplies at factories.
*
*  Reference:  Dantzig, G B., Linear Programming and Extensions
*              Princeton University Press, Princeton, New Jersey, 1963,
*              Chapter 3-3. */

  sets I   /* canning plants */   = ( SEATTLE, SAN_DIEGO ),
       J   /* markets        */   = ( NEW_YORK, CHICAGO, TOPEKA ) ;

  parameters
       A[I]  /* capacity of plant i in cases */,
       B[J]  /* demand at market j in cases  */;

  A[i] := data(i in I:
              SEATTLE     350
              SAN_DIEGO   600  );

  B[j] := data(j in J:
              NEW_YORK    325
              CHICAGO     300
              TOPEKA      275  ) ;

  parameter D[I,J]  /* distance in thousands of miles */;

  D[i,j] := table(i in I, j in J:
                    NEW_YORK       CHICAGO      TOPEKA:
      SEATTLE          2.5           1.7          1.8
      SAN_DIEGO        2.5           1.8          1.4  );

  parameter F /* freight in dollars per case per thousand miles */;

  F := 90;

  parameter C[I,J]
              /* transport cost in thousands of dollars per case */;

  C[i,j] := F * D[i,j] / 1000 ;

  variables
       X[I,J] /* shipment quantities in cases */;

  constraints
       Z      /* total transportation costs in thousands of dollars */,
       SUPPLY[I]   /* observe supply limit at plant i */,
       DEMAND[J]   /* satisfy demand at market j */;

  Z := sum((i,j), C[i,j]*X[i,j]) ;

  SUPPLY[i] :=   sum(j, X[i,j])  <=  A[i] ;

  DEMAND[j] :=   sum(i, X[i,j])  >=  B[j] ;

  minimize Z;

end;
@end example

@appendix LP Problem Generated from the Example Model

This is generated LP problem produced by the GLPK/L language processor from the
example model description (see Appendix C).

@example

Generated LP/MIP problem

Problem:    TRNSPORT
Rows:       6
Columns:    6
Non-zeros:  18
Objective:  Z (MINimization)

****** ROWS (CONSTRAINTS) ******

row 1: DEMAND[NEW_YORK] >= 325
   1 * X[SEATTLE,NEW_YORK]
   1 * X[SAN_DIEGO,NEW_YORK]

row 2: DEMAND[CHICAGO] >= 300
   1 * X[SEATTLE,CHICAGO]
   1 * X[SAN_DIEGO,CHICAGO]

row 3: DEMAND[TOPEKA] >= 275
   1 * X[SEATTLE,TOPEKA]
   1 * X[SAN_DIEGO,TOPEKA]

row 4: SUPPLY[SEATTLE] <= 350
   1 * X[SEATTLE,NEW_YORK]
   1 * X[SEATTLE,CHICAGO]
   1 * X[SEATTLE,TOPEKA]

row 5: SUPPLY[SAN_DIEGO] <= 600
   1 * X[SAN_DIEGO,NEW_YORK]
   1 * X[SAN_DIEGO,CHICAGO]
   1 * X[SAN_DIEGO,TOPEKA]

row 6: Z
   0.225 * X[SEATTLE,NEW_YORK]
   0.153 * X[SEATTLE,CHICAGO]
   0.162 * X[SEATTLE,TOPEKA]
   0.225 * X[SAN_DIEGO,NEW_YORK]
   0.162 * X[SAN_DIEGO,CHICAGO]
   0.126 * X[SAN_DIEGO,TOPEKA]

****** COLUMNS (VARIABLES) ******

col 1: X[SEATTLE,NEW_YORK] >= 0
   DEMAND[NEW_YORK] ... 1
   SUPPLY[SEATTLE] ... 1
   Z ... 0.225

col 2: X[SEATTLE,CHICAGO] >= 0
   DEMAND[CHICAGO] ... 1
   SUPPLY[SEATTLE] ... 1
   Z ... 0.153

col 3: X[SEATTLE,TOPEKA] >= 0
   DEMAND[TOPEKA] ... 1
   SUPPLY[SEATTLE] ... 1
   Z ... 0.162

col 4: X[SAN_DIEGO,NEW_YORK] >= 0
   DEMAND[NEW_YORK] ... 1
   SUPPLY[SAN_DIEGO] ... 1
   Z ... 0.225

col 5: X[SAN_DIEGO,CHICAGO] >= 0
   DEMAND[CHICAGO] ... 1
   SUPPLY[SAN_DIEGO] ... 1
   Z ... 0.162

col 6: X[SAN_DIEGO,TOPEKA] >= 0
   DEMAND[TOPEKA] ... 1
   SUPPLY[SAN_DIEGO] ... 1
   Z ... 0.126

End of output
@end example

@appendix Solution of the Generated LP Problem

This is optimal solution of the generated LP problem (see Appendix D)
obtained by the solver GLPSOL.

@example

Problem:    TRNSPORT
Rows:       6
Columns:    6
Non-zeros:  18
Objective:  Z = 153.675 (MINimization)
Status:     OPTIMAL

No.   Row name     St   Activity    Lower bound   Upper bound    Marginal
--- ------------   -- ------------ ------------- ------------- ------------
  1 DEMAND[NEW_YORK]
                   NL          325           325                      0.225
  2 DEMAND[CHICAGO]
                   NL          300           300                      0.153
  3 DEMAND[TOPEKA]
                   NL          275           275                      0.126
  4 SUPPLY[SEATTLE]
                   B           300                         350
  5 SUPPLY[SAN_DIEGO]
                   B           600                         600
  6 Z              B       153.675

No. Column name    St   Activity     Lower bound   Upper bound    Marginal
--- ------------   -- ------------ ------------- ------------- ------------
  1 X[SEATTLE,NEW_YORK]
                   NL            0             0                      < eps
  2 X[SEATTLE,CHICAGO]
                   B           300             0
  3 X[SEATTLE,TOPEKA]
                   NL            0             0                      0.036
  4 X[SAN_DIEGO,NEW_YORK]
                   B           325             0
  5 X[SAN_DIEGO,CHICAGO]
                   NL            0             0                      0.009
  6 X[SAN_DIEGO,TOPEKA]
                   B           275             0

End of output
@end example

@bye
