16) Decoding Matrix Row and Column Names

Every variable and equation in an LP matrix generated via GRTMPS has a unique name built from user assigned codes and internal elements.  You will see these names if you look at the matrix (output files MTX, ROW or BCD),  the optimizer output (which can be seen in LST, SPR and SPA) , the infeasibility or largest marginal value sections of the RPX, etc.   Some of these output files include your descriptions for objects such as stream and property codes that are included in the names, but there isn’t enough space to say it all.   Here is a guide to identifying some common types of rows and columns generated by GRTMPS 5 – with a quiz at the end to see if you’ve got it.

Some names can be identified from fixed elements and length; others you need to parse and consider what parts you recognize.  The first point about reading the names is that since most variables and constraints apply to specific times and places, most of them start with location and period codes: (LL)(PP).   (If you are using table based input with g5, then the data might use the older g4 or g2 coding systems where the location and / or period were only 1-character long.  If so, the codes will be doubled up as the data is read, so that the matrix row and column names have two character codes.)  As well as the user defined location, location group, and period codes that are given in the data, you might also see XX in in row names for limits that include options from more than one location, and/or period.  

 

Here are some row types, that are likely to appear in refinery models.

 

R1AASTMUTB	UTB at the end means a utility balance row, so R1AASTMUTB is the balance for utility STM  at location R1 during period AA.
R1AALNP_~BAL TKBBA3#6#BAL R122A3brtBAL	BAL as a suffix is a stream material balance row, e.g.  R1AALNP_~ BAL is the balance for stream LNP at R1 during AA.  Most stream codes used in the model input data are 3-characters long and have additional padding to make them 5 characters.  Different padding is used for different types of objects, so that can also be used to interpret them.  Most streams are padded with "_~", but pools are usually "5#" or "6#".  For example TKBBA3#6#BAL is the balance for the pool A3# at location TK in period BB.  Crude specific streams have the associated crude code, rather than padding, so R122A3brtBAL, is the balance at R1 for the A3* from crude brt in period 22.
TKBB95R_~FXWT TKBB95R_~FXVL	FXWT and FXVL also indicate stream balances – in this case the weight and volume balance between blends, such as 95R, and their components.  Products and pools have these in addition to their BAL row.
R1AACDU_]PL R1AAcpc00PE	Process Limits stand out for being shorter than most other rows, and ending with P(M), where M is G, L or E – greater than (MIN), less than (MAX), or equal to (FIX) – and indicates the direction of the constraint.   So R1AACDU_]PL is the maximum on limit CDU at R1 during period AA.  Process limits are also usually 3 characters when entered and padded with "_]".    Crude specific limits also exist, often as part of depooling controls, and have the crude code instead of padding.  R1AAcpc00PE is the fixed constraint on ?00, for crude cpc.
22JY95R_~SUL_)L 22JY95R_~ALK_~G R1AAOHD5#OHbrtQ TKBBa3#6#DNX_)Q TKBBa3#6#DNX_)V	Here are some of the row types related to blending.  They all start with (LL)(PP)(PRDSS) where PRDSS is the stream code, padded to 5 characters.  The next part is usually a quality code, padded with "_)", but can be a stream code if the equation is a control on composition.  Crude specific streams and properties will be 5-characters long and you might not be able to tell whether it is a property or component without looking in the data.  The last character tells you what sort of row it is.  So 22JY95R_~SUL)L is a maximum SUL specification on product 95R for location 22, period JY.  22JY95R_~ALK_~G is the minimum percentage of stream ALK in product 95R.   Pools have “Q” quality balance rows, to track the difference between assumed and actual.   TKBBa3#6#DNX_)Q tracks the DNX property of A3# at location TK during period BB.   U or V rows, such as TKBBa3#6#DNX_)V, are step bounding structure.

 

 Some common column (vector) names have helpful unique fixed elements too, and it is also useful to consider length, and if user code elements are streams or properties.

0AAPR1TK95R_~	If you see something that starts with 0 instead of a location code, that’s a transportation option.  The period comes next, then the transport facility, source location, destination and stream.  That is 0(PP)(T)(LL)(LL)(STRSS), so our example is the movement of 95R from R1 to TK via P, in period AA.
RR..ALK_~I RRAAALK_~FI RRAAALK_~TI	Short names that end in “I” (capital letter I) are inventory.  Here for stream ALK, we have,  in order: opening inventory with special internal period code .., movements from inventory (FI) and movements to inventory (TI), at location RR, period AA.
TK03ARL_~BRX R103HG#6#SAX	Vectors for Purchase and Sales are (LL)(PP)(STRSS)(PS)X.  The last three characters are the account code, which always ends in X.  To determine if a vector is a purchase or a sale you need to look at the account definition in the input data, or the sign of the intersection with the balance and cost rows.
R1AAFCCFDA_^ R1BBCDUARL1A	Process unit operations can usually be spotted by the "_^" padding that converts the mode name to 5 characters.  R1AAFCCFDA_^ is the variable for operation FDA on unit FCC, at location R1, period AA.  Note that the process units are identified by the first 3-character part of their UNT-TN name.  Crude specific modes, such as R1BBCDUARL1A,  will not have the padding, but can be distinguished from blend vectors by their length, and the absence of any stream or property padding characters.
RRAA95R_~ALK_~ RRAA95R_~RE#5#	Component-to-Blend vectors are the longest at 14 characters, as they contain both stream codes - first the blend, then the component.   RRAA95R_~ALK_~ is ALK blending into 95R at RR, period AA.   The second example shows the pool RE#5# also blending into 95R.

 

Got it?  Try your hand at this little quiz.  (Answers at end)

 

1) What row will be generated by this bit of input data?

 

2) Which row of data generated the vector P2Y2PRO_~SAX?

 

3) Which of these vectors could not come from this model? a) R1NVFCCRDA_^   b) 11AAPRO_~TI   c) 0P2P1122LNG_~

 

4) Here are a blend, a process and a sales vector - which is which?

     11AA2CDWTX2X      11AAWTX_~ZUX    11AA2B#6#2BWTX

 

 

 5) Based on these row names which stream(s) must be  pools, bearing in mind that pools don't necessarily have # in the name or padding in the latest version of g5?

     a) R1P1GS1_~FXVL      b) R2P1LPG_~C4#5#L    c) KK1195R_~SUL_)Q   

 

Answers at the bottom.

 

This has just been an introduction to the naming system.  For a more complete description of the code rules and names have a look at the Modelling Reference Guide (accessible under the Help Menu).  In Chapter 1, read the section on  Code Definitions, and then look at Chapter 9: Matrix Nomenclature.  The Annotated Solution print (SPA) file will contain the most complete descriptions for the names in your matrix (activated with the Extended Reports).