add_block

Add block to model

Syntax

h = add_block(source,dest)

h = add_block(___,Name=Value)

Description

h = add_block(source,dest) adds a copy of the block specified by source to the destination specified by dest. The new block is added at the same position in the block diagram as the source block appears in its parent block diagram.

The destination model must be loaded.

h = add_block(___,Name=Value) specifies options using one or more name-value arguments in addition to the input arguments in the previous syntax. For example, to add a Gain block that multiplies the input by 5, set Gain to "5".

Examples

Add Block to Model from Library

You can add a block from a library using the add_block function with these input arguments:

• The library block path from the top level of the Library Browser tree hierarchy to the library block you want to add, for example, "Simulink/Math Operations/Gain"

• The full block path from the top level of the model hierarchy to where you want to add the new block, for example, "myModel/mySubsystem/myblock"

Both paths must end in a block name.

In this example, you add a customizable circular gauge to the Controller subsystem in the f14 model.

Open the example. Then, load or open the destination model.

open_system("f14")

Suppose you do not know the exact name of the block needed to complete this task or the location of the block in the Library Browser tree. To get the library block path, do a keyword search in the Library Browser. Open the Library Browser. In the search box, type gauge and press Enter.

In the search results, pause on the circular gauge icon. A tooltip displays the library block path.

Add the Circular Gauge block to the Controller subsystem. Name the block myGauge.

• The library block path is "simulink_hmi_customizable_blocks/Circular Gauge".

• The full block path is "f14/Controller/myGauge".

add_block("simulink_hmi_customizable_blocks/Circular Gauge","f14/Controller/myGauge");

To see the block, in the f14 model, navigate into the Controller subsystem.

open_system("f14/Controller")

Add Block from Another Model

Add a copy of a block from the f14 model to the vdp model.

Load or open the destination model.

open_system("vdp");

Add the Actuator Model block from the f14 model to the vdp model.

add_block("f14/Actuator Model","vdp/Actuator Model");

Add Block Using Unique Name

Add a Scope block from the Simulink® library to the model vdp. Because the vdp model already contains a block named Scope, use the MakeNameUnique option to create a unique name for the new block.

Load or open the destination model.

open_system("vdp");

Add the Scope block from the Simulink® Sinks library to the vdp model. Set MakeNameUnique to "on".

add_block("simulink/Sinks/Scope","vdp/Scope",MakeNameUnique="on")

Add Block and Set Parameters

Add a block from a library to a model and set parameters using a name-value argument.

Load or open the destination model.

open_system("vdp");

Add a Gain block from the library to the vdp model. Then, set the Gain value to 5.

add_block("simulink/Math Operations/Gain","vdp/Five",Gain="5")

Add Blocks for Ports

How you add a block for a port depends on your goal. You can add a block for a new or existing port. You can also duplicate a block that corresponds with an input port.

Add Blocks for New Ports

Create and open a model named PortBlockCreation.

mdl = "PortBlockCreation";
new_system(mdl);
open_system(mdl);

To create ports identified by port number, add In1 and Out1 blocks. By default, adding an In1 or Out1 block creates a port.

add_block("simulink/Ports & Subsystems/In1",...
    "PortBlockCreation/In1")
add_block("simulink/Ports & Subsystems/Out1",...
    "PortBlockCreation/Out1")

To create ports identified by port name, add In Bus Element and Out Bus Element blocks. By default, new In Bus Element and Out Bus Element blocks correspond with ports named InBus and OutBus, respectively. These ports also have a port number. Optionally, specify a custom name for the port with the PortName block parameter.

add_block("simulink/Ports & Subsystems/In Bus Element",...
    "PortBlockCreation/InBusElement")
add_block("simulink/Ports & Subsystems/Out Bus Element",...
    "PortBlockCreation/OutBusElement")

To create a port when you add an In Bus Element or Out Bus Element block, set CreateNewPort to "on".

add_block("simulink/Ports & Subsystems/In Bus Element",...
    "PortBlockCreation/InBusElement1",CreateNewPort="on")
add_block("simulink/Ports & Subsystems/Out Bus Element",...
    "PortBlockCreation/OutBusElement1",CreateNewPort="on")

When you do not set CreateNewPort to "on", the behavior varies.

• Suppose you have ports named InBus and OutBus. The added block corresponds with one of these ports. If you specify a port name when you add the block, the software renames the InBus or OutBus port to use the specified port name.

• Suppose you have only custom-named ports. The added block corresponds with a new port. If you specify a port name when you add the block, the new port uses the specified port name.

Add Blocks for New Port Elements

In Bus Element and Out Bus Element blocks let you select multiple elements from an input port and connect multiple elements to an output port.

To add an element to an In Bus Element block, copy an existing block that corresponds with the port and specify a unique name for the new element.

add_block("PortBlockCreation/InBusElement",...
    "PortBlockCreation/InBusElement2",Element="signal2")

