Converting Subsystems into Composite Components

The subsystem2ssc function lets you convert a subsystem consisting entirely of Simscape™ blocks into a textual Simscape file. The function generates a composite component file based on the subsystem configuration. If the subsystem being converted contains nested subsystems, then the function generates several Simscape files, one for each subsystem.

Use this functionality to:

Facilitate the authoring of composite components. When writing textual files, it can be difficult to visualize the connections inside a composite component. This functionality lets you create a model out of Simscape blocks, enclose it into a subsystem, and then convert this subsystem into a textual composite component.
Improve the usability of a complex subsystem, by reducing clutter and exposing only a few relevant parameters at the top level.
Share your models with customers without revealing the underlying intellectual property.

Suggested Workflows

To create a reusable composite component:

Model a physical component (such as a motor, valve, amplifier, and so on) using blocks from the Simscape Foundation library, add-on product libraries, or custom blocks. Fine-tune the parameters and troubleshoot the model, as necessary.
Select the blocks and connection lines that represent your physical component, and create a subsystem from selection. For more information, see Create Subsystems.
The subsystem does not need to be masked. However, to expose underlying block parameters or variables at the top level, you have to mask the subsystem and promote these parameters or variables to the subsystem mask. For more information, see Parameter Promotion.
Use the subsystem2ssc function to convert your subsystem into a textual composite component. If the subsystem being converted contains nested subsystems, then the function generates several Simscape files, one for each subsystem.

To enable model sharing without revealing the underlying intellectual property:

When converting the subsystem, use the subsystem2ssc function with a targetFolder argument to place the file or files generated by the function into a target folder.
For example,
```
openExample('simscape/PermanentMagnetDCMotorExample')
subsystem2ssc('PermanentMagnetDCMotor/DC Motor','./MotorsLibrary')
```
creates a file named DC_Motor.ssc and places it into the folder named MotorsLibrary.
Create and place other motor models into the same target folder.
Protect the source files in the target folder by using the sscprotect function.
Share the contents of the folder with other users or customers without revealing the underlying source.

You can place generated files into a namespace folder and build a library by using the sscbuild or sscmirror functions. However, if your subsystem contains nested subsystems, you have to edit the subcomponent paths in the generated files manually to match your intended namespace structure. Alternatively, you can use the Simscape Component blocks, which work with the flat hierarchy of the target folder without modification.

Parameter Promotion

You can mark member block and subsystem parameters for promotion to the top level using the subsystem mask. The subsystem2ssc function automatically generates the corresponding Simscape code, similar to composite components. For more information, see Parameterizing Composite Components.

When you deploy the generated composite file as a custom block, the block dialog box contains these promoted parameters only.

This example shows how you can make the motor inertia modifiable at the DC Motor subsystem level, and the effect on generated Simscape code and the resulting custom block mask:

Open the Permanent Magnet DC Motor example model. At the MATLAB^® command prompt, enter:
```
openExample('simscape/PermanentMagnetDCMotorExample')
```
Right-click the DC Motor subsystem and, from the context menu, select Mask > Edit Mask.
Click the Parameters & Dialog tab. Use the Promote One-to-One control option to promote the Inertia parameter of the Inertia block to the subsystem mask.
Click Save Mask.

Convert the DC Motor subsystem into a Simscape component file and place this file in your current working folder:

subsystem2ssc('PermanentMagnetDCMotor/DC Motor')

The function creates a file named DC_Motor.ssc in the current folder. Open the file in the editor.

component (Propagation = blocks) DC_Motor
  parameters
    inertia = {.01, 'cm^2*g'}; %Inertia
  end
  nodes
    C = foundation.mechanical.rotational.rotational;
    R = foundation.mechanical.rotational.rotational;
    V1 = foundation.electrical.electrical;
    V0 = foundation.electrical.electrical;
  end
  components(ExternalAccess = observe)
    Rotor_Resistance = foundation.electrical.elements.resistor(R = {3.9, 'Ohm'});
    Rotor_Inductance = foundation.electrical.elements.inductor(l = {1.2e-05, 'H'}, r = {0, 'Ohm'}, g = {1e-09, '1/Ohm'}, i_L = {value = {0, 'A'}, priority = priority.high});
    Rotational_Electromechanical_Converter = foundation.electrical.elements.rotational_converter(K = {.0006875493541569879, 's*V/rad'});
    Inertia = foundation.mechanical.rotational.inertia(inertia = inertia);
    Friction = foundation.mechanical.rotational.friction(brkwy_trq = {2e-05, 'm*N'}, brkwy_vel = {.03347, 'rad/s'}, Col_trq = {2e-05, 'm*N'}, visc_coef = {0, 'm*s*N/rad'});
  end
  connections
    connect(V0,Rotor_Resistance.p);
    connect(Rotational_Electromechanical_Converter.p,Rotor_Inductance.n);
    connect(V1,Rotational_Electromechanical_Converter.n);
    connect(Rotor_Inductance.p,Rotor_Resistance.n);
    connect(R,Friction.R);
    connect(R,Inertia.I);
    connect(R,Rotational_Electromechanical_Converter.R);
    connect(C,Friction.C);
    connect(C,Rotational_Electromechanical_Converter.C);
  end
end

Notice the top-level parameters block containing the inertia parameter.

If you now point a Simscape Component block to the DC_Motor.ssc source file, the block dialog box contains a parameter named Inertia.

Limitations

The subsystem being converted must consist entirely of blocks authored in Simscape language, such as blocks from the Simscape Foundation library, add-on product libraries, or custom blocks. Blocks from the Simscape Utilities library are not authored in Simscape language, therefore:

If the subsystem contains a Simscape Component block, then during the conversion this block is replaced by its source component.
Connection Port blocks are represented by the connect statements.
Other blocks from the Utilities library (Solver Configuration, Simscape Bus, and so on) are not allowed because they have no equivalent textual representation.

The subsystem being converted cannot contain multiple Simscape networks.

If the subsystem being converted contains nested subsystems, you might have to manually edit the references to the generated files for nested subsystems when running sscbuild on the namespace.

If you use blocks from Simscape libraries, keep the original subsystem used to generate the composite component. Simscape language does not support forwarding tables or versioning. As a result, if the underlying library blocks undergo changes in a future release, a textual composite component generated from these blocks might stop working. If that happens, open the original subsystem in the new release and rerun the conversion.