Working with the Variant Management Dialog

Created: July 12, 2022 | Updated: July 20, 2022 | Applies to version: 5

Nexus message

This documentation page references Altium NEXUS/NEXUS Client (part of the deployed NEXUS solution), which has been discontinued. All your PCB design, data management and collaboration needs can now be delivered by Altium Designer and a connected Altium 365 Workspace. Check out the FAQs page for more information.

Parent page: Design Variants

Variants are created and configured in the Variant Management dialog. To open the dialog, select Variants from the Project menu (shortcut: C, V).

The dialog has two main regions:

The upper Components for project region, which lists all of the components in the base design, and if applicable, columns for the applied Variants.
The lower Component Parameters region, which details all of the parameters of the component(s) currently selected in the upper region, and if applicable, columns for the applied Variants.

Variants are created and configured in the Variant Management dialog.

Double-click on a component in the Variant Management dialog to jump to that component on the schematic or select Cross Probe from the right-click context menu.

Creating a New Variant

Click the Add Variant button button in the Variant Management dialog to create a new variant of the base design. The Edit Project Variant dialog will open, enter a name for the variant in the Description field and click OK. The other options in this dialog are discussed in more detail later.

The Add Variant button includes a dropdown menu that provides access to the Clone Selected Variant command (available when an existing Variant is selected). Cloning is a quick and easy way to define a number of variants that are very similar.

An additional column will then appear on the right of the Variant Management dialog, with the new Variant name as the column title. All the cells will be empty, where an empty cell indicates that this component is Fitted and unchanged from the base design. The components can now be configured for the new variant. The image below shows a project that has had two variants created, BGA and TSOP.

Region 1 details the components in the base design, region 2 details the components in the BGA variant, and region 3 details the components in the TSOP variant.

To make a variant the active selection, click its variant name in the column header, or click in any of that variant's cells.

The Variant Management dialog includes a number of interface features that assist the display of useful information. These are configured via the right-click context menu.

Right-click context menu, Variant Management dialog

Useful commands include:

Columns:
- Hierarchy Path column – shows the location of the component in the design hierarchy.
- Original Library Link column – details where the base component was sourced from.
Set Selected As – submenu used to choose the type of variation (Fitted, Not Fitted, Alternate). Can be used instead of clicking the control in the component cell. Only available when you right-click on a Variant's component cell.
Only Show Varied Parameters – only display components that have some form of variation applied, in the Variant Management dialog.
Filter – submenu that gives control of which types of variations are displayed in the Variant Management dialog (Varied Parameters, Not Fitted, Alternate). Works well in combination with the Only Show Varied Parameters command.

Varied parameters – a parameter that is varied from the base design is shown in bold in the Component Parameters area of the Variant Management dialog, making it easy to visually identify.

Defining Component Variations

Once the Variant itself has been created, the state of each component is ready to be varied. This can be done by clicking the component cell in the variant column to reveal the Ellipsis control used to configure a variation control, or by right-clicking on a non-selected cell to access the context menu Set Selected As sub-menu.

The Ellipsis control used to configure a variation control opens the Edit Component Variation dialog which (along with the Set Selected As sub-menu) offers three choices:

Fitted – The original component as used in the base design is also fitted/used in this variant of that design. For a newly added variant, all components are fitted by default, and the cells for these fitted components are empty. Note that individual parameters can also be varied for a fitted component, by simply typing in a new parameter value in the dialog's Parameters region for that Variant.
Not Fitted – The original component as used in the base design is not fitted/used in this variant of that design. For a Not Fitted component status, the cell displays the text Not Fitted and the dialog's lower Parameters region will be blank.
Alternate Part – This option allows a different (alternate) part to be selected. Once that part is chosen, the cell displays the alternate part's source Link. The lower Component Parameters region of the dialog will display all of the parameters in the alternate part.

Standard Windows multi-select techniques are supported. Use these to select and configure multiple components simultaneously.

