Documentation Center

  • Trial Software
  • Product Updates

Create Block Libraries

Create a Library

You can create your own block library and add it to the Simulink® Library Browser (see Add Libraries to the Library Browser). To create a library:

  1. Select Library from the New submenu of the File menu.

    Simulink creates a model file for storing the new library and displays the file in a new model editor window.

      Tip   You can also use the new_system command to create the library and the open_system command to open the new library.

  2. Drag blocks from models or other libraries into the new library.

      Note:   If you want to be able to create links in models to a block in the library, you may need to provide a mask (see Masking) for the block. You can also provide a mask for a subsystem in a library, but you do not need to have a mask to create links to it in models.

  3. Save the library's file under a new name.

Create a Sublibrary

If your library contains many blocks, consider grouping the blocks into a hierarchy of sublibraries. Creating a sublibrary entails inserting a reference in the Simulink model file of one library to the model file of another library. The referenced file is called a sublibrary of the parent (i.e., referencing) library. The sublibrary is said to be included by reference in the parent library.

To include a library in another library as a sublibrary:

  1. Open the parent library.

  2. Add a Subsystem block to the parent library.

  3. Delete the subsystem's default input and output ports.

  4. Create a mask for the subsystem that displays text or an image that conveys the sublibrary's purpose.

  5. Set the subsystem's OpenFcn parameter to the name of the sublibrary's model file.

  6. Save the parent library.

Modify and Lock Libraries

When you open a library, it is automatically locked and you cannot modify its contents. To unlock the library, select Diagram > Unlock Library.

When you close the library window, Simulink locks the library.

Locking a library prevents a user from inadvertently modifying a library, for example, by moving a block in the library or adding or deleting a block from the library. If you attempt to modify a locked library, Simulink displays a dialog box that allows you to unlock the library and make the change.

To unlock a block library from the MATLAB® command line, use the following command:

set_param('library_name', 'Lock', 'off');

You must then relock the library from the MATLAB command line to prevent further changes. Use the following command to relock a block library:

set_param('library_name', 'Lock', 'on');

If you want to control end user editing of linked blocks and prevent unintentional disabling of links, you can lock links to a library. See Lock Links to Blocks in a Library.

When you save a library, Simulink checks file permissions and offers to try to make the library writable if necessary.

Make Backward-Compatible Changes to Libraries

Simulink provides the following features to facilitate making changes to library blocks without invalidating models that use the library blocks.

Forwarding Tables

You can create forwarding tables for libraries to specify how to update links in models to reflect changes in the parameters. Use the Forwarding Table to map old library blocks to new library blocks. For example, if you rename or move a block in a library, you can use a forwarding table to enable Simulink to update models that link to the block.

After you specify the forwarding table entry in a library, any links to old library blocks will be updated when you load a model containing links to old blocks. Library authors can use the forwarding tables to automatically transform old links into updated links without any loss of functionality and data. Use the forwarding table to solve compatibility issues with models containing old links that cannot load in the current version of Simulink. Library authors do not need to run slupdate to upgrade old links, and can reduce maintenance of legacy blocks.

To set up a forwarding table for a library,

  1. Select Diagram > Unlock Library.

  2. Select File > Library Properties > Library Properties. The Library Properties dialog box opens.

  3. Select the Forwarding Table tab.

  4. Define the mapping from old library blocks to new library blocks.

    1. Click the Add New Entry button. A new row appears in the table.

    2. Enter values in Old Block Path and New Block Path columns.

      Click GCB to get the path of the currently selected block.

      If you select identical old and new library block names and paths, the Forwarding Table automatically populates library version numbers in the Version columns. The initial value of the LibraryVersion property is the ModelVersion of the library at the time the link was created. The value updates with increments in the model version of the library.

    3. (Optional ) You can define a transformation function to update old link parameter data using a MATLAB file on the path. Specify the function in the Transformation Function column. Transforming old link parameter data for the new library block enables you to load old links and preserve parameter data.

      If you do not want to specify a transformation function, do not edit the field. When you save the library, the column will display No Transformation.

  5. Click OK to apply changes and close the dialog box.

    After specifying the forwarding table mapping, when you open a model containing links to the library, links to old library blocks will be updated.

