Managed Simulation Models in an Altium Vault

Parent page: Vault-based Domain Models

From a designer's perspective, a vault 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 component doesn't contain the domain models themselves, but rather links to these models. These links are specified 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 components, you must first ensure that all the domain models themselves have been created and released.

Altium Designer, in conjunction with Altium Vault, caters for the ability to create and manage Simulation Model Items in an Altium Vault. Such Items are created directly within the target vault. Once a Simulation Model Item has been created (and data released into a revision of it), and its lifecycle state set to a level that the organization views as ready for use at the design level, it can be reused in the creation of one or more vault components.

Folder Type

When creating the folder in which to store Simulation Model Items, you can specify the folder's type. This has no bearing on the content of the folder - releasing a simulation model definition will always result in a corresponding Simulation Model Item. 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 Simulation Models, when defining the folder properties in the Edit Folder dialog.

Specifying the folder type - its intended use - gives a visual indication of the content of that folder when browsing the vault!

Item Type

When creating a target Simulation Model Item in which to store your simulation model definition, ensure that its Content Type is set to Simulation Model, in the Item Properties dialog. If you are creating the Item in a Simulation Models type folder, this Item type will be available from the right-click context menu when creating the Item.

Creating a Simulation Model Item within a Simulation Models folder - the correct Content Type is available on the context menu.

Releasing a Simulation Model

So far, we've discussed the support for a Simulation Model Item in the vault, in terms of related folder and item types. Releasing an actual defined simulation model into a revision of such an item can be performed in a single streamlined way.

A simulation model can be edited and released into the initial revision of a newly-created Simulation Model Item, courtesy of the vault's support for direct editing. Direct editing frees you from 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 released (or 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.

When you create a Simulation Model Item, you have the option to edit and release a simulation model definition into the initial revision of that item, after creation. To do so, simply enable the option Open for editing after creation, at the bottom of the Create Item dialog (which is enabled by default). The Item will be created and the temporary SimModel Editor will open, presenting a .SimModel document as the active document in the main design window. This document will be named according to the Item-Revision, in the format: <Item><Revision>.SimModel (e.g. SIM-001-0001-1.SimModel).

Example of editing the initial revision of a Simulation Model Item, directly from the vault - the temporary SimModel Editor provides the document with which to define your
simulation model.

Use the document to define the simulation model as required. For more information on doing this, see Defining the Simulation Model.

The Sim Model Standard toolbar provides three relevant controls when direct editing:

•  - Save Active Document. Use this button to save the changes made to the document. This is required before you can release the document back to the vault.
•  - Release Document. Use this button to release the defined ssimulation model to the vault, storing it within the initial (planned) revision of the target Simulation Model Item. The Create Revision dialog will appear, in which you can change Comment, Description, and add release notes as required. The document and editor will close after the release. The document containing the source simulation model definition, *.SimModel, will be stored in the revision of the Item.
•  - Cancel Editing. Use this button if you wish to cancel editing. The document and editor will close, and nothing will be released to the target Simulation Model Item.

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. For a SIMetrix or SIMPLIS model, there will be the referenced .lb file. In the Vaults panel, switch to the Preview aspect view, then click on a referenced file to view a preview of its content. Model-level parameters will also be presented, where applicable.

Browse the released revision of the Simulation Model Item, back in the Vaults panel. Switch to the Preview aspect view to see the released data.

Defining the Simulation Model

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 back into the vault, this entry will be used as the Simulation Model Item Revision's Comment.

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)))

.MODEL SMOD SW (VT=\{(CURRENT*RESISTANCE)\} RON=1g ROFF=\{RESISTANCE\})

.ENDS FUSE

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 back into the vault, this entry will be used as the Simulation Model Item Revision'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).

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.

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

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.

Example definitions for SIMetrix and SIMPLIS simulation models.

Reusing a Managed Simulation Model Item

Related page: Managed Components in an Altium Vault , Controlling Access to Vault Content

Once a simulation model definition has been released to an Altium Vault, and its lifecycle state set to a level that the organization views as ready for use at the design level, that model can be reused in the creation of one or more vault components . When directly editing a Component Item from a vault, a Simulation Model Item revision is added for use to the resulting Component Library's Model Links region. This region can be thought of in terms of a 'bucket' of domain models that can be accessed by any component definition in the Component Library document. Assignment is simply a case of specifying which links are required for each definition.

Example of referencing a revision of a Simulation Model Item as a model link in a Component Library, when direct editing the definition for a Component Item (vault component).

Re-Releasing a Simulation Model Item

At any stage, you can come back to any revision of a Simulation Model Item in the vault, and edit it directly. Simply right-click on the revision and choose the Edit command from the context menu. Once again, the temporary editor will open, with the file (containing the source simulation model definition) contained in the revision, opened for editing. Make changes as required, then commit the release of the document into the next revision of the item.

Accessing the command to launch direct editing of an existing revision of a Simulation Model Item.

Updating Related Component Items