Choosing an Alternate Part

When the Alternate Part option is selected, the Edit Component Variation dialog expands to show the base parameters of the existing part. Use the button to browse and locate the required alternate part component in the Replace Component dialog – a modal dialog version of the Components panel. All of Altium NEXUS's component storage models are supported, such as independent libraries, database libraries, as well as server-based components (as shown in the example below).

After selecting an alternate part, the software checks for pin compatibility between the selected alternate component and the original base design component. To be pin-compatible, the alternate must have the same number of pins as the original component, and those pins must be identical in their location and electrical type. The graphical primitives used in the symbols for the two components are not required to match. If the software detects that the alternate component is not pin-compatible, a Confirm dialog must be dismissed before the replacement is accepted. In this case, you need to be mindful of the potential impact on the wiring, and that an error violation may be encountered as the design is validated (Project » Validate, <project name>).

The example of an Alternate Part variation.

The newly applied alternative component can be checked back in the design space. In the applicable schematic sheet for that component, switch to the compiled tab view and then select the required variant in the Variants section of the project, in the Projects panel.

The Schematic Editor will use the symbol graphics for the alternate component, however, if the component is pin-compatible and graphically similar there may be little noticeable change.

To help make it easy to visually identify varied components, the color and font of varied parameters (such as the component comment string), can also be varied. This is configured in the Variant Options dialog. Click Drawing Style in the Variant Management dialog to open the dialog. Note the green italic font used for the alternate component in the animation below.

Graphically identifying the varied component; in this example, both variants use the same component symbol, but the BGA variant uses a different size SRAM.

If an alternate component is not already used in some part of the design, the symbol graphics for the alternate component are stored in the project folder as a dedicated file type: [ProjectName].PrjPcbVariants. Using the .PrjPcbVariants file keeps the project independent from the source libraries that were used to create the design. Note that parameters change for the alternate components defined in the Variant Management dialog are saved in the project file itself.

Symbol Display Mode

If a base component uses a graphical display mode other than the default Normal Mode, and it also has an alternate component defined in a variant, then the alternate component will attempt to use the same graphical display mode. Conversely, if the alternate component does not include this graphical display mode, then the Normal mode is used.

Part view Modes are defined in the Schematic Library Editor with the Component Display Mode commands and are selected for a placed component in the Graphical section of the Properties panel, as shown below. In this example the base part symbol uses Mode, Alternate 1.

An Alternate Part will attempt to use the same graphical display mode number as the base part.

Variants when a DbLink File is used

Altium NEXUS supports several ways of storing and working with components, including the use of a DBLink file with the project. A DBLink file is an interface between the components on the schematic and a company database.

Rather than just creating a reference from each component to a specific database record (as is typically done when you place a component from a DBLib-type library), the DBLink model relies on the designer initiating a query action based on one or more component parameters. The software then searches the database for a record with fields that contain matching values, and when a match occurs, other field values from that record (such as the Part Number) can be returned to the Altium NEXUS component. The component parameter-to-database field mapping is defined in the DBLink document, as is the target database.

► Learn more about Working with Database Libraries

In a design that does not use Variants, the query action is performed via the Update Parameters from Database command, and can also be performed during BOM generation by enabling the Include Parameters from Database option (see below), to extract BOM-specific component data, such as price.

For a design that includes Variants, the parameters used to query the database are varied in the Variant Management dialog. Since those parameter values only exist in the Variant Management dialog, the Update Parameters from Database command is not used to retrieve database information – instead the parameters are extracted from the database when the BOM is being generated.

Display of Variant Management dialog data

The Variant Management dialog includes features to help control the amount of data displayed, which is particularly useful when working on a large design.

