View source for Combining models into an integrated model

[[Category:Analytica User Guide]]
[[Category: Models]]

<breadcrumbs>Analytica User Guide > Working with Large Models > {{PAGENAME}}</breadcrumbs>

===Distributed modeling===
Large models introduce a unique set of modeling issues. Modelers might want to work on different parts of a model simultaneously, or at remote locations. During construction, a large model might be more tractable when broken into modular pieces (modules), but all modules should use a common set of indexes and functions. Analytica provides the functionality required to support large-scale, distributed modeling efforts.

This section describes how to best use Analytica for large modeling projects and contains suggestions for planning a large model where responsibility for each module is assigned to different people (or teams).

=== Define public variables === 
The first step to creating an integrated model is to define public variables for use by all modules and agree on module linkages.

Every integrated model has variables that are used by two or more projects (for example, geographical, organizational, or other static indexes, modeling parameters, and universal constants).
These public variables should be defined in a separate module, and distributed to all project teams. Each team uses the [[Import a module or library|Add Module dialog]] to add the public variables module to its model at the outset of modeling. Using a common module for public variables avoids duplication of variables and facilitates the modules’ integration.

Source control over the public variable module must be established at the outset so that all teams are always working with the same public variables module. Modelers should not add, delete, or change variables in the public variables module unless they inform the source controller, who can then distribute a new version to all modelers.

If multiple teams will be working on separate projects, it is essential that the teams agree upon inputs and outputs. Modelers must specify the input variables, units, and dimensions that they are expecting as well as the output variables, units, and dimensions that they will be providing. The indexes of these inputs and outputs should be contained in the public variables module.

=== Avoid table-index inconsistencies ===
Indexes that are located in the public variables module(s) should be of a static nature, and should not include indexes that change often or are computed from data. These indexes define a structure that all modelers agree upon, and in the (ideally) rare event that a public index needs to be changed, it needs to be done in a particular manner described here that ensures other people's modules don't become inconsistent.

When you have an index that is likely to change, or a computed index that will change with changes to data or inputs, you should try to keep variables with tables that use that index in the same filed module as the index itself. Failure to do in a project with multiple modelers puts you at risk for ending up with a table that is inconsistent with its indexes, which can cause a shuffling of cell data. Suppose for example that Alice and Bob are working together on a model. Alice works on module <code>MA</code>, Bob works on module <code>MB</code> and an index <code>J</code> is in a shared filed module <code>MS</code>. Module <code>MA</code> has a table <code>T1</code> with index <code>J</code>. One day Bob changes <code>J</code>. When he does so, table <code>T1</code> is [[Table Splicing|spliced]] on his computer, and hence remains consistent with <code>J</code>. But when he later shares <code>MS</code> with Alice, her "master" copy of <code>MA</code> is now inconsistent with <code>J</code> and she finds that the cells of table <code>T1</code> have shuffled unexpectedly.

When a shared index does need to be changed, the following procedure should be followed to avoid introducing table-index inconsistencies. All model builders should submit their current filed module revisions to you. Load the full model into Analytica, with everyone's filed modules included, and make the change to the index.  You should also view at least one edit table that uses the index to ensure that it has been fully spliced (or, you can type <code>SpliceIndex All</code> into the [[Typescript Window]]). Save changes and redistribute each person's module back to them. Each modeler should continue his work with this copy. The reason this avoids the problem is that Analytica automatically ensures that tables and indexes are kept consistent when changes occur, in the copy it is running. See [[Table Splicing]].

=== Create a modular model === 
By keeping large pieces of a model in separate, or filed modules, modelers can work on different parts of a model simultaneously. You can break an existing model into modules, or combine modules into an integrated model. In both cases, the result is a top-level model, into which the modules are added.

To save pieces of a large model as a set of filed modules, see [[Using filed modules and libraries]].
To combine existing models into a new, integrated model:
# Create or open the model that will be the top level of the hierarchy. This is the model to which all sub-models will be added.
# Using the [[Import a module or library|Add Module dialog]], add in the sub-models. Be sure to check the ''Merge'' option in the '''Add Module''' dialog. Add the modules in the following sequence:
#* Any public variable modules
#* All remaining modules in order of back to front; that is:
#** First, the module(s) whose outputs are not used by any other module, and
#** Last, the module(s) which take no inputs from any other module.
# Save the entire integrated model, using the '''Save''' command.