When you make a change to a vault-based domain model - be it a symbol, footprint model, or simulation model - the moment you release that change into a new revision of the model's Item, any Component Items that use that model will become effectively out of date, still using the previous revision. In most cases, you will no doubt want to re-release those components, with the respective model links updated to use the latest revisions available. To streamline this process, Altium Vault, in conjunction with Altium Designer, facilitates the ability to update related Component Items - at the point of re-releasing a model Item - after having made any modifications to that model through the direct editing feature.

The option to perform this update to the parent Component Items, can be found in the Create Revision dialog, that appears when releasing the modified simulation model definition back to the target Altium Vault. This option - Update items related to <ModelItemRevision> - is enabled by default.

Accessing the option to update related Component Items, that are referencing the Simulation Model Item
being re-released.

Once you click OK in the Create Revision dialog, the modified simulation model definition is released back to the vault, and its associated temporary editor closed. A Component Library document is then opened in its associated temporary editor (for direct editing), presenting the following:

• Definitions for all components that are associated to (reference) the Simulation Model Item.
• The Model Links region shows the latest (just released) revision for that Simulation Model Item.
• The entry for the linked model - in the applicable Models field of each component definition - is set to use that latest revision of the just-released Simulation Model Item.

Example of pushing a change made to a Simulation Model Item, through to a Component Item that references it.

Unless you need to make any further adjustments, simply click the  button (in the editor's standard toolbar), to release the modified definition(s) into new revision(s) of the corresponding Component Item(s), back in the target vault:

• If only a single Component Item is affected, the Create Revision dialog will appear. Change Comment, Description, and add release notes as required. After clicking OK, the release will proceed, and the temporary Component Library editor then closed.
• If multiple Component Items are affected, the Release Manager dialog will appear. This lists all component Items that are scheduled to be released - by default all enabled for inclusion in the release. Make any changes - to Comment, Description, and inclusion (Enabled option) - as required, then click the Release Items button. View the impending release changes in the subsequent Confirm Release dialog, then click OK. Once the release process completes - indicated by Release Successful in the applicable Action-Status field(s) - close the dialog. The temporary Component Library editor will also then be closed.

Downloading Released Data

Download the data stored in a revision of a Simulation Model Item by right-clicking on that revision and choosing the Operations » Download command from the context menu. The applicable files will be downloaded into a sub-folder under the chosen directory, named using the Item Revision name. The file can be found in the Released folder therein.

Migrating Existing Schematic Libraries

Main page: Streamlined Migration of Existing Libraries to an Altium Vault

Altium Designer, in conjunction with Altium Vault (3.0 or later) provides a streamlined, simple process to quickly migrate your existing libraries to an Altium Vault. The GUI to this process - the Library Migrator view - presents an intuitive flow that takes initial selected libraries, and migrates them to a target Altium Vault. Catering for all types of libraries, relating to older component management methodologies - SCHLIB, PCBLIB, INTLIB, DBLIB, SVNDBLIB - the Library Migrator is the perfect solution to quickly building your company's set of vault components, and the many benefits that such components enjoy (high-integrity, lifecycle management, centralized storage and management, where-used functionality, ease of design resuse). And while the migration process can be configured - giving you enhanced control over how that migration is performed - at its most simplistic, you can simply accept the default settings and set the migration in motion within a matter of clicks.

All information that is present in an original source library is migrated, in order to arrive at a folder of unified components (vault components that have assigned part choices), with all referenced domain models (schematic symbols, PCB footprints, 3D Models, Simulation Models), and parametric information. Component templates can even be created, and used to create those vault components. And if your original components have multiple PCB footprints defined, you can rest assured that the Library Migrator will bring those models across, and keep the current default footprint too.

Accessing the Library Migrator view - the user interface to the component migration process.

Batch Releasing File-based Simulation Model Files

If you have a set of file-based simulation model definitions (*.SimModel) that you need to release to a target Altium Vault quickly, and simultaneously, then you can use Altium Designer's Release Manager. Use it to batch-release simulation definitions stored across multiple source documents, in a nominated source folder location.

Accessed the Release Manager dialog by running the File » Release Manager command.

Release simulation model definitions, stored in one or more source documents, using the Release Manager.

Setting up for release couldn't be simpler:

• Set the Document Type to SIMMODEL.
• Point to a top-level folder containing the simulation model files you want to release. Files can be stored in sub-folders within this folder.
• Choose the target vault.
• Choose to create a top-level folder in the vault based on the nominated top-level Windows folder, or choose an existing vault folder. You can optionally create sub-folders in the nominated vault folder, for each Windows sub-folder. Additionally, you can opt to create a vault folder for each source simulation model file.
• Use the Default Options for New Released Simulation Models region of the Release Manager to control how required new Items are created as part of the release process - in terms of Lifecycle Definition, Item Naming (default is SIM-{00000}) and Item Revision Naming schemes, and starting index.
• Hit the Analyze Folders button.

Analysis of source folders and target vault folders (and Items) based on your chosen options will be performed and the source simulation model files detected will be listed. For each entry, the target Item will be displayed, its current and/or next revision (as applicable) and the action that will be performed by the release process.

Enable the simulation model definitions that you want to release and then click the Prepare Items and Documents button to effectively commit the link information to the source simulation model files involved in the release. Once saved, proceed with the release by clicking the Release Items button.