Difference between revisions of "Filed modules and libraries"

m
 
(11 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
<breadcrumbs>Analytica User Guide > Working with Large Models > {{PAGENAME}}</breadcrumbs>
 
<breadcrumbs>Analytica User Guide > Working with Large Models > {{PAGENAME}}</breadcrumbs>
  
===Models and modules===
+
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.
Modules and libraries can be components of a model. If you are building several similar models, or if you are building a large model composed of similar components, you can create modules and libraries for reuse. (See [[Building Functions and Libraries]] for details about libraries.) To use a module or library in more than one model, create a '''''filed module''''' or '''''filed library'''''.
+
 
 +
__TOC__
 +
 
 +
=== 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 [[User-defined Functions and Libraries|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 [[Import a module or library|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 [[toolbar|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.
  
=== Creating a filed module or library ===
 
To create a filed module or library:
 
 
# Create a module by dragging the module icon from the node palette onto the diagram, and give it a title.
 
# Create a module by dragging the module icon from the node palette onto the diagram, and give it a title.
# Create functions and variables in the module, or create them elsewhere and move them into the module.
+
# Create variables, functions and any other objects in the new module, or, if they already exist, drag them into the module.
# [[To_change_the_class_of_an_object|Change the class]] of the module to '''Module''' [[File:Chapter19_14.png]] or '''Library''' [[File:Chapter19_15.png]]
+
# [[To_change_the_class_of_an_object|Change the class]] of the module  
# The '''Save As''' dialog appears. Give the filed module or library a name and save it.
+
# If you change the class to a separately filed '''Module''' [[File:Chapter19_14.png]] or '''Library''' [[File:Chapter19_15.png]], a file browser dialog prompts you for a directory and file name.
# If you want the original model to load the new filed module or library the next time it is opened, save the model using the '''Save''' command.
+
# 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) [[File:SelectClass.jpg]]
 +
#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 ===
  
=== Locking a filed module or library ===  
+
There are several reasons you might need to manage multiple versions of a model:
To prevent a filed module or library from being modified, lock it:
+
# 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.
 
#  Close the filed module or library, or close Analytica.
 
#  In Windows Explorer, select the filed module or library.
 
#  In Windows Explorer, select the filed module or library.
Line 22: Line 90:
 
# Check the ''Read-only'' checkbox.
 
# Check the ''Read-only'' checkbox.
 
# Close the '''Properties''' window
 
# Close the '''Properties''' window
 
=== Adding a module to a model ===
 
To add a filed module to the active model, use the '''[[Import a module or library|Add Module dialog]]'''. You can either embed a copy of the module or link to the original of the filed module.
 
 
=== Adding library to a model ===
 
To add a filed library to the active model, use the '''[[Import a module or library|Add Module dialog]]'''. You can either embed a copy of the library or link to the original of the filed library.
 
When you select '''Add Library''' from the '''File''' menu, the '''Open File''' dialog always opens up to fixed directory, regardless of the current directory settings or previous changes of directories. The directory is determined by a registry setting in <code>/Lumina Decision Systems/Analytica/
 
3.0/AddLibraryDir</code>, which is set by the Analytica installer to <code>INSTALLDIR/Libraries</code>.
 
 
=== Removing a module or library from a model ===
 
To remove a filed module or library from a model, first select it. Then, select '''Cut''' or '''Clear''' from the '''Edit''' menu. An embedded copy is deleted; a linked original still exists as a separate file.
 
 
=== Saving changes === 
 
After you have linked to a filed module or library, the '''Save''' command 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''' In commands save only the active (topmost window’s) model, filed module or filed library.
 
  
 
== See Also ==
 
== See Also ==
Line 42: Line 96:
 
* [[Additional libraries]]
 
* [[Additional libraries]]
 
* [[User Libraries]]
 
* [[User Libraries]]
* [[Building Functions and Libraries]]
+
* [[User-defined Functions and Libraries]]
 
* [[Analytica Libraries and Templates]]
 
* [[Analytica Libraries and Templates]]
 
* [[Example Models and Libraries]]
 
* [[Example Models and Libraries]]

Latest revision as of 20:25, 27 June 2024

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.

  1. Create a module by dragging the module icon from the node palette onto the diagram, and give it a title.
  2. Create variables, functions and any other objects in the new module, or, if they already exist, drag them into the module.
  3. Change the class of the module
  4. If you change the class to a separately filed Module Chapter19 14.png or Library Chapter19 15.png, a file browser dialog prompts you for a directory and file name.
  5. 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:

  1. Open Model M1.
  2. Create a new Module by dragging from the Toolbar, and give it a title, say "From M1".
  3. Drag all the objects you want to copy into that Module.
  4. Open the Attribute panel (if needed) by clicking on the key icon at the bottom left corner of the window.
  5. Select the node for module "From M1"
  6. Change the Attribute panel to the Class view, to show its current class "Module"
  7. Open the Class menu and select Filed Module (with page icon inside the module icon) SelectClass.jpg
  8. When it prompts to save the Module, select the file name (or use the default).
  9. Now open Model M1
  10. In Edit mode, select Add module... from the File menu, and select module "From M1.ana".
  11. 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:

  1. 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.
  2. 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.
  3. 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.
  4. 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:

  1. Close the filed module or library, or close Analytica.
  2. In Windows Explorer, select the filed module or library.
  3. Select Properties from the File menu.
    Chapter19 16.png
  4. Check the Read-only checkbox.
  5. Close the Properties window

See Also


Comments


You are not allowed to post comments.