Quick hands-on tour of NMOD modeling process

In the coming chapters you will build from scratch the model used in this tour, but we have already set it up here under a different name to easily lead you through the process, giving you a quick feel for how NMOD modeling works.

You may find it helpful to look in Chapter 1 (Models and logical networks) and Chapter 2 (NMOD atom and ORMSware networks) of the Primer as you proceed through this chapter. Some people also find it more helpful to do Chapters 3 and 4 of this tutorial before going through this chapter, because this chapter is more or less passive, working with a model that is already built, while 3 and 4 get one involved in actively building a model from scratch. At any rate, be sure to complete this chapter as it contains important concepts that are essential in building any model of significance.

In this chapter you will learn the following (though not necessarily in the order listed):

• Launching Visio from browser

• NETransing models (translate ORMSware notation to compilable source) and create EXEs of models

• Running/executing models

• Working with ORMSware's Visio dialog boxes for entering network object properties

• About automatic synchronization of Visio file and complementary NET file of a model

• Performing reference check on any given item of interest in the model

• Process of tracking down logic errors in models

• Jumping directly to NETrans errors in a model's NET file

• Jumping directly to model content in NET file causing compilation errors

• Setting up a model's own optional configuration/modeling environment parameters file

• Setting up ORMSware's default configuration file for all models without their own parameters file

• Menu option for producing a model's network objects report from Visio

• Inserting comments in NMOD files (NET, and optional ADD and PGM files)

• Inserting WRITE statements as desired to write to screen and/or external files

• Using Echo notation ({?|x}) for tracking variable/property values

• Column-shifting a block of logic in NET file

• Unconditional execution of logic on conditional arcs

Bring up UltraEdit for ORMSware from the ORMSware browsing shortcut you set up in in Chapter 1 (Section 2). UltraEdit Browser tailored for ORMSware comes up as shown in the image below:

If this is the first time you are launching Visio from the browser, please turn to instructions in Chapter 1 for installing Visio (Section 4) and set it up for use with ORMSware and come back to this point.

If you have already launched a Visio session, but did not launch it from UltraEdit browser, please close Visio now. We will open it from the browser.

From the main menu of UltraEdit, choose Advanced - Launch Visio for ORMSware. If Visio asks whether to enable macros, click the button to do so. Visio will come up with c:\ORMSware\ProgramFiles\ORMSware.VSD preloaded. Close this file for now. 

From the main menu, choose Advanced - Launch Excel with default config. Microsoft Excel will come up with c:\ORMSware\ProgramFiles\NMOD.CFG.htm preloaded.

Let us open Visio file of a model we will be working with during the rest of this chapter.

Press Ctrl-O (or choose File - Open from main menu, or click File-Open icon in the tool bar) and navigate to c:\ORMSware\Tutorial\Chapter2 folder. Choose tPrimerTour.VSD file.

Visio displays tPrimerTour.VSD file. Notice the Network name object at the top of the page. It displays the path along with the name of the model's file.

Save the file now to c:\ORMSware\Play folder. The path name changes in the Network name object at the top. Check the model out to satisfy your curiosity. Play with it to your satisfaction. When you are ready to proceed, close the file and retrieve the original model from the c:\ORMSware\Tutorial\Chapter2 folder again. Save it now into c:\ORMSware\Tutorial. If there is already another tPrimerTour.VSD in that folder, overwrite it.

Pretending that we have put this model together from scratch, let us export it for translation and further development as necessary. You will see a problem with the model when we execute it. We will discuss it, switch back to Visio to fix it, and go through the process again for the first successful run. 

Switch back to the browser window. We can now NETrans (translate using NETrans.EXE) the model. NETrans creates, structures and synchronizes a model's supplemental file (.NET file) for entering additional problem description logic that we cannot enter (or we do not want to enter) in ORMSware's Visio interface.

Instead of just creating the NET file, we also have the option of evoking a process that will take the model as far as possible through translation, compilation and linking to executing the model. This process will abort automatically if it does not make sense at any point along the way to proceed due to errors that need to be fixed.

