Main Content

This case study explains how to build your own library of custom blocks based on component files. It uses an example library of capacitor models. The library makes use of the Simscape™ Foundation electrical domain, and defines three simple components. For more advanced topics, including adding multiple levels of hierarchy, adding new domains, and customizing the appearance of a library, see Case Study — Electrochemical Library.

The example library comes built and on your path so that it is readily executable.
However, it is recommended that you copy the source files to a new directory, for
which you have write permission, and add that directory to your MATLAB^{®} path. This will allow you to make changes and rebuild the library for
yourself. The source files for the example library are in the following package
directory:

matlabroot/toolbox/physmod/simscape/simscapedemos/+Capacitors

where * matlabroot* is the MATLAB root directory on your machine, as returned by entering

matlabroot

in the MATLAB Command Window.

After copying the files, change the directory name `+Capacitors`

to another name, for example `+MyCapacitors`

, so that your copy of
the library builds with a unique name.

To build the library, type

ssc_build MyCapacitors

in the MATLAB Command Window. If building from within the
`+MyCapacitors`

package directory, you can omit the argument
and type just

ssc_build

When the build completes, open the generated library by typing

MyCapacitors_lib

For more information on the library build process, see Building Custom Block Libraries.

To add a block, write a corresponding component file and place it in the package
directory. For example, the Ideal Capacitor block in your
`MyCapacitors_lib`

library is produced by the
`IdealCapacitor.ssc`

file. Open this file in the MATLAB Editor and examine its contents.

component IdealCapacitor % Ideal Capacitor % Models an ideal (lossless) capacitor. The output current I is related % to the input voltage V by I = C*dV/dt where C is the capacitance. % Copyright 2008-2017 The MathWorks, Inc. nodes p = foundation.electrical.electrical; % +:top n = foundation.electrical.electrical; % -:bottom end parameters C = { 1, 'F' }; % Capacitance end variables i = { 0, 'A' }; % Current v = {value = { 0, 'V' }, priority = priority.high}; % Voltage drop end branches i : p.i -> n.i; % Through variable i from node p to node n end equations assert(C > 0) v == p.v-n.v; % Across variable v from p to n i == C*v.der; % Capacitor equation end end

First, let us examine the elements of the component file that affect the block
appearance. Double-click the Ideal Capacitor block in the
`MyCapacitors_lib`

library to open its dialog box, and compare
the block icon and dialog box to the contents of the
`IdealCapacitor.ssc`

file. The block name, Ideal Capacitor, is
taken from the comment on line 2. The comments on lines 3 and 4 are then taken to
populate the block description in the dialog box. The block ports are defined by the
nodes section. The comment expressions at the end of each line control the port
label and location. Similarly in the parameters section, the comments are used to
define parameter names in the block dialog box. For details, see Customizing the Block Name and Appearance.

Also notice that in the equation section there is an assert to ensure that the capacitance value is always greater than zero. This is good practice to ensure that a component is not used outside of its domain of validity. The Simscape Foundation library blocks have such checks implemented where appropriate.

In this example library there are two additional components that can be used for ultracapacitor modeling. These components are evolutions of the Ideal Capacitor. It is good practice to incrementally build component models, adding and testing additional features as they are added.

**Ideal Ultracapacitor**

Ultracapacitors, as their name suggests, are capacitors with a very high
capacitance value. The relationship between voltage and charge is not constant,
unlike for an ideal capacitor. Suppose a manufacturer data sheet gives a graph of
capacitance as a function of voltage, and that capacitance increases approximately
linearly with voltage from the 1 farad at zero volts to 1.5 farads when the voltage
is 2.5 volts. If the capacitance voltage is denoted *v*, then the
capacitance can be approximated as:

$$C=1+0.2\xb7v$$

For a capacitor, current *i* and voltage *v* are
related by the standard equation

$$i=C\frac{dv}{dt}$$

and hence

$$i=({C}_{0}+{C}_{v}\xb7v)\frac{dv}{dt}$$

where *C _{0}* = 1 and

`IdealUltraCapacitor.ssc`

:i == (C0 + Cv*v)*v.der;

In order for the Simscape software to interpret this equation, the variables
(`v`

and `i`

) and the parameters
(`C0`

and `Cv`

) must be defined in the
declaration section. For more information, see Declare Component Variables and
Declare Component Parameters.

Implementing some component equations requires the use of internal variables. An
example is when implementing an ultracapacitor with resistive losses. There are two
resistive terms, the effective series resistance *R*, and the
self-discharge resistance *R _{d}*. Because of
the topology, it is not possible to directly express the capacitor equations in
terms of the through and across variables

**Ultracapacitor with Resistive Losses**

This block is implemented by the component file
`LossyUltraCapacitor.ssc`

. Open this file in the MATLAB Editor and examine its contents.

component LossyUltraCapacitor % Lossy Ultracapacitor % Models an ultracapacitor with resistive losses. The capacitance C % depends on the voltage V according to C = C0 + V*dC/dV. A % self-discharge resistance is included in parallel with the capacitor, % and an equivalent series resistance in series with the capacitor. % Copyright 2008-2017 The MathWorks, Inc. nodes p = foundation.electrical.electrical; % +:top n = foundation.electrical.electrical; % -:bottom end parameters C0 = { 1, 'F' }; % Nominal capacitance C0 at V=0 Cv = { 0.2, 'F/V'}; % Rate of change of C with voltage V R = {2, 'Ohm' }; % Effective series resistance Rd = {500, 'Ohm' }; % Self-discharge resistance end variables i = { 0, 'A' }; % Current vc = {value = { 0, 'V' }, priority = priority.high}; % Capacitor voltage end branches i : p.i -> n.i; % Through variable i from node p to node n end equations assert(C0 > 0) assert(R > 0) assert(Rd > 0) let v = p.v-n.v; % Across variable v from p to n in i == (C0 + Cv*vc)*vc.der + vc/Rd; % Equation 1 v == vc + i*R; % Equation 2 end end end

The additional variable is used to denote the voltage across the capacitor,
*v _{c}*. The equations can then be
expressed in terms of

i == (C0 + Cv*vc)*vc.der + vc/Rd;

Summing voltages gives the second Simscape equation:

v == vc + i*R;

As a check, the number of equations required for a component used in a single connected network is given by the sum of the number of ports plus the number of internal variables minus one. This is not necessarily true for all components (for example, one exception is mass), but in general it is a good rule of thumb. Here this gives 2 + 1 - 1 = 2.

In the Simscape file, the initial condition (initial voltage in this example) is
applied to variable `vc`

with ```
priority =
priority.high
```

, because this is a differential variable. In this case,
`vc`

is readily identifiable as the differential variable as it
has the `der`

(differentiator) operator applied to it.

The capacitor blocks in the example library `MyCapacitors_lib`

have icons associated with them.

During the library build, if there is an image file in the directory with the same
name as the Simscape component file, then this is used to define the icon for the block.
For example, the Ideal Capacitor block defined by
`IdealCapacitor.ssc`

uses the
`IdealCapacitor.jpg`

to define its block icon. If you do not
include an image file, then the block displays its name in place of an icon. For
details, see Customize the Block Icon.