Documentation Center

  • Trial Software
  • Product Updates

Putting It Together — Complete Component Examples

Mechanical Component — Spring

The following file, spring.ssc, implements a component called spring.

The declaration section of the component contains:

  • Two rotational nodes, r and c (for rod and case, respectively)

  • Parameter k, with a default value of 10 N*m/rad, specifying the spring rate

  • Through and Across variables, torque t and angular velocity w, to be connected to the rotational domain Through and Across variables later in the file

  • Internal variable theta, with a default value of 0 rad, specifying relative angle, that is, deformation of the spring

The setup section of the component checks that the spring rate constant is nonnegative.

The branches section establishes the relationship between the component Through variable and the component nodes (and therefore the domain Through variable). The t : r.t -> c.t statement indicates that the torque through the spring acts from node r to node c.

In the equation section, the first equation, w == r.w - c.w, establishes the relationship between the component Across variable and the component nodes (and therefore the domain Across variable). It defines the angular velocity across the spring as the difference between the node angular velocities.

The following two equations define the spring action:

  • t = k * theta, that is, torque equals spring deformation times spring rate

  • w = theta.der, that is, angular velocity equals time derivative of spring deformation

component spring
  nodes
    r = foundation.mechanical.rotational.rotational;
    c = foundation.mechanical.rotational.rotational;
  end
  parameters
    k = { 10, 'N*m/rad' };
  end
  variables
    theta = { 0, 'rad' };
    t = { 0, 'N*m' };        % torque through
    w = { 0, 'rad/s' };      % velocity across
  end
  function setup
    if k < 0
      error( 'Spring rate must be greater than zero' );
    end
  end
  branches
    t : r.t -> c.t; % torque through from node r to node c
  end
  equations
    w == r.w - c.w; % velocity across between node r and node c
    t == k * theta;
    w == theta.der;
  end
end

Electrical Component — Ideal Capacitor

The following file, ideal_capacitor.ssc, implements a component called ideal_capacitor.

The declaration section of the component contains:

  • Two electrical nodes, p and n (for + and – terminals, respectively)

  • Two parameters: C, with a default value of 1 F, specifying the capacitance, and V0, with a default value of 0 V, specifying the initial voltage

  • Through and Across variables, current i and voltage v, to be connected to the electrical domain Through and Across variables later in the file

The setup section of the component performs the following:

  • Checks that the capacitance is nonnegative

  • Sets the initial value of the voltage variable, v, to be equal to the V0 parameter value (Initial voltage)

The branches section establishes the relationship between the component Through variable and the component nodes (and therefore the domain Through variable). The i : p.i -> n.i statement indicates that the current through the capacitor flows from node p to node n.

In the equation section, the first equation, v == p.v - n.v, establishes the relationship between the component Across variable and the component nodes (and therefore the domain Across variable). It defines the voltage across the capacitor as the difference between the node voltages.

The second equation defines the capacitor action: I = C*dV/dt, that is, output current equals capacitance multiplied by the time derivative of the input voltage.

component ideal_capacitor
% 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.

  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, 'F'}
        error( 'Capacitance must be greater than zero' )
    end
    v = V0;                 % v(t=0) == V0
  end
  branches
    i : p.i -> n.i; % Current through from node p to node n
  end
  equations
    v == p.v - n.v; % Voltage across between node p and node n
    i == C*v.der;   % Equation defining the capacitor action
  end
end

No-Flow Component — Voltage Sensor

The following file, voltage_sensor.ssc, implements a component called voltage_sensor. An ideal voltage sensor has a very large resistance, so there is no current flow through the sensor. Therefore, declaring a Through variable, as well as writing branches and equation statements for it, is unnecessary.

The declaration section of the component contains:

  • Two electrical nodes, p and n (for + and – terminals, respectively)

  • An Across variable, voltage v1, to be connected to the electrical domain later in the file

Note that a Through variable (current ) is not declared, and there is no branches section.

In the equation section, the first equation, v == p.v - n.v, establishes the relationship between the component Across variable, voltage v1, and the component nodes (and therefore the domain Across variable at these nodes). It defines the voltage across the sensor as the difference between the node voltages.

The second equation defines the voltage sensor action:

  • V == v1, that is, output voltage equals the voltage across the sensor nodes

component voltage_sensor
% Voltage Sensor
% The block represents an ideal voltage sensor. There is no current
% flowing through the component, therefore it is unnecessary to
% declare a Through variable (i1), use a branches section, or
% create an equation statement for current (such as i1 == 0).
%
% Connection V is a physical signal port that outputs voltage value.


  outputs
    V = { 0.0, 'V' }; % V:bottom
  end

  nodes
    p = foundation.electrical.electrical; % +:top
    n = foundation.electrical.electrical; % -:bottom
  end

  variables
    v1 = { 0, 'V' };
  end

  equations
    v1 == p.v - n.v;
    V == v1;
  end

end

Grounding Component — Electrical Reference

The following file, elec_reference.ssc, implements a component called elec_reference. This component provides an electrical ground to a circuit. It has one node, where the voltage equals zero. It also declares a current variable, makes it incident to the component node using the branches section, and does not specify any value for it in the equation section. Therefore, it can take on any value and handle the current flowing into or out of the reference node.

The declaration section of the component contains:

  • One electrical node, V

  • A Through variable, current i, to be connected to the electrical domain later in the file. Note that there is no need to declare an Across variable (voltage) because this is a grounding component.

