Version management
The purpose of the model version facility is to simplify the process of repeatedly changing parameters, rebuilding the model, making runs and comparing results.
A version project may contain one or more root cases with branches of dependent cases. The project stores the differences between each child case and the corresponding parent case.
A new empty Project is initiated by choosing New… from File menu and than selecting Version project from the list of document templates. This opens a project window.
To make a root case, either click the button Add new base at the bottom of the project window, or copy/paste or drag/drop an existing case to the project window. To drag a case from the Outline view, select the root object in the outline view of the case to add.
After each model change (worth saving), the user can either save the case (i.e., overwrite the previous version) or save it as a new version (by selecting Save as Version from File menu). The saved versions form a series of cases in the Project window.
New branches of cases can be started based on any point in the chain. A project may also contain more than a single root case.
When a version is saved, the difference between the previous (parent) and the present (child) version is saved. The difference is saved in the form of a script, which when applied to the parent case will produce the child case. Scripts can also be manually edited. Use Properties menu item in shortcut menu to access and edit the difference script.
After a series (or a tree) of cases has been run, one may return to any point in the chain to make a model change, without starting a new branch, and automatically rerun all dependent cases (in batch).
Some types of model changes are not supported and may cause problems in rerunning dependent cases. Typically, removing objects which are altered in a subsequent version leads to controlled errors.
Results are presented in a combined outline and table window, where each row represents a model version and most of the columns represent significant parameters and results that are interesting to compare between cases. Results are typically some number from a generated report, the present value of a variable, or a color-coded graph of some variable. In the latter case, a diagram with a curve for each version can be opened. Naturally, it is also possible to open any version to see the full results.
If a case is modified and then simulated (without saving to file), the results of both the original (saved) and the modified case are presented on the screen, as two rows. If Update All (or Branch) is initiated in this state, the user is asked to either abandon or save the modified case first.
A version with an Advanced level model may be based on a Standard level version. In this case, the difference script will start with "Build model" command. This makes it possible to modify physical parameters of an Advanced level model.
The user may suppress simulating of auxiliary versions; e.g., base Standard level version. To do this, open version properties (from shortcut menu) and check the option "Do not simulate".
Basic operations
To start a new project
A new empty Project is initiated by choosing New… from File menu and than selecting Version project from the list of document templates. This opens a project window. The user is prompted to save the project to a file.
Alternatively, it is possible to start a project by saving a standalone system (i.e., one that does not belong to any version project) as a version (use Save as version in File menu).
To open an existing project
Use Open in File menu or double click the project file in the Windows' folder view. (Version Projects are stored in .idm files the same way as the simulated cases).
To add a new root (base) case to project
Click the button Add new base at the bottom of the project window. In the dialog, select (or just accept) the document name and template and press Ok. You can also write some comments that will be available to edit via version properties.
To insert an existing case into project
Open the case, switch to Outline view, select the root of the outline with the mouse, drag it (with left mouse button pressed) to the project window, and drop it into the version table. Alternatively, you can Copy the case from outline view and Paste it to the project window.
To open a case from the project window
Double click on the version name in the project window.
You can also open the case from the Windows' folder view. If the project is not open, it will also be opened.
To save changes in a case
Use Save in File menu or the Save button in the toolbar. Before the case is saved, the user is prompted to save or discard any changes in dependent cases. After the case is saved, the difference between this and the parent case is recalculated and saved. The dependent cases are not updated at this point.
To make a new version
Open the case that should serve as a parent to the new version. Make all required changes without saving the case. Select Save as Version from File menu. In the Save As dialog, select (or just accept) the name of the new version and click the Save button. You should not change the folder in the Save As dialog. After the version is saved, the difference between this and the original versions is calculated and saved. A new row is added to the table of versions.
To rename a version
Click the version name in the project window with right mouse button and select Rename or Properties from the shortcut menu. In the dialog, type in the new name and press Ok button.
All versions in the projects should have different names. The version names coincide with file names containing the corresponding cases (except that the characters not allowed in file names are replaced with underscore "_"; all file names should be different).
To customize the presentation of cases
The table of versions contains user-defined columns that present parameters and results of simulations that are interesting to compare between cases. Currently we support 3 column formats: (1) number, (2) number with color code, (3) color-coded bar. In the latter case, a diagram with a curve for each version can be opened. Naturally, it is also possible to open any version to see the full results.
To add a column
Open a case containing the variable (or a parameter) to be shown in the column and find it in the outline view. Drag the variable to the project table and drop it at the desired place in the table. This opens Summary Properties dialog with new column inserted. Edit the column properties (see below) and click the Ok button.
Alternatively, you can use "+" button in the Summary Properties dialog to add columns (you still need an open case to select variables from).
If a variable is selected to Color Bar column, it is automatically logged (without modification of Log to field in case documents).
To edit a column
Select any cell in the column you want to edit and click the Edit column button at the bottom of the project window. This opens Summary Properties dialog with the selected column active. In the dialog, you can
- Change the variable shown in the column. To do this, click the navigation button and select the variable in the Select object dialog (you need an open case to select from).
- Select the presentation format. Currently we support 3 column formats: (1) number, (2) number with color code, (3) color-coded bar.
- Edit the column headings (label and unit).
- If the presentation includes numbers, edit the numeric format.
- If the presentation includes colors, provide the numerical values that correspond to the extreme colors (blue and red). These fields are required for presentation with colors.
- Click Advanced button and provide more properties. Currently a single advanced property is supported, :get code, where code is either a script of a function name. The code is applied to the selected variable and should return the value to be shown in the project table. If code is a script, it is executed with 2 named parameters: _as, bound to the presentation format (value, value-color, or color-bar) and _indata, bound to non-NIL if the selected variable is an input data and bound to NIL if the variable is a result of simulation.
To remove a column
Select any cell in the column you want to delete and click the Edit column button at the bottom of the project window. This opens Summary Properties dialog with the selected column active. In the dialog, click buttons "x" and Ok.
To change the order of columns
Select any cell in the column you want to move and click the Edit column button at the bottom of the project window. This opens Summary Properties dialog with the selected column active. In the dialog, click buttons "^" and "v" to reorder the columns, and then Ok button.
To change the dependence of versions
To copy a branch, select the label of the version you want to move or copy and drag it (with left mouse button pressed) to the new location. While dragging, a hashed strip shows the suggested insertion position. Release the mouse button to drop the version at the suggested position. The program shows a menu with list of available operation. These are:
- Move version
The dragged version is moved to the new parent and the difference between that version and its new parent version is calculated and saved (unless dropped to the same parent version as before). If the version is dropped as a root version, the difference script is removed.
If the moved version had child versions, the difference scripts of these versions are merged with the old difference script of the moved version. If a root version was moved without child versions, these child versions become root versions (and their difference scripts are removed).
- Move branch
Same as Move version, but the version is moved together with all dependent versions.
- Copy differences
Create a new branch by applying the difference scripts of the selected version to the target parent.
- Move differences
Move the selected branch to new parent and mark the branch as obsolete. It will be rebuilt (by applying the old difference script to the new parent) when the user executes Update branch or Update All.
It is not possible in one operation to insert a version in the middle of a dependency chain. This may be done by two operations: to insert version a in the chain between b and c, (1) move the version a so that it becomes a child of b and (2) move the branch of c so that it becomes a child of a.
To save a case as a separate document
Use Save As… in File menu. You should save cases in a different folder.
To update and run all versions in a project
Click Update All button at the bottom of the project window. This will (1) run all difference scripts in order to update all out-of-date cases (i.e., the cases whose parent versions or difference scripts have been changed by the user), (2) simulate all cases that have been changed after the previous simulation, (3) collect all results for presentation, (4) save all cases and the project.
If some cases are modified and not saved when updating the project is started, they are automatically saved (or discarded, depending on the user's preferences, see Preferences… in Options menu) after a warning (optional).
To update and run all versions in a branch
Click Update Branch button at the bottom of the project window. This does the same as Update All, but for the branch of the selected row only.
To select simulation type or suppress simulation of version
Click the version name in the project window with right mouse button and select Properties from the shortcut menu. In the dialog, click the Simulation type field and select the desired type from menu.
To suppress the simulation, select "Do not simulate".
If you select "Run script", IDA Modeler will ask you to enter the script code.
Click Ok button.
To expand and collapse a branch
Click the buttons "+" and "-" in the left column of the project table to expand (show) and collapse (hide) all dependent cases of the row's case.
To show column details
Select any cell in the column you want to see details and click Plot button at the bottom of the project window. This opens a diagram containing the column's variable in all versions. Works for "Color bar" columns only.
To preview the effect of modifications
Run the modified case without saving it. The summaries of both versions (saved and modified) are shown in the project table.
Version states
The version table displays the version names in different style depending on the current state of the version:
Normal state (black text, white background)
The case is valid, i.e. it reflects all changes made in the parent cases. The results, if displayed, were calculated from the actual version of the case.
Changed (yellow background)
The case is open, modified, and not yet saved. The results, if displayed, were calculated from the last saved version of the case.
If the modified case has also been simulated, the results of this simulation are shown in an extra row (with label MODIFIED). This allows comparison with the saved version of this case.
If a modified and simulated case has been changed after the simulation, the label MODIFIED is also shown with yellow background.
Requires rebuild (gray text)
An ancestor case has been modified and saved, but the changes are not yet propagated to this (dependent) case.
If such a case is moved to another place in the dependency hierarchy, the "Requires rebuild" flag is removed (unless the new parent also requires rebuild), so the changes in the old ancestor will never be propagated.
Is rebuilding now (blue text)
The case is now rebuilding (this can take some time for big cases).
Is simulating now (green text)
The case is simulating (this can take long time, depending on the case size and simulation period).
The simulation is performed in batch mode, i.e., without interactions with user. This is done to allow rebuilding of big projects at nighttime.
The following states are shown in the result columns:
The result is not ready (marked with "?" in corresponding column)
The case has either not been simulated, or has been modified and saved after the simulation, or this column is added or edited after the simulation of this case, or the simulation failed.
The simulation is suppressed (marked with "-" in columns containing results)
The same as "not ready", but the version is marked with flag "do not simulate".
Missing variable (empty cell in the corresponding column)
The case does not contain the variable to be shown in this column.