lemon-project-template-glpk
view deps/glpk/doc/gmpl.tex @ 9:33de93886c88
Import GLPK 4.47
| author | Alpar Juttner <alpar@cs.elte.hu> |
|---|---|
| date | Sun, 06 Nov 2011 20:59:10 +0100 |
| parents | |
| children |
line source
1 %* gmpl.tex *%
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 %***********************************************************************
25 \documentclass[10pt]{article}
26 \usepackage[dvipdfm,linktocpage,colorlinks,linkcolor=blue]{hyperref}
28 \begin{document}
30 \thispagestyle{empty}
32 \begin{center}
34 \vspace*{1in}
36 \begin{huge}
37 \sf\bfseries Modeling Language GNU MathProg
38 \end{huge}
40 \vspace{0.5in}
42 \begin{LARGE}
43 \sf Language Reference
44 \end{LARGE}
46 \vspace{0.5in}
48 \begin{LARGE}
49 \sf for GLPK Version 4.45
50 \end{LARGE}
52 \vspace{0.5in}
53 \begin{Large}
54 \sf (DRAFT, December 2010)
55 \end{Large}
57 \end{center}
59 \newpage
61 \vspace*{1in}
63 \vfill
65 \noindent
66 The GLPK package is part of the GNU Project released under the aegis of
67 GNU.
69 \medskip\noindent
70 Copyright \copyright{} 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2007,
71 2008, 2009, 2010 Andrew Makhorin, Department for Applied Informatics,
72 Moscow Aviation Institute, Moscow, Russia. All rights reserved.
74 \medskip\noindent
75 Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston,
76 MA 02110-1301, USA.
78 \medskip\noindent
79 Permission is granted to make and distribute verbatim copies of this
80 manual provided the copyright notice and this permission notice are
81 preserved on all copies.
83 \medskip\noindent
84 Permission is granted to copy and distribute modified versions of this
85 manual under the conditions for verbatim copying, provided also that
86 the entire resulting derived work is distributed under the terms of
87 a permission notice identical to this one.
89 \medskip\noindent
90 Permission is granted to copy and distribute translations of this
91 manual into another language, under the above conditions for modified
92 versions.
94 \newpage
96 \tableofcontents
98 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
100 \newpage
102 \section{Introduction}
104 {\it GNU MathProg} is a modeling language intended for describing
105 linear mathematical programming models.\footnote{The GNU MathProg
106 language is a subset of the AMPL language. Its GLPK implementation is
107 mainly based on the paper: {\it Robert Fourer}, {\it David M. Gay}, and
108 {\it Brian W. Kernighan}, ``A Modeling Language for Mathematical
109 Programming.'' {\it Management Science} 36 (1990)\linebreak pp. 519-54.}
111 Model descriptions written in the GNU MathProg language consist of
112 a set of statements and data blocks constructed by the user from the
113 language elements described in this document.
115 In a process called {\it translation}, a program called the {\it model
116 translator} analyzes the model description and translates it into
117 internal data structures, which may be then used either for generating
118 mathematical programming problem instance or directly by a program
119 called the {\it solver} to obtain numeric solution of the problem.
121 \subsection{Linear programming problem}
122 \label{problem}
124 In MathProg the linear programming (LP) problem is stated as follows:
126 \medskip
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}
133 L_1&\leq&a_{11}x_1&+&a_{12}x_2&+\dots+&a_{1n}x_n&\leq&U_1\\
134 L_2&\leq&a_{21}x_1&+&a_{22}x_2&+\dots+&a_{2n}x_n&\leq&U_2\\
135 \multicolumn{9}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}\\
136 L_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}
142 l_1&\leq&x_1&\leq&u_1\\
143 l_2&\leq&x_2&\leq&u_2\\
144 \multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .}\\
145 l_n&\leq&x_n&\leq&u_n\\
146 \end{array}\eqno(1.3)
147 $$
148 where $x_1$, $x_2$, \dots, $x_n$ are variables; $z$ is the objective
149 function; $c_1$, $c_2$, \dots, $c_n$ are objective coefficients; $c_0$
150 is 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$
153 are upper constraint bounds; $l_1$, $l_2$, \dots, $l_n$ are lower
154 bounds of variables; $u_1$, $u_2$, \dots, $u_n$ are upper bounds of
155 variables.
157 Bounds of variables and constraint bounds can be finite as well as
158 infinite. Besides, lower bounds can be equal to corresponding upper
159 bounds. Thus, the following types of variables and constraints are
160 allowed:
162 \newpage
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}
172 \bigskip
174 \begin{tabular}{@{}r@{\ }c@{\ }c@{\ }c@{\ }ll}
175 $-\infty$&$<$&$\sum a_jx_j$&$<$&$+\infty$&Free (unbounded) linear
176 form\\
177 $L$&$\leq$&$\sum a_jx_j$&$<$&$+\infty$&Inequality constraint ``greater
178 than or equal to''\\
179 $-\infty$&$<$&$\sum a_jx_j$&$\leq$&$U$&Inequality constraint ``less
180 than or equal to''\\
181 $L$&$\leq$&$\sum a_jx_j$&$\leq$&$U$&Double-bounded inequality
182 constraint\\
183 $L$&$=$&$\sum a_jx_j$&=&$U$&Equality constraint\\
184 \end{tabular}
186 \bigskip
188 In addition to pure LP problems MathProg also allows mixed integer
189 linear programming (MIP) problems, where some or all variables are
190 restricted to be integer or binary.
192 \subsection{Model objects}
194 In MathProg the model is described in terms of sets, parameters,
195 variables, constraints, and objectives, which are called {\it model
196 objects}.
198 The user introduces particular model objects using the language
199 statements. Each model object is provided with a symbolic name that
200 uniquely identifies the object and is intended for referencing purposes.
202 Model objects, including sets, can be multidimensional arrays built
203 over indexing sets. Formally, $n$-dimensional array $A$ is the mapping:
204 $$A:\Delta\rightarrow\Xi,\eqno(1.4)$$
205 where $\Delta\subseteq S_1\times\dots\times S_n$ is a subset of the
206 Cartesian product of indexing sets,\linebreak $\Xi$ is a set of array members.
207 In MathProg the set $\Delta$ is called the {\it subscript domain}. Its
208 members are $n$-tuples $(i_1,\dots,i_n)$, where $i_1\in S_1$, \dots,
209 $i_n\in S_n$.
211 If $n=0$, the Cartesian product above has exactly one member (namely,
212 \linebreak 0-tuple), so it is convenient to think scalar objects as
213 0-dimensional arrays having one member.
215 The type of array members is determined by the type of corresponding
216 model object as follows:
218 \medskip
220 \noindent\hfil
221 \begin{tabular}{@{}ll@{}}
222 Model object&Array member\\
223 \hline
224 Set&Elemental plain set\\
225 Parameter&Number or symbol\\
226 Variable&Elemental variable\\
227 Constraint&Elemental constraint\\
228 Objective&Elemental objective\\
229 \end{tabular}
231 \medskip
233 In order to refer to a particular object member the object should be
234 provided with {\it subscripts}. For example, if $a$ is a 2-dimensional
235 parameter defined over $I\times J$, a reference to its particular
236 member can be written as $a[i,j]$, where $i\in I$ and $j\in J$. It is
237 understood that scalar objects being 0-dimensional need no subscripts.
239 \subsection{Structure of model description}
241 It is sometimes desirable to write a model which, at various points,
242 may require different data for each problem instance to be solved using
243 that model. For this reason in MathProg the model description consists
244 of two parts: the {\it model section} and the {\it data section}.
246 The model section is a main part of the model description that contains
247 declarations of model objects and is common for all problems based on
248 the corresponding model.
250 The data section is an optional part of the model description that
251 contains data specific for a particular problem instance.
253 Depending on what is more convenient the model and data sections can be
254 placed either in one file or in two separate files. The latter feature
255 allows having arbitrary number of different data sections to be used
256 with the same model section.
258 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
260 \newpage
262 \section{Coding model description}
263 \label{coding}
265 The model description is coded in plain text format using ASCII
266 character set. Characters valid in the model description are the
267 following:
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}
281 Within string literals and comments any ASCII characters (except
282 control characters) are valid.
284 White-space characters are non-significant. They can be used freely
285 between lexical units to improve readability of the model description.
286 They are also used to separate lexical units from each other if there
287 is no other way to do that.
289 Syntactically model description is a sequence of lexical units in the
290 following categories:
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}
301 The lexical units of the language are discussed below.
303 \subsection{Symbolic names}
305 A {\it symbolic name} consists of alphabetic and numeric characters,
306 the first of which must be alphabetic. All symbolic names are distinct
307 (case sensitive).
309 \medskip
311 \noindent{\bf Examples}
313 \medskip
315 \noindent\verb|alpha123|
317 \noindent\verb|This_is_a_name|
319 \noindent\verb|_P123_abc_321|
321 \newpage
323 Symbolic names are used to identify model objects (sets, parameters,
324 variables, constraints, objectives) and dummy indices.
326 All symbolic names (except names of dummy indices) must be unique, i.e.
327 the model description must have no objects with identical names.
328 Symbolic names of dummy indices must be unique within the scope, where
329 they are valid.
331 \subsection{Numeric literals}
333 A {\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
336 case insensitive and can be coded as {\tt e}.
338 \medskip
340 \noindent{\bf Examples}
342 \medskip
344 \noindent\verb|123|
346 \noindent\verb|3.14159|
348 \noindent\verb|56.E+5|
350 \noindent\verb|.78|
352 \noindent\verb|123.456e-7|
354 \medskip
356 Numeric literals are used to represent numeric quantities. They have
357 obvious fixed meaning.
359 \subsection{String literals}
361 A {\it string literal} is a sequence of arbitrary characters enclosed
362 either in single quotes or in double quotes. Both these forms are
363 equivalent.
365 If the single quote is part of a string literal enclosed in single
366 quotes, it must be coded twice. Analogously, if the double quote is
367 part of a string literal enclosed in double quotes, it must be coded
368 twice.
370 \medskip
372 \noindent{\bf Examples}
374 \medskip
376 \noindent\verb|'This is a string'|
378 \noindent\verb|"This is another string"|
380 \noindent\verb|'1 + 2 = 3'|
382 \noindent\verb|'That''s all'|
384 \noindent\verb|"She said: ""No"""|
386 \medskip
388 String literals are used to represent symbolic quantities.
390 \subsection{Keywords}
392 A {\it keyword} is a sequence of alphabetic characters and possibly
393 some special characters.
395 All keywords fall into two categories: {\it reserved keywords}, which
396 cannot be used as symbolic names, and {\it non-reserved keywords},
397 which being recognized by context can be used as symbolic names.
399 \newpage
401 The reserved keywords are the following:
403 \medskip
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}
414 \medskip
416 Non-reserved keywords are described in following sections.
418 All the keywords have fixed meaning, which will be explained on
419 discussion of corresponding syntactic constructions, where the keywords
420 are used.
422 \subsection{Delimiters}
424 A {\it delimiter} is either a single special character or a sequence of
425 two special characters as follows:
427 \medskip
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}
438 \medskip
440 If the delimiter consists of two characters, there must be no spaces
441 between the characters.
443 All the delimiters have fixed meaning, which will be explained on
444 discussion corresponding syntactic constructions, where the delimiters
445 are used.
447 \subsection{Comments}
449 For documenting purposes the model description can be provided with
450 {\it comments}, which may have two different forms. The first form is
451 a {\it single-line comment}, which begins with the character {\tt\#}
452 and extends until end of line. The second form is a {\it comment
453 sequence}, which is a sequence of any characters enclosed within
454 {\tt/*} and {\tt*/}.
456 \medskip
458 \noindent{\bf Examples}
460 \medskip
462 \noindent\verb|param n := 10; # This is a comment|
464 \noindent\verb|/* This is another comment */|
466 \medskip
468 Comments are ignored by the model translator and can appear anywhere in
469 the model description, where white-space characters are allowed.
471 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
473 \newpage
475 \section{Expressions}
477 An {\it expression} is a rule for computing a value. In model
478 description expressions are used as constituents of certain statements.
480 In general case expressions consist of operands and operators.
482 Depending on the type of the resultant value all expressions fall into
483 the following categories:
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}
494 \subsection{Numeric expressions}
496 A {\it numeric expression} is a rule for computing a single numeric
497 value represented as a floating-point number.
499 The primary numeric expression may be a numeric literal, dummy index,
500 unsubscripted parameter, subscripted parameter, built-in function
501 reference, iterated numeric expression, conditional numeric expression,
502 or another numeric expression enclosed in parentheses.
504 \medskip
506 \noindent{\bf Examples}
508 \medskip
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}
522 \medskip
524 More general numeric expressions containing two or more primary numeric
525 expressions may be constructed by using certain arithmetic operators.
527 \medskip
529 \noindent{\bf Examples}
531 \medskip
533 \noindent\verb|j+1|
535 \noindent\verb|2 * a[i-1,j+1] - b[i,j]|
537 \noindent\verb|sum{j in J} a[i,j] * x[j] + sum{k in K} b[i,k] * x[k]|
539 \noindent\verb|(if i in I then 2 * p else q[i+1]) / (a[i,j] + 1.5)|
541 \subsubsection{Numeric literals}
543 If the primary numeric expression is a numeric literal, the resultant
544 value is obvious.
546 \subsubsection{Dummy indices}
548 If the primary numeric expression is a dummy index, the resultant value
549 is current value assigned to that dummy index.
551 \subsubsection{Unsubscripted parameters}
553 If the primary numeric expression is an unsubscripted parameter (which
554 must be 0-dimensional), the resultant value is the value of that
555 parameter.
557 \subsubsection{Subscripted parameters}
559 The primary numeric expression, which refers to a subscripted parameter,
560 has the following syntactic form:
562 \medskip
564 \noindent\hfil
565 {\it name}{\tt[}$i_1${\tt,} $i_2${\tt,} \dots{\tt,} $i_n${\tt]}
567 \medskip
569 \noindent where {\it name} is the symbolic name of the parameter,
570 $i_1$, $i_2$, \dots, $i_n$ are subscripts.
572 Each subscript must be a numeric or symbolic expression. The number of
573 subscripts in the subscript list must be the same as the dimension of
574 the parameter with which the subscript list is associated.
576 Actual values of subscript expressions are used to identify
577 a particular member of the parameter that determines the resultant
578 value of the primary expression.
580 \subsubsection{Function references}
582 In MathProg there exist the following built-in functions which may be
583 used in numeric expressions:
585 \medskip
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
592 arc tangent of $y/x$ (in radians). In this case the signs of both
593 arguments $y$ and $x$ are used to determine the quadrant of the
594 resultant value\\
595 {\tt card(}$X${\tt)}&$|X|$, cardinality (the number of elements) of
596 set $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
602 than $x$ (``floor of $x$'')\\
603 \end{tabular}
605 \begin{tabular}{@{}p{96pt}p{222pt}@{}}
606 {\tt gmtime()}&the number of seconds elapsed since 00:00:00~Jan~1, 1970,
607 Coordinated Universal Time (for details see Subsection \ref{gmtime},
608 page \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
613 of values $x_1$, $x_2$, \dots, $x_n$\\
614 {\tt min(}$x_1${\tt,} $x_2${\tt,} \dots{\tt,} $x_n${\tt)}&the smallest
615 of 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
618 digits\\
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
622 calendar 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
626 decimal digits\\
627 {\tt Irand224()}&generating pseudo-random integer uniformly distributed
628 in $[0,2^{24})$\\
629 {\tt Uniform01()}&generating pseudo-random number uniformly distributed
630 in $[0,1)$\\
631 {\tt Uniform(}$a${\tt,} $b${\tt)}&generating pseudo-random number
632 uniformly 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
636 pseudo-random variate with given $\mu$ and $\sigma$\\
637 \end{tabular}
639 \medskip
641 Arguments of all built-in functions, except {\tt card}, {\tt length},
642 and {\tt str2time}, must be numeric expressions. The argument of
643 {\tt card} must be a set expression. The argument of {\tt length} and
644 both arguments of {\tt str2time} must be symbolic expressions.
646 The resultant value of the numeric expression, which is a function
647 reference, is the result of applying the function to its argument(s).
649 Note that each pseudo-random generator function has a latent argument
650 (i.e. some internal state), which is changed whenever the function has
651 been applied. Thus, if the function is applied repeatedly even to
652 identical arguments, due to the side effect different resultant values
653 are always produced.
655 \subsubsection{Iterated expressions}
656 \label{itexpr}
658 An {\it iterated numeric expression} is a primary numeric expression,
659 which has the following syntactic form:
661 \medskip
663 \noindent\hfil
664 {\it iterated-operator indexing-expression integrand}
666 \medskip
668 \noindent where {\it iterated-operator} is the symbolic name of the
669 iterated operator to be performed (see below), {\it indexing-expression}
670 is an indexing expression which introduces dummy indices and controls
671 iterating, {\it integrand} is a numeric expression that participates in
672 the operation.
674 In MathProg there exist four iterated operators, which may be used in
675 numeric expressions:
677 \medskip
679 \noindent\hfil
680 \begin{tabular}{@{}lll@{}}
681 {\tt sum}&summation&$\displaystyle\sum_{(i_1,\dots,i_n)\in\Delta}
682 f(i_1,\dots,i_n)$\\
683 {\tt prod}&production&$\displaystyle\prod_{(i_1,\dots,i_n)\in\Delta}
684 f(i_1,\dots,i_n)$\\
685 {\tt min}&minimum&$\displaystyle\min_{(i_1,\dots,i_n)\in\Delta}
686 f(i_1,\dots,i_n)$\\
687 {\tt max}&maximum&$\displaystyle\max_{(i_1,\dots,i_n)\in\Delta}
688 f(i_1,\dots,i_n)$\\
689 \end{tabular}
691 \medskip
693 \noindent where $i_1$, \dots, $i_n$ are dummy indices introduced in
694 the indexing expression, $\Delta$ is the domain, a set of $n$-tuples
695 specified by the indexing expression which defines particular values
696 assigned to the dummy indices on performing the iterated operation,
697 $f(i_1,\dots,i_n)$ is the integrand, a numeric expression whose
698 resultant value depends on the dummy indices.
700 The resultant value of an iterated numeric expression is the result of
701 applying of the iterated operator to its integrand over all $n$-tuples
702 contained in the domain.
704 \subsubsection{Conditional expressions}
705 \label{ifthen}
707 A {\it conditional numeric expression} is a primary numeric expression,
708 which has one of the following two syntactic forms:
710 \medskip
712 \noindent\hfil
713 {\tt if} $b$ {\tt then} $x$ {\tt else} $y$
715 \medskip
717 \noindent\hspace{126.5pt}
718 {\tt if} $b$ {\tt then} $x$
720 \medskip
722 \noindent where $b$ is an logical expression, $x$ and $y$ are numeric
723 expressions.
725 The resultant value of the conditional expression depends on the value
726 of the logical expression that follows the keyword {\tt if}. If it
727 takes on the value {\it true}, the value of the conditional expression
728 is the value of the expression that follows the keyword {\tt then}.
729 Otherwise, if the logical expression takes on the value {\it false},
730 the value of the conditional expression is the value of the expression
731 that follows the keyword {\it else}. If the second, reduced form of the
732 conditional expression is used and the logical expression takes on the
733 value {\it false}, the resultant value of the conditional expression is
734 zero.
736 \subsubsection{Parenthesized expressions}
738 Any numeric expression may be enclosed in parentheses that
739 syntactically makes it a primary numeric expression.
741 Parentheses may be used in numeric expressions, as in algebra, to
742 specify the desired order in which operations are to be performed.
743 Where parentheses are used, the expression within the parentheses is
744 evaluated before the resultant value is used.
746 The resultant value of the parenthesized expression is the same as the
747 value of the expression enclosed within parentheses.
749 \subsubsection{Arithmetic operators}
751 In MathProg there exist the following arithmetic operators, which may
752 be used in numeric expressions:
754 \medskip
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$"ient of exact division\\
765 $x$ {\tt mod} $y$&remainder of exact division\\
766 $x$ {\tt **} $y$, $x$ {\tt\textasciicircum} $y$&exponentiation (raising
767 to power)\\
768 \end{tabular}
770 \medskip
772 \noindent where $x$ and $y$ are numeric expressions.
774 If the expression includes more than one arithmetic operator, all
775 operators are performed from left to right according to the hierarchy
776 of operations (see below) with the only exception that the
777 exponentiaion operators are performed from right to left.
779 The resultant value of the expression, which contains arithmetic
780 operators, is the result of applying the operators to their operands.
782 \subsubsection{Hierarchy of operations}
783 \label{hierarchy}
785 The following list shows the hierarchy of operations in numeric
786 expressions:
788 \medskip
790 \noindent\hfil
791 \begin{tabular}{@{}ll@{}}
792 Operation&Hierarchy\\
793 \hline
794 Evaluation of functions ({\tt abs}, {\tt ceil}, etc.)&1st\\
795 Exponentiation ({\tt**}, {\tt\textasciicircum})&2nd\\
796 Unary plus and minus ({\tt+}, {\tt-})&3rd\\
797 Multiplication and division ({\tt*}, {\tt/}, {\tt div}, {\tt mod})&4th\\
798 Iterated operations ({\tt sum}, {\tt prod}, {\tt min}, {\tt max})&5th\\
799 Addition and subtraction ({\tt+}, {\tt-}, {\tt less})&6th\\
800 Conditional evaluation ({\tt if} \dots {\tt then} \dots {\tt else})&
801 7th\\
802 \end{tabular}
804 \medskip
806 This hierarchy is used to determine which of two consecutive operations
807 is performed first. If the first operator is higher than or equal to
808 the second, the first operation is performed. If it is not, the second
809 operator is compared to the third, etc. When the end of the expression
810 is reached, all of the remaining operations are performed in the
811 reverse order.
813 \newpage
815 \subsection{Symbolic expressions}
817 A {\it symbolic expression} is a rule for computing a single symbolic
818 value represented as a character string.
820 The primary symbolic expression may be a string literal, dummy index,
821 unsubscripted parameter, subscripted parameter, built-in function
822 reference, conditional symbolic expression, or another symbolic
823 expression enclosed in parentheses.
825 It is also allowed to use a numeric expression as the primary symbolic
826 expression, in which case the resultant value of the numeric expression
827 is automatically converted to the symbolic type.
829 \medskip
831 \noindent{\bf Examples}
833 \medskip
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}
846 \medskip
848 More general symbolic expressions containing two or more primary
849 symbolic expressions may be constructed by using the concatenation
850 operator.
852 \medskip
854 \noindent{\bf Examples}
856 \medskip
858 \noindent\verb|'abc[' & i & ',' & j & ']'|
860 \noindent\verb|"from " & city[i] & " to " & city[j]|
862 \medskip
864 The principles of evaluation of symbolic expressions are completely
865 analogous to the ones given for numeric expressions (see above).
867 \subsubsection{Function references}
869 In MathProg there exist the following built-in functions which may be
870 used in symbolic expressions:
872 \medskip
874 \begin{tabular}{@{}p{96pt}p{222pt}@{}}
875 {\tt substr(}$s${\tt,} $x${\tt)}&substring of $s$ starting from
876 position $x$\\
877 {\tt substr(}$s${\tt,} $x${\tt,} $y${\tt)}&substring of $s$ starting
878 from position $x$ and having length $y$\\
879 {\tt time2str(}$t${\tt,} $f${\tt)}&converting calendar time to
880 character string (for details see Subsection \ref{time2str}, page
881 \pageref{time2str})\\
882 \end{tabular}
884 \medskip
886 The first argument of {\tt substr} must be a symbolic expression while
887 its second and optional third arguments must be numeric expressions.
889 The first argument of {\tt time2str} must be a numeric expression, and
890 its second argument must be a symbolic expression.
892 The resultant value of the symbolic expression, which is a function
893 reference, is the result of applying the function to its arguments.
895 \subsubsection{Symbolic operators}
897 Currently in MathProg there exists the only symbolic operator:
899 \medskip
901 \noindent\hfil
902 {\tt s \& t}
904 \medskip
906 \noindent where $s$ and $t$ are symbolic expressions. This operator
907 means concatenation of its two symbolic operands, which are character
908 strings.
910 \subsubsection{Hierarchy of operations}
912 The following list shows the hierarchy of operations in symbolic
913 expressions:
915 \medskip
917 \noindent\hfil
918 \begin{tabular}{@{}ll@{}}
919 Operation&Hierarchy\\
920 \hline
921 Evaluation of numeric operations&1st-7th\\
922 Concatenation ({\tt\&})&8th\\
923 Conditional evaluation ({\tt if} \dots {\tt then} \dots {\tt else})&
924 7th\\
925 \end{tabular}
927 \medskip
929 This hierarchy has the same meaning as was explained above for numeric
930 expressions (see Subsection \ref{hierarchy}, page \pageref{hierarchy}).
932 \subsection{Indexing expressions and dummy indices}
933 \label{indexing}
935 An {\it indexing expression} is an auxiliary construction, which
936 specifies a plain set of $n$-tuples and introduces dummy indices. It
937 has two syntactic forms:
939 \medskip
941 \noindent\hspace{73.5pt}
942 {\tt\{} {\it entry}$_1${\tt,} {\it entry}$_2${\tt,} \dots{\tt,}
943 {\it entry}$_m$ {\tt\}}
945 \medskip
947 \noindent\hfil
948 {\tt\{} {\it entry}$_1${\tt,} {\it entry}$_2${\tt,} \dots{\tt,}
949 {\it entry}$_m$ {\tt:} {\it predicate} {\tt\}}
951 \medskip
953 \noindent where {\it entry}{$_1$}, {\it entry}{$_2$}, \dots,
954 {\it entry}{$_m$} are indexing entries, {\it predicate} is a logical
955 expression that specifies an optional predicate (logical condition).
957 Each {\it indexing entry} in the indexing expression has one of the
958 following three forms:
960 \medskip
962 \noindent\hspace{123pt}
963 $i$ {\tt in} $S$
965 \medskip
967 \noindent\hfil
968 {\tt(}$i_1${\tt,} $i_2${\tt,} \dots{\tt,}$i_n${\tt)} {\tt in} $S$
970 \medskip
972 \noindent\hspace{123pt}
973 $S$
975 \medskip
977 \noindent where $i_1$, $i_2$, \dots, $i_n$ are indices, $S$ is a set
978 expression (discussed in the next section) that specifies the basic set.
980 The number of indices in the indexing entry must be the same as the
981 dimension of the basic set $S$, i.e. if $S$ consists of 1-tuples, the
982 first form must be used, and if $S$ consists of $n$-tuples, where
983 $n>1$, the second form must be used.
985 If the first form of the indexing entry is used, the index $i$ can be
986 a 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
988 or symbolic expressions, where at least one index must be a dummy index.
989 The third, reduced form of the indexing entry has the same effect as if
990 there 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.
993 A {\it dummy index} is an auxiliary model object, which acts like an
994 individual variable. Values assigned to dummy indices are components of
995 $n$-tuples from basic sets, i.e. some numeric and symbolic quantities.
997 For referencing purposes dummy indices can be provided with symbolic
998 names. However, unlike other model objects (sets, parameters, etc.)
999 dummy indices need not be explicitly declared. Each {\it undeclared}
1000 symbolic name being used in the indexing position of an indexing entry
1001 is recognized as the symbolic name of corresponding dummy index.
1003 Symbolic names of dummy indices are valid only within the scope of the
1004 indexing expression, where the dummy indices were introduced. Beyond
1005 the scope the dummy indices are completely inaccessible, so the same
1006 symbolic names may be used for other purposes, in particular, to
1007 represent dummy indices in other indexing expressions.
1009 The scope of indexing expression, where implicit declarations of dummy
1010 indices are valid, depends on the context, in which the indexing
1011 expression is used:
1013 \begin{enumerate}
1014 \item If the indexing expression is used in iterated operator, its
1015 scope extends until the end of the integrand.
1016 \item If the indexing expression is used as a primary set expression,
1017 its scope extends until the end of that indexing expression.
1018 \item If the indexing expression is used to define the subscript domain
1019 in declarations of some model objects, its scope extends until the end
1020 of the corresponding statement.
1021 \end{enumerate}
1023 The indexing mechanism implemented by means of indexing expressions is
1024 best explained by some examples discussed below.
1026 Let there be given three sets:
1028 \medskip
1030 \noindent\hspace{33.5pt}
1031 $A=\{4,7,9\}$,
1033 \medskip
1035 \noindent\hfil
1036 $B=\{(1,Jan),(1,Feb),(2,Mar),(2,Apr),(3,May),(3,Jun)\}$,
1038 \medskip
1040 \noindent\hspace{33.5pt}
1041 $C=\{a,b,c\}$,
1043 \medskip
1045 \noindent where $A$ and $C$ consist of 1-tuples (singlets), $B$
1046 consists of 2-tuples (doublets). Consider the following indexing
1047 expression:
1049 \medskip
1051 \noindent\hfil
1052 {\tt\{i in A, (j,k) in B, l in C\}}
1054 \medskip
1056 \noindent where {\tt i}, {\tt j}, {\tt k}, and {\tt l} are dummy
1057 indices.
1059 Although MathProg is not a procedural language, for any indexing
1060 expression an equivalent algorithmic description can be given. In
1061 particular, the algorithmic description of the indexing expression
1062 above could look like follows:
1064 \medskip
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}
1074 \newpage
1076 \noindent where the dummy indices $i$, $j$, $k$, $l$ are consecutively
1077 assigned corresponding components of $n$-tuples from the basic sets $A$,
1078 $B$, $C$, and {\it action} is some action that depends on the context,
1079 where the indexing expression is used. For example, if the action were
1080 printing current values of dummy indices, the printout would look like
1081 follows:
1083 \medskip
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}
1097 \medskip
1099 Let the example indexing expression be used in the following iterated
1100 operation:
1102 \medskip
1104 \noindent\hfil
1105 {\tt sum\{i in A, (j,k) in B, l in C\} p[i,j,k,l]}
1107 \medskip
1109 \noindent where {\tt p} is a 4-dimensional numeric parameter or some
1110 numeric 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
1112 resultant value of the primary numeric expression is:
1113 $$\sum_{i\in A,(j,k)\in B,l\in C}(p_{ijkl}).$$
1115 Now let the example indexing expression be used as a primary set
1116 expression. 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
1118 value of such operation is simply the Cartesian product of the basic
1119 sets:
1120 $$A\times B\times C=\{(i,j,k,l):i\in A,(j,k)\in B,l\in C\}.$$
1121 Note that in this case the same indexing expression might be written in
1122 the reduced form:
1124 \medskip
1126 \noindent\hfil
1127 {\tt\{A, B, C\}}
1129 \medskip
1131 \noindent because the dummy indices $i$, $j$, $k$, and $l$ are not
1132 referenced and therefore their symbolic names need not be specified.
1134 Finally, let the example indexing expression be used as the subscript
1135 domain in the declaration of a 4-dimensional model object, say,
1136 a numeric parameter:
1138 \medskip
1140 \noindent\hfil
1141 {\tt param p\{i in A, (j,k) in B, l in C\}} \dots {\tt;}
1143 \medskip
1145 \noindent In this case the action is generating the parameter members,
1146 where each member has the form $p[i,j,k,l]$.
1148 As was said above, some indices in the second form of indexing entries
1149 may be numeric or symbolic expressions, not only dummy indices. In this
1150 case resultant values of such expressions play role of some logical
1151 conditions to select only that $n$-tuples from the Cartesian product of
1152 basic sets that satisfy these conditions.
1154 Consider, for example, the following indexing expression:
1156 \medskip
1158 \noindent\hfil
1159 {\tt\{i in A, (i-1,k) in B, l in C\}}
1161 \medskip
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
1165 indexing expression is the following:
1167 \medskip
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}
1177 \medskip
1179 \noindent Thus, if this indexing expression were used as a primary set
1180 expression, 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)\}.$$
1182 Should note that in this case the resultant set consists of 3-tuples,
1183 not of 4-tuples, because in the indexing expression there is no dummy
1184 index that corresponds to the first component of 2-tuples from the set
1185 $B$.
1187 The general rule is: the number of components of $n$-tuples defined by
1188 an indexing expression is the same as the number of dummy indices in
1189 that expression, where the correspondence between dummy indices and
1190 components on $n$-tuples in the resultant set is positional, i.e. the
1191 first dummy index corresponds to the first component, the second dummy
1192 index corresponds to the second component, etc.
1194 In some cases it is needed to select a subset from the Cartesian
1195 product of some sets. This may be attained by using an optional logical
1196 predicate, which is specified in the indexing expression.
1198 Consider, for example, the following indexing expression:
1200 \medskip
1202 \noindent\hfil
1203 {\tt\{i in A, (j,k) in B, l in C: i <= 5 and k <> 'Mar'\}}
1205 \medskip
1207 \noindent where the logical expression following the colon is a
1208 predicate. The algorithmic description of this indexing expression is
1209 the following:
1211 \medskip
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}
1222 \medskip
1224 \noindent Thus, if this indexing expression were used as a primary set
1225 expression, 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)\}.$$
1228 If no predicate is specified in the indexing expression, one, which
1229 takes on the value {\it true}, is assumed.
1231 \subsection{Set expressions}
1233 A {\it set expression} is a rule for computing an elemental set, i.e.
1234 a collection of $n$-tuples, where components of $n$-tuples are numeric
1235 and symbolic quantities.
1237 The primary set expression may be a literal set, unsubscripted set,
1238 subscripted set, ``arithmetic'' set, indexing expression, iterated set
1239 expression, conditional set expression, or another set expression
1240 enclosed in parentheses.
1242 \medskip
1244 \noindent{\bf Examples}
1246 \medskip
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}
1260 \medskip
1262 More general set expressions containing two or more primary set
1263 expressions may be constructed by using certain set operators.
1265 \medskip
1267 \noindent{\bf Examples}
1269 \medskip
1271 \noindent\verb|(A union B) inter (I cross J)|
1273 \noindent
1274 \verb|1..10 cross (if i < j then {'a', 'b', 'c'} else {'d', 'e', 'f'})|
1276 \subsubsection{Literal sets}
1278 A {\it literal set} is a primary set expression, which has the
1279 following two syntactic forms:
1281 \medskip
1283 \noindent\hspace{39pt}
1284 {\tt\{}$e_1${\tt,} $e_2${\tt,} \dots{\tt,} $e_m${\tt\}}
1286 \medskip
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)\}}
1293 \medskip
1295 \noindent where $e_1$, \dots, $e_m$, $e_{11}$, \dots, $e_{mn}$ are
1296 numeric or symbolic expressions.
1298 If the first form is used, the resultant set consists of 1-tuples
1299 (singlets) enumerated within the curly braces. It is allowed to specify
1300 an empty set as {\tt\{\ \}}, which has no 1-tuples. If the second form
1301 is used, the resultant set consists of $n$-tuples enumerated within the
1302 curly braces, where a particular $n$-tuple consists of corresponding
1303 components enumerated within the parentheses. All $n$-tuples must have
1304 the same number of components.
1306 \subsubsection{Unsubscripted sets}
1308 If the primary set expression is an unsubscripted set (which must be
1309 0-dimen\-sional), the resultant set is an elemental set associated with
1310 the corresponding set object.
1312 \newpage
1314 \subsubsection{Subscripted sets}
1316 The primary set expression, which refers to a subscripted set, has the
1317 following syntactic form:
1319 \medskip
1321 \noindent\hfil
1322 {\it name}{\tt[}$i_1${\tt,} $i_2${\tt,} \dots{\tt,} $i_n${\tt]}
1324 \medskip
1326 \noindent where {\it name} is the symbolic name of the set object,
1327 $i_1$, $i_2$, \dots, $i_n$ are subscripts.
1329 Each subscript must be a numeric or symbolic expression. The number of
1330 subscripts in the subscript list must be the same as the dimension of
1331 the set object with which the subscript list is associated.
1333 Actual values of subscript expressions are used to identify a
1334 particular member of the set object that determines the resultant set.
1336 \subsubsection{``Arithmetic'' sets}
1338 The primary set expression, which is an ``arithmetic'' set, has the
1339 following two syntactic forms:
1341 \medskip
1343 \noindent\hfil
1344 $t_0$ {\tt..} $t_1$ {\tt by} $\delta t$
1346 \medskip
1348 \noindent\hspace{138.5pt}
1349 $t_0$ {\tt..} $t_1$
1351 \medskip
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
1355 equivalent to the first form, where $\delta t=1$.
1357 If $\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)\}.$$
1359 Otherwise, 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)\}.$$
1362 \subsubsection{Indexing expressions}
1364 If the primary set expression is an indexing expression, the resultant
1365 set is determined as described above in Subsection \ref{indexing}, page
1366 \pageref{indexing}.
1368 \subsubsection{Iterated expressions}
1370 An {\it iterated set expression} is a primary set expression, which has
1371 the following syntactic form:
1373 \medskip
1375 \noindent\hfil
1376 {\tt setof} {\it indexing-expression} {\it integrand}
1378 \medskip
1380 \noindent where {\it indexing-expression} is an indexing expression,
1381 which introduces dummy indices and controls iterating, {\it integrand}
1382 is either a single numeric or symbolic expression or a list of numeric
1383 and symbolic expressions separated by commae and enclosed in
1384 parentheses.
1386 If the integrand is a single numeric or symbolic expression, the
1387 resultant 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$
1390 are dummy indices introduced in the indexing expression, $\Delta$ is
1391 the domain, a set of $n$-tuples specified by the indexing expression,
1392 which defines particular values assigned to the dummy indices on
1393 performing the iterated operation.
1395 If the integrand is a list containing $m$ numeric and symbolic
1396 expressions, the resultant set consists of $m$-tuples and is determined
1397 as follows:
1398 $$\{(x_1,\dots,x_m):(i_1,\dots,i_n)\in\Delta\},$$
1399 where $x_1$, \dots, $x_m$ are values of the expressions in the
1400 integrand list, $i_1$, \dots, $i_n$ and $\Delta$ have the same meaning
1401 as above.
1403 \subsubsection{Conditional expressions}
1405 A {\it conditional set expression} is a primary set expression that has
1406 the following syntactic form:
1408 \medskip
1410 \noindent\hfil
1411 {\tt if} $b$ {\tt then} $X$ {\tt else} $Y$
1413 \medskip
1415 \noindent where $b$ is an logical expression, $X$ and $Y$ are set
1416 expressions, which must define sets of the same dimension.
1418 The resultant value of the conditional expression depends on the value
1419 of the logical expression that follows the keyword {\tt if}. If it
1420 takes on the value {\it true}, the resultant set is the value of the
1421 expression that follows the keyword {\tt then}. Otherwise, if the
1422 logical expression takes on the value {\it false}, the resultant set is
1423 the value of the expression that follows the keyword {\tt else}.
1425 \subsubsection{Parenthesized expressions}
1427 Any set expression may be enclosed in parentheses that syntactically
1428 makes it a primary set expression.
1430 Parentheses may be used in set expressions, as in algebra, to specify
1431 the desired order in which operations are to be performed. Where
1432 parentheses are used, the expression within the parentheses is
1433 evaluated before the resultant value is used.
1435 The resultant value of the parenthesized expression is the same as the
1436 value of the expression enclosed within parentheses.
1438 \subsubsection{Set operators}
1440 In MathProg there exist the following set operators, which may be used
1441 in set expressions:
1443 \medskip
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}
1453 \medskip
1455 \noindent where $X$ and Y are set expressions, which must define sets
1456 of the identical dimension (except the Cartesian product).
1458 If the expression includes more than one set operator, all operators
1459 are performed from left to right according to the hierarchy of
1460 operations (see below).
1462 The resultant value of the expression, which contains set operators, is
1463 the result of applying the operators to their operands.
1465 The dimension of the resultant set, i.e. the dimension of $n$-tuples,
1466 of which the resultant set consists of, is the same as the dimension of
1467 the operands, except the Cartesian product, where the dimension of the
1468 resultant set is the sum of the dimensions of its operands.
1470 \subsubsection{Hierarchy of operations}
1472 The following list shows the hierarchy of operations in set
1473 expressions:
1475 \medskip
1477 \noindent\hfil
1478 \begin{tabular}{@{}ll@{}}
1479 Operation&Hierarchy\\
1480 \hline
1481 Evaluation of numeric operations&1st-7th\\
1482 Evaluation of symbolic operations&8th-9th\\
1483 Evaluation of iterated or ``arithmetic'' set ({\tt setof}, {\tt..})&
1484 10th\\
1485 Cartesian product ({\tt cross})&11th\\
1486 Intersection ({\tt inter})&12th\\
1487 Union and difference ({\tt union}, {\tt diff}, {\tt symdiff})&13th\\
1488 Conditional evaluation ({\tt if} \dots {\tt then} \dots {\tt else})&
1489 14th\\
1490 \end{tabular}
1492 \medskip
1494 This hierarchy has the same meaning as was explained above for numeric
1495 expressions (see Subsection \ref{hierarchy}, page \pageref{hierarchy}).
1497 \subsection{Logical expressions}
1499 A {\it logical expression} is a rule for computing a single logical
1500 value, which can be either {\it true} or {\it false}.
1502 The primary logical expression may be a numeric expression, relational
1503 expression, iterated logical expression, or another logical expression
1504 enclosed in parentheses.
1506 \medskip
1508 \noindent{\bf Examples}
1510 \medskip
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}
1523 \medskip
1525 More general logical expressions containing two or more primary logical
1526 expressions may be constructed by using certain logical operators.
1528 \newpage
1530 \noindent{\bf Examples}
1532 \medskip
1534 \noindent\verb|not (a[i,j] < 1.5 or b[i] >= a[i,j]) and (i,j) in S|
1536 \noindent\verb|(i,j) in S or (i,j) not in T diff U|
1538 \subsubsection{Numeric expressions}
1540 The resultant value of the primary logical expression, which is a
1541 numeric expression, is {\it true}, if the resultant value of the
1542 numeric expression is non-zero. Otherwise the resultant value of the
1543 logical expression is {\it false}.
1545 \subsubsection{Relational operators}
1547 In MathProg there exist the following relational operators, which may
1548 be used in logical expressions:
1550 \medskip
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}
1571 \medskip
1573 \noindent where $x$, $x_1$, \dots, $x_n$, $y$ are numeric or symbolic
1574 expressions, $X$ and $Y$ are set expression.
1576 {\it Notes:}
1578 1. In the operations {\tt in}, {\tt not in}, and {\tt !in} the
1579 number of components in the first operands must be the same as the
1580 dimension of the second operand.
1582 2. In the operations {\tt within}, {\tt not within}, and {\tt !within}
1583 both operands must have identical dimension.
1585 All the relational operators listed above have their conventional
1586 mathematical meaning. The resultant value is {\it true}, if
1587 corresponding relation is satisfied for its operands, otherwise
1588 {\it false}. (Note that symbolic values are ordered lexicographically,
1589 and any numeric value precedes any symbolic value.)
1591 \subsubsection{Iterated expressions}
1593 An {\it iterated logical expression} is a primary logical expression,
1594 which has the following syntactic form:
1596 \medskip
1598 \noindent\hfil
1599 {\it iterated-operator} {\it indexing-expression} {\it integrand}
1601 \medskip
1603 \noindent where {\it iterated-operator} is the symbolic name of the
1604 iterated operator to be performed (see below), {\it indexing-expression}
1605 is an indexing expression which introduces dummy indices and controls
1606 iterating, {\it integrand} is a numeric expression that participates in
1607 the operation.
1609 In MathProg there exist two iterated operators, which may be used in
1610 logical expressions:
1612 \medskip
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}
1622 \medskip
1624 \noindent where $i_1$, \dots, $i_n$ are dummy indices introduced in
1625 the indexing expression, $\Delta$ is the domain, a set of $n$-tuples
1626 specified by the indexing expression which defines particular values
1627 assigned to the dummy indices on performing the iterated operation,
1628 $f(i_1,\dots,i_n)$ is the integrand, a logical expression whose
1629 resultant value depends on the dummy indices.
1631 For $\forall$-quantification the resultant value of the iterated
1632 logical 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}.
1636 For $\exists$-quantification the resultant value of the iterated
1637 logical 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}.
1641 \subsubsection{Parenthesized expressions}
1643 Any logical expression may be enclosed in parentheses that
1644 syntactically makes it a primary logical expression.
1646 Parentheses may be used in logical expressions, as in algebra, to
1647 specify the desired order in which operations are to be performed.
1648 Where parentheses are used, the expression within the parentheses is
1649 evaluated before the resultant value is used.
1651 The resultant value of the parenthesized expression is the same as the
1652 value of the expression enclosed within parentheses.
1654 \subsubsection{Logical operators}
1656 In MathProg there exist the following logical operators, which may be
1657 used in logical expressions:
1659 \medskip
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}
1669 \medskip
1671 \noindent where $x$ and $y$ are logical expressions.
1673 If the expression includes more than one logical operator, all
1674 operators are performed from left to right according to the hierarchy
1675 of the operations (see below). The resultant value of the expression,
1676 which contains logical operators, is the result of applying the
1677 operators to their operands.
1679 \subsubsection{Hierarchy of operations}
1681 The following list shows the hierarchy of operations in logical
1682 expressions:
1684 \medskip
1686 \noindent\hfil
1687 \begin{tabular}{@{}ll@{}}
1688 Operation&Hierarchy\\
1689 \hline
1690 Evaluation of numeric operations&1st-7th\\
1691 Evaluation of symbolic operations&8th-9th\\
1692 Evaluation of set operations&10th-14th\\
1693 Relational operations ({\tt<}, {\tt<=}, etc.)&15th\\
1694 Negation ({\tt not}, {\tt!})&16th\\
1695 Conjunction ({\tt and}, {\tt\&\&})&17th\\
1696 $\forall$- and $\exists$-quantification ({\tt forall}, {\tt exists})&
1697 18th\\
1698 Disjunction ({\tt or}, {\tt||})&19th\\
1699 \end{tabular}
1701 \medskip
1703 This hierarchy has the same meaning as was explained above for numeric
1704 expressions (see Subsection \ref{hierarchy}, page \pageref{hierarchy}).
1706 \subsection{Linear expressions}
1708 An {\it linear expression} is a rule for computing so called
1709 a {\it linear form} or simply a {\it formula}, which is a linear (or
1710 affine) function of elemental variables.
1712 The primary linear expression may be an unsubscripted variable,
1713 subscripted variable, iterated linear expression, conditional linear
1714 expression, or another linear expression enclosed in parentheses.
1716 It is also allowed to use a numeric expression as the primary linear
1717 expression, in which case the resultant value of the numeric expression
1718 is automatically converted to a formula that includes the constant term
1719 only.
1721 \medskip
1723 \noindent{\bf Examples}
1725 \medskip
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}
1736 \medskip
1738 More general linear expressions containing two or more primary linear
1739 expressions may be constructed by using certain arithmetic operators.
1741 \medskip
1743 \noindent{\bf Examples}
1745 \medskip
1747 \noindent\verb|2 * x[i-1,j+1] + 3.5 * y[k] + .5 * z|
1749 \noindent\verb|(- x[i,j] + 3.5 * y[k]) / sum{t in T} abs(d[i,j,t])|
1751 \subsubsection{Unsubscripted variables}
1753 If the primary linear expression is an unsubscripted variable (which
1754 must be 0-dimensional), the resultant formula is that unsubscripted
1755 variable.
1757 \subsubsection{Subscripted variables}
1759 The primary linear expression, which refers to a subscripted variable,
1760 has the following syntactic form:
1762 \medskip
1764 \noindent\hfil
1765 {\it name}{\tt[}$i_1${\tt,} $i_2${\tt,} \dots{\tt,} $i_n${\tt]}
1767 \medskip
1769 \noindent where {\it name} is the symbolic name of the model variable,
1770 $i_1$, $i_2$, \dots, $i_n$ are subscripts.
1772 Each subscript must be a numeric or symbolic expression. The number of
1773 subscripts in the subscript list must be the same as the dimension of
1774 the model variable with which the subscript list is associated.
1776 Actual values of the subscript expressions are used to identify a
1777 particular member of the model variable that determines the resultant
1778 formula, which is an elemental variable associated with corresponding
1779 member.
1781 \subsubsection{Iterated expressions}
1783 An {\it iterated linear expression} is a primary linear expression,
1784 which has the following syntactic form:
1786 \medskip
1788 \noindent\hfil
1789 {\tt sum} {\it indexing-expression} {\it integrand}
1791 \medskip
1793 \noindent where {\it indexing-expression} is an indexing expression,
1794 which introduces dummy indices and controls iterating, {\it integrand}
1795 is a linear expression that participates in the operation.
1797 The iterated linear expression is evaluated exactly in the same way as
1798 the iterated numeric expression (see Subection \ref{itexpr}, page
1799 \pageref{itexpr}) with exception that the integrand participated in the
1800 summation is a formula, not a numeric value.
1802 \subsubsection{Conditional expressions}
1804 A {\it conditional linear expression} is a primary linear expression,
1805 which has one of the following two syntactic forms:
1807 \medskip
1809 \noindent\hfil
1810 {\tt if} $b$ {\tt then} $f$ {\tt else} $g$
1812 \medskip
1814 \noindent\hspace{127pt}
1815 {\tt if} $b$ {\tt then} $f$
1817 \medskip
1819 \noindent where $b$ is an logical expression, $f$ and $g$ are linear
1820 expressions.
1822 The conditional linear expression is evaluated exactly in the same way
1823 as the conditional numeric expression (see Subsection \ref{ifthen},
1824 page \pageref{ifthen}) with exception that operands participated in the
1825 operation are formulae, not numeric values.
1827 \subsubsection{Parenthesized expressions}
1829 Any linear expression may be enclosed in parentheses that syntactically
1830 makes it a primary linear expression.
1832 Parentheses may be used in linear expressions, as in algebra, to
1833 specify the desired order in which operations are to be performed.
1834 Where parentheses are used, the expression within the parentheses is
1835 evaluated before the resultant formula is used.
1837 The resultant value of the parenthesized expression is the same as the
1838 value of the expression enclosed within parentheses.
1840 \subsubsection{Arithmetic operators}
1842 In MathProg there exists the following arithmetic operators, which may
1843 be used in linear expressions:
1845 \medskip
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}
1856 \medskip
1858 \noindent where $f$ and $g$ are linear expressions, $x$ is a numeric
1859 expression (more precisely, a linear expression containing only the
1860 constant term).
1862 If the expression includes more than one arithmetic operator, all
1863 operators are performed from left to right according to the hierarchy
1864 of operations (see below). The resultant value of the expression, which
1865 contains arithmetic operators, is the result of applying the operators
1866 to their operands.
1868 \subsubsection{Hierarchy of operations}
1870 The hierarchy of arithmetic operations used in linear expressions is
1871 the same as for numeric expressions (see Subsection \ref{hierarchy},
1872 page \pageref{hierarchy}).
1874 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
1876 \newpage
1878 \section{Statements}
1880 {\it Statements} are basic units of the model description. In MathProg
1881 all statements are divided into two categories: declaration statements
1882 and functional statements.
1884 {\it Declaration statements} (set statement, parameter statement,
1885 variable statement, constraint statement, and objective statement) are
1886 used to declare model objects of certain kinds and define certain
1887 properties of such objects.
1889 {\it Functional statements} (solve statement, check statement, display
1890 statement, printf statement, loop statement) are intended for
1891 performing some specific actions.
1893 Note that declaration statements may follow in arbitrary order, which
1894 does not affect the result of translation. However, any model object
1895 must be declared before it is referenced in other statements.
1897 \subsection{Set statement}
1899 \medskip
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 }}
1907 \setlength{\leftmargini}{60pt}
1909 \begin{description}
1910 \item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
1911 set;
1912 \item[\hspace*{54pt}] {\it alias} is an optional string literal, which
1913 specifies an alias of the set;
1914 \item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
1915 which specifies a subscript domain of the set;
1916 \item[\hspace*{54pt}] {\it attrib}, \dots, {\it attrib} are optional
1917 attributes of the set. (Commae preceding attributes may be omitted.)
1918 \end{description}
1920 \noindent Optional attributes:
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}\\
1926 specifies 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}\\
1929 specifies an elemental set assigned to the set or its members;
1930 \item[{\tt default} {\it expression}]\hspace*{0pt}\\
1931 specifies an elemental set assigned to the set or its members whenever
1932 no appropriate data are available in the data section.
1933 \end{description}
1935 \newpage
1937 \noindent{\bf Examples}
1939 \begin{verbatim}
1940 set V;
1941 set E within V cross V;
1942 set 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);
1945 set 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}
1949 The set statement declares a set. If the subscript domain is not
1950 specified, the set is a simple set, otherwise it is an array of
1951 elemental sets.
1953 The {\tt dimen} attribute specifies the dimension of $n$-tuples, which
1954 the set (if it is a simple set) or its members (if the set is an array
1955 of elemental sets) consist of, where $n$ must be unsigned integer from
1956 1 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,
1959 if there is a set expression that follows {\tt:=} or the keyword
1960 {\tt default}, the dimension of $n$-tuples of corresponding elemental
1961 set is used). If no dimension information is available, {\tt dimen 1}
1962 is assumed.
1964 The {\tt within} attribute specifies a set expression whose resultant
1965 value is a superset used to restrict the set (if it is a simple set) or
1966 its members (if the set is an array of elemental sets) to be within
1967 that superset. Arbitrary number of {\tt within} attributes may be
1968 specified in the same set statement.
1970 The assign ({\tt:=}) attribute specifies a set expression used to
1971 evaluate elemental set(s) assigned to the set (if it is a simple set)
1972 or its members (if the set is an array of elemental sets). If the
1973 assign attribute is specified, the set is {\it computable} and
1974 therefore needs no data to be provided in the data section. If the
1975 assign attribute is not specified, the set must be provided with data
1976 in the data section. At most one assign or default attribute can be
1977 specified for the same set.
1979 The {\tt default} attribute specifies a set expression used to evaluate
1980 elemental set(s) assigned to the set (if it is a simple set) or its
1981 members (if the set is an array of elemental sets) whenever
1982 no appropriate data are available in the data section. If neither
1983 assign nor default attribute is specified, missing data will cause an
1984 error.
1986 \subsection{Parameter statement}
1988 \medskip
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 }}
1996 \setlength{\leftmargini}{60pt}
1998 \begin{description}
1999 \item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2000 parameter;
2001 \item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2002 specifies an alias of the parameter;
2003 \item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
2004 which specifies a subscript domain of the parameter;
2005 \item[\hspace*{54pt}] {\it attrib}, \dots, {\it attrib} are optional
2006 attributes of the parameter. (Commae preceding attributes may be
2007 omitted.)
2008 \end{description}
2010 \noindent Optional attributes:
2012 \begin{description}
2013 \item[{\tt integer}\hspace*{18.5pt}] specifies that the parameter is
2014 integer;
2015 \item[{\tt binary}\hspace*{24pt}] specifies that the parameter is
2016 binary;
2017 \item[{\tt symbolic}\hspace*{13.5pt}] specifies that the parameter is
2018 symbolic;
2019 \item[{\it relation expression}]\hspace*{0pt}\\
2020 (where {\it relation} is one of: {\tt<}, {\tt<=}, {\tt=}, {\tt==},
2021 {\tt>=}, {\tt>}, {\tt<>}, {\tt!=})\\
2022 specifies a condition that restricts the parameter or its members to
2023 satisfy that condition;
2024 \item[{\tt in} {\it expression}]\hspace*{0pt}\\
2025 specifies a superset that restricts the parameter or its members to be
2026 in that superset;
2027 \item[{\tt:=} {\it expression}]\hspace*{0pt}\\
2028 specifies a value assigned to the parameter or its members;
2029 \item[{\tt default} {\it expression}]\hspace*{0pt}\\
2030 specifies a value assigned to the parameter or its members whenever
2031 no appropriate data are available in the data section.
2032 \end{description}
2034 \noindent{\bf Examples}
2036 \begin{verbatim}
2037 param units{raw, prd} >= 0;
2038 param profit{prd, 1..T+1};
2039 param N := 20, integer, >= 0, <= 100;
2040 param 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];
2042 param 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);
2044 param month symbolic default 'May' in {'Mar', 'Apr', 'May'};
2045 \end{verbatim}
2047 The parameter statement declares a parameter. If a subscript domain is
2048 not specified, the parameter is a simple (scalar) parameter, otherwise
2049 it is a $n$-dimensional array.
2051 The type attributes {\tt integer}, {\tt binary}, and {\tt symbolic}
2052 qualify the type of values that can be assigned to the parameter as
2053 shown below:
2055 \medskip
2057 \noindent\hfil
2058 \begin{tabular}{@{}ll@{}}
2059 Type 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}
2067 \newpage
2069 The {\tt symbolic} attribute cannot be specified along with other type
2070 attributes. Being specified it must precede all other attributes.
2072 The condition attribute specifies an optional condition that restricts
2073 values assigned to the parameter to satisfy that condition. This
2074 attribute has the following syntactic forms:
2076 \medskip
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}
2087 \medskip
2089 \noindent where $x$ is a value assigned to the parameter, $v$ is the
2090 resultant value of a numeric or symbolic expression specified in the
2091 condition attribute. Arbitrary number of condition attributes can be
2092 specified for the same parameter. If a value being assigned to the
2093 parameter during model evaluation violates at least one of specified
2094 conditions, an error is raised. (Note that symbolic values are ordered
2095 lexicographically, and any numeric value precedes any symbolic value.)
2097 The {\tt in} attribute is similar to the condition attribute and
2098 specifies a set expression whose resultant value is a superset used to
2099 restrict numeric or symbolic values assigned to the parameter to be in
2100 that superset. Arbitrary number of the {\tt in} attributes can be
2101 specified for the same parameter. If a value being assigned to the
2102 parameter during model evaluation is not in at least one of specified
2103 supersets, an error is raised.
2105 The assign ({\tt:=}) attribute specifies a numeric or symbolic
2106 expression used to compute a value assigned to the parameter (if it is
2107 a simple parameter) or its member (if the parameter is an array). If
2108 the assign attribute is specified, the parameter is {\it computable}
2109 and therefore needs no data to be provided in the data section. If the
2110 assign attribute is not specified, the parameter must be provided with
2111 data in the data section. At most one assign or {\tt default} attribute
2112 can be specified for the same parameter.
2114 The {\tt default} attribute specifies a numeric or symbolic expression
2115 used to compute a value assigned to the parameter or its member
2116 whenever no appropriate data are available in the data section. If
2117 neither assign nor {\tt default} attribute is specified, missing data
2118 will cause an error.
2120 \subsection{Variable statement}
2122 \medskip
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 }}
2130 \setlength{\leftmargini}{60pt}
2132 \begin{description}
2133 \item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2134 variable;
2135 \item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2136 specifies an alias of the variable;
2137 \item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
2138 which specifies a subscript domain of the variable;
2139 \item[\hspace*{54pt}] {\it attrib}, \dots, {\it attrib} are optional
2140 attributes of the variable. (Commae preceding attributes may be
2141 omitted.)
2142 \end{description}
2144 \noindent Optional attributes:
2146 \begin{description}
2147 \item[{\tt integer}\hspace*{18.5pt}] restricts the variable to be
2148 integer;
2149 \item[{\tt binary}\hspace*{24pt}] restricts the variable to be binary;
2150 \item[{\tt>=} {\it expression}]\hspace*{0pt}\\
2151 specifies an lower bound of the variable;
2152 \item[{\tt<=} {\it expression}]\hspace*{0pt}\\
2153 specifies an upper bound of the variable;
2154 \item[{\tt=} {\it expression}]\hspace*{0pt}\\
2155 specifies a fixed value of the variable;
2156 \end{description}
2158 \noindent{\bf Examples}
2160 \begin{verbatim}
2161 var x >= 0;
2162 var y{I,J};
2163 var make{p in prd}, integer, >= commit[p], <= market[p];
2164 var store{raw, 1..T+1} >= 0;
2165 var z{i in I, j in J} >= i+j;
2166 \end{verbatim}
2168 The variable statement declares a variable. If a subscript domain is
2169 not specified, the variable is a simple (scalar) variable, otherwise it
2170 is a $n$-dimensional array of elemental variables.
2172 Elemental variable(s) associated with the model variable (if it is a
2173 simple variable) or its members (if it is an array) correspond to the
2174 variables in the LP/MIP problem formulation (see Subsection
2175 \ref{problem}, page \pageref{problem}). Note that only elemental
2176 variables actually referenced in some constraints and/or objectives are
2177 included in the LP/MIP problem instance to be generated.
2179 The type attributes {\tt integer} and {\tt binary} restrict the
2180 variable to be integer or binary, respectively. If no type attribute is
2181 specified, the variable is continuous. If all variables in the model
2182 are continuous, the corresponding problem is of LP class. If there is
2183 at least one integer or binary variable, the problem is of MIP class.
2185 The lower bound ({\tt>=}) attribute specifies a numeric expression for
2186 computing an lower bound of the variable. At most one lower bound can
2187 be specified. By default all variables (except binary ones) have no
2188 lower bound, so if a variable is required to be non-negative, its zero
2189 lower bound should be explicitly specified.
2191 The upper bound ({\tt<=}) attribute specifies a numeric expression for
2192 computing an upper bound of the variable. At most one upper bound
2193 attribute can be specified.
2195 The fixed value ({\tt=}) attribute specifies a numeric expression for
2196 computing a value, at which the variable is fixed. This attribute
2197 cannot be specified along with the bound attributes.
2199 \subsection{Constraint statement}
2201 \medskip
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;}
2208 \medskip
2210 \hspace{6pt} {\tt s.t.} {\it name} {\it alias} {\it domain} {\tt:}
2211 {\it expression} {\tt,} {\tt<=} {\it expression} {\tt;}
2213 \medskip
2215 \hspace{6pt} {\tt s.t.} {\it name} {\it alias} {\it domain} {\tt:}
2216 {\it expression} {\tt,} {\tt>=} {\it expression} {\tt;}
2218 \medskip
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;}
2224 \medskip
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 }}
2231 \setlength{\leftmargini}{60pt}
2233 \begin{description}
2234 \item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2235 constraint;
2236 \item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2237 specifies an alias of the constraint;
2238 \item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
2239 which specifies a subscript domain of the constraint;
2240 \item[\hspace*{54pt}] {\it expression} is a linear expression used to
2241 compute a component of the constraint. (Commae following expressions
2242 may be omitted.)
2243 \end{description}
2245 \begin{description}
2246 \item[{\rm Note:}\hspace*{31pt}] The keyword {\tt s.t.} may be written
2247 as {\tt subject to} or as {\tt subj to}, or may be omitted at all.
2248 \end{description}
2250 \noindent{\bf Examples}
2252 \begin{verbatim}
2253 s.t. r: x + y + z, >= 0, <= 1;
2254 limit{t in 1..T}: sum{j in prd} make[j,t] <= max_prd;
2255 subject 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];
2257 subject to rlim 'regular-time limit' {t in time}:
2258 sum{p in prd} pt[p] * rprd[p,t] <= 1.3 * dpp[t] * crews[t];
2259 \end{verbatim}
2261 The constraint statement declares a constraint. If a subscript domain
2262 is not specified, the constraint is a simple (scalar) constraint,
2263 otherwise it is a $n$-dimensional array of elemental constraints.
2265 Elemental constraint(s) associated with the model constraint (if it is
2266 a simple constraint) or its members (if it is an array) correspond to
2267 the linear constraints in the LP/MIP problem formulation (see
2268 Subsection \ref{problem}, page \pageref{problem}).
2270 If the constraint has the form of equality or single inequality, i.e.
2271 includes two expressions, one of which follows the colon and other
2272 follows the relation sign {\tt=}, {\tt<=}, or {\tt>=}, both expressions
2273 in the statement can be linear expressions. If the constraint has the
2274 form of double inequality, i.e. includes three expressions, the middle
2275 expression can be a linear expression while the leftmost and rightmost
2276 ones can be only numeric expressions.
2278 Generating the model is, roughly speaking, generating its constraints,
2279 which are always evaluated for the entire subscript domain. Evaluation
2280 of the constraints leads, in turn, to evaluation of other model objects
2281 such as sets, parameters, and variables.
2283 Constructing an actual linear constraint included in the problem
2284 instance, which (constraint) corresponds to a particular elemental
2285 constraint, is performed as follows.
2287 If the constraint has the form of equality or single inequality,
2288 evaluation of both linear expressions gives two resultant linear forms:
2289 $$\begin{array}{r@{\ }c@{\ }r@{\ }c@{\ }r@{\ }c@{\ }r@{\ }c@{\ }r}
2290 f&=&a_1x_1&+&a_2x_2&+\dots+&a_nx_n&+&a_0,\\
2291 g&=&b_1x_1&+&a_2x_2&+\dots+&a_nx_n&+&b_0,\\
2292 \end{array}$$
2293 where $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
2297 carried to the right-hand side, that gives the final elemental
2298 constraint 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.$$
2302 If the constraint has the form of double inequality, evaluation of the
2303 middle linear expression gives the resultant linear form:
2304 $$f=a_1x_1+a_2x_2+\dots+a_nx_n+a_0,$$
2305 and evaluation of the leftmost and rightmost numeric expressions gives
2306 two numeric values $l$ and $u$, respectively. Then the constant term of
2307 the linear form is carried to both left-hand and right-handsides that
2308 gives 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.$$
2311 \subsection{Objective statement}
2313 \medskip
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;}
2320 \medskip
2322 \hspace{6pt} {\tt maximize} {\it name} {\it alias} {\it domain} {\tt:}
2323 {\it expression} {\tt;}
2324 }}
2326 \setlength{\leftmargini}{60pt}
2328 \begin{description}
2329 \item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2330 objective;
2331 \item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2332 specifies an alias of the objective;
2333 \item[\hspace*{54pt}] {\it domain} is an optional indexing expression,
2334 which specifies a subscript domain of the objective;
2335 \item[\hspace*{54pt}] {\it expression} is a linear expression used to
2336 compute the linear form of the objective.
2337 \end{description}
2339 \noindent{\bf Examples}
2341 \begin{verbatim}
2342 minimize obj: x + 1.5 * (y + z);
2343 maximize total_profit: sum{p in prd} profit[p] * make[p];
2344 \end{verbatim}
2346 The objective statement declares an objective. If a subscript domain is
2347 not specified, the objective is a simple (scalar) objective. Otherwise
2348 it is a $n$-dimensional array of elemental objectives.
2350 Elemental objective(s) associated with the model objective (if it is a
2351 simple objective) or its members (if it is an array) correspond to
2352 general linear constraints in the LP/MIP problem formulation (see
2353 Subsection \ref{problem}, page \pageref{problem}). However, unlike
2354 constraints the corresponding linear forms are free (unbounded).
2356 Constructing an actual linear constraint included in the problem
2357 instance, which (constraint) corresponds to a particular elemental
2358 constraint, is performed as follows. The linear expression specified in
2359 the objective statement is evaluated that, gives the resultant linear
2360 form:
2361 $$f=a_1x_1+a_2x_2+\dots+a_nx_n+a_0,$$
2362 where $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
2364 the linear form is used to construct the final elemental constraint in
2365 the standard form:
2366 $$-\infty<a_1x_1+a_2x_2+\dots+a_nx_n+a_0<+\infty.$$
2368 As a rule the model description contains only one objective statement
2369 that defines the objective function used in the problem instance.
2370 However, it is allowed to declare arbitrary number of objectives, in
2371 which case the actual objective function is the first objective
2372 encountered in the model description. Other objectives are also
2373 included in the problem instance, but they do not affect the objective
2374 function.
2376 \subsection{Solve statement}
2378 \medskip
2380 \framebox[345pt][l]{
2381 \parbox[c][24pt]{345pt}{
2382 \hspace{6pt} {\tt solve} {\tt;}
2383 }}
2385 \setlength{\leftmargini}{60pt}
2387 \begin{description}
2388 \item[{\rm Note:}\hspace*{31pt}] The solve statement is optional and
2389 can be used only once. If no solve statement is used, one is assumed at
2390 the end of the model section.
2391 \end{description}
2393 The solve statement causes the model to be solved, that means computing
2394 numeric values of all model variables. This allows using variables in
2395 statements below the solve statement in the same way as if they were
2396 numeric parameters.
2398 Note that the variable, constraint, and objective statements cannot be
2399 used below the solve statement, i.e. all principal components of the
2400 model must be declared above the solve statement.
2402 \subsection{Check statement}
2404 \medskip
2406 \framebox[345pt][l]{
2407 \parbox[c][24pt]{345pt}{
2408 \hspace{6pt} {\tt check} {\it domain} {\tt:} {\it expression} {\tt;}
2409 }}
2411 \setlength{\leftmargini}{60pt}
2413 \begin{description}
2414 \item[{\rm Where:}\hspace*{23pt}] {\it domain} is an optional indexing
2415 expression, which specifies a subscript domain of the check statement;
2416 \item[\hspace*{54pt}] {\it expression} is an logical expression which
2417 specifies the logical condition to be checked. (The colon preceding
2418 {\it expression} may be omitted.)
2419 \end{description}
2421 \noindent{\bf Examples}
2423 \begin{verbatim}
2424 check: x + y <= 1 and x >= 0 and y >= 0;
2425 check sum{i in ORIG} supply[i] = sum{j in DEST} demand[j];
2426 check{i in I, j in 1..10}: S[i,j] in U[i] union V[j];
2427 \end{verbatim}
2429 The check statement allows checking the resultant value of an logical
2430 expression specified in the statement. If the value is {\it false}, an
2431 error is reported.
2433 If the subscript domain is not specified, the check is performed only
2434 once. Specifying the subscript domain allows performing multiple checks
2435 for every\linebreak $n$-tuple in the domain set. In the latter case the
2436 logical expression may include dummy indices introduced in
2437 corresponding indexing expression.
2439 \subsection{Display statement}
2441 \medskip
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 }}
2449 \setlength{\leftmargini}{60pt}
2451 \begin{description}
2452 \item[{\rm Where:}\hspace*{23pt}] {\it domain} is an optional indexing
2453 expression, which specifies a subscript domain of the check statement;
2454 \item[\hspace*{54pt}] {\it item}, \dots, {\it item} are items to be
2455 displayed. (The colon preceding the first item may be omitted.)
2456 \end{description}
2458 \noindent{\bf Examples}
2460 \begin{verbatim}
2461 display: 'x =', x, 'y =', y, 'z =', z;
2462 display sqrt(x ** 2 + y ** 2 + z ** 2);
2463 display{i in I, j in J}: i, j, a[i,j], b[i,j];
2464 \end{verbatim}
2466 \newpage
2468 The display statement evaluates all items specified in the statement
2469 and writes their values to the terminal in plain text format.
2471 If a subscript domain is not specified, items are evaluated and then
2472 displayed only once. Specifying the subscript domain causes items to be
2473 evaluated and displayed for every $n$-tuple in the domain set. In the
2474 latter case items may include dummy indices introduced in corresponding
2475 indexing expression.
2477 An item to be displayed can be a model object (set, parameter, variable,
2478 constraint, objective) or an expression.
2480 If the item is a computable object (i.e. a set or parameter provided
2481 with the assign attribute), the object is evaluated over the entire
2482 domain and then its content (i.e. the content of the object array) is
2483 displayed. Otherwise, if the item is not a computable object, only its
2484 current content (i.e. members actually generated during the model
2485 evaluation) is displayed.
2487 If the item is an expression, the expression is evaluated and its
2488 resultant value is displayed.
2490 \subsection{Printf statement}
2492 \medskip
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;}
2499 \medskip
2501 \hspace{6pt} {\tt printf} {\it domain} {\tt:} {\it format} {\tt,}
2502 {\it expression} {\tt,} \dots {\tt,} {\it expression} {\tt>}
2503 {\it filename} {\tt;}
2505 \medskip
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 }}
2512 \setlength{\leftmargini}{60pt}
2514 \begin{description}
2515 \item[{\rm Where:}\hspace*{23pt}] {\it domain} is an optional indexing
2516 expression, which specifies a subscript domain of the printf statement;
2517 \item[\hspace*{54pt}] {\it format} is a symbolic expression whose value
2518 specifies a format control string. (The colon preceding the format
2519 expression may be omitted.)
2520 \item[\hspace*{54pt}] {\it expression}, \dots, {\it expression} are
2521 zero or more expressions whose values have to be formatted and printed.
2522 Each expression must be of numeric, symbolic, or logical type.
2523 \item[\hspace*{54pt}] {\it filename} is a symbolic expression whose
2524 value specifies a name of a text file, to which the output is
2525 redirected. The flag {\tt>} means creating a new empty file while the
2526 flag {\tt>>} means appending the output to an existing file. If no file
2527 name is specified, the output is written to the terminal.
2528 \end{description}
2530 \noindent{\bf Examples}
2532 \begin{verbatim}
2533 printf 'Hello, world!\n';
2534 printf: "x = %.3f; y = %.3f; z = %.3f\n",
2535 x, y, z > "result.txt";
2536 printf{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}
2540 \newpage
2542 \begin{verbatim}
2543 printf{i in I} 'total flow from %s is %g\n',
2544 i, sum{j in J} x[i,j];
2545 printf{k in K} "x[%s] = " & (if x[k] < 0 then "?" else "%g"),
2546 k, x[k];
2547 \end{verbatim}
2549 The printf statement is similar to the display statement, however, it
2550 allows formatting data to be written.
2552 If a subscript domain is not specified, the printf statement is
2553 executed only once. Specifying a subscript domain causes executing the
2554 printf statement for every $n$-tuple in the domain set. In the latter
2555 case the format and expression may include dummy indices introduced in
2556 corresponding indexing expression.
2558 The format control string is a value of the symbolic expression
2559 {\it format} specified in the printf statement. It is composed of zero
2560 or more directives as follows: ordinary characters (not {\tt\%}), which
2561 are copied unchanged to the output stream, and conversion
2562 specifications, each of which causes evaluating corresponding
2563 expression specified in the printf statement, formatting it, and
2564 writing its resultant value to the output stream.
2566 Conversion specifications that may be used in the format control string
2567 are 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
2569 syntax and semantics as in the C programming language.
2571 \subsection{For statement}
2573 \medskip
2575 \framebox[345pt][l]{
2576 \parbox[c][44pt]{345pt}{
2577 \hspace{6pt} {\tt for} {\it domain} {\tt:} {\it statement} {\tt;}
2579 \medskip
2581 \hspace{6pt} {\tt for} {\it domain} {\tt:} {\tt\{} {\it statement}
2582 \dots {\it statement} {\tt\}} {\tt;}
2583 }}
2585 \setlength{\leftmargini}{60pt}
2587 \begin{description}
2588 \item[{\rm Where:}\hspace*{23pt}] {\it domain} is an indexing
2589 expression 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
2592 executed under control of the for statement;
2593 \item[\hspace*{54pt}] {\it statement}, \dots, {\it statement} is a
2594 sequence of statements (enclosed in curly braces), which should be
2595 executed under control of the for statement.
2596 \end{description}
2598 \begin{description}
2599 \item[{\rm Note:}\hspace*{31pt}] Only the following statements can be
2600 used within the for statement: check, display, printf, and another for.
2601 \end{description}
2603 \noindent{\bf Examples}
2605 \begin{verbatim}
2606 for {(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}
2612 \newpage
2614 \begin{verbatim}
2615 for {i in 1..n}
2616 { for {j in 1..n} printf " %s", if x[i,j] then "Q" else ".";
2617 printf("\n");
2618 }
2619 for {1..72} printf("*");
2620 \end{verbatim}
2622 The for statement causes a statement or a sequence of statements
2623 specified as part of the for statement to be executed for every
2624 $n$-tuple in the domain set. Thus, statements within the for statement
2625 may include dummy indices introduced in corresponding indexing
2626 expression.
2628 \subsection{Table statement}
2630 \medskip
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:}
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;}
2642 \medskip
2644 \hspace{6pt} {\tt table} {\it name} {\it alias} {\it domain} {\tt OUT}
2645 {\it driver} {\it arg} \dots {\it arg} {\tt:}
2647 \hspace{6pt} {\tt\ \ \ \ \ } {\it expr} {\tt\textasciitilde} {\it fld}
2648 {\tt,} \dots {\tt,} {\it expr} {\tt\textasciitilde} {\it fld} {\tt;}
2649 }}
2651 \setlength{\leftmargini}{60pt}
2653 \begin{description}
2654 \item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2655 table;
2656 \item[\hspace*{54pt}] {\it alias} is an optional string literal, which
2657 specifies an alias of the table;
2658 \item[\hspace*{54pt}] {\it domain} is an indexing expression, which
2659 specifies 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
2663 specifies 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,
2666 which is an argument pass\-ed to the table driver. This symbolic
2667 expression must not include dummy indices specified in the domain;
2668 \item[\hspace*{54pt}] {\it set} is the name of an optional simple set
2669 called {\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
2672 at least one field should be specified. The field name following
2673 a parameter name or expression is optional and can be omitted along
2674 with the delimiter {\tt\textasciitilde}, in which case the name of
2675 corresponding 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}
2680 \newpage
2682 \noindent{\bf Examples}
2684 \begin{verbatim}
2685 table data IN "CSV" "data.csv":
2686 S <- [FROM,TO], d~DISTANCE, c~COST;
2687 table result{(f,t) in S} OUT "CSV" "result.csv":
2688 f~FROM, t~TO, x[f,t]~FLOW;
2689 \end{verbatim}
2691 The table statement allows reading data from a table into model
2692 objects such as sets and (non-scalar) parameters as well as writing
2693 data from the model to a table.
2695 \subsubsection{Table structure}
2697 A {\it data table} is an (unordered) set of {\it records}, where each
2698 record consists of the same number of {\it fields}, and each field is
2699 provided with a unique symbolic name called the {\it field name}. For
2700 example:
2702 \bigskip
2704 \begin{tabular}{@{\hspace*{38mm}}c@{\hspace*{11mm}}c@{\hspace*{10mm}}c
2705 @{\hspace*{9mm}}c}
2706 First&Second&&Last\\
2707 field&field&.\ \ .\ \ .&field\\
2708 $\downarrow$&$\downarrow$&&$\downarrow$\\
2709 \end{tabular}
2711 \begin{tabular}{ll@{}}
2712 Table header&$\rightarrow$\\
2713 First record&$\rightarrow$\\
2714 Second record&$\rightarrow$\\
2715 \\
2716 \hfil .\ \ .\ \ .\\
2717 \\
2718 Last 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}
2733 \subsubsection{Reading data from input table}
2735 The input table statement causes reading data from the specified table
2736 record by record.
2738 Once a next record has been read, numeric or symbolic values of fields,
2739 whose names are enclosed in square brackets in the table statement, are
2740 gathered into $n$-tuple, and if the control set is specified in the
2741 table statement, this $n$-tuple is added to it. Besides, a numeric or
2742 symbolic value of each field associated with a model parameter is
2743 assigned to the parameter member identified by subscripts, which are
2744 components of the $n$-tuple just read.
2746 For example, the following input table statement:
2748 \medskip
2750 \noindent\hfil
2751 \verb|table data IN "...": S <- [FROM,TO], d~DISTANCE, c~COST;|
2753 \medskip
2755 \noindent
2756 causes reading values of four fields named {\tt FROM}, {\tt TO},
2757 {\tt DISTANCE}, and {\tt COST} from each record of the specified table.
2758 Values of fields {\tt FROM} and {\tt TO} give a pair $(f,t)$, which is
2759 added to the control set {\tt S}. The value of field {\tt DISTANCE} is
2760 assigned to parameter member ${\tt d}[f,t]$, and the value of field
2761 {\tt COST} is assigned to parameter member ${\tt c}[f,t]$.
2763 Note that the input table may contain extra fields whose names are not
2764 specified in the table statement, in which case values of these fields
2765 on reading the table are ignored.
2767 \subsubsection{Writing data to output table}
2769 The output table statement causes writing data to the specified table.
2770 Note that some drivers (namely, CSV and xBASE) destroy the output table
2771 before writing data, i.e. delete all its existing records.
2773 Each $n$-tuple in the specified domain set generates one record written
2774 to the output table. Values of fields are numeric or symbolic values of
2775 corresponding expressions specified in the table statement. These
2776 expressions are evaluated for each $n$-tuple in the domain set and,
2777 thus, may include dummy indices introduced in the corresponding indexing
2778 expression.
2780 For example, the following output table statement:
2782 \medskip
2784 \noindent
2785 \verb| table result{(f,t) in S} OUT "...": f~FROM, t~TO, x[f,t]~FLOW;|
2787 \medskip
2789 \noindent
2790 causes 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
2792 fields named {\tt FROM}, {\tt TO}, and {\tt FLOW}. The values written
2793 to 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
2795 a value of member ${\tt x}[f,t]$ of corresponding subscripted parameter
2796 or variable.
2798 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
2800 \newpage
2802 \section{Model data}
2804 {\it Model data} include elemental sets, which are ``values'' of model
2805 sets, and numeric and symbolic values of model parameters.
2807 In MathProg there are two different ways to saturate model sets and
2808 parameters with data. One way is simply providing necessary data using
2809 the assign attribute. However, in many cases it is more practical to
2810 separate the model itself and particular data needed for the model. For
2811 the latter reason in MathProg there is another way, when the model
2812 description is divided into two parts: model section and data section.
2814 A {\it model section} is a main part of the model description that
2815 contains declarations of all model objects and is common for all
2816 problems based on that model.
2818 A {\it data section} is an optional part of the model description that
2819 contains model data specific for a particular problem.
2821 In MathProg model and data sections can be placed either in one text
2822 file or in two separate text files.
2824 1. If both model and data sections are placed in one file, the file is
2825 composed as follows:
2827 \bigskip
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}}
2843 \bigskip
2845 2. If the model and data sections are placed in two separate files, the
2846 files are composed as follows:
2848 \bigskip
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}
2874 \bigskip
2876 \begin{description}
2877 \item[{\rm Note:}\hspace*{31pt}] If the data section is placed in a
2878 separate file, the keyword {\tt data} is optional and may be omitted
2879 along with the semicolon that follows it.
2880 \end{description}
2882 \subsection{Coding data section}
2884 The {\it data section} is a sequence of data blocks in various formats,
2885 which are discussed in following subsections. The order, in which data
2886 blocks follow in the data section, may be arbitrary, not necessarily
2887 the same, in which corresponding model objects follow in the model
2888 section.
2890 The rules of coding the data section are commonly the same as the rules
2891 of coding the model description (see Subsection \ref{coding}, page
2892 \pageref{coding}), i.e. data blocks are composed from basic lexical
2893 units such as symbolic names, numeric and string literals, keywords,
2894 delimiters, and comments. However, for the sake of convenience and
2895 improving readability there is one deviation from the common rule: if
2896 a string literal consists of only alphanumeric characters (including
2897 the underscore character), the signs {\tt+} and {\tt-}, and/or the
2898 decimal point, it may be coded without bordering by (single or double)
2899 quotes.
2901 All numeric and symbolic material provided in the data section is coded
2902 in the form of numbers and symbols, i.e. unlike the model section
2903 no expressions are allowed in the data section. Nevertheless, the signs
2904 {\tt+} and {\tt-} can precede numeric literals to allow coding signed
2905 numeric quantities, in which case there must be no white-space
2906 characters between the sign and following numeric literal (if there is
2907 at least one white-space, the sign and following numeric literal are
2908 recognized as two different lexical units).
2910 \subsection{Set data block}
2912 \medskip
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;}
2919 \medskip
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 }}
2926 \setlength{\leftmargini}{60pt}
2928 \begin{description}
2929 \item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
2930 set;
2931 \item[\hspace*{54pt}] {\it symbol}, \dots, {\it symbol} are subscripts,
2932 which specify a particular member of the set (if the set is an array,
2933 i.e. a set of sets);
2934 \item[\hspace*{54pt}] {\it record}, \dots, {\it record} are data
2935 records.
2936 \end{description}
2938 \begin{description}
2939 \item[{\rm Note:}\hspace*{31pt}] Commae preceding data records may be
2940 omitted.
2941 \end{description}
2943 \noindent Data records:
2945 \begin{description}
2946 \item[{\tt :=}\hspace*{45pt}] is a non-significant data record, which
2947 may 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
2950 simple format;
2951 \item[{\tt:} {\it matrix-data}]\hspace*{0pt}\\
2952 specifies set data in the matrix format;
2953 \item[{\tt(tr)} {\tt:} {\it matrix-data}]\hspace*{0pt}\\
2954 specifies set data in the transposed matrix format. (In this case the
2955 colon following the keyword {\tt(tr)} may be omitted.)
2956 \end{description}
2958 \noindent{\bf Examples}
2960 \begin{verbatim}
2961 set month := Jan Feb Mar Apr May Jun;
2962 set month "Jan", "Feb", "Mar", "Apr", "May", "Jun";
2963 set A[3,Mar] := (1,2) (2,3) (4,2) (3,1) (2,2) (4,4) (3,4);
2964 set A[3,'Mar'] := 1 2 2 3 4 2 3 1 2 2 4 4 2 4;
2965 set A[3,'Mar'] : 1 2 3 4 :=
2966 1 - + - -
2967 2 - + + -
2968 3 + - - +
2969 4 - + - + ;
2970 set B := (1,2,3) (1,3,2) (2,3,1) (2,1,3) (1,2,2) (1,1,1) (2,1,1);
2971 set B := (*,*,*) 1 2 3, 1 3 2, 2 3 1, 2 1 3, 1 2 2, 1 1 1, 2 1 1;
2972 set B := (1,*,2) 3 2 (2,*,1) 3 1 (1,2,3) (2,1,3) (1,1,1);
2973 set 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}
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
2985 set of triplets. Data blocks for the same set are equivalent in the
2986 sense that they specify the same data in different formats.)
2988 \medskip
2990 The {\it set data block} is used to specify a complete elemental set,
2991 which is assigned to a set (if it is a simple set) or one of its
2992 members (if the set is an array of sets).\footnote{There is another way
2993 to specify data for a simple set along with data for parameters. This
2994 feature is discussed in the next subsection.}
2996 Data blocks can be specified only for non-computable sets, i.e. for
2997 sets, which have no assign ({\tt:=}) attribute in the corresponding set
2998 statements.
3000 If the set is a simple set, only its symbolic name should be specified
3001 in the header of the data block. Otherwise, if the set is a
3002 $n$-dimensional array, its symbolic name should be provided with a
3003 complete list of subscripts separated by commae and enclosed in square
3004 brackets to specify a particular member of the set array. The number of
3005 subscripts must be the same as the dimension of the set array, where
3006 each subscript must be a number or symbol.
3008 An elemental set defined in the set data block is coded as a sequence
3009 of data records described below.\footnote{{\it Data record} is simply a
3010 technical term. It does not mean that data records have any special
3011 formatting.}
3013 \newpage
3015 \subsubsection{Assign data record}
3017 The {\it assign} ({\tt:=}) {\it data record} is a non-signficant
3018 element. It may be used for improving readability of data blocks.
3020 \subsubsection{Slice data record}
3022 The {\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
3024 following syntactic form:
3026 \medskip
3028 \noindent\hfil
3029 {\tt(} $s_1$ {\tt,} $s_2$ {\tt,} \dots {\tt,} $s_n$ {\tt)}
3031 \medskip
3033 \noindent where $s_1$, $s_2$, \dots, $s_n$ are components of the slice.
3035 Each 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
3037 dimension of $n$-tuples in the elemental set to be defined. For
3038 instance, if the elemental set contains 4-tuples (quadruplets), the
3039 slice must have four components. The number of asterisks in the slice
3040 is called the {\it slice dimension}.
3042 The 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
3044 subsequent data records must specify tuples of the dimension $m$.
3045 Whenever a $m$-tuple is encountered, each asterisk in the slice is
3046 replaced by corresponding components of the $m$-tuple that gives the
3047 resultant $n$-tuple, which is included in the elemental set to be
3048 defined. For example, if the slice $(a,*,1,2,*)$ is in effect, and
3049 2-tuple $(3,b)$ is encountered in a subsequent data record, the
3050 resultant 5-tuple included in the elemental set is $(a,3,1,2,b)$.
3052 The slice having no asterisks itself defines a complete $n$-tuple,
3053 which is included in the elemental set.
3055 Being once specified the slice effects until either a new slice or the
3056 end of data block is encountered. Note that if no slice is specified in
3057 the data block, one, components of which are all asterisks, is assumed.
3059 \subsubsection{Simple data record}
3061 The {\it simple data record} defines one $n$-tuple in a simple format
3062 and has the following syntactic form:
3064 \medskip
3066 \noindent\hfil
3067 $t_1$ {\tt,} $t_2$ {\tt,} \dots {\tt,} $t_n$
3069 \medskip
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
3073 components are optional and may be omitted.
3075 \subsubsection{Matrix data record}
3077 The {\it matrix data record} defines several 2-tuples (doublets) in
3078 a matrix format and has the following syntactic form:
3080 \newpage
3082 $$\begin{array}{cccccc}
3083 \mbox{{\tt:}}&c_1&c_2&\dots&c_n&\mbox{{\tt:=}}\\
3084 r_1&a_{11}&a_{12}&\dots&a_{1n}&\\
3085 r_2&a_{21}&a_{22}&\dots&a_{2n}&\\
3086 \multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}&\\
3087 r_m&a_{m1}&a_{m2}&\dots&a_{mn}&\\
3088 \end{array}$$
3089 where $r_1$, $r_2$, \dots, $r_m$ are numbers and/or symbols
3090 corresponding to rows of the matrix; $c_1$, $c_2$, \dots, $c_n$ are
3091 numbers 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
3094 the column list and the delimiter {\tt:=} following the column list
3095 cannot be omitted.)
3097 Each 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
3099 plus sign ({\tt+}), that 2-tuple (or a longer $n$-tuple, if a slice is
3100 used) is included in the elemental set. Otherwise, if $a_{ij}$ is the
3101 minus sign ({\tt-}), that 2-tuple is not included in the elemental set.
3103 Since the matrix data record defines 2-tuples, either the elemental set
3104 must consist of 2-tuples or the slice currently used must be
3105 2-dimensional.
3107 \subsubsection{Transposed matrix data record}
3109 The {\it transposed matrix data record} has the following syntactic
3110 form:
3111 $$\begin{array}{cccccc}
3112 \mbox{{\tt(tr) :}}&c_1&c_2&\dots&c_n&\mbox{{\tt:=}}\\
3113 r_1&a_{11}&a_{12}&\dots&a_{1n}&\\
3114 r_2&a_{21}&a_{22}&\dots&a_{2n}&\\
3115 \multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}&\\
3116 r_m&a_{m1}&a_{m2}&\dots&a_{mn}&\\
3117 \end{array}$$
3118 (In this case the delimiter {\tt:} following the keyword {\tt(tr)} is
3119 optional and may be omitted.)
3121 This data record is completely analogous to the matrix data record (see
3122 above) with only exception that in this case each element $a_{ij}$ of
3123 the matrix corresponds to 2-tuple $(c_j,r_i)$ rather than $(r_i,c_j)$.
3125 Being once specified the {\tt(tr)} indicator affects all subsequent
3126 data records until either a slice or the end of data block is
3127 encountered.
3129 \subsection{Parameter data block}
3131 \medskip
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;}
3138 \medskip
3140 \hspace{6pt} {\tt param} {\it name} {\tt default} {\it value} {\tt,}
3141 {\it record} {\tt,} \dots {\tt,} {\it record} {\tt;}
3143 \medskip
3145 \hspace{6pt} {\tt param} {\tt:} {\it tabbing-data} {\tt;}
3147 \medskip
3149 \hspace{6pt} {\tt param} {\tt default} {\it value} {\tt:}
3150 {\it tabbing-data} {\tt;}
3151 }}
3153 \newpage
3155 \setlength{\leftmargini}{60pt}
3157 \begin{description}
3158 \item[{\rm Where:}\hspace*{23pt}] {\it name} is a symbolic name of the
3159 parameter;
3160 \item[\hspace*{54pt}] {\it value} is an optional default value of the
3161 parameter;
3162 \item[\hspace*{54pt}] {\it record}, \dots, {\it record} are data
3163 records;
3164 \item[\hspace*{54pt}] {\it tabbing-data} specifies parameter data in
3165 the tabbing format.
3166 \end{description}
3168 \begin{description}
3169 \item[{\rm Note:}\hspace*{31pt}] Commae preceding data records may be
3170 omitted.
3171 \end{description}
3173 \noindent Data records:
3175 \begin{description}
3176 \item[{\tt :=}\hspace*{45pt}] is a non-significant data record, which
3177 may 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
3180 plain format;
3181 \item[{\tt:} {\it tabular-data}]\hspace*{0pt}\\
3182 specifies parameter data in the tabular format;
3183 \item[{\tt(tr)} {\tt:} {\it tabular-data}]\hspace*{0pt}\\
3184 specifies set data in the transposed tabular format. (In this case the
3185 colon following the keyword {\tt(tr)} may be omitted.)
3186 \end{description}
3188 \noindent{\bf Examples}
3190 \begin{verbatim}
3191 param T := 4;
3192 param month := 1 'Jan' 2 'Feb' 3 'Mar' 4 'Apr' 5 'May';
3193 param month := [1] Jan, [2] Feb, [3] Mar, [4] Apr, [5] May;
3194 param day := [Sun] 0, [Mon] 1, [Tue] 2, [Wed] 3, [Thu] 4,
3195 [Fri] 5, [Sat] 6;
3196 param init_stock := iron 7.32 nickel 35.8;
3197 param init_stock [*] iron 7.32, nickel 35.8;
3198 param cost [iron] .025 [nickel] .03;
3199 param value := iron -.1, nickel .02;
3200 param : init_stock cost value :=
3201 iron 7.32 .025 -.1
3202 nickel 35.8 .03 .02 ;
3203 param : raw : init_stock cost value :=
3204 iron 7.32 .025 -.1
3205 nickel 35.8 .03 .02 ;
3206 param 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}
3213 \newpage
3215 \begin{verbatim}
3216 param 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}
3231 The {\it parameter data block} is used to specify complete data for a
3232 parameter (or parameters, if data are specified in the tabbing format).
3234 Data blocks can be specified only for non-computable parameters, i.e.
3235 for parameters, which have no assign ({\tt:=}) attribute in the
3236 corresponding parameter statements.
3238 Data defined in the parameter data block are coded as a sequence of
3239 data records described below. Additionally the data block can be
3240 provided with the optional {\tt default} attribute, which specifies a
3241 default numeric or symbolic value of the parameter (parameters). This
3242 default value is assigned to the parameter or its members, if
3243 no appropriate value is defined in the parameter data block. The
3244 {\tt default} attribute cannot be used, if it is already specified in
3245 the corresponding parameter statement.
3247 \subsubsection{Assign data record}
3249 The {\it assign} ({\tt:=}) {\it data record} is a non-signficant
3250 element. It may be used for improving readability of data blocks.
3252 \subsubsection{Slice data record}
3254 The {\it slice data record} is a control record, which specifies a
3255 {\it slice} of the parameter array. It has the following syntactic form:
3257 \medskip
3259 \noindent\hfil
3260 {\tt[} $s_1$ {\tt,} $s_2$ {\tt,} \dots {\tt,} $s_n$ {\tt]}
3262 \medskip
3264 \noindent where $s_1$, $s_2$, \dots, $s_n$ are components of the slice.
3266 Each 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
3268 dimension of the parameter. For instance, if the parameter is a
3269 4-dimensional array, the slice must have four components. The number of
3270 asterisks in the slice is called the {\it slice dimension}.
3272 The 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
3274 subsequent data records must specify subscripts of the parameter
3275 members as if the parameter were $m$-dimensional, not $n$-dimensional.
3277 Whenever $m$ subscripts are encountered, each asterisk in the slice is
3278 replaced by corresponding subscript that gives $n$ subscripts, which
3279 define the actual parameter member. For example, if the slice
3280 $[a,*,1,2,*]$ is in effect, and subscripts 3 and $b$ are encountered in
3281 a subsequent data record, the complete subscript list used to choose a
3282 parameter member is $[a,3,1,2,b]$.
3284 It is allowed to specify a slice having no asterisks. Such slice itself
3285 defines a complete subscript list, in which case the next data record
3286 should define only a single value of corresponding parameter member.
3288 Being once specified the slice effects until either a new slice or the
3289 end of data block is encountered. Note that if no slice is specified in
3290 the data block, one, components of which are all asterisks, is assumed.
3292 \subsubsection{Plain data record}
3294 The {\it plain data record} defines a subscript list and a single value
3295 in the plain format. This record has the following syntactic form:
3297 \medskip
3299 \noindent\hfil
3300 $t_1$ {\tt,} $t_2$ {\tt,} \dots {\tt,} $t_n$ {\tt,} $v$
3302 \medskip
3304 \noindent where $t_1$, $t_2$, \dots, $t_n$ are subscripts, and $v$ is a
3305 value. Each subscript as well as the value can be a number or symbol.
3306 Commae following subscripts are optional and may be omitted.
3308 In case of 0-dimensional parameter or slice the plain data record has
3309 no subscripts and consists of a single value only.
3311 \subsubsection{Tabular data record}
3313 The {\it tabular data record} defines several values, where each value
3314 is provided with two subscripts. This record has the following
3315 syntactic form:
3316 $$\begin{array}{cccccc}
3317 \mbox{{\tt:}}&c_1&c_2&\dots&c_n&\mbox{{\tt:=}}\\
3318 r_1&a_{11}&a_{12}&\dots&a_{1n}&\\
3319 r_2&a_{21}&a_{22}&\dots&a_{2n}&\\
3320 \multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}&\\
3321 r_m&a_{m1}&a_{m2}&\dots&a_{mn}&\\
3322 \end{array}$$
3323 where $r_1$, $r_2$, \dots, $r_m$ are numbers and/or symbols
3324 corresponding to rows of the table; $c_1$, $c_2$, \dots, $c_n$ are
3325 numbers 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
3327 number or symbol or the single decimal point ({\tt.}). (In this data
3328 record the delimiter {\tt:} preceding the column list and the delimiter
3329 {\tt:=} following the column list cannot be omitted.)
3331 Each 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
3334 conjunction with the current slice to form the complete subscript list
3335 that identifies a particular member of the parameter array. If $a_{ij}$
3336 is a number or symbol, this value is assigned to the parameter member.
3337 However, if $a_{ij}$ is the single decimal point, the member is
3338 assigned a default value specified either in the parameter data block
3339 or in the parameter statement, or, if no default value is specified,
3340 the member remains undefined.
3342 Since the tabular data record provides two subscripts for each value,
3343 either the parameter or the slice currently used must be 2-dimensional.
3345 \subsubsection{Transposed tabular data record}
3347 The {\it transposed tabular data record} has the following syntactic
3348 form:
3349 $$\begin{array}{cccccc}
3350 \mbox{{\tt(tr) :}}&c_1&c_2&\dots&c_n&\mbox{{\tt:=}}\\
3351 r_1&a_{11}&a_{12}&\dots&a_{1n}&\\
3352 r_2&a_{21}&a_{22}&\dots&a_{2n}&\\
3353 \multicolumn{5}{c}{.\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .\ \ .}&\\
3354 r_m&a_{m1}&a_{m2}&\dots&a_{mn}&\\
3355 \end{array}$$
3356 (In this case the delimiter {\tt:} following the keyword {\tt(tr)} is
3357 optional and may be omitted.)
3359 This data record is completely analogous to the tabular data record
3360 (see above) with only exception that the first subscript defined by
3361 element $a_{ij}$ is $c_j$ while the second one is $r_i$.
3363 Being once specified the {\tt(tr)} indicator affects all subsequent
3364 data records until either a slice or the end of data block is
3365 encountered.
3367 \subsubsection{Tabbing data format}
3369 The parameter data block in the {\it tabbing format} has the following
3370 syntactic 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:}}&
3375 p_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,}&
3378 a_{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,}&
3381 a_{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,}&
3386 a_{mk}&\mbox{\tt;}\\
3387 \end{array}$$
3389 {\it Notes:}
3391 1. The keyword {\tt default} may be omitted along with a value
3392 following it.
3394 2. Symbolic name {\tt s} may be omitted along with the colon following
3395 it.
3397 3. All comae are optional and may be omitted.
3399 \medskip
3401 The data block in the tabbing format shown above is exactly equivalent
3402 to the following data blocks for $j=1,2,\dots,k$:
3404 \medskip
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;}
3411 {\tt param} $p_j$ {\tt default} {\it value} {\tt:=}
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;}
3420 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3422 \appendix
3424 \newpage
3426 \section{Using suffixes}
3428 Suffixes can be used to retrieve additional values associated with
3429 model variables, constraints, and objectives.
3431 A {\it suffix} consists of a period ({\tt.}) followed by a non-reserved
3432 keyword. 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
3434 elemental variable {\tt x[i,j]}, which (value) can be used everywhere
3435 in expressions like a numeric parameter.
3437 For model variables suffixes have the following meaning:
3439 \medskip
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}
3455 \medskip
3457 For model constraints and objectives suffixes have the following
3458 meaning:
3460 \medskip
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
3474 solution\\
3475 \end{tabular}
3477 \medskip
3479 Note that suffixes {\tt.status}, {\tt.val}, and {\tt.dual} can be used
3480 only below the solve statement.
3482 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3484 \newpage
3486 \section{Date and time functions}
3488 \noindent\hfil
3489 by Andrew Makhorin \verb|<mao@gnu.org>|
3491 \noindent\hfil
3492 and Heinrich Schuchardt \verb|<heinrich.schuchardt@gmx.de>|
3494 \subsection{Obtaining current calendar time}
3495 \label{gmtime}
3497 To obtain the current calendar time in MathProg there exists the
3498 function {\tt gmtime}. It has no arguments and returns the number of
3499 seconds elapsed since 00:00:00 on January 1, 1970, Coordinated
3500 Universal Time (UTC). For example:
3502 \medskip
3504 \verb| param utc := gmtime();|
3506 \medskip
3508 MathProg has no function to convert UTC time returned by the function
3509 {\tt gmtime} to {\it local} calendar times. Thus, if you need to
3510 determine the current local calendar time, you have to add to the UTC
3511 time returned the time offset from UTC expressed in seconds. For
3512 example, the time in Berlin during the winter is one hour ahead of UTC
3513 that corresponds to the time offset +1 hour = +3600 secs, so the
3514 current winter calendar time in Berlin may be determined as follows:
3516 \medskip
3518 \verb| param now := gmtime() + 3600;|
3520 \medskip
3522 \noindent Similarly, the summer time in Chicago (Central Daylight Time)
3523 is five hours behind UTC, so the corresponding current local calendar
3524 time may be determined as follows:
3526 \medskip
3528 \verb| param now := gmtime() - 5 * 3600;|
3530 \medskip
3532 Note that the value returned by {\tt gmtime} is volatile, i.e. being
3533 called several times this function may return different values.
3535 \subsection{Converting character string to calendar time}
3536 \label{str2time}
3538 The function {\tt str2time(}{\it s}{\tt,} {\it f}{\tt)} converts a
3539 character string (timestamp) specified by its first argument {\it s},
3540 which must be a symbolic expression, to the calendar time suitable for
3541 arithmetic calculations. The conversion is controlled by the specified
3542 format string {\it f} (the second argument), which also must be a
3543 symbolic expression.
3545 The result of conversion returned by {\tt str2time} has the same
3546 meaning 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,
3549 i.e. being applied to 00:00:00 on January 1, 1970 it always returns 0.
3551 For example, the model statements:
3553 \medskip
3555 \verb| param s, symbolic, := "07/14/98 13:47";|
3557 \verb| param t := str2time(s, "%m/%d/%y %H:%M");|
3559 \verb| display t;|
3561 \medskip
3563 \noindent produce the following printout:
3565 \medskip
3567 \verb| t = 900424020|
3569 \medskip
3571 \noindent where the calendar time printed corresponds to 13:47:00 on
3572 July 14, 1998.
3574 \newpage
3576 The format string passed to the function {\tt str2time} consists of
3577 conversion specifiers and ordinary characters. Each conversion
3578 specifier begins with a percent ({\tt\%}) character followed by a
3579 letter.
3581 The following conversion specifiers may be used in the format string:
3583 \medskip
3585 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3586 {\tt\%b}&The abbreviated month name (case insensitive). At least three
3587 first letters of the month name must appear in the input string.\\
3588 \end{tabular}
3590 \medskip
3592 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3593 {\tt\%d}&The day of the month as a decimal number (range 1 to 31).
3594 Leading zero is permitted, but not required.\\
3595 \end{tabular}
3597 \medskip
3599 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3600 {\tt\%h}&The same as {\tt\%b}.\\
3601 \end{tabular}
3603 \medskip
3605 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3606 {\tt\%H}&The hour as a decimal number, using a 24-hour clock (range 0
3607 to 23). Leading zero is permitted, but not required.\\
3608 \end{tabular}
3610 \medskip
3612 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3613 {\tt\%m}&The month as a decimal number (range 1 to 12). Leading zero is
3614 permitted, but not required.\\
3615 \end{tabular}
3617 \medskip
3619 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3620 {\tt\%M}&The minute as a decimal number (range 0 to 59). Leading zero
3621 is permitted, but not required.\\
3622 \end{tabular}
3624 \medskip
3626 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3627 {\tt\%S}&The second as a decimal number (range 0 to 60). Leading zero
3628 is permitted, but not required.\\
3629 \end{tabular}
3631 \medskip
3633 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3634 {\tt\%y}&The year without a century as a decimal number (range 0 to 99).
3635 Leading zero is permitted, but not required. Input values in the range
3636 0 to 68 are considered as the years 2000 to 2068 while the values 69 to
3637 99 as the years 1969 to 1999.\\
3638 \end{tabular}
3640 \medskip
3642 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3643 {\tt\%z}&The offset from GMT in ISO 8601 format.\\
3644 \end{tabular}
3646 \medskip
3648 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3649 {\tt\%\%}&A literal {\tt\%} character.\\
3650 \end{tabular}
3652 \medskip
3654 All other (ordinary) characters in the format string must have a
3655 matching character in the input string to be converted. Exceptions are
3656 spaces in the input string which can match zero or more space
3657 characters in the format string.
3659 If some date and/or time component(s) are missing in the format and,
3660 therefore, in the input string, the function {\tt str2time} uses their
3661 default values corresponding to 00:00:00 on January 1, 1970, that is,
3662 the default value of the year is 1970, the default value of the month
3663 is January, etc.
3665 The function {\tt str2time} is applicable to all calendar times in the
3666 range 00:00:00 on January 1, 0001 to 23:59:59 on December 31, 4000 of
3667 the Gregorian calendar.
3669 \subsection{Converting calendar time to character string}
3670 \label{time2str}
3672 The function {\tt time2str(}{\it t}{\tt,} {\it f}{\tt)} converts the
3673 calendar time specified by its first argument {\it t}, which must be a
3674 numeric expression, to a character string (symbolic value). The
3675 conversion is controlled by the specified format string {\it f} (the
3676 second argument), which must be a symbolic expression.
3678 The calendar time passed to {\tt time2str} has the same meaning as
3679 values 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,
3682 i.e. the calendar time 0 always corresponds to 00:00:00 on January 1,
3683 1970.
3685 For example, the model statements:
3687 \medskip
3689 \verb| param s, symbolic, := time2str(gmtime(), "%FT%TZ");|
3691 \verb| display s;|
3693 \medskip
3695 \noindent may produce the following printout:
3697 \medskip
3699 \verb| s = '2008-12-04T00:23:45Z'|
3701 \medskip
3703 \noindent which is a timestamp in the ISO format.
3705 The format string passed to the function {\tt time2str} consists of
3706 conversion specifiers and ordinary characters. Each conversion
3707 specifier begins with a percent ({\tt\%}) character followed by a
3708 letter.
3710 The following conversion specifiers may be used in the format string:
3712 \medskip
3714 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3715 {\tt\%a}&The abbreviated (2-character) weekday name.\\
3716 \end{tabular}
3718 \medskip
3720 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3721 {\tt\%A}&The full weekday name.\\
3722 \end{tabular}
3724 \medskip
3726 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3727 {\tt\%b}&The abbreviated (3-character) month name.\\
3728 \end{tabular}
3730 \medskip
3732 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3733 {\tt\%B}&The full month name.\\
3734 \end{tabular}
3736 \medskip
3738 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3739 {\tt\%C}&The century of the year, that is the greatest integer not
3740 greater than the year divided by 100.\\
3741 \end{tabular}
3743 \medskip
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}
3749 \medskip
3751 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3752 {\tt\%D}&The date using the format \verb|%m/%d/%y|.\\
3753 \end{tabular}
3755 \medskip
3757 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3758 {\tt\%e}&The day of the month like with \verb|%d|, but padded with
3759 blank rather than zero.\\
3760 \end{tabular}
3762 \medskip
3764 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3765 {\tt\%F}&The date using the format \verb|%Y-%m-%d|.\\
3766 \end{tabular}
3768 \medskip
3770 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3771 {\tt\%g}&The year corresponding to the ISO week number, but without the
3772 century (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
3774 to the previous or next year, that year is used instead.\\
3775 \end{tabular}
3777 \medskip
3779 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3780 {\tt\%G}&The year corresponding to the ISO week number. This has the
3781 same 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
3783 instead.
3784 \end{tabular}
3786 \medskip
3788 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3789 {\tt\%h}&The same as \verb|%b|.\\
3790 \end{tabular}
3792 \medskip
3794 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3795 {\tt\%H}&The hour as a decimal number, using a 24-hour clock (range 00
3796 to 23).\\
3797 \end{tabular}
3799 \medskip
3801 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3802 {\tt\%I}&The hour as a decimal number, using a 12-hour clock (range 01
3803 to 12).\\
3804 \end{tabular}
3806 \medskip
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}
3812 \medskip
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}
3819 \medskip
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}
3826 \medskip
3828 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3829 {\tt\%m}&The month as a decimal number (range 01 to 12).\\
3830 \end{tabular}
3832 \medskip
3834 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3835 {\tt\%M}&The minute as a decimal number (range 00 to 59).\\
3836 \end{tabular}
3838 \medskip
3840 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3841 {\tt\%p}&Either {\tt AM} or {\tt PM}, according to the given time value.
3842 Midnight is treated as {\tt AM} and noon as {\tt PM}.\\
3843 \end{tabular}
3845 \medskip
3847 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3848 {\tt\%P}&Either {\tt am} or {\tt pm}, according to the given time value.
3849 Midnight is treated as {\tt am} and noon as {\tt pm}.\\
3850 \end{tabular}
3852 \medskip
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}
3859 \medskip
3861 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3862 {\tt\%S}&The second as a decimal number (range 00 to 59).\\
3863 \end{tabular}
3865 \medskip
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}
3872 \medskip
3874 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3875 {\tt\%u}&The day of the week as a decimal number (range 1 to 7), Monday
3876 being 1.\\
3877 \end{tabular}
3879 \medskip
3881 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3882 {\tt\%U}&The week number of the current year as a decimal number (range
3883 00 to 53), starting with the first Sunday as the first day of the first
3884 week. Days preceding the first Sunday in the year are considered to be
3885 in week 00.
3886 \end{tabular}
3888 \medskip
3890 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3891 {\tt\%V}&The ISO week number as a decimal number (range 01 to 53). ISO
3892 weeks start with Monday and end with Sunday. Week 01 of a year is the
3893 first week which has the majority of its days in that year; this is
3894 equivalent to the week containing January 4. Week 01 of a year can
3895 contain days from the previous year. The week before week 01 of a year
3896 is the last week (52 or 53) of the previous year even if it contains
3897 days from the new year. In other word, if 1 January is Monday, Tuesday,
3898 Wednesday or Thursday, it is in week 01; if 1 January is Friday,
3899 Saturday or Sunday, it is in week 52 or 53 of the previous year.\\
3900 \end{tabular}
3902 \medskip
3904 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3905 {\tt\%w}&The day of the week as a decimal number (range 0 to 6), Sunday
3906 being 0.\\
3907 \end{tabular}
3909 \medskip
3911 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3912 {\tt\%W}&The week number of the current year as a decimal number (range
3913 00 to 53), starting with the first Monday as the first day of the first
3914 week. Days preceding the first Monday in the year are considered to be
3915 in week 00.\\
3916 \end{tabular}
3918 \medskip
3920 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3921 {\tt\%y}&The year without a century as a decimal number (range 00 to
3922 99), that is the year modulo 100.\\
3923 \end{tabular}
3925 \medskip
3927 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3928 {\tt\%Y}&The year as a decimal number, using the Gregorian calendar.\\
3929 \end{tabular}
3931 \medskip
3933 \begin{tabular}{@{}p{20pt}p{298pt}@{}}
3934 {\tt\%\%}&A literal \verb|%| character.\\
3935 \end{tabular}
3937 \medskip
3939 All other (ordinary) characters in the format string are simply copied
3940 to the resultant string.
3942 The first argument (calendar time) passed to the function {\tt time2str}
3943 must be in the range from $-62135596800$ to $+64092211199$ that
3944 corresponds to the period from 00:00:00 on January 1, 0001 to 23:59:59
3945 on December 31, 4000 of the Gregorian calendar.
3947 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
3949 \newpage
3951 \section{Table drivers}
3952 \label{drivers}
3954 \noindent\hfil
3955 by Andrew Makhorin \verb|<mao@gnu.org>|
3957 \noindent\hfil
3958 and Heinrich Schuchardt \verb|<heinrich.schuchardt@gmx.de>|
3960 \bigskip\bigskip
3962 The {\it table driver} is a program module which provides transmitting
3963 data between MathProg model objects and data tables.
3965 Currently the GLPK package has four table drivers:
3967 \setlength{\leftmargini}{2.5em}
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}
3976 \subsection{CSV table driver}
3978 The CSV table driver assumes that the data table is represented in the
3979 form of a plain text file in the CSV (comma-separated values) file
3980 format as described below.
3982 To choose the CSV table driver its name in the table statement should
3983 be specified as \verb|"CSV"|, and the only argument should specify the
3984 name of a plain text file containing the table. For example:
3986 \medskip
3988 \verb| table data IN "CSV" "data.csv": ... ;|
3990 \medskip
3992 The filename suffix may be arbitrary, however, it is recommended to use
3993 the suffix `\verb|.csv|'.
3995 On reading input tables the CSV table driver provides an implicit field
3996 named \verb|RECNO|, which contains the current record number. This
3997 field can be specified in the input table statement as if there were
3998 the actual field having the name \verb|RECNO| in the CSV file. For
3999 example:
4001 \medskip
4003 \verb| table list IN "CSV" "list.csv": num <- [RECNO], ... ;|
4005 \subsubsection*{CSV format\footnote{This material is based on the RFC
4006 document 4180.}}
4008 The CSV (comma-separated values) format is a plain text file format
4009 defined as follows.
4011 1. Each record is located on a separate line, delimited by a line
4012 break. For example:
4014 \medskip
4016 \verb| aaa,bbb,ccc\n|
4018 \verb| xxx,yyy,zzz\n|
4020 \medskip
4022 \noindent
4023 where \verb|\n| means the control character \verb|LF| ({\tt 0x0A}).
4025 \newpage
4027 2. The last record in the file may or may not have an ending line
4028 break. For example:
4030 \medskip
4032 \verb| aaa,bbb,ccc\n|
4034 \verb| xxx,yyy,zzz|
4036 \medskip
4038 3. There should be a header line appearing as the first line of the
4039 file in the same format as normal record lines. This header should
4040 contain names corresponding to the fields in the file. The number of
4041 field names in the header line should be the same as the number of
4042 fields in the records of the file. For example:
4044 \medskip
4046 \verb| name1,name2,name3\n|
4048 \verb| aaa,bbb,ccc\n|
4050 \verb| xxx,yyy,zzz\n|
4052 \medskip
4054 4. Within the header and each record there may be one or more fields
4055 separated by commas. Each line should contain the same number of fields
4056 throughout the file. Spaces are considered as part of a field and
4057 therefore not ignored. The last field in the record should not be
4058 followed by a comma. For example:
4060 \medskip
4062 \verb| aaa,bbb,ccc\n|
4064 \medskip
4066 5. Fields may or may not be enclosed in double quotes. For example:
4068 \medskip
4070 \verb| "aaa","bbb","ccc"\n|
4072 \verb| zzz,yyy,xxx\n|
4074 \medskip
4076 6. If a field is enclosed in double quotes, each double quote which is
4077 part of the field should be coded twice. For example:
4079 \medskip
4081 \verb| "aaa","b""bb","ccc"\n|
4083 \medskip
4085 \noindent{\bf Example}
4087 \begin{verbatim}
4088 FROM,TO,DISTANCE,COST
4089 Seattle,New-York,2.5,0.12
4090 Seattle,Chicago,1.7,0.08
4091 Seattle,Topeka,1.8,0.09
4092 San-Diego,New-York,2.5,0.15
4093 San-Diego,Chicago,1.8,0.10
4094 San-Diego,Topeka,1.4,0.07
4095 \end{verbatim}
4097 \subsection{xBASE table driver}
4099 The xBASE table driver assumes that the data table is stored in the
4100 .dbf file format.
4102 To choose the xBASE table driver its name in the table statement should
4103 be specified as \verb|"xBASE"|, and the first argument should specify
4104 the name of a .dbf file containing the table. For the output table there
4105 should be the second argument defining the table format in the form
4106 \verb|"FF...F"|, where \verb|F| is either {\tt C({\it n})},
4107 which specifies a character field of length $n$, or
4108 {\tt N({\it n}{\rm [},{\it p}{\rm ]})}, which specifies a numeric field
4109 of length $n$ and precision $p$ (by default $p$ is 0).
4111 The following is a simple example which illustrates creating and
4112 reading a .dbf file:
4114 \begin{verbatim}
4115 table 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;
4118 set S, dimen 4;
4119 table tab2 IN "xBASE" "foo.dbf": S <- [B, C, RECNO, A];
4120 display S;
4121 end;
4122 \end{verbatim}
4124 \subsection{ODBC table driver}
4126 The ODBC table driver allows connecting to SQL databases using an
4127 implementation of the ODBC interface based on the Call Level Interface
4128 (CLI).\footnote{The corresponding software standard is defined in
4129 ISO/IEC 9075-3:2003.}
4131 \paragraph{Debian GNU/Linux.}
4132 Under Debian GNU/Linux the ODBC table driver uses the iODBC
4133 package,\footnote{See {\tt<http://www.iodbc.org/>}.} which should be
4134 installed before building the GLPK package. The installation can be
4135 effected with the following command:
4137 \begin{verbatim}
4138 sudo apt-get install libiodbc2-dev
4139 \end{verbatim}
4141 Note that on configuring the GLPK package to enable using the iODBC
4142 library the option `\verb|--enable-odbc|' should be passed to the
4143 configure script.
4145 The individual databases must be entered for systemwide usage in
4146 \linebreak \verb|/etc/odbc.ini| and \verb|/etc/odbcinst.ini|. Database
4147 connections to be used by a single user are specified by files in the
4148 home directory (\verb|.odbc.ini| and \verb|.odbcinst.ini|).
4150 \paragraph{Microsoft Windows.}
4151 Under Microsoft Windows the ODBC table driver uses the Microsoft ODBC
4152 library. To enable this feature the symbol:
4154 \begin{verbatim}
4155 #define ODBC_DLNAME "odbc32.dll"
4156 \end{verbatim}
4158 \noindent
4159 should be defined in the GLPK configuration file `\verb|config.h|'.
4161 Data sources can be created via the Administrative Tools from the
4162 Control Panel.
4164 \bigskip
4166 To choose the ODBC table driver its name in the table statement should
4167 be specified as \verb|'ODBC'| or \verb|'iODBC'|.
4169 The argument list is specified as follows.
4171 The first argument is the connection string passed to the ODBC library,
4172 for example:
4174 \verb|'DSN=glpk;UID=user;PWD=password'|, or
4176 \verb|'DRIVER=MySQL;DATABASE=glpkdb;UID=user;PWD=password'|.
4178 Different parts of the string are separated by semicolons. Each part
4179 consists of a pair {\it fieldname} and {\it value} separated by the
4180 equal sign. Allowable fieldnames depend on the ODBC library. Typically
4181 the following fieldnames are allowed:
4183 \verb|DATABASE | database;
4185 \verb|DRIVER | ODBC driver;
4187 \verb|DSN | name of a data source;
4189 \verb|FILEDSN | name of a file data source;
4191 \verb|PWD | user password;
4193 \verb|SERVER | database;
4195 \verb|UID | user name.
4197 The second argument and all following are considered to be SQL
4198 statements
4200 SQL statements may be spread over multiple arguments. If the last
4201 character of an argument is a semicolon this indicates the end of
4202 a SQL statement.
4204 The arguments of a SQL statement are concatenated separated by space.
4205 The eventual trailing semicolon will be removed.
4207 All but the last SQL statement will be executed directly.
4209 For IN-table the last SQL statement can be a SELECT command starting
4210 with the capitalized letters \verb|'SELECT '|. If the string does not
4211 start with \verb|'SELECT '| it is considered to be a table name and a
4212 SELECT statement is automatically generated.
4214 For OUT-table the last SQL statement can contain one or multiple
4215 question marks. If it contains a question mark it is considered a
4216 template for the write routine. Otherwise the string is considered a
4217 table name and an INSERT template is automatically generated.
4219 The writing routine uses the template with the question marks and
4220 replaces the first question mark by the first output parameter, the
4221 second question mark by the second output parameter and so forth. Then
4222 the SQL command is issued.
4224 The following is an example of the output table statement:
4226 \begin{small}
4227 \begin{verbatim}
4228 table 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}
4238 \noindent
4239 Alternatively it could be written as follows:
4241 \begin{small}
4242 \begin{verbatim}
4243 table 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}
4253 Using templates with `\verb|?|' supports not only INSERT, but also
4254 UPDATE, DELETE, etc. For example:
4256 \begin{small}
4257 \begin{verbatim}
4258 table 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}
4267 \subsection{MySQL table driver}
4269 The MySQL table driver allows connecting to MySQL databases.
4271 \paragraph{Debian GNU/Linux.}
4272 Under Debian GNU/Linux the MySQL table\linebreak driver uses the MySQL
4273 package,\footnote{For download development files see
4274 {\tt<http://dev.mysql.com/downloads/mysql/>}.} which should be installed
4275 before building the GLPK package. The installation can be effected with
4276 the following command:
4278 \begin{verbatim}
4279 sudo apt-get install libmysqlclient15-dev
4280 \end{verbatim}
4282 Note that on configuring the GLPK package to enable using the MySQL
4283 library the option `\verb|--enable-mysql|' should be passed to the
4284 configure script.
4286 \paragraph{Microsoft Windows.}
4287 Under Microsoft Windows the MySQL table driver also uses the MySQL
4288 library. To enable this feature the symbol:
4290 \begin{verbatim}
4291 #define MYSQL_DLNAME "libmysql.dll"
4292 \end{verbatim}
4294 \noindent
4295 should be defined in the GLPK configuration file `\verb|config.h|'.
4297 \bigskip
4299 To choose the MySQL table driver its name in the table statement should
4300 be specified as \verb|'MySQL'|.
4302 The argument list is specified as follows.
4304 The first argument specifies how to connect the data base in the DSN
4305 style, for example:
4307 \verb|'Database=glpk;UID=glpk;PWD=gnu'|.
4309 Different parts of the string are separated by semicolons. Each part
4310 consists of a pair {\it fieldname} and {\it value} separated by the
4311 equal sign. The following fieldnames are allowed:
4313 \verb|Server | server running the database (defaulting to localhost);
4315 \verb|Database | name of the database;
4317 \verb|UID | user name;
4319 \verb|PWD | user password;
4321 \verb|Port | port used by the server (defaulting to 3306).
4323 The second argument and all following are considered to be SQL
4324 statements
4326 SQL statements may be spread over multiple arguments. If the last
4327 character of an argument is a semicolon this indicates the end of
4328 a SQL statement.
4330 The arguments of a SQL statement are concatenated separated by space.
4331 The eventual trailing semicolon will be removed.
4333 All but the last SQL statement will be executed directly.
4335 For IN-table the last SQL statement can be a SELECT command starting
4336 with the capitalized letters \verb|'SELECT '|. If the string does not
4337 start with \verb|'SELECT '| it is considered to be a table name and a
4338 SELECT statement is automatically generated.
4340 For OUT-table the last SQL statement can contain one or multiple
4341 question marks. If it contains a question mark it is considered a
4342 template for the write routine. Otherwise the string is considered a
4343 table name and an INSERT template is automatically generated.
4345 The writing routine uses the template with the question marks and
4346 replaces the first question mark by the first output parameter, the
4347 second question mark by the second output parameter and so forth. Then
4348 the SQL command is issued.
4350 The following is an example of the output table statement:
4352 \begin{small}
4353 \begin{verbatim}
4354 table 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}
4364 \noindent
4365 Alternatively it could be written as follows:
4367 \begin{small}
4368 \begin{verbatim}
4369 table 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}
4379 Using templates with `\verb|?|' supports not only INSERT, but also
4380 UPDATE, DELETE, etc. For example:
4382 \begin{small}
4383 \begin{verbatim}
4384 table 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}
4393 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4395 \newpage
4397 \section{Solving models with glpsol}
4399 The GLPK package\footnote{{\tt http://www.gnu.org/software/glpk/}}
4400 includes the program {\tt glpsol}, which is a stand-alone LP/MIP solver.
4401 This program can be launched from the command line or from the shell to
4402 solve models written in the GNU MathProg modeling language.
4404 In order to tell the solver that the input file contains a model
4405 description, you need to specify the option \verb|--model| in the
4406 command line. For example:
4408 \medskip
4410 \verb| glpsol --model foo.mod|
4412 \medskip
4414 Sometimes it is necessary to use the data section placed in a separate
4415 file, in which case you may use the following command:
4417 \medskip
4419 \verb| glpsol --model foo.mod --data foo.dat|
4421 \medskip
4423 \noindent Note that if the model file also contains the data section,
4424 that section is ignored.
4426 If the model description contains some display and/or printf statements,
4427 by default the output is sent to the terminal. In order to redirect the
4428 output to a file you may use the following command:
4430 \medskip
4432 \verb| glpsol --model foo.mod --display foo.out|
4434 \medskip
4436 If you need to look at the problem, which has been generated by the
4437 model translator, you may use the option \verb|--wlp| as follows:
4439 \medskip
4441 \verb| glpsol --model foo.mod --wlp foo.lp|
4443 \medskip
4445 \noindent in which case the problem data is written to file
4446 \verb|foo.lp| in CPLEX LP format suitable for visual analysis.
4448 Sometimes it is needed merely to check the model description not
4449 solving the generated problem instance. In this case you may specify
4450 the option \verb|--check|, for example:
4452 \medskip
4454 \verb| glpsol --check --model foo.mod --wlp foo.lp|
4456 \medskip
4458 In order to write a numeric solution obtained by the solver you may use
4459 the following command:
4461 \medskip
4463 \verb| glpsol --model foo.mod --output foo.sol|
4465 \medskip
4467 \noindent in which case the solution is written to file \verb|foo.sol|
4468 in a plain text format.
4470 The complete list of the \verb|glpsol| options can be found in the
4471 reference manual included in the GLPK distribution.
4473 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4475 \newpage
4477 \section{Example model description}
4479 \subsection{Model description written in MathProg}
4481 Below here is a complete example of the model description written in
4482 the GNU MathProg modeling language.
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.
4496 set I;
4497 /* canning plants */
4499 set J;
4500 /* markets */
4502 param a{i in I};
4503 /* capacity of plant i in cases */
4505 param b{j in J};
4506 /* demand at market j in cases */
4508 param d{i in I, j in J};
4509 /* distance in thousands of miles */
4511 param f;
4512 /* freight in dollars per case per thousand miles */
4514 param c{i in I, j in J} := f * d[i,j] / 1000;
4515 /* transport cost in thousands of dollars per case */
4517 var x{i in I, j in J} >= 0;
4518 /* shipment quantities in cases */
4520 minimize cost: sum{i in I, j in J} c[i,j] * x[i,j];
4521 /* total transportation costs in thousands of dollars */
4523 s.t. supply{i in I}: sum{j in J} x[i,j] <= a[i];
4524 /* observe supply limit at plant i */
4526 s.t. demand{j in J}: sum{i in I} x[i,j] >= b[j];
4527 /* satisfy demand at market j */
4529 data;
4531 set I := Seattle San-Diego;
4533 set J := New-York Chicago Topeka;
4535 param a := Seattle 350
4536 San-Diego 600;
4538 param b := New-York 325
4539 Chicago 300
4540 Topeka 275;
4542 param d : New-York Chicago Topeka :=
4543 Seattle 2.5 1.7 1.8
4544 San-Diego 2.5 1.8 1.4 ;
4546 param f := 90;
4548 end;
4549 \end{verbatim}
4550 \end{small}
4552 \subsection{Generated LP problem instance}
4554 Below here is the result of the translation of the example model
4555 produced by the solver \verb|glpsol| and written in CPLEX LP format
4556 with the option \verb|--wlp|.
4558 \begin{small}
4559 \begin{verbatim}
4560 \* Problem: transp *\
4562 Minimize
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)
4567 Subject 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
4576 End
4577 \end{verbatim}
4578 \end{small}
4580 \subsection{Optimal LP solution}
4582 Below here is the optimal solution of the generated LP problem instance
4583 found by the solver \verb|glpsol| and written in plain text format
4584 with the option \verb|--output|.
4586 \newpage
4588 \begin{small}
4589 \begin{verbatim}
4590 Problem: transp
4591 Rows: 6
4592 Columns: 6
4593 Non-zeros: 18
4594 Status: OPTIMAL
4595 Objective: cost = 153.675 (MINimum)
4597 No. 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
4611 No. 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
4626 End of output
4627 \end{verbatim}
4628 \end{small}
4630 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
4632 \newpage
4634 \setcounter{secnumdepth}{-1}
4636 \section{Acknowledgment}
4638 The authors would like to thank the following people, who kindly read,
4639 commented, and corrected the draft of this document:
4641 \medskip
4643 \noindent Juan Carlos Borras \verb|<borras@cs.helsinki.fi>|
4645 \medskip
4647 \noindent Harley Mackenzie \verb|<hjm@bigpond.com>|
4649 \medskip
4651 \noindent Robbie Morrison \verb|<robbie@actrix.co.nz>|
4653 \end{document}