The two alternative methods of controlling each module’s input and output nodes so the modules
can be easily integrated, are:
* Identical identifiers
* Redundant nodes

=== Identical identifiers === 
Assign the input nodes in each module the exact same identifiers as the output nodes in other modules that will be feeding into them. When you add the modules beginning with the last modules first (that is, those at the end of model flow diagram), the input nodes are overwritten by the output nodes, thus linking the modules and avoiding duplication.

With identical identifiers, the individual modules cannot be evaluated alone because they are missing their input data. They can be evaluated only as part of the integrated model.

=== Redundant nodes===  
Place the output node identifiers in the definition fields of their respective input nodes. Due to the node redundancy, this method requires more memory than using identical identifiers, and it is therefore less desirable when large tables of data are passed between modules. However, since no nodes are overwritten and lost upon integration, this method preserves the modules’ structural integrity, with both input and output nodes visible in each module’s diagram.

With redundant nodes, each module can be opened and evaluated alone, using stand alone shells.

=== Stand alone shells === 
With redundant nodes, you can create a top-level model that contains one or more modules and the public variables module plus dummy inputs and outputs. Such a top-level model is called a '''''stand alone shell''''' because it allows you to open and evaluate a single module 'standing alone' from the rest of the integrated model. Stand alone shells are useful when modelers want to examine or refine a particular module without the overhead of opening and running the entire model.

To create a stand alone shell for module <code>Mod1</code>, which is a filed module:
# Open the integrated model and evaluate all nodes that feed inputs to <code>Mod1</code>.
# Use the '''Export''' command (see [[Import_and_Export_data#Importing_into_an_Edit_Table_or_List|Import to and export from an Edit table or List]]) to save the value of each feeding node in a separate file. Make a note of these items:
#* The identifier of each node and the indexes by which its results are dimensioned.
#* The identifiers of <code>Mod1’</code>s output nodes, if you want to include their dummies in the stand alone shell.
# Close the integrated model.
# Create a new model, to be the stand alone shell.
# Use '''Add Module''' to add the public variables module.
# For each input node, create a node containing an edit table, using the identifier and dimensions of the feeding nodes you noted from the integrated model.
# Use the Import command (see [[Import_and_Export_data#Importing_into_an_Edit_Table_or_List|Import to and export from an Edit table or List]]) to load the appropriate data into each node’s edit table.
# Use '''Add Module''' to add <code>Mod1</code> into the stand alone shell.
# To include output nodes at the top level of the hierarchy, create nodes there and define them as the identifiers of <code>Mod1</code>’s outputs.
# Save the shell.

The shell now has all the components necessary to open and evaluate <code>Mod1</code>, without loading the entire model. As long as modelers do not make changes to the dimensions or identifiers of module inputs and outputs, they can modify a module while using the stand alone shell, and the resulting module is usable within the integrated model.

== Cautions in combining models ==
=== Identifiers === 
Every object in a model must have a unique identifier. The identifiers of filed libraries and filed modules that you add to a model, as well as their variables and functions, cannot duplicate identifiers in the root model. See [[Import a module or library|Merge contents (overwrite)]].

=== Created attributes === 
When you combine models with created attributes, the maximum number of defined attributes is five (see [[Managing attributes]]).

=== Location of filed modules and libraries === 
If the model will eventually be distributed to other computers, all modules and libraries should be on the same drive as the root model prior to being added to the root model. When the model is distributed, distribute it with all filed modules and libraries.

== See Also ==
* [[Expand your model]]
* [[Using Add Module... to import a Model file]]
* [[Import a module or library]]
* [[Modules and Libraries]]
* [[Obfuscated and Browse-Only Models]]
* [[Filed modules and libraries]]
* [[Working with Models, Modules, and Files in ADE]]
* [[Example Models and Libraries]]
* [[Example Models]]


<footer>Import a module or library/ {{PAGENAME}} / Making a browse-only model and hiding definitions</footer>