So, let us choose that option now instead and see how far we can go.

Choose Advanced - NETrans + Compile.Link.Run from the main menu (it does not matter which file the browser is currently displaying). A black command window will open displaying status messages as the modeling process manager executes a chain of tasks moving from translation through compilation and linking to execution. When the process stops all of those status messages and output (if any) from the model will be displayed in the output window at the bottom of the browser.

When the run is complete, you will see the following message displayed towards the end of the messages in the output box:

***Alert: Reached requested safety limit of 1000 events

The Alert message above is the error condition we said we would encounter as we were getting ready to generate the report from Visio. To understand the cause of this Alert message, switch to Visio window. We will jump the gun and take you directly to the problem which is a common mistake analysts make. The problem is infinite cycles or loops. You will know what causes cycling and what to check in a model under similar circumstances by the time you finish this tutorial.

Double-click a[15]. The Branch property says: {&L.CurveBuild}...

Without getting into details at this point, what {&L.CurveBuild}... means is that execution will continue along [15] to n[2] if:

&L.CurveBuild has a value of TRUE and if whatever other resultant condition the analyst meant to define in the NET file of this model also has a value of TRUE. That the analyst meant to include more logic in this arc's Branch property is indicated by the ellipses (three periods/dots) after the right brace.

You will see that this Branch condition always evaluates to TRUE with the way things are currently in the model, causing an infinite loop.

Let us leave this dialog box up and switch to the browser to learn what causes the infinite loop.

We need to bring up tPrimerTour.NET in c:\ORMSware\Tutorial folder. We can do this, among other common ways, by using the file tree window of the browser (left side) or we can use the following method:

Look in the output window at the bottom of the browser for the file that interests us. The file of interest to us at this point is c:\ORMSware\Tutorial\tPrimerTour.NET and you can see that name displayed towards the bottom of the output window. Double-click it. The browser displays the file in the main window.

Page down to Object 15.

