NMOD Primer Ch 11

In the next chapter (Working with Visio interface and NET file) we will be discussing how to express content logic to be executed in nodes and arcs of ORMSware networks, drilling further into the nuts and bolts layer of modeling with NMOD. To prepare you for that discussion, we need to explain first how to interpret various notations used in contents of nodes and arcs.

This chapter is long and very involved, but it explains some of the capabilities of NMOD which make it a powerful modeling-programming hybrid product. If you are going to really get excited about NMOD, here is where it is going to turn the corner, ready for acceleration. If you get through this chapter, you will in all likelihood finish this primer as well as the Hands-on Tutorial.

ORMSware uses braces ({}) to denote entity properties, network object properties and certain special functions. They are also used to envelope property constants, expressions, and collections of statements entered through network object dialog boxes in the Visio interface.

Close Figure 10 window if it is still open. Click Figure 11a and Figure 11b below to open windows showing a newer version of our example model and its NET file.

Displays in these windows will help us get through the discussion of property notations. We will explain the newer version of the model and details of the content logic (NET) file later. For now, let us focus on notations in content logic.

Notes

If the reader has hands-on experience with Visual Basic, C++, Fortran 95 or similar languages, all of NMOD will be a breeze. If not, the rest of this primer may at times require sitting up a little! However, anyone with an affinity towards logical/quantitative modeling, or enjoys seeing a good model in action, is likely to find at the end of the day that the NMOD paradigm is easy to understand and that modeling with NMOD is quite intuitive.

Notice in Figure 11a the use of Role property to push some of the arcs into the background of viewer's consciousness. Objects playing Primary Roles communicate quickly the essence of the model. Notice also that there is now an OR arc leading into the middle node on the right (Machine cost), which is a Convergence node. You will see how all of this works shortly. And, later in this primer, we will also show you how to make support arcs completely invisible using Temporal Arcs so that only the essence of the model is displayed.

When ORMSware Translator/Preprocessor (called NETrans) sees a left brace in a content logic statement (e.g. as in {cp.D}WearCoeff), it expects to see the following in the case of entity properties:

For example, using the above rules, when NETrans sees {cp.D}WearCoeff, it translates that string as follows:

If there are spaces anywhere between { and the end of the name, current version of NETrans will translate a property notation incorrectly.

Global, Customer, Surrogate and System properties are the most frequently used properties in NMOD, and their notations are gp, cp, sp, and sys, respectively. To make it easier to denote them without the braces, NMOD permits short forms as illustrated in the following examples:

In the current version of NMOD data types can be five KINDs of integers, two KINDs of real (floating point), logical (binary), or character string. If we use WearCoeff in all cases for illustration purposes and show a surrogate property of all types, they would be:

Notes

1. The type in item 9 above may seem odd, but here is how it works. Since the characters between property type indicator and the period is a number, NETrans will deduce it to be a 13-character string property. There are no restrictions on the number of different string properties and the number of characters per string one can use in any model. String property notation is explained in more detail a little later.

2. If a model actually contained all of the variables above, there will be no conflict or ambiguity as NETrans will declare them, according to the data type indicated by the user, prefixing each property with unique three-character Hungarian notation. However, for practical purposes, it is advisable to keep to a minimum such use of same property name with different data types.

3. We will be changing the use of braces slightly starting with the next version when it comes to notating properties of entities, network objects, etc. The structure will be similar to the short form for global, customer and surrogate properties in that the type denotation will come before the period. Since the number of symbols (such as $, &, # and @) available to denote various properties is limited, we will use braces to envelope character sequences with special meanings. This will give us the degrees of freedom necessary to create and permit limitless entity types and structures. For example, {u.nop}L.Labled could denote a logical/binary type user-defined network object property named Labeled.

In the above list, the data type of item 1 is the default integer a Fortran 95 processor provides on any given computing platform. In the case of a PC with 4-byte word, 32-bit architecture, the largest magnitude possible with one word of storage for an integer is -1 + 2 ** 31 while using the Lahey Fortran 95 processor. It should be safe to declare an integer property using this KIND, since all bigger platforms to which a model may be ported is likely to have the same or higher number of bits per word.

Regardless of what KIND of integer and real types below you use in your models, this KIND feature of ANSI Fortran 95 will ensure that your models running one one platform do not abort or produce inaccurate answers due to differences in word sizes. The KINDs used in NMOD are defined as below:

KIND indicator	Nickname	Data Type	Guaranteed largest magnitude (See Caution below)	Precision (mantissa decimals)	Reference
I	Integer	Integer	Default integer range offered by any given F95 processor		item 1 in list above
T	Tiny	Integer	10**2 = 100		item 2 in list above
S	Small	Integer	10**4 = 10,000		item 3 in list above
R	Regular	Integer	10**9 = 1,000,000,000		item 4 in list above
B	Big	Integer	10**18		item 5 in list above
S	Single	Real	10**37	6	item 6 in list above
D	Double	Real	10**307	15	item 7 in list above

Caution: It is a common mistake to assume that declaring a numerical storage to be a particular KIND (let us say, T) would ensure that if the magnitude of a number exceeds 100, the program will flag an error. The purpose of KIND is to prevent a program from aborting when ported to different (computer) platforms and (F95) processors, when the underlying architecture of the target is not large enough to hold a number that was stored without any problems while running on the original platform. In other words, a given KIND will ensure that sufficient number of bits in the target architecture will be used to represent any number declared using that particular KIND.

The easiest way to understand this is perhaps to think in terms of the default INTEGER on (say) a 32-bit platform. Let us say that the biggest default integer magnitude on this platform is -1+2**31. Suppose we port the model to another platform where the biggest default integer magnitude is (for argument's sake) -1+2**28. During a model run with an integer variable that is calculated to have a value > -1+2**28, but less than -1+2**31, will abort on the target platform though it executed fine on the original platform.

Declaring numerical variables using the KIND attribute allows us to be confident that a model running normally on any platform will not abort on any other problem due to inconsistencies in word sizes, precision of mantissa, etc. as long as the magnitude of a number of a particular KIND is less than or equal to the upper limit for that KIND. The developer of the program can define a KIND in anyway s/ he chooses. The KINDs we have defined are shown in the table above.

Think of this as a warranty. It guarantees performance up to a certain limit. You may be able to go beyond the limit under certain circumstances, but it is not warrantable. But, performance up to the limit is guaranteed with 100% certainty.

13 in item 9 above implies that the property is a 13-character string. To describe this in general terms, if we wanted to use a n-character string to store values of this property, we would call it @n.WearCoeff. Moving back to specific from general, if we wanted the property to be stored in a 93-character string, we would call the property @93.WearCoeff, and so on.

You will see in Chapter 16 (Using Microsoft Excel for inputs) an example of how NMOD's Translator declares string variables based on this notation. You can also see in Example Problem 1's NET file how we used a 255-character Global property (search for &255.LinePad) to push the travel history of a surrogate into a chain of notes.

Network objects in NMOD are nodes and arcs. Properties of nodes and arcs are predefined as shown in the table below (data type P for a property indicates that it is a Procedure property):

Network object property (nop)	Data type	Node	Arc	Description
Branch	L		x	Flag showing whether Branch property of a given arc evaluates to True or False
Flow	R		x	A 5-element vector property. NMOD uses only the last element known as the AND-arc Multiplier property. Data type indicated in column 2 is that of the multiplier element of the vector.
Merging	P	x		Procedure property for executing merging logic when all required AND incidents for convergence at a Convergence node have occurred
Duration	D	x	x	Logic that evaluates to a number showing how long a surrogate is to remain at a network object
Trans	P	x	x	Procedure property for executing transformation logic in any given node or arc
SignalTarget	P	x	x	Procedure property for creating and executing signals/temporal arcs connecting any node or arc to any other node or arc (including itself); also, often used to execute post-event logic associated with network objects.

The best way to understand nop notation is to look at a dialog box of a node in our Visio interface as well as its corresponding code block in the content logic file for the model. A dialog box of a node is shown below. We changed its Name property to WearParameters and entered some content ({&S.WearCoeff = 0.1; &S.WearExpon = 1.8}) in the text box for its Trans/control property. Its corresponding code block created by NETrans is displayed further down in this chapter. We will get to that momentarily.

As many logic statements as desired can be entered between the braces, separated by semicolons (;) as can be seen in the highlighted text in the dialog box. However, the total string within the braces must not be longer than 254 characters. As a practical matter, however, it is better to limit the entry in text boxes pretty much to the visible width of the boxes. More logic relevant to a field can be entered separately in a model's NET file.

Notes

The file for storing content logic of a model's network(s) is called the NET file. The name we have given our example model is Primer. So, its NET file will be named Primer.NET by NETrans.

If a Primer.NET file already exists, NETrans will, back it up to a file called Primer.NBK, update Primer.NET with entries from the dialog boxes exported by Visio, and translate the updated Primer.NET to create a compilable source file for the model (and name it Primer.F95), portable to any platform with a Fortran 95 processor.

Let us examine now the relationship between entries in the dialog box and the corresponding code in a model's NET file.

We wanted to create a node for wear and tear parameters in our example model. So, we decided to call the node WearParameters and entered it in the text box for the Name field in the dialog as explained earlier.

Looking at the bottom of the diagram in Figure 11a window, you can see that Visio gave this node an object ID of 1. When we exported the network from Visio and ran it through NETrans, it created a code block labeled {Object.1} CostPerPiece.[1]WearParameters as shown below. Notice the + and - signs preceding the label at the beginning and end of the code block for the node.

We were only concerned with setting the values of the wear-and-tear coefficient and wear-and-tear exponent in this node. We entered the logic statements for doing both in one line in the text box for Transformation/control field, separating the statements by a semicolon.

NETrans inserts a property's dialog box entry right after the beginning delimiter record of that property in NET file. When inserting dialog box entry in the appropriate code block in NET file, NETrans also precedes the entry with a network object property notation (see {nop.P}Trans: preceding the statement in the code block of n[1]'s Trans property). If we run NETrans again to translate the next export of the model from Visio, it will replace this statement with whatever happens to be the corresponding statement in the new export.

Alert: A common mistake is to modify the first line of a property inserted by NETrans in the NET file (which is the entry through the Visio interface). Every time NETrans is run against a NET file, it updates {nop...}-prefixed first line of every property with whatever is in the corresponding Visio export. Because we do not have an IDE, it is easy to make this mistake and wonder what happened to the changes one made in the NET file. Any desired change to those lines should be made in Visio and then exported before NETrans synchronizes the latest available Visio report of a model with its existing NET file and updates the NET file.

As you have seen, the text block above shows how NETrans inserts information entered in the dialog box into the code block in Primer.NET for CostPerPiece.n[1] as well as certain enveloping information. Specifically, NETrans did the following:

Procedure properties Procedure properties cannot be set equal to any value. It is a property that holds a procedure which NMOD executes when an object is fired (i.e. activated).

A procedure property may have just one line of logic/expression, many lines of logic, or no logic at all.

If there is only one line, it can be entered in the dialog box as you have already seen.

If the procedure has more than one line of logic, the analyst indicates this by adding ellipses (...) in the dialog box immediately following the right brace enveloping that property (see at left highlighted text in the image of the arc dialog box for [15] in our Primer model). And you can see below the additional code for its Branch property entered into the NET file by the analyst. Note, however, that Branch is a scalar property, not a procedure property. But the analyst has nevertheless entered code into [15]'s Branch property block as if it were a procedure property. We will pursue this topic a little further down.


  !----------------------------------------

  +{Object.15}CostPerPiece--->|PiecesPerHour
    +{Branch}
      {nop.L}Branch={&L.CurveBuild}...
      {nop.L}Branch = {nop.L}Branch .AND. @B.PiecesPerHour < &B.PiecesLim
      WRITE(9,*)"&L.CurveBuild,@B.PiecesPerHour < &B.PiecesLim,{nop.L}Branch:", &
      &L.CurveBuild,@B.PiecesPerHour,&B.PiecesLim,{nop.L}Branch
    -{Branch}
    +{Trans}
      {nop.P}Trans:{@B.PiecesPerHour = @B.PiecesPerHour + &B.PiecesIncrement}
    -{Trans}
  -{Object.15}CostPerPiece--->|PiecesPerHour
  !----------------------------------------

Note: In the planned IDE, the user will simply click on an ellipses button to open up the corresponding block for entering additional lines of code, but still will be able to view as much of the overall code as desired. Also, note that NETrans identifies a line in a property block as one that it had previously inserted there when it sees that the right-hand side of a {nop} statement is enveloped by {}. If you look at the Branch property block above, you will see two {nop.L}Branch statements. The RHS of the first one is enveloped by {}, while the next one is not. NETrans recognizes the first one as a previous entry through Visio dialog box and the second line as one that was put directly into the NET file by the user.

Scalar properties Notice that when NETrans inserted the branch condition of CostPerPiece.a[15] from the dialog box into the NET file, it preceded the statement with {nop.L}Branch= rather than {nop.L}Branch:. Since Branch property is logical (binary) type variable, it can be set to a logical constant, variable, function or expression on the right side of the equal sign.

NMOD is not concerned with what the analyst does in the logic inserted after the first line of a scalar property. The analyst can accomplish whatever s/ he wishes in those lines of code. NMOD will execute the logic as if it were executing a procedure property.

The branch condition will remain as it was evaluated in the first line of the property code block until and unless NMOD finds and executes another {nop.L}Branch= statement in the block. The right-hand-side of the branch statement can be any logical (binary) constant, variable, function or expression, or {nop.L}Branch can be used as an actual logical argument in a call to a user-defined procedure (subroutine).

Once again, take a look at the first two lines in the Branch property code block. Both records have {nop.L}Branch on the left of the = sign. So, how does NETrans know that the second line was entered by the analyst in the NET file, and what the analyst did to make sure that the final value of the Branch property is properly evaluated?

We will elaborate on what we mentioned in a Note earlier. Notice that the first statement, which was put there by NETrans to begin with, is enveloped with {} and the left brace is immediately to the right of the equal sign. On the other hand, in the second line even if the analyst had put { immediately after the =, the left brace's matching right brace is not at the end of the line. Since there are no matching left and right braces after the = sign enveloping the statement, NETrans knows that it is not the entry from that arc's Visio dialog box.

When you actually starts modeling with NMOD, all of these technical details as to how NETrans recognizes this and that seldom come up, if ever. We included it here primarily to satisfy the curious.

Notice that even if branch condition evaluates to False, thereby preventing dispatch of a surrogate along the arc, the logic imbedded in the Branch property of the arc will still execute. Therefore, in the case of PiecesPerHour.a[15] in our example model, the WRITE statement in the Branch property code will always execute, unconditionally.

Common practice is to use procedure properties to manipulate entity properties, scalar variables, and arrays as well as to call user-supplied procedures, and procedures exposed by NMOD. Other than predecessor-successor relationships, transformation procedure property is the most common property analysts use to shape the formulation of a model, as well as to control its behavior. However, as you can imagine from what we just explained under scalar properties , analysts can figure out ways to use any property block to manipulate the structure and functionality of a model.

In order to fully exploit code blocks of properties in that manner, it is necessary to understand when a given network object property is executed by NMOD. We will explain this in upcoming chapters.

Note: Procedures can be supplied by user in source or object form. User can also supply procedures by creating an ADD file for the model. As many procedures as desired can be included in the ADD file. Sometimes it is useful to supply the procedures through ADD file, because ADD file can contain ORMSware notations. When NETrans preprocesses a model, it checks to see if an ADD file exists for the model. If one exists, NETrans translates it. ADD file is explained further in Chapter 17 (User-defined scalars, arrays, derived types and procedures).

When ORMSware encounters nop notations, it considers them to be about properties of the object in which the logic is imbedded. For example, the {nop.P}Trans procedure property defined in {Object.15}CostPerPiece--->|PiecesPerHour as shown above obviously refers specifically to the Transformation procedure property of CostPerPiece.a[15].

There are only two network object property values analysts can set using the nop notation. They are {nop.L}Branch in arcs and {nop.D}Duration in arcs as well as nodes. As for procedure properties, in addition to Trans procedure property, analysts also have control over the content logic of Merging procedure properties of nodes, and SignalTarget procedure properties of both nodes and arcs.

There are other network object properties which user can access from any property field in a dialog box or any code block in NET file. However, those network object properties cannot be altered programmatically (i.e. cannot be altered from within content logic), but some of them can be changed in the Visio interface (e.g. Type properties of network objecs) by structuring model network(s) accordingly.

Network object Property	Data type	Node	Arc	Description
Page	R	x	x	The Visio network page on which the object is located
ObjectID	R	x	x	ID assigned to object by Visio
Type	T	x	x	Node type/arc type, set in Visio by analyst
Name (node)	25 char	x		Name assigned to node in Visio by analyst
Orig	R	x		Number of arcs originating from a given node, inferred by NETrans from network(s) constructed by analyst
ArcSeqOut	B	x		Arc sequence number(s) assigned by ORMSware to arc(s) originating from a given node
Term	R	x		Number of arcs terminating in a given node, inferred by NETrans from network(s) constructed by analyst
AndTerm	R	x		Number of AND arcs terminating in a given node, inferred by NETrans from network(s) constructed by analyst
NetPage	R	x		Page number of the subnetwork referenced by a given node (applies only to nodes of Network type), inferred by NETrans
Name (arc)	56 char		x	Arc name ORMSware derives from names of the originating and terminating nodes of any arc, its Visio-assigned object ID and the Type property of the arc
Orig	B		x	An arc's origin in terms of sequence number assigned by ORMSware to node from which a given arc originates
Term	B		x	An arc's destination in terms of sequence number assigned by ORMSware to node in which a given arc terminates

These properties can be accessed only through functions provided by NMOD to protect them from being altered by the user during model execution. You will find a table of these functions in Appendix A. If you need a function not listed there, please contact us for assistance.

Notation of properties