To view an example of a forwarding table:

  1. Enter

    open_system('simulink')
  2. Select File > Library Properties > Library Properties

  3. Click the Forwarding Table tab.

  4. View how the forwarding table specifies the mapping of old blocks to new blocks. You cannot make changes because the library is locked. Do not edit the forwarding table for your Simulink library.

  5. Click OK to close the dialog

The following example shows a forwarding table that defines:

  • A block with the same name moving to a different library (Constant A)

  • A block changing name in the same library (Block X to Block Y)

  • A block changing name, moving library, and applying a transformation function (Gain A to Gain B)

  • A block with three version updates (Block A) using a transformation function. When you select identical old and new library block names and paths, the Forwarding Table automatically populates version numbers in the Version columns. If this is the first entry with identical names, version starts at 0, and the new version number is set to the ModelVersion of the library. For subsequent entries, the first version is set to the previous entry's new version, and the new version is set to the current ModelVersion of the library.

At the command line you can create a simple forwarding table specifying the old locations and new locations of blocks that have moved within the library or to another library. You associate a forwarding table with a library by setting its ForwardingTable parameter to a cell array of two-element cell arrays, each of which specifies the old and new path of a block that has moved. For example, the following command creates a forwarding table and assigns it to a library named Lib1.

set_param('Lib1', 'ForwardingTable', {{'Lib1/A', 'Lib2/A'} 
{'Lib1/B', 'Lib1/C'}});

The forwarding table specifies that block A has moved from Lib1 to Lib2. and that block B is now named C. Suppose that you open a model that contains links to Lib1/A and Lib1/B. Simulink updates the link to Lib1/A to refer to Lib2/A and the link to Lib1/B to refer to Lib1/C. The changes become permanent when you subsequently save the model.

Writing Transformation Functions.  You can use transformation functions to add or remove parameters and define parameter values. Transforming old link parameter data for the new library block enables you to load old links and preserve parameter data that differs from library values. Define your transformation function using a MATLAB file on the path, then specify the function in the Forwarding Table Transformation Function column.

The transformation function in your MATLAB file must be like the following:

function outData = TransformationFcn(inData)

where inData is a structure with fields ForwardingTableEntry and InstanceData, and ForwardingTableEntry is a structure.

This general transformation function can have many local functions defined in it. The function calls the appropriate local functions based on old block names and versions. Use this to combine many local functions into a single transformation function, to avoid having many transformation functions on the MATLAB path.

InstanceData and NewInstanceData are structures with fields Name and Value. Instance data means the names and values of parameters that are different from the library values.

outData is a structure with fields NewInstanceData and NewBlockPath.

The following example code shows how to define a transformation function that adds a parameter with value uint8 to update a Compare To Constant block:

function [outData] = TransformationCompConstBlk(inData)
% Example transformation Function for old 'Compare To Const' block.
%
% If instanceData of old 'Compare To Const' block does not have 
% the 'OutDataTypestr' parameter, 
% add the parameter with value 'uint8'. 
%%

outData.NewBlockPath = '';
outData.NewInstanceData = [];

instanceData = inData.InstanceData;
% Get the field type 'Name' from instanceData
[ParameterNames{1:length(instanceData)}] = instanceData.Name;

if (~ismember('OutDataTypeStr',ParameterNames))
    % OutDataTypeStr parameter is not present in old link. Add it and set value uint8
    instanceData(end+1).Name = 'OutDataTypeStr';
    instanceData(end).Value = 'uint8';
end

outData.NewInstanceData = instanceData;

Creating Aliases for Mask Parameters