You can see that there is nothing below the definition of Branch property after &L.CurveBuild (i.e. the analyst has not put in any additional logic to influence the value of Branch property beyond whatever the value of &L.CurveBuild may be. But, what is the value of &L.CurveBuild when it is time to consider traversing this arc and where is it defined?

We can get a quick list of all of the network objects and their properties in which &L.CurveBuild is either defined or used. To get broader coverage just in case we used L.CurveBuild as a customer or surrogate property, or even of another data type than logical, we may want to search just for CurveBuild.

To get the list, highlight just CurveBuild by double-clicking it in c:\ORMSware\Tutorial\tPrimerTour.NET in the main window of the browser. Then choose Advanced - [ Reference check ] from the main menu. You will see from the results displayed in the bottom window that it appears only in [15]; that while it is used in [15], it is not defined anywhere.

With its value not explicitly defined anywhere in the model it apparently happens to have randomly taken on the value of TRUE when model execution began. If you did not get the safety limit message earlier, this is the reason; the random value &L.CurveBuild took on when the model run was initiated on your computer happened to be FALSE.

The 1000 events safety limit mentioned by the message earlier came from the configuration file for this model. We have the option of setting up individual configuration file for a model, or using a default configuration file (Excel worksheet NMOD.CFG.htm) available in c:\ORMSware\ProgramFiles folder for any model for which we choose not to set up its own configuration file. NMOD will automatically use default configuration if the analyst does not set one up for a given model.

To see the contents of default configuration file, open it from Excel (c:\ORMSware\ProgramFiles\NMOD.CFG.htm). Notice the 1000 on the record for Max number of events (in cell b10). If it weren't for this barrier, the model would have run away from us, since we had not explicitly set the value of &L.CurveBuild anywhere and it had randomly taken on an initial value of TRUE.

Right below Max number of events in the spreadsheet is the parameter value of another safety device. It allows you to keep a model from running past a time boundary. The role of conceptual time in modeling is explained in Chapter 19 (Reinforcing concepts through PrimerSig's feedback file) of the Primer.

It is always a good idea to set a Max events barrier when starting a new model to prevent potential infinite cycling due to oversight while formulating a model in the beginning of a project.

Let us fix the &L.CurveBuild problem now so that the model calculates CostPerPiece only once. Switch to Visio window. The dialog box we left open earlier is, of course, still there.

Entering model logic/network object properties in Visio

Let us position the cursor in c:\ORMSware\Tutorial\tPrimerTour.NET in the middle of {Object.15} so that we can immediately see the effect of NETrans on this arc in NET file.

Write the report from Visio as before, but this time let us execute Advanced - Just NETrans in the browser to see what happens to the logNo we added earlier in Visio.

You will see [15]'s Branch property change, reflecting the modification we made in Visio.

Let us now change the Branch property statement, back to the way it was before right here in the NET file; delete logNo !. Now choose Advanced - Just NETrans. Move the message box out of the way if necessary and watch what happens.

The logNo ! has reappeared! This is because NETrans does not permit changes to the property statements entered in Visio to be changed anywhere other than in Visio to ensure data integrity (because at this time we do not have roundtrip link between contents of Visio and NET file). We will discuss this further a little later in this chapter.

Having blocked [15] with logNo now, let us compile and run the model to see if the cycling problem is gone.

Choose Advanced - Netrans + Compile.Link.Run. A command window will open displaying status messages, the model will execute, the window will close and you will be back in the browser.

You will see in the output window that there is no Alert message and that the model execution ended normally. Click All in the File changed, reload file?, if it comes up. Please do this always, unless we specifically request otherwise.

Now let us look at the results.

Whenever Produce execution feedback parameter is not set to No in a model's configuration file, NMOD automatically produces a feedback file (c:\ORMSware\ProgramFiles\NMOD.TXT) showing how the model executed (i.e. how the networks were traversed, etc.). Double-click Execution feedback in c:\ORMSware\ProgramFilesN\NMOD.TXT in output window to bring up c:\ORMSware\Tutorial\NMOD.TXT in the main browser window and jump to the end (Ctrl-End) of file. There is nothing much there of use, except that we can see above No more pending events that branching along a[15] was blocked as we intended.

It will be useful to get the results of the number of widgets/pieces required per hour, machine cost and labor cost per hour for that rate of production, and resulting cost per piece at the end of a model run. We can write all of these results at the same time, in one place into the default execution feedback file.

Let us put in some WRITE and echo ({?|variable}) statements to find out if our model is doing the right calculations.

Copy to clipboard the text below, including the hidden linefeed character at the end of the last line (after 35)).

WRITE(9,*)REPEAT("=",35)
{?|#B.PiecesPerHour}
{?|#S.LaborCostPerHour}
{?|#S.MachineCostPerHour}
{?|&D.CostPerPiece}
WRITE(9,*)REPEAT("=",35)

The 9 in the WRITE statements above refers to file-handle number. NMOD opens Unit 9 (associating it with c:\ORMSware\ProgramFiles\NMOD.TXT) at the beginning of every model run to write certain messages whether or not the Produce execution feedback option is set to Yes. Since we know that Unit 9 would be open, we chose to write to it rather than bothering with opening another file just to write this little output.

Since NMOD's atom is not confined to just one variable or array per network object, it is not possible to automatically display the results from each network object. Instead, ORMSware offers a quick way to indicate which variables you want displayed by using the Echo notation. Using the edit features of UltraEdit, each user will be able to figure out ways to easily create Echo statements from any logic block in NET and ADD files.

NETrans creates WRITE statements for each echo statement as in the following examples:

{?|#B.PiecesPerHour} yields:     WRITE(9,*)"??? #B.PiecesPerHour =",#B.PiecesPerHour

{?|} yields: WRITE(9,*)"???"

{?|No_blanks_commas_or_operators} yields: WRITE(9,*)"??? No_blanks_commas_or_operators"

You will see how this translation/expansion works when you look at this model's first-cut results shortly. Notice also that you can use UltraEdit's search facility to search for ??? to list results of all echo statements in a model.

Click on tPrimerTour.NET tab in the browser. Position the cursor in column 1 of the -{Branch} tag line below the {&L.CurveBuild} line in [15]. Paste the clipboard content. If a blank line appears at the bottom of the block pasted, you may want to get rid of it (depending on your personal preference).

We now want to shift the block of code to the right to align it with {nop.L}Branch above, so that things will be neat and easy to read.

Highlight the block of code we just inserted. Hit tab key 3 times. By the way, key combination to move left is Shift-tab.

Alternatively, press Alt-c or choose from main menu Column - Column mode. Left-click and drag the mouse in column 1 of the block of code we want to shift. Release mouse. A thin blue line appears. Now, just hit the tab key on your computer 3 times and the text will be aligned neatly. Toggle out of column mode.

Obviously, the first method is easier for this occasion. We will need column mode, however, if we want to shift just selected columns in a contiguous set of lines rather than the entire block.

Before we proceed to check out the results, let us do a couple things. Let us discuss the location where we have inserted the WRITE statements, and then make a couple of mistakes in the write statements and see what happens during NETransing and compilation.

You may have wondered why we put the write statements in a[15] instead of n[5], especially when we have taken measures to make sure that a[15] never executes. We did this to make the point that you can put the logic you want to execute unconditionally on any arc, even if no traversal takes place along that arc (but only if its originating node does execute).

When n[5] is finished, NMOD looks to see if it has any successor arcs that should be executed. To determine if [15] should be executed, NMOD evaluates its Branch property value. It first encounters the logNo value. Then, since that property has continued logic indicated by the ellipses, NMOD executes the continuation logic in case the existing Branch condition is to be updated before final decision can be made. We have simply taken advantage of this process, putting our WRITE statements in [15]'s Branch property code block, ensuring their unconditional execution. If we want to turn off the writing code block, we can simply remove the ellipses using [15]'s dialog box in Visio, re-export, translate, and recompile.

Now let us make those mistakes. Let us make one mistake that will produce translation error and another that will produce compilation error. We will go through the process of fixing those mistakes and getting the model to produce the results we want to see.

In the block of WRITE & echo statements which we just inserted change #B.PiecesPerHour to #qB.PiecesPerHour as shown below:

{?|#qB.PiecesPerHour}

Page away (up or down) from the above line, positioning the cursor away from the above line, and then click on any other window tab in the browser. This is so that you can see later how the browser takes you to the location of the error. 

Just NETrans the model and watch for Alert message towards the bottom of the output window. The message says that there is an error, on which line the error is, and what type of error it is. Double-click the message in the output window. The browser will switch to tPrimerTour.NET window and position the cursor on the offending line.

Now choose Advanced - Netrans + Compile.Link.Run to see what happens if we try to go all the way through when there is a translation error source in a model. Though NETrans did not consider the error serious enough to stop its own execution (see message NETrans ended normally), it communicated the error to the modeling process manager which stopped the process without attempting compilation.

Moving on, let us delete the q we put in to create the error.

Before we create an error that will get past NETrans, but will cause a compilation problem, let us explore a little deeper into the issue of content coordination of a model's Visio diagrams and its supplemental logic file (NET file).

Go to [15]'s Trans property statement in NET file and change the equal sign (=) to two equal signs (==) as below.

{nop.L}Branch={@B.PiecesPerHour == @B.PiecesPerHour + &B.PiecesIncrement}

Just NETrans and watch the output window. We have a clean translation. As you might expect from our previous experience, however, the error we had put in is no longer there. NETrans has changed it back to the way it was before.

One of NETrans's functions is to coordinate Visio diagram with the NET file. We are able to get from Visio only one line of property value statement for each property of an object (recall the dialog boxes). If we need more lines to describe a network object's property value or behavior, we have to indicate continuation using ellipses (...) and then enter the supplemental logic in the model's NET file.

When NETrans structures the NET file, it places records from Visio export at the top of the corresponding property code block for each object in the NET file, while also using the nop (network object property) notation and an enveloping scheme to wrap each Visio-entered record for identification purposes. Without going further into it, the bottom line is that NETrans wrote over the == change we had made in the NET file with what was originally there in the Visio report.

In order to put in the change we want in the nop record, let us now go make that change in Visio and re-export.

Page away from [15]'s Trans property in NET file. Switch to Visio, make the change in the Transition property of a[15] and re-export the file. Then, choose Advanced -- Netrans + Compile.Link.Run in the browser.

You will notice that the error (i.e. == that we put in) remains this time and is reflected in NET file, but we have a clean translation. This is because NETrans job in terms of translation is simply to translate the ORMSware notations it finds. It has no idea whether a piece of code will compile. That job is up to the compiler.

Looking below the NETrans ended normally message in the output window (you may have to scroll up a little), you will see that the compilation step was performed, but the process stopped after the compilation step, since compilation errors have to be fixed before the linking step for creating the model's executable (EXE) file.

To track compilation error to the source, we have to first find out what the compiler said. In the output window double-click Check c:\ORMSware\ProgramFiles\CompilerFeedback.TXT for details.

Scan down to find the following (line and column numbers we have shown below may be off, since we may have inserted or deleted records in NET file after writing this chapter, but that will not keep you from understanding what is explained here):

Module subprogram name(Obj_1_15)
1104-S: "C:\ORMSware\Tutorial\tPrimerTour.F95", line 156, column 35: Invalid delimiter.

Obj_1_15 gives us a clue right away that the error is in page/network 1, object 15. But, we will use an easy process to get to the source in a minute.

Look below the above message to find Compiling program unit NetAndEntProcsAndProps at line... Notice a bunch of errors below it. You can always ignore errors below this point, because they are the result of that one little mistake we put in, pointed out as above by the compiler.

Now to track this error back to our model logic, triple-click (or choose Edit - Select Line from main menu, or Alt-E L) to select the entire error message line. Then choose Advanced - [Track back err] and watch the output window. It shows a preview of the offending line in the translated ANSI Fortran 95 source as well as the original line in NET file.

Recall that we have positioned the cursor away from Object 15 in NET file. Double-click the message in the output window referring to the NET file name and line number. The browser takes you to the original offending line in the NET file.

Let us correct the problem in Visio (arc [15], change == to =) and export the model again.

Click NMOD.TXT tab towards the top of the browser. Jump to the end of file and make sure that the display is still showing the bottom of NMOD.TXT file from our first execution that flagged the 1000 events limit.

Choose Advanced -- Netrans + Compile.Link.Run. The NMOD window goes blank. Press Ctrl-End. Results of our write statements appear at the bottom of the NMOD.TXT window. The file is shorter this time, since there were only 21 events in this run. You can also see from the messages in output window that everything worked all the way through to the end, that the model execution ended normally.

Notice the message CostPerPiece.[15]CostPerPiece--->|PiecesPerHour branch condition not satisfied from NMOD right below the results in the main window. As you can see, though no traversal takes place on a[15], the logic in its Branch property (the WRITE statements we inserted) still executed, unconditionally.

We are finished with the quick tour of NMOD modeling process. You have made changes in Visio and gone through the report writing and translate-compile-link-run process several times, so you should be able to play around and look at some results if you so wish.

If you would like to go through this chapter again to do the above exercises, the original model is still in c:\ORMSware\Tutorial\Chapter2 folder. You should, however, delete the NET file in the Tutorial folder, since NETrans always preserves during translation all existing supplemental logic in a NET file, in case the analyst wishes to reuse the code later (recall that if there are no ellipses present at the end of a property statement, NETrans ignores the supplemental logic for that property in the NET file and flags it as inactive, but does not delete it).

Go to the top of NMOD.TXT file. Whenever we execute a model and want to look at the Echo statement results, we would end up coming to this point at the top of NMOD.TXT. To find all results written with Echo statements in one shot, press Ctrl-F. Enter ??? in the Find what text box. Make sure List Lines Containing String option is checked. Hit Enter. Notice the results of all Echo statements in the dialog box as well as where the yellow highlighter is in the main window. You can figure out different ways to use Echo statements to get the effects you desire, to jump to the results you want in the main window, and to copy the results to clipboard for further use.