Documentation |
On this page… |
---|
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 Generate Custom Block Libraries from Simscape Component Files.
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-2013 The MathWorks, Inc. nodes p = foundation.electrical.electrical; % +:top n = foundation.electrical.electrical; % -:bottom end parameters C = { 1, 'F' }; % Capacitance V0 = { 0, 'V' }; % Initial voltage end variables i = { 0, 'A' }; % Current through variable v = { 0, 'V' }; % Voltage across variable end function setup if C <= 0 error( 'Capacitance must be greater than zero' ) end v = V0; end branches i : p.i -> n.i; % Through variable i from node p to node n end equations 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 setup section there is a check 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 C_{v} = 0.2. This equation is implemented by the following line in the equation section of the Simscape file 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 Declaring Component Variablesand Declaring 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 i and v.
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-2013 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 V0 = { 0, 'V' }; % Initial voltage end variables i = { 0, 'A' }; % Current through variable vc = { 0, 'V' }; % Internal variable for capacitor voltage end function setup if C0 <= 0 error( 'Nominal capacitance C0 must be greater than zero' ) end if R <= 0 error( 'Effective series resistance must be greater than zero' ) end if Rd <= 0 error( 'Self-discharge resistance must be greater than zero' ) end vc = V0; end branches i : p.i -> n.i; % Through variable i from node p to node n end equations 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 v, i, and v_{c} using Kirchhoff's current and voltage laws. Summing currents at the capacitor + node gives the first Simscape equation:
i == (C0 + Cv*v)*v.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 and not v. This is because initial conditions should be applied only to differential variables. 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.