Filed modules and libraries

Analytica User GuideWorking with Large ModelsFiled modules and libraries

A Model may contain several Modules (including Libraries, which are a subclass of Modules). Usually, Modules and Libraries are embedded in the file of their parent Model, but it is also possible to include them in separate files, known as Filed (or linked) Modules and Libraries. This page describes these different classes of Module, and how to create, save, import, and remove them.

Module Classes

Technically, Module is a Class of Object. Model and Library are subclasses of the Module class. Each Module (including a Model or Library) is simply a collection of variables and other objects. It has a Diagram view, displaying the objects arranged as nodes with arrows indicating dependencies. It may contain submodules, defining a nested hierarchy of Modules. The Module hierarchy provides a convenient way to organize a complex model, perhaps with hundreds or thousands of variables and other objects.

There are six types of module:

Model: A top level Module, always saved in a separate file.
Module: A plain Module that is embedded in its parent Model or other Module.
Filed Module: A Module used in a parent Model or other Module, but saved in its own file.
Library: A Module that contains Functions and/or other objects designed for use in multiple Models.
Filed Library: A library saved in its own file. Analytica is distributed with a set of standard libraries of this kind. You can also create your own Libraries for use by yourself and others.
Form: A special class of Module that makes it easy to add User Input nodes, and User Output nodes, simply by drawing arrows from a variable to the Form Node, or from the Form Node to a variable, respectively.

The only difference between a Filed Module or Library and a Module or Library embedded in its parent Model is that it is saved as a separate file. When you add a filed Module or Library into a Model, it gives you the choice of keeping it in a separate file or embedding it in the Model file. It's usually best to embed it so that you don't have to remember to include the separate files when you move the Model or share it with other people.

If you leave a module as a separate file, any changes you make to it will also affect any other Models that also link to this filed Module or Library. Sometimes this is useful, for example when several people are working on a Model in parallel, and you want them all to benefit from your improvements. For the same reason, it is dangerous because any change that anyone makes to the filed Module will affect all Models that use it.

Add a Module or Library to a Model

To add a filed Module or Library to the active Model, use the Add Module dialog from the File menu. It prompts you for the directory and file. If instead, you select Add Library from the File menu, the file dialog defaults to the directory containing the Standard libraries distributed with Analytica.

Either way, it gives you the choice to embed the Module or Library into the parent Model or to link to the file.

Remove a filed Module or Library from a Model

To remove a Module or Library from a Model, first select it. Then, select Cut or Clear from the Edit menu, or press the delete key. If it was embedded, it deletes it. If it was filed, it deletes only the node and link from the parent Module, but not the separate file.

To create a library or filed module or library

The Node toolbar offers only a standard embedded Module. To make a separately filed Module, Library, or Form, you first create a standard Module and then change its class to what you want.

Create a module by dragging the module icon from the node palette onto the diagram, and give it a title.
Create variables, functions and any other objects in the new module, or, if they already exist, drag them into the module.
Change the class of the module
If you change the class to a separately filed Module or Library , a file browser dialog prompts you for a directory and file name.
If you want the parent Model to load the new filed Module or Library the next time it is opened, use the Save command from the File menu to make sure it saves the link to the new file.

Changing Module Class

You can change the Class of a Module to another Module Class, including from embedded to filed or vice versa, in the same way that you change the Class of a Variable. (You can't change a Module into a Variable or other non-Module class, or vice versa.) Show its Class in its Object Window, or Attribute pane. In Edit mode, press on the Class menu and select another Class.

If you change from an embedded to Filed Class, e.g. from Library to Filed Library, it a File browser prompts you to select the file name and directory.

Saving changes

After you have linked to a filed module or library, the Save option from the File menu saves every filed module and library that has changed, as well as the model containing them, in their corresponding files. The Save As and Save A Copy options save only the active (topmost window’s) model, filed module or filed library, but not any submodules it may contain.

Using a Module to Copy stuff from one Model to Another

Analytica doesn't let you copy and paste objects directly from one Model to another. Here's how to copy variables, functions, modules, or any objects from a model M1 into another model M2:

Open Model M1.
Create a new Module by dragging from the Toolbar, and give it a title, say "From M1".
Drag all the objects you want to copy into that Module.
Open the Attribute panel (if needed) by clicking on the key icon at the bottom left corner of the window.
Select the node for module "From M1"
Change the Attribute panel to the Class view, to show its current class "Module"
Open the Class menu and select Filed Module (with page icon inside the module icon)
When it prompts to save the Module, select the file name (or use the default).
Now open Model M1
In Edit mode, select Add module... from the File menu, and select module "From M1.ana".
In the Add module or library dialog, select Embed a model, but leave Merge contents unchecked.

This reads "From M1.ana" to become a new module into M2. With "Merge contents" unchecked, if any imported object has the same identifier as an existing object in M2, it adds a digit at the end of its identifier, to make no existing object gets overwritten.

Managing multiple versions of a model

There are several reasons you might need to manage multiple versions of a model:

While you are developing a model, you want to explore alternative ways to structure it. In this case, it's a good idea to make sure the parts for which you want to try different versions are all in the same module, and the parts that won't change are outside it. That way, once you've explored the variations, you can more easily remember what's changed and what's haven't.
Similarly, when two or more modelers work on a model in parallel, it's best to agree on who can make changes to which module(s) before you fork the model (start multiple versions). Then you can change those modules to be separately filed. Usually one person takes responsibility for the parent model. Analytica doesn't have a built-in way to prevent "unauthorized" changes to a module, except by saving it as "Browse-only". But you can lock a module using the Windows explorer (see below.) When you recombine the modules (merge them) you can simply copy the changed modules into the same folder as the parent model. When you restart the parent model it will automatically read in the new module versions. At that point you can decide if you want to change them back from separately filed to integrated modules.
A great way to support multiple modelers and multiple model versions is to use Github, the widely used software source code management tool. Analytica works well with Github. That allows multiple modelers to work simultaneously on the same modules. It tracks who made what changes and makes it easy to compare versions. When you want to merge changes, you can see each change and decide which version of each change you want to use.
Sometimes you want to create several versions of a model for different applications . One approach is to put all the variables, functions, and so on that are common to all the applications into a separately filed module, and keep the things that change from one version to another in the parent model.

Module Attributes

Each Module has standard attributes common to any Object, including Identifier, Title, and Description, plus Author(s). If it is a separately filed Module or Library, it also contains Created date, Last Saved date, and File info, containing its file path and name, like a Model object. You can see these in its Object Window.

Locking a filed module or library

You can use the Windows explorer to lock a filed module or library to prevent users from modifying it, even which they can modify things in a parent model that uses it:

Close the filed module or library, or close Analytica.
In Windows Explorer, select the filed module or library.
Select Properties from the File menu.
Check the Read-only checkbox.
Close the Properties window