To add an element to an Out Bus Element block, copy an existing block that corresponds with the port. Optionally, specify a unique element name.

add_block("PortBlockCreation/OutBusElement",...
    "PortBlockCreation/OutBusElement2")

Duplicate Blocks for Input Ports

Multiple blocks in a block diagram can use the same input from an input port. Duplicating a block that corresponds with an input port can simplify line routing.

To duplicate an In1 block, copy the block from the block diagram and set CopyOption to "duplicate".

add_block("PortBlockCreation/In1",...
    "PortBlockCreation/In1Dup",CopyOption="duplicate")

To duplicate an In Bus Element block, copy the block.

add_block("PortBlockCreation/InBusElement",...
    "PortBlockCreation/InBusElementDup")

The duplicate blocks use the same port number as the original blocks. For name-based ports, the block selects the same element from the same port as the original block.

Input Arguments

source — Block to copy

block path

Block to copy, specified as a block path. For more information about block paths, see Get Handles and Paths.

To copy a block from a model, specify the block path. The new block has the same parameter settings.

Example: add_block("vdp/Mu","mymodel/Mu")

To copy a block from a library, specify the library block path. To get the library block path, pause on the block in the Library Browser. Alternatively, open the library, select the block, and enter gcb at the command line. To open the library, in the Library Browser, right-click the library name in the library list and select Open library_name library.

Example: add_block("simulink/Math Operations/Gain","mymodel/Gain")

To create a block with a certain block type, specify the block type as 'built-in/blocktype', where blocktype is the programmatic block name. To get the value of the BlockType parameter for a block, see Common Block Properties. Blocks added using 'built-in/blocktype' can have different configurations than library blocks.

Example: add_block("built-in/Gain","mymodel/Gain")

Multiple library blocks have SubSystem as the BlockType. When you specify the source block as "built-in/SubSystem", the new block represents a subsystem with one input and one output. For other subsystems and masked blocks, use the library block path instead of the BlockType value.

dest — Name and location of new block

block path

Name and location of new block, specified as a block path.

Example: add_block("simulink/Math Operations/Gain","f14/Controller/MyNewBlock")

Name-Value Arguments

Specify optional pairs of arguments as Name1=Value1,...,NameN=ValueN, where Name is the argument name and Value is the corresponding value. Name-value arguments must appear after other arguments, but the order of the pairs does not matter.

Example: add_block("simulink/Math Operations/Gain","mymodel/Gain",Gain="5") adds a Gain block that multiplies its input by 5.

For the add_block function, specify block parameter and property values as name-value arguments. For information about block parameters and properties, see Programmatically Specify Block Parameters and Properties.

MakeNameUnique — Unique block name

"off" (default) | "on"

Unique block name, specified as "off" or "on".

To create a unique block name for the added block, set MakeNameUnique to "on". When the specified block name exists, the software appends a number to the end of the block name or increments the number at the end of the block name.

Example: add_block("simulink/Math Operations/Gain","mymodel/Gain",MakeNameUnique="on")

CopyOption — Copy option

"" (default) | "nolink" | "duplicate"

Copy option, specified as "", "nolink", or "duplicate".

• "nolink" — The new block does not link to the custom library that contains the source block.

• "duplicate" — The new block duplicates an input port block and has the same port number as the source block. To branch a signal from an input port without creating a port or adding lines, duplicate the block that corresponds with the input port. For more information, see Create Duplicate Inport Blocks.

Example: add_block("myLibrary/CustomBlock","myModel/CustomBlock",CopyOption="nolink")

Example: add_block("myModel/mySubsystem/Inport","myModel/mySubsystem/InportDup",CopyOption="duplicate")

CreateNewPort — New bus element port

"off" (default) | "on"

New bus element port, specified as "off" or "on". The source block must be an In Bus Element or Out Bus Element block.

To add a block for a new port, set CreateNewPort to "on". Optionally, specify the name of the new port with the PortName parameter. By default, the name of the new port is a combination of the port name from the copied block and a number. If the port name from the copied block already ends in a number, the number is incremented for uniqueness.

Setting CreateNewPort to "off" does not prevent port creation. For example, the first In Bus Element or Out Bus Element block that you add to your model creates a port. Adding a block and specifying a unique port name with PortName can also create a port.

When you set CreateNewPort to "off", you allow the added block to correspond with an existing port. For example, when you copy an In Bus Element or Out Bus Element block from your model, you can have the new block represent a new element of the port by specifying the element name with the Element parameter.

For more information on how to author bus element ports programmatically, see Programmatically Create Bus Element Ports.

Example: add_block("simulink/Ports & Subsystems/In Bus Element","myModel/InBusElement1",CreateNewPort="on")

Output Arguments

h — New block

handle

New block, returned as a handle.

For more information about block handles, see Get Handles and Paths.

Tips

To prevent overlapping blocks, specify the position of the new block with the Position block property. For more information, see Programmatically Specify Block Parameters and Properties.

Version History

Introduced before R2006a