Releasing a Simulation Model to a Vault

Old Content - see latest equivalent

Parent article: Vault-Based Domain Models

From a designer's perspective, a vault-based component (Component Item) gathers together all information needed to represent that component across all design domains, within a single entity. It could therefore be thought of as a container in this respect. A 'bucket' into which all domain models and parametric information is stored.

In terms of its representation in the various domains, a vault-based component doesn't contain the domain models themselves, but rather links to these models. These links are specified on the design-side, as part of the source component definition – from which the released Component Item is generated. As such, before you can delve into the process of defining and releasing vault-based components, you must first ensure that all the domain models themselves have been created and released.

This article takes a look at the process of releasing a Simulation Model definition into the vault so that it can be used in the creation of one or more vault-based components.

Defining the Simulation Model

A simulation model definition within a SimModel file (*.SimModel) on the design-side is mapped to a Simulation Model Item on the release side. Each release of the file stores the model data into a new revision of that Item.

Firstly, create a new SimModel file (File » New » Library » SimModel File). The file will open as the active document in the SimModel editor. Both model definition and linkage to a target vault (and Item Revision therein) are handled from within this file.

Initial view within a newly-created Simulation Model file.

The information required to define the model in a SimModel file is as follows:

  • Model Name – use this field to specify the name of the model. When released into a vault, this entry will be used as the target Simulation Model Item's Comment.

This must be the name, as it appears in any referenced model or subcircuit file.

When referencing an MDL file, the name must be that appearing in the .MODEL line of the model's definition. Consider a model for a diode with the following definition:

.MODEL 1N4002 D(IS=2.55E-9 RS=0.042 N=1.75 TT=5.76E-6 CJO=1.85E-11 + VJ=0.75 M=0.333 BV=100 IBV=1E-5 )

The model name here is 1N4002. This is the name that must be entered into the Model Name field.

When referencing a CKT file, the name must be that appearing in the .SUBCKT line of the model's definition. Consider a model for a fuse with the following definition:

.SUBCKT FUSE 1 2 PARAMS: CURRENT=1 RESISTANCE=1m SW1 1 2 3 0 SMOD OFF BNLV 3 0 V=(abs(v(1,2)))



The model name here is FUSE. This is the name that must be entered into the Model Name field.

  • Kind – this drop-down gives access to a number of model categories containing the range of analog device models built-in to SPICE.
  • Sub Kind – this drop-down lists all model types in a chosen category.
  • Spice Prefix – the required prefix for this type of model. Automatically selected for all model Kind/Sub-Kind selections, unless Sub-Kind is set to Generic Editor.
  • Model File – for a model that has been defined using a .mdl or .ckt file, including an intermediary .mdl file used to link to a Digital SimCode definition (in a .scb file), use this field to browse to and nominate the required file. If using a SIMetrix or SIMPLIS model, browse to and nominate the required .lb file (see Support for SIMetrix/SIMPLIS Models).
  • Description – enter a description of the model, for example its purpose. When released into a vault, this entry will be used as the target Simulation Model Item's Description.
  • Netlist Template – displays the information that is entered into the XSpice netlist for a given component. For all of the predefined model kinds and sub-kinds, the Netlist Template is read-only. If, however, one of these predefined entries does not allow enough control over the information placed in the netlist, you can define your own template. To edit the Template, you need to select Generic Editor in the Sub-Kind field – ensuring that the Kind field is first set to General. For all other model sub-kinds, you can effectively change to General/Generic Editor and edit the predefined template – massaging it to your own requirements.
  • Netlist Preview – read-only display of the text exactly as it will be written to the XSpice netlist file when a netlist is generated or a simulation is run.
  • Model Preview – read-only display of the content of the referenced .mdl or .ckt file.
  • Parameters – model-level parameters for the model (see Model-Level Parameters).

When editing, roll-back (or forward) changes using standard Undo and Redo controls, available from the main Edit menu or the Sim Model Standard toolbar. Alternatively, use the Ctrl+Z and Ctrl+Y shortcut keys respectively.

Once the definition of the model is ready, save the file with the same name as the model itself.

Example of a fully defined simulation model - for a standard Schottky Diode.

A SimModel file can also be generated directly from the active Schematic Library or Database Library. For more information, see SimModel File Generation from the Active Schematic Library and SimModel File Generation from the Active Database Library, respectively.

You can now proceed to release the model definition. To do so requires the following steps:

  1. Link the model to the required revision of a target Item in a target Altium Vault. The Item must be of type altium-simulation-model, and the revision in which to release the simulation model data must be in the Planned state.
  2. Release the model definition into that targeted Item-Revision.

Model-Level Parameters

Where applicable, model-level parameters can be defined directly within the SimModel file, since they are naturally part of a model's definition. The Parameters region of the document will automatically populate with parameters applicable to the chosen model Kind/Sub Kind. Parameter values can be edited in two ways:

  • In-Place Editing – click on the Parameter Value field associated to a parameter in the list and enter the required value directly.
  • Dialog-based Editing – click the Edit Parameters button, located below the Parameters region, to access the SimModel Parameters dialog. Parameters applicable to the chosen model Kind/Sub Kind will be presented. Edit the values for these as required. After clicking OK, the Parameters region will be updated with this information.