To remove columns that are not of interest, right-click in the upper part of the dialog and use the Columns option in the context menu to toggle the visibility of any column.
To display only those components being varied, right-click in the upper part of the dialog and select Only Show Varied Components option from the context menu.
When the Only Show Varied Components mode has been selected, right-click again and configure the Filter options. In the image shown below, the Filter has been configured to display only those components that use Alternate Parts.
To change the order of the listed Variants, select and drag a variant column heading to a new location. Use this in combination with the Fit to Width checkbox to position and size the variant of interest.

The Variant Management dialog, with columns hidden and a filter applied to only show components that use an Alternate Part.
The Variant Management dialog, with columns hidden and a filter applied to only show components that use an Alternate Part.

Display of Variants in design documents

The way in which varied components are presented in schematic design documents (and PCB outputs) is configured in the Variant Options dialog. Those settings subsequently affect how the component variations are presented in printed or PDF outputs, and in PCB printouts such as Assembly drawings. To access the Variant Options dialog, click at the bottom of the Variant Management dialog, after selecting a cell in the relevant variant column.

Use the Variant Options dialog to configure how variants are presented on the schematic and in PCB printouts. Use the Variant Options dialog to configure how variants are presented on the schematic and in PCB printouts.

Resetting and Updating Variant Data

Design variations set up in the Variant Management dialog are ultimately saved in the project file. This includes the Not Fitted state, local parameter variations to a Fitted component, and the parameter values of Alternate Parts. The actual Alternate Parts are stored in a [ProjectName].PrjPcbVariants file. The Variant Management dialog includes commands for resetting parameters and updating components, which helps to ensure that they are in sync with the source component libraries.

Updating a Varied Parameter

Parameters modified locally in the Variant Management dialog can be restored to their original value by right-clicking on the modified parameter (shown in bold) in the Variant Parameter list, and then choosing Reset Selected from the context menu – as shown below. Note that multiple parameters can be selected at once then reset in a single action, or Reset All used to reset all parameters for that component.

Modified parameter(s) can have their value(s) restored using the Reset Selected command.

Updating an Alternate Part Parameter

If a library component that is used as an Alternate Part has had parameters changed in the library, then you to can bring those changes directly into the variant definitions in your project by right-clicking in that Variant's Parameter list and selecting Update Values from Library from the menu (as shown below). Note that this updates the parameters, if you need to update the graphic, use the technique described below.

If an Alternate Part component has been modified in the library, use the Update Values from Library command to refresh the copy used in the project.

Following the Update Values from Library command, browse to and locate the component in the source library or Managed Component Server (via the Browse Libraries dialog or the Server content Explorer) and click OK to open the Update Project Variants From Library dialog. Select/deselect the Parameters from Library Component and Variants to Update, then click OK to complete the update process.

If the component selected for a parameter update is a server-hosted managed component, a basic modal dialog version of the Components panel will be opened rather than the Browse Libraries dialog. Browse or Search to locate the component, click OK to open the Update Project Variants From Library dialog then select the desired parameters for updating, as described here.

Updating a varied component from the source library. Here you configure which parameters are updated, and to which variant the updates are applied.

All parameters are listed on the left of the Update Project Variants From Library dialog – if required, any parameter can be deselected to exclude it from the update process. On the right of the dialog, the target Project Variant can be changed (Project Variant To Update). This will default to select the Variant that was selected when the Update Values from Library command was activated.

Note that this parameter update process brings parameter values directly from the library into the Variant Management dialog, and does not update the copy of the component that is stored in the [ProjectName].PrjPcbVariants file. If you later perform one of the Reset commands to reset parameter values, which retrieves values from the PrjPcbVariants file, it may revert a parameter value to an earlier value and overwrite any current changes. To ensure that this cannot happen, update the component in the PrjPcbVariants file using the process described below.

Completely updating an Alternate Part

If the source component for an Alternate Part has been edited in its library, it can be updated in the design by running the Update from Library dialog.

Launched from the Tools menu in the schematic editor, the dialog includes an option to Include Variants. When this option is enabled, the component list will expand to include any components that have been used as Alternate Parts. Check the components in the list to be updated, and then complete the Wizard to update the required parts from the source.

