Sets Within GAMS, sets are equivalent to subscripts in algebra and are a series of items that can be simultaneously operated over including summed over or looped over among other possibilities. Here material is given on the major aspects of sets usage under the following categories Set declaration ............................................................................................................................ 2 Subsets........................................................................................................................................ 3 Element definition ...................................................................................................................... 3 Explicit element definition .................................................................................................... 3 Element definition by computation ....................................................................................... 4 Multi dimensional sets ............................................................................................................... 5 Domain checking........................................................................................................................ 5 Set element referencing.............................................................................................................. 6 Whole sets.............................................................................................................................. 6 Single elements...................................................................................................................... 7 Operating over part of a set ................................................................................................... 7 Using subsets .................................................................................................................... 7 Using conditionals ............................................................................................................ 8 Sameas.......................................................................................................................... 8 Diag .............................................................................................................................. 8 Ord................................................................................................................................ 9 Card .............................................................................................................................. 9 Using tuples ...................................................................................................................... 9 Universal set............................................................................................................................. 10 * as a set identifier ............................................................................................................... 10 Finding sets from data .............................................................................................................. 11 Using another name or an alias ................................................................................................ 11 Alias..................................................................................................................................... 11 Element order and capitalization in output .............................................................................. 12 Functions specifically referencing sets .................................................................................... 12 Ord ....................................................................................................................................... 12 Ordered sets .................................................................................................................... 13 Unordered sets ................................................................................................................ 13 Card ..................................................................................................................................... 13 Sameas ................................................................................................................................. 13 Diag ..................................................................................................................................... 14 Indexing sets defined over time ............................................................................................... 14 Leads and lags ..................................................................................................................... 14 - ....................................................................................................................................... 14 + ...................................................................................................................................... 14 Circular or equilibrium leads and lags................................................................................. 15 ++ .................................................................................................................................... 15 --...................................................................................................................................... 15 Element Position.................................................................................................................. 15 Set Arithmetic .......................................................................................................................... 16 Unions.................................................................................................................................. 16 Intersections......................................................................................................................... 16 Complements ....................................................................................................................... 16 Differences........................................................................................................................... 16 Alphabetic list of features ........................................................................................................ 17 Set declaration In order to use any set one must first declare it. In its most complete form the set declaration contains set name list of elements contained surrounded by /'s optional explanatory text for the whole set optional explanatory text for individual elements (rules for item names) (rules for set element names) (rules for entries) (rules for entries) The general format for the set declaration and element definition statement is: SET setname optional explanatory text / first set element name second set element name … /; Optional explanatory text Optional explanatory text or SETs setname optional explanatory text / first set element name Optional explanatory text second set element name Optional explanatory text … /; Examples (sets.gms) SETs SET SET j i PROCESS PRODUCTION PROCESSES commodities Crop commodities Set jj(j) $onmulti set i /x1,x2,x3/ /r1 ,r2/; /X1,X2,X3/; / corn in bushels Wheat in metric tons milk in pounds cost “cost/unit” "long-complex-*&$name" 'element name'/ ; set to b e computed later without entries ; additional entries for i /i1,i2/; Notes The word set or sets can be used. Set names must obey the item naming presented in the Rules for Item Names, Element names and Explanatory Text chapter. Labels and long explanatory names should be used where possible as argued in the Writing Models and Good Modeling Practices chapter. Multiple sets can be stacked with the set or sets keyword only used once (see example with i and j below). When multiple sets are defined in one set statement a ; is entered after all set definitions. Set elements are separated by spaces or commas. Element definitions can be quoted, have blanks or special characters as discussed in the Rules for Item Names, Element names and Explanatory Text chapter. Use of $onmulti allows multiple set statements to appear for a named set. Subsets One can define subsets containing part of the elements of another set using a set statement. The general format is SET subsetname(setname) optional explanatory text / Elementname1 optional explanatory text Elementname2 optional explanatory text/; where most of the contents are as discussed under set declaration above. The new elements are Subsetname which names this subset Setname which names the “super” set that this one is a subset of. Examples (sets.gms) Set Set Superset Subset(superset) allitems Crop(allitems) Resources(allitems) /r1,r2,r4*r15, r25/ /r1,r25/; /Corn,wheat,water,land/ /Corn,wheat/ /water,land/; Notes The named elements of the subset must be elements of the superset. The subset does not need to contain all elements of the superset. The subset may be defined with explicit or calculated elements as discussed below. Element definition Elements within sets can be entered explicitly or in the case of subsets may be defined with computations. Each case is covered below. Explicit element definition Explicit element definition involves the types of statements as above composed of set name of the set optional explanatory text / element names followed by optional explanatory text. between element names either a comma or a carriage return /. In element definition, one may cause multiple elements to be defined in sequence by using notation such as r1*r4 which causes definition of r1,r2,r3,r4. One can also place the number in other positions using for example 1u*10u which would define 1u, 2u, 3u etc. up to 10u. Examples (sets.gms) SETs SET SET rj ri mPROCESS mcommodities /x1,”x2 item”,’x3*case’/ /r1 ,r2,r4*r10, 1a*200a/; PROCESSES /X1,X2,X3/; Commodities / corn in bushels Wheat in metric tons milk in pounds/ ; Element definition by computation Elements of subsets may also be computed. This is done by using a statement such as Set(“nameofelement”)=yes; which is equivalent to including a set element named nameofelement in the set declaration. One may also use computations to remove elements by using a statement like Set(“nameofelement”)=no; Examples (sets.gms) Set nSuperset nSubset(nsuperset); nSubset(nsuperset)=yes; nSubset(“r4”)=no; /r1*r15/ Set nallitems /Corn,wheat,water,land/ nCrop(nallitems) ; Parameter yield(nallitems) /Corn 100,Wheat 40/; nCrop(nallitems)$(yield(nallitems) gt 0)=yes; Notes By default all elements in a set without definition are undefined (set to no), so one only has to identify the items present (setting them to yes). Setting an element to no removes it from the set. Complex conditionals can be employed in defining the sets. Conditionals are discussed in the Conditionals chapter. Computed sets cannot be used to define the domain of data items. One must use the superset for the domain. Sometimes one will compute a set and set all elements to yes then go back and selectively remove items using a command setting them to no. More on set computations appears in the Calculating Items chapter. Multi dimensional sets Sets do not need to be one dimensional and rather can be composed as sets of other sets where the basic notation to identify the presence of an element is set multidimset(set1name,set2name) .set2elementname / /set1elementname with the period separating the two set elements. Examples (sets.gms) Sets Origins Originating Places /”New York”, Boston/ Destinations Demand points /”Portland”,London, Houston/ Linkedbyroad(origins,destinations) Places linked by roadways /”NEW York” .Portland, “New York” .Houston, boston.Portland, boston.Houston/; Notes Up to 10 sets may be used to define a multidimensional set. These sets are useful in speeding up GAMS and making sure that unneeded cases like sending goods by truck across the ocean are not considered in the context of conditionals. A major use of multi dimensional sets is as a tuple in sums or conditions Shorthand notation may be used to specify elements in multidimensional sets using parentheses. For example, the statement Set xx(origins,destinations) /boston.(houston,london)/; is the same as the statement Set xx(origins,destinations) /boston.houston,boston.london/; Domain checking The GAMS compiler conducts 'domain checking,' with respect to subset definition and set element usage. Domain checking verifies that each element defined in a subset is in fact a member of the superset. It also insures that each referenced element of a set in GAMS calculations or other equations is in fact a member of the set associated with the definition of that location in parameters, variables, sets etc. When the items are not in the domain of the referenced set GAMS issues a compilation error and points to the mission element. Examples (seterr.gms) In the following case, the elements in bold and blue would pass the domain check, but the elements in bold and red would stimulate compiler errors because Baltimore is not an element of the set places and seatle is a misspelling. Set places list of locations /boston,Miami,seattle/; Set place(places) /boston,Miami,seatle,Baltimore/; Parameter dataitem(places) / boston 5,Miami 8,seatle 4,Baltimore 3/; Notes Domain checking is automatic and is only suppressed under two circumstances When the set in the position is either the universal set or is aliased to the universal set as discussed below. When the $onwarning option is used to suppress domain checking. Domain checking finds misspellings and omitted elements and thus should be used as often as possible. Sets with calculated elements cannot be used in definition of item domains. This will generate a GAMS error. These sets are called dynamic sets. Set element referencing Set elements are referenced in calculations, equation specifications, loops and many other statements. GAMS statements ordinarily refer to either a single element or to every element in the set. Special provisions must be made to operate on more than one, but not all, elements of a set. Set referencing may also be controlled by tuples where multiple sets are referenced only for specially defined joint elements. Each of these cases is defined below. Whole sets GAMS ordinarily operates over every element in a set. Thus, the command (sets.gms) Set II /i1*i4000/; Parameter x(ii); x(ii)=4; will define every case of x associated with the set II to 4 and in this case 4000 of them. Similarly the definition X(ii)=y(ii) +3; Will sequentially define every case of x in II to equal the associated case in y plus 3; Also the following commands will each operate or define items for each case of II Loop(II, z=z+y(Ii)); Z=sum(II,y(Ii)); Variable zz(Ii); Equation eq(Ii); Single elements One can also specify an element name in quotes to cause GAMS to operate over just a single element of a set. Thus the command x("i344")=4; will only operate over the I344 element of x leaving the rest alone. Similarly, the definition X("i344")=y("i344") +3; will only define the i344 case of x to equal the i344 case in y plus 3; The command X(Ii)=y("i344") +3; will set every case of x associated with the entries in Ii to the i344 case of y plus 3. Operating over part of a set Ordinarily one operates over each and every element of the reference set that an item is defined over. Thus in the case NX(II,J)=4; Each element of NX associated with every element of II in interaction with every element in J is operated over. However, there are cases where one wishes only to operate over part of those cases. In such a situation GAMS can be commanded to operate over part of the set through defined subsets, conditionals or tuples. Each case will be covered below. Using subsets There may be cases where one wishes to reference a priori known or calculated subsets. In such case, one may define a subset, either explicitly or through calculation, then reference the item with respect to that subset. Consider the following example. (sets.gms) Set thisI /i1*i10/; Set thisJ(thisI) / i1,i3,i5/; Parameter A(thisI) /i7 5, i2 9, i3 11/; Set wherea(thisI); Wherea(thisi)$a(thisi)=yes; Parameter nzz(thisi); nZz(thisi)=5; nZz(wherea)=-1; nZz(thisj)=12; In this case, the blue colored statements operate over subsets of thisI with the wherea reference being over a calculated subset and the thisj reference being over an explicitly defined subset. Using conditionals One may also operate over part of a set depending upon a conditional. For example the following statement Z=sum(thisI$nzz(thisI),1); would add up the number of elements in thisI that are associated with a nonzero value of nzz(thisI) as controlled by the conditional $nzz(thisI). The chapter on conditionals covers a lot more cases and provides a fuller description. Some particular forms of conditionals merit special mention in this document on sets. Conditionals can involve functions that return particular values depending on the position of elements in sets, the length of sets or the comparison of set elements to each other or text strings. These functions are defined in the section on functions below. Discussion of their use follows Sameas Diag Sameas and diag are functions that allow comparison of set names. Suppose I wish to add up shipments within cities. Further suppose I have an array move(origins,cities) giving the amount from origins to cities. In addition the within city are those in move(origins, cities) where the origin name is the same as the cities name. (sets.gms) Alias(origins,cities); Z=sum((origins,cities)$sameas(origins,cities),move(origins,cities)); or Z=sum((origins,cities)$diag(origins,cities),move(origins,cities)); Equivalently a statement like Z=sum((origins,cities)$(not sameas(origins,cities)),move(origins,cities)); adds up the shipments between cities. One could also operate over particular elements using these commands Available(resource)$(sameas(resource,”cropland”) or sameas(resource,”pasture”)).. Sum(activity,usage(resource,activity)*xvar(activity))=l= endowment(resource); where the sameas command would compare the text for the element name for each elements of the set resource with the string cropland or pasture and if so operate over that part of the resource set. Ord Card ORD and CARD are functions defined in the Conditionals chapter that allow knowledge of and special processing for the relative position of a set element within a set. Namely, I may also wish to do particular things if I are on the first or last or other elements of a set. The statement (sets.gms) stock(t)$(ord(t) eq 1) = initial; defines a constraint only for the first element of t. The command Carryout.lo(t)$(ord(t) eq card(t)) = final; only operates for the last element of t. Using tuples A tuple refers to a set defined over other sets. The set may either be a one dimensional subset or a multidimensional set. Tuples are useful in calculations and in imposing conditionals. Examples (sets.gms) One ca replace a sum that would go over all cases of a set with one that only operates over a subset. Namely in mZ=sum(r(mi),mx(mi)); the index r(mi) only operates over those elements in mI that appear in the subset r. Similarly in mQ(i_am_a_tuple (mI,mj) =mx(mi)+my(mj); the only the mi and mj cases which are operated over are those explicitly defined in the set named i_am_a_tuple. Finally, note that when using a tuple on both sides of the equation that one does not need to explicitly enter the component sets as follows mQ(i_am_a_tuple) =mQ(i_am_a_tuple )*1.5; where mq is declared as mq(mi,mj) in sets.gms but so is i_am_a_tuple so the mi and mj can be left out of the replacement statement and the replacement will operate over all mi and mj cases in the tuple. Universal set * as a set identifier Set references may be indefinite allowing any entries at all by referring to the universal set. This is done by either Using an * in stead of a set name in an item definition or Aliasing a set to the universal set (denoted by an *) and then using that set in item definitions. In either case domain checking is suppressed and any entry whatsoever may be used without error. Examples (sets.gms) Here I use the universal set in a number of places Set knownset /p1*p4/; Alias (newuniverse,*); Set a1(newuniverse); Parameter dataitem(*) data without fixed set assignments / Newitem1 1, newitem2 3/; Parameter dd(newuniverse); Dd(knownset)=4; Dd("newone")=5; Dataitem("newitem4")=dataitem("newitem1")*dataitem("newitem2"); A1("boston")=yes; where the blue and bolded items are all associated with universal sets and no domain checking is going on and new elements can be freely introduced . Notes Use of universal sets for data input items is not recommended as spelling errors will not generally be detected. GAMS will check in replacement statements to make sure specifically referenced elements have been defined and will give an error if not (setuniverr.gms). But this is not done in model equations. Sometimes this is useful in finding the sets over which data items are defined or in quickly formulating reports. Finding sets from data Sometimes it is desirable to find the set that characterizes an item then use it from then on. One may accomplish this by using an alias with the universal set and then compute set elements based on data using conditionals. Examples Consider the example trnsprt.gms where this is done using several steps. First I define sets without specifying elements (sources and places here) as equivalent to universal (unspecified) set. alias(sources,places,*) Then I enter data which contains an indicator of which set elements are valid entries in the set to be computed where in this case to be associated with the set sources the named place must have totalsupply. table trandata (sources,places) data from spreadsheet newyork chicago totalsupply seattle 2.5 1.7 350 Sandiego 2.5 1.8 300 totalneed 325 75 Now in preparation of set calculation I define subsets for the sets I will compute. These sets will be set to yes based on the data. set source(sources) sources in spreadsheet data destinaton(places) destinations in spreadsheet data; Then I compute the set elements based on the data. In this case a source is defined (set to yes) if that location has an entry for totalsupply and a destination is defined if that place has an entry for totalneed. source(sources)$(trandata(sources,"totalsupply"))=yes; destinaton(places)$(trandata("totalneed", places ))=yes; These sets can be used from then on. Such computations are useful if a report has been specified with indefinite elements but needs to be manipulated or if one gets in a data table from elsewhere which defines the problem dimensions (set elements). Using another name or an alias Alias There are occasions when one may wish to address a single set more than once in a statement. In GAMS this is done by giving the set another name through the ALIAS command as follows ALIAS(knownset,newset1,newset2,...); where each of the new sets will refer to the same elements as in the existing known set. Examples (sets.gms) Suppose I have a two-dimensional data item that addresses the same set in both dimensions and I wish to compute the cost from each place to each other as a function of distance. To do this I use an alias as follows Set place /p1,p2/; Alias(place,otherplace); Table distplace(place,place) distaces P1 p2 P1 0 4 P2 4 0; Parameter cost(place,place) cost data; Cost(place,otherplace)=1+5*distplace(place,otherplace); Element order and capitalization in output Set element ordering and capitalization are dictated by the general rules in GAMS for such items which is called the Unique Element List or UEL that is discussed in the Rules for Item Capitalization and Ordering chapter. The short answer from these rules is that the capitalization used is the first one seen in the program and the order is the order in which the names for the set elements first appear in the program. Functions specifically referencing sets There are four types of functions that are usable within GAMS that involve sets. These allow comparisons of set elements (sameas,diag), an indication of the relative position of a set element within a set (ord) and a count of the total number of elements within a set (card) . Ord ORD(setelement) reports the position of his particular setelement within the overall set. Thus the command thisX(ione)=ord(ione); will set thisx(ione) equal to one for the first element in Ione, two for the second etc; Notes 1. Ord only works with ordered sets. 2. Ord refers to the relative position of each element in the set not necessarily the order in which they are typed. In particular the order may be different as determined by the rules for set ordering. Ordered sets Unordered sets Ord and the leads and lags below only work on ordered sets. Such sets must have explicit element definitions and cannot contain calculated elements, only sets with a priori specified values. Unordered sets are those that are not ordered. Card CARD(setname) reports the count of the total number of elements within the set. Thus the command number=card(i); will set the parameter number equal to the count of the total elements in i. Note card works with any sets whether they contain calculated elements or not. Sameas SAMEAS(setelement,othersetelement) or sameas(asetelement,”text”) returns an indicator that is true if the text giving the name of setelement is the same as the text for othersetelement and a false otherwise. Similarly sameas(asetelement,”texttotest”) returns an indicator that is true if the text giving the name of asetelement is the same as the texttotest and false otherwise. SAMEAS can also be used as a set. Examples (sameas.gms) The following red use of sameas will only permit the case of cityI and cityj to be part of the sum where the elements for both are boston and do not require the sets to be subsets of each other. The blue use will only operate for the element of I associated with the name “new york”. Set cityI / “new york”, Chicago, boston/; Set cityj /boston/; Scalar ciz,cir,cirr; ciZ=sum(sameas(cityI,cityj),1); ciR=sum((cityI,cityj)$ sameas(cityI,cityj),1); ciRR=sum(sameas(cityI,”new york”),1); Notes The above examples show that sameas can be used as a tuple or a multidimensional set. Diag DIAG(setelement,othersetelement) or diag(asetelement,”text”) returns an number that is one if the text giving the name of setelement is the same as the text for othersetelement and a zero otherwise. Similarly diag(asetelement,”texttotest”) returns a one if the text giving the name of asetelement is the same as the texttotest and zero otherwise. Examples (diag.gms) The following red use of diag will only be one for cityI and cityj where the elements for both are the same (boston in this case). The blue use will only be one for the element of cityI associated with the name “new york”. Set cityI / “new york”, Chicago, boston/; Set cityj /boston/; Scalar ciz,cir,cirr; ciZ=sum((cityi,cityj),diag(cityI,cityj)); ciRR=sum(cityi, diag(cityI,"new york")); Indexing sets defined over time Special features are included in GAMS for use with sets that represent time. These involve leads and lags in both equilibrium and non equilibrium settings and the use of special functions for particular time periods Leads and lags + Some problems involve sets defined over time covering years or quarters or months. Often when operating with such sets one may wish to define carryover relationships. For example, suppose beginning storage in a quarter equals ending storage in a previous quarter. These operators only work with ordered sets. GAMS lead and lag features for set referencing are used as follows (dynindex.gms) Stockbal(t).. endstock(t-1)=e=beginstock(t); Where the -1 notation references the previous time period to the current one, or equivalently Stockbal2(t).. endstock(t)=e=beginstock(t+1); Notes The lead and lag can also use +2 to go two periods into the future or +someothernumber for other leads and –somenumber for lags. When th case identified by t-1 ot t+1 etc does not exist the term is just skipped. Thus in the stockbal example above no lag t-1 tem is defined for the first case of t and no t+1 case is defined in stockbal2 equation for the last set element in t. Circular or equilibrium leads and lags ++ -Some problems involve sets defined over time covering quarters or months. Often when operating with such sets one may wish to define carryover relationships where the year wraps around in an equilibrium fashion and beginning storage in January equals ending storage in December. These operators only work with ordered sets. Examples The GAMS equilibrium lead and lag features for set referencing are used as follows (dynindex.gms) Stockbal3(t).. endstock(t--1)=e=beginstock(t); Where the --1 notation references the previous time period to the current one and wraps to the last element when on the first element, or equivalently Stockbal4(t).. endstock(t)=e=beginstock(t++1); Notes The lead and lag can also use ++n (--n) to go n periods into the future (past). When a case t--1 or t++1 etc does not exist the reference wraps restarting at the top or the bottom. Element Position Dynamic models often lead one to need to specify initial, terminal and normal operating rules. For example, given a model defined over years one could want beginning storage in year one to equal Initial storage, ending storage in the last period to equal a fixed amount and initial storage in the years in between to equal carry out storage from the year before. Thus is commonly imposed using CARD and ORD. In such a case one could impose the following (dynindex.gms) Storecarry(t).. Beginstorage(t) =e= initial$(ord(t) eq 1) +endstorage(t-1); Termstore(t)$(ord(t)=card(t)).. Endstorage(t)=e=finalstore; Set Arithmetic Arithmetic like set operations can be performed over sets that are a subset of a common superset to form set unions, intersections, complements, and differences Unions Set unions can be formed using an addition type operation namely (setarith.gms) Subset3(superset) = Subset1(superset) + Subset2(superset); The membership of subset3 contains all elements that are either members of subset1 and or subset2. This operation is equivalent to the statements Subset3(superset)=no; subset3(subset1)=yes; subset3(subset2)=yes; Intersections Set unions can be formed using a multiplication type operation namely (setarith.gms) Subset3(superset) = Subset1(superset) * Subset2(superset); The membership of subset3 contains all elements that are members of both subset1 and subset2. This operation is equivalent to the statements Subset3(superset)=yes$(subset1(superset) and subset2(superset)); Complements Set complements can be formed using the not operator (setarith.gms) Subset3(superset) = not Subset1(superset); The membership of subset3 contains all elements that are not members of subset1. This operation is equivalent to the statements Subset3(superset)=yes; subset3(subset1)=no; Differences Set differences can be formed using a subtraction type operation namely (setarith.gms) Subset3(superset) = Subset1(superset) - Subset2(superset); The membership of subset3 contains all elements that are in subset1 but not in subset2. This operation is equivalent to the statements subset3(subset1)=yes; subset3(subset2)=no; Alphabetic list of features * * $ -+ + ++ ' " / Alias And Capitalization Card Complement Defining sets from data Element definition Diag Difference Domain checking Dynamic set Element order Intersection Multi dimensional set No Not $Onmulti Ord Order Ordered set Set Symbol that when used in set declaration is indicator of universal set. Symbol that will carry out set intersection. Symbol to set off conditionals, use in set references. Symbol that is operator to form set difference. Symbol that signifies a lag operation in a set. Symbol that signifies a circular lag operation in a set. Symbol that signifies a lead operation in a set. Symbol that will carry out set union. Symbol that signifies a circular lead operation in a set. Symbol surrounding set element name or explanatory text that must appear in pairs. Symbol surrounding set element name or explanatory text that must appear in pairs. Symbol to set off explicitly defined set elements. Command giving more than one name to a set. Operator to form set intersection. Font case structure that will be used in output. Function that returns total number of elements in a set. Elements that are not in a set. Method to compute sets based on data. Act of putting data or elements in a named item. Comparing text defining set elements. Elements that differ between sets. Act of checking if referenced element is in fact in set or if item is defined over named set. Calculated set that cannot be used as a domain. Order set elements will appear in output. Method to define common set elements. Set that is defined with respect to more that one other set. Special value that indicates an element is not in a set, can be used in assignment statement. Operator to form set complement. Allow multiple declarations of a named item. Function that returns position number of set element in total set. Order of set elements as they will appear in the output. Set that has ordered elements and can be used with Ord, leads and lags. Command that specifies a grouping of named elements. Sets Subset Sameas Tuples Uel Union Unique element list Universal set Unordered set Yes Command that specifies a grouping of named elements. Set made up of all or part of elements of another set. Comparing text defining set elements. Set that is defined with respect to more that one other set and can be used in controlling sets. List of all set element names in model. Method to define total set of elements across sets. List of all set element names in model. List of all set elements names known to the program in order and capitalization that they will appear in output. Set that has ordered elements and cannot be used with Ord, leads and lags. Special value that indicates set element membership, can be used in assignment statement.