For the built-in SPICE3f5, supported PSpice and subcircuit model kinds, the available parameters will automatically be listed in the Parameters region (and SimModel Parameters dialog). When using the Generic Editor, controls for adding and removing parameters are provided directly below the region (and in the SimModel Parameters dialog).

Define parameters for the model as part of its definition - either directly using in-place editing, or through the SimModel Parameters dialog.

When a simulation-ready vault component is placed in a design, a simulation parameter can have a different value at the component-level, to that for the same parameter at the model-level. When the netlist is generated, the component-level parameter will have priority. Component-level parameters are naturally defined as part of the source component definition, within a Component Library. For more information, see Adding Component-Level Simulation Parameters.

Linking the Model File to a Vault

The link to the target vault and Item Revision therein, is stored as part of the SimModel file. Link information and related controls are provided on the right-hand side of the document view.

Controls for linking the simulation model definition to a Simulation Model Item in a target vault.

Clicking the Choose button to the right of the Item Revision field will give access to the Choose Item dialog – essentially a trimmed incarnation of the Vaults panel. The field at the top-left of the dialog indicates which vault you are currently exploring. To select a different vault, click the  icon to the left of the vault name (or on the vault name itself) to access a menu of top-level vault management controls. This menu displays all vaults that you currently have an active connection to.

Access to the Choose Item dialog can also be made using the File » Link SimModel to Vault command.

If you have not connected to a vault, use the Vault Administration command on the menu to access the Data Management – Vaults page of the Preferences dialog (DXP » Preferences), from where you can make a connection to the required vault as necessary.

With the required target vault active, you can either drill down through its folder hierarchy to select the required existing Item, or create the folder and/or Item as required, on-the-fly. Ensure that the Item-Revision chosen – which will receive the released model data – is in a Planned state.

Manually linking the model definition to a planned revision of a Simulation Model Item, in the target vault.

Folder Type

Whether you have created a Simulation Model Item in the target vault beforehand, or are creating it in situ at the time of model linking, you will need to first create the folder in which that Item will reside. As part of folder creation, the folder's type can be specified. This has no bearing on the content of the folder – releasing simulation model definitions will always result in Simulation Model Items. It simply provides a visual 'clue' as to what is stored in a folder and can be beneficial when browsing a vault for particular content. To nominate a folder's use as a container for Simulation Model Items, set its Folder Type as altium-simulation-library.

Specifying the folder type - its intended use - provides visual indication of the content contained within that folder while browsing the vault.

Item Naming Scheme

Another important aspect of the parent folder is the Item Naming Scheme employed for it. This defines the format of the unique ID for each Item created in that particular folder. Several default example schemes are available, utilizing the short-form code for either the folder type or the content type. Using a default naming scheme, the software will automatically assign the next available unique ID, based on that scheme, having scanned the entire vault and identifiers of existing Items. This can be a great time-saver when manually creating Simulation Model Items prior to release.

A custom scheme can also be defined for a folder, simply by typing it within the field, ensuring that the variable portion is enclosed in curly braces (e.g. SIMMODEL-001-{C000}).

The Item Naming Scheme of the parent folder is applied to the Unique ID for each Item
created within that folder.

The Item Naming Scheme employed for the parent folder can be changed at any time. The modified scheme will then be applied to any subsequent newly-created Items within that folder.

Item Lifecycle Definition and Revision Naming

When defining the Simulation Model Item, to which the simulation model definition is linked, be sure to specify the type of lifecycle management to be used for the Item, and the naming scheme employed for its revisions, respectively. Once the simulation model definition has been released into the initial revision of the Item, these schemes cannot be changed for that particular Item.

Specify the required schemes in the Item Properties dialog, using the Lifecycle Definition and Revision Naming Scheme fields respectively.

Selecting the Lifecycle Definition and Revision Naming schemes for a manually created Item.

Observing standard revision naming schemes and lifecycle definitions, across the various types of design item in a vault ensures smooth, consistent management of those items. At the lowest level, it's typical for models to use 1-level revision naming with basic lifecycle management – they’re either ready for design reuse or not!

Verifying the Link is Established

Once the required revision of the Simulation Model Item in the target vault is chosen, clicking OK in the Choose Item dialog will create the link between source model definition and target Item. Evidence of the link can be seen back in the SimModel file. Link information is stored in the SimModel file, so be sure to save the file!

Evidence that the SimModel file is now linked to an Item in the vault.

Performing the Release

With the link to the target vault and Item-Revision in place, the process of releasing the simulation model definition into the vault can proceed. Select the File » Release To <TargetVaultName> command. When the data has been prepared to be added to the vault a confirmation dialog will appear. This dialog also includes a field to add any pertinent release notes. Click Yes to commit the simulation model definition to the vault.