Simulink lets you create aliases, i.e., alternate names, for a mask's parameters. A model can then refer to the mask parameter by either its name or its alias. This allows you to change the name of a mask parameter in a library block without having to recreate links to the block in existing models (see Using Mask Parameter Aliases to Create Backward-Compatible Parameter Name Changes).

To create aliases for a masked block's mask parameters, use the set_param command to set the block's MaskVarAliases parameter to a cell array that specifies the names of the aliases in the same order as the mask names appear in the block's MaskVariables parameter.

Using Mask Parameter Aliases to Create Backward-Compatible Parameter Name Changes.  The following example illustrates the use of mask parameter aliases to create backward-compatible parameter name changes.

  1. Create a new library. File > New > Library

  2. Open the model masking_example described in How Mask Parameters Work. Drag the masked block named mx+b into your new library and rename it to Line.

  3. Right-click the block and select Properties. In the Block Properties dialog, select the Block Annotation tab. In the Enter text and tokens for annotation box, enter

    m = %<m>
    b = %<b>

    The block displays the value of its m and b parameters,

  4. Right-click the block, and select Mask > Mask Parameters. In the Block Parameter dialog, enter 0.5 for the Slope and 0 for the Intercept.

  5. Save the new library with the filename mylibrary.

  6. Create a new Simulink model. File > New > Model.

  7. From the mylibrary window, drag an instance of the Line block to your new model. Rename the instance LineA.

  8. Right-click the block and select Mask > Mask Parameters. In the Block Parameters dialog, change the value Slope to -0.5. and change the value Intercept. to 30. Select Display > Library Links > User Defined.

  9. Add a Scope and Clock block to your model and connect them to your block. Save the new model with the filename mymodel.

  10. From the Simulation menu, select Model Configuration Parameters. From the Type list, select Fixed-step. From the Solver list, select discrete (no continuous states. In the Fixed-step size box, enter 0.1. Simulate model.

    Note that the model simulates without error.

  11. Save and close mymodel.

  12. Open mylibrary.

  13. Edit mask. Right-click block, select Edit mask. In the Mask Editor dialog,

    • Select the Parameters tab. In the Dialog parameters section and Variable column, change the variable m to slope and b to intercept.

    • Select the Icon & Ports tab. In the Icon Drawing commends box, change the variable m to slope and b to intercept.

  14. Right-click the Line block, select Properties. In the Block Properties dialog, .

    • Select the Block Annotation tab . In the Enter text and tokens of annotation box, rename the m parameter to slope and the b parameter to intercept.

  15. Click OK and save mylibrary.

  16. Reopen mymodel.

    Note that LineA icon has reverted to the appearance of its library master (i.e., mylib/Line) and that its annotation displays question marks for the values of m and b. These changes reflect the parameter name changes in the library block. In particular, Simulink cannot find any parameters named m and b in the library block and hence does not know what to do with the instance values for those parameters. As a result, LineA reverts to the default values for the slope and intercept parameters, thereby inadvertently changing the behavior of the model. The following steps show how to use parameter aliases to avoid this inadvertent change of behavior.

  17. Close mymodel.

  18. In the Library: mylibrary window, select the Line block.

  19. Execute the following command at the MATLAB command line.

    set_param(gcb, 'MaskVarAliases',{'m', 'b'})

    This specifies that m and b are aliases for the Line block slope and intercept parameters.

  20. Reopen mymodel.

    Note that LineA appearance, not the annotation, now reflects the value of the slope parameter under its original name, i.e., m. This is because when Simulink opened the model, it found that m is an alias for slope and assigned the value of m stored in the model file to the LineA slope parameter.

  21. Change LineA block annotation property to reflect LineA parameter name changes, replace

    m = %<m>
    b = %<b>

    with

    m = %<slope>
    b = %<intercept>

    LineA now appears with m = -0.5 and b = 30.

    Note that LineA annotation shows that, thanks to parameter aliasing, Simulink has correctly applied the parameter values stored for LineA in the mymodels file to the block renamed parameters.

Was this topic helpful?