Module FAQs

The version 9.1 release of iThink & STELLA introduced a new approach to modeling complex systems: hierarchical modules.  Modeling with modules can really simplify the way you think about, construct and communicate systems.

Since a lot of customers are now getting their feet wet with modules, we’ve been receiving a steady stream of questions.  We asked our Director of Product Development Karim Chichakly to compile a list of frequently asked questions that he thought would be useful for anyone using modules.  The questions and answers are listed below. If you have any additional questions, post them in the comments and we’ll respond.

What is a module?

A module is a container for lower-level model structure.  It is designed to support a process of top-down model design and development.

What is a module input?

A module input is a variable that can become the ghost of another variable at a different level of the module hierarchy.   It becomes the ghost when you assign it to that other variable.  After it is assigned, it is referred to both as a cross-level ghost and an assigned module input.  All of this is managed transparently if you use the ghost tool.

What is a module output?

When a variable is designated as a module output, you are telling the software that this variable can be ghosted on a different level of the module hierarchy.  While any variable can be a module output, it is important to carefully manage which variables you intend to be shared across modules.

How are modules different from Decision Process Diamonds (DPDs)?

DPDs were designed to collapse one level of structure and hide non-essential details while modules were designed for top-down development of complex models.  Their goals are very different and so is their behavior.  While it is true that modules can be used to replace DPDs, the reverse is not true.

Why can’t I directly connect modules to variables as I can with DPDs?

Although it may appear that they are, DPDs are never directly connected to anything.  When a DPD is connected to a variable, a “nub” (which is just a placeholder) is placed inside the DPD.  In order to get the model to work, you must open the DPD and connect that nub to a variable in the DPD.  When you do this, you have connected a variable that is hidden inside the DPD directly to a variable outside the DPD – and this connection is visible while the DPD is extant.

We chose a different metaphor for modules because modules do not appear side-by-side with the model they are in.  Thus, you cannot see the connections.  Although we could have created nubs like in the DPD, we would have had to give the nubs names which then persisted on connections going out to the diagram frame after the variable was connected.  Again, it is important to remember that DPDs are not connected to variables any more than modules are – variables are connected one-to-one with other variables.

What is the metaphor for modules?

For modules, we decided the proper metaphor was that of ghosts, which are already used to refer to a variable elsewhere in a model.  In fact, the most natural (and easiest) method to connect variables in different modules is with the ghost tool.

As a result, all variables used from another module are clearly visible within the module that uses them.  The use of those variables inside the module is also clearly visible.

A direct consequence of this metaphor is that no connections can be made across levels without first going through a cross-level ghost (also known as a module input).  This is different from the requirements of a DPD, which allowed you to see the variable inside the DPD at the same time as the variable outside the DPD.

How are modules different from submodels?

Like DPDs, submodels collapse one level of structure.  They were specifically designed to hide low-level details of processes from the top-level of the model.  A submodel is a proxy for a stock and, in this way, varies dramatically from a module which presently has no value at all.  Also, a submodel allows several outflows from a process to be rolled up (summed) into one outflow of the submodel, which modules do not allow (there are not flows into or out of modules).  However, modules do allow a main chain to cross their boundaries in much the same way a submodel does.

How are modules different from sectors?

Sectors and modules represent the same basic concept:  A fundamental unit of the model at a high-level with detail inside.  The difference is the sector does not hide that detail within it and cannot be nested.  The module hides the detail within it and can be nested as many levels as desired.  Sectors can still be useful for breaking up small models.

Will all four methods of organizing model structure continue to exist in the future?

While there remain clear and separate uses for sectors and modules, the functionality of the DPD almost completely overlaps that of the module.  The submodel, which is used infrequently nowadays, also mostly overlaps with the module.  At some point in the future, both the DPD and the submodel will be removed from the software.

Why can’t I connect a module to a module output?

Whatever variable a module gets connected to must be able to become a cross-level ghost.  This means it cannot have any connections into it and it cannot be a module output, as no variable can be both a module input and a module output.  To use a variable in a module, you must first ghost it in the current module.

Why can’t a variable be both a module input and module output?

Because a module input is the ghost of another variable.  A ghost just represents the variable – it is not the variable itself.  Connections should be made from the original variable whenever possible.  When this is not possible, an intermediate variable set identically equal to the original variable can be used.

Why does the software complain that I cannot connect a module to a module output when I didn’t create a module output (and there is no indication on the variable concerned)?

There are two types of module outputs:  explicit and implicit.  An explicit module output is created by right-clicking on the variable and choosing Module->Provide Output from the context menu.  After doing this, there will be a second border drawn inside the variable (that looks like a large O in converters and flows) and that variable will be accessible in the module directly above this one and in all modules (and their submodules) connected to this one.  Note the ghost tool also creates explicit module outputs.

An implicit module output is created any time a variable is connected to a module.  This variable is treated as a parameter to that module and that module alone, so can only be accessed inside that module.  The only visual indication that this is a module output is the connecter running from the variable to the module.  There is no mark on the variable and the context menu will not claim it is a module output.  This is because the context menu is for setting explicit module outputs which behave slightly differently.

Can the file hierarchy for modules match the model hierarchy?

At present, all modules must exist at the same level in the Modules folder.  This does mean that all filenames must be unique.

Can the modules be saved in one file with the top-level model?

At present, all modules must exist as separate files in the Modules folder.

Can I control import and export independently at each level of the module hierarchy?

At present, import and export sheets can be associated only with the top-level model and should be in the Data folder.  Multiple sheets are allowed, so they can be organized by module.  To import a module variable, make sure to precede the name in the import sheet with the name of the module and a period.  For example, to import variable “x” in module “mod”, the name in the import sheet must be “mod.x”.

Can I put my import and export sheets in the same directory as my modules?

Import and export sheets must appear either within the same directory as the model or in the Data folder, which is itself in the same directory as the model.

If two modules have the same logic, can I share the same module file?

Yes.  However, you will be unable to edit the module while it is assigned to more than one module.  This is indicated by a disabled toolbar and a lock in the upper-left hand corner of the screen.  To edit the module, temporarily disconnect it from all modules but one, edit it, and then reconnect it.  Alternatively, you can open the ITT file directly, edit it, and then re-import it into your model.