After its release, information regarding the Item that the model definition is linked to is updated in the SimModel file – the Revision Details (which will now show the revision's comment and description) and the Revision State (which will now show Released, when using basic lifecycle management). Be sure to save the file. Click the Show in Explorer button to browse the released model directly in the vault using the Vaults panel.

Browsing the released Simulation Model Item in the vault, using the Vaults panel.

The released data stored in the vault consists of the model definition in the .SimModel file, as well as any referenced .mdl or .ckt file. For a modeled digital component, there will be the intermediate .mdl file, as well as the referenced Digital SimCode .scb file. In addition, model-level parameters can also be viewed as part of the model Item's preview. Click on a referenced file to view a preview of its content.

View the content of .mdl, .ckt and .scb files, referenced by simulation models, directly through the Vaults panel.

With the model released, it can now be used in the applicable component definition, ultimately making the released Component Item which references it, simulation-ready. For more information, see Adding a Simulation Model to a Component Definition.

An .scb file typically contains multiple SimCode models. When the simulation model definition is released, the .scb file – released and stored with the SimModel file in the vault – is stripped back to include only the single SimCode model referenced by the simulation model definition, and not the full listing of models.

The released data can be downloaded by right-clicking on the entry for the Item-Revision and choosing the Operations » Download command from the context menu. The downloaded folder for the Item-Revision will contain a Released sub-folder. It is in here that you will find the data.

Support for SIMetrix/SIMPLIS Models

Simulation model definitions referencing SIMetrix or SIMPLIS models can also be released to an Altium Vault. Two aspects to bear in mind when using these types of models are:

  • The Model Name must have a prefix of either SIMetrix_ or SIMPLIS_ respectively. This helps to distinguish between models targeted to these different simulators.
  • The Model File field must point to the underlying model file (*.lb), in which the SIMetrix/SIMPLIS model is defined.

Whereas the model files (*.ckt and *.mdl) used by Altium Designer's built in Simulator usually contain one model each, SIMetrix/SIMPLIS model files (*.lb) contain dozens or even hundreds of models.

The released data stored in the vault consists of the model definition in the .SimModel file, as well as the referenced .lb file. As with all other referenced model files, the content of the .lb file can be viewed within the Vaults panel, along with any model-level parameters for the Simulation Model Item.

Unlike a released .scb file, the released .lb file is not stripped back to contain only the reference model.

An example of a released SIMetrix-based simulation model.

An example of a released SIMPLIS-based simulation model.

Re-releasing the Model Definition

With the source SimModel file linked to the vault and Simulation Model Item therein, re-releasing the simulation model defined in that file – to take into account any modifications – is a straightforward process:

  1. Make the changes to the model's definition as required.
  2. Create a new Planned revision for the linked Simulation Model Item. This can be done from the Lifecycle view for the Item, in the Vaults panel, or from the detailed view for the Item. The latter can be accessed from the SimModel file by clicking the Details button (to the far right of the Item Revision field).
  3. Choose this new Item Revision in the SimModel file.
  4. Save the SimModel file.
  5. Use the File » Release To <TargetVaultName> command.

Streamlined Re-release Through File-less Editing

Main article: File-less Editing in an Altium Vault

File-less editing frees you of the shackles of separate version-controlled source data. You can simply edit a supported Item type using a temporary editor loaded with the latest source direct from the vault itself. And once editing is complete, the entity is re-released into a subsequent planned revision of its parent Item, and the temporary editor closed. There are no files on your hard drive, no questioning whether you are working with the correct or latest source, and no having to maintain separate version control software. The Altium Vault handles it all, with the same great integrity you've come to expect, and in a manner that greatly expedites changes to your data.

A Simulation Model Item can be edited in this way directly from the Vaults panel, or from the Model Links region of a Component Library document, that is itself currently being edited in this manner. In both cases, access to file-less editing is provided through the Edit command on the respective right-click menu.

Releasing Multiple Simulation Model Files

Main article: Batch Releasing to a Vault with the Release Manager

When migrating components from existing component management methodologies to the next-generation vault-based component model, releasing SimModel files each containing a single simulation model definition can be a tedious task – especially since release of a single SimModel file requires that file to be open and active in Altium Designer. This is also the case if changes have been made affecting simulation model definitions across an array of source SimModel files, that need to be re-released into a new revision of each target Simulation Model Item.

To facilitate the release of multiple SimModel files to a target vault simultaneously, Altium Designer provides a Release Manager (File » Release Manager). Use it to batch-release simulation model definitions stored across multiple SimModel files in a nominated source folder location.

Batch-release simulation model definitions, stored in multiple SimModel files, using the Release Manager.

The Release Manager can also be used to quickly generate SimModel files, en masse, from a nominated folder of Schematic Library documents. With the Schematic Libraries loaded, simply use the Generate SimModel Files command from the Migration Tools drop-down menu.

Using the Release Manager, and having generated SimModel files automatically (from an active SchLib, DbLib, or batch of SchLibs), can certainly provide a streamlined productivity boost when it comes to migrating existing library components to a vault. Auto-generated SimModel files have their model definitions specified, but vault-Item link information left undefined. This enables you to use the Release Manager to release into new Items – created as part of the release process – without having to create Simulation Model Items in the vault ahead of time.


You are reporting an issue with the following selected text and/or image within the active document: