aimms_tutorial_beginner

AIMMS A One-Hour Tutorial for Beginners March 2010 Paragon Decision Technology Johannes Bisschop Koos Heerink Copyright c© 1993–2010 by Paragon Decision Technology B.V. All rights reserved. Paragon Decision Technology B.V. Schipholweg 1 2034 LS Haarlem The Netherlands Tel.: +31 23 5511512 Fax: +31 23 5511517 Paragon Decision Technology Inc. 500 108th Avenue NE Ste. # 1085 Bellevue, WA 98004 USA Tel.: +1 425 458 4024 Fax: +1 425 458 4025 Paragon Decision Technology Pte. Ltd. 80 Raffles Place UOB Plaza 1, Level 36-01 Singapore 048624 Tel.: +65 9640 4182 Email: info@aimms.com WWW: www.aimms.com ISBN xx–xxxxxx–x–x Aimms is a registered trademark of Paragon Decision Technology B.V. IBM ILOG CPLEX and sc CPLEX is a registered trademark of IBM Corporation. GUROBI is a registered trademark of Gurobi Optimization, Inc. KNITRO is a registered trademark of Ziena Optimization, Inc. XPRESS-MP is a registered trademark of FICO Fair Isaac Corporation. Mosek is a registered trademark of Mosek ApS. Windows and Excel are registered trademarks of Microsoft Corporation. TEX, LATEX, andAMS-LATEX are trademarks of the American Mathematical Society. Lucida is a registered trademark of Bigelow & Holmes Inc. Acrobat is a registered trademark of Adobe Systems Inc. Other brands and their products are trademarks of their respective holders. Information in this document is subject to change without notice and does not represent a commitment on the part of Paragon Decision Technology B.V. The software described in this document is furnished under a license agreement and may only be used and copied in accordance with the terms of the agreement. The documentation may not, in whole or in part, be copied, photocopied, reproduced, translated, or reduced to any electronic medium or machine-readable form without prior consent, in writing, from Paragon Decision Technology B.V. Paragon Decision Technology B.V. makes no representation or warranty with respect to the adequacy of this documentation or the programs which it describes for any particular purpose or with respect to its adequacy to produce any particular result. In no event shall Paragon Decision Technology B.V., its employees, its contractors or the authors of this documentation be liable for special, direct, indirect or consequential damages, losses, costs, charges, claims, demands, or claims for lost profits, fees or expenses of any nature or kind. In addition to the foregoing, users should recognize that all complex software systems and their doc- umentation contain errors and omissions. The authors, Paragon Decision Technology B.V. and its em- ployees, and its contractors shall not be responsible under any circumstances for providing information or corrections to errors and omissions discovered at any time in this book or the software it describes, whether or not they are aware of the errors or omissions. The authors, Paragon Decision Technology B.V. and its employees, and its contractors do not recommend the use of the software described in this book for applications in which errors or omissions could threaten life, injury or significant loss. This documentation was typeset by Paragon Decision Technology B.V. using LATEX and the Lucida font family. Contents Contents iii Common Aimms Shortcut Keys iv 1 Introduction 1 2 What to Expect 3 2.1 Scope of one-hour tutorial . . . . . . . . . . . . . . . . . . . . . . 3 2.2 Problem description and model statement . . . . . . . . . . . . 3 2.3 A preview of your output . . . . . . . . . . . . . . . . . . . . . . 6 3 Building the Model 7 3.1 Starting a new project . . . . . . . . . . . . . . . . . . . . . . . . 7 3.2 The Model Explorer . . . . . . . . . . . . . . . . . . . . . . . . . . 8 3.3 Entering sets and indices . . . . . . . . . . . . . . . . . . . . . . . 9 3.4 Entering parameters and variables . . . . . . . . . . . . . . . . . 10 3.5 Entering constraints and the mathematical program . . . . . 13 3.6 Viewing the identifiers . . . . . . . . . . . . . . . . . . . . . . . . 15 4 Entering and Saving the Data 21 4.1 Entering set data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21 4.2 Entering parameter data . . . . . . . . . . . . . . . . . . . . . . . 22 4.3 Saving your data . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 5 Solving the Model 27 5.1 Computing the solution . . . . . . . . . . . . . . . . . . . . . . . 27 6 Building a Page 30 6.1 Creating a new page . . . . . . . . . . . . . . . . . . . . . . . . . . 30 6.2 Presenting the input data . . . . . . . . . . . . . . . . . . . . . . 30 6.3 Presenting the output data . . . . . . . . . . . . . . . . . . . . . 33 6.4 Finishing the page . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 7 Performing a What-If Run 40 7.1 Modifying input data . . . . . . . . . . . . . . . . . . . . . . . . . 40 Common Aimms Shortcut Keys 42 Common Aimms Shortcut Keys Key Function F1 Open Aimms Help F2 Rename the selected identifier F3 Find and repeat find F4 Switch between edit mode and end-user mode (for the active page) F5 Compile all F6 Run MainExecution Alt+F6 Switch to debugger mode F7 Save the active page F8 Open Model Explorer Ctrl+F8 Open Identifer Selector F9 Open Page Manager Alt+ F9 Open Template Manager Ctrl+ F9 Open Menu Builder F10 Open Data Manager Ctrl+ F10 Open Data Management Setup F11 Open Identifer Info dialog Ctrl+ B Insert a break point in debugger mode Ctrl+ D Open Data Page Ctrl+ F Open Find dialog Ctrl+ M Open Message Window Ctrl+ P Open Progress Window Ctrl+ T View Text Representation of selected part(s) Ctrl+Shift + T View Text Representation of whole model Ctrl+ W Open Wizard Ctrl+ Space Name completion Ctrl+ Shift+Space Name completion including Aimms Predeclared Identifers Ctrl+ Enter Check, commit, and close Insert Insert a node (when single insert choice) or Open Select Node Type dialog (when multiple insert choices) Chapter 1 Introduction Ways to learn Aimms . . . There are several ways in which you can learn the Aimms language and get a ba- sic understanding of its underlying development environment. The following opportunities are immediately available, and are part of the Aimms installation. � There are two tutorials on Aimms to provide you with some initial work- ing knowledge of the system and its language. One tutorial is intended for beginners, while the other is aimed at professional users of Aimms. � There is a model library with a variety of examples to illustrate simple and advanced applications together with particular aspects of both the language and the graphical user interface. � There are three reference books on Aimms, which are available in PDF for- mat and in hard copy form. They are The User’s Guide to introduce you to Aimms and its development environment, The Language Reference to describe the modeling language in detail, and Optimization Modeling to enable you to become familiar with building models. . . . for beginnersAs a beginner into optimization modeling languages, you may not have much time for learning yet another tool in order to finish some project or home- work requirements. In this case, concentrate your efforts on this tutorial. Af- ter completing this tutorial, you should be able to use the system to build your own simple models, and to enter your own small data sets for subse- quent viewing. The book on Optimization Modeling may teach you some useful tricks, and will show you different (mostly non-trivial) examples of optimiza- tion models. Besides English, the tutorial for beginners is also available in Spanish, Hungarian, German and French, which can be found on our web site: http://www.aimms.com/downloads/tutorials/tutorial-for-beginners. . . . for professionals As a professional in the field of optimization modeling you are looking for a tool that simplifies your work and minimizes the time needed for model con- struction and model maintenance. In this situation, you cannot get around the fact that you will need to initially make a substantial time investment to get to know several of the advanced features that will subsequently support you in your role as a professional application builder. Depending on your skills, expe- rience, and learning habits you should determine your own individual learning path. Along this path you are advised to work through the extensive tutorial Chapter 1. Introduction 2 especially designed for professionals. This tutorial for professionals provides a good start, and should create excitement about the possibilities of Aimms. Individual examples in the library, plus selected portions of the three books, will subsequently offer you additional ideas on how to use Aimms effectively while building your own advanced applications. Tutorials are different in scope The one-hour tutorial for beginners is designed as the bare minimum needed to build simple models using the Aimms Model Explorer. Data values are en- tered by hand using data pages, and the student can build a page with objects to view and modify the data. The extensive tutorial for professionals is an elab- orate tour of Aimms covering a range of advanced language features plus an introduction to all the building tools. Especially of interest will be the modeling of time using the concepts of horizon and calendar, the use of quantities and units, the link to a database, the connection to an external DLL, and advanced reporting facilities. Even then, some topics such as efficiency considerations (execution efficiency, matrix manipulation routines) and the Aimms API will remain untouched. Chapter 2 What to Expect This chapterIn this chapter you will find a brief overview of the tasks to be performed, a compact statement of the underlying model to be built, and a glimpse of the output you will produce. 2.1 Scope of one-hour tutorial Summarizing your work Once you have read the short problem description and the associated mathe- matical model statement, you will be asked to complete a series of tasks that make up this one-hour tutorial, namely: � create a new project in Aimms, � enter all identifier declarations, � enter the data manually, � save your data in a case, � build a small procedure, � build a single page with – header text, – a standard table and two bar charts with input data, – a composite table and a stacked bar chart with output data, – a button to execute the procedure, and – a scalar object with the optimal value, � perform a what-if run. 2.2 Problem description and model statement Problem description Truckloads of beer are to be shipped from two plants to five customers dur- ing a particular period of time. Both the available supply at each plant and the required demand by each customer (measured in terms of truckloads) are known. The cost associated with moving one truck load from a plant to a customer is also provided. The objective is to make a least-cost plan for mov- ing the beer such that the demand is met and shipments do not exceed the available supply from each brewery. Chapter 2. What to Expect 4 Data overviewThe following table provides the data for the problem described in the previous paragraph. Customers Unit Transport Cost Plants Amsterdam Breda Gouda Amersfoort Den Bosch Supply Haarlem 131 405 188 396 485 47 Eindhoven 554 351 479 366 155 63 Demand 28 16 22 31 12 Table 2.1: Input data for beer transport problem Identifier declarations The following declarations list the identifiers that are part of the mathematical program to be built. Indices: p plants c customers Parameters: Sp supply at plant p Dc demand by customer c Upc unit transport cost from p to c Variables: xpc transport from p to c z total transport cost Model summaryThe mathematical model summary below captures the least-cost plan to trans- port beer such that the demand is met and shipments do not exceed available supply. Minimize: z = ∑ pc Upcxpc Subject to: ∑ c xpc ≤ Sp ∀p ∑ p xpc ≥ Dc ∀c xpc ≥ 0 ∀(p, c) Chapter 2. What to Expect 5 AmsterdamHaarlem Gouda Amersfoort Breda Den Bosch Eindhoven Figure 2.1: The Netherlands Using explicit names Even though the above notation with one-letter symbols is typical of small mathematical optimization models, it will not be used to represent the model in Aimms. Instead, explicit names will be used throughout to avoid any un- necessary translation symbols. The number of symbols needed to describe practical applications is generally large, and a clear naming convention sup- ports the understanding and maintenance of large models. Chapter 2. What to Expect 6 2.3 A preview of your output A single pageFigure 2.2 is a page that contains both input and output data associated with the beer transport model. In Chapter 6 you will be asked to construct this page using the point-and-click facilities available in Aimms. Figure 2.2: An input-output page Chapter 3 Building the Model 3.1 Starting a new project Starting AimmsAssuming that Aimms 3 has already been installed on your machine. If there is an Aimms 3 shortcut on your desktop, double click it to start Aimms 3, otherwise execute the following sequence of actions to start Aimms: � press the Start button on the taskbar, � go to the Programs submenu, and � select and click on the Aimms icon to start Aimms. Specifying a project name Next, you will see the Aimms splash screen. Once Aimms has started, the splash screen will disappear and the Aimms window will open. Should you encounter the Aimms Tip of the Day dialog box, close it, because it is not relevant to you at this point. Creating a new project from within Aimms Press the New Project button , which is located in the leftmost position on the Aimms toolbar. The dialog box shown in Figure 3.1 will then appear, requiring you to take the following actions: � specify ‘Beer Transport’ as the project name, and � press the wizard button to select the folder for your Aimms projects if the default folder ‘...\My Documents\My AIMMS Projects\Beer Transport’ is not desired,and � press the OK button. Chapter 3. Building the Model 8 Figure 3.1: The New Project wizard Next, the Aimms Model Explorer and the Aimms Page Manager will be auto- matically opened. We will look at the Aimms Model Explorer first. 3.2 The Model Explorer Initial model tree When opened for the first time, the Aimms Model Explorer will display the initial model tree shown in Figure 3.2. In this initial model tree you will see � a single declaration section, where you can store the declarations used in your model, � the predefined procedure MainInitialization, which is not relevant for this tutorial, � the predefined procedure MainExecution, where you will put the execution statement necessary to solve the mathematical program, and � the predefined procedure MainTermination, which is again not relevant for this tutorial. Figure 3.2: The initial model tree Chapter 3. Building the Model 9 3.3 Entering sets and indices Opening the declaration section The declaration of model identifiers requires you to first ‘open’ the declaration section. You can do this either by clicking the icon or by double-clicking on the scroll icon . Note that double-clicking on the name of the declaration section instead of on its icon will open the attribute form of the declaration section and will therefore, at this point, not lead to the desired result. After opening the declaration section the standard identifier buttons on the toolbar will be enabled. Creating the set ‘Plants’ To create a set of plants you should take the following actions: � press the Set button to create a new set identifier in the model tree, � specify ‘Plants’ as the name of the set, and � press the Enter key to register the name. Opening its attribute form Next, you need to declare the index p as an attribute of the set ‘Plants’. You can open the attribute form by double-clicking on the node ‘Plants’ in the model tree. The resulting initial attribute form of the set ‘Plants’ is shown in Fig- ure 3.3. Figure 3.3: The initial attribute form of the set ‘Plants’ Declaring the index p To declare the index p as an attribute of the set ‘Plants’, execute the following sequence of actions: � move the mouse cursor to the ‘Index’ attribute field, and click in the (empty) edit field, � enter the letter p, and � complete the attribute form by pressing the Check, Commit and Close button . Chapter 3. Building the Model 10 Creating the set ‘Customers’ Next, create the set ‘Customers’ with associated index c in exactly the same way as you created the set ’Plants’ with index domain p. Figure 3.4 contains the resulting model tree. Figure 3.4: An intermediate model tree Saving your changes The asterisk on the left of the project name indicates that additions to your project have not yet been saved to disk. To save your work, please press the Save Project button on the toolbar. 3.4 Entering parameters and variables Domain specification In this section you will declare the parameters and variables that are needed in your model. The sets ‘Plants’ and ‘Customers’ and their associated indices will be used to specify the index domain for the parameters and variables. Creating the parameter ‘Supply’ The declaration of a parameter is similar to the declaration of a set. To enter the parameter ‘Supply(p)’, you should execute the following actions: � press the parameter button on the toolbar to create a new parameter in the model tree, � specify ‘Supply(p)’ as the name of the parameter, and � press the Enter key to register the name. Note that parentheses are used to add the index domain p to the identifier ‘Supply’. Creating the parameter ‘Demand’ The parameter ’Demand(c)’ can be added in the same way. Should you make a mistake in entering the information, then you can always re-edit a name field by a single mouse click within the field. Chapter 3. Building the Model 11 Creating the parameter ‘UnitTransport- Cost’ The last model parameter ‘UnitTransportCost’ is a two-dimensional parameter with index domain (p, c). After entering ‘UnitTransportCost(p,c)’, the resulting model tree should be the same as in Figure 3.5. Figure 3.5: An intermediate model tree Creating the variable ‘Transport’ Declaring a variable is similar to declaring a parameter. � press the variable button on the toolbar to create a new variable in the model tree, � specify ‘Transport(p,c)’ as the name of the variable, and � press the Enter key to register the variable. Specifying range attribute After opening the attribute form of the variable by double-clicking on the node ‘Transport’ in the model tree, press the wizard button in front of the ‘Range’ attribute field. The resulting dialog box provides the opportunity to specify the range of values that the variable ‘Transport’ is allowed to take. In this case, select the ‘Standard Range’, then select ‘nonnegative’, and finally press the OK button (see Figure 3.6). Chapter 3. Building the Model 12 Figure 3.6: The Aimms range wizard Creating the variable ‘Total- TransportCost’ It should be clear by now how to create the variable ‘TotalTransportCost’. This variable will be used to specify the objective function. After entering its name, open the attribute form. There is no need to specify the range attribute, since the default range ‘free’ will suffice. You are now ready to enter the following definition of this particular variable: sum[ (p,c), UnitTransportCost(p,c) * Transport(p,c) ] Specifying definition attribute Simply enter the above definition in the ‘Definition’ attribute field. You could type the entire sentence yourself, but you can also let Aimms do some of the typing for you. Considering the parameter ‘UnitTransportCost(p,c)’, the fol- lowing two support features are quite useful. � Type the letter u or U, and press the Ctrl-Spacebar combination for auto- matic name completion. � Another option available to you is to drag the name ‘Unit