COIN-OR::LEMON - Graph Library

source: glpk-cmake/doc/gmpl.tex

Last change on this file was 1:c445c931472f, checked in by Alpar Juttner <alpar@…>, 14 years ago

Import glpk-4.45

  • Generated files and doc/notes are removed
File size: 146.9 KB
Line 
1%* gmpl.tex *%
2
3%***********************************************************************
4%  This code is part of GLPK (GNU Linear Programming Kit).
5%
6%  Copyright (C) 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008,
7%  2009, 2010 Andrew Makhorin, Department for Applied Informatics,
8%  Moscow Aviation Institute, Moscow, Russia. All rights reserved.
9%  E-mail: <mao@gnu.org>.
10%
11%  GLPK is free software: you can redistribute it and/or modify it
12%  under the terms of the GNU General Public License as published by
13%  the Free Software Foundation, either version 3 of the License, or
14%  (at your option) any later version.
15%
16%  GLPK is distributed in the hope that it will be useful, but WITHOUT
17%  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
18%  or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public
19%  License for more details.
20%
21%  You should have received a copy of the GNU General Public License
22%  along with GLPK. If not, see <http://www.gnu.org/licenses/>.
23%***********************************************************************
24
25\documentclass[10pt]{article}
26\usepackage[dvipdfm,linktocpage,colorlinks,linkcolor=blue]{hyperref}
27
28\begin{document}
29
30\thispagestyle{empty}
31
32\begin{center}
33
34\vspace*{1in}
35
36\begin{huge}
37\sf\bfseries Modeling Language GNU MathProg
38\end{huge}
39
40\vspace{0.5in}
41
42\begin{LARGE}
43\sf Language Reference
44\end{LARGE}
45
46\vspace{0.5in}
47
48\begin{LARGE}
49\sf for GLPK Version 4.45
50\end{LARGE}
51
52\vspace{0.5in}
53\begin{Large}
54\sf (DRAFT, December 2010)
55\end{Large}
56
57\end{center}
58
59\newpage
60
61\vspace*{1in}
62
63\vfill
64
65\noindent
66The GLPK package is part of the GNU Project released under the aegis of
67GNU.
68
69\medskip\noindent
70Copyright \copyright{} 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
712008, 2009, 2010 Andrew Makhorin, Department for Applied Informatics,
72Moscow Aviation Institute, Moscow, Russia. All rights reserved.
73
74\medskip\noindent
75Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
76MA 02110-1301, USA.
77
78\medskip\noindent
79Permission is granted to make and distribute verbatim copies of this
80manual provided the copyright notice and this permission notice are
81preserved on all copies.
82
83\medskip\noindent
84Permission is granted to copy and distribute modified versions of this
85manual under the conditions for verbatim copying, provided also that
86the entire resulting derived work is distributed under the terms of
87a permission notice identical to this one.
88
89\medskip\noindent
90Permission is granted to copy and distribute translations of this
91manual into another language, under the above conditions for modified
92versions.
93
94\newpage
95
96\tableofcontents
97
98%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
99
100\newpage
101
102\section{Introduction}
103
104{\it GNU MathProg} is a modeling language intended for describing
105linear mathematical programming models.\footnote{The GNU MathProg
106language is a subset of the AMPL language. Its GLPK implementation is
107mainly based on the paper: {\it Robert Fourer}, {\it David M. Gay}, and
108{\it Brian W. Kernighan}, ``A Modeling Language for Mathematical
109Programming.'' {\it Management Science} 36 (1990)\linebreak pp. 519-54.}
110
111Model descriptions written in the GNU MathProg language consist of
112a set of statements and data blocks constructed by the user from the
113language elements described in this document.
114
115In a process called {\it translation}, a program called the {\it model
116translator} analyzes the model description and translates it into
117internal data structures, which may be then used either for generating
118mathematical programming problem instance or directly by a program
119called the {\it solver} to obtain numeric solution of the problem.
120
121\subsection{Linear programming problem}
122\label{problem}
123
124In MathProg the linear programming (LP) problem is stated as follows:
125
126\medskip
127
128\noindent\hspace{.7in}minimize (or maximize)
129$$z=c_1x_1+c_2x_2+\dots+c_nx_n+c_0\eqno(1.1)$$
130\noindent\hspace{.7in}subject to linear constraints
131$$
132\begin{array}{l@{\ }c@{\ }r@{\ }c@{\ }r@{\ }c@{\ }r@{\ }c@{\ }l}
133L_1&\leq&a_{11}x_1&+&a_{12}x_2&+\dots+&a_{1n}x_n&\leq&U_1\\
134L_2&\leq&a_{21}x_1&+&a_{22}x_2&+\dots+&a_{2n}x_n&\leq&U_2\\
135\multicolumn{9}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}\\
136L_m&\leq&a_{m1}x_1&+&a_{m2}x_2&+\dots+&a_{mn}x_n&\leq&U_m\\
137\end{array}\eqno(1.2)
138$$
139\noindent\hspace{.7in}and bounds of variables
140$$
141\begin{array}{l@{\ }c@{\ }c@{\ }c@{\ }l}
142l_1&\leq&x_1&\leq&u_1\\
143l_2&\leq&x_2&\leq&u_2\\
144\multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .}\\
145l_n&\leq&x_n&\leq&u_n\\
146\end{array}\eqno(1.3)
147$$
148where $x_1$, $x_2$, \dots, $x_n$ are variables; $z$ is the objective
149function; $c_1$, $c_2$, \dots, $c_n$ are objective coefficients; $c_0$
150is the constant term (``shift'') of the objective function; $a_{11}$,
151$a_{12}$, \dots, $a_{mn}$ are constraint coefficients; $L_1$, $L_2$,
152\dots, $L_m$ are lower constraint bounds; $U_1$, $U_2$, \dots, $U_m$
153are upper constraint bounds; $l_1$, $l_2$, \dots, $l_n$ are lower
154bounds of variables; $u_1$, $u_2$, \dots, $u_n$ are upper bounds of
155variables.
156
157Bounds of variables and constraint bounds can be finite as well as
158infinite. Besides, lower bounds can be equal to corresponding upper
159bounds. Thus, the following types of variables and constraints are
160allowed:
161
162\newpage
163
164\begin{tabular}{@{}r@{\ }c@{\ }c@{\ }c@{\ }l@{\hspace*{38pt}}l}
165$-\infty$&$<$&$x$&$<$&$+\infty$&Free (unbounded) variable\\
166$l$&$\leq$&$x$&$<$&$+\infty$&Variable with lower bound\\
167$-\infty$&$<$&$x$&$\leq$&$u$&Variable with upper bound\\
168$l$&$\leq$&$x$&$\leq$&$u$&Double-bounded variable\\
169$l$&$=$&$x$&=&$u$&Fixed variable\\
170\end{tabular}
171
172\bigskip
173
174\begin{tabular}{@{}r@{\ }c@{\ }c@{\ }c@{\ }ll}
175$-\infty$&$<$&$\sum a_jx_j$&$<$&$+\infty$&Free (unbounded) linear
176form\\
177$L$&$\leq$&$\sum a_jx_j$&$<$&$+\infty$&Inequality constraint ``greater
178than or equal to''\\
179$-\infty$&$<$&$\sum a_jx_j$&$\leq$&$U$&Inequality constraint ``less
180than or equal to''\\
181$L$&$\leq$&$\sum a_jx_j$&$\leq$&$U$&Double-bounded inequality
182constraint\\
183$L$&$=$&$\sum a_jx_j$&=&$U$&Equality constraint\\
184\end{tabular}
185
186\bigskip
187
188In addition to pure LP problems MathProg also allows mixed integer
189linear programming (MIP) problems, where some or all variables are
190restricted to be integer or binary.
191
192\subsection{Model objects}
193
194In MathProg the model is described in terms of sets, parameters,
195variables, constraints, and objectives, which are called {\it model
196objects}.
197
198The user introduces particular model objects using the language
199statements. Each model object is provided with a symbolic name that
200uniquely identifies the object and is intended for referencing purposes.
201
202Model objects, including sets, can be multidimensional arrays built
203over indexing sets. Formally, $n$-dimensional array $A$ is the mapping:
204$$A:\Delta\rightarrow\Xi,\eqno(1.4)$$
205where $\Delta\subseteq S_1\times\dots\times S_n$ is a subset of the
206Cartesian product of indexing sets,\linebreak $\Xi$ is a set of array members.
207In MathProg the set $\Delta$ is called the {\it subscript domain}. Its
208members are $n$-tuples $(i_1,\dots,i_n)$, where $i_1\in S_1$, \dots,
209$i_n\in S_n$.
210
211If $n=0$, the Cartesian product above has exactly one member (namely,
212\linebreak 0-tuple), so it is convenient to think scalar objects as
2130-dimensional arrays having one member.
214
215The type of array members is determined by the type of corresponding
216model object as follows:
217
218\medskip
219
220\noindent\hfil
221\begin{tabular}{@{}ll@{}}
222Model object&Array member\\
223\hline
224Set&Elemental plain set\\
225Parameter&Number or symbol\\
226Variable&Elemental variable\\
227Constraint&Elemental constraint\\
228Objective&Elemental objective\\
229\end{tabular}
230
231\medskip
232
233In order to refer to a particular object member the object should be
234provided with {\it subscripts}. For example, if $a$ is a 2-dimensional
235parameter defined over $I\times J$, a reference to its particular
236member can be written as $a[i,j]$, where $i\in I$ and $j\in J$. It is
237understood that scalar objects being 0-dimensional need no subscripts.
238
239\subsection{Structure of model description}
240
241It is sometimes desirable to write a model which, at various points,
242may require different data for each problem instance to be solved using
243that model. For this reason in MathProg the model description consists
244of two parts: the {\it model section} and the {\it data section}.
245
246The model section is a main part of the model description that contains
247declarations of model objects and is common for all problems based on
248the corresponding model.
249
250The data section is an optional part of the model description that
251contains data specific for a particular problem instance.
252
253Depending on what is more convenient the model and data sections can be
254placed either in one file or in two separate files. The latter feature
255allows having arbitrary number of different data sections to be used
256with the same model section.
257
258%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
259
260\newpage
261
262\section{Coding model description}
263\label{coding}
264
265The model description is coded in plain text format using ASCII
266character set. Characters valid in the model description are the
267following:
268
269\begin{itemize}
270\item alphabetic characters:\\
271\verb|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|\\
272\verb|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 _|
273\item numeric characters:\\
274\verb|0 1 2 3 4 5 6 7 8 9|
275\item special characters:\\
276\verb?! " # & ' ( ) * + , - . / : ; < = > [ ] ^ { | }?
277\item white-space characters:\\
278\verb|SP HT CR NL VT FF|
279\end{itemize}
280
281Within string literals and comments any ASCII characters (except
282control characters) are valid.
283
284White-space characters are non-significant. They can be used freely
285between lexical units to improve readability of the model description.
286They are also used to separate lexical units from each other if there
287is no other way to do that.
288
289Syntactically model description is a sequence of lexical units in the
290following categories:
291
292\begin{itemize}
293\item symbolic names;
294\item numeric literals;
295\item string literals;
296\item keywords;
297\item delimiters;
298\item comments.
299\end{itemize}
300
301The lexical units of the language are discussed below.
302
303\subsection{Symbolic names}
304
305A {\it symbolic name} consists of alphabetic and numeric characters,
306the first of which must be alphabetic. All symbolic names are distinct
307(case sensitive).
308
309\medskip
310
311\noindent{\bf Examples}
312
313\medskip
314
315\noindent\verb|alpha123|
316
317\noindent\verb|This_is_a_name|
318
319\noindent\verb|_P123_abc_321|
320
321\newpage
322
323Symbolic names are used to identify model objects (sets, parameters,
324variables, constraints, objectives) and dummy indices.
325
326All symbolic names (except names of dummy indices) must be unique, i.e.
327the model description must have no objects with identical names.
328Symbolic names of dummy indices must be unique within the scope, where
329they are valid.
330
331\subsection{Numeric literals}
332
333A {\it numeric literal} has the form {\it xx}{\tt E}{\it syy}, where
334{\it xx} is a number with optional decimal point, {\it s} is the sign
335{\tt+} or {\tt-}, {\it yy} is a decimal exponent. The letter {\tt E} is
336case insensitive and can be coded as {\tt e}.
337
338\medskip
339
340\noindent{\bf Examples}
341
342\medskip
343
344\noindent\verb|123|
345
346\noindent\verb|3.14159|
347
348\noindent\verb|56.E+5|
349
350\noindent\verb|.78|
351
352\noindent\verb|123.456e-7|
353
354\medskip
355
356Numeric literals are used to represent numeric quantities. They have
357obvious fixed meaning.
358
359\subsection{String literals}
360
361A {\it string literal} is a sequence of arbitrary characters enclosed
362either in single quotes or in double quotes. Both these forms are
363equivalent.
364
365If the single quote is part of a string literal enclosed in single
366quotes, it must be coded twice. Analogously, if the double quote is
367part of a string literal enclosed in double quotes, it must be coded
368twice.
369
370\medskip
371
372\noindent{\bf Examples}
373
374\medskip
375
376\noindent\verb|'This is a string'|
377
378\noindent\verb|"This is another string"|
379
380\noindent\verb|'1 + 2 = 3'|
381
382\noindent\verb|'That''s all'|
383
384\noindent\verb|"She said: ""No"""|
385
386\medskip
387
388String literals are used to represent symbolic quantities.
389
390\subsection{Keywords}
391
392A {\it keyword} is a sequence of alphabetic characters and possibly
393some special characters.
394
395All keywords fall into two categories: {\it reserved keywords}, which
396cannot be used as symbolic names, and {\it non-reserved keywords},
397which being recognized by context can be used as symbolic names.
398
399\newpage
400
401The reserved keywords are the following:
402
403\medskip
404
405\noindent\hfil
406\begin{tabular}{@{}p{.7in}p{.7in}p{.7in}p{.7in}@{}}
407{\tt and}&{\tt else}&{\tt mod}&{\tt union}\\
408{\tt by}&{\tt if}&{\tt not}&{\tt within}\\
409{\tt cross}&{\tt in}&{\tt or}\\
410{\tt diff}&{\tt inter}&{\tt symdiff}\\
411{\tt div}&{\tt less}&{\tt then}\\
412\end{tabular}
413
414\medskip
415
416Non-reserved keywords are described in following sections.
417
418All the keywords have fixed meaning, which will be explained on
419discussion of corresponding syntactic constructions, where the keywords
420are used.
421
422\subsection{Delimiters}
423
424A {\it delimiter} is either a single special character or a sequence of
425two special characters as follows:
426
427\medskip
428
429\noindent\hfil
430\begin{tabular}{@{}p{.3in}p{.3in}p{.3in}p{.3in}p{.3in}p{.3in}@{}}
431{\tt+}&{\tt\textasciicircum}&{\tt==}&{\tt!}&{\tt:}&{\tt)}\\
432{\tt-}&{\tt\&}&{\tt>=}&{\tt\&\&}&{\tt;}&{\tt[}\\
433{\tt*}&{\tt<}&{\tt>}&{\tt||}&{\tt:=}&{\tt|}\\
434{\tt/}&{\tt<=}&{\tt<>}&{\tt.}&{\tt..}&{\tt\{}\\
435{\tt**}&{\tt=}&{\tt!=}&{\tt,}&{\tt(}&{\tt\}}\\
436\end{tabular}
437
438\medskip
439
440If the delimiter consists of two characters, there must be no spaces
441between the characters.
442
443All the delimiters have fixed meaning, which will be explained on
444discussion corresponding syntactic constructions, where the delimiters
445are used.
446
447\subsection{Comments}
448
449For documenting purposes the model description can be provided with
450{\it comments}, which may have two different forms. The first form is
451a {\it single-line comment}, which begins with the character {\tt\#}
452and extends until end of line. The second form is a {\it comment
453sequence}, which is a sequence of any characters enclosed within
454{\tt/*} and {\tt*/}.
455
456\medskip
457
458\noindent{\bf Examples}
459
460\medskip
461
462\noindent\verb|param n := 10; # This is a comment|
463
464\noindent\verb|/* This is another comment */|
465
466\medskip
467
468Comments are ignored by the model translator and can appear anywhere in
469the model description, where white-space characters are allowed.
470
471%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
472
473\newpage
474
475\section{Expressions}
476
477An {\it expression} is a rule for computing a value. In model
478description expressions are used as constituents of certain statements.
479
480In general case expressions consist of operands and operators.
481
482Depending on the type of the resultant value all expressions fall into
483the following categories:
484
485\begin{itemize}
486\item numeric expressions;
487\item symbolic expressions;
488\item indexing expressions;
489\item set expressions;
490\item logical expressions;
491\item linear expressions.
492\end{itemize}
493
494\subsection{Numeric expressions}
495
496A {\it numeric expression} is a rule for computing a single numeric
497value represented as a floating-point number.
498
499The primary numeric expression may be a numeric literal, dummy index,
500unsubscripted parameter, subscripted parameter, built-in function
501reference, iterated numeric expression, conditional numeric expression,
502or another numeric expression enclosed in parentheses.
503
504\medskip
505
506\noindent{\bf Examples}
507
508\medskip
509
510\noindent
511\begin{tabular}{@{}ll@{}}
512\verb|1.23|&(numeric literal)\\
513\verb|j|&(dummy index)\\
514\verb|time|&(unsubscripted parameter)\\
515\verb|a['May 2003',j+1]|&(subscripted parameter)\\
516\verb|abs(b[i,j])|&(function reference)\\
517\verb|sum{i in S diff T} alpha[i] * b[i,j]|&(iterated expression)\\
518\verb|if i in I then 2 * p else q[i+1]|&(conditional expression)\\
519\verb|(b[i,j] + .5 * c)|&(parenthesized expression)\\
520\end{tabular}
521
522\medskip
523
524More general numeric expressions containing two or more primary numeric
525expressions may be constructed by using certain arithmetic operators.
526
527\medskip
528
529\noindent{\bf Examples}
530
531\medskip
532
533\noindent\verb|j+1|
534
535\noindent\verb|2 * a[i-1,j+1] - b[i,j]|
536
537\noindent\verb|sum{j in J} a[i,j] * x[j] + sum{k in K} b[i,k] * x[k]|
538
539\noindent\verb|(if i in I then 2 * p else q[i+1]) / (a[i,j] + 1.5)|
540
541\subsubsection{Numeric literals}
542
543If the primary numeric expression is a numeric literal, the resultant
544value is obvious.
545
546\subsubsection{Dummy indices}
547
548If the primary numeric expression is a dummy index, the resultant value
549is current value assigned to that dummy index.
550
551\subsubsection{Unsubscripted parameters}
552
553If the primary numeric expression is an unsubscripted parameter (which
554must be 0-dimensional), the resultant value is the value of that
555parameter.
556
557\subsubsection{Subscripted parameters}
558
559The primary numeric expression, which refers to a subscripted parameter,
560has the following syntactic form:
561
562\medskip
563
564\noindent\hfil
565{\it name}{\tt[}$i_1${\tt,} $i_2${\tt,} \dots{\tt,} $i_n${\tt]}
566
567\medskip
568
569\noindent where {\it name} is the symbolic name of the parameter,
570$i_1$, $i_2$, \dots, $i_n$ are subscripts.
571
572Each subscript must be a numeric or symbolic expression. The number of
573subscripts in the subscript list must be the same as the dimension of
574the parameter with which the subscript list is associated.
575
576Actual values of subscript expressions are used to identify
577a particular member of the parameter that determines the resultant
578value of the primary expression.
579
580\subsubsection{Function references}
581
582In MathProg there exist the following built-in functions which may be
583used in numeric expressions:
584
585\medskip
586
587\begin{tabular}{@{}p{96pt}p{222pt}@{}}
588{\tt abs(}$x${\tt)}&$|x|$, absolute value of $x$\\
589{\tt atan(}$x${\tt)}&$\arctan x$, principal value of the arc tangent of
590$x$ (in radians)\\
591{\tt atan(}$y${\tt,} $x${\tt)}&$\arctan y/x$, principal value of the
592arc tangent of $y/x$ (in radians). In this case the signs of both
593arguments $y$ and $x$ are used to determine the quadrant of the
594resultant value\\
595{\tt card(}$X${\tt)}&$|X|$, cardinality (the number of elements) of
596set $X$\\
597{\tt ceil(}$x${\tt)}&$\lceil x\rceil$, smallest integer not less than
598$x$ (``ceiling of $x$'')\\
599{\tt cos(}$x${\tt)}&$\cos x$, cosine of $x$ (in radians)\\
600{\tt exp(}$x${\tt)}&$e^x$, base-$e$ exponential of $x$\\
601{\tt floor(}$x${\tt)}&$\lfloor x\rfloor$, largest integer not greater
602than $x$ (``floor of $x$'')\\
603\end{tabular}
604
605\begin{tabular}{@{}p{96pt}p{222pt}@{}}
606{\tt gmtime()}&the number of seconds elapsed since 00:00:00~Jan~1, 1970,
607Coordinated Universal Time (for details see Subsection \ref{gmtime},
608page \pageref{gmtime})\\
609{\tt length(}$s${\tt)}&$|s|$, length of character string $s$\\
610{\tt log(}$x${\tt)}&$\log x$, natural logarithm of $x$\\
611{\tt log10(}$x${\tt)}&$\log_{10}x$, common (decimal) logarithm of $x$\\
612{\tt max(}$x_1${\tt,} $x_2${\tt,} \dots{\tt,} $x_n${\tt)}&the largest
613of values $x_1$, $x_2$, \dots, $x_n$\\
614{\tt min(}$x_1${\tt,} $x_2${\tt,} \dots{\tt,} $x_n${\tt)}&the smallest
615of values $x_1$, $x_2$, \dots, $x_n$\\
616{\tt round(}$x${\tt)}&rounding $x$ to nearest integer\\
617{\tt round(}$x${\tt,} $n${\tt)}&rounding $x$ to $n$ fractional decimal
618digits\\
619{\tt sin(}$x${\tt)}&$\sin x$, sine of $x$ (in radians)\\
620{\tt sqrt(}$x${\tt)}&$\sqrt{x}$, non-negative square root of $x$\\
621{\tt str2time(}$s${\tt,} $f${\tt)}&converting character string $s$ to
622calendar time (for details see Subsection \ref{str2time}, page
623\pageref{str2time})\\
624{\tt trunc(}$x${\tt)}&truncating $x$ to nearest integer\\
625{\tt trunc(}$x${\tt,} $n${\tt)}&truncating $x$ to $n$ fractional
626decimal digits\\
627{\tt Irand224()}&generating pseudo-random integer uniformly distributed
628in $[0,2^{24})$\\
629{\tt Uniform01()}&generating pseudo-random number uniformly distributed
630in $[0,1)$\\
631{\tt Uniform(}$a${\tt,} $b${\tt)}&generating pseudo-random number
632uniformly distributed in $[a,b)$\\
633{\tt Normal01()}&generating Gaussian pseudo-random variate with
634$\mu=0$ and $\sigma=1$\\
635{\tt Normal(}$\mu${\tt,} $\sigma${\tt)}&generating Gaussian
636pseudo-random variate with given $\mu$ and $\sigma$\\
637\end{tabular}
638
639\medskip
640
641Arguments of all built-in functions, except {\tt card}, {\tt length},
642and {\tt str2time}, must be numeric expressions. The argument of
643{\tt card} must be a set expression. The argument of {\tt length} and
644both arguments of {\tt str2time} must be symbolic expressions.
645
646The resultant value of the numeric expression, which is a function
647reference, is the result of applying the function to its argument(s).
648
649Note that each pseudo-random generator function has a latent argument
650(i.e. some internal state), which is changed whenever the function has
651been applied. Thus, if the function is applied repeatedly even to
652identical arguments, due to the side effect different resultant values
653are always produced.
654
655\subsubsection{Iterated expressions}
656\label{itexpr}
657
658An {\it iterated numeric expression} is a primary numeric expression,
659which has the following syntactic form:
660
661\medskip
662
663\noindent\hfil
664{\it iterated-operator indexing-expression integrand}
665
666\medskip
667
668\noindent where {\it iterated-operator} is the symbolic name of the
669iterated operator to be performed (see below), {\it indexing-expression}
670is an indexing expression which introduces dummy indices and controls
671iterating, {\it integrand} is a numeric expression that participates in
672the operation.
673
674In MathProg there exist four iterated operators, which may be used in
675numeric expressions:
676
677\medskip
678
679\noindent\hfil
680\begin{tabular}{@{}lll@{}}
681{\tt sum}&summation&$\displaystyle\sum_{(i_1,\dots,i_n)\in\Delta}
682f(i_1,\dots,i_n)$\\
683{\tt prod}&production&$\displaystyle\prod_{(i_1,\dots,i_n)\in\Delta}
684f(i_1,\dots,i_n)$\\
685{\tt min}&minimum&$\displaystyle\min_{(i_1,\dots,i_n)\in\Delta}
686f(i_1,\dots,i_n)$\\
687{\tt max}&maximum&$\displaystyle\max_{(i_1,\dots,i_n)\in\Delta}
688f(i_1,\dots,i_n)$\\
689\end{tabular}
690
691\medskip
692
693\noindent where $i_1$, \dots, $i_n$ are dummy indices introduced in
694the indexing expression, $\Delta$ is the domain, a set of $n$-tuples
695specified by the indexing expression which defines particular values
696assigned to the dummy indices on performing the iterated operation,
697$f(i_1,\dots,i_n)$ is the integrand, a numeric expression whose
698resultant value depends on the dummy indices.
699
700The resultant value of an iterated numeric expression is the result of
701applying of the iterated operator to its integrand over all $n$-tuples
702contained in the domain.
703
704\subsubsection{Conditional expressions}
705\label{ifthen}
706
707A {\it conditional numeric expression} is a primary numeric expression,
708which has one of the following two syntactic forms:
709
710\medskip
711
712\noindent\hfil
713{\tt if} $b$ {\tt then} $x$ {\tt else} $y$
714
715\medskip
716
717\noindent\hspace{126.5pt}
718{\tt if} $b$ {\tt then} $x$
719
720\medskip
721
722\noindent where $b$ is an logical expression, $x$ and $y$ are numeric
723expressions.
724
725The resultant value of the conditional expression depends on the value
726of the logical expression that follows the keyword {\tt if}. If it
727takes on the value {\it true}, the value of the conditional expression
728is the value of the expression that follows the keyword {\tt then}.
729Otherwise, if the logical expression takes on the value {\it false},
730the value of the conditional expression is the value of the expression
731that follows the keyword {\it else}. If the second, reduced form of the
732conditional expression is used and the logical expression takes on the
733value {\it false}, the resultant value of the conditional expression is
734zero.
735
736\subsubsection{Parenthesized expressions}
737
738Any numeric expression may be enclosed in parentheses that
739syntactically makes it a primary numeric expression.
740
741Parentheses may be used in numeric expressions, as in algebra, to
742specify the desired order in which operations are to be performed.
743Where parentheses are used, the expression within the parentheses is
744evaluated before the resultant value is used.
745
746The resultant value of the parenthesized expression is the same as the
747value of the expression enclosed within parentheses.
748
749\subsubsection{Arithmetic operators}
750
751In MathProg there exist the following arithmetic operators, which may
752be used in numeric expressions:
753
754\medskip
755
756\begin{tabular}{@{}p{96pt}p{222pt}@{}}
757{\tt +} $x$&unary plus\\
758{\tt -} $x$&unary minus\\
759$x$ {\tt +} $y$&addition\\
760$x$ {\tt -} $y$&subtraction\\
761$x$ {\tt less} $y$&positive difference (if $x<y$ then 0 else $x-y$)\\
762$x$ {\tt *} $y$&multiplication\\
763$x$ {\tt /} $y$&division\\
764$x$ {\tt div} $y$&quotient of exact division\\
765$x$ {\tt mod} $y$&remainder of exact division\\
766$x$ {\tt **} $y$, $x$ {\tt\textasciicircum} $y$&exponentiation (raising
767to power)\\
768\end{tabular}
769
770\medskip
771
772\noindent where $x$ and $y$ are numeric expressions.
773
774If the expression includes more than one arithmetic operator, all
775operators are performed from left to right according to the hierarchy
776of operations (see below) with the only exception that the
777exponentiaion operators are performed from right to left.
778
779The resultant value of the expression, which contains arithmetic
780operators, is the result of applying the operators to their operands.
781
782\subsubsection{Hierarchy of operations}
783\label{hierarchy}
784
785The following list shows the hierarchy of operations in numeric
786expressions:
787
788\medskip
789
790\noindent\hfil
791\begin{tabular}{@{}ll@{}}
792Operation&Hierarchy\\
793\hline
794Evaluation of functions ({\tt abs}, {\tt ceil}, etc.)&1st\\
795Exponentiation ({\tt**}, {\tt\textasciicircum})&2nd\\
796Unary plus and minus ({\tt+}, {\tt-})&3rd\\
797Multiplication and division ({\tt*}, {\tt/}, {\tt div}, {\tt mod})&4th\\
798Iterated operations ({\tt sum}, {\tt prod}, {\tt min}, {\tt max})&5th\\
799Addition and subtraction ({\tt+}, {\tt-}, {\tt less})&6th\\
800Conditional evaluation ({\tt if} \dots {\tt then} \dots {\tt else})&
8017th\\
802\end{tabular}
803
804\medskip
805
806This hierarchy is used to determine which of two consecutive operations
807is performed first. If the first operator is higher than or equal to
808the second, the first operation is performed. If it is not, the second
809operator is compared to the third, etc. When the end of the expression
810is reached, all of the remaining operations are performed in the
811reverse order.
812
813\newpage
814
815\subsection{Symbolic expressions}
816
817A {\it symbolic expression} is a rule for computing a single symbolic
818value represented as a character string.
819
820The primary symbolic expression may be a string literal, dummy index,
821unsubscripted parameter, subscripted parameter, built-in function
822reference, conditional symbolic expression, or another symbolic
823expression enclosed in parentheses.
824
825It is also allowed to use a numeric expression as the primary symbolic
826expression, in which case the resultant value of the numeric expression
827is automatically converted to the symbolic type.
828
829\medskip
830
831\noindent{\bf Examples}
832
833\medskip
834
835\noindent
836\begin{tabular}{@{}ll@{}}
837\verb|'May 2003'|&(string literal)\\
838\verb|j|&(dummy index)\\
839\verb|p|&(unsubscripted parameter)\\
840\verb|s['abc',j+1]|&(subscripted parameter)\\
841\verb|substr(name[i],k+1,3)|&(function reference)\\
842\verb|if i in I then s[i,j] else t[i+1]|&(conditional expression)\\
843\verb|((10 * b[i,j]) & '.bis')|&(parenthesized expression)\\
844\end{tabular}
845
846\medskip
847
848More general symbolic expressions containing two or more primary
849symbolic expressions may be constructed by using the concatenation
850operator.
851
852\medskip
853
854\noindent{\bf Examples}
855
856\medskip
857
858\noindent\verb|'abc[' & i & ',' & j & ']'|
859
860\noindent\verb|"from " & city[i] & " to " & city[j]|
861
862\medskip
863
864The principles of evaluation of symbolic expressions are completely
865analogous to the ones given for numeric expressions (see above).
866
867\subsubsection{Function references}
868
869In MathProg there exist the following built-in functions which may be
870used in symbolic expressions:
871
872\medskip
873
874\begin{tabular}{@{}p{96pt}p{222pt}@{}}
875{\tt substr(}$s${\tt,} $x${\tt)}&substring of $s$ starting from
876position $x$\\
877{\tt substr(}$s${\tt,} $x${\tt,} $y${\tt)}&substring of $s$ starting
878from position $x$ and having length $y$\\
879{\tt time2str(}$t${\tt,} $f${\tt)}&converting calendar time to
880character string (for details see Subsection \ref{time2str}, page
881\pageref{time2str})\\
882\end{tabular}
883
884\medskip
885
886The first argument of {\tt substr} must be a symbolic expression while
887its second and optional third arguments must be numeric expressions.
888
889The first argument of {\tt time2str} must be a numeric expression, and
890its second argument must be a symbolic expression.
891
892The resultant value of the symbolic expression, which is a function
893reference, is the result of applying the function to its arguments.
894
895\subsubsection{Symbolic operators}
896
897Currently in MathProg there exists the only symbolic operator:
898
899\medskip
900
901\noindent\hfil
902{\tt s \& t}
903
904\medskip
905
906\noindent where $s$ and $t$ are symbolic expressions. This operator
907means concatenation of its two symbolic operands, which are character
908strings.
909
910\subsubsection{Hierarchy of operations}
911
912The following list shows the hierarchy of operations in symbolic
913expressions:
914
915\medskip
916
917\noindent\hfil
918\begin{tabular}{@{}ll@{}}
919Operation&Hierarchy\\
920\hline
921Evaluation of numeric operations&1st-7th\\
922Concatenation ({\tt\&})&8th\\
923Conditional evaluation ({\tt if} \dots {\tt then} \dots {\tt else})&
9247th\\
925\end{tabular}
926
927\medskip
928
929This hierarchy has the same meaning as was explained above for numeric
930expressions (see Subsection \ref{hierarchy}, page \pageref{hierarchy}).
931
932\subsection{Indexing expressions and dummy indices}
933\label{indexing}
934
935An {\it indexing expression} is an auxiliary construction, which
936specifies a plain set of $n$-tuples and introduces dummy indices. It
937has two syntactic forms:
938
939\medskip
940
941\noindent\hspace{73.5pt}
942{\tt\{} {\it entry}$_1${\tt,} {\it entry}$_2${\tt,} \dots{\tt,}
943{\it entry}$_m$ {\tt\}}
944
945\medskip
946
947\noindent\hfil
948{\tt\{} {\it entry}$_1${\tt,} {\it entry}$_2${\tt,} \dots{\tt,}
949{\it entry}$_m$ {\tt:} {\it predicate} {\tt\}}
950
951\medskip
952
953\noindent where {\it entry}{$_1$}, {\it entry}{$_2$}, \dots,
954{\it entry}{$_m$} are indexing entries, {\it predicate} is a logical
955expression that specifies an optional predicate (logical condition).
956
957Each {\it indexing entry} in the indexing expression has one of the
958following three forms:
959
960\medskip
961
962\noindent\hspace{123pt}
963$i$ {\tt in} $S$
964
965\medskip
966
967\noindent\hfil
968{\tt(}$i_1${\tt,} $i_2${\tt,} \dots{\tt,}$i_n${\tt)} {\tt in} $S$
969
970\medskip
971
972\noindent\hspace{123pt}
973$S$
974
975\medskip
976
977\noindent where $i_1$, $i_2$, \dots, $i_n$ are indices, $S$ is a set
978expression (discussed in the next section) that specifies the basic set.
979
980The number of indices in the indexing entry must be the same as the
981dimension of the basic set $S$, i.e. if $S$ consists of 1-tuples, the
982first form must be used, and if $S$ consists of $n$-tuples, where
983$n>1$, the second form must be used.
984
985If the first form of the indexing entry is used, the index $i$ can be
986a dummy index only (see below). If the second form is used, the indices
987$i_1$, $i_2$, \dots, $i_n$ can be either dummy indices or some numeric
988or symbolic expressions, where at least one index must be a dummy index.
989The third, reduced form of the indexing entry has the same effect as if
990there were $i$ (if $S$ is 1-dimensional) or $i_1$, $i_2$, \dots, $i_n$
991(if $S$ is $n$-dimensional) all specified as dummy indices.
992
993A {\it dummy index} is an auxiliary model object, which acts like an
994individual variable. Values assigned to dummy indices are components of
995$n$-tuples from basic sets, i.e. some numeric and symbolic quantities.
996
997For referencing purposes dummy indices can be provided with symbolic
998names. However, unlike other model objects (sets, parameters, etc.)
999dummy indices need not be explicitly declared. Each {\it undeclared}
1000symbolic name being used in the indexing position of an indexing entry
1001is recognized as the symbolic name of corresponding dummy index.
1002
1003Symbolic names of dummy indices are valid only within the scope of the
1004indexing expression, where the dummy indices were introduced. Beyond
1005the scope the dummy indices are completely inaccessible, so the same
1006symbolic names may be used for other purposes, in particular, to
1007represent dummy indices in other indexing expressions.
1008
1009The scope of indexing expression, where implicit declarations of dummy
1010indices are valid, depends on the context, in which the indexing
1011expression is used:
1012
1013\begin{enumerate}
1014\item If the indexing expression is used in iterated operator, its
1015scope extends until the end of the integrand.
1016\item If the indexing expression is used as a primary set expression,
1017its scope extends until the end of that indexing expression.
1018\item If the indexing expression is used to define the subscript domain
1019in declarations of some model objects, its scope extends until the end
1020of the corresponding statement.
1021\end{enumerate}
1022
1023The indexing mechanism implemented by means of indexing expressions is
1024best explained by some examples discussed below.
1025
1026Let there be given three sets:
1027
1028\medskip
1029
1030\noindent\hspace{33.5pt}
1031$A=\{4,7,9\}$,
1032
1033\medskip
1034
1035\noindent\hfil
1036$B=\{(1,Jan),(1,Feb),(2,Mar),(2,Apr),(3,May),(3,Jun)\}$,
1037
1038\medskip
1039
1040\noindent\hspace{33.5pt}
1041$C=\{a,b,c\}$,
1042
1043\medskip
1044
1045\noindent where $A$ and $C$ consist of 1-tuples (singlets), $B$
1046consists of 2-tuples (doublets). Consider the following indexing
1047expression:
1048
1049\medskip
1050
1051\noindent\hfil
1052{\tt\{i in A, (j,k) in B, l in C\}}
1053
1054\medskip
1055
1056\noindent where {\tt i}, {\tt j}, {\tt k}, and {\tt l} are dummy
1057indices.
1058
1059Although MathProg is not a procedural language, for any indexing
1060expression an equivalent algorithmic description can be given. In
1061particular, the algorithmic description of the indexing expression
1062above could look like follows:
1063
1064\medskip
1065
1066\noindent\hfil
1067\begin{tabular}{@{}l@{}}
1068{\bf for all} $i\in A$ {\bf do}\\
1069\hspace{12pt}{\bf for all} $(j,k)\in B$ {\bf do}\\
1070\hspace{24pt}{\bf for all} $l\in C$ {\bf do}\\
1071\hspace{36pt}{\it action};\\
1072\end{tabular}
1073
1074\newpage
1075
1076\noindent where the dummy indices $i$, $j$, $k$, $l$ are consecutively
1077assigned corresponding components of $n$-tuples from the basic sets $A$,
1078$B$, $C$, and {\it action} is some action that depends on the context,
1079where the indexing expression is used. For example, if the action were
1080printing current values of dummy indices, the printout would look like
1081follows:
1082
1083\medskip
1084
1085\noindent\hfil
1086\begin{tabular}{@{}llll@{}}
1087$i=4$&$j=1$&$k=Jan$&$l=a$\\
1088$i=4$&$j=1$&$k=Jan$&$l=b$\\
1089$i=4$&$j=1$&$k=Jan$&$l=c$\\
1090$i=4$&$j=1$&$k=Feb$&$l=a$\\
1091$i=4$&$j=1$&$k=Feb$&$l=b$\\
1092\multicolumn{4}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}\\
1093$i=9$&$j=3$&$k=Jun$&$l=b$\\
1094$i=9$&$j=3$&$k=Jun$&$l=c$\\
1095\end{tabular}
1096
1097\medskip
1098
1099Let the example indexing expression be used in the following iterated
1100operation:
1101
1102\medskip
1103
1104\noindent\hfil
1105{\tt sum\{i in A, (j,k) in B, l in C\} p[i,j,k,l]}
1106
1107\medskip
1108
1109\noindent where {\tt p} is a 4-dimensional numeric parameter or some
1110numeric expression whose resultant value depends on {\tt i}, {\tt j},
1111{\tt k}, and {\tt l}. In this case the action is summation, so the
1112resultant value of the primary numeric expression is:
1113$$\sum_{i\in A,(j,k)\in B,l\in C}(p_{ijkl}).$$
1114
1115Now let the example indexing expression be used as a primary set
1116expression. In this case the action is gathering all 4-tuples
1117(quadruplets) of the form $(i,j,k,l)$ in one set, so the resultant
1118value of such operation is simply the Cartesian product of the basic
1119sets:
1120$$A\times B\times C=\{(i,j,k,l):i\in A,(j,k)\in B,l\in C\}.$$
1121Note that in this case the same indexing expression might be written in
1122the reduced form:
1123
1124\medskip
1125
1126\noindent\hfil
1127{\tt\{A, B, C\}}
1128
1129\medskip
1130
1131\noindent because the dummy indices $i$, $j$, $k$, and $l$ are not
1132referenced and therefore their symbolic names need not be specified.
1133
1134Finally, let the example indexing expression be used as the subscript
1135domain in the declaration of a 4-dimensional model object, say,
1136a numeric parameter:
1137
1138\medskip
1139
1140\noindent\hfil
1141{\tt param p\{i in A, (j,k) in B, l in C\}} \dots {\tt;}
1142
1143\medskip
1144
1145\noindent In this case the action is generating the parameter members,
1146where each member has the form $p[i,j,k,l]$.
1147
1148As was said above, some indices in the second form of indexing entries
1149may be numeric or symbolic expressions, not only dummy indices. In this
1150case resultant values of such expressions play role of some logical
1151conditions to select only that $n$-tuples from the Cartesian product of
1152basic sets that satisfy these conditions.
1153
1154Consider, for example, the following indexing expression:
1155
1156\medskip
1157
1158\noindent\hfil
1159{\tt\{i in A, (i-1,k) in B, l in C\}}
1160
1161\medskip
1162
1163\noindent where {\tt i}, {\tt k}, {\tt l} are dummy indices, and
1164{\tt i-1} is a numeric expression. The algorithmic decsription of this
1165indexing expression is the following:
1166
1167\medskip
1168
1169\noindent\hfil
1170\begin{tabular}{@{}l@{}}
1171{\bf for all} $i\in A$ {\bf do}\\
1172\hspace{12pt}{\bf for all} $(j,k)\in B$ {\bf and} $j=i-1$ {\bf do}\\
1173\hspace{24pt}{\bf for all} $l\in C$ {\bf do}\\
1174\hspace{36pt}{\it action};\\
1175\end{tabular}
1176
1177\medskip
1178
1179\noindent Thus, if this indexing expression were used as a primary set
1180expression, the resultant set would be the following:
1181$$\{(4,May,a),(4,May,b),(4,May,c),(4,Jun,a),(4,Jun,b),(4,Jun,c)\}.$$
1182Should note that in this case the resultant set consists of 3-tuples,
1183not of 4-tuples, because in the indexing expression there is no dummy
1184index that corresponds to the first component of 2-tuples from the set
1185$B$.
1186
1187The general rule is: the number of components of $n$-tuples defined by
1188an indexing expression is the same as the number of dummy indices in
1189that expression, where the correspondence between dummy indices and
1190components on $n$-tuples in the resultant set is positional, i.e. the
1191first dummy index corresponds to the first component, the second dummy
1192index corresponds to the second component, etc.
1193
1194In some cases it is needed to select a subset from the Cartesian
1195product of some sets. This may be attained by using an optional logical
1196predicate, which is specified in the indexing expression.
1197
1198Consider, for example, the following indexing expression:
1199
1200\medskip
1201
1202\noindent\hfil
1203{\tt\{i in A, (j,k) in B, l in C: i <= 5 and k <> 'Mar'\}}
1204
1205\medskip
1206
1207\noindent where the logical expression following the colon is a
1208predicate. The algorithmic description of this indexing expression is
1209the following:
1210
1211\medskip
1212
1213\noindent\hfil
1214\begin{tabular}{@{}l@{}}
1215{\bf for all} $i\in A$ {\bf do}\\
1216\hspace{12pt}{\bf for all} $(j,k)\in B$ {\bf do}\\
1217\hspace{24pt}{\bf for all} $l\in C$ {\bf do}\\
1218\hspace{36pt}{\bf if} $i\leq 5$ {\bf and} $l\neq`Mar'$ {\bf then}\\
1219\hspace{48pt}{\it action};\\
1220\end{tabular}
1221
1222\medskip
1223
1224\noindent Thus, if this indexing expression were used as a primary set
1225expression, the resultant set would be the following:
1226$$\{(4,1,Jan,a),(4,1,Feb,a),(4,2,Apr,a),\dots,(4,3,Jun,c)\}.$$
1227
1228If no predicate is specified in the indexing expression, one, which
1229takes on the value {\it true}, is assumed.
1230
1231\subsection{Set expressions}
1232
1233A {\it set expression} is a rule for computing an elemental set, i.e.
1234a collection of $n$-tuples, where components of $n$-tuples are numeric
1235and symbolic quantities.
1236
1237The primary set expression may be a literal set, unsubscripted set,
1238subscripted set, ``arithmetic'' set, indexing expression, iterated set
1239expression, conditional set expression, or another set expression
1240enclosed in parentheses.
1241
1242\medskip
1243
1244\noindent{\bf Examples}
1245
1246\medskip
1247
1248\noindent
1249\begin{tabular}{@{}ll@{}}
1250\verb|{(123,'aa'), (i,'bb'), (j-1,'cc')}|&(literal set)\\
1251\verb|I|&(unsubscripted set)\\
1252\verb|S[i-1,j+1]|&(subscripted set)\\
1253\verb|1..t-1 by 2|&(``arithmetic'' set)\\
1254\verb|{t in 1..T, (t+1,j) in S: (t,j) in F}|&(indexing expression)\\
1255\verb|setof{i in I, j in J}(i+1,j-1)|&(iterated expression)\\
1256\verb|if i < j then S[i] else F diff S[j]|&(conditional expression)\\
1257\verb|(1..10 union 21..30)|&(parenthesized expression)\\
1258\end{tabular}
1259
1260\medskip
1261
1262More general set expressions containing two or more primary set
1263expressions may be constructed by using certain set operators.
1264
1265\medskip
1266
1267\noindent{\bf Examples}
1268
1269\medskip
1270
1271\noindent\verb|(A union B) inter (I cross J)|
1272
1273\noindent
1274\verb|1..10 cross (if i < j then {'a', 'b', 'c'} else {'d', 'e', 'f'})|
1275
1276\subsubsection{Literal sets}
1277
1278A {\it literal set} is a primary set expression, which has the
1279following two syntactic forms:
1280
1281\medskip
1282
1283\noindent\hspace{39pt}
1284{\tt\{}$e_1${\tt,} $e_2${\tt,} \dots{\tt,} $e_m${\tt\}}
1285
1286\medskip
1287
1288\noindent\hfil
1289{\tt\{(}$e_{11}${\tt,} \dots{\tt,} $e_{1n}${\tt),}
1290{\tt(}$e_{21}${\tt,} \dots{\tt,} $e_{2n}${\tt),} \dots{\tt,}
1291{\tt(}$e_{m1}${\tt,} \dots{\tt,} $e_{mn}${\tt)\}}
1292
1293\medskip
1294
1295\noindent where $e_1$, \dots, $e_m$, $e_{11}$, \dots, $e_{mn}$ are
1296numeric or symbolic expressions.
1297
1298If the first form is used, the resultant set consists of 1-tuples
1299(singlets) enumerated within the curly braces. It is allowed to specify
1300an empty set as {\tt\{\ \}}, which has no 1-tuples. If the second form
1301is used, the resultant set consists of $n$-tuples enumerated within the
1302curly braces, where a particular $n$-tuple consists of corresponding
1303components enumerated within the parentheses. All $n$-tuples must have
1304the same number of components.
1305
1306\subsubsection{Unsubscripted sets}
1307
1308If the primary set expression is an unsubscripted set (which must be
13090-dimen\-sional), the resultant set is an elemental set associated with
1310the corresponding set object.
1311
1312\newpage
1313
1314\subsubsection{Subscripted sets}
1315
1316The primary set expression, which refers to a subscripted set, has the
1317following syntactic form:
1318
1319\medskip
1320
1321\noindent\hfil
1322{\it name}{\tt[}$i_1${\tt,} $i_2${\tt,} \dots{\tt,} $i_n${\tt]}
1323
1324\medskip
1325
1326\noindent where {\it name} is the symbolic name of the set object,
1327$i_1$, $i_2$, \dots, $i_n$ are subscripts.
1328
1329Each subscript must be a numeric or symbolic expression. The number of
1330subscripts in the subscript list must be the same as the dimension of
1331the set object with which the subscript list is associated.
1332
1333Actual values of subscript expressions are used to identify a
1334particular member of the set object that determines the resultant set.
1335
1336\subsubsection{``Arithmetic'' sets}
1337
1338The primary set expression, which is an ``arithmetic'' set, has the
1339following two syntactic forms:
1340
1341\medskip
1342
1343\noindent\hfil
1344$t_0$ {\tt..} $t_1$ {\tt by} $\delta t$
1345
1346\medskip
1347
1348\noindent\hspace{138.5pt}
1349$t_0$ {\tt..} $t_1$
1350
1351\medskip
1352
1353\noindent where $t_0$, $t_1$, and $\delta t$ are numeric expressions
1354(the value of $\delta t$ must not be zero). The second form is
1355equivalent to the first form, where $\delta t=1$.
1356
1357If $\delta t>0$, the resultant set is determined as follows:
1358$$\{t:\exists k\in{\cal Z}(t=t_0+k\delta t,\ t_0\leq t\leq t_1)\}.$$
1359Otherwise, if $\delta t<0$, the resultant set is determined as follows:
1360$$\{t:\exists k\in{\cal Z}(t=t_0+k\delta t,\ t_1\leq t\leq t_0)\}.$$
1361
1362\subsubsection{Indexing expressions}
1363
1364If the primary set expression is an indexing expression, the resultant
1365set is determined as described above in Subsection \ref{indexing}, page
1366\pageref{indexing}.
1367
1368\subsubsection{Iterated expressions}
1369
1370An {\it iterated set expression} is a primary set expression, which has
1371the following syntactic form:
1372
1373\medskip
1374
1375\noindent\hfil
1376{\tt setof} {\it indexing-expression} {\it integrand}
1377
1378\medskip
1379
1380\noindent where {\it indexing-expression} is an indexing expression,
1381which introduces dummy indices and controls iterating, {\it integrand}
1382is either a single numeric or symbolic expression or a list of numeric
1383and symbolic expressions separated by commae and enclosed in
1384parentheses.
1385
1386If the integrand is a single numeric or symbolic expression, the
1387resultant set consists of 1-tuples and is determined as follows:
1388$$\{x:(i_1,\dots,i_n)\in\Delta\},$$
1389\noindent where $x$ is a value of the integrand, $i_1$, \dots, $i_n$
1390are dummy indices introduced in the indexing expression, $\Delta$ is
1391the domain, a set of $n$-tuples specified by the indexing expression,
1392which defines particular values assigned to the dummy indices on
1393performing the iterated operation.
1394
1395If the integrand is a list containing $m$ numeric and symbolic
1396expressions, the resultant set consists of $m$-tuples and is determined
1397as follows:
1398$$\{(x_1,\dots,x_m):(i_1,\dots,i_n)\in\Delta\},$$
1399where $x_1$, \dots, $x_m$ are values of the expressions in the
1400integrand list, $i_1$, \dots, $i_n$ and $\Delta$ have the same meaning
1401as above.
1402
1403\subsubsection{Conditional expressions}
1404
1405A {\it conditional set expression} is a primary set expression that has
1406the following syntactic form:
1407
1408\medskip
1409
1410\noindent\hfil
1411{\tt if} $b$ {\tt then} $X$ {\tt else} $Y$
1412
1413\medskip
1414
1415\noindent where $b$ is an logical expression, $X$ and $Y$ are set
1416expressions, which must define sets of the same dimension.
1417
1418The resultant value of the conditional expression depends on the value
1419of the logical expression that follows the keyword {\tt if}. If it
1420takes on the value {\it true}, the resultant set is the value of the
1421expression that follows the keyword {\tt then}. Otherwise, if the
1422logical expression takes on the value {\it false}, the resultant set is
1423the value of the expression that follows the keyword {\tt else}.
1424
1425\subsubsection{Parenthesized expressions}
1426
1427Any set expression may be enclosed in parentheses that syntactically
1428makes it a primary set expression.
1429
1430Parentheses may be used in set expressions, as in algebra, to specify
1431the desired order in which operations are to be performed. Where
1432parentheses are used, the expression within the parentheses is
1433evaluated before the resultant value is used.
1434
1435The resultant value of the parenthesized expression is the same as the
1436value of the expression enclosed within parentheses.
1437
1438\subsubsection{Set operators}
1439
1440In MathProg there exist the following set operators, which may be used
1441in set expressions:
1442
1443\medskip
1444
1445\begin{tabular}{@{}p{96pt}p{222pt}@{}}
1446$X$ {\tt union} $Y$&union $X\cup Y$\\
1447$X$ {\tt diff} $Y$&difference $X\backslash Y$\\
1448$X$ {\tt symdiff} $Y$&symmetric difference $X\oplus Y$\\
1449$X$ {\tt inter} $Y$&intersection $X\cap Y$\\
1450$X$ {\tt cross} $Y$&cross (Cartesian) product $X\times Y$\\
1451\end{tabular}
1452
1453\medskip
1454
1455\noindent where $X$ and Y are set expressions, which must define sets
1456of the identical dimension (except the Cartesian product).
1457
1458If the expression includes more than one set operator, all operators
1459are performed from left to right according to the hierarchy of
1460operations (see below).
1461
1462The resultant value of the expression, which contains set operators, is
1463the result of applying the operators to their operands.
1464
1465The dimension of the resultant set, i.e. the dimension of $n$-tuples,
1466of which the resultant set consists of, is the same as the dimension of
1467the operands, except the Cartesian product, where the dimension of the
1468resultant set is the sum of the dimensions of its operands.
1469
1470\subsubsection{Hierarchy of operations}
1471
1472The following list shows the hierarchy of operations in set
1473expressions:
1474
1475\medskip
1476
1477\noindent\hfil
1478\begin{tabular}{@{}ll@{}}
1479Operation&Hierarchy\\
1480\hline
1481Evaluation of numeric operations&1st-7th\\
1482Evaluation of symbolic operations&8th-9th\\
1483Evaluation of iterated or ``arithmetic'' set ({\tt setof}, {\tt..})&
148410th\\
1485Cartesian product ({\tt cross})&11th\\
1486Intersection ({\tt inter})&12th\\
1487Union and difference ({\tt union}, {\tt diff}, {\tt symdiff})&13th\\
1488Conditional evaluation ({\tt if} \dots {\tt then} \dots {\tt else})&
148914th\\
1490\end{tabular}
1491
1492\medskip
1493
1494This hierarchy has the same meaning as was explained above for numeric
1495expressions (see Subsection \ref{hierarchy}, page \pageref{hierarchy}).
1496
1497\subsection{Logical expressions}
1498
1499A {\it logical expression} is a rule for computing a single logical
1500value, which can be either {\it true} or {\it false}.
1501
1502The primary logical expression may be a numeric expression, relational
1503expression, iterated logical expression, or another logical expression
1504enclosed in parentheses.
1505
1506\medskip
1507
1508\noindent{\bf Examples}
1509
1510\medskip
1511
1512\noindent
1513\begin{tabular}{@{}ll@{}}
1514\verb|i+1|&(numeric expression)\\
1515\verb|a[i,j] < 1.5|&(relational expression)\\
1516\verb|s[i+1,j-1] <> 'Mar'|&(relational expression)\\
1517\verb|(i+1,'Jan') not in I cross J|&(relational expression)\\
1518\verb|S union T within A[i] inter B[j]|&(relational expression)\\
1519\verb|forall{i in I, j in J} a[i,j] < .5 * b|&(iterated expression)\\
1520\verb|(a[i,j] < 1.5 or b[i] >= a[i,j])|&(parenthesized expression)\\
1521\end{tabular}
1522
1523\medskip
1524
1525More general logical expressions containing two or more primary logical
1526expressions may be constructed by using certain logical operators.
1527
1528\newpage
1529
1530\noindent{\bf Examples}
1531
1532\medskip
1533
1534\noindent\verb|not (a[i,j] < 1.5 or b[i] >= a[i,j]) and (i,j) in S|
1535
1536\noindent\verb|(i,j) in S or (i,j) not in T diff U|
1537
1538\subsubsection{Numeric expressions}
1539
1540The resultant value of the primary logical expression, which is a
1541numeric expression, is {\it true}, if the resultant value of the
1542numeric expression is non-zero. Otherwise the resultant value of the
1543logical expression is {\it false}.
1544
1545\subsubsection{Relational operators}
1546
1547In MathProg there exist the following relational operators, which may
1548be used in logical expressions:
1549
1550\medskip
1551
1552\begin{tabular}{@{}ll@{}}
1553$x$ {\tt<} $y$&test on $x<y$\\
1554$x$ {\tt<=} $y$&test on $x\leq y$\\
1555$x$ {\tt=} $y$, $x$ {\tt==} $y$&test on $x=y$\\
1556$x$ {\tt>=} $y$&test on $x\geq y$\\
1557$x$ {\tt>} $y$&test on $x>y$\\
1558$x$ {\tt<>} $y$, $x$ {\tt!=} $y$&test on $x\neq y$\\
1559$x$ {\tt in} $Y$&test on $x\in Y$\\
1560{\tt(}$x_1${\tt,}\dots{\tt,}$x_n${\tt)} {\tt in} $Y$&test on
1561$(x_1,\dots,x_n)\in Y$\\
1562$x$ {\tt not} {\tt in} $Y$, $x$ {\tt!in} $Y$&test on $x\not\in Y$\\
1563{\tt(}$x_1${\tt,}\dots{\tt,}$x_n${\tt)} {\tt not} {\tt in} $Y$,
1564{\tt(}$x_1${\tt,}\dots{\tt,}$x_n${\tt)} {\tt !in} $Y$&test on
1565$(x_1,\dots,x_n)\not\in Y$\\
1566$X$ {\tt within} $Y$&test on $X\subseteq Y$\\
1567$X$ {\tt not} {\tt within} $Y$, $X$ {\tt !within} $Y$&test on
1568$X\not\subseteq Y$\\
1569\end{tabular}
1570
1571\medskip
1572
1573\noindent where $x$, $x_1$, \dots, $x_n$, $y$ are numeric or symbolic
1574expressions, $X$ and $Y$ are set expression.
1575
1576{\it Notes:}
1577
15781. In the operations {\tt in}, {\tt not in}, and {\tt !in} the
1579number of components in the first operands must be the same as the
1580dimension of the second operand.
1581
15822. In the operations {\tt within}, {\tt not within}, and {\tt !within}
1583both operands must have identical dimension.
1584
1585All the relational operators listed above have their conventional
1586mathematical meaning. The resultant value is {\it true}, if
1587corresponding relation is satisfied for its operands, otherwise
1588{\it false}. (Note that symbolic values are ordered lexicographically,
1589and any numeric value precedes any symbolic value.)
1590
1591\subsubsection{Iterated expressions}
1592
1593An {\it iterated logical expression} is a primary logical expression,
1594which has the following syntactic form:
1595
1596\medskip
1597
1598\noindent\hfil
1599{\it iterated-operator} {\it indexing-expression} {\it integrand}
1600
1601\medskip
1602
1603\noindent where {\it iterated-operator} is the symbolic name of the
1604iterated operator to be performed (see below), {\it indexing-expression}
1605is an indexing expression which introduces dummy indices and controls
1606iterating, {\it integrand} is a numeric expression that participates in
1607the operation.
1608
1609In MathProg there exist two iterated operators, which may be used in
1610logical expressions:
1611
1612\medskip
1613
1614\noindent\hfil
1615\begin{tabular}{@{}lll@{}}
1616{\tt forall}&$\forall$-quantification&$\displaystyle
1617\forall(i_1,\dots,i_n)\in\Delta[f(i_1,\dots,i_n)],$\\
1618{\tt exists}&$\exists$-quantification&$\displaystyle
1619\exists(i_1,\dots,i_n)\in\Delta[f(i_1,\dots,i_n)],$\\
1620\end{tabular}
1621
1622\medskip
1623
1624\noindent where $i_1$, \dots, $i_n$ are dummy indices introduced in
1625the indexing expression, $\Delta$ is the domain, a set of $n$-tuples
1626specified by the indexing expression which defines particular values
1627assigned to the dummy indices on performing the iterated operation,
1628$f(i_1,\dots,i_n)$ is the integrand, a logical expression whose
1629resultant value depends on the dummy indices.
1630
1631For $\forall$-quantification the resultant value of the iterated
1632logical expression is {\it true}, if the value of the integrand is
1633{\it true} for all $n$-tuples contained in the domain, otherwise
1634{\it false}.
1635
1636For $\exists$-quantification the resultant value of the iterated
1637logical expression is {\it false}, if the value of the integrand is
1638{\it false} for all $n$-tuples contained in the domain, otherwise
1639{\it true}.
1640
1641\subsubsection{Parenthesized expressions}
1642
1643Any logical expression may be enclosed in parentheses that
1644syntactically makes it a primary logical expression.
1645
1646Parentheses may be used in logical expressions, as in algebra, to
1647specify the desired order in which operations are to be performed.
1648Where parentheses are used, the expression within the parentheses is
1649evaluated before the resultant value is used.
1650
1651The resultant value of the parenthesized expression is the same as the
1652value of the expression enclosed within parentheses.
1653
1654\subsubsection{Logical operators}
1655
1656In MathProg there exist the following logical operators, which may be
1657used in logical expressions:
1658
1659\medskip
1660
1661\begin{tabular}{@{}p{96pt}p{222pt}@{}}
1662{\tt not} $x$, {\tt!}$x$&negation $\neg\ x$\\
1663$x$ {\tt and} $y$, $x$ {\tt\&\&} $y$&conjunction (logical ``and'')
1664$x\;\&\;y$\\
1665$x$ {\tt or} $y$, $x$ {\tt||} $y$&disjunction (logical ``or'')
1666$x\vee y$\\
1667\end{tabular}
1668
1669\medskip
1670
1671\noindent where $x$ and $y$ are logical expressions.
1672
1673If the expression includes more than one logical operator, all
1674operators are performed from left to right according to the hierarchy
1675of the operations (see below). The resultant value of the expression,
1676which contains logical operators, is the result of applying the
1677operators to their operands.
1678
1679\subsubsection{Hierarchy of operations}
1680
1681The following list shows the hierarchy of operations in logical
1682expressions:
1683
1684\medskip
1685
1686\noindent\hfil
1687\begin{tabular}{@{}ll@{}}
1688Operation&Hierarchy\\
1689\hline
1690Evaluation of numeric operations&1st-7th\\
1691Evaluation of symbolic operations&8th-9th\\
1692Evaluation of set operations&10th-14th\\
1693Relational operations ({\tt<}, {\tt<=}, etc.)&15th\\
1694Negation ({\tt not}, {\tt!})&16th\\
1695Conjunction ({\tt and}, {\tt\&\&})&17th\\
1696$\forall$- and $\exists$-quantification ({\tt forall}, {\tt exists})&
169718th\\
1698Disjunction ({\tt or}, {\tt||})&19th\\
1699\end{tabular}
1700
1701\medskip
1702
1703This hierarchy has the same meaning as was explained above for numeric
1704expressions (see Subsection \ref{hierarchy}, page \pageref{hierarchy}).
1705
1706\subsection{Linear expressions}
1707
1708An {\it linear expression} is a rule for computing so called
1709a {\it linear form} or simply a {\it formula}, which is a linear (or
1710affine) function of elemental variables.
1711
1712The primary linear expression may be an unsubscripted variable,
1713subscripted variable, iterated linear expression, conditional linear
1714expression, or another linear expression enclosed in parentheses.
1715
1716It is also allowed to use a numeric expression as the primary linear
1717expression, in which case the resultant value of the numeric expression
1718is automatically converted to a formula that includes the constant term
1719only.
1720
1721\medskip
1722
1723\noindent{\bf Examples}
1724
1725\medskip
1726
1727\noindent
1728\begin{tabular}{@{}ll@{}}
1729\verb|z|&(unsubscripted variable)\\
1730\verb|x[i,j]|&(subscripted variable)\\
1731\verb|sum{j in J} (a[i] * x[i,j] + 3 * y)|&(iterated expression)\\
1732\verb|if i in I then x[i,j] else 1.5 * z + 3|&(conditional expression)\\
1733\verb|(a[i,j] * x[i,j] + y[i-1] + .1)|&(parenthesized expression)\\
1734\end{tabular}
1735
1736\medskip
1737
1738More general linear expressions containing two or more primary linear
1739expressions may be constructed by using certain arithmetic operators.
1740
1741\medskip
1742
1743\noindent{\bf Examples}
1744
1745\medskip
1746
1747\noindent\verb|2 * x[i-1,j+1] + 3.5 * y[k] + .5 * z|
1748
1749\noindent\verb|(- x[i,j] + 3.5 * y[k]) / sum{t in T} abs(d[i,j,t])|
1750
1751\subsubsection{Unsubscripted variables}
1752
1753If the primary linear expression is an unsubscripted variable (which
1754must be 0-dimensional), the resultant formula is that unsubscripted
1755variable.
1756
1757\subsubsection{Subscripted variables}
1758
1759The primary linear expression, which refers to a subscripted variable,
1760has the following syntactic form:
1761
1762\medskip
1763
1764\noindent\hfil
1765{\it name}{\tt[}$i_1${\tt,} $i_2${\tt,} \dots{\tt,} $i_n${\tt]}
1766
1767\medskip
1768
1769\noindent where {\it name} is the symbolic name of the model variable,
1770$i_1$, $i_2$, \dots, $i_n$ are subscripts.
1771
1772Each subscript must be a numeric or symbolic expression. The number of
1773subscripts in the subscript list must be the same as the dimension of
1774the model variable with which the subscript list is associated.
1775
1776Actual values of the subscript expressions are used to identify a
1777particular member of the model variable that determines the resultant
1778formula, which is an elemental variable associated with corresponding
1779member.
1780
1781\subsubsection{Iterated expressions}
1782
1783An {\it iterated linear expression} is a primary linear expression,
1784which has the following syntactic form:
1785
1786\medskip
1787
1788\noindent\hfil
1789{\tt sum} {\it indexing-expression} {\it integrand}
1790
1791\medskip
1792
1793\noindent where {\it indexing-expression} is an indexing expression,
1794which introduces dummy indices and controls iterating, {\it integrand}
1795is a linear expression that participates in the operation.
1796
1797The iterated linear expression is evaluated exactly in the same way as
1798the iterated numeric expression (see Subection \ref{itexpr}, page
1799\pageref{itexpr}) with exception that the integrand participated in the
1800summation is a formula, not a numeric value.
1801
1802\subsubsection{Conditional expressions}
1803
1804A {\it conditional linear expression} is a primary linear expression,
1805which has one of the following two syntactic forms:
1806
1807\medskip
1808
1809\noindent\hfil
1810{\tt if} $b$ {\tt then} $f$ {\tt else} $g$
1811
1812\medskip
1813
1814\noindent\hspace{127pt}
1815{\tt if} $b$ {\tt then} $f$
1816
1817\medskip
1818
1819\noindent where $b$ is an logical expression, $f$ and $g$ are linear
1820expressions.
1821
1822The conditional linear expression is evaluated exactly in the same way
1823as the conditional numeric expression (see Subsection \ref{ifthen},
1824page \pageref{ifthen}) with exception that operands participated in the
1825operation are formulae, not numeric values.
1826
1827\subsubsection{Parenthesized expressions}
1828
1829Any linear expression may be enclosed in parentheses that syntactically
1830makes it a primary linear expression.
1831
1832Parentheses may be used in linear expressions, as in algebra, to
1833specify the desired order in which operations are to be performed.
1834Where parentheses are used, the expression within the parentheses is
1835evaluated before the resultant formula is used.
1836
1837The resultant value of the parenthesized expression is the same as the
1838value of the expression enclosed within parentheses.
1839
1840\subsubsection{Arithmetic operators}
1841
1842In MathProg there exists the following arithmetic operators, which may
1843be used in linear expressions:
1844
1845\medskip
1846
1847\begin{tabular}{@{}p{96pt}p{222pt}@{}}
1848{\tt+} $f$&unary plus\\
1849{\tt-} $f$&unary minus\\
1850$f$ {\tt+} $g$&addition\\
1851$f$ {\tt-} $g$&subtraction\\
1852$x$ {\tt*} $f$, $f$ {\tt*} $x$&multiplication\\
1853$f$ {\tt/} $x$&division
1854\end{tabular}
1855
1856\medskip
1857
1858\noindent where $f$ and $g$ are linear expressions, $x$ is a numeric
1859expression (more precisely, a linear expression containing only the
1860constant term).
1861
1862If the expression includes more than one arithmetic operator, all
1863operators are performed from left to right according to the hierarchy
1864of operations (see below). The resultant value of the expression, which
1865contains arithmetic operators, is the result of applying the operators
1866to their operands.
1867
1868\subsubsection{Hierarchy of operations}
1869
1870The hierarchy of arithmetic operations used in linear expressions is
1871the same as for numeric expressions (see Subsection \ref{hierarchy},
1872page \pageref{hierarchy}).
1873
1874%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1875
1876\newpage
1877
1878\section{Statements}
1879
1880{\it Statements} are basic units of the model description. In MathProg
1881all statements are divided into two categories: declaration statements
1882and functional statements.
1883
1884{\it Declaration statements} (set statement, parameter statement,
1885variable statement, constraint statement, and objective statement) are
1886used to declare model objects of certain kinds and define certain
1887properties of such objects.
1888
1889{\it Functional statements} (solve statement, check statement, display
1890statement, printf statement, loop statement) are intended for
1891performing some specific actions.
1892
1893Note that declaration statements may follow in arbitrary order, which
1894does not affect the result of translation. However, any model object
1895must be declared before it is referenced in other statements.
1896
1897\subsection{Set statement}
1898
1899\medskip
1900
1901\framebox[345pt][l]{
1902\parbox[c][24pt]{345pt}{
1903\hspace{6pt} {\tt set} {\it name} {\it alias} {\it domain} {\tt,}
1904{\it attrib} {\tt,} \dots {\tt,} {\it attrib} {\tt;}
1905}}
1906
1907\setlength{\leftmargini}{60pt}
1908
1909\begin{description}
1910\item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
1911set;
1912\item[\hspace*{54pt}] {\it alias} is an optional string literal, which
1913specifies an alias of the set;
1914\item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
1915which specifies a subscript domain of the set;
1916\item[\hspace*{54pt}] {\it attrib}, \dots, {\it attrib} are optional
1917attributes of the set. (Commae preceding attributes may be omitted.)
1918\end{description}
1919
1920\noindent Optional attributes:
1921
1922\begin{description}
1923\item[{\tt dimen} $n$\hspace*{19pt}] specifies the dimension of
1924$n$-tuples, which the set consists of;
1925\item[{\tt within} {\it expression}]\hspace*{0pt}\\
1926specifies a superset which restricts the set or all its members
1927(elemental sets) to be within that superset;
1928\item[{\tt:=} {\it expression}]\hspace*{0pt}\\
1929specifies an elemental set assigned to the set or its members;
1930\item[{\tt default} {\it expression}]\hspace*{0pt}\\
1931specifies an elemental set assigned to the set or its members whenever
1932no appropriate data are available in the data section.
1933\end{description}
1934
1935\newpage
1936
1937\noindent{\bf Examples}
1938
1939\begin{verbatim}
1940set V;
1941set E within V cross V;
1942set step{s in 1..maxiter} dimen 2 := if s = 1 then E else
1943   step[s-1] union setof{k in V, (i,k) in step[s-1], (k,j)
1944   in step[s-1]}(i,j);
1945set A{i in I, j in J}, within B[i+1] cross C[j-1], within
1946   D diff E, default {('abc',123), (321,'cba')};
1947\end{verbatim}
1948
1949The set statement declares a set. If the subscript domain is not
1950specified, the set is a simple set, otherwise it is an array of
1951elemental sets.
1952
1953The {\tt dimen} attribute specifies the dimension of $n$-tuples, which
1954the set (if it is a simple set) or its members (if the set is an array
1955of elemental sets) consist of, where $n$ must be unsigned integer from
19561 to 20. At most one {\tt dimen} attribute can be specified. If the
1957{\tt dimen} attribute is not specified, the dimension of\linebreak
1958$n$-tuples is implicitly determined by other attributes (for example,
1959if there is a set expression that follows {\tt:=} or the keyword
1960{\tt default}, the dimension of $n$-tuples of corresponding elemental
1961set is used). If no dimension information is available, {\tt dimen 1}
1962is assumed.
1963
1964The {\tt within} attribute specifies a set expression whose resultant
1965value is a superset used to restrict the set (if it is a simple set) or
1966its members (if the set is an array of elemental sets) to be within
1967that superset. Arbitrary number of {\tt within} attributes may be
1968specified in the same set statement.
1969
1970The assign ({\tt:=}) attribute specifies a set expression used to
1971evaluate elemental set(s) assigned to the set (if it is a simple set)
1972or its members (if the set is an array of elemental sets). If the
1973assign attribute is specified, the set is {\it computable} and
1974therefore needs no data to be provided in the data section. If the
1975assign attribute is not specified, the set must be provided with data
1976in the data section. At most one assign or default attribute can be
1977specified for the same set.
1978
1979The {\tt default} attribute specifies a set expression used to evaluate
1980elemental set(s) assigned to the set (if it is a simple set) or its
1981members (if the set is an array of elemental sets) whenever
1982no appropriate data are available in the data section. If neither
1983assign nor default attribute is specified, missing data will cause an
1984error.
1985
1986\subsection{Parameter statement}
1987
1988\medskip
1989
1990\framebox[345pt][l]{
1991\parbox[c][24pt]{345pt}{
1992\hspace{6pt} {\tt param} {\it name} {\it alias} {\it domain} {\tt,}
1993{\it attrib} {\tt,} \dots {\tt,} {\it attrib} {\tt;}
1994}}
1995
1996\setlength{\leftmargini}{60pt}
1997
1998\begin{description}
1999\item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2000parameter;
2001\item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2002specifies an alias of the parameter;
2003\item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
2004which specifies a subscript domain of the parameter;
2005\item[\hspace*{54pt}] {\it attrib}, \dots, {\it attrib} are optional
2006attributes of the parameter. (Commae preceding attributes may be
2007omitted.)
2008\end{description}
2009
2010\noindent Optional attributes:
2011
2012\begin{description}
2013\item[{\tt integer}\hspace*{18.5pt}] specifies that the parameter is
2014integer;
2015\item[{\tt binary}\hspace*{24pt}] specifies that the parameter is
2016binary;
2017\item[{\tt symbolic}\hspace*{13.5pt}] specifies that the parameter is
2018symbolic;
2019\item[{\it relation expression}]\hspace*{0pt}\\
2020(where {\it relation} is one of: {\tt<}, {\tt<=}, {\tt=}, {\tt==},
2021{\tt>=}, {\tt>}, {\tt<>}, {\tt!=})\\
2022specifies a condition that restricts the parameter or its members to
2023satisfy that condition;
2024\item[{\tt in} {\it expression}]\hspace*{0pt}\\
2025specifies a superset that restricts the parameter or its members to be
2026in that superset;
2027\item[{\tt:=} {\it expression}]\hspace*{0pt}\\
2028specifies a value assigned to the parameter or its members;
2029\item[{\tt default} {\it expression}]\hspace*{0pt}\\
2030specifies a value assigned to the parameter or its members whenever
2031no appropriate data are available in the data section.
2032\end{description}
2033
2034\noindent{\bf Examples}
2035
2036\begin{verbatim}
2037param units{raw, prd} >= 0;
2038param profit{prd, 1..T+1};
2039param N := 20, integer, >= 0, <= 100;
2040param comb 'n choose k' {n in 0..N, k in 0..n} :=
2041   if k = 0 or k = n then 1 else comb[n-1,k-1] + comb[n-1,k];
2042param p{i in I, j in J}, integer, >= 0, <= i+j,
2043   in A[i] symdiff B[j], in C[i,j], default 0.5 * (i + j);
2044param month symbolic default 'May' in {'Mar', 'Apr', 'May'};
2045\end{verbatim}
2046
2047The parameter statement declares a parameter. If a subscript domain is
2048not specified, the parameter is a simple (scalar) parameter, otherwise
2049it is a $n$-dimensional array.
2050
2051The type attributes {\tt integer}, {\tt binary}, and {\tt symbolic}
2052qualify the type of values that can be assigned to the parameter as
2053shown below:
2054
2055\medskip
2056
2057\noindent\hfil
2058\begin{tabular}{@{}ll@{}}
2059Type attribute&Assigned values\\
2060\hline
2061(not specified)&Any numeric values\\
2062{\tt integer}&Only integer numeric values\\
2063{\tt binary}&Either 0 or 1\\
2064{\tt symbolic}&Any numeric and symbolic values\\
2065\end{tabular}
2066
2067\newpage
2068
2069The {\tt symbolic} attribute cannot be specified along with other type
2070attributes. Being specified it must precede all other attributes.
2071
2072The condition attribute specifies an optional condition that restricts
2073values assigned to the parameter to satisfy that condition. This
2074attribute has the following syntactic forms:
2075
2076\medskip
2077
2078\begin{tabular}{@{}ll@{}}
2079{\tt<} $v$&check for $x<v$\\
2080{\tt<=} $v$&check for $x\leq v$\\
2081{\tt=} $v$, {\tt==} $v$&check for $x=v$\\
2082{\tt>=} $v$&check for $x\geq v$\\
2083{\tt>} $v$&check for $x\geq v$\\
2084{\tt<>} $v$, {\tt!=} $v$&check for $x\neq v$\\
2085\end{tabular}
2086
2087\medskip
2088
2089\noindent where $x$ is a value assigned to the parameter, $v$ is the
2090resultant value of a numeric or symbolic expression specified in the
2091condition attribute. Arbitrary number of condition attributes can be
2092specified for the same parameter. If a value being assigned to the
2093parameter during model evaluation violates at least one of specified
2094conditions, an error is raised. (Note that symbolic values are ordered
2095lexicographically, and any numeric value precedes any symbolic value.)
2096
2097The {\tt in} attribute is similar to the condition attribute and
2098specifies a set expression whose resultant value is a superset used to
2099restrict numeric or symbolic values assigned to the parameter to be in
2100that superset. Arbitrary number of the {\tt in} attributes can be
2101specified for the same parameter. If a value being assigned to the
2102parameter during model evaluation is not in at least one of specified
2103supersets, an error is raised.
2104
2105The assign ({\tt:=}) attribute specifies a numeric or symbolic
2106expression used to compute a value assigned to the parameter (if it is
2107a simple parameter) or its member (if the parameter is an array). If
2108the assign attribute is specified, the parameter is {\it computable}
2109and therefore needs no data to be provided in the data section. If the
2110assign attribute is not specified, the parameter must be provided with
2111data in the data section. At most one assign or {\tt default} attribute
2112can be specified for the same parameter.
2113
2114The {\tt default} attribute specifies a numeric or symbolic expression
2115used to compute a value assigned to the parameter or its member
2116whenever no appropriate data are available in the data section. If
2117neither assign nor {\tt default} attribute is specified, missing data
2118will cause an error.
2119
2120\subsection{Variable statement}
2121
2122\medskip
2123
2124\framebox[345pt][l]{
2125\parbox[c][24pt]{345pt}{
2126\hspace{6pt} {\tt var} {\it name} {\it alias} {\it domain} {\tt,}
2127{\it attrib} {\tt,} \dots {\tt,} {\it attrib} {\tt;}
2128}}
2129
2130\setlength{\leftmargini}{60pt}
2131
2132\begin{description}
2133\item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2134variable;
2135\item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2136specifies an alias of the variable;
2137\item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
2138which specifies a subscript domain of the variable;
2139\item[\hspace*{54pt}] {\it attrib}, \dots, {\it attrib} are optional
2140attributes of the variable. (Commae preceding attributes may be
2141omitted.)
2142\end{description}
2143
2144\noindent Optional attributes:
2145
2146\begin{description}
2147\item[{\tt integer}\hspace*{18.5pt}] restricts the variable to be
2148integer;
2149\item[{\tt binary}\hspace*{24pt}] restricts the variable to be binary;
2150\item[{\tt>=} {\it expression}]\hspace*{0pt}\\
2151specifies an lower bound of the variable;
2152\item[{\tt<=} {\it expression}]\hspace*{0pt}\\
2153specifies an upper bound of the variable;
2154\item[{\tt=} {\it expression}]\hspace*{0pt}\\
2155specifies a fixed value of the variable;
2156\end{description}
2157
2158\noindent{\bf Examples}
2159
2160\begin{verbatim}
2161var x >= 0;
2162var y{I,J};
2163var make{p in prd}, integer, >= commit[p], <= market[p];
2164var store{raw, 1..T+1} >= 0;
2165var z{i in I, j in J} >= i+j;
2166\end{verbatim}
2167
2168The variable statement declares a variable. If a subscript domain is
2169not specified, the variable is a simple (scalar) variable, otherwise it
2170is a $n$-dimensional array of elemental variables.
2171
2172Elemental variable(s) associated with the model variable (if it is a
2173simple variable) or its members (if it is an array) correspond to the
2174variables in the LP/MIP problem formulation (see Subsection
2175\ref{problem}, page \pageref{problem}). Note that only elemental
2176variables actually referenced in some constraints and/or objectives are
2177included in the LP/MIP problem instance to be generated.
2178
2179The type attributes {\tt integer} and {\tt binary} restrict the
2180variable to be integer or binary, respectively. If no type attribute is
2181specified, the variable is continuous. If all variables in the model
2182are continuous, the corresponding problem is of LP class. If there is
2183at least one integer or binary variable, the problem is of MIP class.
2184
2185The lower bound ({\tt>=}) attribute specifies a numeric expression for
2186computing an lower bound of the variable. At most one lower bound can
2187be specified. By default all variables (except binary ones) have no
2188lower bound, so if a variable is required to be non-negative, its zero
2189lower bound should be explicitly specified.
2190
2191The upper bound ({\tt<=}) attribute specifies a numeric expression for
2192computing an upper bound of the variable. At most one upper bound
2193attribute can be specified.
2194
2195The fixed value ({\tt=}) attribute specifies a numeric expression for
2196computing a value, at which the variable is fixed. This attribute
2197cannot be specified along with the bound attributes.
2198
2199\subsection{Constraint statement}
2200
2201\medskip
2202
2203\framebox[345pt][l]{
2204\parbox[c][96pt]{345pt}{
2205\hspace{6pt} {\tt s.t.} {\it name} {\it alias} {\it domain} {\tt:}
2206{\it expression} {\tt,} {\tt=} {\it expression} {\tt;}
2207
2208\medskip
2209
2210\hspace{6pt} {\tt s.t.} {\it name} {\it alias} {\it domain} {\tt:}
2211{\it expression} {\tt,} {\tt<=} {\it expression} {\tt;}
2212
2213\medskip
2214
2215\hspace{6pt} {\tt s.t.} {\it name} {\it alias} {\it domain} {\tt:}
2216{\it expression} {\tt,} {\tt>=} {\it expression} {\tt;}
2217
2218\medskip
2219
2220\hspace{6pt} {\tt s.t.} {\it name} {\it alias} {\it domain} {\tt:}
2221{\it expression} {\tt,} {\tt<=} {\it expression} {\tt,} {\tt<=}
2222{\it expression} {\tt;}
2223
2224\medskip
2225
2226\hspace{6pt} {\tt s.t.} {\it name} {\it alias} {\it domain} {\tt:}
2227{\it expression} {\tt,} {\tt>=} {\it expression} {\tt,} {\tt>=}
2228{\it expression} {\tt;}
2229}}
2230
2231\setlength{\leftmargini}{60pt}
2232
2233\begin{description}
2234\item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2235constraint;
2236\item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2237specifies an alias of the constraint;
2238\item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
2239which specifies a subscript domain of the constraint;
2240\item[\hspace*{54pt}] {\it expression} is a linear expression used to
2241compute a component of the constraint. (Commae following expressions
2242may be omitted.)
2243\end{description}
2244
2245\begin{description}
2246\item[{\rm Note:}\hspace*{31pt}] The keyword {\tt s.t.} may be written
2247as {\tt subject to} or as {\tt subj to}, or may be omitted at all.
2248\end{description}
2249
2250\noindent{\bf Examples}
2251
2252\begin{verbatim}
2253s.t. r: x + y + z, >= 0, <= 1;
2254limit{t in 1..T}: sum{j in prd} make[j,t] <= max_prd;
2255subject to balance{i in raw, t in 1..T}: store[i,t+1] -
2256   store[i,t] - sum{j in prd} units[i,j] * make[j,t];
2257subject to rlim 'regular-time limit' {t in time}:
2258sum{p in prd} pt[p] * rprd[p,t] <= 1.3 * dpp[t] * crews[t];
2259\end{verbatim}
2260
2261The constraint statement declares a constraint. If a subscript domain
2262is not specified, the constraint is a simple (scalar) constraint,
2263otherwise it is a $n$-dimensional array of elemental constraints.
2264
2265Elemental constraint(s) associated with the model constraint (if it is
2266a simple constraint) or its members (if it is an array) correspond to
2267the linear constraints in the LP/MIP problem formulation (see
2268Subsection \ref{problem}, page \pageref{problem}).
2269
2270If the constraint has the form of equality or single inequality, i.e.
2271includes two expressions, one of which follows the colon and other
2272follows the relation sign {\tt=}, {\tt<=}, or {\tt>=}, both expressions
2273in the statement can be linear expressions. If the constraint has the
2274form of double inequality, i.e. includes three expressions, the middle
2275expression can be a linear expression while the leftmost and rightmost
2276ones can be only numeric expressions.
2277
2278Generating the model is, roughly speaking, generating its constraints,
2279which are always evaluated for the entire subscript domain. Evaluation
2280of the constraints leads, in turn, to evaluation of other model objects
2281such as sets, parameters, and variables.
2282
2283Constructing an actual linear constraint included in the problem
2284instance, which (constraint) corresponds to a particular elemental
2285constraint, is performed as follows.
2286
2287If the constraint has the form of equality or single inequality,
2288evaluation of both linear expressions gives two resultant linear forms:
2289$$\begin{array}{r@{\ }c@{\ }r@{\ }c@{\ }r@{\ }c@{\ }r@{\ }c@{\ }r}
2290f&=&a_1x_1&+&a_2x_2&+\dots+&a_nx_n&+&a_0,\\
2291g&=&b_1x_1&+&a_2x_2&+\dots+&a_nx_n&+&b_0,\\
2292\end{array}$$
2293where $x_1$, $x_2$, \dots, $x_n$ are elemental variables; $a_1$, $a_2$,
2294\dots, $a_n$, $b_1$, $b_2$, \dots, $b_n$ are numeric coefficients;
2295$a_0$ and $b_0$ are constant terms. Then all linear terms of $f$ and
2296$g$ are carried to the left-hand side, and the constant terms are
2297carried to the right-hand side, that gives the final elemental
2298constraint in the standard form:
2299$$(a_1-b_1)x_1+(a_2-b_2)x_2+\dots+(a_n-b_n)x_n\left\{
2300\begin{array}{@{}c@{}}=\\\leq\\\geq\\\end{array}\right\}b_0-a_0.$$
2301
2302If the constraint has the form of double inequality, evaluation of the
2303middle linear expression gives the resultant linear form:
2304$$f=a_1x_1+a_2x_2+\dots+a_nx_n+a_0,$$
2305and evaluation of the leftmost and rightmost numeric expressions gives
2306two numeric values $l$ and $u$, respectively. Then the constant term of
2307the linear form is carried to both left-hand and right-handsides that
2308gives the final elemental constraint in the standard form:
2309$$l-a_0\leq a_1x_1+a_2x_2+\dots+a_nx_n\leq u-a_0.$$
2310
2311\subsection{Objective statement}
2312
2313\medskip
2314
2315\framebox[345pt][l]{
2316\parbox[c][44pt]{345pt}{
2317\hspace{6pt} {\tt minimize} {\it name} {\it alias} {\it domain} {\tt:}
2318{\it expression} {\tt;}
2319
2320\medskip
2321
2322\hspace{6pt} {\tt maximize} {\it name} {\it alias} {\it domain} {\tt:}
2323{\it expression} {\tt;}
2324}}
2325
2326\setlength{\leftmargini}{60pt}
2327
2328\begin{description}
2329\item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2330objective;
2331\item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2332specifies an alias of the objective;
2333\item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
2334which specifies a subscript domain of the objective;
2335\item[\hspace*{54pt}] {\it expression} is a linear expression used to
2336compute the linear form of the objective.
2337\end{description}
2338
2339\noindent{\bf Examples}
2340
2341\begin{verbatim}
2342minimize obj: x + 1.5 * (y + z);
2343maximize total_profit: sum{p in prd} profit[p] * make[p];
2344\end{verbatim}
2345
2346The objective statement declares an objective. If a subscript domain is
2347not specified, the objective is a simple (scalar) objective. Otherwise
2348it is a $n$-dimensional array of elemental objectives.
2349
2350Elemental objective(s) associated with the model objective (if it is a
2351simple objective) or its members (if it is an array) correspond to
2352general linear constraints in the LP/MIP problem formulation (see
2353Subsection \ref{problem}, page \pageref{problem}). However, unlike
2354constraints the corresponding linear forms are free (unbounded).
2355
2356Constructing an actual linear constraint included in the problem
2357instance, which (constraint) corresponds to a particular elemental
2358constraint, is performed as follows. The linear expression specified in
2359the objective statement is evaluated that, gives the resultant linear
2360form:
2361$$f=a_1x_1+a_2x_2+\dots+a_nx_n+a_0,$$
2362where $x_1$, $x_2$, \dots, $x_n$ are elemental variables; $a_1$, $a_2$,
2363\dots, $a_n$ are numeric coefficients; $a_0$ is the constant term. Then
2364the linear form is used to construct the final elemental constraint in
2365the standard form:
2366$$-\infty<a_1x_1+a_2x_2+\dots+a_nx_n+a_0<+\infty.$$
2367
2368As a rule the model description contains only one objective statement
2369that defines the objective function used in the problem instance.
2370However, it is allowed to declare arbitrary number of objectives, in
2371which case the actual objective function is the first objective
2372encountered in the model description. Other objectives are also
2373included in the problem instance, but they do not affect the objective
2374function.
2375
2376\subsection{Solve statement}
2377
2378\medskip
2379
2380\framebox[345pt][l]{
2381\parbox[c][24pt]{345pt}{
2382\hspace{6pt} {\tt solve} {\tt;}
2383}}
2384
2385\setlength{\leftmargini}{60pt}
2386
2387\begin{description}
2388\item[{\rm Note:}\hspace*{31pt}] The solve statement is optional and
2389can be used only once. If no solve statement is used, one is assumed at
2390the end of the model section.
2391\end{description}
2392
2393The solve statement causes the model to be solved, that means computing
2394numeric values of all model variables. This allows using variables in
2395statements below the solve statement in the same way as if they were
2396numeric parameters.
2397
2398Note that the variable, constraint, and objective statements cannot be
2399used below the solve statement, i.e. all principal components of the
2400model must be declared above the solve statement.
2401
2402\subsection{Check statement}
2403
2404\medskip
2405
2406\framebox[345pt][l]{
2407\parbox[c][24pt]{345pt}{
2408\hspace{6pt} {\tt check} {\it domain} {\tt:} {\it expression} {\tt;}
2409}}
2410
2411\setlength{\leftmargini}{60pt}
2412
2413\begin{description}
2414\item[{\rm Where:}\hspace*{23pt}] {\it domain} is an optional indexing
2415expression, which specifies a subscript domain of the check statement;
2416\item[\hspace*{54pt}] {\it expression} is an logical expression which
2417specifies the logical condition to be checked. (The colon preceding
2418{\it expression} may be omitted.)
2419\end{description}
2420
2421\noindent{\bf Examples}
2422
2423\begin{verbatim}
2424check: x + y <= 1 and x >= 0 and y >= 0;
2425check sum{i in ORIG} supply[i] = sum{j in DEST} demand[j];
2426check{i in I, j in 1..10}: S[i,j] in U[i] union V[j];
2427\end{verbatim}
2428
2429The check statement allows checking the resultant value of an logical
2430expression specified in the statement. If the value is {\it false}, an
2431error is reported.
2432
2433If the subscript domain is not specified, the check is performed only
2434once. Specifying the subscript domain allows performing multiple checks
2435for every\linebreak $n$-tuple in the domain set. In the latter case the
2436logical expression may include dummy indices introduced in
2437corresponding indexing expression.
2438
2439\subsection{Display statement}
2440
2441\medskip
2442
2443\framebox[345pt][l]{
2444\parbox[c][24pt]{345pt}{
2445\hspace{6pt} {\tt display} {\it domain} {\tt:} {\it item} {\tt,}
2446\dots {\tt,} {\it item} {\tt;}
2447}}
2448
2449\setlength{\leftmargini}{60pt}
2450
2451\begin{description}
2452\item[{\rm Where:}\hspace*{23pt}] {\it domain} is an optional indexing
2453expression, which specifies a subscript domain of the check statement;
2454\item[\hspace*{54pt}] {\it item}, \dots, {\it item} are items to be
2455displayed. (The colon preceding the first item may be omitted.)
2456\end{description}
2457
2458\noindent{\bf Examples}
2459
2460\begin{verbatim}
2461display: 'x =', x, 'y =', y, 'z =', z;
2462display sqrt(x ** 2 + y ** 2 + z ** 2);
2463display{i in I, j in J}: i, j, a[i,j], b[i,j];
2464\end{verbatim}
2465
2466\newpage
2467
2468The display statement evaluates all items specified in the statement
2469and writes their values to the terminal in plain text format.
2470
2471If a subscript domain is not specified, items are evaluated and then
2472displayed only once. Specifying the subscript domain causes items to be
2473evaluated and displayed for every $n$-tuple in the domain set. In the
2474latter case items may include dummy indices introduced in corresponding
2475indexing expression.
2476
2477An item to be displayed can be a model object (set, parameter, variable,
2478constraint, objective) or an expression.
2479
2480If the item is a computable object (i.e. a set or parameter provided
2481with the assign attribute), the object is evaluated over the entire
2482domain and then its content (i.e. the content of the object array) is
2483displayed. Otherwise, if the item is not a computable object, only its
2484current content (i.e. members actually generated during the model
2485evaluation) is displayed.
2486
2487If the item is an expression, the expression is evaluated and its
2488resultant value is displayed.
2489
2490\subsection{Printf statement}
2491
2492\medskip
2493
2494\framebox[345pt][l]{
2495\parbox[c][60pt]{345pt}{
2496\hspace{6pt} {\tt printf} {\it domain} {\tt:} {\it format} {\tt,}
2497{\it expression} {\tt,} \dots {\tt,} {\it expression} {\tt;}
2498
2499\medskip
2500
2501\hspace{6pt} {\tt printf} {\it domain} {\tt:} {\it format} {\tt,}
2502{\it expression} {\tt,} \dots {\tt,} {\it expression} {\tt>}
2503{\it filename} {\tt;}
2504
2505\medskip
2506
2507\hspace{6pt} {\tt printf} {\it domain} {\tt:} {\it format} {\tt,}
2508{\it expression} {\tt,} \dots {\tt,} {\it expression} {\tt>>}
2509{\it filename} {\tt;}
2510}}
2511
2512\setlength{\leftmargini}{60pt}
2513
2514\begin{description}
2515\item[{\rm Where:}\hspace*{23pt}] {\it domain} is an optional indexing
2516expression, which specifies a subscript domain of the printf statement;
2517\item[\hspace*{54pt}] {\it format} is a symbolic expression whose value
2518specifies a format control string. (The colon preceding the format
2519expression may be omitted.)
2520\item[\hspace*{54pt}] {\it expression}, \dots, {\it expression} are
2521zero or more expressions whose values have to be formatted and printed.
2522Each expression must be of numeric, symbolic, or logical type.
2523\item[\hspace*{54pt}] {\it filename} is a symbolic expression whose
2524value specifies a name of a text file, to which the output is
2525redirected. The flag {\tt>} means creating a new empty file while the
2526flag {\tt>>} means appending the output to an existing file. If no file
2527name is specified, the output is written to the terminal.
2528\end{description}
2529
2530\noindent{\bf Examples}
2531
2532\begin{verbatim}
2533printf 'Hello, world!\n';
2534printf: "x = %.3f; y = %.3f; z = %.3f\n",
2535   x, y, z > "result.txt";
2536printf{i in I, j in J}: "flow from %s to %s is %d\n",
2537   i, j, x[i,j] >> result_file & ".txt";
2538\end{verbatim}
2539
2540\newpage
2541
2542\begin{verbatim}
2543printf{i in I} 'total flow from %s is %g\n',
2544   i, sum{j in J} x[i,j];
2545printf{k in K} "x[%s] = " & (if x[k] < 0 then "?" else "%g"),
2546   k, x[k];
2547\end{verbatim}
2548
2549The printf statement is similar to the display statement, however, it
2550allows formatting data to be written.
2551
2552If a subscript domain is not specified, the printf statement is
2553executed only once. Specifying a subscript domain causes executing the
2554printf statement for every $n$-tuple in the domain set. In the latter
2555case the format and expression may include dummy indices introduced in
2556corresponding indexing expression.
2557
2558The format control string is a value of the symbolic expression
2559{\it format} specified in the printf statement. It is composed of zero
2560or more directives as follows: ordinary characters (not {\tt\%}), which
2561are copied unchanged to the output stream, and conversion
2562specifications, each of which causes evaluating corresponding
2563expression specified in the printf statement, formatting it, and
2564writing its resultant value to the output stream.
2565
2566Conversion specifications that may be used in the format control string
2567are the following: {\tt d}, {\tt i}, {\tt f}, {\tt F}, {\tt e}, {\tt E},
2568{\tt g}, {\tt G}, and {\tt s}. These specifications have the same
2569syntax and semantics as in the C programming language.
2570
2571\subsection{For statement}
2572
2573\medskip
2574
2575\framebox[345pt][l]{
2576\parbox[c][44pt]{345pt}{
2577\hspace{6pt} {\tt for} {\it domain} {\tt:} {\it statement} {\tt;}
2578
2579\medskip
2580
2581\hspace{6pt} {\tt for} {\it domain} {\tt:} {\tt\{} {\it statement}
2582\dots {\it statement} {\tt\}} {\tt;}
2583}}
2584
2585\setlength{\leftmargini}{60pt}
2586
2587\begin{description}
2588\item[{\rm Where:}\hspace*{23pt}] {\it domain} is an indexing
2589expression which specifies a subscript domain of the for statement.
2590(The colon following the indexing expression may be omitted.)
2591\item[\hspace*{54pt}] {\it statement} is a statement, which should be
2592executed under control of the for statement;
2593\item[\hspace*{54pt}] {\it statement}, \dots, {\it statement} is a
2594sequence of statements (enclosed in curly braces), which should be
2595executed under control of the for statement.
2596\end{description}
2597
2598\begin{description}
2599\item[{\rm Note:}\hspace*{31pt}] Only the following statements can be
2600used within the for statement: check, display, printf, and another for.
2601\end{description}
2602
2603\noindent{\bf Examples}
2604
2605\begin{verbatim}
2606for {(i,j) in E: i != j}
2607{  printf "flow from %s to %s is %g\n", i, j, x[i,j];
2608   check x[i,j] >= 0;
2609}
2610\end{verbatim}
2611
2612\newpage
2613
2614\begin{verbatim}
2615for {i in 1..n}
2616{  for {j in 1..n} printf " %s", if x[i,j] then "Q" else ".";
2617   printf("\n");
2618}
2619for {1..72} printf("*");
2620\end{verbatim}
2621
2622The for statement causes a statement or a sequence of statements
2623specified as part of the for statement to be executed for every
2624$n$-tuple in the domain set. Thus, statements within the for statement
2625may include dummy indices introduced in corresponding indexing
2626expression.
2627
2628\subsection{Table statement}
2629
2630\medskip
2631
2632\framebox[345pt][l]{
2633\parbox[c][68pt]{345pt}{
2634\hspace{6pt} {\tt table} {\it name} {\it alias} {\tt IN} {\it driver}
2635{\it arg} \dots {\it arg} {\tt:}
2636
2637\hspace{6pt} {\tt\ \ \ \ \ } {\it set} {\tt<-} {\tt[} {\it fld} {\tt,}
2638\dots {\tt,} {\it fld} {\tt]} {\tt,} {\it par} {\tt\textasciitilde}
2639{\it fld} {\tt,} \dots {\tt,} {\it par} {\tt\textasciitilde} {\it fld}
2640{\tt;}
2641
2642\medskip
2643
2644\hspace{6pt} {\tt table} {\it name} {\it alias} {\it domain} {\tt OUT}
2645{\it driver} {\it arg} \dots {\it arg} {\tt:}
2646
2647\hspace{6pt} {\tt\ \ \ \ \ } {\it expr} {\tt\textasciitilde} {\it fld}
2648{\tt,} \dots {\tt,} {\it expr} {\tt\textasciitilde} {\it fld} {\tt;}
2649}}
2650
2651\setlength{\leftmargini}{60pt}
2652
2653\begin{description}
2654\item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2655table;
2656\item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2657specifies an alias of the table;
2658\item[\hspace*{54pt}] {\it domain} is an indexing expression, which
2659specifies a subscript domain of the (output) table;
2660\item[\hspace*{54pt}] {\tt IN} means reading data from the input table;
2661\item[\hspace*{54pt}] {\tt OUT} means writing data to the output table;
2662\item[\hspace*{54pt}] {\it driver} is a symbolic expression, which
2663specifies the driver used to access the table (for details see Section
2664\ref{drivers}, page \pageref{drivers});
2665\item[\hspace*{54pt}] {\it arg} is an optional symbolic expression,
2666which is an argument pass\-ed to the table driver. This symbolic
2667expression must not include dummy indices specified in the domain;
2668\item[\hspace*{54pt}] {\it set} is the name of an optional simple set
2669called {\it control set}. It can be omitted along with the delimiter
2670{\tt<-};
2671\item[\hspace*{54pt}] {\it fld} is a field name. Within square brackets
2672at least one field should be specified. The field name following
2673a parameter name or expression is optional and can be omitted along
2674with the delimiter {\tt\textasciitilde}, in which case the name of
2675corresponding model object is used as the field name;
2676\item[\hspace*{54pt}] {\it par} is a symbolic name of a model parameter;
2677\item[\hspace*{54pt}] {\it expr} is a numeric or symbolic expression.
2678\end{description}
2679
2680\newpage
2681
2682\noindent{\bf Examples}
2683
2684\begin{verbatim}
2685table data IN "CSV" "data.csv":
2686   S <- [FROM,TO], d~DISTANCE, c~COST;
2687table result{(f,t) in S} OUT "CSV" "result.csv":
2688   f~FROM, t~TO, x[f,t]~FLOW;
2689\end{verbatim}
2690
2691The table statement allows reading data from a table into model
2692objects such as sets and (non-scalar) parameters as well as writing
2693data from the model to a table.
2694
2695\subsubsection{Table structure}
2696
2697A {\it data table} is an (unordered) set of {\it records}, where each
2698record consists of the same number of {\it fields}, and each field is
2699provided with a unique symbolic name called the {\it field name}. For
2700example:
2701
2702\bigskip
2703
2704\begin{tabular}{@{\hspace*{38mm}}c@{\hspace*{11mm}}c@{\hspace*{10mm}}c
2705@{\hspace*{9mm}}c}
2706First&Second&&Last\\
2707field&field&.\ \ .\ \ .&field\\
2708$\downarrow$&$\downarrow$&&$\downarrow$\\
2709\end{tabular}
2710
2711\begin{tabular}{ll@{}}
2712Table header&$\rightarrow$\\
2713First record&$\rightarrow$\\
2714Second record&$\rightarrow$\\
2715\\
2716\hfil .\ \ .\ \ .\\
2717\\
2718Last record&$\rightarrow$\\
2719\end{tabular}
2720\begin{tabular}{|l|l|c|c|}
2721\hline
2722{\tt FROM}&{\tt TO}&{\tt DISTANCE}&{\tt COST}\\
2723\hline
2724{\tt Seattle}  &{\tt New-York}&{\tt 2.5}&{\tt 0.12}\\
2725{\tt Seattle}  &{\tt Chicago} &{\tt 1.7}&{\tt 0.08}\\
2726{\tt Seattle}  &{\tt Topeka}  &{\tt 1.8}&{\tt 0.09}\\
2727{\tt San-Diego}&{\tt New-York}&{\tt 2.5}&{\tt 0.15}\\
2728{\tt San-Diego}&{\tt Chicago} &{\tt 1.8}&{\tt 0.10}\\
2729{\tt San-Diego}&{\tt Topeka}  &{\tt 1.4}&{\tt 0.07}\\
2730\hline
2731\end{tabular}
2732
2733\subsubsection{Reading data from input table}
2734
2735The input table statement causes reading data from the specified table
2736record by record.
2737
2738Once a next record has been read, numeric or symbolic values of fields,
2739whose names are enclosed in square brackets in the table statement, are
2740gathered into $n$-tuple, and if the control set is specified in the
2741table statement, this $n$-tuple is added to it. Besides, a numeric or
2742symbolic value of each field associated with a model parameter is
2743assigned to the parameter member identified by subscripts, which are
2744components of the $n$-tuple just read.
2745
2746For example, the following input table statement:
2747
2748\medskip
2749
2750\noindent\hfil
2751\verb|table data IN "...": S <- [FROM,TO], d~DISTANCE, c~COST;|
2752
2753\medskip
2754
2755\noindent
2756causes reading values of four fields named {\tt FROM}, {\tt TO},
2757{\tt DISTANCE}, and {\tt COST} from each record of the specified table.
2758Values of fields {\tt FROM} and {\tt TO} give a pair $(f,t)$, which is
2759added to the control set {\tt S}. The value of field {\tt DISTANCE} is
2760assigned to parameter member ${\tt d}[f,t]$, and the value of field
2761{\tt COST} is assigned to parameter member ${\tt c}[f,t]$.
2762
2763Note that the input table may contain extra fields whose names are not
2764specified in the table statement, in which case values of these fields
2765on reading the table are ignored.
2766
2767\subsubsection{Writing data to output table}
2768
2769The output table statement causes writing data to the specified table.
2770Note that some drivers (namely, CSV and xBASE) destroy the output table
2771before writing data, i.e. delete all its existing records.
2772
2773Each $n$-tuple in the specified domain set generates one record written
2774to the output table. Values of fields are numeric or symbolic values of
2775corresponding expressions specified in the table statement. These
2776expressions are evaluated for each $n$-tuple in the domain set and,
2777thus, may include dummy indices introduced in the corresponding indexing
2778expression.
2779
2780For example, the following output table statement:
2781
2782\medskip
2783
2784\noindent
2785\verb|   table result{(f,t) in S} OUT "...": f~FROM, t~TO, x[f,t]~FLOW;|
2786
2787\medskip
2788
2789\noindent
2790causes writing records, by one record for each pair $(f,t)$ in set
2791{\tt S}, to the output table, where each record consists of three
2792fields named {\tt FROM}, {\tt TO}, and {\tt FLOW}. The values written
2793to fields {\tt FROM} and {\tt TO} are current values of dummy indices
2794{\tt f} and {\tt t}, and the value written to field {\tt FLOW} is
2795a value of member ${\tt x}[f,t]$ of corresponding subscripted parameter
2796or variable.
2797
2798%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2799
2800\newpage
2801
2802\section{Model data}
2803
2804{\it Model data} include elemental sets, which are ``values'' of model
2805sets, and numeric and symbolic values of model parameters.
2806
2807In MathProg there are two different ways to saturate model sets and
2808parameters with data. One way is simply providing necessary data using
2809the assign attribute. However, in many cases it is more practical to
2810separate the model itself and particular data needed for the model. For
2811the latter reason in MathProg there is another way, when the model
2812description is divided into two parts: model section and data section.
2813
2814A {\it model section} is a main part of the model description that
2815contains declarations of all model objects and is common for all
2816problems based on that model.
2817
2818A {\it data section} is an optional part of the model description that
2819contains model data specific for a particular problem.
2820
2821In MathProg model and data sections can be placed either in one text
2822file or in two separate text files.
2823
28241. If both model and data sections are placed in one file, the file is
2825composed as follows:
2826
2827\bigskip
2828
2829\noindent\hfil
2830\framebox{\begin{tabular}{l}
2831{\it statement}{\tt;}\\
2832{\it statement}{\tt;}\\
2833\hfil.\ \ .\ \ .\\
2834{\it statement}{\tt;}\\
2835{\tt data;}\\
2836{\it data block}{\tt;}\\
2837{\it data block}{\tt;}\\
2838\hfil.\ \ .\ \ .\\
2839{\it data block}{\tt;}\\
2840{\tt end;}
2841\end{tabular}}
2842
2843\bigskip
2844
28452. If the model and data sections are placed in two separate files, the
2846files are composed as follows:
2847
2848\bigskip
2849
2850\noindent\hfil
2851\begin{tabular}{@{}c@{}}
2852\framebox{\begin{tabular}{l}
2853{\it statement}{\tt;}\\
2854{\it statement}{\tt;}\\
2855\hfil.\ \ .\ \ .\\
2856{\it statement}{\tt;}\\
2857{\tt end;}\\
2858\end{tabular}}\\
2859\\\\Model file\\
2860\end{tabular}
2861\hspace{32pt}
2862\begin{tabular}{@{}c@{}}
2863\framebox{\begin{tabular}{l}
2864{\tt data;}\\
2865{\it data block}{\tt;}\\
2866{\it data block}{\tt;}\\
2867\hfil.\ \ .\ \ .\\
2868{\it data block}{\tt;}\\
2869{\tt end;}\\
2870\end{tabular}}\\
2871\\Data file\\
2872\end{tabular}
2873
2874\bigskip
2875
2876\begin{description}
2877\item[{\rm Note:}\hspace*{31pt}] If the data section is placed in a
2878separate file, the keyword {\tt data} is optional and may be omitted
2879along with the semicolon that follows it.
2880\end{description}
2881
2882\subsection{Coding data section}
2883
2884The {\it data section} is a sequence of data blocks in various formats,
2885which are discussed in following subsections. The order, in which data
2886blocks follow in the data section, may be arbitrary, not necessarily
2887the same, in which corresponding model objects follow in the model
2888section.
2889
2890The rules of coding the data section are commonly the same as the rules
2891of coding the model description (see Subsection \ref{coding}, page
2892\pageref{coding}), i.e. data blocks are composed from basic lexical
2893units such as symbolic names, numeric and string literals, keywords,
2894delimiters, and comments. However, for the sake of convenience and
2895improving readability there is one deviation from the common rule: if
2896a string literal consists of only alphanumeric characters (including
2897the underscore character), the signs {\tt+} and {\tt-}, and/or the
2898decimal point, it may be coded without bordering by (single or double)
2899quotes.
2900
2901All numeric and symbolic material provided in the data section is coded
2902in the form of numbers and symbols, i.e. unlike the model section
2903no expressions are allowed in the data section. Nevertheless, the signs
2904{\tt+} and {\tt-} can precede numeric literals to allow coding signed
2905numeric quantities, in which case there must be no white-space
2906characters between the sign and following numeric literal (if there is
2907at least one white-space, the sign and following numeric literal are
2908recognized as two different lexical units).
2909
2910\subsection{Set data block}
2911
2912\medskip
2913
2914\framebox[345pt][l]{
2915\parbox[c][44pt]{345pt}{
2916\hspace{6pt} {\tt set} {\it name} {\tt,} {\it record} {\tt,} \dots
2917{\tt,} {\it record} {\tt;}
2918
2919\medskip
2920
2921\hspace{6pt} {\tt set} {\it name} {\tt[} {\it symbol} {\tt,} \dots
2922{\tt,} {\it symbol} {\tt]} {\tt,} {\it record} {\tt,} \dots {\tt,}
2923{\it record} {\tt;}
2924}}
2925
2926\setlength{\leftmargini}{60pt}
2927
2928\begin{description}
2929\item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2930set;
2931\item[\hspace*{54pt}] {\it symbol}, \dots, {\it symbol} are subscripts,
2932which specify a particular member of the set (if the set is an array,
2933i.e. a set of sets);
2934\item[\hspace*{54pt}] {\it record}, \dots, {\it record} are data
2935records.
2936\end{description}
2937
2938\begin{description}
2939\item[{\rm Note:}\hspace*{31pt}] Commae preceding data records may be
2940omitted.
2941\end{description}
2942
2943\noindent Data records:
2944
2945\begin{description}
2946\item[{\tt :=}\hspace*{45pt}] is a non-significant data record, which
2947may be used freely to improve readability;
2948\item[{\tt(} {\it slice} {\tt)}\hspace*{18.5pt}] specifies a slice;
2949\item[{\it simple-data}\hspace*{5.5pt}] specifies set data in the
2950simple format;
2951\item[{\tt:} {\it matrix-data}]\hspace*{0pt}\\
2952specifies set data in the matrix format;
2953\item[{\tt(tr)} {\tt:} {\it matrix-data}]\hspace*{0pt}\\
2954specifies set data in the transposed matrix format. (In this case the
2955colon following the keyword {\tt(tr)} may be omitted.)
2956\end{description}
2957
2958\noindent{\bf Examples}
2959
2960\begin{verbatim}
2961set month := Jan Feb Mar Apr May Jun;
2962set month "Jan", "Feb", "Mar", "Apr", "May", "Jun";
2963set A[3,Mar] := (1,2) (2,3) (4,2) (3,1) (2,2) (4,4) (3,4);
2964set A[3,'Mar'] := 1 2 2 3 4 2 3 1 2 2 4 4 2 4;
2965set A[3,'Mar'] : 1 2 3 4 :=
2966               1 - + - -
2967               2 - + + -
2968               3 + - - +
2969               4 - + - + ;
2970set B := (1,2,3) (1,3,2) (2,3,1) (2,1,3) (1,2,2) (1,1,1) (2,1,1);
2971set B := (*,*,*) 1 2 3, 1 3 2, 2 3 1, 2 1 3, 1 2 2, 1 1 1, 2 1 1;
2972set B := (1,*,2) 3 2 (2,*,1) 3 1 (1,2,3) (2,1,3) (1,1,1);
2973set B := (1,*,*) : 1 2 3 :=
2974                 1 + - -
2975                 2 - + +
2976                 3 - + -
2977         (2,*,*) : 1 2 3 :=
2978                 1 + - +
2979                 2 - - -
2980                 3 + - - ;
2981\end{verbatim}
2982
2983\noindent(In these examples {\tt month} is a simple set of singlets,
2984{\tt A} is a 2-dimensional array of doublets, and {\tt B} is a simple
2985set of triplets. Data blocks for the same set are equivalent in the
2986sense that they specify the same data in different formats.)
2987
2988\medskip
2989
2990The {\it set data block} is used to specify a complete elemental set,
2991which is assigned to a set (if it is a simple set) or one of its
2992members (if the set is an array of sets).\footnote{There is another way
2993to specify data for a simple set along with data for parameters. This
2994feature is discussed in the next subsection.}
2995
2996Data blocks can be specified only for non-computable sets, i.e. for
2997sets, which have no assign ({\tt:=}) attribute in the corresponding set
2998statements.
2999
3000If the set is a simple set, only its symbolic name should be specified
3001in the header of the data block. Otherwise, if the set is a
3002$n$-dimensional array, its symbolic name should be provided with a
3003complete list of subscripts separated by commae and enclosed in square
3004brackets to specify a particular member of the set array. The number of
3005subscripts must be the same as the dimension of the set array, where
3006each subscript must be a number or symbol.
3007
3008An elemental set defined in the set data block is coded as a sequence
3009of data records described below.\footnote{{\it Data record} is simply a
3010technical term. It does not mean that data records have any special
3011formatting.}
3012
3013\newpage
3014
3015\subsubsection{Assign data record}
3016
3017The {\it assign} ({\tt:=}) {\it data record} is a non-signficant
3018element. It may be used for improving readability of data blocks.
3019
3020\subsubsection{Slice data record}
3021
3022The {\it slice data record} is a control record, which specifies a
3023{\it slice} of the elemental set defined in the data block. It has the
3024following syntactic form:
3025
3026\medskip
3027
3028\noindent\hfil
3029{\tt(} $s_1$ {\tt,} $s_2$ {\tt,} \dots {\tt,} $s_n$ {\tt)}
3030
3031\medskip
3032
3033\noindent where $s_1$, $s_2$, \dots, $s_n$ are components of the slice.
3034
3035Each component of the slice can be a number or symbol or the asterisk
3036({\tt*}). The number of components in the slice must be the same as the
3037dimension of $n$-tuples in the elemental set to be defined. For
3038instance, if the elemental set contains 4-tuples (quadruplets), the
3039slice must have four components. The number of asterisks in the slice
3040is called the {\it slice dimension}.
3041
3042The effect of using slices is the following. If a $m$-dimensional slice
3043(i.e. a slice having $m$ asterisks) is specified in the data block, all
3044subsequent data records must specify tuples of the dimension $m$.
3045Whenever a $m$-tuple is encountered, each asterisk in the slice is
3046replaced by corresponding components of the $m$-tuple that gives the
3047resultant $n$-tuple, which is included in the elemental set to be
3048defined. For example, if the slice $(a,*,1,2,*)$ is in effect, and
30492-tuple $(3,b)$ is encountered in a subsequent data record, the
3050resultant 5-tuple included in the elemental set is $(a,3,1,2,b)$.
3051
3052The slice having no asterisks itself defines a complete $n$-tuple,
3053which is included in the elemental set.
3054
3055Being once specified the slice effects until either a new slice or the
3056end of data block is encountered. Note that if no slice is specified in
3057the data block, one, components of which are all asterisks, is assumed.
3058
3059\subsubsection{Simple data record}
3060
3061The {\it simple data record} defines one $n$-tuple in a simple format
3062and has the following syntactic form:
3063
3064\medskip
3065
3066\noindent\hfil
3067$t_1$ {\tt,} $t_2$ {\tt,} \dots {\tt,} $t_n$
3068
3069\medskip
3070
3071\noindent where $t_1$, $t_2$, \dots, $t_n$ are components of the
3072$n$-tuple. Each component can be a number or symbol. Commae between
3073components are optional and may be omitted.
3074
3075\subsubsection{Matrix data record}
3076
3077The {\it matrix data record} defines several 2-tuples (doublets) in
3078a matrix format and has the following syntactic form:
3079
3080\newpage
3081
3082$$\begin{array}{cccccc}
3083\mbox{{\tt:}}&c_1&c_2&\dots&c_n&\mbox{{\tt:=}}\\
3084r_1&a_{11}&a_{12}&\dots&a_{1n}&\\
3085r_2&a_{21}&a_{22}&\dots&a_{2n}&\\
3086\multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}&\\
3087r_m&a_{m1}&a_{m2}&\dots&a_{mn}&\\
3088\end{array}$$
3089where $r_1$, $r_2$, \dots, $r_m$ are numbers and/or symbols
3090corresponding to rows of the matrix; $c_1$, $c_2$, \dots, $c_n$ are
3091numbers and/or symbols corresponding to columns of the matrix, $a_{11}$,
3092$a_{12}$, \dots, $a_{mn}$ are matrix elements, which can be either
3093{\tt+} or {\tt-}. (In this data record the delimiter {\tt:} preceding
3094the column list and the delimiter {\tt:=} following the column list
3095cannot be omitted.)
3096
3097Each element $a_{ij}$ of the matrix data block (where $1\leq i\leq m$,
3098$1\leq j\leq n$) corresponds to 2-tuple $(r_i,c_j)$. If $a_{ij}$ is the
3099plus sign ({\tt+}), that 2-tuple (or a longer $n$-tuple, if a slice is
3100used) is included in the elemental set. Otherwise, if $a_{ij}$ is the
3101minus sign ({\tt-}), that 2-tuple is not included in the elemental set.
3102
3103Since the matrix data record defines 2-tuples, either the elemental set
3104must consist of 2-tuples or the slice currently used must be
31052-dimensional.
3106
3107\subsubsection{Transposed matrix data record}
3108
3109The {\it transposed matrix data record} has the following syntactic
3110form:
3111$$\begin{array}{cccccc}
3112\mbox{{\tt(tr) :}}&c_1&c_2&\dots&c_n&\mbox{{\tt:=}}\\
3113r_1&a_{11}&a_{12}&\dots&a_{1n}&\\
3114r_2&a_{21}&a_{22}&\dots&a_{2n}&\\
3115\multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}&\\
3116r_m&a_{m1}&a_{m2}&\dots&a_{mn}&\\
3117\end{array}$$
3118(In this case the delimiter {\tt:} following the keyword {\tt(tr)} is
3119optional and may be omitted.)
3120
3121This data record is completely analogous to the matrix data record (see
3122above) with only exception that in this case each element $a_{ij}$ of
3123the matrix corresponds to 2-tuple $(c_j,r_i)$ rather than $(r_i,c_j)$.
3124
3125Being once specified the {\tt(tr)} indicator affects all subsequent
3126data records until either a slice or the end of data block is
3127encountered.
3128
3129\subsection{Parameter data block}
3130
3131\medskip
3132
3133\framebox[345pt][l]{
3134\parbox[c][80pt]{345pt}{
3135\hspace{6pt} {\tt param} {\it name} {\tt,} {\it record} {\tt,} \dots
3136{\tt,} {\it record} {\tt;}
3137
3138\medskip
3139
3140\hspace{6pt} {\tt param} {\it name} {\tt default} {\it value} {\tt,}
3141{\it record} {\tt,} \dots {\tt,} {\it record} {\tt;}
3142
3143\medskip
3144
3145\hspace{6pt} {\tt param} {\tt:} {\it tabbing-data} {\tt;}
3146
3147\medskip
3148
3149\hspace{6pt} {\tt param} {\tt default} {\it value} {\tt:}
3150{\it tabbing-data} {\tt;}
3151}}
3152
3153\newpage
3154
3155\setlength{\leftmargini}{60pt}
3156
3157\begin{description}
3158\item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
3159parameter;
3160\item[\hspace*{54pt}] {\it value} is an optional default value of the
3161parameter;
3162\item[\hspace*{54pt}] {\it record}, \dots, {\it record} are data
3163records;
3164\item[\hspace*{54pt}] {\it tabbing-data} specifies parameter data in
3165the tabbing format.
3166\end{description}
3167
3168\begin{description}
3169\item[{\rm Note:}\hspace*{31pt}] Commae preceding data records may be
3170omitted.
3171\end{description}
3172
3173\noindent Data records:
3174
3175\begin{description}
3176\item[{\tt :=}\hspace*{45pt}] is a non-significant data record, which
3177may be used freely to improve readability;
3178\item[{\tt[} {\it slice} {\tt]}\hspace*{18.5pt}] specifies a slice;
3179\item[{\it plain-data}\hspace*{11pt}] specifies parameter data in the
3180plain format;
3181\item[{\tt:} {\it tabular-data}]\hspace*{0pt}\\
3182specifies parameter data in the tabular format;
3183\item[{\tt(tr)} {\tt:} {\it tabular-data}]\hspace*{0pt}\\
3184specifies set data in the transposed tabular format. (In this case the
3185colon following the keyword {\tt(tr)} may be omitted.)
3186\end{description}
3187
3188\noindent{\bf Examples}
3189
3190\begin{verbatim}
3191param T := 4;
3192param month := 1 'Jan' 2 'Feb' 3 'Mar' 4 'Apr' 5 'May';
3193param month := [1] Jan, [2] Feb, [3] Mar, [4] Apr, [5] May;
3194param day := [Sun] 0, [Mon] 1, [Tue] 2, [Wed] 3, [Thu] 4,
3195             [Fri] 5, [Sat] 6;
3196param init_stock := iron 7.32 nickel 35.8;
3197param init_stock [*] iron 7.32, nickel 35.8;
3198param cost [iron] .025 [nickel] .03;
3199param value := iron -.1, nickel .02;
3200param       : init_stock cost value :=
3201      iron       7.32    .025  -.1
3202      nickel    35.8     .03    .02 ;
3203param : raw : init_stock cost value :=
3204      iron       7.32    .025  -.1
3205      nickel    35.8     .03    .02 ;
3206param demand default 0 (tr)
3207       :  FRA  DET  LAN  WIN  STL  FRE  LAF :=
3208   bands  300   .   100   75   .   225  250
3209   coils  500  750  400  250   .   850  500
3210   plate  100   .    .    50  200   .   250 ;
3211\end{verbatim}
3212
3213\newpage
3214
3215\begin{verbatim}
3216param trans_cost :=
3217   [*,*,bands]:  FRA  DET  LAN  WIN  STL  FRE  LAF :=
3218         GARY     30   10    8   10   11   71    6
3219         CLEV     22    7   10    7   21   82   13
3220         PITT     19   11   12   10   25   83   15
3221   [*,*,coils]:  FRA  DET  LAN  WIN  STL  FRE  LAF :=
3222         GARY     39   14   11   14   16   82    8
3223         CLEV     27    9   12    9   26   95   17
3224         PITT     24   14   17   13   28   99   20
3225   [*,*,plate]:  FRA  DET  LAN  WIN  STL  FRE  LAF :=
3226         GARY     41   15   12   16   17   86    8
3227         CLEV     29    9   13    9   28   99   18
3228         PITT     26   14   17   13   31  104   20 ;
3229\end{verbatim}
3230
3231The {\it parameter data block} is used to specify complete data for a
3232parameter (or parameters, if data are specified in the tabbing format).
3233
3234Data blocks can be specified only for non-computable parameters, i.e.
3235for parameters, which have no assign ({\tt:=}) attribute in the
3236corresponding parameter statements.
3237
3238Data defined in the parameter data block are coded as a sequence of
3239data records described below. Additionally the data block can be
3240provided with the optional {\tt default} attribute, which specifies a
3241default numeric or symbolic value of the parameter (parameters). This
3242default value is assigned to the parameter or its members, if
3243no appropriate value is defined in the parameter data block. The
3244{\tt default} attribute cannot be used, if it is already specified in
3245the corresponding parameter statement.
3246
3247\subsubsection{Assign data record}
3248
3249The {\it assign} ({\tt:=}) {\it data record} is a non-signficant
3250element. It may be used for improving readability of data blocks.
3251
3252\subsubsection{Slice data record}
3253
3254The {\it slice data record} is a control record, which specifies a
3255{\it slice} of the parameter array. It has the following syntactic form:
3256
3257\medskip
3258
3259\noindent\hfil
3260{\tt[} $s_1$ {\tt,} $s_2$ {\tt,} \dots {\tt,} $s_n$ {\tt]}
3261
3262\medskip
3263
3264\noindent where $s_1$, $s_2$, \dots, $s_n$ are components of the slice.
3265
3266Each component of the slice can be a number or symbol or the asterisk
3267({\tt*}). The number of components in the slice must be the same as the
3268dimension of the parameter. For instance, if the parameter is a
32694-dimensional array, the slice must have four components. The number of
3270asterisks in the slice is called the {\it slice dimension}.
3271
3272The effect of using slices is the following. If a $m$-dimensional slice
3273(i.e. a slice having $m$ asterisks) is specified in the data block, all
3274subsequent data records must specify subscripts of the parameter
3275members as if the parameter were $m$-dimensional, not $n$-dimensional.
3276
3277Whenever $m$ subscripts are encountered, each asterisk in the slice is
3278replaced by corresponding subscript that gives $n$ subscripts, which
3279define the actual parameter member. For example, if the slice
3280$[a,*,1,2,*]$ is in effect, and subscripts 3 and $b$ are encountered in
3281a subsequent data record, the complete subscript list used to choose a
3282parameter member is $[a,3,1,2,b]$.
3283
3284It is allowed to specify a slice having no asterisks. Such slice itself
3285defines a complete subscript list, in which case the next data record
3286should define only a single value of corresponding parameter member.
3287
3288Being once specified the slice effects until either a new slice or the
3289end of data block is encountered. Note that if no slice is specified in
3290the data block, one, components of which are all asterisks, is assumed.
3291
3292\subsubsection{Plain data record}
3293
3294The {\it plain data record} defines a subscript list and a single value
3295in the plain format. This record has the following syntactic form:
3296
3297\medskip
3298
3299\noindent\hfil
3300$t_1$ {\tt,} $t_2$ {\tt,} \dots {\tt,} $t_n$ {\tt,} $v$
3301
3302\medskip
3303
3304\noindent where $t_1$, $t_2$, \dots, $t_n$ are subscripts, and $v$ is a
3305value. Each subscript as well as the value can be a number or symbol.
3306Commae following subscripts are optional and may be omitted.
3307
3308In case of 0-dimensional parameter or slice the plain data record has
3309no subscripts and consists of a single value only.
3310
3311\subsubsection{Tabular data record}
3312
3313The {\it tabular data record} defines several values, where each value
3314is provided with two subscripts. This record has the following
3315syntactic form:
3316$$\begin{array}{cccccc}
3317\mbox{{\tt:}}&c_1&c_2&\dots&c_n&\mbox{{\tt:=}}\\
3318r_1&a_{11}&a_{12}&\dots&a_{1n}&\\
3319r_2&a_{21}&a_{22}&\dots&a_{2n}&\\
3320\multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}&\\
3321r_m&a_{m1}&a_{m2}&\dots&a_{mn}&\\
3322\end{array}$$
3323where $r_1$, $r_2$, \dots, $r_m$ are numbers and/or symbols
3324corresponding to rows of the table; $c_1$, $c_2$, \dots, $c_n$ are
3325numbers and/or symbols corresponding to columns of the table, $a_{11}$,
3326$a_{12}$, \dots, $a_{mn}$ are table elements. Each element can be a
3327number or symbol or the single decimal point ({\tt.}). (In this data
3328record the delimiter {\tt:} preceding the column list and the delimiter
3329{\tt:=} following the column list cannot be omitted.)
3330
3331Each element $a_{ij}$ of the tabular data block ($1\leq i\leq m$,
3332$1\leq j\leq n$) defines two subscripts, where the first subscript is
3333$r_i$, and the second one is $c_j$. These subscripts are used in
3334conjunction with the current slice to form the complete subscript list
3335that identifies a particular member of the parameter array. If $a_{ij}$
3336is a number or symbol, this value is assigned to the parameter member.
3337However, if $a_{ij}$ is the single decimal point, the member is
3338assigned a default value specified either in the parameter data block
3339or in the parameter statement, or, if no default value is specified,
3340the member remains undefined.
3341
3342Since the tabular data record provides two subscripts for each value,
3343either the parameter or the slice currently used must be 2-dimensional.
3344
3345\subsubsection{Transposed tabular data record}
3346
3347The {\it transposed tabular data record} has the following syntactic
3348form:
3349$$\begin{array}{cccccc}
3350\mbox{{\tt(tr) :}}&c_1&c_2&\dots&c_n&\mbox{{\tt:=}}\\
3351r_1&a_{11}&a_{12}&\dots&a_{1n}&\\
3352r_2&a_{21}&a_{22}&\dots&a_{2n}&\\
3353\multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}&\\
3354r_m&a_{m1}&a_{m2}&\dots&a_{mn}&\\
3355\end{array}$$
3356(In this case the delimiter {\tt:} following the keyword {\tt(tr)} is
3357optional and may be omitted.)
3358
3359This data record is completely analogous to the tabular data record
3360(see above) with only exception that the first subscript defined by
3361element $a_{ij}$ is $c_j$ while the second one is $r_i$.
3362
3363Being once specified the {\tt(tr)} indicator affects all subsequent
3364data records until either a slice or the end of data block is
3365encountered.
3366
3367\subsubsection{Tabbing data format}
3368
3369The parameter data block in the {\it tabbing format} has the following
3370syntactic form:
3371$$\begin{array}{p{12pt}@{\ }l@{\ }c@{\ }l@{\ }c@{\ }l@{\ }r@{\ }l@{\ }c
3372@{\ }l@{\ }c@{\ }l@{\ }l}
3373\multicolumn{7}{@{}c@{}}{\mbox{\tt param}\ \mbox{\tt default}\ \mbox
3374{\it value}\ \mbox{\tt:}\ \mbox{\it s}\ \mbox{\tt:}}&
3375p_1&\mbox{\tt,}&p_2&\mbox{\tt,} \dots \mbox{\tt,}&p_k&\mbox{\tt:=}\\
3376&t_{11}&\mbox{\tt,}&t_{12}&\mbox{\tt,} \dots \mbox{\tt,}&t_{1n}&
3377\mbox{\tt,}&a_{11}&\mbox{\tt,}&a_{12}&\mbox{\tt,} \dots \mbox{\tt,}&
3378a_{1k}\\
3379&t_{21}&\mbox{\tt,}&t_{22}&\mbox{\tt,} \dots \mbox{\tt,}&t_{2n}&
3380\mbox{\tt,}&a_{21}&\mbox{\tt,}&a_{22}&\mbox{\tt,} \dots \mbox{\tt,}&
3381a_{2k}\\
3382\multicolumn{13}{c}
3383{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}\\
3384&t_{m1}&\mbox{\tt,}&t_{m2}&\mbox{\tt,} \dots \mbox{\tt,}&t_{mn}&
3385\mbox{\tt,}&a_{m1}&\mbox{\tt,}&a_{m2}&\mbox{\tt,} \dots \mbox{\tt,}&
3386a_{mk}&\mbox{\tt;}\\
3387\end{array}$$
3388
3389{\it Notes:}
3390
33911. The keyword {\tt default} may be omitted along with a value
3392following it.
3393
33942. Symbolic name {\tt s} may be omitted along with the colon following
3395it.
3396
33973. All comae are optional and may be omitted.
3398
3399\medskip
3400
3401The data block in the tabbing format shown above is exactly equivalent
3402to the following data blocks for $j=1,2,\dots,k$:
3403
3404\medskip
3405
3406{\tt set} {\it s} {\tt:=}
3407{\tt(}$t_{11}${\tt,}$t_{12}${\tt,}\dots{\tt,}$t_{1n}${\tt)}
3408{\tt(}$t_{21}${\tt,}$t_{22}${\tt,}\dots{\tt,}$t_{2n}${\tt)} \dots
3409{\tt(}$t_{m1}${\tt,}$t_{m2}${\tt,}\dots{\tt,}$t_{mn}${\tt)} {\tt;}
3410
3411{\tt param} $p_j$ {\tt default} {\it value} {\tt:=}
3412
3413$\!${\tt[}$t_{11}${\tt,}$t_{12}${\tt,}\dots{\tt,}$t_{1n}${\tt]}
3414$a_{1j}$
3415{\tt[}$t_{21}${\tt,}$t_{22}${\tt,}\dots{\tt,}$t_{2n}${\tt]} $a_{2j}$
3416\dots
3417{\tt[}$t_{m1}${\tt,}$t_{m2}${\tt,}\dots{\tt,}$t_{mn}${\tt]} $a_{mj}$
3418{\tt;}
3419
3420%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3421
3422\appendix
3423
3424\newpage
3425
3426\section{Using suffixes}
3427
3428Suffixes can be used to retrieve additional values associated with
3429model variables, constraints, and objectives.
3430
3431A {\it suffix} consists of a period ({\tt.}) followed by a non-reserved
3432keyword. For example, if {\tt x} is a two-dimensional variable,
3433{\tt x[i,j].lb} is a numeric value equal to the lower bound of
3434elemental variable {\tt x[i,j]}, which (value) can be used everywhere
3435in expressions like a numeric parameter.
3436
3437For model variables suffixes have the following meaning:
3438
3439\medskip
3440
3441\begin{tabular}{@{}p{96pt}p{222pt}@{}}
3442{\tt.lb}&lower bound\\
3443{\tt.ub}&upper bound\\
3444{\tt.status}&status in the solution:\\
3445&0 --- undefined\\
3446&1 --- basic\\
3447&2 --- non-basic on lower bound\\
3448&3 --- non-basic on upper bound\\
3449&4 --- non-basic free (unbounded) variable\\
3450&5 --- non-basic fixed variable\\
3451{\tt.val}&primal value in the solution\\
3452{\tt.dual}&dual value (reduced cost) in the solution\\
3453\end{tabular}
3454
3455\medskip
3456
3457For model constraints and objectives suffixes have the following
3458meaning:
3459
3460\medskip
3461
3462\begin{tabular}{@{}p{96pt}p{222pt}@{}}
3463{\tt.lb}&lower bound of the linear form\\
3464{\tt.ub}&upper bound of the linear form\\
3465{\tt.status}&status in the solution:\\
3466&0 --- undefined\\
3467&1 --- non-active\\
3468&2 --- active on lower bound\\
3469&3 --- active on upper bound\\
3470&4 --- active free (unbounded) row\\
3471&5 --- active equality constraint\\
3472{\tt.val}&primal value of the linear form in the solution\\
3473{\tt.dual}&dual value (reduced cost) of the linear form in the
3474solution\\
3475\end{tabular}
3476
3477\medskip
3478
3479Note that suffixes {\tt.status}, {\tt.val}, and {\tt.dual} can be used
3480only below the solve statement.
3481
3482%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3483
3484\newpage
3485
3486\section{Date and time functions}
3487
3488\noindent\hfil
3489by Andrew Makhorin \verb|<mao@gnu.org>|
3490
3491\noindent\hfil
3492and Heinrich Schuchardt \verb|<heinrich.schuchardt@gmx.de>|
3493
3494\subsection{Obtaining current calendar time}
3495\label{gmtime}
3496
3497To obtain the current calendar time in MathProg there exists the
3498function {\tt gmtime}. It has no arguments and returns the number of
3499seconds elapsed since 00:00:00 on January 1, 1970, Coordinated
3500Universal Time (UTC). For example:
3501
3502\medskip
3503
3504\verb|   param utc := gmtime();|
3505
3506\medskip
3507
3508MathProg has no function to convert UTC time returned by the function
3509{\tt gmtime} to {\it local} calendar times. Thus, if you need to
3510determine the current local calendar time, you have to add to the UTC
3511time returned the time offset from UTC expressed in seconds. For
3512example, the time in Berlin during the winter is one hour ahead of UTC
3513that corresponds to the time offset +1 hour = +3600 secs, so the
3514current winter calendar time in Berlin may be determined as follows:
3515
3516\medskip
3517
3518\verb|   param now := gmtime() + 3600;|
3519
3520\medskip
3521
3522\noindent Similarly, the summer time in Chicago (Central Daylight Time)
3523is five hours behind UTC, so the corresponding current local calendar
3524time may be determined as follows:
3525
3526\medskip
3527
3528\verb|   param now := gmtime() - 5 * 3600;|
3529
3530\medskip
3531
3532Note that the value returned by {\tt gmtime} is volatile, i.e. being
3533called several times this function may return different values.
3534
3535\subsection{Converting character string to calendar time}
3536\label{str2time}
3537
3538The function {\tt str2time(}{\it s}{\tt,} {\it f}{\tt)} converts a
3539character string (timestamp) specified by its first argument {\it s},
3540which must be a symbolic expression, to the calendar time suitable for
3541arithmetic calculations. The conversion is controlled by the specified
3542format string {\it f} (the second argument), which also must be a
3543symbolic expression.
3544
3545The result of conversion returned by {\tt str2time} has the same
3546meaning as values returned by the function {\tt gmtime} (see Subsection
3547\ref{gmtime}, page \pageref{gmtime}). Note that {\tt str2time} does
3548{\tt not} correct the calendar time returned for the local timezone,
3549i.e. being applied to 00:00:00 on January 1, 1970 it always returns 0.
3550
3551For example, the model statements:
3552
3553\medskip
3554
3555\verb|   param s, symbolic, := "07/14/98 13:47";|
3556
3557\verb|   param t := str2time(s, "%m/%d/%y %H:%M");|
3558
3559\verb|   display t;|
3560
3561\medskip
3562
3563\noindent produce the following printout:
3564
3565\medskip
3566
3567\verb|   t = 900424020|
3568
3569\medskip
3570
3571\noindent where the calendar time printed corresponds to 13:47:00 on
3572July 14, 1998.
3573
3574\newpage
3575
3576The format string passed to the function {\tt str2time} consists of
3577conversion specifiers and ordinary characters. Each conversion
3578specifier begins with a percent ({\tt\%}) character followed by a
3579letter.
3580
3581The following conversion specifiers may be used in the format string:
3582
3583\medskip
3584
3585\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3586{\tt\%b}&The abbreviated month name (case insensitive). At least three
3587first letters of the month name must appear in the input string.\\
3588\end{tabular}
3589
3590\medskip
3591
3592\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3593{\tt\%d}&The day of the month as a decimal number (range 1 to 31).
3594Leading zero is permitted, but not required.\\
3595\end{tabular}
3596
3597\medskip
3598
3599\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3600{\tt\%h}&The same as {\tt\%b}.\\
3601\end{tabular}
3602
3603\medskip
3604
3605\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3606{\tt\%H}&The hour as a decimal number, using a 24-hour clock (range 0
3607to 23). Leading zero is permitted, but not required.\\
3608\end{tabular}
3609
3610\medskip
3611
3612\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3613{\tt\%m}&The month as a decimal number (range 1 to 12). Leading zero is
3614permitted, but not required.\\
3615\end{tabular}
3616
3617\medskip
3618
3619\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3620{\tt\%M}&The minute as a decimal number (range 0 to 59). Leading zero
3621is permitted, but not required.\\
3622\end{tabular}
3623
3624\medskip
3625
3626\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3627{\tt\%S}&The second as a decimal number (range 0 to 60). Leading zero
3628is permitted, but not required.\\
3629\end{tabular}
3630
3631\medskip
3632
3633\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3634{\tt\%y}&The year without a century as a decimal number (range 0 to 99).
3635Leading zero is permitted, but not required. Input values in the range
36360 to 68 are considered as the years 2000 to 2068 while the values 69 to
363799 as the years 1969 to 1999.\\
3638\end{tabular}
3639
3640\medskip
3641
3642\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3643{\tt\%z}&The offset from GMT in ISO 8601 format.\\
3644\end{tabular}
3645
3646\medskip
3647
3648\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3649{\tt\%\%}&A literal {\tt\%} character.\\
3650\end{tabular}
3651
3652\medskip
3653
3654All other (ordinary) characters in the format string must have a
3655matching character in the input string to be converted. Exceptions are
3656spaces in the input string which can match zero or more space
3657characters in the format string.
3658
3659If some date and/or time component(s) are missing in the format and,
3660therefore, in the input string, the function {\tt str2time} uses their
3661default values corresponding to 00:00:00 on January 1, 1970, that is,
3662the default value of the year is 1970, the default value of the month
3663is January, etc.
3664
3665The function {\tt str2time} is applicable to all calendar times in the
3666range 00:00:00 on January 1, 0001 to 23:59:59 on December 31, 4000 of
3667the Gregorian calendar.
3668
3669\subsection{Converting calendar time to character string}
3670\label{time2str}
3671
3672The function {\tt time2str(}{\it t}{\tt,} {\it f}{\tt)} converts the
3673calendar time specified by its first argument {\it t}, which must be a
3674numeric expression, to a character string (symbolic value). The
3675conversion is controlled by the specified format string {\it f} (the
3676second argument), which must be a symbolic expression.
3677
3678The calendar time passed to {\tt time2str} has the same meaning as
3679values returned by the function {\tt gmtime} (see Subsection
3680\ref{gmtime}, page \pageref{gmtime}). Note that {\tt time2str} does
3681{\it not} correct the specified calendar time for the local timezone,
3682i.e. the calendar time 0 always corresponds to 00:00:00 on January 1,
36831970.
3684
3685For example, the model statements:
3686
3687\medskip
3688
3689\verb|   param s, symbolic, := time2str(gmtime(), "%FT%TZ");|
3690
3691\verb|   display s;|
3692
3693\medskip
3694
3695\noindent may produce the following printout:
3696
3697\medskip
3698
3699\verb|   s = '2008-12-04T00:23:45Z'|
3700
3701\medskip
3702
3703\noindent which is a timestamp in the ISO format.
3704
3705The format string passed to the function {\tt time2str} consists of
3706conversion specifiers and ordinary characters. Each conversion
3707specifier begins with a percent ({\tt\%}) character followed by a
3708letter.
3709
3710The following conversion specifiers may be used in the format string:
3711
3712\medskip
3713
3714\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3715{\tt\%a}&The abbreviated (2-character) weekday name.\\
3716\end{tabular}
3717
3718\medskip
3719
3720\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3721{\tt\%A}&The full weekday name.\\
3722\end{tabular}
3723
3724\medskip
3725
3726\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3727{\tt\%b}&The abbreviated (3-character) month name.\\
3728\end{tabular}
3729
3730\medskip
3731
3732\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3733{\tt\%B}&The full month name.\\
3734\end{tabular}
3735
3736\medskip
3737
3738\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3739{\tt\%C}&The century of the year, that is the greatest integer not
3740greater than the year divided by 100.\\
3741\end{tabular}
3742
3743\medskip
3744
3745\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3746{\tt\%d}&The day of the month as a decimal number (range 01 to 31).\\
3747\end{tabular}
3748
3749\medskip
3750
3751\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3752{\tt\%D}&The date using the format \verb|%m/%d/%y|.\\
3753\end{tabular}
3754
3755\medskip
3756
3757\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3758{\tt\%e}&The day of the month like with \verb|%d|, but padded with
3759blank rather than zero.\\
3760\end{tabular}
3761
3762\medskip
3763
3764\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3765{\tt\%F}&The date using the format \verb|%Y-%m-%d|.\\
3766\end{tabular}
3767
3768\medskip
3769
3770\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3771{\tt\%g}&The year corresponding to the ISO week number, but without the
3772century (range 00 to 99). This has the same format and value as
3773\verb|%y|, except that if the ISO week number (see \verb|%V|) belongs
3774to the previous or next year, that year is used instead.\\
3775\end{tabular}
3776
3777\medskip
3778
3779\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3780{\tt\%G}&The year corresponding to the ISO week number. This has the
3781same format and value as \verb|%Y|, except that if the ISO week number
3782(see \verb|%V|) belongs to the previous or next year, that year is used
3783instead.
3784\end{tabular}
3785
3786\medskip
3787
3788\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3789{\tt\%h}&The same as \verb|%b|.\\
3790\end{tabular}
3791
3792\medskip
3793
3794\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3795{\tt\%H}&The hour as a decimal number, using a 24-hour clock (range 00
3796to 23).\\
3797\end{tabular}
3798
3799\medskip
3800
3801\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3802{\tt\%I}&The hour as a decimal number, using a 12-hour clock (range 01
3803to 12).\\
3804\end{tabular}
3805
3806\medskip
3807
3808\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3809{\tt\%j}&The day of the year as a decimal number (range 001 to 366).\\
3810\end{tabular}
3811
3812\medskip
3813
3814\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3815{\tt\%k}&The hour as a decimal number, using a 24-hour clock like
3816\verb|%H|, but padded with blank rather than zero.\\
3817\end{tabular}
3818
3819\medskip
3820
3821\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3822{\tt\%l}&The hour as a decimal number, using a 12-hour clock like
3823\verb|%I|, but padded with blank rather than zero.
3824\end{tabular}
3825
3826\medskip
3827
3828\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3829{\tt\%m}&The month as a decimal number (range 01 to 12).\\
3830\end{tabular}
3831
3832\medskip
3833
3834\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3835{\tt\%M}&The minute as a decimal number (range 00 to 59).\\
3836\end{tabular}
3837
3838\medskip
3839
3840\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3841{\tt\%p}&Either {\tt AM} or {\tt PM}, according to the given time value.
3842Midnight is treated as {\tt AM} and noon as {\tt PM}.\\
3843\end{tabular}
3844
3845\medskip
3846
3847\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3848{\tt\%P}&Either {\tt am} or {\tt pm}, according to the given time value.
3849Midnight is treated as {\tt am} and noon as {\tt pm}.\\
3850\end{tabular}
3851
3852\medskip
3853
3854\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3855{\tt\%R}&The hour and minute in decimal numbers using the format
3856\verb|%H:%M|.\\
3857\end{tabular}
3858
3859\medskip
3860
3861\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3862{\tt\%S}&The second as a decimal number (range 00 to 59).\\
3863\end{tabular}
3864
3865\medskip
3866
3867\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3868{\tt\%T}&The time of day in decimal numbers using the format
3869\verb|%H:%M:%S|.\\
3870\end{tabular}
3871
3872\medskip
3873
3874\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3875{\tt\%u}&The day of the week as a decimal number (range 1 to 7), Monday
3876being 1.\\
3877\end{tabular}
3878
3879\medskip
3880
3881\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3882{\tt\%U}&The week number of the current year as a decimal number (range
388300 to 53), starting with the first Sunday as the first day of the first
3884week. Days preceding the first Sunday in the year are considered to be
3885in week 00.
3886\end{tabular}
3887
3888\medskip
3889
3890\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3891{\tt\%V}&The ISO week number as a decimal number (range 01 to 53). ISO
3892weeks start with Monday and end with Sunday. Week 01 of a year is the
3893first week which has the majority of its days in that year; this is
3894equivalent to the week containing January 4. Week 01 of a year can
3895contain days from the previous year. The week before week 01 of a year
3896is the last week (52 or 53) of the previous year even if it contains
3897days from the new year. In other word, if 1 January is Monday, Tuesday,
3898Wednesday or Thursday, it is in week 01; if 1 January is Friday,
3899Saturday or Sunday, it is in week 52 or 53 of the previous year.\\
3900\end{tabular}
3901
3902\medskip
3903
3904\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3905{\tt\%w}&The day of the week as a decimal number (range 0 to 6), Sunday
3906being 0.\\
3907\end{tabular}
3908
3909\medskip
3910
3911\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3912{\tt\%W}&The week number of the current year as a decimal number (range
391300 to 53), starting with the first Monday as the first day of the first
3914week. Days preceding the first Monday in the year are considered to be
3915in week 00.\\
3916\end{tabular}
3917
3918\medskip
3919
3920\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3921{\tt\%y}&The year without a century as a decimal number (range 00 to
392299), that is the year modulo 100.\\
3923\end{tabular}
3924
3925\medskip
3926
3927\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3928{\tt\%Y}&The year as a decimal number, using the Gregorian calendar.\\
3929\end{tabular}
3930
3931\medskip
3932
3933\begin{tabular}{@{}p{20pt}p{298pt}@{}}
3934{\tt\%\%}&A literal \verb|%| character.\\
3935\end{tabular}
3936
3937\medskip
3938
3939All other (ordinary) characters in the format string are simply copied
3940to the resultant string.
3941
3942The first argument (calendar time) passed to the function {\tt time2str}
3943must be in the range from $-62135596800$ to $+64092211199$ that
3944corresponds to the period from 00:00:00 on January 1, 0001 to 23:59:59
3945on December 31, 4000 of the Gregorian calendar.
3946
3947%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3948
3949\newpage
3950
3951\section{Table drivers}
3952\label{drivers}
3953
3954\noindent\hfil
3955by Andrew Makhorin \verb|<mao@gnu.org>|
3956
3957\noindent\hfil
3958and Heinrich Schuchardt \verb|<heinrich.schuchardt@gmx.de>|
3959
3960\bigskip\bigskip
3961
3962The {\it table driver} is a program module which provides transmitting
3963data between MathProg model objects and data tables.
3964
3965Currently the GLPK package has four table drivers:
3966
3967\setlength{\leftmargini}{2.5em}
3968
3969\begin{itemize}
3970\item built-in CSV table driver;
3971\item built-in xBASE table driver;
3972\item ODBC table driver;
3973\item MySQL table driver.
3974\end{itemize}
3975
3976\subsection{CSV table driver}
3977
3978The CSV table driver assumes that the data table is represented in the
3979form of a plain text file in the CSV (comma-separated values) file
3980format as described below.
3981
3982To choose the CSV table driver its name in the table statement should
3983be specified as \verb|"CSV"|, and the only argument should specify the
3984name of a plain text file containing the table. For example:
3985
3986\medskip
3987
3988\verb|   table data IN "CSV" "data.csv": ... ;|
3989
3990\medskip
3991
3992The filename suffix may be arbitrary, however, it is recommended to use
3993the suffix `\verb|.csv|'.
3994
3995On reading input tables the CSV table driver provides an implicit field
3996named \verb|RECNO|, which contains the current record number. This
3997field can be specified in the input table statement as if there were
3998the actual field having the name \verb|RECNO| in the CSV file. For
3999example:
4000
4001\medskip
4002
4003\verb|   table list IN "CSV" "list.csv": num <- [RECNO], ... ;|
4004
4005\subsubsection*{CSV format\footnote{This material is based on the RFC
4006document 4180.}}
4007
4008The CSV (comma-separated values) format is a plain text file format
4009defined as follows.
4010
40111. Each record is located on a separate line, delimited by a line
4012break. For example:
4013
4014\medskip
4015
4016\verb|   aaa,bbb,ccc\n|
4017
4018\verb|   xxx,yyy,zzz\n|
4019
4020\medskip
4021
4022\noindent
4023where \verb|\n| means the control character \verb|LF| ({\tt 0x0A}).
4024
4025\newpage
4026
40272. The last record in the file may or may not have an ending line
4028break. For example:
4029
4030\medskip
4031
4032\verb|   aaa,bbb,ccc\n|
4033
4034\verb|   xxx,yyy,zzz|
4035
4036\medskip
4037
40383. There should be a header line appearing as the first line of the
4039file in the same format as normal record lines. This header should
4040contain names corresponding to the fields in the file. The number of
4041field names in the header line should be the same as the number of
4042fields in the records of the file. For example:
4043
4044\medskip
4045
4046\verb|   name1,name2,name3\n|
4047
4048\verb|   aaa,bbb,ccc\n|
4049
4050\verb|   xxx,yyy,zzz\n|
4051
4052\medskip
4053
40544. Within the header and each record there may be one or more fields
4055separated by commas. Each line should contain the same number of fields
4056throughout the file. Spaces are considered as part of a field and
4057therefore not ignored. The last field in the record should not be
4058followed by a comma. For example:
4059
4060\medskip
4061
4062\verb|   aaa,bbb,ccc\n|
4063
4064\medskip
4065
40665. Fields may or may not be enclosed in double quotes. For example:
4067
4068\medskip
4069
4070\verb|   "aaa","bbb","ccc"\n|
4071
4072\verb|   zzz,yyy,xxx\n|
4073
4074\medskip
4075
40766. If a field is enclosed in double quotes, each double quote which is
4077part of the field should be coded twice. For example:
4078
4079\medskip
4080
4081\verb|   "aaa","b""bb","ccc"\n|
4082
4083\medskip
4084
4085\noindent{\bf Example}
4086
4087\begin{verbatim}
4088FROM,TO,DISTANCE,COST
4089Seattle,New-York,2.5,0.12
4090Seattle,Chicago,1.7,0.08
4091Seattle,Topeka,1.8,0.09
4092San-Diego,New-York,2.5,0.15
4093San-Diego,Chicago,1.8,0.10
4094San-Diego,Topeka,1.4,0.07
4095\end{verbatim}
4096
4097\subsection{xBASE table driver}
4098
4099The xBASE table driver assumes that the data table is stored in the
4100.dbf file format.
4101
4102To choose the xBASE table driver its name in the table statement should
4103be specified as \verb|"xBASE"|, and the first argument should specify
4104the name of a .dbf file containing the table. For the output table there
4105should be the second argument defining the table format in the form
4106\verb|"FF...F"|, where \verb|F| is either {\tt C({\it n})},
4107which specifies a character field of length $n$, or
4108{\tt N({\it n}{\rm [},{\it p}{\rm ]})}, which specifies a numeric field
4109of length $n$ and precision $p$ (by default $p$ is 0).
4110
4111The following is a simple example which illustrates creating and
4112reading a .dbf file:
4113
4114\begin{verbatim}
4115table tab1{i in 1..10} OUT "xBASE" "foo.dbf"
4116   "N(5)N(10,4)C(1)C(10)": 2*i+1 ~ B, Uniform(-20,+20) ~ A,
4117   "?" ~ FOO, "[" & i & "]" ~ C;
4118set S, dimen 4;
4119table tab2 IN "xBASE" "foo.dbf": S <- [B, C, RECNO, A];
4120display S;
4121end;
4122\end{verbatim}
4123
4124\subsection{ODBC table driver}
4125
4126The ODBC table driver allows connecting to SQL databases using an
4127implementation of the ODBC interface based on the Call Level Interface
4128(CLI).\footnote{The corresponding software standard is defined in
4129ISO/IEC 9075-3:2003.}
4130
4131\paragraph{Debian GNU/Linux.}
4132Under Debian GNU/Linux the ODBC table driver uses the iODBC
4133package,\footnote{See {\tt<http://www.iodbc.org/>}.} which should be
4134installed before building the GLPK package. The installation can be
4135effected with the following command:
4136
4137\begin{verbatim}
4138sudo apt-get install libiodbc2-dev
4139\end{verbatim}
4140
4141Note that on configuring the GLPK package to enable using the iODBC
4142library the option `\verb|--enable-odbc|' should be passed to the
4143configure script.
4144
4145The individual databases must be entered for systemwide usage in
4146\linebreak \verb|/etc/odbc.ini| and \verb|/etc/odbcinst.ini|. Database
4147connections to be used by a single user are specified by files in the
4148home directory (\verb|.odbc.ini| and \verb|.odbcinst.ini|).
4149
4150\paragraph{Microsoft Windows.}
4151Under Microsoft Windows the ODBC table driver uses the Microsoft ODBC
4152library. To enable this feature the symbol:
4153
4154\begin{verbatim}
4155#define ODBC_DLNAME "odbc32.dll"
4156\end{verbatim}
4157
4158\noindent
4159should be defined in the GLPK configuration file `\verb|config.h|'.
4160
4161Data sources can be created via the Administrative Tools from the
4162Control Panel.
4163
4164\bigskip
4165
4166To choose the ODBC table driver its name in the table statement should
4167be specified as \verb|'ODBC'| or \verb|'iODBC'|.
4168
4169The argument list is specified as follows.
4170
4171The first argument is the connection string passed to the ODBC library,
4172for example:
4173
4174\verb|'DSN=glpk;UID=user;PWD=password'|, or
4175
4176\verb|'DRIVER=MySQL;DATABASE=glpkdb;UID=user;PWD=password'|.
4177
4178Different parts of the string are separated by semicolons. Each part
4179consists of a pair {\it fieldname} and {\it value} separated by the
4180equal sign. Allowable fieldnames depend on the ODBC library. Typically
4181the following fieldnames are allowed:
4182
4183\verb|DATABASE | database;
4184
4185\verb|DRIVER   | ODBC driver;
4186
4187\verb|DSN      | name of a data source;
4188
4189\verb|FILEDSN  | name of a file data source;
4190
4191\verb|PWD      | user password;
4192
4193\verb|SERVER   | database;
4194
4195\verb|UID      | user name.
4196
4197The second argument and all following are considered to be SQL
4198statements
4199
4200SQL statements may be spread over multiple arguments.  If the last
4201character of an argument is a semicolon this indicates the end of
4202a SQL statement.
4203
4204The arguments of a SQL statement are concatenated separated by space.
4205The eventual trailing semicolon will be removed.
4206
4207All but the last SQL statement will be executed directly.
4208
4209For IN-table the last SQL statement can be a SELECT command starting
4210with the capitalized letters \verb|'SELECT '|. If the string does not
4211start with \verb|'SELECT '| it is considered to be a table name and a
4212SELECT statement is automatically generated.
4213
4214For OUT-table the last SQL statement can contain one or multiple
4215question marks. If it contains a question mark it is considered a
4216template for the write routine. Otherwise the string is considered a
4217table name and an INSERT template is automatically generated.
4218
4219The writing routine uses the template with the question marks and
4220replaces the first question mark by the first output parameter, the
4221second question mark by the second output parameter and so forth. Then
4222the SQL command is issued.
4223
4224The following is an example of the output table statement:
4225
4226\begin{small}
4227\begin{verbatim}
4228table ta { l in LOCATIONS } OUT
4229   'ODBC'
4230   'DSN=glpkdb;UID=glpkuser;PWD=glpkpassword'
4231   'DROP TABLE IF EXISTS result;'
4232   'CREATE TABLE result ( ID INT, LOC VARCHAR(255), QUAN DOUBLE );'
4233   'INSERT INTO result 'VALUES ( 4, ?, ? )' :
4234   l ~ LOC, quantity[l] ~ QUAN;
4235\end{verbatim}
4236\end{small}
4237
4238\noindent
4239Alternatively it could be written as follows:
4240
4241\begin{small}
4242\begin{verbatim}
4243table ta { l in LOCATIONS } OUT
4244   'ODBC'
4245   'DSN=glpkdb;UID=glpkuser;PWD=glpkpassword'
4246   'DROP TABLE IF EXISTS result;'
4247   'CREATE TABLE result ( ID INT, LOC VARCHAR(255), QUAN DOUBLE );'
4248   'result' :
4249   l ~ LOC, quantity[l] ~ QUAN, 4 ~ ID;
4250\end{verbatim}
4251\end{small}
4252
4253Using templates with `\verb|?|' supports not only INSERT, but also
4254UPDATE, DELETE, etc. For example:
4255
4256\begin{small}
4257\begin{verbatim}
4258table ta { l in LOCATIONS } OUT
4259   'ODBC'
4260   'DSN=glpkdb;UID=glpkuser;PWD=glpkpassword'
4261   'UPDATE result SET DATE = ' & date & ' WHERE ID = 4;'
4262   'UPDATE result SET QUAN = ? WHERE LOC = ? AND ID = 4' :
4263   quantity[l], l;
4264\end{verbatim}
4265\end{small}
4266
4267\subsection{MySQL table driver}
4268
4269The MySQL table driver allows connecting to MySQL databases.
4270
4271\paragraph{Debian GNU/Linux.}
4272Under Debian GNU/Linux the MySQL table\linebreak driver uses the MySQL
4273package,\footnote{For download development files see
4274{\tt<http://dev.mysql.com/downloads/mysql/>}.} which should be installed
4275before building the GLPK package. The installation can be effected with
4276the following command:
4277
4278\begin{verbatim}
4279sudo apt-get install libmysqlclient15-dev
4280\end{verbatim}
4281
4282Note that on configuring the GLPK package to enable using the MySQL
4283library the option `\verb|--enable-mysql|' should be passed to the
4284configure script.
4285
4286\paragraph{Microsoft Windows.}
4287Under Microsoft Windows the MySQL table driver also uses the MySQL
4288library. To enable this feature the symbol:
4289
4290\begin{verbatim}
4291#define MYSQL_DLNAME "libmysql.dll"
4292\end{verbatim}
4293
4294\noindent
4295should be defined in the GLPK configuration file `\verb|config.h|'.
4296
4297\bigskip
4298
4299To choose the MySQL table driver its name in the table statement should
4300be specified as \verb|'MySQL'|.
4301
4302The argument list is specified as follows.
4303
4304The first argument specifies how to connect the data base in the DSN
4305style, for example:
4306
4307\verb|'Database=glpk;UID=glpk;PWD=gnu'|.
4308
4309Different parts of the string are separated by semicolons. Each part
4310consists of a pair {\it fieldname} and {\it value} separated by the
4311equal sign. The following fieldnames are allowed:
4312
4313\verb|Server   | server running the database (defaulting to localhost);
4314
4315\verb|Database | name of the database;
4316
4317\verb|UID      | user name;
4318
4319\verb|PWD      | user password;
4320
4321\verb|Port     | port used by the server (defaulting to 3306).
4322
4323The second argument and all following are considered to be SQL
4324statements
4325
4326SQL statements may be spread over multiple arguments.  If the last
4327character of an argument is a semicolon this indicates the end of
4328a SQL statement.
4329
4330The arguments of a SQL statement are concatenated separated by space.
4331The eventual trailing semicolon will be removed.
4332
4333All but the last SQL statement will be executed directly.
4334
4335For IN-table the last SQL statement can be a SELECT command starting
4336with the capitalized letters \verb|'SELECT '|. If the string does not
4337start with \verb|'SELECT '| it is considered to be a table name and a
4338SELECT statement is automatically generated.
4339
4340For OUT-table the last SQL statement can contain one or multiple
4341question marks. If it contains a question mark it is considered a
4342template for the write routine. Otherwise the string is considered a
4343table name and an INSERT template is automatically generated.
4344
4345The writing routine uses the template with the question marks and
4346replaces the first question mark by the first output parameter, the
4347second question mark by the second output parameter and so forth. Then
4348the SQL command is issued.
4349
4350The following is an example of the output table statement:
4351
4352\begin{small}
4353\begin{verbatim}
4354table ta { l in LOCATIONS } OUT
4355   'MySQL'
4356   'Database=glpkdb;UID=glpkuser;PWD=glpkpassword'
4357   'DROP TABLE IF EXISTS result;'
4358   'CREATE TABLE result ( ID INT, LOC VARCHAR(255), QUAN DOUBLE );'
4359   'INSERT INTO result VALUES ( 4, ?, ? )' :
4360   l ~ LOC, quantity[l] ~ QUAN;
4361\end{verbatim}
4362\end{small}
4363
4364\noindent
4365Alternatively it could be written as follows:
4366
4367\begin{small}
4368\begin{verbatim}
4369table ta { l in LOCATIONS } OUT
4370   'MySQL'
4371   'Database=glpkdb;UID=glpkuser;PWD=glpkpassword'
4372   'DROP TABLE IF EXISTS result;'
4373   'CREATE TABLE result ( ID INT, LOC VARCHAR(255), QUAN DOUBLE );'
4374   'result' :
4375   l ~ LOC, quantity[l] ~ QUAN, 4 ~ ID;
4376\end{verbatim}
4377\end{small}
4378
4379Using templates with `\verb|?|' supports not only INSERT, but also
4380UPDATE, DELETE, etc. For example:
4381
4382\begin{small}
4383\begin{verbatim}
4384table ta { l in LOCATIONS } OUT
4385   'MySQL'
4386   'Database=glpkdb;UID=glpkuser;PWD=glpkpassword'
4387   'UPDATE result SET DATE = ' & date & ' WHERE ID = 4;'
4388   'UPDATE result SET QUAN = ? WHERE LOC = ? AND ID = 4' :
4389   quantity[l], l;
4390\end{verbatim}
4391\end{small}
4392
4393%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4394
4395\newpage
4396
4397\section{Solving models with glpsol}
4398
4399The GLPK package\footnote{{\tt http://www.gnu.org/software/glpk/}}
4400includes the program {\tt glpsol}, which is a stand-alone LP/MIP solver.
4401This program can be launched from the command line or from the shell to
4402solve models written in the GNU MathProg modeling language.
4403
4404In order to tell the solver that the input file contains a model
4405description, you need to specify the option \verb|--model| in the
4406command line. For example:
4407
4408\medskip
4409
4410\verb|   glpsol --model foo.mod|
4411
4412\medskip
4413
4414Sometimes it is necessary to use the data section placed in a separate
4415file, in which case you may use the following command:
4416
4417\medskip
4418
4419\verb|   glpsol --model foo.mod --data foo.dat|
4420
4421\medskip
4422
4423\noindent Note that if the model file also contains the data section,
4424that section is ignored.
4425
4426If the model description contains some display and/or printf statements,
4427by default the output is sent to the terminal. In order to redirect the
4428output to a file you may use the following command:
4429
4430\medskip
4431
4432\verb|   glpsol --model foo.mod --display foo.out|
4433
4434\medskip
4435
4436If you need to look at the problem, which has been generated by the
4437model translator, you may use the option \verb|--wlp| as follows:
4438
4439\medskip
4440
4441\verb|   glpsol --model foo.mod --wlp foo.lp|
4442
4443\medskip
4444
4445\noindent in which case the problem data is written to file
4446\verb|foo.lp| in CPLEX LP format suitable for visual analysis.
4447
4448Sometimes it is needed merely to check the model description not
4449solving the generated problem instance. In this case you may specify
4450the option \verb|--check|, for example:
4451
4452\medskip
4453
4454\verb|   glpsol --check --model foo.mod --wlp foo.lp|
4455
4456\medskip
4457
4458In order to write a numeric solution obtained by the solver you may use
4459the following command:
4460
4461\medskip
4462
4463\verb|   glpsol --model foo.mod --output foo.sol|
4464
4465\medskip
4466
4467\noindent in which case the solution is written to file \verb|foo.sol|
4468in a plain text format.
4469
4470The complete list of the \verb|glpsol| options can be found in the
4471reference manual included in the GLPK distribution.
4472
4473%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4474
4475\newpage
4476
4477\section{Example model description}
4478
4479\subsection{Model description written in MathProg}
4480
4481Below here is a complete example of the model description written in
4482the GNU MathProg modeling language.
4483
4484\begin{small}
4485\begin{verbatim}
4486# A TRANSPORTATION PROBLEM
4487#
4488# This problem finds a least cost shipping schedule that meets
4489# requirements at markets and supplies at factories.
4490#
4491#  References:
4492#              Dantzig G B, "Linear Programming and Extensions."
4493#              Princeton University Press, Princeton, New Jersey, 1963,
4494#              Chapter 3-3.
4495
4496set I;
4497/* canning plants */
4498
4499set J;
4500/* markets */
4501
4502param a{i in I};
4503/* capacity of plant i in cases */
4504
4505param b{j in J};
4506/* demand at market j in cases */
4507
4508param d{i in I, j in J};
4509/* distance in thousands of miles */
4510
4511param f;
4512/* freight in dollars per case per thousand miles */
4513
4514param c{i in I, j in J} := f * d[i,j] / 1000;
4515/* transport cost in thousands of dollars per case */
4516
4517var x{i in I, j in J} >= 0;
4518/* shipment quantities in cases */
4519
4520minimize cost: sum{i in I, j in J} c[i,j] * x[i,j];
4521/* total transportation costs in thousands of dollars */
4522
4523s.t. supply{i in I}: sum{j in J} x[i,j] <= a[i];
4524/* observe supply limit at plant i */
4525
4526s.t. demand{j in J}: sum{i in I} x[i,j] >= b[j];
4527/* satisfy demand at market j */
4528
4529data;
4530
4531set I := Seattle San-Diego;
4532
4533set J := New-York Chicago Topeka;
4534
4535param a := Seattle     350
4536           San-Diego   600;
4537
4538param b := New-York    325
4539           Chicago     300
4540           Topeka      275;
4541
4542param d :              New-York   Chicago   Topeka :=
4543           Seattle     2.5        1.7       1.8
4544           San-Diego   2.5        1.8       1.4  ;
4545
4546param f := 90;
4547
4548end;
4549\end{verbatim}
4550\end{small}
4551
4552\subsection{Generated LP problem instance}
4553
4554Below here is the result of the translation of the example model
4555produced by the solver \verb|glpsol| and written in CPLEX LP format
4556with the option \verb|--wlp|.
4557
4558\begin{small}
4559\begin{verbatim}
4560\* Problem: transp *\
4561
4562Minimize
4563 cost: + 0.225 x(Seattle,New~York) + 0.153 x(Seattle,Chicago)
4564 + 0.162 x(Seattle,Topeka) + 0.225 x(San~Diego,New~York)
4565 + 0.162 x(San~Diego,Chicago) + 0.126 x(San~Diego,Topeka)
4566
4567Subject To
4568 supply(Seattle): + x(Seattle,New~York) + x(Seattle,Chicago)
4569 + x(Seattle,Topeka) <= 350
4570 supply(San~Diego): + x(San~Diego,New~York) + x(San~Diego,Chicago)
4571 + x(San~Diego,Topeka) <= 600
4572 demand(New~York): + x(Seattle,New~York) + x(San~Diego,New~York) >= 325
4573 demand(Chicago): + x(Seattle,Chicago) + x(San~Diego,Chicago) >= 300
4574 demand(Topeka): + x(Seattle,Topeka) + x(San~Diego,Topeka) >= 275
4575
4576End
4577\end{verbatim}
4578\end{small}
4579
4580\subsection{Optimal LP solution}
4581
4582Below here is the optimal solution of the generated LP problem instance
4583found by the solver \verb|glpsol| and written in plain text format
4584with the option \verb|--output|.
4585
4586\newpage
4587
4588\begin{small}
4589\begin{verbatim}
4590Problem:    transp
4591Rows:       6
4592Columns:    6
4593Non-zeros:  18
4594Status:     OPTIMAL
4595Objective:  cost = 153.675 (MINimum)
4596
4597No.   Row name   St   Activity    Lower bound  Upper bound   Marginal
4598--- ------------ -- ------------ ------------ ------------ ------------
4599  1 cost         B       153.675
4600  2 supply[Seattle]
4601                 B           300                       350
4602  3 supply[San-Diego]
4603                 NU          600                       600        < eps
4604  4 demand[New-York]
4605                 NL          325          325                     0.225
4606  5 demand[Chicago]
4607                 NL          300          300                     0.153
4608  6 demand[Topeka]
4609                 NL          275          275                     0.126
4610
4611No. Column name  St   Activity    Lower bound  Upper bound   Marginal
4612--- ------------ -- ------------ ------------ ------------ ------------
4613  1 x[Seattle,New-York]
4614                 B             0            0
4615  2 x[Seattle,Chicago]
4616                 B           300            0
4617  3 x[Seattle,Topeka]
4618                 NL            0            0                     0.036
4619  4 x[San-Diego,New-York]
4620                 B           325            0
4621  5 x[San-Diego,Chicago]
4622                 NL            0            0                     0.009
4623  6 x[San-Diego,Topeka]
4624                 B           275            0
4625
4626End of output
4627\end{verbatim}
4628\end{small}
4629
4630%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4631
4632\newpage
4633
4634\setcounter{secnumdepth}{-1}
4635
4636\section{Acknowledgment}
4637
4638The authors would like to thank the following people, who kindly read,
4639commented, and corrected the draft of this document:
4640
4641\medskip
4642
4643\noindent Juan Carlos Borras \verb|<borras@cs.helsinki.fi>|
4644
4645\medskip
4646
4647\noindent Harley Mackenzie \verb|<hjm@bigpond.com>|
4648
4649\medskip
4650
4651\noindent Robbie Morrison \verb|<robbie@actrix.co.nz>|
4652
4653\end{document}
Note: See TracBrowser for help on using the repository browser.