To fully update an Alternate Part, including its graphic, enable the Include Variants checkbox and enable the part to be updated.

If there have been changes made to library components used in the base design, these are also updated in the usual way:

via the Schematic editor Tools » Update from Library command
or the Schematic Library editor Tools » Update Schematics command.

Change multiple Parameters for Multiple Components

The Variant Management dialog supports multi-select, which means that any number of components can be selected simultaneously in the upper (Component) part of the dialog, and then updates performed on any number of parameters selected in the lower (Parameters) part of the dialog. The dialog also offers Filters (via the right-click context menu), to further refine the selection and the displayed data.

By way of example, to reset the manually-varied parameters for all components, in all variants:

In the upper (Component) part of the dialog, use the Only Show Varied Components right-click menu option in combination with the right-click Filter options to only Show Fitted with Varied Parameters. The component list should now display only those components that have manually varied parameters.
Right-click in the component list and choose Select All from the context menu. All components currently displayed in the upper part of the dialog will be selected.
Then right-click in the lower (Parameters) part of the dialog and choose Select All from that context menu. All parameters for all components will now be selected. Note that the Select Column command could have been chosen instead, which would allow an action (such as Reset) to be applied to the components in a specific Variant (column).
Right-click again in the parameters list and choose Reset Selected from the context menu. Hover the cursor over the image below to show steps 2, 3 and 4.

Resetting all manually varied parameters, for all components, in all variants. Hover the cursor over the image to show steps 2, 3 and 4.

If you have been experimenting with the Filter options and have applied different filters, you may need to reset the filter before attempting another update. To do this, disable the Only Show Varied Components option to clear the filter system, then re-apply it and clear the Filter options as required.

Working with Variant Parameters

Altium NEXUS supports Parameters at various levels of a project. For example, document-level parameters can be added to each schematic sheet in the Parameters tab of the Schematic editor Properties panel (available when nothing is selected). Project-level parameters can also be added to a project on the Parameters tab of the Project Options dialog (Project » Options). Further to this, parameters can also be added to a Variant via the Edit Project Variant dialog. In the Variant Management dialog, select the variant column and click the Edit Variant button to open this dialog.

Parameters included at various levels in a project exist in a hierarchy, which means you can, in fact, create a parameter with the same name at different levels in the project, where each has a different value. Altium NEXUS resolves this situation using priorities, in the following way:

Variant (highest priority)
Schematic document
Project

This arrangement means that the parameter value defined in a schematic document overrides the value defined in the Project options, and the parameter's value defined in a Variant overrides the value defined in the schematic document. Note that schematic-level parameters are not available on the PCB or in the BOM – for these types of output, project or variant parameters should be used.

In the images below, a Parameter called ProjectTitle has been defined for the project, and also for each variant. The animation shows the behavior on the PCB as the Variants selector is used to show the base design, then each variant.

A ProjectTitle parameter added to the project (via the Project Options dialog) has also been added to each design Variant, but with a different Value in each case.

A special string .ProjectTitle has been placed on the PCB overlay, which is automatically linked to project and variant parameters of the same name. A special string .ProjectTitle has been placed on the PCB overlay, which is automatically linked to project and variant parameters of the same name.

Variant Errors

Variant settings are stored in the project file (*.PrjPcb), and this data is read, analyzed and loaded into the Variant Management dialog when that dialog is opened. If issues are detected when the data loads, such as any mismatches between component designators or component UIDs, an Information dialog will open to outline the problem.

Resolve designator and UID mismatches before continuing with the design process.

Component UID mismatches are automatically resolved, and these corrections will be retained when the project is saved. Duplicate designators must be corrected at the schematic level. To resolve these, validate the project (Project » Validate <project name>) and check the Messages panel for warning/error details.

Printer-friendly version

If you find an issue, select the text/image and pressCtrl + Enterto send us your feedback.