The branches section establishes the relationship between the component Through variable, current i, and the component nodes (and therefore the domain Through variable). The i : V.i -> * statement indicates that the current flows from node V to the reference node, indicated as *.

The equation section of the component contains the equation that defines the grounding action:

  • V.v == 0, that is, voltage at the node equals zero

component elec_reference
% Electrical Reference
% Electrical reference port. A model must contain at least one
% electrical reference port (electrical ground).

  nodes
    V = foundation.electrical.electrical; % :top
  end

  variables
    i = { 0, 'A' };
  end

  branches
    i : V.i -> *;
  end

  equations
    V.v == 0;
  end

end

Composite Component — DC Motor

In the Permanent Magnet DC Motor example, the DC Motor block is implemented as a masked subsystem.

The following code implements the same model by means of a composite component, called DC Motor. The composite component uses the components from the Simscape™ Foundation library as building blocks, and connects them as shown in the preceding block diagram.

component DC_Motor
% DC Motor
% This block models a DC motor with an equivalent circuit comprising a
% series connection of a resistor, inductor and electromechanical converter.
% Default values are as for the DC Motor Simscape example, ssc_dcmotor.

nodes
    p = foundation.electrical.electrical;               % +:left
    n = foundation.electrical.electrical;               % -:left
    R = foundation.mechanical.rotational.rotational;    % R:right
    C = foundation.mechanical.rotational.rotational;    % C:right
end

parameters
    rotor_resistance    = { 3.9, 'Ohm' };           % Rotor Resistance
    rotor_inductance    = { 12e-6, 'H' };           % Rotor Inductance
    motor_inertia       = { 0.01, 'g*cm^2' };       % Inertia
    breakaway_torque    = { 0.02e-3, 'N*m' };       % Breakaway friction torque
    coulomb_torque      = { 0.02e-3, 'N*m' };       % Coulomb friction torque
    viscous_coeff       = { 0, 'N*m*s/rad' };       % Viscous friction coefficient
    velocity_threshold  = { 0.1, 'rad/s' };         % Linear region velocity threshold
    back_emf_constant   = { 0.072e-3, 'V/rpm' };    % Back EMF constant
end

components(Hidden=true)
    rotorResistor                  = foundation.electrical.elements.resistor(R = rotor_resistance);
    rotorInductor                  = foundation.electrical.elements.inductor(l = rotor_inductance);
    rotationalElectroMechConverter = foundation.electrical.elements.rotational_converter(K =
                                        back_emf_constant);
    friction                       = foundation.mechanical.rotational.friction(brkwy_trq =
                                        breakaway_torque, Col_trq = coulomb_torque,
                                        visc_coef = viscous_coeff, vel_thr = velocity_threshold);
    motorInertia                   = foundation.mechanical.rotational.inertia(inertia = motor_inertia);
end

connections
    connect(p, rotorResistor.p);
    connect(rotorResistor.n, rotorInductor.p);
    connect(rotorInductor.n, rotationalElectroMechConverter.p);
    connect(rotationalElectroMechConverter.n, n);
    connect(rotationalElectroMechConverter.R, friction.R, motorInertia.I, R);
    connect(rotationalElectroMechConverter.C, friction.C, C);
end

end

The declaration section of the composite component starts with the nodes section, which defines the top-level connection ports of the resulting composite block:

  • Two electrical conserving ports, + and -, on the left side of the block

  • Two mechanical rotational conserving ports, R and C, on the right side of the block

The parameters declaration block lists all the parameters that will be available in the composite block dialog box.

The components block declares all the member (constituent) components, specifying their complete names starting from the top-level package directory. This example uses the components from the Simscape Foundation library:

  • Resistor

  • Inductor

  • Rotational Electromechanical Converter

  • Rotational Friction

  • Inertia

The components block also links the top-level parameters, declared in the parameters declaration block, to the parameters of underlying member components. For example, the Rotor Resistance parameter of the composite block (rotor_resistance) corresponds to the Resistance parameter (R) of the Resistor block in the Foundation library.

You do not have to link all the parameters of member blocks to top-level parameters. For example, the Rotational Friction block in the Foundation library has the Transition approximation coefficient parameter, which is not mapped to any parameter at the top level. Therefore, the composite model always uses the default value of this parameter specified in the Rotational Friction component, 10 rad/s.

The connections block defines the connections between the nodes (ports) of the member components, and their connections to the top-level ports of the resulting composite block, declared in the nodes declaration block of the composite component:

  • Positive electrical port p of the composite component is connected to the positive electrical port p of the Resistor

  • Negative electrical port n of the Resistor is connected to the positive electrical port p of the Inductor

  • Negative electrical port n of the Inductor is connected to the positive electrical port p of the Rotational Electromechanical Converter

  • Negative electrical port n of the Rotational Electromechanical Converter is connected to the negative electrical port n of the composite component

  • Mechanical rotational port R of the composite component is connected to the following mechanical rotational ports: R of the Rotational Electromechanical Converter, R of the Rotational Friction, and I of the Inertia

  • Mechanical rotational port C of the composite component is connected to the following mechanical rotational ports: C of the Rotational Electromechanical Converter and C of the Rotational Friction

These connections are the textual equivalent of the graphical connections in the preceding block diagram.

Was this topic helpful?