the simulation platform for power electronic systems · integration with simulink coder. . . . . ....

electrical engineering software

Plexim GmbH [email protected] www.plexim.comp

lecs U

ser Manual Version 3.4

THE SIMULATION PLATFORM FOR

POWER ELECTRONIC SYSTEMS

User Manual Version 4.5

How to Contact Plexim:

+41 44 533 51 00 Phone%+41 44 533 51 01 Fax

Plexim GmbH Mail)Technoparkstrasse 18005 ZurichSwitzerland

[email protected] Email@http://www.plexim.com Web

PLECS User Manual

© 2002–2020 by Plexim GmbH

The software PLECS described in this manual is furnished under a licenseagreement. The software may be used or copied only under the terms of thelicense agreement. No part of this manual may be photocopied or reproducedin any form without prior written consent from Plexim GmbH.

PLECS is a registered trademark of Plexim GmbH. MATLAB, Simulink andSimulink Coder are registered trademarks of The MathWorks, Inc. Otherproduct or brand names are trademarks or registered trademarks of their re-spective holders.

mailto:[email protected]

http://www.plexim.com/

Contents

Contents iii

Before You Begin 1Installing PLECS Blockset . . . . . . . . . . . . . . . . . . . . . . . . . . 1

Installation on Microsoft Windows . . . . . . . . . . . . . . . . . . . 1Installation on macOS . . . . . . . . . . . . . . . . . . . . . . . . . . 1Installation on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2Configuring the MATLAB Search Path . . . . . . . . . . . . . . . . 3Configuring PLECS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4Installing Different Versions of PLECS Blockset in Parallel . . . . 4Uninstalling PLECS Blockset . . . . . . . . . . . . . . . . . . . . . . 4

Installing PLECS Standalone . . . . . . . . . . . . . . . . . . . . . . . . . 5Installation on Microsoft Windows . . . . . . . . . . . . . . . . . . . 5Installation on macOS . . . . . . . . . . . . . . . . . . . . . . . . . . 5Installation on Linux . . . . . . . . . . . . . . . . . . . . . . . . . . . 5Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

License File Location . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6Network Licensing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7What’s New in Version 4.5 . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Major New Features . . . . . . . . . . . . . . . . . . . . . . . . . . . 8New and Enhanced Library Components . . . . . . . . . . . . . . . 8Further Enhancements . . . . . . . . . . . . . . . . . . . . . . . . . . 9

Contents

1 Getting Started 11

Getting Started with PLECS Blockset . . . . . . . . . . . . . . . . . . . . 11

A Simple Passive Network . . . . . . . . . . . . . . . . . . . . . . . . 11

Buck Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

Getting Started with PLECS Standalone . . . . . . . . . . . . . . . . . . 20

A Simple Passive Network . . . . . . . . . . . . . . . . . . . . . . . . 20

Buck Converter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

2 How PLECS Works 27

Modeling Dynamic Systems . . . . . . . . . . . . . . . . . . . . . . . . . . 27

System Equations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Block Diagrams . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Physical Models . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Simulating Dynamic Systems . . . . . . . . . . . . . . . . . . . . . . . . . 29

Model Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Model Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Fixed-Step Simulation . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Sampled Data Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Sample Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

Sample Time Inheritance . . . . . . . . . . . . . . . . . . . . . . . . 39

Multirate Systems . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Data Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

Blocks with an Implicit Output Data Type . . . . . . . . . . . . . . 42

Specifying an Output Data Type . . . . . . . . . . . . . . . . . . . . 43

Data Type Inheritance . . . . . . . . . . . . . . . . . . . . . . . . . . 43

iv

Contents

3 Using PLECS 45Configuring PLECS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45

Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Thermal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Scope Colors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Update . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Coder . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Installing Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49

Creating a New Circuit with PLECS Blockset . . . . . . . . . . . . . . . 50

Customizing the Circuit Block . . . . . . . . . . . . . . . . . . . . . 51

Using the Library Browser . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Copying a Component into a Schematic . . . . . . . . . . . . . . . . 54

Moving a Component . . . . . . . . . . . . . . . . . . . . . . . . . . . 54

Specifying Component Parameters . . . . . . . . . . . . . . . . . . . 54

Displaying Parameters in the Schematic . . . . . . . . . . . . . . . 55

Changing Parameters of Multiple Components . . . . . . . . . . . . 56

Changing Parameters During a Simulation . . . . . . . . . . . . . . 56

Changing Component Names . . . . . . . . . . . . . . . . . . . . . . 56

Changing the Orientation of Components . . . . . . . . . . . . . . . 57

Getting Component Help . . . . . . . . . . . . . . . . . . . . . . . . . 57

Libraries . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Creating a New Library in PLECS Blockset . . . . . . . . . . . . . 58

Creating a New Library in PLECS Standalone . . . . . . . . . . . . 58

Creating a Library Reference . . . . . . . . . . . . . . . . . . . . . . 58

Updating a Library Reference . . . . . . . . . . . . . . . . . . . . . . 59

Breaking a Library Reference . . . . . . . . . . . . . . . . . . . . . . 59

Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Signal Connections and Physical Connections . . . . . . . . . . . . 60

Creating Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

v

Contents

Creating Branches . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Automatic Creation of Connections . . . . . . . . . . . . . . . . . . . 61

Editing Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Annotations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62

Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

Creating a Subsystem by Adding the Subsystem Block . . . . . . . 63

Creating a Subsystem by Grouping Existing Blocks . . . . . . . . . 63

Arranging Subsystem Terminals . . . . . . . . . . . . . . . . . . . . 64

Resizing a Subsystem Block . . . . . . . . . . . . . . . . . . . . . . . 64

Placing the Subsystem Label . . . . . . . . . . . . . . . . . . . . . . 65

Masking Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Mask Icon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66

Mask Dialog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71

Mask Workspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75

Mask Probe Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77

Mask Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 78

Unprotecting Masked Subsystems . . . . . . . . . . . . . . . . . . . 79

Getting Started with Lua . . . . . . . . . . . . . . . . . . . . . . . . 79

Circuit Browser . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 84

Viewing Options . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85

PLECS Probe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 87

Copying a Probe . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88

Assertions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

Assertion Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Component Assertions . . . . . . . . . . . . . . . . . . . . . . . . . . 91

Locating Assertions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 92

Controlling Access to Circuits and Subsystems . . . . . . . . . . . . . . . 93

Encrypting Circuits and Subsystems . . . . . . . . . . . . . . . . . . 93

Exporting Schematics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 94

Using the PLECS Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95

vi

Contents

Legend . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Zoom Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 96

Scrolling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 97

Y-Axis Auto-Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Changing Curve Properties . . . . . . . . . . . . . . . . . . . . . . . 98

Spreading Signals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 98

Cursors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 99

Fourier Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Saving a View . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Adding Traces . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 100

Saving and Loading Trace Data . . . . . . . . . . . . . . . . . . . . 101

Scope Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Printing and Exporting . . . . . . . . . . . . . . . . . . . . . . . . . . 101

Using the Fourier Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . 102

Calculation Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 102

Display Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . 103

Zoom, Export and Print . . . . . . . . . . . . . . . . . . . . . . . . . 104

Calculation of the Fourier coefficients . . . . . . . . . . . . . . . . . 104

Using the XY Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Time Range Window . . . . . . . . . . . . . . . . . . . . . . . . . . . 105

Zoom, Save View, Export and Print . . . . . . . . . . . . . . . . . . 106

Simulation Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 107

PLECS Blockset Parameters . . . . . . . . . . . . . . . . . . . . . . 107

PLECS Standalone Parameters . . . . . . . . . . . . . . . . . . . . . 111

vii

Contents

4 Thermal Modeling 119

Heat Sink Concept . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 119

Implementation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Thermal Loss Dissipation . . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Semiconductor Losses . . . . . . . . . . . . . . . . . . . . . . . . . . 120

Ohmic Losses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Heat Sinks and Subsystems . . . . . . . . . . . . . . . . . . . . . . . . . . 124

Temperature Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

Thermal Description Parameter . . . . . . . . . . . . . . . . . . . . . . . 127

Assigning Thermal Data Sheets . . . . . . . . . . . . . . . . . . . . 127

Using Reference Variables . . . . . . . . . . . . . . . . . . . . . . . . 127

Thermal Library . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Library Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

Global and Local Data Sheets . . . . . . . . . . . . . . . . . . . . . . 130

Creating New Data Sheets . . . . . . . . . . . . . . . . . . . . . . . 131

Browsing the Thermal Library . . . . . . . . . . . . . . . . . . . . . 131

Thermal Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

Editing Switching Losses . . . . . . . . . . . . . . . . . . . . . . . . 133

Editing Conduction Losses . . . . . . . . . . . . . . . . . . . . . . . . 134

Editing the Thermal Equivalent Circuit . . . . . . . . . . . . . . . . 135

Adding Custom Variables . . . . . . . . . . . . . . . . . . . . . . . . 136

Adding Custom Lookup Tables . . . . . . . . . . . . . . . . . . . . . 137

Editing Lookup Tables . . . . . . . . . . . . . . . . . . . . . . . . . . 138

Importing Data from Graphical Datasheets . . . . . . . . . . . . . . 140

Semiconductor Loss Specification . . . . . . . . . . . . . . . . . . . . . . . 145

Single Semiconductor Switch Losses . . . . . . . . . . . . . . . . . . 145

Diode Losses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 145

Losses of Semiconductor Switch with Diode . . . . . . . . . . . . . 146

viii

Contents

5 Magnetic Modeling 149Equivalent circuits for magnetic components . . . . . . . . . . . . . . . . 149

Coupled inductors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

Reluctance-resistance analogy . . . . . . . . . . . . . . . . . . . . . . 150

Permeance-capacitance analogy . . . . . . . . . . . . . . . . . . . . . 152

Magnetic Circuit Domain in PLECS . . . . . . . . . . . . . . . . . . . . . 153

Modeling Non-Linear Magnetic Material . . . . . . . . . . . . . . . 154

Saturation Curves for Soft-Magnetic Material . . . . . . . . . . . . 155

6 Mechanical Modeling 157Flanges and Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

Force/Torque Flows and Sign Conventions . . . . . . . . . . . . . . . . . 158

Positions and Angles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Initial Conditions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

Angle Wrapping . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Ideal Clutches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

Inelastic Collisions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

7 Analysis Tools 165Steady-State Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

Fast Jacobian Calculation for Thermal States . . . . . . . . . . . . 166

Non-periodic Case . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 167

AC Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Impulse Response Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

Compensation for Discrete Pulse . . . . . . . . . . . . . . . . . . . . 169

Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 169

Multitone Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

ix

Contents

Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

Remarks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 171

Usage in PLECS Standalone . . . . . . . . . . . . . . . . . . . . . . . . . 172

Steady-State Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . 172

AC Sweep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

Impulse Response Analysis . . . . . . . . . . . . . . . . . . . . . . . 175

Multitone Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . 175

Extraction of State-Space Matrices . . . . . . . . . . . . . . . . . . . 176

Application Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

Usage in PLECS Blockset . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

Steady-State Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . 180

AC Sweep / Loop Gain Analysis . . . . . . . . . . . . . . . . . . . . . 182

Impulse Response Analysis . . . . . . . . . . . . . . . . . . . . . . . 185

Multitone / Loop Gain Analysis . . . . . . . . . . . . . . . . . . . . . 187

Extraction of State-Space Matrices . . . . . . . . . . . . . . . . . . . 188

Application Example . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

8 C-Scripts 199How C-Scripts Work . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

C-Script Functions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

Modeling Discontinuities . . . . . . . . . . . . . . . . . . . . . . . . . 202

Sample Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

User Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

Runtime Checks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

C-Script Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 208

A Simple Function – Times Two . . . . . . . . . . . . . . . . . . . . 208

Discrete States – Sampled Delay . . . . . . . . . . . . . . . . . . . . 209

Continuous States – Integrator . . . . . . . . . . . . . . . . . . . . . 209

Event Handling – Wrapping Integrator . . . . . . . . . . . . . . . . 210

Piecewise Smooth Functions – Saturation . . . . . . . . . . . . . . . 211

x

Contents

Multiple Sample Times – Turn-on Delay . . . . . . . . . . . . . . . 212

C-Script Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 215

Deprecated Macros . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

9 State Machines 221

Working with State Machines . . . . . . . . . . . . . . . . . . . . . . . . . 222

Working with States . . . . . . . . . . . . . . . . . . . . . . . . . . . 223

Working with Transitions . . . . . . . . . . . . . . . . . . . . . . . . 224

Working with Junctions . . . . . . . . . . . . . . . . . . . . . . . . . 226

Working with Annotations . . . . . . . . . . . . . . . . . . . . . . . . 226

State Machine Configuration . . . . . . . . . . . . . . . . . . . . . . 227

State Machine Execution . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Transition Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . 231

Trigger Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

Trigger Lifetime . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 233

Execution of Hierarchical State Machines . . . . . . . . . . . . . . . 234

State Machine Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Oven Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 235

Constant On-Time Control . . . . . . . . . . . . . . . . . . . . . . . . 237

10 Simulation Scripts 239

Command Line Interface in PLECS Blockset . . . . . . . . . . . . . . . . 239

Simulation Scripts in PLECS Standalone . . . . . . . . . . . . . . . . . . 245

Overview of PLECS Scripting Extensions . . . . . . . . . . . . . . . 246

Example Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

XML-RPC Interface in PLECS Standalone . . . . . . . . . . . . . . . . . 252

Establishing an XML-RPC Connection to PLECS . . . . . . . . . . 252

Overview of XML-RPC Commands . . . . . . . . . . . . . . . . . . . 253

Example Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

Scripted Simulation and Analysis Options . . . . . . . . . . . . . . . . . 256

xi

Contents

11 Code Generation 263

Code Generation for Physical Systems . . . . . . . . . . . . . . . . . . . . 263

Reducing the Code Size . . . . . . . . . . . . . . . . . . . . . . . . . 264

Maximum Number of Switches . . . . . . . . . . . . . . . . . . . . . 264

Handling Naturally Commutated Devices . . . . . . . . . . . . . . . 264

Unsupported Components . . . . . . . . . . . . . . . . . . . . . . . . . . . 267

Code Generation with PLECS Standalone . . . . . . . . . . . . . . . . . 268

Generating Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269

Task Transitions in Multi-Tasking Mode . . . . . . . . . . . . . . . 273

Simulating a Subsystem in CodeGen Mode . . . . . . . . . . . . . . 274

Code Generation with PLECS Blockset . . . . . . . . . . . . . . . . . . . 275

Standalone Code Generation . . . . . . . . . . . . . . . . . . . . . . 275

Integration with Simulink Coder . . . . . . . . . . . . . . . . . . . . 275

Simulink Coder Options . . . . . . . . . . . . . . . . . . . . . . . . . 275

Code Generation Targets . . . . . . . . . . . . . . . . . . . . . . . . . 276

Real-Time Target . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

Rapid Simulation Target . . . . . . . . . . . . . . . . . . . . . . . . . 277

12 Processor-in-the-Loop 281

Motivation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 281

How PIL Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 282

PIL Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284

Configuring PLECS for PIL . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Target Manager . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285

Communication Links . . . . . . . . . . . . . . . . . . . . . . . . . . 286

PIL Block . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 288

xii

Contents

13 Components by Category 293System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 293

Assertions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Control . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 294

Math . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Continuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

Delays . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Discontinuous . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 296

Discrete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 297

Functions & Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Logical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 298

Modulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 299

State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Small Signal Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Electrical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 300

Meters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Passive Components . . . . . . . . . . . . . . . . . . . . . . . . . . . 301

Power Semiconductors . . . . . . . . . . . . . . . . . . . . . . . . . . 302

Power Modules . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 303

Switches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 304

Machines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 305

Converters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Electronics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Model Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Thermal . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 307

Magnetic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 308

xiii

Contents

Mechanical . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Translational . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 309

Rotational . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 310

Additional Simulink Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . 311

14 Component Reference 3131D Look-Up Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 314

2D Look-Up Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 316

2-Pulse Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317

3-Level Half Bridge (ANPC) . . . . . . . . . . . . . . . . . . . . . . . . . . 318

3-Level Half Bridge (T-Type) . . . . . . . . . . . . . . . . . . . . . . . . . 320

5-Level Half Bridge (ANPC) . . . . . . . . . . . . . . . . . . . . . . . . . . 322

3-Phase Current Source Inverter . . . . . . . . . . . . . . . . . . . . . . . 324

3-Phase Voltage Source Inverter . . . . . . . . . . . . . . . . . . . . . . . 326

3D Look-Up Table . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 328

3-Phase Overmodulation . . . . . . . . . . . . . . . . . . . . . . . . . . . . 330

6-Pulse Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 331

Abs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 332

Algebraic Constraint . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 333

Ambient Temperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 334

Air Gap . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 335

Ammeter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 336

Angle Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 337

Assert Dynamic Lower Limit . . . . . . . . . . . . . . . . . . . . . . . . . 338

Assert Dynamic Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 339

Assert Dynamic Upper Limit . . . . . . . . . . . . . . . . . . . . . . . . . 340

Assertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 341

Assert Lower Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 342

Assert Range . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 343

Assert Upper Limit . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 344

Blanking Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 345

xiv

Contents

Blanking Time (3-Level) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 346

Breaker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 347

Brushless DC Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 348

Brushless DC Machine (Simple) . . . . . . . . . . . . . . . . . . . . . . . 351

C-Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 355

Capacitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 358

Clock . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 360

Combinatorial Logic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 361

Comparator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 362

Compare to Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 363

Configurable Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . 364

Constant . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 366

Constant Heat Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 367

Constant Temperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 368

Continuous PID Controller . . . . . . . . . . . . . . . . . . . . . . . . . . 369

Controlled Heat Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 375

Controlled Temperature . . . . . . . . . . . . . . . . . . . . . . . . . . . . 376

Current Source (Controlled) . . . . . . . . . . . . . . . . . . . . . . . . . . 377

Current Source AC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 378

Current Source DC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 379

D Flip-flop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 380

Dual Active Bridge Converter . . . . . . . . . . . . . . . . . . . . . . . . . 381

Data Type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 383

DC Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 384

Dead Zone . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386

Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387

Diode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 388

Diode with Reverse Recovery . . . . . . . . . . . . . . . . . . . . . . . . . 390

Diode Rectifier (3ph) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 393

Discrete Fourier Transform . . . . . . . . . . . . . . . . . . . . . . . . . . 394

Discrete Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395

xv

Contents

Discrete Mean Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399

Discrete PID Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . 400

Discrete RMS Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 404

Discrete State Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 405

Discrete Total Harmonic Distortion . . . . . . . . . . . . . . . . . . . . . 406

Discrete Transfer Function . . . . . . . . . . . . . . . . . . . . . . . . . . 407

Display . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409

DLL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410

Double Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 414

Dynamic Signal Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . 415

Edge Detection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 416

Electrical Algebraic Component . . . . . . . . . . . . . . . . . . . . . . . . 417

Electrical Ground . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419

Electrical Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 420

Electrical Model Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 421

Electrical Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 422

Enable . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 424

Flux Rate Meter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 425

Flying Capacitor Half Bridge . . . . . . . . . . . . . . . . . . . . . . . . . 426

Force (Constant) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 428

Force (Controlled) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 429

Force Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 430

Fourier Series . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 431

Fourier Transform . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 432

From File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 433

Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 435

FMU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 436

Full-Bridge LLC Resonant Converter . . . . . . . . . . . . . . . . . . . . 437

Gain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440

Gear . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441

GTO . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442

xvi

Contents

GTO (Reverse Conducting) . . . . . . . . . . . . . . . . . . . . . . . . . . 444

Half-Bridge LLC Resonant Converter . . . . . . . . . . . . . . . . . . . . 446

Heat Flow Meter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 449

Heat Sink . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 450

Hit Crossing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 451

Hysteretic Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 452

Ideal 3-Level Converter (3ph) . . . . . . . . . . . . . . . . . . . . . . . . . 454

Ideal Converter (3ph) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 455

Ideal Transformer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 456

IGBT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 458

IGBT 3-Level Converter (3ph) . . . . . . . . . . . . . . . . . . . . . . . . . 460

IGBT 3-Level Half Bridge (NPC) . . . . . . . . . . . . . . . . . . . . . . . 462

IGBT Chopper (High-Side Switch) . . . . . . . . . . . . . . . . . . . . . . 464

IGBT Chopper (High-Side Switch with Reverse Diode) . . . . . . . . . . 465

IGBT Chopper (Low-Side Switch) . . . . . . . . . . . . . . . . . . . . . . 467

IGBT Chopper (Low-Side Switch with Reverse Diode) . . . . . . . . . . 468

IGBT Converter (3ph) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 470

IGBT Full Bridges (Series Connected) . . . . . . . . . . . . . . . . . . . . 472

IGBT Half Bridge . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 474

IGBT Half Bridges (Low-/High-Side Connected) . . . . . . . . . . . . . . 476

IGBT with Diode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 478

IGBT with Limited di/dt . . . . . . . . . . . . . . . . . . . . . . . . . . . . 480

IGCT (Reverse Blocking) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 484

IGCT (Reverse Conducting) . . . . . . . . . . . . . . . . . . . . . . . . . . 486

Induction Machine (Slip Ring) . . . . . . . . . . . . . . . . . . . . . . . . 488

Induction Machine (Open Stator Windings) . . . . . . . . . . . . . . . . . 492

Induction Machine (Squirrel Cage) . . . . . . . . . . . . . . . . . . . . . . 495

Induction Machine with Saturation . . . . . . . . . . . . . . . . . . . . . 498

Inductor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 504

Inertia . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 506

Initial Condition . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 507

xvii

Contents

Integrator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 508

JK Flip-flop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 510

Leakage Flux Path . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 512

Linear Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 513

Linear Transformer (2 Windings) . . . . . . . . . . . . . . . . . . . . . . . 514

Linear Transformer (3 Windings) . . . . . . . . . . . . . . . . . . . . . . . 516

Logical Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 518

Magnetic Permeance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 519

Magnetic Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 520

Magnetic Resistance . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 522

Manual Double Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 523

Manual Signal Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 524

Manual Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525

Manual Triple Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526

Mass . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 527

Math Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528

Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 529

Meter (3-Phase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530

Minimum / Maximum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531

MMF Meter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 532

MMF Source (Constant) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 533

MMF Source (Controlled) . . . . . . . . . . . . . . . . . . . . . . . . . . . 534

Model Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 535

Monoflop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 536

MOSFET . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538

MOSFET Converter (3ph) . . . . . . . . . . . . . . . . . . . . . . . . . . . 540

MOSFET with Diode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 541

MOSFET with Limited di/dt . . . . . . . . . . . . . . . . . . . . . . . . . . 543

Moving Average . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 545

Multiport Signal Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546

Mutual Inductor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 547

xviii

Contents

Mutual Inductance (2 Windings) . . . . . . . . . . . . . . . . . . . . . . . 549

Mutual Inductance (3 Windings) . . . . . . . . . . . . . . . . . . . . . . . 551

Non-Excited Synchronous Machine . . . . . . . . . . . . . . . . . . . . . . 553

Offset . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 557

Op-Amp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 558

Op-Amp with Limited Output . . . . . . . . . . . . . . . . . . . . . . . . . 559

Pause / Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560

Peak Current Controller . . . . . . . . . . . . . . . . . . . . . . . . . . . . 561

Periodic Average . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 562

Periodic Impulse Average . . . . . . . . . . . . . . . . . . . . . . . . . . . 563

Permanent Magnet Synchronous Machine . . . . . . . . . . . . . . . . . 564

Phase-Shifted Full-Bridge Converter . . . . . . . . . . . . . . . . . . . . . 568

Pi-Section Line . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 571

Piece-wise Linear Resistor . . . . . . . . . . . . . . . . . . . . . . . . . . . 573

Planetary Gear Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 575

Polar to Rectangular . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 577

PLL (Single-Phase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 578

PLL (Three-Phase) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 583

Position Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 587

Product . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 588

Pulse Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 589

Pulse Generator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 590

Quantizer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 591

Rack and Pinion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 592

Ramp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 593

Random Numbers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 594

Rate Limiter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 595

Rectangular to Polar . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 596

Relational Operator . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 597

Relay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 598

Resistor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 599

xix

Contents

RMS Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 600

Rotational Algebraic Component . . . . . . . . . . . . . . . . . . . . . . . 601

Rotational Backlash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 603

Rotational Clutch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 604

Rotational Damper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 605

Rotational Friction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 606

Rotational Hard Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 608

Rotational Model Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . 610

Rotational Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 611

Rotational Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 612

Rotational Speed (Constant) . . . . . . . . . . . . . . . . . . . . . . . . . . 613

Rotational Speed (Controlled) . . . . . . . . . . . . . . . . . . . . . . . . . 614

Rotational Speed Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 615

Rounding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616

Saturable Capacitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617

Saturable Core . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619

Saturable Inductor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622

Saturable Transformers . . . . . . . . . . . . . . . . . . . . . . . . . . . . 624

Saturation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 626

Sawtooth PWM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 627

Sawtooth PWM (3-Level) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 629

Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 631

Set/Reset Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633

Signal Demultiplexer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 635

Signal From . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 636

Signal Goto . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 637

Signal Inport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 638

Signal Multiplexer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 640

Signal Outport . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 641

Signal Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 643

Signal Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644

xx

Contents

Signum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645

Sine Wave . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646

Small Signal Gain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647

Small Signal Perturbation . . . . . . . . . . . . . . . . . . . . . . . . . . . 648

Small Signal Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649

Space Vector PWM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650

Space Vector PWM (3-Level) . . . . . . . . . . . . . . . . . . . . . . . . . 654

SR Flip-flop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 658

State Machine . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 659

State Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 660

Step . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661

Subsystem . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 662

Sum . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 665

Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 666

Switched Reluctance Machine . . . . . . . . . . . . . . . . . . . . . . . . . 667

Symmetrical PWM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 671

Symmetrical PWM (3-Level) . . . . . . . . . . . . . . . . . . . . . . . . . . 673

Synchronous Machine (Round Rotor) . . . . . . . . . . . . . . . . . . . . . 675

Synchronous Machine (Salient Pole) . . . . . . . . . . . . . . . . . . . . . 680

Synchronous Reluctance Machine . . . . . . . . . . . . . . . . . . . . . . 686

Task Frame . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 690

Thermal Capacitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 691

Thermal Chain . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 692

Thermal Ground . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 693

Thermal Model Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . 694

Thermal Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 695

Thermal Resistor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 697

Thermometer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 698

Thyristor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 699

Thyristor Rectifier/Inverter . . . . . . . . . . . . . . . . . . . . . . . . . . 701

Thyristor with Reverse Recovery . . . . . . . . . . . . . . . . . . . . . . . 702

xxi

Contents

To File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 704

Torque (Constant) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 706

Torque (Controlled) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707

Torque Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708

Torsion Spring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 709

Total Harmonic Distortion . . . . . . . . . . . . . . . . . . . . . . . . . . . 710

Transfer Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711

Transformation 3ph->RRF . . . . . . . . . . . . . . . . . . . . . . . . . . . 713

Transformation 3ph->SRF . . . . . . . . . . . . . . . . . . . . . . . . . . . 714

Transformation RRF->3ph . . . . . . . . . . . . . . . . . . . . . . . . . . . 715

Transformation RRF->SRF . . . . . . . . . . . . . . . . . . . . . . . . . . 716

Transformation SRF->3ph . . . . . . . . . . . . . . . . . . . . . . . . . . . 717

Transformation SRF->RRF . . . . . . . . . . . . . . . . . . . . . . . . . . 718

Transformers (3ph, 2 Windings) . . . . . . . . . . . . . . . . . . . . . . . 719

Transformers (3ph, 3 Windings) . . . . . . . . . . . . . . . . . . . . . . . 722

Translational Algebraic Component . . . . . . . . . . . . . . . . . . . . . 725

Translational Backlash . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 727

Translational Clutch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 728

Translational Damper . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729

Translational Friction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 730

Translational Hard Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . 732

Translational Model Settings . . . . . . . . . . . . . . . . . . . . . . . . . 734

Translational Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735

Translational Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 736

Translational Speed (Constant) . . . . . . . . . . . . . . . . . . . . . . . . 737

Translational Speed (Controlled) . . . . . . . . . . . . . . . . . . . . . . . 738

Translational Speed Sensor . . . . . . . . . . . . . . . . . . . . . . . . . . 739

Translational Spring . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 740

Transmission Line (3ph) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 741

Transport Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 748

TRIAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749

xxii

Contents

Triangular Wave Generator . . . . . . . . . . . . . . . . . . . . . . . . . . 751

Trigonometric Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752

Triple Switch . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 753

Trigger . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754

Turn-on Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756

Variable Capacitor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 757

Variable Inductor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 760

Variable Magnetic Permeance . . . . . . . . . . . . . . . . . . . . . . . . . 764

Variable Resistor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 766

Variable Resistor with Constant Capacitor . . . . . . . . . . . . . . . . . 767

Variable Resistor with Constant Inductor . . . . . . . . . . . . . . . . . . 768

Variable Resistor with Variable Capacitor . . . . . . . . . . . . . . . . . . 769

Variable Resistor with Variable Inductor . . . . . . . . . . . . . . . . . . 771

Voltage Source (Controlled) . . . . . . . . . . . . . . . . . . . . . . . . . . 773

Voltage Source AC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774

Voltage Source AC (3-Phase) . . . . . . . . . . . . . . . . . . . . . . . . . 775

Voltage Source DC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776

Voltmeter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 777

White Noise . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 778

Winding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 780

Wire Multiplexer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 782

Wire Selector . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 783

XY Plot . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 784

Zener Diode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 786

Zero Order Hold . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 787

xxiii

Contents

15 Additional Simulink Blocks 789AC Sweep . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 790

Discrete Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 793

Impulse Response Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . 794

Loop Gain Analysis (AC Sweep) . . . . . . . . . . . . . . . . . . . . . . . 796

Loop Gain Analysis (Multitone) . . . . . . . . . . . . . . . . . . . . . . . . 797

Modulators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 798

Multitone Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 799

Steady-State Analysis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 801

Timer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 803

Transformations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 804

xxiv

Before You Begin

Installing PLECS Blockset

Installing PLECS Blockset on your computer is easy. You do not need to havesystem administrator permissions. Since PLECS Blockset requires MATLABand Simulink make sure these programs are installed on your computer.

Installation on Microsoft Windows

1 If you already have a license file *.lic, copy it to your harddisk.

2 Run the installer executable by double-clicking it. PLECS can be installedfor the current user or all users of a machine. To install PLECS for allusers the installer must be executed with administrator privileges.

3 After the installer has finished, it will automatically start the PLECSBlockset Installation Wizard.

4 On the License File page you can choose to keep an existing license file,copy a new license file from your harddisk or request a trial or student li-cense.

5 Review the MATLAB Search Path page and click Continue.

6 Start MATLAB and enter plecslib or choose the entry PLECS in theSimulink Library Browser to open the PLECS Library.

Installation on macOS


Before You Begin

2 Open the diskimage by double-clicking it and copy the folderPLECS Blockset x.y to a location of your choice.

3 Run the application PLECS.app inside the folder PLECS Blockset x.y bydouble-clicking it. This will start the PLECS Blockset Installation Wiz-ard.




Installation on Linux


2 Open a terminal and extract the packageplecs-blockset-x-y-z_linux64.tar.gz by entering the command

tar xf plecs-blockset-x-y-z_linux64.tar.gz

in a directory of your choice.

3 Still within the terminal execute the program PLECS.setup inside the folderplecs/bin/glnxa64. This will start the PLECS Blockset InstallationWizard.




Licensing

If PLECS cannot locate any license file when you start it, it will show a mes-sage that it is unlicensed.

2

Installing PLECS Blockset

Choose Start in demo mode to use PLECS in a restricted demo mode thatlets you build models and run simulations. Saving Simulink models contain-ing PLECS blocks is disabled in this mode.

Choose Open license manager... to open the License Manager, which letsyou install a license file or request a time-limited trial or student license.

If PLECS does locate license files but they do not contain a valid license (e.g.because it has expired) it will immediately open the License Manager withoutthe option to start the demo mode.

Without a valid license you will still be able to open or save Simulink modelscontaining PLECS blocks. However, you cannot modify a circuit schematic orrun a simulation.

Note PLECS scans the license file only once when the module is loadedby MATLAB. Therefore, if you reinstall the license file, you need to clear thePLECS module before the changes can become effective. You can do this by en-tering plecsclear at the MATLAB command prompt.

Configuring the MATLAB Search Path

The recommended method to register PLECS Blockset with MATLAB isto add appropriate addpath commands to the startup file startup.m inyour MATLAB startup folder. For information on the startup.m file, enterdoc startup in MATLAB. The PLECS Blockset Installation Wizard willassist you in creating or updating this file.

Using this method has the advantage that if you update MATLAB after hav-ing installed PLECS, the new MATLAB version will automatically know aboutPLECS. The disadvantage is that each user must setup their startup file indi-vidually.

As an alternative method you can register PLECS with a specific MATLABinstallation using the MATLAB Path Browser or by directly editing the filepathdef.m in the directory matlabroot/toolbox/local/. This method may beappropriate if PLECS will be used by multiple users sharing the same com-puter. You need to add the PLECS directory and its subdirectory demos to theMATLAB search path.

3

Before You Begin

Configuring PLECS

For information about setting global configuration options for PLECS see“Configuring PLECS” (on page 45).

Installing Different Versions of PLECS Blockset in Paral-lel

If you want to keep different versions of PLECS installed in parallel on onecomputer, you must ensure that only one version is on your MATLAB path atany time during a MATLAB session. Otherwise, loss of data may occur. Be-fore changing the MATLAB path, be sure to clear the currently loaded PLECSmodule by entering plecsclear at the MATLAB command prompt. As an ad-ditional precaution you should restart MATLAB after the change.

Uninstalling PLECS Blockset

Uninstalling PLECS Blockset is as easy as installing it.

1 Locate the directory where PLECS is installed by entering

which plecs

in the MATLAB command line.

2 Remove the PLECS directory and its subdirectory demos from the searchpath. Depending on how the directories were added to the path duringinstallation, this is done using the Path Browser or by editing the filepathdef.m in the directory matlabroot/toolbox/local/ or your MATLABstartup file startup.m.

3 Quit MATLAB.

4 On Windows, deinstall PLECS Blockset by choosing the appropriate entryin the Windows control panel. On macOS and Linux just delete the PLECSdirectory.

4

Installing PLECS Standalone

Installing PLECS Standalone

Installing PLECS on your system is easy. You do not need to have system ad-ministrator permissions.

Installation on Microsoft Windows


2 Run the installer executable by double-clicking it. PLECS can be installedfor the current user or all users of a machine. To install PLECS for allusers the installer must be executed with administrator privileges.

3 Start PLECS.

Installation on macOS


2 Open the disk image by double-clicking it.

3 Copy PLECS to the Application folder.

4 Start PLECS.

Installation on Linux


2 Open a terminal and extract the packageplecs-standalone-x-y-z_linux64.tar.gz by entering the command

tar xf plecs-standalone-x-y-z_linux64.tar.gz

in a directory of your choice. This will create a new sub-directory namedplecs containing the required files.

3 Start PLECS by executing PLECS in the folder plecs.

5

Before You Begin

Licensing

If PLECS cannot locate any license file when you start it, it will show a mes-sage that it is unlicensed.

Choose Start in demo mode to use PLECS in a restricted demo mode thatlets you build models and run simulations. Saving models or data is disabledin this mode.

Choose Open license manager... to open the License Manager, which letsyou install a license file or request a time-limited trial or student license.

If PLECS does locate license files but they do not contain a valid license (e.g.because it has expired) it will immediately open the License Manager withoutthe option to start the demo mode.

License File Location

Both PLECS Standalone and PLECS Blockset search for license files named*.lic in the following directories:

License File Search Paths

Platform Search Paths

Windows C:\Users\<USER>\AppData\Local\Plexim\PLECS\licensesC:\ProgramData\Plexim\PLECS\licenses

macOS ~/Library/Application Support/Plexim/PLECS/licenses/Library/Application Support/Plexim/PLECS/licenses

Linux ~/.local/share/Plexim/PLECS/licenses/usr/local/share/Plexim/PLECS/licenses

The License Manager will install license files in the first directory listed foreach platform because this location is usually writable by the user. However,an administrator may choose to install license files to be used for all users inthe other directory.

If none of the search directories contains any license file *.lic, PLECS usesthe environment variables PLEXIM_LICENSE_FILE and LM_LICENSE_FILE to lo-cate the license file.

6

Network Licensing

Network Licensing

If you purchase one or more floating licenses for PLECS, the license serverprogram FlexNet Publisher is employed to control access to PLECS. FlexNetPublisher is a product of Flexera Software. The license file sent to you mustbe installed on the license server. This file contains information that identifiesthe computer running the license manager and specifies the number of float-ing licenses you have purchased.

On the client computer(s), you need to use a text editor to create a license filenetwork.lic with the following content:

SERVER licenseserver ANYUSE_SERVER

where licenseserver is the IP address or the hostname or fully qualified do-main name (FQDN) of the server computer running the license manager. Ifthe hostname or FQDN is used, verify that the client computer can resolve itto the correct IP address. If the license manager uses a TCP port other than27000-27009, the port number must be specified on the SERVER line after thekeyword ANY, e.g.:

SERVER licenseserver ANY 3456USE_SERVER

PLECS tries to obtain a license from the server the first time you load amodel or library containing a PLECS circuit. If the license is not granted –e.g. because the server is down or unreachable or because the licensed numberof concurrent users is already reached – PLECS will open the License Man-ager to report the problem. In order to retry to obtain a license you need torestart PLECS Standalone or clear PLECS Blockset from the MATLAB mem-ory using the MATLAB command plecsclear. Once granted, a license is re-turned to the server when quit PLECS Standalone or clear PLECS Blocksetfrom the MATLAB memory.

If the connection to the license server is lost after you have obtained a license,PLECS will temporarily switch to the unlicensed mode. Upon successful recon-nection to the server, PLECS will switch back to normal operation.

7

Before You Begin

What’s New in Version 4.5

Major New Features

• The new FMU block (see page 436) enables you to include Model-ExchangeFunctional Mockup Units created by other simulation tools in your PLECSmodels.

PLECS Standalone Only

• PLECS has a new default variable-step solver auto that automaticallyswitches from the non-stiff DOPRI solver to the stiff RADAU solver if amodel is found to become stiff during a simulation. See “PLECS StandaloneParameters” on page 111.

• The new Model Reference block (see page 535) allows you to reuse a subsys-tem from one model in another model via a link so that the referencing sub-system is updated automatically when the original subsystem is changed.

• The new solver option OutputTimes enables you to specify the time valuesfor which you wish to retrieve output signal values when running a simu-lation from an Octave script or via the XML-RPC interface. See “ScriptedSimulation and Analysis Options” (on page 256).

PLECS Blockset Only

• PLECS Blockset now has a Demo Mode analogous to the Demo Mode ofPLECS Standalone. The Demo Mode allows you to use PLECS without alicense. You can freely edit models and run simulations, but saving modelsis disabled.

• PLECS now supports the “Fast Restart” feature of Simulink.

New and Enhanced Library Components

• There are two new Phase Locked Loop implementations: PLL (Single-Phase) (see page 578) and PLL (Three-Phase) (see page 583).

• The new Multiport Signal Switch (see page 546) allows you to switch be-tween multiple signals depending on a control signal.

• The new Dynamic Signal Selector (see page 415) allows you to select or re-order elements of a vector signal depending on a control signal.

8

What’s New in Version 4.5

• The Integrator (see page 508) has been enhanced with an option to wrapthe integrator state between given limits.

• The Transport Delay (see page 748) has been enhanced with an option tospecify the delay time with a control signal instead of a parameter.

Further Enhancements

• You can now configure PLECS to show link indicators on components thatlink back into a library. See “Libraries” on page 46.

• The Generic PLECS Coder target has been enhanced with an option to cre-ate separate output and update functions instead of a single step function.See “Target” on page 272.

9

Before You Begin

10

1

Getting Started

Let us have a quick tour and see how PLECS is used. Our aim is to show theessential elements of PLECS in real applications without regarding all the de-tails, rules, and exceptions. At this stage, we are not trying to be complete. Wewant to get you as soon as possible to the point where you can set up usefulapplications. Many of the details are not necessary at the beginning and canbe studied later.

The following section addresses users of PLECS Blockset for Simulink. If youare using the stand-alone version of PLECS please continue with section “Get-ting Started with PLECS Standalone” (on page 20).

Getting Started with PLECS Blockset

To access PLECS you simply need to enter plecslib in the MATLAB com-mand line. This will bring up a Simulink model that contains a genericPLECS block named “Circuit” and various component libraries. In the li-braries you find electrical components, from which you can create your cir-cuits. Alternatively, you may access the PLECS toolbox by opening it in theSimulink library browser.

A Simple Passive Network

The only way to become familiar with a new program is by using it. For thisreason we are presenting here two example circuits that you can reconstructon your computer. The examples are based on each other, since the features ofPLECS will be explained step by step.

1 Getting Started

The first electrical system we are going to model is a simple RLC network asshown in Fig. 1.1. A capacitor is charged by a DC voltage source via an RL-branch and its voltage is monitored with a voltmeter.

10mH

10V vC100 µF

10Ω

Figure 1.1: Simple RLC network

In order to enter the circuit in PLECS we have to open a new Simulink model.Into the model window we copy the block “Circuit” from the PLECS library bydragging it with the mouse. Our Simulink model should now look like Fig. 1.2.

Figure 1.2: Simulink model

Components

A double-click on the PLECS block will open an empty schematic window witha menu bar quite similar to the one of a Simulink window. The componentsrequired for our circuit must be copied into this window from the componentslibraries. Like in Simulink, this is done by dragging them with the mouse.If you want to copy components already placed in the window hold down theCtrl key (cmd key on macOS) while dragging the mouse. The componentsthat you need for the RLC network can be found in in the library “Electrical”in the sub-libraries “Sources”, “Meters” and “Passive Components”.

12


After you have copied all components the schematic window should look likeFig. 1.3. If not, move the components with the left mouse button. To rotateselected components press Ctrl-R, to flip them horizontally press Ctrl-F. Allthese functions can also be accessed via the menu bar.

Figure 1.3: PLECS schematic

Note You cannot place Simulink objects in a PLECS schematic and vice versasince both programs do not share the same Graphical User Interface.

Connections

The unconnected electrical terminals of a component are marked with lit-tle hollow circles. If we bring the mouse pointer close to such a terminal thepointer shape changes from an arrow to a cross. We now can drag a connec-tion to another component by holding the left mouse button down. Whenwe approach another terminal or an existing connection the pointer shapechanges into a double cross. As soon as we release the mouse button an elec-trical connection will be created.

For drawing a branch connection place the mouse pointer on an existing con-nection where you want the branch to start. With the right mouse button orwith the left mouse button while holding down the Ctrl key you can create aconnection from there to the desired destination.

13

1 Getting Started

Component Properties

Each component is identified by a unique name, which is chosen automati-cally. You may change it as you wish by double-clicking on it in the schematic.The name is intended only for documentation purposes and does not affect thesimulation. Of greater importance are the parameters that determine, for ex-ample, the inductance of an inductor, the capacity of an capacitor, or the volt-age of a DC voltage source. A double-click on the component icon opens a di-alog box in which you can set these parameters. Fig. 1.4 shows the dialog boxfor an inductor.

Figure 1.4: Inductor dialog box

If you want selected parameters to be displayed in the schematic, you mustcheck the check box on the right side of the edit field. For reasons of claritywe prefer to display only the most important parameters of a component.

Units

Like Simulink PLECS does not know anything about units. It is your respon-sibility that variables are scaled correctly. For power electronics we recom-mend the use of SI quantities. However, if you want to employ PLECS for thesimulation of power systems it may be more appropriate to work with “perunit” quantities.

For every component enter the values according to the schematic in Fig. 1.1.In the dialog boxes of the inductor and the capacitor you can additionally setthe initial current resp. the initial voltage. Please leave both values at zero.

14


Signals

Up to now our electrical circuit lacks a connection with the Simulink envi-ronment. You will notice this from the fact that the PLECS block in Simulinkdoes not have inputs or outputs. In order to add inputs and outputs we mustcopy the respective port blocks from the library “System” into the schematic.In our case we want to access in Simulink the voltage measured by the volt-meter. Therefore, we need the “Signal Outport” block that exports a signalinto the parent system.

Signals in PLECS correspond to the connections between Simulink blocks.They provide unidirectional information interchange between components andwith Simulink.

Connect the output of the voltmeter with the input of the port block. InSimulink, connect a Scope to the output of the PLECS block and start thesimulation. In order to see something of the more interesting part of the sim-ulation you probably need to set the stop time to 0.1. By this time you shouldhave something like Fig. 1.5 and Fig. 1.6 on your screen.

Figure 1.5: Complete model

Adding More Measurements

If you want to measure other quantities in the circuit, simply add the requiredvoltmeters and ammeters. The measured signals can be exported to Simulinkwith additional port blocks. Alternatively you can bundle the measured sig-nals into a vector by using the multiplexer for signals “Signal Multiplexer”from the library “System”.

15

1 Getting Started

Figure 1.6: Simulation result

You can also add scopes in the PLECS schematic directly. The “Scope" blockcan be found in the library “System".

Importing Signals

You have already learned how to export signals from the electrical circuit toSimulink via the output block. In the same manner you can also import sig-nals from Simulink into your circuit, usually to control sources.

Let us see how the capacitor in our example charges and discharges if we ap-ply a pulsed voltage. In the schematic we replace the DC voltage source by acontrolled one. Copy the input block “Signal Inport” into the schematic andconnect it to the voltage source. The PLECS block in Simulink now also hasan input terminal. Any Simulink signal that you connect to this terminalwill be translated into a voltage in the electrical circuit. In Fig. 1.7 we useda pulse generator with a period of 0.04 sec and an amplitude of 10.

The signal generated by the pulse generator is discrete, i.e. its value changesabruptly. Normally, the PLECS Scope would determine the signal type auto-matically and display vertical slopes. In this case, however, the discrete signalcoming from the pulse generator is multiplexed with a continuous signal be-fore reaching the Scope. In order to avoid trapezoidal curves, the signal typemust be set manually to “discrete” in the Data window of the Scope (see Fig.1.8).

16


Figure 1.7: RLC network with a pulsed voltage source

Figure 1.8: Data window of the PLECS Scope

Buck Converter

In the next example we will introduce the concept of ideal switches, whichdistinguishes PLECS from other simulation programs. It will be shown howswitches are controlled, i.e. either by voltages and currents in the system orby external signals.

25mH

vsrc 2Ω220µF vC

isrc

Figure 1.9: Schematic of buck converter

17

1 Getting Started

Switches

In the buck converter outlined in Fig. 1.9 we will model the transistor as anentirely controllable switch and bear in mind that it may conduct current onlyin one direction. We also need a free-wheeling diode. The diode is a switchthat closes as the voltage across it becomes positive, and opens as the currentthrough it becomes negative.

The diode can be found in the library “Electrical / Power Semiconductors” andthe switch in the library “Electrical / Switches”. All components in these li-braries are based on ideal switches that have zero on-resistance and infiniteoff-resistance. They open and close instantaneously. In some components likethe diode you may add a forward voltage or a non-zero on-resistance. If youare unsure about these values leave them at zero.

In order to control the switch in our buck converter we import another signalfrom Simulink and connect it to the switch. The switch will close upon a non-zero signal and open when the signal goes back to zero.

Figure 1.10: Electrical part of buck converter

By now you should be able to model the electrical part of the buck converteras shown in Fig. 1.10. For the buck converter we will implement a hysteresistype control that keeps the capacitor voltage roughly in a ±0.2 V band around6 V. To make things a bit more interesting we apply a step change from 12 Vdown to 8 V to the input voltage during the simulation.

18


Figure 1.11: Simulation of buck converter with hysteresis control

19

1 Getting Started

Getting Started with PLECS Standalone

The only way to become familiar with a new program is by using it. For thisreason we are presenting here two example circuits that you can reconstructon your computer. The examples are based on each other, since the features ofPLECS will be explained step by step.

After starting PLECS the PLECS Library browser is displayed. In the li-braries you find various components from which you can create your circuits.You can browse through the available libraries and see which components areavailable.

A Simple Passive Network

The first electrical system we are going to model is a simple RLC network asshown in Fig. 1.12. A capacitor is charged by a DC voltage source via an RL-branch and its voltage is monitored with a voltmeter.

10mH

10V vC100 µF

10Ω

Figure 1.12: Simple RLC network

In order to enter the circuit in PLECS we have to open a new PLECS model.This is done by selecting “New Model” from the “File” Menu in the LibraryBrowser.

Components

The components required for our circuit must be copied into this window fromthe Library Browser. This is done by dragging them with the mouse. If youwant to copy components already placed in the window hold down the Ctrlkey (cmd key on macOS) while dragging them.

The electrical components that you need for the RLC network can be found inin the library “Electrical” in the sub-libraries “Sources”, “Meters” and “Pas-sive Components”. The scope is located in the library “System”. Instead of

20


browsing for the components you can also search for them by entering the firstletters of the component you need in the search bar. For example, typing scshows you the scope, res all available resistors etc.

After you have copied all components the schematic window should look likeFig. 1.13. If not, move the components with the left mouse button. To rotateselected components press Ctrl-R, to flip them horizontally press Ctrl-F. Allthese functions can also be accessed via the menu bar.

Figure 1.13: PLECS schematic

Connections

The unconnected electrical terminals of a component are marked with lit-tle hollow circles. If we bring the mouse pointer close to such a terminal thepointer shape changes from an arrow to a cross. We now can drag a connec-tion to another component by holding the left mouse button down. Whenwe approach another terminal or an existing connection the pointer shapechanges into a double cross. As soon as we release the mouse button an elec-trical connection will be created.

For drawing a branch connection place the mouse pointer on an existing con-nection where you want the branch to start. With the right mouse button orwith the left mouse button while holding down the Ctrl key you can create aconnection from there to the desired destination.

Component Properties

Each component is identified by a unique name, which is chosen automati-cally. You may change it as you wish by double-clicking on it in the schematic.The name is intended only for documentation purposes and does not affect the

21

1 Getting Started

simulation. Of greater importance are the parameters that determine, for ex-ample, the inductance of an inductor, the capacity of an capacitor, or the volt-age of a DC voltage source. A double-click on the component icon opens a dia-log box in which you can set these parameters. Fig. 1.14 shows the dialog boxfor an inductor.

Figure 1.14: Inductor dialog box

If you want selected parameters to be displayed in the schematic, you mustcheck the check box on the right side of the edit field. For reasons of claritywe prefer to display only the most important parameters of a component.

Units

PLECS does not know anything about units. It is your responsibility thatvariables are scaled correctly. For power electronics we recommend the useof SI quantities. However, if you want to employ PLECS for the simulation ofpower systems it may be more appropriate to work with “per unit” quantities.

For every component enter the values according to the schematic in Fig. 1.12.In the dialog boxes of the inductor and the capacitor you can additionally setthe initial current resp. the initial voltage. Please leave both values at zero.

Signals

In addition to the electrical connections (wires) that are used to connect elec-trical components PLECS also makes use of unidirectional signals. The sig-nals are painted in green and have an arrowhead to indicate their direction.

22


In the RLC example a signal connects the output terminal of the voltmeter tothe input terminal of the scope.

PLECS uses signals to carry non-electrical information like measurement val-ues or triggering pulses for switches. Signals can be used in calculations anddisplayed in a scope. Electrical connections cannot be fed into a scope directly,you always have to use a volt- or ammeter to convert the electrical quantitiesinto a signal first.

By this time your model should look similar to Fig. 1.15. To start the simu-lation, press Ctrl-T or select “Start” from the “Simulation” menu. In orderto see something of the more interesting part of the simulation you need toset the time span to 0.1. To do this, open the Simulation Parameters dialogby clicking the corresponding menu entry in the “Simulation” menu or pressCtrl-E.

You should now get the simulation results shown in below.

Figure 1.15: Complete model and simulation result

Adding Control Blocks

To enhance our model we would like to add some dynamic behavior into ourstatic electrical model. Let us see how the capacitor in our example chargesand discharges if we apply a pulsed voltage. In the schematic we replace theDC voltage source by a controlled one. The input of the voltage source can beany signal generated from one of the control blocks in PLECS. In Fig. 1.16 weused a pulse generator with a period of 0.04 sec and an amplitude of 10 to con-trol the voltage source.

23

1 Getting Started

Figure 1.16: RLC network with a pulsed voltage source

Buck Converter

In the next example we will introduce the concept of ideal switches, whichdistinguishes PLECS from other simulation programs. It will be shown howswitches are controlled, i.e. either by voltages and currents in the system orby external signals.

25mH

vsrc 2Ω220µF vC

isrc

Figure 1.17: Schematic of buck converter

Switches

In the buck converter outlined in Fig. 1.17 we will model the transistor as anentirely controllable switch and bear in mind that it may conduct current onlyin one direction. We also need a free-wheeling diode. The diode is a switchthat closes as the voltage across it becomes positive, and opens as the currentthrough it becomes negative.

The diode can be found in the library “Electrical / Power Semiconductors” andthe switch in the library “Electrical / Switches”. All components in these li-

24


braries are based on ideal switches that have zero on-resistance and infiniteoff-resistance. They open and close instantaneously. In some components likethe diode you may add a forward voltage or a non-zero on-resistance. If youare unsure about these values leave them at zero.

The switch is controlled by an external signal. It will close upon a non-zeroinput and open when the signal goes back to zero.

We start with the electrical part of the buck converter first. By now youshould be able to model it as shown in Fig. 1.18.

Figure 1.18: Electrical part of buck converter

Subsystems

We’d also like to separate the electrical part from the control part. This has noeffect on the simulation result but makes the whole system more structured.Once you have completed the circuit from Fig. 1.18, select all components (ei-ther by clicking on an empty space in the upper left corner of the schematicand dragging a frame to the lower right corner, or by pressing Ctrl-A). Nowcreate a new subsystem by selecting “Create Subsystem” from the “Edit” menuor by pressing Ctrl-G. The electrical components are now in a new subsys-tem “Sub”. You can rename it to something more meaningful, e.g. “Circuit”and change the icon size by dragging one of the selected corners. You can alsomove the name label to another position by clicking and dragging it to the bor-ders or the corners of the icon. Now your system should look similar to Fig.1.19.

To connect the subsystem to the outer schematic we need to place ports intoit. Drag two Signal Inports and two Signal Outports into the subsystemschematic and connect them to the voltage source, the switch, the volt- and

25

1 Getting Started

Figure 1.19: Electrical Subsystem

the ammeter respectively. Note that a new terminal appears in the subsystemicon for each port that you drag into the subsystem schematic.

For the buck converter we will implement a hysteresis type control that keepsthe capacitor voltage roughly in a ±0.2 V band around 6 V. To make things abit more interesting we apply a step change from 12 V down to 8 V to the in-put voltage during the simulation.

Figure 1.20: Simulation of buck converter with hysteresis control

Demo Models

Now that you’ve built your first own models in PLECS it may be worthwhileto take a look at the demo models that come with PLECS. Open the demomodel browser by selecting “Demo Models” from the “View” Menu.

26

2

How PLECS Works

PLECS is a software package for modeling and simulating dynamic systems.As with any other software package, in order to make the best use of it youshould have a basic understanding of its working principles. Before delvinginto the question how PLECS works, however, it is worthwhile to distinguishbetween the terms modeling and simulation.

The term modeling refers to the process of extracting knowledge from the sys-tem to be simulated and representing this knowledge in some formal way.The second part – i.e. the representation of knowledge – can be more or lessstraightforward depending on the formalism used. PLECS offers three dif-ferent formalisms – equations (implemented as C-code), block diagrams andphysical models – that can be used in the same modeling environment. Theyare described in the following section.

The term simulation refers to the process of performing experiments on amodel in order to predict how the real system would behave under the sameconditions. More specifically, in the context of PLECS, it refers to the compu-tation of the trajectories of the model’s states and outputs over time by meansof an ordinary differential equation (ODE) solver. This is described in the sec-ond section.

Modeling Dynamic Systems

A system can be thought of as a black box as depicted below. The system doesnot exchange energy with its environment but only information: It accepts in-put signals u, and its reactions can be observed by the output signals y.

A system can have internal state variables that store information about thesystem’s past and influence its current behavior. Such state variables can becontinuous, i.e. they are governed by differential equations, or discrete, i.e.

2 How PLECS Works

xc, xd

System statesu

Input signalsyOutput signals

they change only at certain instants. An example of a continuous state vari-able is the flux or current of an inductor; an example of a discrete state vari-able is the state of a flip flop.

System Equations

One way to describe a system is by mathematical equations. Typical systemequations are listed below:

• An output function describes the system’s outputs in terms of the currenttime, the system’s inputs and its internal states.

• If the system has discrete states, an update function determines if and howthey change at a given time for the current inputs and internal states.

• If the system has continuous states, a derivative function describes theirderivatives with respect to time.

Symbolically, these functions can be expressed as follows:

y = foutput(t, u, xc, xd)

xnextd = fupdate(t, u, xc, xd)

xc = fderivative(t, u, xc, xd)

Such a description is most convenient for implementation in a procedural pro-gramming language like C.

Block Diagrams

A more graphic modeling method that is commonly used in control engineer-ing is a block diagram such as the one below which shows a low pass filter.

Each of the three blocks is again a dynamic system in itself, that can be de-scribed with its own set of system equations. The blocks are interconnected

28

Simulating Dynamic Systems

1/s+− 10

with directed lines to form a larger system. The direction of the connectionsdetermines the order in which the equations of the individual blocks must beevaluated.

Physical Models

Block diagrams are very convenient to model control structures where it isclear what the input and output of a block should be. This distinction is lessclear or impossible for physical systems.

For instance, an electrical resistor relates the quantities voltage and currentaccording to Ohm’s law. But does it conduct a current because a voltage is ap-plied to it, or does it produce a voltage because a current is flowing through it?Whether the first or the second formulation is more appropriate depends onthe context, e.g. whether the resistor is connected in series with an inductoror in parallel with a capacitor. This means that it is not possible to create asingle block that represents an electrical resistor.

Therefore, block diagrams with their directed connections are usually not veryuseful for modeling physical systems. Physical systems are more convenientlymodeled using schematics in which the connections between individual compo-nents do not imply a computational order.

PLECS currently supports physical models in the electrical, magnetic, me-chanical and thermal domains (in the form of lumped parameter models).


A simulation is performed in two phases – initialization and execution – thatare described in this section.

29

2 How PLECS Works

Model Initialization

Physical Model Equations

PLECS first sets up the system equations for the physical model according toe.g. Kirchhoff ’s current and voltage laws. If the physical model contains onlyideal linear and/or switching elements it can be described by a set of piece-wise linear state-space equations:

x = Aσx + Bσu

y = Cσx + Dσu

The subscript σ is due to the fact that each state-change of a switching ele-ment leads to a new set of state-space matrices.

The complete physical model is thus represented by a single, atomic subsys-tem. The following figure shows the interaction between the physical subsys-tem, the surrounding block diagram and the ODE solver.

s1 Event

detectionSolver

B + A C +

DSw

itch

man

ager

Physical model

continuousinputs

gateinputs

measure-ments

Switched state-space implementation

The physical subsystem accepts external input signals for controllable sourcesand for switching elements and it provides an output signal containing thevalues of physical measurements. During the simulation, the derivativesof the physical state variables are calculated and handed over to the solverwhich in turn calculates the momentary values of these state variables.

30


The Switch Manager monitors the gate signals and the internal measure-ments and decides whether a switching action is necessary. The Switch Man-ager also provides auxiliary signals – so-called zero-crossing signals – to thesolver for proper location of the exact instants when a switching should occur.

A flowchart of the Switch Manager is shown in the figure below. In everysimulation step, after the physical measurements have been calculated, theSwitch Manager evaluates the switching conditions of all switches in thephysical model. If a switching action is necessary, it initiates the calculationof a new set of state-space matrices or fetches a previously calculated set froma cache. Afterwards, it recalculates the physical measurements with the newstate-space matrices to check whether further switching actions of naturallycommutated devices are required. It will iterate through this process until allswitches have reached a stable position. If a set of switch states σ is encoun-tered repeatedly in this process, PLECS is unable to determine stable condi-tions and aborts the simulation.

Calculate state-space

outputs

Toggle switchesand get newtopology σ

Switch loopdetected?

Switchingrequired?

Start withgiven u, x, σ

Continue withnext step

yes

no

no

STOPyes

Switch Manager flowchart

Block Sorting

After the setup of the physical model, PLECS determines the execution orderof the block diagram. As noted above, the physical model is treated as a single

31

2 How PLECS Works

atomic subsystem of the block diagram. The execution order is governed bythe following computational causality:

If the output function of a block depends on the current value of one ormore input signals,the output functions of the blocks that provide theseinput signals must be evaluated first.

Direct feedthrough The property of an input port whether or not its cur-rent signal values are required to compute the output function is called directfeedthrough. For example, the output function of a linear gain is

y = k · u

and so the input signal of the gain has direct feedthrough. In contrast, theoutput function of an integrator is

y = xc

i.e. the integrator just outputs its current state regardless of the current in-put. The integrator input therefore does not have direct feedthrough.

Algebraic loops An algebraic loop is a group of one or more blocks that areconnected in a circular manner, so that the output of one block is connected toa direct feedthrough input of the next one.

For such a group it is impossible to find a sequence in which to compute theiroutput functions because each computation involves an unknown variable (theoutput of the previous block). Instead, the output functions of these blocksmust be solved simultaneously. PLECS uses a Newton-type equation solver forthis purpose. Since the solver performs iterations in order to find a solutionconsistent with all blocks, models with algebraic loops may run more slowlythan models without algebraic loops. Failure to find a solution brings the sim-ulation to a halt with an error message.

See “Simulation Parameters” (on page 107) for a list of parameters that influ-ence the solution of algebraic loops.

The Initial Condition block (see page 507) can be used to provide a guess tothe equation solver at the start of a simulation.

32


Model Execution

The figure below illustrates the workflow of the actual simulation.

Calculateoutputs

Calculateupdates

Calculateoutputs

Calculateoutputs

Startsimulation

Terminatesimulation

Mainloop

Eventdetectionloop

Integrationloop

Calculatederivatives

Calculatezero-crossings

Simulation loop

Main Loop

The main simulation loop – also called a major time step – consists of two ac-tions:

1 The output functions of all blocks are evaluated in the execution order thatwas determined during block sorting. If a model contains scopes, they willbe updated at this point.

2 The update functions of blocks with discrete state variables are executed tocompute the discrete state values for the next simulation step.

Depending on the model and the solver settings, the solver may enter one orboth of the following minor loops.

33

2 How PLECS Works

Integration Loop

If a model has continuous state variables, it is the task of the solver to nu-merically integrate the time derivatives of the state variables (provided by themodel) in order to calculate the momentary values of the states variables.

Depending on the solver algorithm, an integration step is performed in multi-ple stages – also called minor time steps – in order to increase the accuracy ofthe numerical integration. In each stage the solver calculates the derivativesat a different intermediate time. Since the derivative function of a block candepend on the block’s inputs – i.e. on other blocks’ outputs – the solver mustfirst execute all output functions for that particular time.

Having completed an integration step for the current step size, a variable-stepsolver checks whether the local integration error remains within the specifiedtolerance. If not, the current integration step is discarded and a new integra-tion is initiated with a reduced step size.

Event Detection Loop

If a model contains discontinuities, i.e. instants at which the model behaviorchanges abruptly, it may register auxiliary event functions to aid a variable-step solver in locating these instants. Event functions are block functions andare specified implicitly as zero-crossing functions depending on the currenttime and the block’s inputs and internal states.

For instance, if a physical model contains a diode, it will register two eventfunctions, fturn on = vD and fturn off = iD, depending on the diode voltage andcurrent, so that the solver can locate the exact instants at which the diodeshould turn on and off.

If one or more event functions change sign during the current simulationstep, the solver performs a bisection search to locate the time of the first zero-crossing. This search involves the evaluation of the event functions at differ-ent intermediate times. Since the event function of a block – like the deriva-tive function – can depend on the block’s inputs, the solver must first executeall output functions for a particular time. Also these intermediate time stepsare called minor time steps.

Having located the first event, the solver will reduce the current step size sothat the next major time step is taken just after the event.

34


Fixed-Step Simulation

As indicated in the previous paragraphs, certain important aspects of the mi-nor simulation loops require a variable-step solver that can change its stepsize during a simulation. Using a solver with a fixed step size has two seriousimplications.

Integration Error A fixed-step solver does not have any control over theintegration error. The integration error is a function of the model time con-stants, the step size and the integration method. The first parameter is ob-viously given by the model, but the second and possibly the third parametermust be provided by the user. One strategy for determining an appropriatestep size is to iteratively run simulations and reduce the step size until thesimulation results stabilize.

Event Handling Discontinuities in a physical model – such as the turn-on orturn-off of a diode or the transition from static to dynamic friction – typicallydo not coincide with a fixed simulation step. Postponing such non-sampledevents until the following fixed simulation step will produce jitter and maylead to subsequent runtime errors, e.g. because a physical state variable be-comes discontinuous.

For these reasons it is generally recommended to use a variable-step solver.However, if you plan to generate code from a model to run it on a real-timesystem you will need to use a fixed-step solver.

Physical Model Discretization

In order to mitigate the problems due to non-sampled events, PLECS trans-forms the physical model into a discrete state-space model when it is sim-ulated with a fixed-step solver. The continuous state-space equations of theelectrical and magnetic domains are discretized and replaced with the follow-ing update rule:

xn = Ad · xn−1 + Bd1 · un−1 + Bd2 · un

By default, a first-order hold is applied to the input signals, i.e. it is assumedthat the inputs change linearly from un−1 in the previous step to un in thecurrent step. As a consequence, the inputs of the electro-magnetic model nowhave direct feedthrough because their current values must be known beforethe current model states and the model output can be calculated. This willresult in an algebraic loop if the value of a controlled voltage or current sourcedepends on a measurement in the electro-magnetic model.

35

2 How PLECS Works

To avoid this problem, the Controlled Current Source (see page 377) and theControlled Voltage Source (see page 773) can be configured to apply a zero-order hold on the input signal when the model is discretized. In this case onlythe input value from the previous simulation step u

(i)n−1 is required to calculate

the current state values.

By default, the discrete state-space matrices Ad, Bd1 and Bd2 are calculatedfrom the continuous matrices A and B using a fifth-order accurate fully-implicit three-stage Runge-Kutta formula (Radau IIA). Alternatively, the bilin-ear transformation known as Tustin’s method can be chosen. It is only 2nd or-der accurate and has poor damping characteristics for time constants that aresmaller than the discretization step size, but it is cheaper to compute becauseBd1 equals Bd2. Therefore, it can be useful for real-time simulations wherethe calculation time is essential. The discretization method can be chosen inthe Simulation Parameters dialog (see page 107).

Note that this applies only to the discretization of the electro-magnetic do-main. The state variables both from other physical domains and from the con-trol block diagram are integrated with Euler’s method.

Interpolation of Non-Sampled Switching Events

With the physical model discretized like this, non-sampled switching eventscan be handled efficiently using the following algorithm:

1 Check whether the solver has stepped over a non-sampled switching eventin the last simulation step.

2 If so, determine the time of the event and calculate the model state just af-ter the event using linear interpolation and handle the event, i.e. toggle oneor more switches.

3 Perform one full forward step.

4 Linearly interpolate the model states back to the actual simulation time.

This algorithm is illustrated using the example of a half-wave rectifier shownbelow. The two graphs show the commutation of the dc current from diode D3(shown in gray) to diode D1 (shown in black). The solid lines show the resultsfrom a simulation with a variable-step solver, large dots mark the steps of thefixed-step simulation, and small dots mark the internal interpolation steps.

Commutation starts when the voltage across D1 becomes positive. The fixed-step solver first steps well beyond the zero-crossing of the voltage (1). PLECSthen internally steps back to the zero-crossing (2) and turns on D1. With the

36


new set of state-space equations, it performs an internal full step forward (3)and then interpolates back to the actual simulation time (4). Next, the solversteps beyond the zero-crossing of the current through D3 (1). Again, PLECSinternally steps back to the zero-crossing (2) and turns off D3. With the newset of state-space equations, it performs an internal full step forward (3) andthen interpolates back to the actual simulation time (4).

12

34

Dio

de c

urre

nts

1

2 34

Dio

de v

olta

ge

Interpolation of non-sampled switching events

Note that without this interpolation scheme, D3 would have been turned off atpoint (1). This would have caused the current through the inductor in phase 3to become discontinuous. Such a non-physical behavior can lead to gross simu-lation errors and should therefore be avoided.

37

2 How PLECS Works

Sampled Data Systems

PLECS allows you to model sampled data systems, i.e. discrete systems thatchange only at distinct times. You can model systems that are sampled pe-riodically or at variable intervals, systems that contain blocks with differentsample rates, and systems that mix continuous and discrete blocks.

Sample Times

Sample times are assigned on a per-block basis, and some blocks may havemore than one sample time. PLECS distinguishes between the following sam-ple time types:Continuous A continuous sample time is used for blocks that must be up-dated in every major and minor time step. This includes all blocks that havecontinuous state variables, such as the Integrator or Transfer Function.Semi-Continuous A semi-continuous sample time is used for blocks thatmust be updated in every major time step but whose output does not changeduring minor time steps. This applies for instance to the Memory block, whichalways outputs the input value of the previous major time step.Discrete-Periodic A periodic sample time is used for blocks that are updatedduring major time steps at regular intervals.Discrete-Variable A variable sample time is used for blocks that must beupdated during major time steps at variable intervals which are specified bythe blocks themselves.Inherited An inherited sample time is used for blocks that do not have asample time of their own but may adopt the sample time from other blocksconnected to them. This includes blocks such as Gain, Sum and Product.Constant A constant sample time is used for blocks that are updated onlyonce at the beginning of a simulation. The only block that explicitly uses aconstant sample time is the Constant block. However, other blocks may inherita constant sample time.For most block types the sample time is automatically assigned. Discreteblocks and the C-Script block (see page 355) have a parameter Sample Timeallowing you to specify the sample time explicitly. A sample time is specifiedas a two-element vector consisting of the sample period and an offset time.The offset time can be omitted if it is zero.The table below lists the different sample time types and their correspondingparameter values.

38


Sample Time Parameter Values

Type Value

Continuous [0, 0]

0

Semi-Continuous [0, -1]

Discrete-Periodic [Tp, To] Tp: Sample period, Tp > 0

Tp To: Sample offset, 0 ≤ To < Tp

Discrete-Variable [-2, 0]

-2

Inherited [-1, 0]

-1

Constant [inf, 0]

inf

Sample Time Inheritance

For blocks with an inherited sample time, PLECS employs the following prop-agation scheme to determine an appropriate sample time:

1 Propagate the sample times forward along the block execution order (see“Block Sorting” on page 31). A block with an inherited sample time will beassigned a sample time based on the sample times of the blocks that areconnected to the block’s inputs.

2 Propagate the sample times backward along the block execution order. Ablock with an inherited sample time will be assigned a sample time basedon the sample times of the blocks that are connected to the block’s outputs.

3 Loop until there are no inherited sample times left or until no inheritedsample time can be resolved.

Sample times are assigned according to the following rules:

• If any sample time is inherited, the block sample time also remains inher-ited.

39

2 How PLECS Works

• Else, if all sample times are constant, the block sample time is set to con-stant.

• Else, if any sample time is continuous, the block sample time is set to con-tinuous.

• Else, if all sample times are fixed-step discrete or constant and the fastestsample time is a valid base sample time of the other non-constant sampletimes, the block sample time is set to the fastest sample time.

• Else, the block sample time is set to semi-continuous.

Any block sample time that cannot be resolved using this propagation schemeis set to continuous.

Multirate Systems

Systems that contain blocks with multiple different discrete-periodic sampletimes are called multirate systems. For such systems, PLECS calculates abase sample time as the greatest common divisor of the periods and offsetsof the individual sample times. The individual periods and offsets are then ex-pressed as integer multiples of the base sample time.

This is necessary in order to avoid synchronization problems between blockswith different sample times that would occur when the sample hits are cal-culated using floating-point arithmetic. For instance, in double precisionfloating-point arithmetic 3*1e-4 is not equal to 3e-4 (even though the differ-ence is only about 5.4 ∗ 10−20).

In order to find the greatest common divisor, PLECS may slightly adjust indi-vidual sample periods or offsets within a relative tolerance of approximately±10−8. PLECS does not allow the base sample time to become smaller than10−6 times the largest sample period in order to avoid overflows in the integerarithmetic.

Troubleshooting

If PLECS fails to find an appropriate base sample time it will show a corre-sponding error message. There are three possibilities to resolve the problem:

Adjusting the sample times Adjust the sample times of the individualblocks in the system so that PLECS can find a base sample time within theabove constraints. Whenever possible, specify sample times as rational num-bers instead of decimal fractions. For instance, for a block that is sampledwith a frequency of 30 kHz enter 1/30e3 instead of 3.3333e-5.

40


Allow multiple base sample times You can allow PLECS to use differ-ent base sample rates for different groups of block sample times. To do so,uncheck the option Use single base sample rate in the simulation param-eters dialog. Only block sample times within the same group are then guaran-teed to be synchronized with each other.

Disable sample time synchronization You can disable the sample timesynchronization altogether by unchecking the option Synchronize fixed-stepsample times in the simulation parameters dialog. This is generally not rec-ommended.

The last two options are only available when using a continuous state-spacemodel with a variable-step solver.

41

2 How PLECS Works

Data Types

PLECS can use different data types to store the value of a signal. The sup-ported data types are listed in the table below.

Data Types

Name Description

bool Boolean

uint8_t Unsigned 8-bit integer

int8_t Signed 8-bit integer





float Single-precision floating point

double Double-precision floating point

target A pseudo data type that resolves to single-precision ordouble-precision floating point depending on the simulationtarget. For normal simulations and when using the PLECSBlockset Coder, this type resolves to double. When usingthe PLECS Standalone Coder, the type is determined by theparameter Floating point format in the Coder Optionsdialog (see “Generating Code” on page 269).

Blocks with an Implicit Output Data Type

Certain blocks have an implicit output data type. For instance, all physicalmeters use the target output type, and a logical operator always outputs aBoolean signal. Other blocks with implicit output data types are listed be-low:

• Comparator (see page 362), bool

42

Data Types

• Edge Detection (see page 416), bool• Hit Crossing (see page 451), bool• Logical Operator (see page 518), bool• Monoflop (see page 536), bool• Relational Operator (see page 597), bool• Sign (see page 645), int32_t

Specifying an Output Data Type

The following blocks let you specify the data type of their output signals:

• Constant (see page 366)• Data Type (see page 383)• Enable (see page 424)• Gain (see page 440)• Offset (see page 557)• Product (see page 588)• Pulse Generator (see page 590)• Relay (see page 598)• Signal Input (see page 638)• Step (see page 661)• Sum (see page 665)• Rounding (see page 616)

Some of these blocks also let you choose to inherit the output data type fromthe input signal(s).

Data Type Inheritance

The following blocks implicitly inherit the output data type from the input sig-nals:

• Delay (see page 387)• Initial Condition (see page 507)• Memory (see page 529)• Minimum / Maximum (see page 531)• Signal Switch (see page 644)

43

2 How PLECS Works

• Zero Order Hold (see page 787)

If the input signals have heterogeneous data types, the data type with thegreatest order (as defined in the table above) is chosen. To explicitly set thedata type of one of the above blocks, insert a Data Type block (see page 383)in front of the block.

44

3

Using PLECS

The user interface of PLECS very closely resembles that of Simulink. Circuitsare built using the same simple click and drag procedures that you use tobuild a model. This chapter explains those aspects of PLECS that either areunique to PLECS or work differently from Simulink.

Configuring PLECS

The PLECS configuration parameters can be modified per user in the PLECSPreferences dialog. Choose the menu entry Preferences... from the Filemenu (PLECS menu on OS X) to open it.

General

The language used by PLECS can be specified in the Language field. PLECSuses the language settings of your computer as default setting. Availablelanguages are English and Japanese. To activate the new language settingsPLECS must be restarted.

The setting Symbol format controls whether resistors and capacitors aredrawn in DIN or ANSI style. The table below shows the different componentrepresentation for both settings.

When the Grid setting is set to on a grid is displayed in the background ofschematic windows for easier placement of components and their connections.

When the Circuit browser default setting specifies the default filteringmode used for all circuit browsers (see section “Circuit Browser” on page 84).

The maximum amount of memory that is used by PLECS during the sim-ulation can be controlled with the setting Cache size limit. Once PLECS

3 Using PLECS

DIN ANSI

reaches the memory limit it will discard earlier computation results whichmay have to be recalculated later during the simulation. On the other handthe value should not be higher than about one third of the physical memory ofthe computer where PLECS is running, otherwise the simulation performancemay be degraded due to swapping.

In PLECS Standalone the XML-RPC interface can be enabled or disabled forexternal scripting. When enabled, PLECS listens on the specified TCP port forincoming XML-RPC connections. See chapter “XML-RPC Interface in PLECSStandalone” (on page 252) for details on using the XML-RPC interface.

When opening a model, PLECS can reopen all scope windows that were openwhen the model was saved. The option Scope windows enables or disablesthis behavior.

Libraries

To add custom libraries to the library browser add these libraries in the Userlibraries settings. All custom libraries must be located on the library searchpath, which is defined differently depending on the PLECS edition:

• For PLECS Standalone the library search path can be changed in theSearch path settings on the same preferences page.

• For PLECS Blockset the custom libraries must be located on the MATLABsearch path. The MATLAB search path can be set from the MATLAB filemenu. The Search path settings are not available in the PLECS Blocksetpreferences.

If the checkbox Show library link indicators is checked, PLECS will dis-play a small hollow curved arrow ( ) in the lower left corner of each compo-nent that links back to a library. A right-click on this link indicator opens acontext menu that allows you to break the library link or show the originalcomponent in the library browser.

46

Configuring PLECS

Note To create a new component library in PLECS Blockset, you need to copythe PLECS Library block from the PLECS Extras library into a Simulink modelor library. For details on creating custom libraries see also section “Libraries”(on page 58).

Thermal

The setting Thermal description search path contains the root directoriesof the thermal library. See section “Thermal Library” (on page 130) for moredetails.

Scope Colors

The Scope background setting determines whether the PLECS scopes aredrawn with a black or white background.

The Scope palette setting determines the appearance of the curves insidethe PLECS scopes. To create a new custom palette, select any existing paletteand click on Duplicate. To remove a palette, click on Remove. Note that thedefault palette is read-only and cannot be removed.

The Signals group box lists the base properties used for the curves in a scopeplot. You can specify color, line style and line width individually for eachcurve. If a plot contains more curves than the number of entries in this list,PLECS will restart at the beginning. The default palette specifies six solid,one pixel wide line styles.

The Distinguish traces by setting specifies how different traces for a specificsignal are distinguished from each other (see “Adding Traces” on page 100).In the default palette, traces are distinguished by brightness, i.e. by using dif-ferent shades of the base color. In custom palettes, you can alternatively dis-tinguish traces by varying the color, line style or width. The selected propertywill then not be available in the signal list. Again, if a plot has more tracesthan the number of entries in this list, PLECS will restart at the beginning.

47

3 Using PLECS

Update

PLECS can be configured to check for updates every time it is started. If thecomputer running PLECS is located behind a firewall it may be necessary toconfigure proxy settings. These settings can be determined automatically orentered manually.

The Server name configures the fully qualified domain name or the IP ad-dress of the HTTP proxy server. Leave empty to disable proxy usage.

The Server port configures the TCP port of the HTTP proxy server.

The Proxy user configures the username to use for proxy authentication.Leave empty to disable proxy authentication.

The Proxy password configures the password for proxy authentication.

Note To check for updates PLECS sends its version to the PLEXIM updateserver. No further personal information is transmitted.

Coder

This tab only appears if you have a license for the PLECS Coder. For moreinformation about the PLECS Coder, see “Code Generation” (on page 263).

The setting Target support packages path lets you specify a folder, whichPLECS searches for target support packages for the PLECS Coder. A targetsupport package enables the PLECS Coder to generate code that is specific fora particular target such as the PLECS RT Box.

The table Installed targets lists the support packages that are installed inthe specified folder. PLECS automatically searches the folder when you startit. To refresh the list after you have installed a new target, click on the Re-fresh button.

48

Installing Extensions

Installing Extensions

The functionality of PLECS can be extended using packages called extensions.For PLECS 4.2, two extensions are available: WBS (Web-Based Simulation)and PIL (Processor-In-the-Loop). To install and configure these extensions,the Extensions dialog can be used: in PLECS, click on the menu entry PLECSExtensions... from the File menu.

WBS allows the visitor of a web page to run PLECS simulations interactivelyin a web browser. The simulation models are provided by a PLECS simula-tion server. PLECS Standalone can be used as a simulation server on the localcomputer. No additional WBS license is needed as long as this feature is usedonly for development and test purposes; for the deployment of the web servicea separate server license is required. The PLECS WBS framework containsthe necessary files to set up the web service. Please see the accompanying doc-umentation within the framework.

The PIL approach allows to run code on an embedded controller that is syn-chronized with the simulation in PLECS. The necessary framework files forgenerating suitable embedded applications can be installed by users thathave a separate PIL license. For more information about PIL, see chapter

49

3 Using PLECS

“Processor-in-the-loop” (on page 281) and the separate documentation avail-able from the PLECS website.

The dialog shows the available frameworks shipped with the current PLECSrelease in the lower part and the already installed frameworks in the upperpart. To extract a framework an installation path has to be specified once (atthe top of the dialog). Select the desired version from the available frame-works and click on Install selected.

Creating a New Circuit with PLECS Blockset

Open the PLECS library by typing plecslib at the MATLAB commandprompt. On Windows you can also use the Simulink library browser and clickon the entry PLECS. Copy the Circuit block from the PLECS library intoyour Simulink model, then double-click the block to open the schematic editor.

50

http://www.plexim.com/download/documentation

Creating a New Circuit with PLECS Blockset

Customizing the Circuit Block

You can customize the mask of the Circuit block to a certain extent, e.g. inorder to change the block icon or to define mask parameters. For informationon Simulink block masks please refer to the Simulink documentation.

Note You may not change the mask type or remove the callback from the ini-tialization commands. Doing so will break the interface and may lead to loss ofdata.

If you define mask parameters for the Circuit block, PLECS evaluates com-ponent parameters in the mask workspace rather than the MATLAB baseworkspace. The mask workspace contains both the mask parameters and anyadditional variables defined by the mask initialization commands. For detailson parameter evaluation see “Specifying Component Parameters” (on page 54).

By default, a double-click on the Circuit block opens the schematic editor. Thiscan be changed by editing the OpenFcn parameter of the block. To changethe behavior so that a double-click opens both the schematic editor and themask dialog,

1 Select the block, then choose Block Properties from the Edit menu orfrom the block’s context menu.

2 On the Callbacks pane of the block properties dialog, select OpenFcnfrom the function list and change the content of the callback function to

plecs('sl',202); open_system(gcb,'mask');

Alternatively, you can change the behavior so that a double-click opensonly the mask dialog. Then, add a checkbox to the dialog that will open theschematic editor when you click on it:

1 Select the block, then choose Block Properties from the Edit menu orfrom the block’s context menu.

2 On the Callbacks pane of the block properties dialog select OpenFcn fromthe function list and clear the content of the callback function.

3 Select the block, then choose Edit Mask from the Edit menu or from theblock’s context menu.

51

3 Using PLECS

4 On the Parameters pane of the mask editor add a checkbox parameterwith the prompt Open schematic and the variable name openschematic.As a dialog callback for the new parameter enter

if (strcmp(get_param(gcb,'openschematic'),'on'))set_param(gcb,'openschematic','off');plecs('sl',202);

end

Using the Library Browser

In PLECS Blockset the library browser is opened by a double-click on theComponents block in the PLECS library. In PLECS Standalone it is openedautomatically when the program is started. It can always be re-opened by se-lecting Library Browser in the Window menu.

You can navigate through the component library by clicking on the tree en-tries. Alternatively, you can search for a specific component by typing part ofits name into the search bar.

Drag the components you need from the library browser into the schematiceditor.

52

Using the Library Browser

Note In PLECS Blockset you cannot place Simulink blocks in a PLECSschematic or PLECS components in a Simulink model since both programs donot share the same Graphical User Interface.

53

3 Using PLECS

Components

Copying a Component into a Schematic

You can copy a new component into a schematic in different ways:

• Press and hold the Ctrl key (Cmd key on macOS), then drag an existingcomponent from the same or a different schematic.

• Drag a component from the Library Browser into the schematic.• Click into the schematic and start typing the type name of the desired com-

ponent. This will open a mini browser in a popup window. To insert a com-ponent, use the up/down cursor keys and press Enter, or click and drag thecomponent to the desired location. To close the mini browser without insert-ing a component, press the Esc key.

Moving a Component

To move a component, click it with the left mouse button and drag it to thedesired location. If the component has connected terminals, the connectionsare automatically rerouted to the new location so that the terminals remainconnected. To cut any existing connections when moving a component, holdthe Shift key while dragging the component.

Specifying Component Parameters

Every component has a dialog box to view and modify the component param-eters. To open the parameter dialog, double-click on a component or select thecomponent and choose Parameters... from the Edit menu or the component’scontext menu.

Most component parameters accept MATLAB expressions as values, providedthat they evaluate to an acceptable result. Parameter expressions are evalu-ated when you start a simulation or update the Simulink model. In case anerror occurs during evaluation of the parameters, an error dialog appears andthe corresponding component is highlighted.

An exception to this behavior are parameters that affect the appearance of thecomponent such as the parameter Number of windings of the Mutual Induc-tor (see page 547) or the parameter Width of the Wire Multiplexer (see page782). Such parameters must be literal values and are evaluated immediately.

54

Components

Integer values may be specified as decimal, binary or hexadecimal values.Hexadecimal integers are prefixed by 0x, binary integers are prefixed by 0b.The expressions 0xfa and 0b11111010, for example, both evaluate to 250.

Using Workspace Variables in Parameter Expressions

Parameter expressions that are not evaluated immediately can include MAT-LAB variables. Expressions are evaluated as a whole in one workspace. Bydefault, the evaluation workspace is the MATLAB base workspace. However,you can define local mask workspaces for subsystems that will then be usedfor the parameter evaluation in the underlying schematics. For information onsubsystem mask workspaces see “Mask Parameters” (on page 71).

You can also mask the Circuit block as a whole. This is necessary e.g. if youwant parameter expressions to be evaluated in the Simulink model workspace,or when you use the sim command from within a MATLAB function and wantto access the function workspace. For more information see “Customizing theCircuit Block” (on page 51).

Displaying Parameters in the Schematic

You can cause PLECS to display any component parameter beneath the blockicon in the schematic. You specify the parameters to be displayed using the

55

3 Using PLECS

check boxes next to the edit fields in the dialog box. Parameter values can beedited in the schematic directly by double-clicking them.

Changing Parameters of Multiple Components

You can simultaneously change the parameters of multiple components of thesame type. To do so, select the components, then double-click any of them orchoose Parameters... from the Edit menu or the components’ context menu.

In the parameter dialog for multiple components, parameters, for which theselected components have different values, show a placeholder text multiplevalues. If you leave this placeholder as is, the components retain their indi-vidual values for this parameter when you apply any other changes that youhave made.

Changing Parameters During a Simulation

Parameters are evaluated once a new simulation is started. Their values re-main constant throughout the simulation. Certain parameters can be changedduring the simulation, their value is used as soon as the change is applied.Depending on the parameter type it may be necessary to reevaluate otherparts of the model, which may take some extra computation time.

Parameters are changeable during the simulation if they do not change thestructure of the model. If, for example, a parameter value is a vector the ele-ments of the vector may be changed, whereas the size of the vector must re-main the same. Parameters that influence the number of terminals of a com-ponent or the width of a signal cannot be changed during simulation.

Changing Component Names

Component names are edited by double-clicking them in the schematic. Toshow or hide a component name, toggle Show name in the Format menu.

All component names in the same schematic must be unique and must containat least one non-space character. Trailing spaces are removed from the names.

56

Components

Changing the Orientation of Components

You can change the orientation of a component by choosing one of these com-mands from the Format menu:

• The Rotate command rotates a component clockwise 90 degrees (Ctrl-R).• The Flip left/right command flips a component horizontally (Ctrl-F).• The Flip up/down command flips a component vertically (Ctrl-I).

Note Unlike in Simulink, flipping a component is not equivalent to rotating it180 degrees.

Getting Component Help

Use the Help button in the dialog box to get online help about the component.

57

3 Using PLECS

Libraries

Libraries enable you to ensure that the custom components or masked sub-systems used in your circuit are always up-to-date. Or, the other way round,if you are developing your own custom components you can use a library toensure that changes you make to your component models are automaticallypropagated to a user’s circuit upon loading.

Creating a New Library in PLECS Blockset

To create a new component library, open the PLECS Extras library and copythe PLECS Library block into a Simulink model or library. The Simulinkmodel must be named (i.e. saved) before you can copy components from thecomponent library.

To add the new library to the library browser it has to be added to the list ofuser libraries in the PLECS Preferences (see chapter “Configuring PLECS” onpage 45 for details).

Creating a New Library in PLECS Standalone

Any model file in PLECS Standalone can be used as a library file. Addition-ally it is also possible to use PLECS Blockset libraries in PLECS Standalone.To make model file available as a library the file has to be added to the librarylist in the PLECS preferences (see chapter “Configuring PLECS” on page 45for details).

To create a new library file, create a new model file, copy the desired compo-nents into it and save it in a directory on the library path. The library path isalso set in the PLECS preferences.

Creating a Library Reference

When you copy a library component – either into a circuit schematic or intoanother or even the same component library – PLECS automatically createsa reference component rather than a full copy. You can modify the parametersof the reference component but you cannot mask it or, if it is already masked,edit the mask. You can recognize a library reference by the string "(link)" dis-played next to the mask type in the dialog box or by the string "Link" dis-played in the title bar of the underlying schematic windows.

58

Libraries

The reference component links to the library component by its full path, i.e.the Simulink path of the PLECS Library block and the path of the compo-nent within the component library as they are in effect at the time the copyis made. If PLECS is unable to resolve a library reference it highlights thereference component and issues an error message.

You can fix an unresolved library reference in two ways

• Delete the reference component and make a new copy of the library compo-nent.

• In PLECS Blockset, add the directory that contains the required Simulinkmodel to the MATLAB path and reload the circuit.

Updating a Library Reference

Library references are resolved upon loading of a circuit. Afterwards, anychanges that you make to a referenced library component are automaticallypropagated to the referencing components when you start a simulation or (inPLECS Blockset) when you update the simulation model.

Breaking a Library Reference

You can break the link between a library reference and the library component.The reference then becomes a simple copy of the library component; changesto the library component no longer affect the copy.

In order to break the link between a reference and its library component, se-lect the reference component, then choose Break library link from the Sub-system submenu of the Edit menu or the component’s context menu.

It is often desirable to break the links to all user-defined libraries in a model,for example when sending a model to another PLECS user who does not haveall the libraries that the model depends on. This can be done by selectingBreak all library links... from the Edit menu. Library links to the PLECScomponent library are not affected by this functionality.

59

3 Using PLECS

Connections

Connections define the relationship and interaction between components.

Signal Connections and Physical Connections

Signals are drawn with green lines ending with an arrow head. They repre-sent a directed flow of values from the signal output of one component to thesignal input of one or several other components. Values can be either scalarsor vectors. The width of a signal is determined when the simulation is started.

Physical connections represent energy flow between two points and do nothave an inherent direction. They are drawn in separate colors for the differ-ent physical domains: black for electrical, red for magnetic, blue for thermaland violet for mechanical. Physical connections can be created between physi-cal terminals of the same domain.

Creating Connections

To create a new connection, move the mouse pointer over an unconnected ter-minal, press the mouse button, and drag the mouse pointer to the desireddestination. If you drag the mouse pointer near a matching terminal, thepointer shape changes to a double cross, and the two terminals will be con-nected when you release the mouse button. If you drag the mouse pointer overa component, the connection will be routed to the nearest matching terminal(if any) of that component.

Creating Branches

Branches are used to connect more than two terminals. To create a branchconnection, place the mouse pointer on an existing connection or node whereyou want the branch to start. Press the right mouse button and drag themouse pointer to the desired destination. Instead of the right mouse buttonyou can also use the left mouse button while holding down the Ctrl key.

Alternatively, you can also create a branch by clicking on an unconnected ter-minal and dragging the mouse pointer to a matching connection or node.

60

Connections

Automatic Creation of Connections

If you select a component and hold the Alt key while hovering the mousepointer over another component, the schematic editor suggests connectionsbetween matching terminals or terminal groups of the two components. A ter-minal group in this context is a contiguous set of terminals of the same kindalong one edge of a component. To create the connection(s), press the mousebutton. Only one pair of matching terminals or terminal groups is connectedat one time. If there are multiple candidates, the connection with the shortestpath is chosen.

This is illustrated in the figures below. First, the starting component, a volt-age source, is selected. Next, the mouse pointer is moved to the destinationcomponent, a resistor, while holding down the Alt key. The editor suggests aconnection between the closest two electrical terminals. Last, after a mouseclick, the connection is created, and the editor suggests another connection be-tween the remaining two terminals.

You can also let the schematic editor create connections from multiple startingcomponents to a single destination component at once. This is useful e.g. tocombine the signal outputs of multiple meters into one Signal Multiplexer (seepage 640). First, select the many components, then move the mouse pointerto the destination while holding down the Alt key. Press the mouse button tocreate all connections at once.

61

3 Using PLECS

Editing Connections

After a connection has been created, you can change its path by moving indi-vidual segments. To move a connection segment, click it with the left mousebutton, then drag it to the desired destination.

You can also move parallel segments of different connections simultaneously.To do so, select the connections, then click on any one of the parallel segmentsand drag it to the desired destination. The other segments will be shifted si-multaneously while maintaining their relative distances.

Annotations

You can annotate schematics with text labels. Create an annotation by double-clicking in an unoccupied area of a schematic and start typing. To finish edit-ing, press the Escape key or click anywhere outside the annotation box.

You can move an annotation by selecting and dragging it with the mouse. Toedit an existing annotation, double-click it. Choose Text alignment from theFormat menu to change the text alignment of the annotation.

62

Subsystems

Subsystems

Subsystems allow you to simplify a schematic by establishing a hierarchy,where a Subsystem block is on one layer and the elements that make up thesubsystem are on another. Subsystems also enable you to create your ownreusable components. For more information see “Masking Subsystems” (onpage 66).

You can create a subsystem in two ways:

• Add a Subsystem block to your schematic, then open that block and add theblocks it contains to the subsystem.

• Select a number of blocks, then group those blocks into a subsystem.

Creating a Subsystem by Adding the Subsystem Block

To create a new subsystem, first add a Subsystem block to the schematic, thenadd the elements that make up the subsystem:

1 Copy the Subsystem block from the System library into your schematic.

2 Double-click on the Subsystem block in order to open it.

3 In the empty Subsystem window, build the subsystem. Use the differentport blocks (e.g. Signal Inport (see page 638), Signal Outport (see page 641)or Electrical Port (see page 422)) to configure the interface of the subsys-tem.

Creating a Subsystem by Grouping Existing Blocks

If a schematic already contains the blocks you want to convert to a subsystem,you can create the subsystem by grouping those blocks:

1 Select the blocks and connections that you want to include in the subsystemwithin a bounding box.

2 Choose Create subsystem from the Edit menu. PLECS replaces the se-lected blocks with a Subsystem block.

63

3 Using PLECS

Arranging Subsystem Terminals

When you add a port to a subsystem schematic, a corresponding terminal ap-pears at a free slot on the border of the Subsystem block. If necessary, theSubsystem block is resized automatically in order to accommodate the newterminal.

You can move a terminal to another free slot on the border by dragging it withthe middle mouse button. While you hold down the mouse button, a circleshows the free slot nearest to the mouse pointer. As an alternative you canpress the left mouse button while holding down the Shift key. When you re-lease the mouse button, the terminal is moved.

The figures below show a Subsystem block before, during and after moving aterminal.

Notice how the shape of the cursor changes to crosshairs as you move it intothe capture radius of the terminal. When you press and hold down the centermouse button, the cursor shape changes to a pointing hand.

Resizing a Subsystem Block

To change the size of a Subsystem block, select it, then drag one of its se-lection handles. While you hold down the mouse button, a dashed rectangleshows the new size. When you release the mouse button, the block is resized.The minimum size of a Subsystem block is limited by the number of terminalson each side.

The figures below show a Subsystem block before, during and after resizing.

Notice how the terminals on the right edge of the Subsystem block are shiftedafter you release the mouse button in order to fit into the new frame. The

64

Subsystems

block height cannot be reduced further because the terminals cannot beshifted any closer.

Placing the Subsystem Label

The label of a Subsystem block can be placed at any of the following nine po-sitions: at the middle of the four edges, at the four corners, or in the centerof the block. To change the placement of the label, drag it to a new location.While you hold down the mouse button, a dashed rectangle shows the new po-sition. When you release the mouse button, the label is moved.

65

3 Using PLECS

Masking Subsystems

Masking a subsystem allows you to create a custom user interface for a Sub-system block that hides the underlying schematic, making it appear as anatomic component with its own icon and dialog box. Many of the componentsin the PLECS component library are in fact masked subsystems.

To mask a subsystem, select the Subsystem block, then choose Create mask...from the Subsystem submenu of the Edit menu or the block’s context menu.The mask editor appears. The mask editor consists of five tabbed panes thatare described in detail below.

Mask Icon

The Icon pane enables you to create icons that show descriptive text or labels,graphics and images.

Mask Editor Icon Tab

66

Masking Subsystems

Mask Icon Drawing Language

The Language selector lets you choose the programming language used forthe drawing commands. Choose Lua to create dynamic icons that can changedepending on user input. See “Getting Started with Lua” (on page 79) for abrief introduction to this language. Choose Legacy to select the syntax usedby PLECS 4.1 and older.

Mask Icon Drawing Commands

The drawing commands available in the Lua language are described below. Ifyou enter more than one command, the graphic objects are drawn in the or-der in which the commands appear. In case an error occurs during evaluationof the commands, PLECS displays three question marks (? ? ?) in the maskicon; if you hover the mouse over the subsystem block, a tooltip will show theerror message.

TextThe commands

Icon:text('text')Icon:text(x, y, 'text')

display text in the center of the icon or centered around the coordinates x, y.The text does not rotate with the icon; it is always displayed from left to right.The second command can be followed by parameter/value pairs to specify addi-tional properties listed in the table below.

LineThe command

Icon:line(xvec, yvec)

draws the line specified by the vectors xvec and yvec. Both vectors musthave the same length. Note that vectors are entered using curly braces, e.g.1, 2, 3. The vectors may contain non-finite values such as 0/0 or 1/0.When non-finite values are encountered, the line is interrupted and continuedat the next point that has finite values.

67

3 Using PLECS

Text Properties

Property Description

FontSize An integer specifying the font size of the text

TextFormat Specify the string PlainText to display the text as is (thedefault) or RichText to enable HTML markup such as<b></b> or <sup></sup>.

Color A vector r, g, b of three integers in the range from 0 to255 specifying the text color in RBG format

Patch

The command

Icon:patch(xvec, yvec)

draws a solid polygon with vertices specified by the vectors xvec and yvec.Both vectors must have the same length. Note that vectors are entered usingcurly braces, e.g. 1, 2, 3.

Circle

The command

Icon:circle(x, y, r)

draws a circle with the center coordinates x, y and the radius r.

Ellipse

The command

Icon:ellipse(x, y, rx, ry)

draws an ellipse with the center coordinates x, y and the radii rx and ry.

68

Masking Subsystems

ArcThe command

Icon:arc(x, y, rx, ry, start, span)

draws an elliptical arc with the center coordinates x, y and the radii rx and rybeginning at the start angle (in degrees) and extending span degrees counter-clockwise. The 0 degree angle is at 3 o’clock. Clockwise arcs can be drawn us-ing a negative span angle.

ColorThe command

Icon:color(r, g, b)

changes the current drawing color. The new color is given by r, g and b whichspecify the red, green and blue components. Each value is given as an integerin the range from 0 to 255.

ImageThe commands

Icon:image(xvec, yvec, 'filename')Icon:image(xvec, yvec, 'filename', 'on')

read an image from the file filename and display it on the mask icon.The parameter filename must be either an absolute filename (e.g.C:\images\myimage.png) or a relative filename that is appended to themodel’s directory (e.g. images\myimage.png). Supported image formats areBMP, GIF, JPG and PNG.The two-element vectors xvec and yvec specify the minimum and maximumcoordinates of the image’s extent. Note that vectors are entered using curlybraces, e.g. -10, 10.Use the optional flag 'on' to indicate that the image should rotate or flip to-gether with the mask icon. By default, this is set to 'off', and the image ori-entation remains fixed.Only one image can be displayed on a mask icon; if you use multiple imagecommands, only the last one will be effective.

69

3 Using PLECS

Querying Parameter Values

The command

Dialog:get('variable')

returns the string value of the mask parameter associated with the variablevariable. Note that the parameter values are not evaluated. Thus, if the userenters e.g. 2*2, the return value will be '2*2' and not '4'. The return valuefor a combobox parameter is a string containing the 1-based index of the cho-sen option or the expression entered by the user.

Legacy Command Syntax

The legacy command syntax is listed in the following table. The meaning ofthe command arguments is analogous to the Lua syntax. Vector parametersare entered using square brackets with optional commas for separating theelements, e.g. [1, 2, 3] or [3 4 5]. Note that the legacy syntax does notsupport all commands and options. Single-line comments start with a percentsign (%).

Legacy Command Syntax

Command Syntax

Text text(’text’)text(x, y, ’text’)

Line line(xvec, yvec)

Patch patch(xvec, yvec)

Circle circle(x, y, r)

Color color(r, g, b)

Image image(xvec, yvec, imread(’filename’))image(xvec, yvec, imread(’filename’), ’on’)

70

Masking Subsystems

Mask Icon Coordinates

All coordinates used by the mask drawing commands are expressed in pixels.The origin of the coordinate system is always the center of the block icon; it isadjusted when the block is resized. In an unrotated and unflipped block, thex-axis stretches from the left towards the right, and the y-axis stretches fromthe top towards the bottom.

Use the icon frame and/or the terminal locations as reference points in orderto position graphic elements. Both the frame and the terminals snap to a gridof 10 by 10 pixels.

Note PLECS expects you to confine icon drawings to the boundaries of thesubsystem frame. PLECS will not clip your drawings to the subsystem frame,but if you draw outside the frame, the drawings will not be erased properly e.g.when the subsystem is moved.

Mask Icon Properties

Show subsystem frameThe subsystem frame is the rectangle that encloses the block. It is drawnif this property is set, otherwise it is hidden.

Hide terminal labelsThis property controls whether the terminal labels underneath the iconare shown or hidden. A terminal label is only shown if this property is un-set and the name of the corresponding port block is visible.

Icon rotatesIf drawing commands are provided, this property determines whether thedrawn icon rotates when the component is rotated. The drawn icon re-mains stationary if this property is unchecked.

Mask Dialog

The Dialog pane enables you to define the parameters that will appear in thedialog box of the masked subsystem.

71

3 Using PLECS

Mask Editor Dialog Tab

Prompts and Associated Variables

Mask parameters are defined by a Prompt, a Variable and a Type. Theprompt provides information that helps the user identify the purpose of a pa-rameter. The variable name specifies the variable that will be assigned theparameter value.

Note In PLECS Standalone, the maximum length of variable names is 63characters. This is due to the way in which a mask workspace is stored inPLECS and exchanged with Octave. It is advisable to observe this limit alsoin PLECS Blockset to ensure that a model can be exchanged with PLECS Stan-dalone.

Mask parameters appear on the dialog box in the order they appear in the

72

Masking Subsystems

prompt list. You can add or remove parameters or change their order by us-ing the four buttons to the left of the prompt list.

Parameter Types

Parameters of type Edit are shown as a text edit field. The entered text is in-terpreted as a MATLAB/Octave expression and is usually expected to evaluateto a numeric value. Parameters of type String are shown as a combination ofa text edit field and a switch that determines whether the entered text shouldbe interpreted as a literal string or as a variable or expression that evaluatesto a string. Parameters of type Combo Box offer a choice of predefined val-ues. The possible values are defined in the Combo Box values field witheach line representing one value. Parameters of type Check Box can be setto false or true. Parameters of type Thermal allow to specify a thermal de-scription. See section “Thermal Description Parameter” (on page 127) for moredetails.

Tab Names

You can group parameters into separate tabs shown in the parameter dialogby assigning a tab name in the Tab column. All parameters that have thesame tab name will appear on the same tab page in the parameter dialog.

Tunable Parameters

By default, mask parameter values cannot be modified during a simulation.However, if you check the box in the Tunable column, the corresponding pa-rameter will be made tunable so that you can in fact modify it interactivelyduring a simulation by entering a new value in the parameter dialog. When-ever you change the parameter, PLECS will re-evaluate the parameter vari-able and the mask initialization commands and propagate the new variablevalues to the underlying components, which in turn must have tunable pa-rameters. If a changed variable is used in a non-tunable component parame-ter, the change will have no effect until the simulation is restarted.

Dialog Callback

The dialog callback is a Lua function that is executed whenever the userchanges a mask parameter. You can use it to disable or hide a parameter orchange its value depending on the value of another parameter.

73

3 Using PLECS

Querying Parameter Values

The command

Dialog:get('variable')

returns the string value of the mask parameter associated with the variablevariable. Note that the parameter values are not evaluated. Thus, if the userenters e.g. 2*2, the return value will be '2*2' and not '4'. The return valuefor a combobox parameter is a string containing the 1-based index of the cho-sen option or the expression entered by the user.

Setting Parameter Properties

The command

Dialog:set('variable', 'property', value, ...)

changes one or more properties of the mask parameter associated with thevariable variable. The properties are listed in the following table.

Parameter Properties

Property Description

Value A string specifying the parameter value

Enable A Boolean (i.e. true or false) specifying the enable state of theparameter. A disabled parameter is greyed out in the dialogand cannot be modified.

Visible A Boolean (i.e. true or false) specifying the visibility of theparameter in the dialog

Note Parameters that are disabled or invisible are not evaluated, and the pa-rameter variables are assigned a NaN value (not a number).

74

Masking Subsystems

Hiding, Showing and Moving TerminalsThe command

Block:showTerminal('name', flag)

shows or hides the terminal named name depending on the boolean value flag.The companion port of a hidden terminal acts in the same way as if the termi-nal was shown but unconnected.

The command

Block:moveTerminal('name', x, y)

moves the terminal named name to the relative coordinates x, y with respectto the unrotated and unflipped block. Note that the terminal rotation is notchanged.

Mask Workspace

Variable Scope

PLECS associates a local variable workspace with each masked subsystemthat has one or more mask parameters defined. Components in the underlyingschematics can access only variables that are defined in this mask workspace.

Initialization Commands

Mask initialization commands are defined on the Initialization pane. Theyare evaluated in the mask workspace when a simulation is started. You canenter any valid MATLAB/Octave expression, consisting of MATLAB/Octavefunctions, operators, and variables defined in the mask workspace. Variablesdefined in the base workspace cannot be accessed. The dialog parameter vari-ables are listed on the left hand side of the tab.

You can use mask initialization commands to check the user input, e.g.whether a variable value is within a certain range, or to define additionalworkspace variables that may be derived from mask parameters.

To show an error message in the Diagnostics window, e.g. that a certain maskparameter value is not valid, use the command

error('error message')

75

3 Using PLECS

Mask Editor Initialization Tab

To show a warning message in the Diagnostics window, use the command

plecs('warning','warning message')

Note that the native MATLAB/Octave command warning will only print thewarning message to the MATLAB command window or the Octave console.

Note In PLECS Standalone, the maximum length of variable names is 63characters. This is due to the way in which a mask workspace is stored inPLECS and exchanged with Octave. It is advisable to observe this limit alsoin PLECS Blockset to ensure that a model can be exchanged with PLECS Stan-dalone.

76

Masking Subsystems

Mask Probe Signals

The Probes pane enables you to define the probe signals that the maskedsubsystem will provide to the PLECS Probe. Mask probe signals appear inthe probe editor in the order they appear in the mask signal list. You can addor remove signals or change their order by using the four buttons to the left ofthe signal list.

Mask Editor Probes Tab

Mask probe signals are defined as vectors of probe signals from componentsbelow the subsystem mask. For this reason the controls in the lower half ofthe dialog are identical to those of the probe editor. In order to define a masksignal, select the signal in the list and then drag the desired components intothe dialog window. The new components are added to the bottom of the listof probed components. Next, select the components one by one and enablethe desired component signals in the list on the right side by using the checkboxes.

77

3 Using PLECS

Mask Documentation

The Documentation pane enables you to define the descriptive text that isdisplayed in the dialog box of the masked subsystem.

Mask Editor Documentation Tab

Mask Type

The mask type is a string used only for purposes of documentation. PLECSdisplays this string in the dialog box and appends "(mask)" in order to differ-entiate masked subsystems from built-in components.

Mask Description

The mask description is informative text that is displayed in the dialog box inthe frame under the mask type. Long lines of text are automatically wrapped

78

Masking Subsystems

to fit into the dialog box. You can force line breaks by using the Enter or Re-turn key.

Unprotecting Masked Subsystems

If you define a mask icon for a Subsystem block, PLECS automatically pro-tects the block and the underlying schematic. You can no longer resize theSubsystem block or modify the sub-schematic. The purpose of this protectionis to prevent the user from making unintentional changes that might renderthe icon useless.

If you want to change a masked Subsystem block, you can unprotect it bychoosing Unprotect from the Subsystem submenu of the Edit menu or theblock’s context menu. You can later protect it again by choosing Protect fromthe same menus.

Getting Started with Lua

Lua is a simple yet powerful open-source scripting language. This section in-troduces you to the basic concepts that you are likely to need in order to cre-ate dynamic subsystem masks. For a full reference please visit the Lua site athttp://www.lua.org.

Types and Variables

Lua is a dynamically typed language, which means that types are not asso-ciated with variables but only with values. To define a variable, you simplyassign a value to it.

By default, Lua declares all variables as global. However, PLECS executesLua code in a protected environment that forbids the creation or modificationof global variables. Therefore, you must explicitly declare variables as localusing the local keyword, e.g.

local a = "a string"

The most basic types in Lua are: nil, boolean, number, string and table.You can query the type of a value with the function type which returns thetype name as a string.

Nil Nil is a type with the single value nil. It is used to represent the ab-sence of a useful value.

79

http://www.lua.org

3 Using PLECS

Booleans The Boolean type has two values false and true. It can be usedin conditional expressions. If you use other types in conditional expressions,beware that Lua considers only the Boolean false and nil as false and any-thing else as true. In particular, both the numerical 0 and the empty string ”or "" are considered true in conditional tests.

Lua supports the logical operators and, or and not.

Numbers Lua differentiates between (double-precision) floating point num-bers and (64-bit) integer numbers. Numerals with a decimal point or an expo-nent are considered floats; otherwise, they are treated as integers.

Strings String literals in Lua can be delimited by single or double matchingquotes:

local a = "a string"local b = 'another string'

The difference between the two kinds is that inside one kind of quotes you canuse the other kind of quote without needing to escape it. The escape characteris the backslash (\), and the common C escape sequences such as \n for new-line are supported.

Long strings literals are delimited with matching double square brackets thatenclose zero or more equal signs, e.g. [[...]] or [==[...]==]. They can spanseveral lines and do not interpret escape sequences.

Tables Tables are Lua’s generic data structuring mechanism. They are usedto represent e.g. arrays, sets or records. A table is essentially an associativearray that accepts as keys not only numbers or strings but any other value ex-cept nil. A table is constructed with curly braces and a sequence of key/valuepairs, e.g.

a = x = 10, y = 20

A numerical vector as used in the mask icon drawing commands is just a ta-ble with 1-based consecutive integer keys and numeric values. It can be con-structed using the shorthand form of omitting the keys and just specifying thevalues:

a = 1, 2, 3

Alternatively, a numerical vector can be constructed using the followingPLECS specific syntax extension:

80

Masking Subsystems

a = Vector 1, 2, 3

A vector constructed in this way can be added to or multiplied with a scalarvalue. This is especially helpful in icon drawing functions if the graphic objectshall be displaced or scaled:

a_x = Vector 1, 2, 3 *zoom_factor + x_offseta_y = Vector 4, 5, 6 *zoom_factor + y_offset

Comments

A simple comment starts anywhere with two consecutive hyphens (--) andruns until the end of the line. Long comments start with two hyphens fol-lowed by two square brackets (--[[) and continue until the first occurrenceof two closing square brackets (]]).

A common trick is to use --]] to end a long comment to quickly comment anduncomment a block of code:

--[[Icon:line(-10, 10, -10, 10) -- commented out--]]

To un-comment the code block, prepend another hyphen to the first line:

---[[Icon:line(-10, 10, -10, 10) -- will be executed--]]

In the first example, the --[[ starts a long comment that continues until (andincluding) the ]] in the third line. In the second example, the first two hy-phens start an ordinary single-line comment, and so the second line is notcommented out. The two hyphens at the beginning of the third line againstart a single-line comment. Without these hyphens, the unpaired closingsquare brackets in the third line would cause a syntax error.

Statements

Lua does not need an explicit separator between consecutive statements, butyou can use a semicolon if you wish. Also, line breaks are treated like ordi-nary white space, so you can split a single statement into multiple lines with-out having to use a special continuation mark.

81

3 Using PLECS

Relational Operators

Lua supports the following relational operators:

< > <= >= == ~=

Relational operators always return a Boolean value. The == operator tests forequality and the ~= operator for inequality. They can be applied to any twovalues. If the values have different types, Lua considers them not equal. Oth-erwise, they are compared according to their type.

Functions

A function is defined as follows

local function drawTriangle(x, y)Icon:line(Vector0, 8.66, -8.66, 0+x,

Vector-10, 5, 5, -10+y)end

As with variables, the local keyword is required because without it the func-tion would be declared globally, which PLECS forbids. A function definitionconsists of the keyword function, a name (drawTriangle), a list of parame-ters (x, y), a body, i.e. a list of statements, and the terminator end. Parame-ters are local variables that are initialized with the values of the argumentspassed in the function call.The example above defines a function that draws a triangle with the centerpoint x, y. The function can be called as follows

drawTriangle(-10, 0)drawTriangle(10, 0)

A function can also return values using the return statement:

local function sum(values)local result = 0for i = 1, #values do

result = result + values[i]endreturn result

end

local x = sum(1, 2, 3) -- x will be 6

82

Masking Subsystems

Control Structures

Lua provides control structures for conditional execution and iteration.

if then else The if statement tests its condition and executes the thenbranch if the condition is true and otherwise the else part. The conditioncan result in any value, but as mentioned earlier, Lua treats all values otherthan nil and false as true. In particular, both the numerical 0 and the emptystring ('') are treated as true.

if Dialog:get('choice') == '1' thenIcon:text('+')

elseIcon:text('-')

end

Multiple conditions can be tested with the elseif statement. It is similar toan else followed by an if but avoids the need for and extra end:

if Dialog:get('choice') == '1' thenIcon:text('+')

elseif Dialog:get('choice') == '2' thenIcon:text('-')

elseIcon:text('+/-')

end

for The for statement has the following form:

for x = -10, 10, 5 doIcon:line(x, x, -10, 10)

end

The loop variable, x, which is implicitly local to the loop, is successively as-signed the values from -10 to 10 with an increment of 5, and for each valuethe loop body is executed. The result of the example will be five parallel ver-tical lines. The step value is optional; if it is omitted, Lua will assume a stepvalue of 1.

Lua also provides other control structures (iterator-based for, while, repeat).However, these are not relevant for dynamic masks.

83

3 Using PLECS

Circuit Browser

The Circuit Browser enables you to navigate a circuit diagram hierarchically.To display the Circuit Browser, select Show circuit browser from the Viewmenu of the schematic editor. Note that this option is only available from themain schematic window, i.e. the Circuit Browser will only be shown once forevery model.

The editor window splits into two panes. The left pane shows the CircuitBrowser, the right pane displays the current schematic. The Circuit Browsershows either a hierarchical or a flat list of all components and subsystems inthe circuit.

Selecting a component in the Circuit Browser will also select the same com-ponent in the schematic and vice versa. By dragging the mouse or by holdingdown the shift key you can select multiple components. If the selected compo-nents are compatible with each other, their parameters can be edited simul-taneously. The parameter dialog is displayed on double clicking the selectedcomponents or on clicking the option Component parameters. . . from thecontext menu.

The schematic is automatically updated to show the last selected component.The schematic of a specific subsystem can be displayed by double clicking it inthe Circuit Browser.

The components can be sorted by clicking on one of the column headers. Toquickly find e.g. all diodes in a circuit, switch to the flat view (see below) andsort it by clicking on Type. This will group all diodes together in the list.

84

Circuit Browser

Viewing Options

In the toolbar of the Circuit Browser, several viewing options are available.

View As Tree

The first two buttons in the toolbar switch between hierarchical and flat view.In the hierarchical (or tree) view, the first entry corresponds to the top-levelschematic of your circuit. A “+” or “–” sign next to a name indicates that thecorresponding schematic contains one or more subsystems. By double-clickingon the entry you can expand or collapse the list of these subsystems. This willalso show the schematic of the subsystem.

View As Flat List

The flat view lists all components of the entire circuit except the top-level cir-cuit itself. This view has an additional column that shows the path of eachcomponent.

Look Under Masks

By default, the Circuit Browser treats a masked subsystem like a component,i.e. it will not list the contents of the subschematic. You can change this be-havior by toggling this button.

Follow Library Links

By default, the Circuit Browser treats a library link like a component, i.e. itwill not list the contents of the subschematic. You can change this behavior bytoggling this button.

Filter

The Filter button lets you choose, which components are shown in the CircuitBrowser. When filtering is turned off, all components are shown. By clickingon the small arrow symbol, you can select between two filtering modes:

85

3 Using PLECS

Show only subsystems When this mode is active, the Circuit Browsershows only subsystems.

Show assertions When this mode is active, the Circuit Browser shows onlyassertion blocks and components with attached assertions (see “Assertions”on page 90). To view the associated assertion parameters, double-click on theentry in the Circuit Browser.

Custom filter When this mode is active, a search bar is shown. The CircuitBrowser shows only those components that match the search criterion or allcomponents if the search string is empty.

The default filtering mode of the Circuit Browser can be specified in thePLECS preferences (see section “Configuring PLECS” on page 45).

86

PLECS Probe

PLECS Probe

The PLECS Probe enables you to monitor various quantities in a circuit. Mostintrinsic components provide one or more probe signals that describe their cur-rent state, input, or output signals. For instance, an inductor provides a probesignal that monitors the inductor current; the probe signals of a diode are thediode voltage, current and conduction state.The PLECS Probe can either be used in a PLECS schematic or – for PLECSBlockset – in a Simulink model. To use the PLECS Probe in a schematic usethe Probe block from the “System” Library.In order to use the PLECS Probe in Simulink, drag the Probe block from thePLECS library into the Simulink model that contains the circuit which youwant to probe. Double-click the icon to open the probe editor window.

This window contains the following information.Probed circuit For the Simulink Probe the text box across the top shows thename of the circuit that you are probing and its path, i.e. the Simulink systemcontaining the Circuit block.

Note A Simulink Probe must be in the same Simulink model as the Circuitblock whose components you want to monitor. In addition, a Simulink Probeblock only accepts components from one single Circuit block at a time.

87

3 Using PLECS

Probed components The list box on the left side shows the componentsthat you have selected for probing. The components are identified by theirtype, name and path within the circuit. For adding components to this list,simply select them in the schematic editor and drag them into the probe edi-tor. The new components are appended at the bottom of the list. You can re-order the components using the Up , Down and Remove buttons. Ifyou click on the Show component button, the currently selected compo-nent will be shown in the schematic editor.

Component signals The list box on the right side shows the available probesignals for the selected component. Use the check boxes next to the signalnames in order to enable or disable individual signals. You can simultane-ously edit the signal states of several components provided that the compo-nents have the same type. In order to select multiple components, hold theShift or Ctrl key while clicking on a list entry.

For PLECS Probes that are used in a PLECS schematic there are two ways toadd components to the probe: Either drag them into the Probed componentsarea in the probe dialog (see above) or drop them onto the Probe block directly.

The output of the Probe block is a vector signal consisting of all enabled probesignals. If no probe signal is enabled a warning message will be printed to thecommand window and the block will output a scalar zero.

Copying a Probe

When you copy a PLECS Probe in a PLECS schematic, one of the followingthree cases can apply:

1 If a probed component is copied simultaneously with a Probe block referringto it, the copied Probe block will refer to the copy of the component.

2 Else, if the Probe block is copied within the same circuit, the copied Probeblock will refer to the original component.

3 Else (i.e. if the Probe block is copied into a different circuit), the probe refer-ence will be removed.

For technical reasons it is not possible to determine whether a PLECS Probefor Simulink is copied simultaneously with a Circuit block. Therefore, PLECSonly distinguishes between the following two cases:

1 If you copy a Simulink Probe block within the same model, the copied Probeblock will always refer to the original components.

88

PLECS Probe

2 If you copy a Probe block into a different model, all data is cleared from thecopied block.

89

3 Using PLECS

Assertions

Assertions allow you to monitor arbitrary signals during a simulation andraise a warning or error message if they fail to meet a given condition. For in-stance, imagine you want to ensure that a certain component operates withina safe temperature range. Once the temperature leaves the defined operatingrange, you would like to receive a notification. In PLECS, this can be achievedusing assertions.

Assertions are conditions that are assumed to hold during the entire simu-lation of a model. When a condition becomes invalid, i.e. when an assertionfails, PLECS executes a predefined action. The possible actions are:

• to ignore the failed assertion• to add a warning message to the diagnostics window• to add a warning message to the diagnostics window and additionally

pause the simulation• to add an error message to the diagnostics window and immediately stop

the simulation

There is a global model parameter that allows you to override the actions de-fined locally in the individual assertions (see “Simulation Parameters” on page107).

Note In PLECS Standalone, assertions are partially disabled during analy-ses (see “Analysis Tools” on page 165) and simulation scripts (see “SimulationScripts” (on page 239)). In a Steady-State Analysis, assertions are only enabledduring the final period shown at the end of the analysis. Assertions are not al-lowed to pause the Steady-State analysis, but it may be aborted if an assertiontriggers an error message. In all other analyses, assertions are entirely dis-abled. Assertions are not allowed to pause a simulation script, but a script maybe aborted if an assertion raises an error message.

PLECS provides two kinds of assertions: built-in assertion blocks and asser-tions that can be established on components based on their probe signals.

90

Assertions

Assertion Blocks

There is one basic Assertion block (see page 341) that interprets its input sig-nal as a boolean value. While the value is non-zero, the assertion holds; when-ever the input becomes zero, the assertion fails.

Because assertions are often used to ensure that a signal is within a certainrange or below or above a certain limit, PLECS provides additional assertionblocks to directly do this. These blocks are:

• Assert Dynamic Lower Limit (see page 338)• Assert Dynamic Range (see page 339)• Assert Dynamic Upper Limit (see page 340)• Assert Lower Limit (see page 342)• Assert Range (see page 343)• Assert Upper Limit (see page 344)

Component Assertions

PLECS also provides the possibility to add assertions directly to components.This can be used to define a valid range for any probe signal of a component.To add assertions to a component, open its parameter dialog and click on theAssertions tab. If the parameter dialog of a component does not provide thistab, it is not possible to add assertions.

Use the “+” and “-” buttons to add or remove assertions. In the differentcolumns, the parameters for the assertions can be provided: the probe signal

91

3 Using PLECS

that is limited by the assertion, the lower and upper limits, whether the lim-its should be inclusive, and the action executed when the assertion fails (seeabove). If the limits are included (by setting a check mark in that column), thelimits themselves are considered part of the valid range, otherwise the signalhas to be strictly within the limits. The values -inf and inf may be used todisable the lower or upper limit, respectively.

Locating Assertions

To quickly get an overview of all assertions that are defined in a model, openthe Circuit Browser (see page 84) and set the filter option to Show asser-tions. The Circuit Browser will then list only assertion blocks and compo-nents, for which assertions have been defined.

92

Controlling Access to Circuits and Subsystems

Controlling Access to Circuits and Subsystems

PLECS allows you to control user access to individual subsystems or to com-plete circuits. In particular, you can prevent a user from viewing or modifyinga schematic while still allowing the user to simulate a circuit.

To change the access settings of a circuit, open the permissions dialog box bychoosing Circuit permissions... from the File menu. To change the settingsof a subsystem, choose Permissions... from the Subsystem submenu of theEdit menu or the block’s context menu.

You can grant or deny the following privileges:

• The View privilege controls whether a user can view the schematic of a cir-cuit or subsystem.

• The Modify privilege controls whether a user can modify the schematic ofa circuit or subsystem. For a subsystem it also controls whether the maskdefinition may be modified.

If you apply access restrictions you will be asked for a password to prevent anunauthorized person from lifting these restrictions. The access settings canonly be changed again if the correct password is provided.

Encrypting Circuits and Subsystems

When PLECS saves a circuit with access restrictions to a model file, it en-crypts the respective sections to protect the circuit description from unautho-rized access.

93

3 Using PLECS

Exporting Schematics

PLECS allows you to export the schematic to a bitmap or PDF file for docu-mentation. The supported image formats are:

• JPEG (Bitmap)• TIFF (Bitmap)• PNG (Bitmap)• SVG (Scalable Vector Graphics)• PDF (Portable Document Format)

To export a schematic choose Export... from the File menu and select yourdesired output format. A second dialog lets you specify the export options forthe specific format, e.g. the bitmap resolution.

It is also possible to copy schematics to other applications directly via theclipboard. To copy an image of the current schematic to the clipboard chooseCopy as image from the Edit menu, then select Paste from the Edit menuin your target application.

94

Using the PLECS Scope


The PLECS scope is used to display simulation results and offers powerfulzooming and analysis tools to simplify viewing and processing results. ThePLECS scope can be placed on the Simulink worksheet or in the PLECS cir-cuit. The appearance of the PLECS scope is depicted below. The scope con-tains a plot area and optional Zoom view, Saved view and Data view windows.

Getting Started

To use the scope, drag the scope block from the PLECS library onto yourworksheet or schematic diagram. The scope block for Simulink can be foundin the top level of the PLECS library. The scope block for a PLECS circuit islocated in the PLECS Sources & Meters library.

95

3 Using PLECS

Double clicking on the Scope block opens the Scope window. The main windowof the scope can contain multiple plots. Plots can be quickly added or removedby right clicking the plot area and selecting Insert plot above, Insert plotbelow or Remove plot from the context menu.The optional Zoom view, Saved view and Data view windows can be openedby right-clicking on the toolbar area. They can also be opened from the Viewmenu. These optional windows can be docked and undocked from the mainwindow. To dock them in main window, simply drag them to the desired loca-tion inside the main window.

Legend

You can show a legend on top of each plot by choosing Show legend from theView menu or from the context menu. The default text of a signal label is de-rived from the name of the block from which the signal originates and possiblya probe signal name. To modify the text, double-click on a label. If you erasethe complete label text, the default text is restored.

Zoom Operations

Zooming is performed by clicking on the plot area and dragging the mouse un-til the desired area is selected. Two zoom modes exist: Constrained Zoom andFree Zoom. The zoom mode is selected using the toolbar button. To temporar-ily switch zoom modes, the Ctrl key (cmd key with macOS) can be pressed.

Constrained Zoom

With Constrained Zoom, zooming is only performed in the x or y direction.The zoom direction is selected by moving the mouse horizontally or vertically.

Free Zoom

With Free Zoom mode activated, the zoom area is defined by dragging thezoom cursor over a certain portion of the plot.

Zoom to Fit

Zoom to fit will fit the entire waveform into the plot window.

96


Zoom to Specification

A zoom range can also be manually specified. Double-clicking on the x or yaxis opens a dialog in which the x or y range of the zoom area can be entered.

Previous View, Next View

Every time a zoom action is performed, the view is stored in the view history.The previous and next view buttons allow you to navigate backwards and for-wards through the view history.

Panning

A zoom area can be panned by dragging the x or y axes of the plot with thehand symbol that appears.

Zoom Area Window

The zoom area window displays the entire waveform and highlights the zoomview that is displayed in the plot window. Constraint Zoom and Free Zoomcan also be performed in the zoom area window. The zoom area window is ac-tivated by right clicking on the toolbar.

Scrolling

During a simulation, if the current x-axis range is smaller than the simulationtime span, the scope will automatically scroll the x-axis so that the currentsimulation time step is always shown. The scrolling mode (paged or continu-ous) may be specified in the scope parameters.

Scrolling is suspended if you manually zoom or pan so that the current simu-lation time is greater than the right x-axis limit. This is indicated by a stackof small arrows at the right border of the plot. Scrolling is resumed if youclick on these arrows or if you zoom or pan so that the current simulationtime is less than the right x-axis limit.

97

3 Using PLECS

Y-Axis Auto-Scaling

The scope features a dynamic auto-scaling mode, in which the y-axis limitsare always adjusted to the currently visible waveforms. The state of the auto-scaling mode is indicated by a small semi-transparent icon ( / ) in the top-right corner of a plot. Clicking on this icon will toggle the state. Auto-scalingwill be enabled for all plots in the scope if you click the Zoom to Fit button.If you zoom in the y direction of a plot, auto-scaling will be disabled for thatplot. The initial auto-scale state at simulation start is specified for each plotindividually in the scope parameters (see page 631).

Changing Curve Properties

By default, the curves for the different signals and/or traces in a plot aredrawn with a pen that is defined by the palette selected in the PLECS pref-erences (see “Scope Colors” on page 47).

To change individual curve properties (color, line style and width), right-clickon a plot and select Edit curve properties from the context menu. This willopen a table listing the properties of all visible curves. To change a particularproperty, double-click on the corresponding table cell.

Locally changed properties are highlighted with a white background andare stored persistently in the model file. In contrast, properties that are de-fined by the global scope palette have a grey background. To remove all localchanges click on Restore Defaults.

Spreading Signals

When using a single plot to display multiple signals that assume only a smallnumber of discrete values (such as gate signals), it can be difficult to prop-erly see the value that a particular signal has. You can have the scope au-tomatically separate the signals in a plot by offsetting and scaling them ap-propriately. All signals are scaled by the same factor and the offsets are dis-tributed evenly in order to maintain the proportions between the signal. Verti-cal scrolling and zooming is disabled in this mode.

To enable signal spreading, right-click on a plot and select Spread signalsfrom the context menu. While spreading is enabled, the y-axis will only dis-play the zero-lines for the individual signals, and zooming in the y-direction isdisabled.

98


Cursors

The cursors are used for measuring waveform values and analyzing the sim-ulation results. Cursors can be positioned by dragging them to a specific timelocation, or by manually entering a value in the Time row in the Data Win-dow.

When the cursors are moved, they will snap to the nearest simulation timestep. To place the cursors arbitrarily, hold down the Shift key while movingthe cursor. The values in the data window will be displayed in italics to indi-cate they are interpolated from the two nearest time steps.

Data Window

When the cursors are activated, the data window appears if it was not alreadyopen. By default, the data window displays two columns in which the timeand data value of each signal at the position of each cursor are given. The sig-nal names are also displayed and can be modified by double-clicking on thename.

A right-click into the Data Window shows a context menu. Selecting “Copyto Clipboard” copies the current contents of the table to the system clipboard.Afterwards the data can be pasted into other applications, e.g. a spreadsheettool or word processor.

Signal Type

A small icon that represents the signal type is shown next to the signal namein the data view window. Signals can be of the continuous, discrete or impulsetype. The scope automatically determines the signal type from the port set-tings of the connected signal to ensure the signal is displayed correctly. Thesignal type can be overridden if necessary by clicking on the signal type icon.

Analyzing Data

Right-clicking on the data view header line in the data view window allowsfor additional data analysis columns to be displayed. For example, difference,RMS, min, max, and total harmonic distortion (THD) analysis can be per-formed. The analysis is performed on the data between the two cursors. Formeaningful RMS and THD values the cursor range must be equal to the pe-riod of the fundamental frequency.

99

3 Using PLECS

Locking the Cursors

Locking the cursors can be useful for performing measurements over a fixedtime period, such as the time period of an ac voltage. When dragging one ofthe locked cursors, the other cursor will be moved in parallel at a specifiedtime difference. To lock the cursors, the Delta column in the Data Windowmust be made visible by right-clicking on the table header. The desired cursordistance can be entered in the Time row of the Delta column. The cursorscan be unlocked by double-clicking on the lock icon in the Delta column.

Fourier Analysis

A Fourier analysis of the data in the current cursor range is accessible fromthe View menu. The use of the Fourier analysis is detailed in section “Usingthe Fourier Analysis” (on page 102).

Saving a View

A particular zoom view can be saved by pressing the eye button. The savedviews window will appear if it was not already displayed and the new viewwill be added to the saved views list. To access a particular saved view, clickon the view name in the saved views window. Saved views can be renamed bydouble clicking the name of the view, and reordered by clicking and draggingan entry up and down in the list. A view can be removed with the red deletebutton.

Adding Traces

After a simulation has been completed the resulting curves can be saved as atrace. Traces allow to compare the results of different simulation runs.

A new trace is added by either pressing the Hold current trace button in thetoolbar or by pressing the green plus button next to the Current Trace entryin the Traces window. To remove a trace press the red minus button next tothe trace in the Traces window. Held traces can be reordered by clicking anddragging an entry up and down in the list.

Traces can also be added and removed by simulation scripts. For details, seesection “Holding and Clearing Traces in Scopes” (on page 241).

100


Saving and Loading Trace Data

Existing traces in a scope can be saved by selecting Save trace data... fromthe File menu. The saved traces can be loaded into a scope for later reference.The scope into which the trace data is loaded must have the same number ofplots as the scope from which the data was saved. The number of input sig-nals per plot should also match, otherwise the trace data is lost when a newsimulation is started.

Scope Parameters

The scope parameters dialog allows for the appearance of the scope to bechanged and automatic or custom zoom settings to be applied to the x and yaxes. More information can be found in the parameter description of the Scopeblock (see page 631). The plot background color can be changed in the PLECSpreferences (see section “Configuring PLECS” on page 45).

Printing and Exporting

A plot can be printed or exported from the File menu. When printing, the ap-pearance of the plot and legend can be changed using the Page Setup option.When exporting, the plot style can also be changed and the output size of theimage can be customized.

The data table can be exported to e.g. Microsoft Excel using the clipboard. Tocopy the data to the clipboard open the context menu by right-clicking andchoose "Copy to clipboard".

101

3 Using PLECS

Using the Fourier Analysis

The Fourier Analysis is available from the View menu in the PLECS scopewindow.

The Fourier analysis window shows the magnitude of the Fourier coefficientsfor the given number of harmonics. The analysis range for the Fourier analy-sis is determined by the cursors in the scope window. By default it is assumedthat the cursor range covers exactly one period of the base frequency, thoughthis can be changed in the Fourier parameters. Note that spectral leakage ef-fects will be visible if the cursor time range is not an exact integer multiple ofthe inverse base frequency.

Calculation Parameters

Base FreqencyThe analysis range T is always bound to the cursor range in the PLECSscope. In general it consists of n periods of the base frequency, i.e. T = n

f0.

A click on the frequency input field f: in the window title bar opens theBase Frequency dialog. Two modes are available to set the base frequency:by freely positioning the cursors in the PLECS scope or by entering thenumerical values directly in the Base Frequency dialog.

The first mode is activated by selecting Calculate from cursor rangein the Base Frequency dialog. In this mode it is assumed that the cursorrange covers a single base period. The two cursors can be positioned inde-pendently from each other and should be set as exactly as possible to thestart and end of a single base period. The corresponding base frequency isdisplayed in the window toolbar.

If the base frequency is known beforehand it can be entered directly bychoosing Set base frequency. In this mode the scope cursors are lockedto the number of base periods. Moving the cursors still allows you to selectthe analysis range without changing the base frequency.

Number of Fourier CoefficientsThe number of Fourier Coefficients which are calculated can be changed inthe input field N: in the window title bar.

102

Using the Fourier Analysis

Display Parameters

Display frequency axisThe frequency axis is either shown underneath each plot or underneaththe last plot only.

Frequency axis labelThe text is shown below the frequency axis.

ScalingThe Fourier analysis window offers three options to scale the Fourier coef-ficients: Absolute, linear displays the absolute value of each coefficient.Absolute, logarithmic displays the common logarithm of the absolutevalues, multiplied by 20. Relative, linear scales all coefficients such thatthe coefficient of the base frequency is 1. When set to Relative, logarith-mic (dB) the coefficients are displayed on a logarithmic scale in Decibelsrelative to the coefficient of the base frequency.

Table dataThe table below the Fourier plots shows the calculated Fourier coefficients.The values can be displayed without phase (Magnitude only), with phasevalues in radians (Magnitude, phase (rad)) or with phase values in de-gree (Magnitude, phase (degree)).

The following items can be set for each plot independently:

TitleThe name which is displayed above the plot.

Axis labelThe axis label is displayed on the left of the y-axis.

Y-limitsThe initial lower and upper bound of the y-axis. If set to auto, the y-axisis automatically scaled such that all data is visible.

Signal Type

As in the scope window the signal type in the Fourier analysis window can bechanged by clicking the small icon next to the signal name in the data viewwindow. Available types are bars, stems and continuous. By default the sig-nals are displayed as bars. Changing the signal type for one signal will affectall signals in the same plot.

103

3 Using PLECS

Zoom, Export and Print

The Fourier analysis window offers the same zoom, export and print opera-tions as the PLECS scope. See section “Using the PLECS Scope” (on page 95)for details.

Calculation of the Fourier coefficients

The following approximation is made to calculate the Fourier coefficients of asignal with variable sampling intervals ∆Tm:

F(n) =2

T

ˆ

T

f(t)e−jω0ntdt ≈ 2

T

∑m

ˆ

∆Tm

fm(t)e−jω0ntdt

where

fm(t) = amt+ bm for continuous signals

fm(t) = bm for discrete signals

A piecewise linear approximation is used for continuous signals. Compared toa fast Fourier transformation (FFT) the above approach also works for signalswhich are sampled with a variable sample rate. The accuracy of this approxi-mation highly depends on the simulation step size, ∆Tm: A smaller simulationstep size yields more accurate results.

104

Using the XY Plot

Using the XY Plot

The XY plot is used to display the relationship between two signals, x and y.In every simulation step the x and y input signals are taken as coordinates fora new point in the XY plot. You can choose to draw trajectories by connectingconsecutive points with a direct line, to draw a vector from the origin to thecurrent point or a combination of both.

Time Range Window

The time range window allows you to restrict the data that is used for plot-ting. The window is accessible from the View menu.

The time range can be modified by moving its left and right boundary. Theinactive time range is grayed out. By clicking into the time range, the activetime range can be shifted without changing its length. Any change of the time

105

3 Using PLECS

range is reflected in the XY plot immediately. If vectors are drawn, the rightend of the time range determines the position of the vector head.

If a time range is specified in the XY plot parameters it is used as the defaultwidth of the time range in the time range window. A detailed parameter de-scription is available in the XY Plot documentation (see page 784).

Zoom, Save View, Export and Print

The XY plot offers the same zoom, export and print operations as the PLECSscope. See section “Using the PLECS Scope” (on page 95) for details.

106

Simulation Parameters


PLECS Blockset Parameters

This section describes the simulation parameters available in PLECS Blocksetfor Simulink. For the PLECS Standalone simulation parameters please referto the next section (see page 111).

To open the parameter dialog, select PLECS parameters from the Simula-tion menu of the schematic editor.

Circuit Model Options

Diode Turn-On Threshold This parameter globally controls the turn-on be-havior of line commutated devices such as diodes, thyristors, GTOs and simi-lar semiconductors. A diode starts conducting as soon as the voltage across itbecomes larger than the sum of the forward voltage and the threshold voltage.Similar conditions apply to the other line commutated devices. The defaultvalue for this parameter is 1e-3.

For most applications the threshold could also be set to zero. However, in cer-tain cases it is necessary to set this parameter to a small positive value toprevent line commutated devices from bouncing. Bouncing occurs if a switchreceives an opening command and a closing command repeatedly in subse-quent simulation steps or even within the same simulation step. Such a sit-uation can arise in large, stiff systems that contain many interconnectedswitches.

Note The Diode Turn-On Threshold is not equivalent to the voltage dropacross a device when it is conducting. The turn-on threshold only delays theinstant when a device turns on. The voltage drop across a device is solely de-termined by the forward voltage and/or on-resistance specified in the device pa-rameters.

Type This parameter lets you choose between the continuous and discretestate-space method for setting up the physical model equations. For detailsplease refer to section “Physical Model Equations” (on page 30).

When you choose Continuous state-space, PLECS employs the Simulinksolver to solve the differential equations and integrate the state variables. The

107

3 Using PLECS

Switch Manager communicates with the solver in order to ensure that switch-ing occurs at the correct time. This is done with Simulink’s zero-crossing de-tection capability. For this reason the continuous method can only be usedwith a variable-step solver.

In general, the default solver of Simulink, ode45, is recommended. However,your choice of circuit parameters may lead to stiff differential equations, e.g.if you have large resistors connected in series with inductors. In this case youshould choose one of Simulink’s stiff solvers.

When you choose Discrete state-space, PLECS discretizes the linear state-space equations of the physical model as described in section “State-SpaceDiscretization” (on page 35). All other continuous state variables are updatedusing the Forward Euler method. This method can be used with both variable-step and fixed-step solvers.

Discrete State-Space Options

Sample time This parameter determines the rate with which Simulinksamples the circuit. A setting of auto or -1 means that the sample time is in-herited from the Simulink model.

Refine factor This parameter controls the internal step size which PLECSuses to discretize the state-space equations. The discretization time step ∆tis thus calculated as the sample time divided by the refine factor. The refinefactor must be a positive integer. The default is 1.

Choosing a refine factor larger than 1 allows you to use a sample time thatis convenient for your discrete controller while at the same time taking intoaccount the usually faster dynamics of the electrical system.

Disc. method This parameter determines the algorithm used to discretizethe state-space equations of the electro-magnetic model.

ZC step size This parameter is used by the Switch Manager when a non-sampled event (usually the zero crossing of a current or voltage) is detected. Itcontrols the relative size of a step taken across the event. The default is 1e-9.

Tolerances The error tolerances are used to check whether the state vari-ables are consistent after a switching event. The defaults are 1e-3 for the rel-ative tolerance and 1e-6 for the absolute tolerance.

108


Diagnostics

Zero crossing detection disabled In order to accurately determine theproper switching times of power semiconductors, PLECS highly depends onthe solver’s capability to locate zero crossings. If you switch off the zero cross-ing detection in the Simulink solver or use the less accurate “Adaptive” detec-tion algorithm, PLECS will therefore issue a diagnostic message. This optionallows you to specify the severity level (warning or error) of this message.

If you encounter problems due to many consecutive zero crossings, it is usu-ally not advisable to modify the zero crossing detection settings. Consecutivezero crossings are often caused by insufficient simulation accuracy, typicallyin conjunction with a stiff model. In this case it may help to tighten the rela-tive tolerance of the Simulink solver (from the default 1e-3 to 1e-5 or 1e-6)and to switch from the default solver ode45 to a stiff solver such as ode23tband, where applicable, set the Simulink solver option Solver reset method toRobust.

Number of consecutive gate signal changes If you configure a Signal In-port block (see page 638) in a top-level schematic to be a gate signal, PLECSexpects this signal to change only at discrete instants. If instead the signalchanges in more than the specified number of consecutive simulation timesteps, PLECS will issue an error message to indicate that there may be aproblem in the gate signal generator. You can disable this diagnostic by en-tering 0.

Division by zero This option determines the diagnostic action to take ifPLECS encounters a division by zero in a Product block (see page 588) or aFunction block (see page 435). A division by zero yields ±∞ or nan („not anumber”, if you divide 0/0). Using these values as inputs for other blocks maylead to unexpected model behavior. Possible choices are ignore, warning anderror. In new models, the default is error. In models created with PLECS 3.6or earlier, the default is warning.

Algebraic loop with state machines This option determines the diagnos-tic action to take if PLECS detects an algebraic loop that includes a State Ma-chine (see page 659). This may lead to unexpected behavior because the StateMachine will be executed multiple times for the same simulation step dur-ing the iterative solution of the algebraic loop. Possible choices are ignore,warning and error. The default is error.

Negative switch loss This option determines the diagnostic action to takeif PLECS encounters negative loss values during the calculation of switchlosses (see “Loss Calculation” on page 123). PLECS can issue an error or a

109

3 Using PLECS

warning message or can continue silently. In the latter two cases, the lossesthat are injected into the thermal model are cropped to zero.

Assertion action Use this option to override the action that is executedwhen an assertion fails (see Assertion block on page 341). The default is uselocal settings, which uses the actions specified in each individual assertion.Assertions with the individual setting ignore are always ignored, even if thisoption is different from use local settings. Note that during analyses andsimulation scripts, assertions may be partly disabled (see “Assertions” on page90).

Sample times

Synchronize fixed-step sample times This option specifies whetherPLECS should attempt to find a common base sample rate for blocks thatspecify a discrete sample time.

Use single base sample rate This option specifies whether PLECS shouldattempt to find a single common base sample rate for all blocks that specify adiscrete sample time.

These options can only be modified for a Continuous State-Space model; for aDiscrete State-Space model they are checked by default. For details see sec-tion “Multirate Systems” (on page 40).

Algebraic loops

Method Use this option to select the strategy adopted by the nonlinearequation solver. Currently, either a line search method or a trust regionmethod can be used.

Tolerance The relative error bound. The solver updates the block outputsiteratively until the maximum relative change from one iteration to the nextand the maximum relative residual of the loop equations are both smallerthan this value.

State-space calculation

Use extended precision When this option is checked, PLECS uses higher-precision arithmetics for the internal calculation of the state-space matricesfor a physical model. Check this option if PLECS reports that the system ma-trix is close to singular.

110


Enable state-space splitting When this option is checked, PLECS will at-tempt to split the state-space model for a physical domain into smaller inde-pendent models that can be calculated and updated individually. This can re-duce the calculation effort at runtime, which is particularly advantageous forreal-time simulations.

Display state-space splitting When this option is checked, PLECS will is-sue diagnostic messages that highlight the components that make up the indi-vidual state-space models after splitting. This is useful e.g. in order to connectModel Settings blocks in the appropriate places (see Electrical Model Settingson page 421, Rotational Model Settings on page 610 and Translational ModelSettings on page 734).

Simulink Coder

Target This option specifies the code generation target that is used whenyou generate code with the Simulink Coder. For details on the available tar-gets see section “Code Generation Targets” (on page 276).

Inline circuit parameters for RSim target This option controls whetherPLECS inlines parameter values or whether it should keep them tunablewhen it creates code for the RSim target. For details see section “Tunable Cir-cuit Parameters in Rapid Simulations” (on page 278).

PLECS Standalone Parameters

This section describes the simulation parameters available for PLECS Stan-dalone. For the PLECS Blockset simulation parameters please refer to theprevious section.

To open the parameter dialog, select Simulation parameters from the Simu-lation menu of the schematic editor or press Ctrl-E.

Simulation Time

Start Time The start time specifies the initial value of the simulation timevariable t at the beginning of a simulation, in seconds. If a simulation isstarted from a stored system state (see “System State” on page 117), this pa-rameter is ignored and the simulation time specified in the system state isused instead.

111

3 Using PLECS

Time Span The simulation ends when the simulation time has advanced bythe specified time span.

Solver

These two parameters let you choose between variable-step and fixed-stepsolvers. A fixed-step solver uses the same step size – i.e. the simulation timeincrement – throughout a simulation. The step size must be chosen by theuser so as to achieve a good balance between accuracy and computational ef-fort.

A variable-step solver can adopt the step size during the simulation dependingon model dynamics. At times of rapid state changes the step size is reducedto maintain accuracy; when the model states change only slowly, the step sizeis increased to save unnecessary computations. The step size can also be ad-justed in order to accurately simulate discontinuities. For these reasons, avariable-step solver should generally be preferred.

DOPRI is a variable-step solver using a fifth-order accurate explicit Runge-Kutta formula (the Dormand-Prince pair). This solver is most efficient fornon-stiff systems and is selected by default. A stiff system can be sloppily de-fined as one having time constants that differ by several orders of magnitudes.Such a system forces a non-stiff solver to choose excessively small time steps.If DOPRI detects stiffness in a system, it will abort the simulation with therecommendation to switch to a stiff solver.

RADAU is a variable-step solver for stiff systems using a fifth-order accuratefully-implicit three-stage Runge-Kutta formula (Radau IIA). For non-stiff sys-tems DOPRI is more efficient than RADAU.

If auto is selected, PLECS starts a simulation with DOPRI and automati-cally switches to RADAU if the system is found to become stiff during a simu-lation. This is the default choice for a variable-step solver.

The fixed-step solver Discrete does not actually solve any differential equa-tions but just advances the simulation time with fixed increments. If thissolver is chosen, the linear state-space equations of the physical model are dis-cretized as described in section “State-Space Discretization” (on page 35). Allother continuous state variables are updated using the Forward Euler method.Events and discontinuities that occur between simulation steps are accountedfor by a linear interpolation method.

112


Variable-Step Solver Options

Max Step Size The maximum step size specifies the largest time step thatthe solver can take and should not be chosen unnecessarily small. If you sus-pect that the solver is missing events, try reducing the maximum step size.However, if you just require more output points for smoother curves, youshould increase the refine factor (see below).

Initial Step Size This parameter can be used to suggest a step size to beused for the first integration step. The default setting auto causes the solverto choose the step size according to the initial state derivatives. You shouldonly change this parameter if you suspect that the solver is missing an eventat the beginning of a simulation.

Tolerances The relative and absolute specify the acceptable local integrationerrors for the individual state variables according to

erri ≤ rtol · |xi|+ atoli

If all error estimates are smaller than the limit, the solver will increase thestep size for the following step. If any error estimate is larger than the limit,the solver will discard the current step and repeat it with a smaller step size.

The default absolute tolerance setting auto causes the solver to update theabsolute tolerance for each state variable individually, based on the maximumabsolute value encountered so far.

Refine factor The refine factor is an efficient method for generating addi-tional output points in order to achieve smoother results. For each successfulintegration step, the solver calculates r − 1 intermediate steps by interpolatingthe continuous states based on a higher-order polynomial. This is computa-tionally much cheaper than reducing the maximum step size (see above).

Fixed-Step Solver Options

Fixed step size This parameter specifies the fixed time increments for thesolver and also the sample time used for the state-space discretization of thephysical model.

Circuit Model Options

Diode Turn-On Threshold This parameter globally controls the turn-on be-havior of line commutated devices such as diodes, thyristors, GTOs and simi-lar semiconductors. A diode starts conducting as soon as the voltage across it

113

3 Using PLECS

becomes larger than the sum of the forward voltage and the threshold voltage.Similar conditions apply to the other line commutated devices. The defaultvalue for this parameter is 0.For most applications the threshold could also be set to zero. However, in cer-tain cases it is necessary to set this parameter to a small positive value toprevent line commutated devices from bouncing. Bouncing occurs if a switchreceives an opening command and a closing command repeatedly in subse-quent simulation steps or even within the same simulation step. Such a sit-uation can arise in large, stiff systems that contain many interconnectedswitches.

Note The Diode Turn-On Threshold is not equivalent to the voltage dropacross a device when it is conducting. The turn-on threshold only delays theinstant when a device turns on. The voltage drop across a device is solely de-termined by the forward voltage and/or on-resistance specified in the device pa-rameters.

Disc. method This parameter determines the algorithm used to discretizethe state-space equations of the electro-magnetic model.ZC step size This parameter is used by the Switch Manager when a non-sampled event (usually the zero crossing of a current or voltage) is detected. Itcontrols the relative size of a step taken across the event. The default is 1e-9.Tolerances The error tolerances are used to check whether the state vari-ables are consistent after a switching event. The defaults are 1e-3 for the rel-ative tolerance and 1e-6 for the absolute tolerance.

Sample times

Synchronize fixed-step sample times This option specifies whetherPLECS should attempt to find a common base sample rate for blocks thatspecify a discrete sample time.Use single base sample rate This option specifies whether PLECS shouldattempt to find a single common base sample rate for all blocks that specify adiscrete sample time.These options can only be modified for a variable-step solver; for a fixed-stepsolver they are checked by default. For details see section “Multirate Systems”(on page 40).

114


State-space calculation

Use extended precision When this option is checked, PLECS uses higher-precision arithmetics for the internal calculation of the state-space matricesfor a physical model. Check this option if PLECS reports that the system ma-trix is close to singular.

Enable state-space splitting When this option is checked, PLECS will at-tempt to split the state-space model for a physical domain into smaller inde-pendent models that can be calculated and updated individually. This can re-duce the calculation effort at runtime, which is particularly advantageous forreal-time simulations.

Display state-space splitting When this option is checked, PLECS will is-sue diagnostic messages that highlight the components that make up the indi-vidual state-space models after splitting. This is useful e.g. in order to connectModel Settings blocks in the appropriate places (see Electrical Model Settingson page 421, Rotational Model Settings on page 610 and Translational ModelSettings on page 734).

Assertions

Assertion action Use this option to override the action that is executedwhen an assertion fails (see Assertion block on page 341). The default is uselocal settings, which uses the actions specified in each individual assertion.Assertions with the individual setting ignore are always ignored, even if thisoption is different from use local settings. Note that during analyses andsimulation scripts, assertions may be partly disabled (see “Assertions” on page90).

Algebraic loops

Method Use this option to select the strategy adopted by the nonlinearequation solver. Currently, either a line search method or a trust regionmethod can be used.

Tolerance The relative error bound. The solver updates the block outputsiteratively until the maximum relative change from one iteration to the nextand the maximum relative residual of the loop equations are both smallerthan this value.

115

3 Using PLECS

Diagnostics

Division by zero This option determines the diagnostic action to take ifPLECS encounters a division by zero in a Product block (see page 588) or aFunction block (see page 435). A division by zero yields ±∞ or nan („not anumber”, if you divide 0/0). Using these values as inputs for other blocks maylead to unexpected model behavior. Possible choices are ignore, warning anderror. In new models, the default is error. In models created with PLECS 3.6or earlier, the default is warning.

Negative switch loss This option determines the diagnostic action to takeif PLECS encounters negative loss values during the calculation of switchlosses (see “Loss Calculation” on page 123). PLECS can issue an error or awarning message or can continue silently. In the latter two cases, the lossesthat are injected into the thermal model are cropped to zero.

Stiffness detection This parameter only applies to the non-stiff, variable-step DOPRI solver. The DOPRI solver contains an algorithm to detect when amodel becomes „stiff” during the simulation. Stiff models cannot be solved ef-ficiently with non-stiff solvers, because they constantly need to adjust the stepsize at relatively small values to keep the solution from becoming numericallyunstable.

If the DOPRI solver detects stiffness in model, it will raise a warning or errormessage depending on this parameter setting with the recommendation to usethe stiff RADAU solver instead.

Max. number of consecutive zero-crossings This parameter only ap-plies to variable-step solvers. For a model that contains discontinuities (alsotermed „zero-crossings”), a variable-step solver will reduce the step size so asto make a simulation step precisely at the time when a discontinuity occurs(see “Event Detection Loop” on page 34). If many discontinuities occur in sub-sequent steps, the simulation may come to an apparent halt without actuallystopping because the solver is forced to reduce the step size to an excessivelysmall value.

This parameter specifies an upper limit for the number of discontinuities inconsecutive simulation steps before PLECS stops the simulation with an errormessage that shows the responsible component(s). To disable this diagnostic,set this parameter to 0.

Algebraic loop with state machines This option determines the diagnos-tic action to take if PLECS detects an algebraic loop that includes a State Ma-chine (see page 659). This may lead to unexpected behavior because the State

116


Machine will be executed multiple times for the same simulation step dur-ing the iterative solution of the algebraic loop. Possible choices are ignore,warning and error. The default is error.

System State

This parameter controls how the system state is initialized at the beginning ofa simulation. The system state comprises

• the simulation time,• the values of all physical storage elements (e.g. inductors, capacitors, ther-

mal capacitances),• the conduction states of all electrical switching elements (e.g. ideal

switches, diodes),• the values of all continuous and discrete state variables in the control block

diagram (e.g. integrators, transfer functions, delays),• custom state information of C-Script blocks

Block parameters When this option is selected, the state variables are ini-tialized with the values specified in the individual block parameters.

Stored system state When this option is selected, the state variables areinitialized globally from a previously stored system state; the initial valuesspecified in the individual block parameters are ignored. This option is dis-abled if no state has been stored.

Store system state... Pressing this button after a transient simulationrun or an analysis will store the final system state along with a time stampand an optional comment. When you save the model, this information will bestored in the model file so that it can be used in future sessions.

Note Adding, removing, renaming, changing path (when moving in or outof a subsystem) or changing the number of internal states of blocks that havecontinuous or discrete state variables associated with them will invalidate thestored system state.

117

3 Using PLECS

Model Initialization Commands

The model initialization commands are executed when a simulation is startedin order to populate the base workspace. You can use variables defined in thebase workspace when specifying component parameters (see “Specifying Com-ponent Parameters” on page 54).

Note The maximum length of variable names is 63 characters. This is due tothe way in which a workspace is stored in PLECS and exchanged with Octave.

118

4

Thermal Modeling

Thermal management is an important aspect of power electronic systems andis becoming more critical with increasing demands for compact packaging andhigher power density. PLECS enables you to include the thermal design withthe electrical design at an early stage in order to provide a cooling solutionsuitable for each particular application.

Heat Sink Concept

The core component of the thermal library is an idealized heat sink (see page450) depicted as a semitransparent box in the figure below. A heat sink ab-sorbs the thermal losses dissipated by the components within its boundaries.At the same time, a heat sink defines an isotherm environment and propa-gates its temperature to the components which it encloses.

Diode Module IGBT Module

BrakeResistor

BrakeChopper

Tm m

Rth T: 60

Heat conduction from one heat sink to another or to an ambient temperatureis modeled with lumped thermal resistances and capacitances that are con-

4 Thermal Modeling

nected to the heat sinks. This approach allows you to control the level of de-tail of the thermal model.

Implementation

Each heat sink has an intrinsic thermal capacitance versus the thermal refer-ence node. All thermal losses absorbed by the heat sink flow into this capaci-tance and therefore raise the heat sink temperature. Heat exchange with theenvironment occurs via the external connectors.

HeatSink

Heatsink

temperature

K

Thermal

losses

You may set the intrinsic capacitance to zero, but then you must connect theheat sink either to an external thermal capacitance or to a fixed temperature,i.e. the Constant Temperature block (see page 368) or the Controlled Tempera-ture block (see page 376).

Thermal Loss Dissipation

There are two classes of intrinsic components that dissipate thermal losses:semiconductor switches and ohmic resistors.

Semiconductor Losses

Power semiconductors dissipate losses due to their non-ideal nature. Theselosses can be classified as conduction losses and switching losses. For com-pleteness the blocking losses due to leakage currents need to be mentioned,but they can usually be neglected.Semiconductor losses are specified by referencing a thermal data sheet in thecomponent parameter Thermal description. See section “Thermal Descrip-tion Parameter” (on page 127) and “Thermal Library” (on page 130) for moredetails.

120


Conduction Losses

The conduction losses can be computed in a straightforward manner as theproduct of the device current and the device voltage. By default the on-statevoltage is calculated from the electrical device parameters as v = Vf +Ron · i.

However, PLECS also allows you to specify the on-state voltage used for theloss calculation as an arbitrary function of the device current and the devicetemperature: v = von(i, T ). You may also specify additional custom functionarguments. This function is defined in the Conduction loss tab of the ther-mal description as a 2D look-up table or a functional expression (see “ThermalEditor” on page 132).

100.8 2 4

2.25

4.8 120 2.8

3

von [V]

0

0.75

14

82.6º24.7º

Legend:

118.8º

20

1.5

ion [A]86 16 18

A setting of 0 V for a single temperature and current value means no conduc-tion losses. If you do not specify a thermal description in the device parame-ters, the default will be used, i.e. the losses are calculated from the electricaldevice parameters.

Note If you specify the Thermal description parameter, the dissipated ther-mal power does not correspond to the electrical power that is consumed by thedevice. This must be taken into account when you use the thermal losses forestimating the efficiency of a circuit.

121

4 Thermal Modeling

Switching Losses

Switching losses occur because the transitions from on-state to off-state andvice versa do not occur instantaneously. During the transition interval boththe current through and the voltage across the device are substantially largerthan zero which leads to large instantaneous power losses. This is illustratedin the figure below. The curves show the simplified current and voltage wave-forms and the dissipated power during one switching cycle of an IGBT in aninverter leg.

iC(t)

vCE

(t)

iC(t)

vCE

(t)

t

Eon

Eoffp(t)

t

In other simulation programs the computation of switching losses is usuallychallenging because it requires very detailed and accurate semiconductor mod-els. Furthermore, very small simulation time-steps are needed since the du-ration of an individual switching transition is in the order of a few hundrednanoseconds.

In PLECS this problem is bypassed by using the fact that for a given circuitthe current and voltage waveforms during the transition and therefore the to-tal loss energy are principally a function of the pre- and post-switching condi-tions and the device temperature: E = Eon(vblock, ion, T ), E = Eoff(vblock, ion, T ).You may also specify additional custom function arguments. These functionsare defined in the tabs Turn-on loss and Turn-off loss of the thermal editoras 3D look-up tables or functional expressions (see “Thermal Editor” on page132) .

A setting of 0 J for a single voltage, current and temperature value means noswitching losses.

122


0.4

0.8

15

125º

Legend:25º

E [mJ]

vblock [V] 105 8

0.2

500

0 ion [A]

0.6

0

600

Note Due to the instantaneous nature of the switching transitions, the dissi-pated thermal energy cannot be consumed electrically by the device. This mustbe taken into account when you use the thermal losses for estimating the effi-ciency of a circuit.

Loss Calculation

As described above, the conduction and switching losses are defined by meansof look-up tables. From these tables the actual losses are calculated during asimulation using linear interpolation if the input values (on-state current, pre-and post-switching current or voltage, junction temperature) lie within thespecified index range. If an input value lies out of range, PLECS will extrapo-late using the first or last pair of index values.

If the calculated loss value is negative, PLECS will issue a diagnostic messageand/or crop the value to zero. You can select the diagnostic action to be takenwith the diagnostic parameter Negative switch loss in the simulation pa-rameters dialog (see “PLECS Blockset Parameters” on page 107 and “PLECSStandalone Parameters” on page 111).

123

4 Thermal Modeling

Supported devices

Semiconductor components that implement this loss model are

• the Diode (see page 388),• the Thyristor (see page 699),• the GTO (see page 442),• the GTO with Diode (see page 444),• the IGBT (see page 458),• the IGBT with Diode (see page 478),• the Reverse Blocking IGCT (see page 484),• the Reverse Conducting IGCT (see page 486),• the MOSFET (see page 538),• the MOSFET with Diode (see page 541) and• the TRIAC (see page 749).

In addition, the Set/Reset Switch (see page 633) is also included in this groupto enable you to build your own semiconductor models.

Ohmic Losses

Ohmic losses are calculated as i2 · R resp. u2/R. They are dissipated by thefollowing components:

• the Resistor (see page 599),• the Variable Resistor with Variable Series Inductor (see page 771),• the Variable Resistor with Constant Series Inductor (see page 768),• the Variable Resistor with Variable Parallel Capacitor (see page 769) and• the Variable Resistor with Constant Parallel Capacitor (see page 767).

Heat Sinks and Subsystems

By default, if you place a subsystem on a heat sink, the heat sink temperatureis propagated recursively into all subschematics of the subsystem. All thermallosses dissipated in all subschematics flow into the heat sink. In some casesthis is not desirable.

The implicit propagation mechanism is disabled if a subschematic containsone or more heat sinks or the Ambient Temperature block (see page 334). This

124

Temperature Initialization

latter block provides a thermal connection to the heat sink enclosing the par-ent subsystem block.

Cathode

Anode

Vf: Vf

R: Ron

L: Lrr R: RL V K * v_Lf(u)

f(u): K*u

R: Roff

AiD

VvAC

Ambient

f(u)

vAC*iD

As an example the figure above shows the subschematic of the Diode with Re-verse Recovery (see page 390). By default, this diode model would only dissi-pate the ohmic losses from the three resistors and the conduction losses of theinternal ideal diode. However, the losses from the reverse recovery current in-jected by the current source would be neglected because current sources (andalso voltage sources) do not dissipate thermal losses.

The Diode with Reverse Recovery therefore uses a Controlled Heat Flow block(see page 375) to inject the electrical power loss into the thermal model viathe Ambient Temperature block. The power loss is calculated by multiplyingthe device voltage and the device current.

Temperature Initialization

The state variables of a thermal model are the temperatures of thermal capac-itances, and like other state variables they need to be initialized with a start-ing value. For this purpose the Thermal Capacitor (see page 691) and othercomponents that implicitly contain thermal capacitances have a parameterInitial temperature, that allows you to specify this starting value.

125

4 Thermal Modeling

However, you can also let PLECS calculate the initial value for you based onother temperatures in the thermal system. To do so, simply leave the param-eter blank or enter nan (a floating point constant standing for “Not A Num-ber”). At the beginning of a simulation, PLECS will perform a “DC analysis”,treating thermal capacitances with known initial values like constant temper-ature sources and calculating the unknown initial values such that the systemwould be in steady state.

As an example, consider the following thermal system consisting of a con-stant temperature source and three thermal R/C pairs. If you leave the Ini-tial temperature parameter of the three capacitances blank, all three will“inherit” the starting temperature from the source. On the other hand, if youleave only the parameters of the first two capacitances blank and specify aninitial value of 125 for the third one, PLECS will initialize the first capac-itance with T0 = 25 + (125 − 25) · 2

2+3+5 = 45 and the second one withT0 = 25+(125−25) · 2+3

2+3+5 = 75. Of course, as soon as the simulation starts, thetemperatures in all three capacitances will eventually drop to the temperatureof the source.

Time0 10 20 30 40 50 60 70 80 90 100

Temperature

20406080100120140

126

Thermal Description Parameter


Most semiconductor components in PLECS have a parameter Thermal de-scription. The parameter can be used in two ways:

• to assign a data sheet from the thermal library to the component or• to assign a data sheet from a reference variable that is defined either as a

thermal mask parameter or in the MATLAB workspace.

Assigning Thermal Data Sheets

Thermal data sheets can be assigned to semiconductors with the menu entryFrom library.... PLECS only displays data sheets that match the device type;e.g. in the dialog box of a thyristor only those data sheets appear that havetheir Type field set to Thyristor.

Selecting a data sheet from a thermal library

If no data sheet is available the menu entry is disabled. In thermal param-eters of masked subsystem all data sheets are accessible, regardless of theirtype. See section “Thermal Library” (on page 130) for more information onhow to create new data sheets.

Using Reference Variables

To use a reference variable in the Thermal description parameter select themenu entry By reference from the parameter menu. Afterwards the refer-ence variable can then be entered in the text field.

127

4 Thermal Modeling

The reference variable must either be defined in a subsystem mask or in theMATLAB workspace. If a MATLAB workspace variable is used it must specifythe name of a thermal description file or a structure that defines the thermalloss data.

Referencing thermal data sheets

If the reference variable refers to a thermal data sheet, it must be specifiedas a string beginning with file: followed by the name of the datasheet. It ispossible to use an absolute file path to a thermal description file, for example:

thLosses = 'file:C:\Thermal\Vendor\mydiode.xml'

Alternatively, the name of a data sheet from the thermal library can be speci-fied. In this case the data sheet must be on the thermal search path. Its namemust be provided as a relative path without the .xml extension, for example:

thLosses = 'file:Vendor/mydiode'

Referencing data loss structures

The reference variable can contain a data structure that defines the thermallosses with the fields Von, Eon, Eoff and CauerChain. The fields are de-scribed as follows:

Von This field is a 2D lookup table for the voltage drop in form of a structwith two index vectors i, T and an output matrix v.

Eon, Eoff These fields are 3D lookup tables of the turn-on and turn-offlosses in form of structs with three index vectors v, i, T and an output arrayE.

CauerChain This field is a struct of two arrays, R and C which must have thesame length. The elements specify the respective values of the resistances andcapacitances in the thermal Cauer chain.

Any of the index vectors may be omitted if the lookup value is not dependenton the corresponding variable. The number of dimensions of the output tablemust correspond to the number of index vectors. If none of the index vectorsis specified, the output table must be a scalar. In this case the output can bespecified directly as a scalar rather than as a struct with a single scalar field.

An example for constructing a workspace variable containing loss data isgiven below:

128


von.i = [0 5 15 35 50];von.T = [25 125];von.v = [[0.8 1.3 1.7 2.3 2.7]' [0.6 1.1 1.6 2.6 3.2]'];eon.v = [0 200 300];eon.i = [0 13 23 32 50];eon.T = [25 125];eon.E = 1e-3 * ...

[0.000 0.000 0.000 0.000 0.0000.000 0.167 0.333 0.500 1.3330.000 0.250 0.500 0.750 1.700];

eon.E(:,:,2) = 1e-3 * ...[0.000 0.000 0.000 0.000 0.0000.000 0.333 0.667 1.000 2.2670.000 0.500 1.000 1.500 3.400];

cc.C = [0.95 2.4];cc.R = [0.118 0.172];thLosses = struct('Von', von, 'Eon', eon, 'Eoff', 0, ...

'CauerChain', cc);

In PLECS Blockset, workspace variables can also be constructed from ther-mal data sheets using the command line interface (see “Converting ThermalDescriptions” (on page 243)).

129

4 Thermal Modeling

Thermal Library

PLECS uses a library of thermal data sheets for semiconductors. The datasheets of the thermal library are created and edited with the thermal editor(see “Thermal Editor” (on page 132)). By separating the thermal descriptionsof semiconductors from their electrical behavior it is possible to use specificparameters from semiconductor manufactures for thermal simulations in con-junction with the generic electrical switch models from PLECS.

Library Structure

PLECS uses directory names to hierarchically organize the data sheets in thethermal library. The reference to a data sheet consists of its relative path andits filename starting from the directories on the thermal search path.

The search path for thermal libraries is specified in the PLECS preferences(see section “Configuring PLECS” (on page 45)). Each search path entry is theroot directory for a library tree. On program startup PLECS searches eachroot directory in the search path recursively for .xml files and merges theavailable descriptions into one logical structure. The accessible data sheetscan be updated manually by pressing the Rescan button in the PLECS pref-erences window. If a new data sheet is created and saved below a directorywhich is already on the search path the library is updated automatically.

A common way to organize data sheets within a thermal library is to use themanufacturer name as the first directory level and the part number as thefilename of the data sheet.

Global and Local Data Sheets

In addition to the global library search paths specified in the Preferenceswindow PLECS searches a private directory for each model. This allows forsharing models with other users without the need to synchronize the wholethermal library. The private directory is located in the same directory asthe model file. Its name is the name of the model file (without the .mdl or.plecs extension) plus a suffix _plecs, e.g. plSMPS_CCM_plecs for modelplSMPS_CCM.mdl (plSMPS_CCM.plecs).

If a library file with the same relative path is found both in the global and thelocal library the file from the local library is used.

130

Thermal Library

Creating New Data Sheets

New thermal data sheets are created by selecting New... + Thermal descrip-tion... from the File menu.

The data sheet should be saved on the thermal search path, otherwise it willnot be added to the thermal library and cannot be accessed.

Note It is also possible to import thermal descriptions from PLECS 1.x usingthe command line interface (see section “Command Line Interface” (on page243)).

Browsing the Thermal Library

PLECS allows for browsing the thermal library with the Thermal librarybrowser. It is invoked from the Window menu.

The tree view on the left shows all local and global data sheets of the thermallibrary for the current model.

131

4 Thermal Modeling

Thermal Editor

The Thermal Editor is used for creating, viewing and editing thermal datasheets. To open a new editor window select New... + Thermal description...from the File menu. Existing library data sheets can be edited either in theThermal library browser (accessible from the Window menu) or by assign-ing a data sheet to a semiconductor in the Thermal description parameterand then selecting the menu entry Edit....In order to access the data sheet in a PLECS model it must be saved in a sub-directory on the thermal search path. See section “Thermal Library” (on page130) for details of the structure of the thermal library.

132

Thermal Editor

The Thermal Editor window has the following input elements:

Manufacturer, Part number These text fields are for documentation pur-poses only.

Type This selector serves as a filter for the Thermal description menu en-try on the Thermal tab of a semiconductor parameter dialog. It must be setaccording to the semiconductor type it is intended to be used with.

Turn-on loss, Turn-off loss, Conduction loss On these tabs you define theswitching and conduction losses of the device. See “Editing Switching Losses”(on page 133) and “Editing Conduction Losses” (on page 134).

Therm. impedance On this tab you define the thermal impedance betweenthe junction and the case of the device. See “Editing the Thermal EquivalentCircuit” (on page 135).

Variables On this tab you define custom parameters (such as gate resis-tance or stray inductance) that may be used to define device losses. Here youcan also specify hard limits both for your custom parameters and for intrinsicvariables, i.e. the blocking voltage, the device current and the junction temper-ature.

Custom tables On this tab you define custom lookup tables that may beused to define device losses.

Comment This tab provides you with a text field that you may use for docu-mentation purposes.

Editing Switching Losses

Switching losses are defined on the Turn-on loss and Turn-off loss tabs. TheComputation method popup specifies whether the loss function is defined asa 3D lookup table, a functional expression or a combination of both.

If you select Lookup table, the pane below will show a 3D lookup table withthe blocking voltage, the device current and the junction temperature as inputvariables. For more information regarding lookup tables see “Editing LookupTables” (on page 138).

If you select Formula, the pane below will show a text field that allows you toenter a functional expression. A formula may consist of numerical constantsincluding pi, arithmetic operators (+ - * / ˆ), mathematical functions (abs,acos, asin, atan, atan2, cos, cosh, exp, log, log10, max, min, mod, pow, sgn,sin, sinh, sqrt, tan, and tanh), brackets and the function arguments. The de-fault function arguments are the blocking voltage v, the device current i and

133

4 Thermal Modeling

the junction temperature T. You may define additional function arguments onthe Variables tab (see “Adding Custom Variables” on page 136. You may alsoreference custom lookup tables using the function lookup (see “Adding CustomLookup Tables” on page 137).

If you select Lookup table and formula, the pane below will show bothlookup table and formula field. With this method, an energy E is first com-puted from the lookup table and may then be used in the formula to calcu-late the final loss energy value. For instance, in order to quickly increase theswitching loss by 20%, you could enter 1.2*E into the formula field.

Editing Conduction Losses

Conduction losses are defined by means of the on-state voltage drop on theConduction loss tab. The Computation method popup specifies whetherthe voltage drop is defined as a 2D lookup table, a functional expression or acombination of both.

If you select Lookup table, the pane below will show a 2D lookup table withthe device current and the junction temperature as input variables. For moreinformation regarding lookup tables see “Editing Lookup Tables” (on page138). On using the import wizard for constructing lookup table data from ven-dor plots, see “Import data from plot images” (on page 140).

If you select, Formula, the pane below will show a text field that allows youto enter a functional expression. The default function arguments are the de-vice current i and the junction temperature T. You may define additional func-tion arguments on the Variables tab (see “Adding Custom Variables” on page136. You may also reference custom lookup tables using the function lookup(see “Adding Custom Lookup Tables” on page 137).

If you select Lookup table and formula, the pane below will show bothlookup table and formula field. With this method, a voltage v is first computedfrom the lookup table and may then be used in the formula to calculate the fi-nal voltage drop value. For instance, in order to quickly increase the voltagedrop by 20%, you could enter 1.2*v into the formula field.

134

Thermal Editor

Editing the Thermal Equivalent Circuit

The thermal equivalent circuit of a component describes its physical structurein terms of thermal transitions from the junction to the case. Each transitionconsists of a thermal resistor and a thermal capacitor. They can be edited onthe Therm. impedance tab of the thermal editor. The thermal equivalentcircuit is specified either in Cauer or Foster form.The structure of a Cauer network is shown in the figure below. In the thermaleditor the number of chain elements n and the values for Ri (in K/W) and Ci(in J/K) for each chain element need to be entered.

Cauer network

The figure below illustrates the structure of a Foster network. In the thermaleditor the number of chain elements n and the values for Ri in (K/W) and τi(in s) for each chain element need to be entered. Foster networks can be con-verted to Cauer networks by pressing the button Convert to Cauer.

Foster network

Note Internally, PLECS always uses the Cauer network to calculate the ther-mal transitions. Foster networks are converted to Cauer networks at simula-tion start. Strictly speaking, this conversion is only accurate if the temperatureat the outer end of the network, i.e. the case, is held constant. For practical pur-poses the conversion should yield accurate results if the external thermal ca-pacitance is much bigger than the capacitances within the network.

135

4 Thermal Modeling

Adding Custom Variables

Custom variables, such as gate resistance or stray inductance, that you wishto use in the definition of device losses may be defined on the Variables tab.

Use the Add , Remove , Up and Down buttons on the left to add orremove custom variables or to reorder them. Note that the first three linesin the list are reserved for the intrinsic variables and may not be removed orreordered.

When you add a custom variable, you may specify a Prompt, which shouldprovide a brief description of the purpose variable, and a Variable, whichmust be a unique identifier. This identifier may then be used in the formulaexpressions that define the device losses.

In the Min and Max columns you may enter minimum and maximum allowedvalues for both intrinsic and custom variables. During a simulation, PLECSwill monitor the actual values of the variables and raise a diagnostic mes-sage if a variable value exceeds a specified limit. The default action is to showan error and stop the simulation but this may be changed in the simulationparameters dialog using the diagnostic parameter Loss variable limit ex-ceeded (see “PLECS Blockset Parameters” on page 107 and “PLECS Stan-dalone Parameters” on page 111).

136

Thermal Editor

Specifying custom variable values

When you select a thermal description with custom variables on the Thermaltab of a semiconductor parameter dialog, the dialog will show additional pa-rameter fields for the custom variables using the prompts mentioned above.An example dialog is shown below.

Instead of static values that remain constant during a simulation you mayalso specify the label of a Signal Goto block (see page 637) for a custom vari-able. The label is a string consisting of a prefix for the scope (g: for global,s: for schematic and m: for masked subsystem) and the tag name of the Gotoblock. For example, if your model contains a Goto block with global scope andthe tag name Rg, you would enter ’g:Rg’ (including the quotation marks) inorder to reference this signal in a custom variable of a thermal description.This can be used e.g. to simulate the effect of a gate drive that can dynami-cally change the effective gate resistance.

Adding Custom Lookup Tables

Custom lookup tables are defined on the Custom tables tab. To add a new ta-ble, click on New... and specify a unique name and the number of dimensionsof the new table. Use the Duplicate..., Rename... and Remove buttons toduplicate, rename or remove an existing custom table.

137

4 Thermal Modeling

Custom tables can be used in function expressions for device losses using thelookup function, which is called with a string specifying custom table nameand one to three numeric arguments depending on the number of dimensionsof the table.

For example, consider that you have defined a custom variable Rg for the gateresistance and a custom table Gate Resistance Eon Scaler that describeshow the turn-on losses scale in terms of the gate resistance. You could thenuse the Lookup table and formula method on the Turn-on loss tab, spec-ify the nominal losses in the turn-on-loss lookup table and enter the followingfunction expression:

E*lookup('Gate Resistance Eon Scaler', Rg)

Editing Lookup Tables

When editing an intrinsic lookup table on one of the three loss tabs or a cus-tom lookup table, you can add and remove new interpolation points for a ta-ble dimension with the Edit menu or the context menu in the table. To entermultiple values at once, separate them by semicolons or spaces.

To rotate and tilt a three-dimensional table view, click on an empty space withthe left mouse button and drag the mouse while keeping the mouse buttonpressed.

Lookup method

When calculating function values from a lookup table, PLECS uses linear in-terpolation if an input value lies within the index range for the correspondingtable dimension. If the input value lies outside the index range, PLECS willextrapolate using the first or last pair of index values.

Copy, Paste and Scaling

Thermal data can be copied and pasted within the tables of the thermal edi-tor, and to or from other programs, like e.g. Microsoft Excel. This can be doneusing the context menu or by pressing Ctrl-C/Ctrl-V (or cmd-C/cmd-V onMac OS X). To specify the target location for the data, you have to select apart of the table that has the same number of rows and columns as the copied

138

Thermal Editor

data. When copying from another program, only the first correctly format-ted number in each table cell will be copied, any additional information (e.g.units) will be discarded.

Values selected in a table can be scaled by a given factor by right-clicking andchoosing Scale selected values. . . from the context menu. To convert a valuefrom 0.23 J to 0.23 mJ, e.g., you can scale it with a factor of 0.001. To onlychange the unit but not the actual value, i.e. to change 0.23 J to 230 mJ, usethe Energy scale drop box at the top right.

139

4 Thermal Modeling

Importing Data from Graphical Datasheets

PLECS provides an Import Wizard that facilitates the import of data fromgraphs that are typically used on real datasheets. The wizard is opened byclicking on the magic wand icon ( ) that appears in the top right corner ofany page that allows you to enter tabular data, i.e. the loss and custom tablesand the thermal impedance.

When you open the import wizard for the first time on a particular page, youare requested to provide a graph image. To import an image, drag a image fileto the empty wizard area or click on the appropriate underlined text to open afile browser that lets you choose an image file. Image files must have a bitmapfile format (PNG, GIF, BMP, JPG or XPM). To import graphs from a PDF file,

140

Thermal Editor

take a snapshot of the desired graph, then select Paste from the Edit menuof the editor window or press Ctrl-V (cmd-V on Mac OS X) to paste the snap-shot into the wizard.After the image has been imported, a green coordinate system is drawn ontop of it. Your first task should be to align the green axes with the coordinatesystem in the image. You can move an axis or change its length by draggingthe axis itself or its end point with the mouse.Ensure that the axes have the proper dimensions. For turn-on and turn-offlosses, the x-axis is expected to be in Amperes and the y-axis, in Joules; forconduction losses, the x-axis is expected to be in Amperes and the y-axis, inVolts. If the dimensions in the image are swapped, you can flip the image byclicking on the Mirror axes button in the image configuration dialog (see be-low).

Configuring the Graph Import

After you have aligned the green coordinate system, you need to enter theaxis limits into the configuration dialog that has opened automatically whenthe image was imported. If you have closed the dialog, you can open it againby clicking on the button in the wizard toolbar or on one of the green axislimit labels.In addition to the minimum and maximum settings, the x-axis has a Snapproperty that is initialized automatically from the axis limits. You can over-ride the snap value by entering a number here; entering 0 disables snapping.To restore the automatically calculated value, click on the button.Both the x-axis and y-axis have a Scale property that lets you choose betweena linear and logarithmic scale. By default, double-logarithmic scaling is usedfor thermal impedances only; for all other imports the scaling defaults to lin-ear.The Opacity slider lets you change the opacity of the graph image from fullytransparent (or invisible) to fully opaque. The Mirror axes button will mirrorthe graph image diagonally so that the two axes are exchanged. This is usefule.g. when importing conduction losses where the graph typically shows Voltson the x-axis and Amperes on the y-axis.

Adding and Moving Points

Points are added by double-clicking anywhere in the coordinate system. Ifsnapping is enabled, the x-value is adjusted to the nearest snap value. To

141

4 Thermal Modeling

move points, drag them with the left mouse button. If snapping is enabled,you can temporarily disable it by pressing and holding the Shift key whenyou click on a point.To add new curves (e.g. for another temperature value) use the correspondingentry from the Edit menu or from the context menu of the table at the bot-tom of the editor. If there is more than one curve, a double-click will add newpoints to all curves: The point at the mouse location is added to the currentcurve, i.e. the curve that you added or interacted with most recently. For allother curves, points are added based on their neighboring points’ coordinates.Also, if there is more than one curve, the movement of points is restrictedto the y-direction. The reason for this is that all curves in the look-up tableshare the same x-values, so changing the x-value of a point in one curve willaffect all other curves as well. You can temporarily override this restriction bypressing and holding the Shift key when you click on a point.

Zooming and Panning

You can zoom into the graph for more precise placement of points and axes.Zooming is controlled via the View menu and the corresponding buttons inthe toolbar. You can also zoom in and out by holding the Ctrl key (Cmd keyon macOS) while rolling the mouse wheel. When you have zoomed into thegraph, you can pan the image using the sliders or by holding the Ctrl or Cmdkey while pressing and dragging the left mouse button. Pressing the spacebarwill zoom the graph to fit the window.

Adding and Managing Graph Images

Sometimes, the curves for one look-up table come from different graphs. Toadd a new graph image to the wizard, click the button in the toolbar. Tochange the visibility of a particular curve on the current graph, use the checkbox in the corresponding row header in the table at the bottom. Press the

button in the toolbar to rename the current graph; graph names are usedpurely for documentation purposes. To remove a graph (but not the curves),press the button.

Fitting Thermal Impedances

When a vendor datasheet provides the thermal impedance as a heating curverather than Foster or Cauer network coefficients, you can use the import wiz-

142

Thermal Editor

ard to fit Foster coefficients to a given heating curve. First, import the graphof the heating curve as described above and place a number of points on theheating curve, then choose the desired number of Foster elements. As a gen-eral rule, you must place at least two points per Foster element. As soon asthese requirements are met, PLECS will calculate a set of Foster coefficientsand display the result as an orange curve on top of the graph.

PLECS uses a non-deterministic optimization algorithm to minimize the er-ror between the calculated curve and the points that you have placed. Thisalgorithm may not converge at all or converge at a local instead of the globalminimum. If the current fit is not satisfactory, you can calculate a new one bypressing the Recalculate button. Once the results are acceptable, press theAccept button to close the wizard and transfer the calculated Foster values.

143

4 Thermal Modeling

Note The fitting algorithm can handle only single pulse curves. Vendordatasheets sometimes also show heating curves for repeated pulses with dif-ferent duty cycles; these curves cannot be used to calculate Foster coefficientswith PLECS.

If the fitting algorithm repeatedly does not find a satisfactory solution, you mayneed to increase the number of Foster elements. Typically, three to five Fosterelements should yield good results.

144

Semiconductor Loss Specification


Care must be taken to ensure the polarity of the currents and voltages arecorrect when specifying conduction and switching loss data for semiconductorswitches and diodes. If one or both polarities are in the wrong direction, thelosses will be zero or incorrect. The voltage and current polarities of a singlesemiconductor switch, diode and semiconductor switch with diode are definedin PLECS as shown in the figure below.

Voltage and current polarity of single semiconductor switch, diode and semi-conductor switch with diode

Single Semiconductor Switch Losses

The blocking voltage experienced by a single semiconductor switch is positive;therefore, switching losses are defined in the positive voltage/positive currentregion. Conduction losses are also defined in the positive voltage/positive cur-rent region.

Diode Losses

The voltage and current waveforms during a typical diode switching cycle areshown in the next figure. Turn on losses occur at t = t1 and turn off losses att = t2. The switching energy loss in both cases is calculated by PLECS usingthe negative blocking voltage and positive conducting current at the switchinginstant. These values are shown in the figure as dots. Therefore, the lookuptables for the turn-on and turn-off switching losses must be specified in thenegative voltage/positive current region.

Conduction losses occur when t1 < t < t2. During this time period, the currentand voltage are both positive. Therefore the conduction loss profile must bespecified in the positive voltage/positive current region.

145

4 Thermal Modeling

Idiode

Vdiode

t1

t2

t

Diode voltage and current during switching

Losses of Semiconductor Switch with Diode

Semiconductor switches with an integrated diode such as the IGBT with Diodemodel allow losses for both the semiconductor switch and diode to be individ-ually specified using a single set of lookup tables. The conduction and switch-ing loss tables for the semiconductor switch are specified for the same volt-age/current regions as for the single semiconductor switch without diode. Dueto the polarity reversal of the diode, the diode losses are appended to the losstables of the semiconductor switch by extending the tables in the negativevoltage/negative current direction for the diode conduction losses, and in thepositive voltage/negative current direction for the diode switching losses. Anexample turn-off loss table and conduction loss profile for a semiconductorswitch with diode are shown in the next two figures. A summary of the validvoltage and current regions for defining conduction and switching losses forthe different types of semiconductors is given below:

Switch with DiodeDiode Switch

Switch Diode

V I V I V I V I

Conduction Loss + + + + + + - -

Switching Loss - + + + + + + -

146


Turn-off loss lookup table for semiconductor switch with diode

Conduction loss profile for semiconductor switch with diode

147

4 Thermal Modeling

148

5

Magnetic Modeling

Inductors and transformers are key components in modern power electroniccircuits. Compared to other passive components they are rather difficult tomodel for the following reasons:

• Magnetic components, especially transformers with multiple windings canhave complex geometric structures. The flux in the magnetic core may besplit into several paths with different magnetic properties. In addition tothe core flux, each winding has its own leakage flux.

• Core materials such as iron alloy and ferrite express a highly non-linearbehavior. At high flux densities, the core material saturates leading to agreatly reduced inductor impedance. Moreover, hysteresis effects and eddycurrents cause frequency-depending losses.

In PLECS, the user can build complex magnetic components in a special mag-netic circuit domain. Primitives such as windings, cores and air gaps are pro-vided in the Magnetics Library. The available core models include saturationand hysteresis. Frequency dependent losses can be modeled with magneticresistances. Windings form the interface between the electrical and the mag-netic domain.

Alternatively, less complex magnetic components such as saturable inductorsand single-phase transformers can be modeled directly in the electrical do-main.

Equivalent circuits for magnetic components

To model complex magnetic structures with equivalent circuits, three differentapproaches exist: Coupled-inductors, the resistance-reluctance analogy andthe capacitance-permeance analogy.

5 Magnetic Modeling

Coupled inductors

In the coupled inductor approach, the magnetic component is modeled directlyin the electrical domain as an equivalent circuit, in which inductances repre-sent magnetic flux paths and losses incur at resistors. Magnetic coupling be-tween windings is realized either with mutual inductances or with ideal trans-formers.Using coupled inductors, magnetic components can be implemented in any cir-cuit simulator since only electrical components are required. This approach ismost commonly used for representing standard magnetic components such astransformers. The figure below shows an example for a two-winding trans-former, where Lσ1 and Lσ2 represent the leakage inductances, Lm the non-linear magnetization inductance and Rfe the iron losses. The copper resis-tances of the windings are modeled with R1 and R2.

Lσ1

Rfe

Lσ2 R2

Lm

R1

Ideal TransformerN1:N2

Transformer implementation with coupled inductors

However, the equivalent circuit bears little resemblance to the physical struc-ture of the magnetic component. For example, parallel flux paths in the mag-netic structure are modeled with series inductances in the equivalent circuit.For non-trivial magnetic components such as multiple-winding transformersor integrated magnetic components, the equivalent circuit can be difficult toderive and understand. In addition, equivalent circuits based on inductors areimpossible to derive for non-planar magnetic components.

Reluctance-resistance analogy

The traditional approach to model magnetic structures with equivalent elec-trical circuits is the reluctance-resistance analogy. The magnetomotive force(MMF) F is regarded as analogous to voltage and the magnetic flux Φ as anal-ogous to current. As a consequence, magnetic reluctance of the flux path Rcorresponds to electrical resistance:

150

Equivalent circuits for magnetic components

R =FΦ

The magnetic circuit is simple to derive from the core geometry: Each sectionof the flux path is represented by a reluctance and each winding becomes anMMF source.To link the external electrical circuit with the magnetic circuit, a magneticinterface is required. The magnetic interface represents a winding and estab-lishes a relationship between flux and MMF in the magnetic circuit and volt-age v and current i at the electrical ports:

v = NdΦ

dt

i =F

N

where N is the number of turns. If the magnetic interface is implementedwith an integrator it can be solved by an ODE solver for ordinary differentialequations:

Φ =1

N

ˆv dt

The schematic below outlines a possible implementation of the magnetic inter-face in PLECS.

Ф

K

K: 1/N

L: N

V F

A

i

Vve+

e-

m+

m-

Electrical Magnetic

Implementation of magnetic interface

Although the reluctance-resistance duality may appear natural and is widelyaccepted, it is an awkward choice for multiple reasons:• Physically, energy is stored in the magnetic field of a volume unit. In a

magnetic circuit model with lumped elements, the reluctances should there-fore be storage components. However, with the traditional choice of mmfand flux as magnetic system variables, reluctances are modeled as resis-tors, i.e. components that would usually dissipate energy. It is also confus-ing that the magnetic interface is a storage component.

151

5 Magnetic Modeling

• To model energy dissipation in the core material, inductors must be em-ployed in the magnetic circuit, which is even less intuitive.

• Magnetic circuits with non-linear reluctances generate differential-algebraicequations (DAE) resp. algebraic loops that cannot be solved with the ODEsolvers offered in PLECS.

• The use of magnetic interfaces results in very stiff system equations forclosely coupled windings.

Permeance-capacitance analogy

To avoid the drawbacks of the reluctance-resistance analogy the alternativepermeance-capacitance analogy is most appropriate. Here, the MMF F isagain the across-quantity (analogous to voltage), while the rate-of-change ofmagnetic flux Φ is the through-quantity (analogous to current). With thischoice of system variables, magnetic permeance P corresponds to capacitance:

Φ = P dF

dt

Hence it is convenient to use permeance P instead of the reciprocal reluctanceR to model flux path elements. Because permeance is modeled with storagecomponents, the energy relationship between the actual and equivalent mag-netic circuit is preserved. The permeance value of a volume element is givenby:

P =1

R=µ0µrA

l

where µ0 = 4π × 10−7 N/A2 is the magnetic constant, µr is the relative per-meability of the material, A is the cross-sectional area and l the length of theflux path.

Magnetic resistors (analogous to electrical resistors) can be used in the mag-netic circuit to model losses. They can be connected in series or in parallel toa permeance component, depending on the nature of the specific loss. The en-ergy relationship is maintained as the power

Ploss = F Φ

converted into heat in a magnetic resistor corresponds to the power loss in theelectrical circuit.

Windings form the interface between the electrical and the magnetic domain.A winding of N turns is described with the equations below. The left-hand

152

Magnetic Circuit Domain in PLECS

side of the equations refers to the electrical domain, the right-hand side to themagnetic domain.

v = N Φ

i =F

N

Because a winding converts through-quantities (Φ resp. i) in one domain intoacross-quantities (v resp. F ) in the other domain, it can be implemented witha gyrator, in which N is the gyrator resistance R. The figure below shows thesymbol for a gyrator and a possible implementation in PLECS.

A

A

R

R

Gyrator symbol and implementation

In principle, the gyrator component could be used with regular capacitors tobuild magnetic circuits. However, neither the gyrator symbol nor the capaci-tor adequately resemble a winding respectively a flux path. Moreover, any di-rect connection between the electrical and magnetic domain made by mistakewould lead to non-causal systems that are very difficult to debug. Therefore,dedicated magnetic components should be used when modeling magnetic cir-cuits.


The magnetic domain provided in PLECS is based on the permeance-capacitance analogy. The magnetic library comprises windings, constant andvariable permeances as well as magnetic resistors. By connecting them accord-ing to the physical structure the user can create equivalent circuits for arbi-trary magnetic components. The two-winding transformer from above will looklike the schematic below when modeled in the magnetic domain.

Pσ1 and Pσ2 represent the permeances of the leakage flux path, Pm the non-linear permeance of the core, and Gfe dissipates the iron losses. The windingresistances R1 and R2 are modeled in the electrical domain.

153

5 Magnetic Modeling

R2R1

N1 N2

GfePm

Pσ1 Pσ2

Transformer implementation in the magnetic domain

Modeling Non-Linear Magnetic Material

Non-linear magnetic material properties such as saturation and hysteresiscan be modeled using the variable permeance component. The permeance isdetermined by the signal fed into the input of the component. The flux-ratethrough a variable permeance P(t) is governed by the equation:

Φ =d

dt(P · F ) = P · dF

dt+

d

dtP · F

Since F is the state variable the equation must be solved for dFdt . Therefore,

the control signal must provide the values of both P(t) and ddtP(t).

The control signals must also provide the flux Φ(t) through the permeance.This enables the solver to enforce Kirchhoff ’s current law for all branches k ofa node:

n∑k=1

Φk = 0

When specifying the characteristic of a non-linear permeance, we need to dis-tinguish carefully between the total permeance Ptot(F ) = Φ/F and the differ-ential permeance Pdiff(F ) = dΦ/dF .

If the total permeance Ptot(F ) is known the flux-rate Φ through a time-varying permeance is calculated as:

154


Φ =dΦ

dt

=d

dt(Ptot · F )

= Ptot ·dF

dt+

dPtot

dt· F

= Ptot ·dF

dt+

dPtot

dF· dF

dt· F

=

(Ptot +

dPtot

dF· F)· dF

dt

In this case, the control signal for the variable permeance component is:P(t)

ddtP(t)

Φ(t)

=

Ptot + d

dF Ptot · F

0

Ptot · F

In most cases, however, the differential permeance Pdiff(F ) is provided to char-acterize magnetic saturation and hysteresis. With

Φ =dΦ

dt

=dΦ

dF· dF

dt

= Pdiff ·dF

dt,

the control signal isP(t)

ddtP(t)

Φ(t)

=

Pdiff

0

Ptot · F

Saturation Curves for Soft-Magnetic Material

Curve fitting techniques can be employed to model the properties of ferromag-netic material. As an example, a saturation curve adapted from the modifiedLangevian equation for bulk magnetization without interdomain coupling isused, which is referred to as the coth function:

155

5 Magnetic Modeling

B = Bsat

(coth

3H

a− a

3H

)+ µsatH

The coth function has three degrees of freedom which are set by the coef-ficients Bsat, a and µsat. These coefficients can by found e.g. using a least-squares fitting procedure. Calculating the derivate of B with respect to Hyields

dB

dH= Bsat

(tanh2 (H/a)− 1

a tanh2 (H/a)− a

H2

)+ µsat

With the relationships Φ = B · A and F = H · l the control signal Pdiff for thevariable permeance is easily derived from the equation above.

ReferencesS. El-Hamamsy and E. Chang, “Magnetics modeling for computer-aided de-

sign of power electronics circuits,” in Power Electronics Specialists Confer-ence, vol. 2, pp. 635–645, 1989.

R. W. Buntenbach, “Improved circuit models for inductors wound on dissipa-tive magnetic cores,” in Proc. 2nd Asilomar Conf. Circuits Syst., PacificGrove, CA, Oct. 1968, pp. 229–236 (IEEE Publ. No. 68C64-ASIL).

R. W. Buntenbach, “Analogs between magnetic and electrical circuits,” inElectron. Products, vol. 12, pp. 108–113, 1969.

D. Hamill, “Lumped equivalent circuits of magnetic components: the gyrator-capacitor approach,” in IEEE Transactions on Power Electronics, vol. 8,pp. 97–103, 1993.

D. Hamill, “Gyrator-capacitor modeling: A better way of understanding mag-netic components,” in APEC Conference Proceedings pp. 326–332, 1994.

156

6

Mechanical Modeling

One-dimensional mechanics describe the mechanical interaction between bod-ies that have exactly one degree of freedom. A translational body (or Mass)can move along a single axis, and a rotational body (or Inertia) can rotatearound a single axis. With this limitation one-dimensional mechanical sys-tems can be modeled similarly to electrical systems using simple analogiesthat are listed in the following table.

Electrical and Mechanical Analogies

Electrical Translational Rotational

Voltage Speed Angular speed

Current Force Torque

Capacitor Body (mass) Body (moment of inertia)

Inductor Spring Spring

Resistor Damper Damper

Transformer Lever Gear

Switch Clutch Clutch

6 Mechanical Modeling

Flanges and Connections

The two mechanical subdomains use separate connectors: a translationalflange and a rotational flange . You can draw connections between flangesof the same type. By creating branch connections you can connect more thantwo flanges. Flanges that are connected to each other have the same displace-ment (i.e. position or angle), and the connection will exert whatever force isnecessary in order to maintain this relationship.

Body components (i.e. the translational Mass and the rotational Inertia) havetwo rigidly connected flanges so that the two systems shown below are equiva-lent:

Equivalent connections of three translational bodies

Force/Torque Flows and Sign Conventions

As the above table of electrical and mechanical analogies suggests, forces ortorques acting on components are modeled as flows from one flange to another.The direction of a positive flow is indicated either with a dot next to a flangeor with an arrow in the component icon.

Force and torque flows must be balanced, i.e. the sum of all flows towardsa component must generally be zero, but there are two exceptions to thisrule:

• Reference components only have a single flange so balancing is not possiblefor a single instance. Reference components in fact represent connectors ofa single, global reference frame, and it is the net flow towards this referenceframe that must be zero.

• Body components have an implicit internal connection to the global refer-ence frame. A positive net flow towards a body causes the body to acceleratein the positive direction.

158

Positions and Angles

In this context it is important to note that the positive direction does not nec-essarily correlate with the graphical orientation of the components. For in-stance, the schematic shown below models the equation

F1 + F2 = m · a

i.e. both forces accelerate the body in the positive direction, even though in theschematic the two forces might appear to oppose each other.

Mass and two forces

Positions and Angles

In contrast to other modeling environments, PLECS does not generally useflange displacements as state variables in the component equations in orderto avoid having to solve Index-2 problems. Instead, absolute or relative dis-placements are only calculated when required e.g. in a hard-stop componentor if you explicitly measure them using a sensor. The displacements are thencalculated by integrating the corresponding absolute or relative speed.

Initial Conditions

As with all integrators, displacement meters must be provided with properinitial values. PLECS allows you to specify these initial values directly in thecomponents that require them or indirectly via neighboring components. Forthis purpose, most components have an initial displacement parameter thatdefaults to an empty string, which means ”don’t care” or ”don’t know”.

At simulation start, PLECS will automatically calculate required but un-known initial values from the values that you have provided. An error will beflagged if you do not supply enough data to determine required initial values.On the other hand, an error will also be flagged, if you provide too much andinconsistent data.

The example shown below models a body with mass m that is subject to agravitational force m · g and suspended from a spring. The spring is initiallyunstretched (dx0 = 0) but its equilibrium displacement x0 is not specified.

159


Spring and mass

If the model is run as is, PLECS will flag an error because it does not haveenough data to calculate this equilibrium length and the initial value of theposition sensor. To fix this, you can specify any one of the following three pa-rameters:

1 the initial value x0 of the position sensor

2 the initial position x0 of the body

3 the equilibrium displacement x0 of the spring

Note that you may specify more than one of the above values, but if you do so,the settings must be consistent.

Angle Wrapping

When calculating angles by integrating angular speed, care must be taken toavoid numerical problems during longer simulations. For this reason, PLECSautomatically wraps the integral in the interval between −π and +π when youmeasure an absolute angle with a position sensor that has one flange inter-nally connected to the rotational reference frame. Note that relative angles– measured with a position sensor that has two accessible flanges – are notwrapped because you can wind a torsion spring by more than one turn.

Ideal Clutches

Analogous to its ideal electrical switches, PLECS features ideal mechani-cal clutches that engage and disengage instantaneously. While engaged theymake an ideal rigid connection between their flanges and while disengagedthey transmit zero force (or torque).

160

Ideal Clutches

Inelastic Collisions

PLECS permits you to connect an ideal clutch between two bodies and engagethe clutch while they move (or rotate) at different speeds. PLECS models suchan event as a perfectly inelastic collision and calculates the common speed af-ter the collision based on the conservation law of angular momentum so thate.g.

ω+ =J1ω

−1 + J2ω

−2

J1 + J2

where J1 and J2 are the moments of inertia of the two bodies, ω−1 and ω−2 arethe two angular speeds prior to the collision and ω+ is the common angularspeed after the collision.

It is important to note that kinetic energy is lost during an inelastic colli-sion even though the clutch is ideal and lossless. Assuming for simplicity thatJ1 = J2 = J so that ω+ = 1

2 (ω−1 + ω−2 ), the kinetic energy of the system beforeand after the collision is for example

E− =1

2J(ω−1

2+ ω−2

2)

E+ =1

2(2J) ω+2

=1

4J(ω−1 + ω−2

)2⇒ E− − E+ =

1

4J(ω−1 − ω

−2

)2

This is demonstrated using the simple example shown below consisting of twobodies with the same inertia J = 1kg·m2

rad2 . One initially rotates with ω−1 = 1 rads

while the other is stationary ω−2 = 0. There is no friction or external torqueacting on the bodies. When the clutch engages at t = 1s, the two bodies imme-diately rotate with the same speed ω+ = .5 rad

s and the total kinetic energy ofthe system reduces instantaneously from .5J to .25J.

It is interesting to compare this response with that of a more detailed model,in which the clutch is modeled with a finite damping coefficient when en-gaged. Additionally the two shafts connecting the bodies with the clutch are

161


0

0.5

1Sp

eed

/ rad

s−

1

0 1 2

0

0.5

Mec

h. e

nerg

y / J

t / s

Inelastic collision with ideal clutch

assumed to have a certain elasticity and damping coefficient. The correspond-ing schematic and plots are shown below; for comparison the response fromthe idealized model is superimposed with dashed lines.

The damping coefficients and spring constants have been exaggerated so thatthere is visible swinging. Note however, that after the transients have settled,the two bodies rotate at the same common speed as in the idealized model.Likewise, the final mechanical energy stored in the system is the same as inthe idealized model.

162

Ideal Clutches

0

0.5

1Sp

eed

/ rad

s−

1

0 1 2

0

0.5

Mec

h. e

nerg

y / J

t / s

Inelastic collision with non-ideal clutch and elastic shafts

163


164

7

Analysis Tools

Steady-State Analysis

Many specifications of a power electronic system are often given in terms ofsteady-state characteristics. A straight-forward way to obtain the steady-stateoperating point of a system is to simulate over a sufficiently long time-spanuntil all transients have faded out. The drawback of this brute-force approachis that it can be very time consuming. Usually a system has time constantsthat are much longer than the switching period. This applies in particular toelectro-thermal models.

Algorithm

The steady-state analysis of a periodic system is based on a quasi-Newtonmethod with Broyden’s update. In this approach the problem is formulatedas finding the roots of the function

f(x) = x− FT (x)

where x is an initial vector of state variables and FT (x) is the final vector ofstate variables one period T later.

Evaluating f(x) or FT (x) therefore involves running a simulation from tstart totstart + T . The period, T , must be the least common multiple of the periods ofall sources (signal or electrical) in the model.

The above problem can be solved iteratively using

xk+1 = xk − J−1k · f(xk) , Jk =

∂f(x)

∂x

∣∣∣∣xk

The Jacobian J is calculated numerically using finite differences. If n is thenumber of state variables, calculating the Jacobian requires n + 1 simulation

7 Analysis Tools

runs where each state variable in turn is slightly perturbed and the differencebetween the perturbed and unperturbed solution is computed to obtain onecolumn of J:

ji =f(x + ∆xi)− f(x)

|∆xi|, i = 1 . . . n

Because this is computationally expensive, only the first Jacobian is actuallycomputed this way. In subsequent iterations, the Jacobian is updated usingBroyden’s method, which does not require any additional simulations.

The convergence criterion of the iterations is based on the requirement thatboth the maximum relative error in the state variables and the maximum rel-ative change from one iteration to the next are smaller than a certain limitrtol:∣∣∣∣xk+1 − xk

xk

∣∣∣∣ < rtol and|fi(x)|

max |xi(τ)|< rtol for all i = 1, . . . , n

A steady-state analysis comprises the following steps:

1 Simulate until the final switch positions after one cycle are equal to the ini-tial switch positions. This is called a circular topology.

2 Calculate the Jacobian matrix J0 for the initial state.

3 Iterate until the convergence criterion is satisfied. If during the iterationsthe final switch positions after one cycle differ from the initial switch posi-tions, go back to step 1.

Fast Jacobian Calculation for Thermal States

To reduce the number of simulation runs and thus save computation timePLECS can calculate the Jacobian matrix entries pertaining to thermal statesdirectly from the state-space matrices rather than using finite differences.

There is a certain error involved with this method since it neglects the feed-back from the thermal states to the electrical states (or Simulink states).While this will not affect the accuracy of the final result of the steady-stateanalysis it may slow down the convergence. Normally, however, the overallperformance will be much faster than calculating the full Jacobian matrix.

The calculation method is controlled by the parameter JacobianCalculation(see below).

166


Non-periodic Case

If the operating point of the system is defined as non-periodic (DC), a variantof the algorithm described above is performed. As in the periodic case, Newtoniterations are executed to find the steady-state. Here, the algorithm searchesfor the roots of the function

f(x) = x

i.e. the time derivative of the vector of state variables x. Since no simulationhas to be performed to compute f , the full Jacobian J is calculated in each it-eration. The convergence criterion remains the same as for the periodic case.

Limitations

Hidden state variables

In PLECS Blockset, the steady-state analysis depends on the fact that amodel can be completely initialized with the InitialState parameter of thesim command. However, certain Simulink blocks that clearly have an inter-nal memory do not store this memory in the state vector and therefore can-not be initialized. Among these blocks are the Memory block, the Relay block,the Transport Delay block and the Variable Transport Delay block. If a modelcontains any block with hidden states, the algorithm may be unable to find asolution.

State variable windup

If the effect of a state variable on the system is limited in some way but thestate variable itself is not limited, it might wind up towards infinity. In thiscase the algorithm may fail to converge or return a false solution. In order toavoid this problem you should limit the state variable itself, e.g. by enablingthe Limit output checkbox of an Integrator block.

Reference

D. Maksimovic, "Automated steady-state analysis of switching power convert-ers using a general-purpose simulation tool", Proc. IEEE Power Electron-ics Specialists Conference, June 1997, pp. 1352-1358.

167

7 Analysis Tools

AC Analysis

The AC Analysis uses the Steady-State Analysis to compute the transfer func-tion of a periodic system at discrete analysis frequencies. For each frequencythe following steps are executed:

1 Apply a sinusoidal perturbation to the system under study.

2 Find the periodic steady-state operating point of the perturbed system.

3 Extract the system response at the perturbation frequency using Fourieranalysis.

The perturbation frequencies are defined by specifying the sweep range andthe number of points to be placed within this range on a linear or logarithmicscale.

Note The period length of the perturbed system is the least common multipleof the unperturbed system period and the perturbation period. In order to keepthis number and thus the simulation time small the algorithm may slightly ad-just the individual perturbation frequencies.

In PLECS Standalone, the operating point can be defined as “non-periodic”(DC). In this case, no sweep is executed, but the Bode plot is computed di-rectly from the state space matrices at the steady-state.

Impulse Response Analysis

An alternative and faster method to determine the open loop transfer functionof a system is the Impulse Response Analysis. Instead of perturbing a systemwith sinusoidal stimuli of different frequencies, one at a time, a single impulseis applied when the system is in steady state. The system transfer functioncan then be calculated very efficiently over a wide frequency range (from zeroto half the system frequency) by computing the Laplace transform of the tran-sient impulse response.

Algorithm

The impulse response analysis is performed in three steps:

168


1 Find the steady-state operating point of the system under study.

2 Apply a perturbation in form of a discrete impulse for the duration of oneperiod.

3 Calculate the Laplace transform of the transient impulse response.

Compensation for Discrete Pulse

Theoretically, in order to compute the system transfer function from theLaplace transform of the system response, the system must be perturbed witha unit Dirac impulse (also known as delta function). This is not practical fornumerical analysis, so the algorithm applies a finite rectangular pulse instead.For transfer functions such as the line-to-output transfer function or the out-put impedance this can be compensated for by dividing the Laplace transformof the system response by the Laplace transform of the rectangular pulse.This is achieved by setting the parameter Compensation for discrete pulseto discrete pulse, which is the default.

However, when calculating control-to-output transfer functions that involvethe duty cycle of a switched converter, the rectangular input signal interfereswith the sampling of the modulator. In this case the compensation type shouldbe set to external reference. This causes the Impulse Response Analysisblock to have two input signals that should be connected as shown in this fig-ure.

m15/28

ScopeModulator

PWM

[m_ac]

[m_ac]

Control to OutputTransfer Function

PLECSImpulse Resp.

Analysis

Circuit

s

i_L

v_load

PLECSCircuit

Finally, you can set the compensation type to none which means that the com-puted transfer function is taken as is. Use this setting if the modulator usesregular sampling and the sampling period is identical to the system period.

Reference

D. Maksimovic, "Automated small-signal analysis of switching power convert-ers using a general-purpose time-domain simulator", Proc. Applied Power

169

7 Analysis Tools

Electronics Conference, February 1998.

Multitone Analysis

The Multitone Analysis is similar to an AC Analysis. Again the response ofthe system to a small perturbation signal is analysed. However, instead ofmultiple sinusoidal signals of different frequencies, only one multitone signalis applied. It is composed of several sinusoidal signals and therefore containsall investigated frequencies at once.

The multitone signal is computed as

u(t) =

√2

N

N∑k=1

sin

(2πkfbt+

π(k − 1)2

N

),

where N is the number of tones and fb the base frequency. In PLECS, theuser can control the amplitude of the perturbation signal by a factor that ismultiplied to u(t).

Algorithm

The simulation is divided into two phases. It is assumed that the systemreaches its steady-state in the first phase of duration Ti. In the second phaseof duration Tb = 1/fb, the response of the system is recorded for the Fourieranalysis.

The Multitone Analysis performs these steps:

1 Perform an unperturbed simulation of length Ti + Tb. Record the systemresponse during Tb in y0.

2 Perform a simulation of the same length and perturbed by u. Record thesystem response during Tb in y.

3 Compute the Fourier transforms U of u and Y of y − y0.

4 Compute the transfer function as G = Y/U .

170

Multitone Analysis

Remarks

The Multitone Analysis is faster than the AC Analysis because it only needsto compute the response to one signal instead of a set of signals for each fre-quency. On the other hand, the analysed frequencies are restricted to mul-tiples of the base frequency. Since the Multitone Analysis does not use theSteady-State Analysis, it still works in cases where the Steady-State Analy-sis fails, provided Ti is large enough.

Note that the lengths of the y0 and y vectors are different in general. To com-pute the difference y − y0, the missing values are linearly interpolated.

References

S. Boyd, "Multitone signals with low crest factor", IEEE Transactions of Cir-cuits and Systems, Vol. CAS-33, No. 10, 1986.

C. Fernández, P. Zumel, A. Fernández-Herrero, M. Sanz, A. Lázaro, A. Bar-rado, "Frequency response of switching DC/DC converters from a singlesimulation in the time domain", Applied Power Electronics Conferenceand Exposition (APEC), 2011 Twenty-Sixth Annual IEEE , March 2011.

171

7 Analysis Tools

Usage in PLECS Standalone

In PLECS Standalone all analyses are managed in the Analysis Tools Dialogshown below. To open the dialog, select Analysis tools... from the Simula-tion menu of the schematic editor.

The left hand side of the dialog window shows a list of the analyses that arecurrently configured for the model. To add a new analysis, click the buttonmarked + below the list and select the desired analysis type. To remove thecurrently selected analysis, click on the button marked -. You can reorder theanalyses by clicking and dragging an entry up and down in the list.

The right hand side of the dialog window shows the parameter settings of thecurrently selected analysis. Each analysis must have a unique Description.The other parameters available for the different analysis types are describedfurther below.

The button Start analysis/Abort analysis starts the currently selectedanalysis or aborts the analysis that is currently running. The button Showlog/Hide log shows or hides a log window that displays the progress of ananalysis and diagnostic messages.


Operating pointThis parameter defines whether the operating point of the system is peri-odic or non-periodic (DC). If it is periodic, the system period can be speci-

172


fied using the next parameter.

System periodThe system period is the least common multiple of the periods of allsources (signal or electrical) in the model. If the parameter setting doesnot reflect the true system period or an integer multiple thereof, the anal-ysis will yield meaningless results or fail to converge altogether. A settingof 0 is equivalent to defining the system as non-periodic. When set to auto,which is the default, PLECS will try to determine the system period auto-matically.

Simulation start timeThe start time tstart to be used in the transient simulation runs. Simula-tions run from tstart to tstart + T , where T is the system period specifiedabove. The default is 0.

Show final cycles / timespanThe number of steady-state cycles for which a transient simulation is runat the end of an analysis. Or, if the simulation is non-periodic, the dura-tion of the final transient simulation. The default is 1.

Number of init. cyclesThe number of cycle-by-cycle simulations to be performed before the New-ton iterations are started. When an analysis fails to converge because thestarting point was too far from the steady-state solution, this parametercan help to get better starting conditions. The default is 0.

Termination toleranceThe relative error bound. The analysis continues until both the maximumrelative error in the state variables and the maximum relative changefrom one iteration to the next are smaller than this bound for each statevariable.

Max. number of iterationsMaximum number of Newton iterations allowed.

Rel. perturbation for JacobianRelative perturbation of the state variables used to calculate the approxi-mate Jacobian matrix.

Jacobian calculationControls whether Jacobian matrix entries for thermal state variables arecalculated via finite differences (full) or directly from the state-space ma-trices (fast). The default is fast.

173

7 Analysis Tools

AC Sweep

In order to perform an AC sweep, you need to insert a Small Signal Perturba-tion (see page 648) and a Small Signal Response (see page 649) block in orderto define the points at which the perturbation is injected and the response ismeasured. The Small Signal Gain (see page 647) block can be used to obtainthe closed loop gain of a feedback loop.At the end of an analysis, a scope window will open and display the Bode dia-gram of the transfer function. You can also open the scope manually by click-ing one Show results button.Operating point

This parameter defines whether the operating point of the system is peri-odic or non-periodic (DC). If it is periodic, the system period can be speci-fied using the next parameter.

System periodThe system period is the least common multiple of the periods of allsources (signal or electrical) in the model. If the parameter setting doesnot reflect the true system period or an integer multiple thereof, the anal-ysis will yield meaningless result or fail to converge altogether. A systemperiod of 0 is equivalent to defining the system as non-periodic. When setto auto, which is the default, PLECS will try to determine the system pe-riod automatically.

Frequency rangeA vector containing the lowest and highest perturbation frequency.

AmplitudeA vector containing the amplitudes of the perturbation signal at the low-est and highest frequency. The amplitudes at intermediate frequencies areinterpolated linearly. If a scalar is entered, the amplitude will be constantfor all frequencies.

PerturbationThe Small Signal Perturbation block that will be active during the analy-sis. All other perturbations blocks will output 0.

ResponseThe Small Signal Response block that will record the system response dur-ing the analysis.

Simulation start timeThe start time tstart to be used in the transient simulation runs. Simula-tions run from tstart to tstart + T , where T is the system period specifiedabove. The default is 0.

174


Frequency scaleSpecifies whether the sweep frequencies should be distributed on a linearor logarithmic scale.

Number of pointsThe number of automatically distributed frequencies.

Additional frequenciesA vector specifying frequencies to be swept in addition to the automati-cally distributed frequencies.

For a description of the steady-state options please refer to “Steady-StateAnalysis” (on page 172).


In order to perform an impulse response analysis, you need to insert a SmallSignal Perturbation (see page 648) and a Small Signal Response (see page649) block in order to define the points at which the perturbation is injectedand the response is measured.At the end of an analysis, a scope window will open and display the Bode dia-gram of the transfer function. You can also open the scope manually by click-ing one Show results button.For a description of the parameters please refer to “AC Sweep” (on page 174).In an impulse response analysis, the computational effort for an individualfrequency is very cheap. Therefore, the parameter Additional frequencies isomitted; instead, the Number of points can be set to a large value in orderobtain smooth curves.

Multitone Analysis

In order to perform a multitone analysis, you need to insert a Small SignalPerturbation (see page 648) and a Small Signal Response (see page 649) blockin order to define the points at which the perturbation is injected and the re-sponse is measured.At the end of an analysis, a scope window will open and display the Bode dia-gram of the transfer function. You can also open the scope manually by click-ing one Show results button.Initial simulation period

The duration of an initial simulation performed before the response ismeasured. It is assumed that during this period, the system reaches its

175

7 Analysis Tools

steady state. The total simulation duration will be the sum of this parame-ter and one period of the base frequency signal.

Frequency rangeA vector containing the lowest and highest frequency of the multitone per-turbation signal. The highest frequency is rounded up towards the nextinteger multiple of the lowest frequency.In a multitone analysis, the frequencies are linearly spaced (see “Multi-tone Analysis” (on page 170)). Since the Bode plot has a logarithmic scale,PLECS thins out the higher frequency values to accelerate the analysis.If the lowest and highest frequencies are far apart, i.e. separated by sev-eral orders of magnitude, the multitone analysis may become slow. Onereason is that the simulation times become long and the simulation stepssmall, since they depend on the lowest and highest frequencies, respec-tively. You may try to speed up the analysis by specifying intermediatefrequency values, i.e. by entering a frequency vector with more than twoelements. Each intermediate value must be greater than ten times thepreceding value. If the frequency vector contains n elements, n − 1 sepa-rate multitone analyses are performed and the Bode plot is composed ofthe respective results. Since the frequency range of each individual multi-tone analysis is smaller than the overall range, the total time needed maybecome shorter.

AmplitudeThe amplitude of the perturbation signal. Note that the actual perturba-tion signal may have a sightly different amplitude due to its compositionfrom the different tones.

PerturbationThe Small Signal Perturbation block that will be active during the analy-sis. All other perturbations blocks will output 0.

ResponseThe Small Signal Response block that will record the system response dur-ing the analysis.

Extraction of State-Space Matrices

PLECS allows you to extract the state-space matrices describing the linearportion of a circuit model for a given combination of switch positions. Thecommands used for this purpose are listed below. These commands can beused both in a Simulation Script (see page 245) and on the Octave console. Ineach of the commands circuit is the name of the circuit model.

176


names = plecs('get', circuit, 'StateSpaceOrder');

returns a struct containing the names of the components associated with thecircuit model’s inputs, outputs, states and switches.

plecs('set', circuit, 'SwitchVector', switchpos);

sets the vector of switch positions for the subsequent analysis to switchpos.

t = plecs('get', circuit, 'Topology');

returns a struct with the state-space matrices A, B, C, D and I for the vec-tor of switch positions specified by the previous command. The matrix I is theidentity matrix if all electrical states are independent. Otherwise it specifiesthe relationship between the dependent variables.

Above commands can also be invoked via the XML-RPC interface (see page252) using an analogous syntax.

Application Example

The demo model BuckOpenLoop implements the buck converter shown below.It operates at a switching frequency of 100 kHz with a fixed duty-cycle of15/28. To run a transient simulation from zero initial conditions, select Startfrom the Simulation menu.

Cm

ScopePWM

sm~+m' ~

vo'

V: 28 R: 3V

A

FETD

L: 50e-6

C: 500e-6 I ~i'

To view the analyses configured in this model select Analysis tools... fromthe Simulation menu. The only periodic source in the model is the carriersignal used in the modulator. Hence, the parameter System period for allanalyses is specified as T = 1/100 kHz = 10−5 s.

177

7 Analysis Tools

Steady-State Operation

To view the steady-state operation of the converter, select Steady-State Anal-ysis from the list and click on Start analysis. After the analysis has foundthe periodic operating point, the scope will show five steady-state cycles.

Control-to-Output Transfer Function

For the calculation of the control-to-output transfer function, a small pertur-bation needs to be added to the modulation index. This is done with the SmallSignal Perturbation block m', which has the Show feed-through input set-ting enabled. The system output in this case is defined as the output voltageof the converter. The output signal of the voltmeter is therefore connected tothe Small Signal Response block vo'.

To calculate the transfer function using the AC Sweep, select Control to Out-put TF (AC Sweep) from the list and click on Start analysis. The analysissweeps the frequency range between 100 Hz and 50 kHz. 21 points are placedlogarithmically within this range; to obtain a smoother output, additional datapoints are generated between 800 and 1400 Hz.

To calculate the transfer function using the Impulse Response Analysis, selectControl to Output TF (Impulse Response) from the list and click on Startanalysis.

Output Impedance

For the calculation of the output impedance, a small perturbation current isinjected into the converter output using a current source that is controlledby the Small Signal Perturbation block i’ and the output voltage responseis measured. As above, two analyses have been configured that calculate theimpedance using the AC Sweep and the Impulse Response Analysis.

Loop Gain

The demo model BuckClosedLoop implements the controlled buck convertershown below. A PID controller regulates the output voltage to 15 volts.

For the calculation of the voltage loop gain, the Small Signal Gain block LoopGain Meter has been inserted into the feedback path. If you look under themask of the Small Signal Gain, you can see how the block both injects a smallperturbation and measures the system response.

178


15Vref

Scope+−

PWM

sm

~vo'

V: 28 R: 3V

A

FETD

L: 50e-6

C: 500e-6

PIDController

Verr m

Loop Gain Meter~

I ~i'

To calculate the loop gain, select Analysis tools... from the Simulationmenu, then choose Closed Loop Gain from the list of analyses and clickStart analysis.

179

7 Analysis Tools

Usage in PLECS Blockset

In PLECS Blockset, you configure analyses by copying the appropriate blocksfrom the Analysis Tools library in PLECS Extras into your model.


To perform a steady-state analysis, copy the Steady-State Analysis block (seepage 801) into your model. An analysis can be run interactively from the blockdialog or via a MATLAB command. The calling syntax is

plsteadystate(block);

where block is the Simulink handle or the full block path of the Steady-StateAnalysis block. The block handle or path can be followed by parameter/valuepairs. Otherwise, the settings specified in the block dialog are used.

The following table lists the parameters of the Steady-State Analysis block.The Parameter column shows the parameter names to be used with theplsteadystate command. The Description column indicates whether andwhere you can set the value in the dialog box. Parameters that are not acces-sible in the dialog box can be modified using the set_param command.

Steady-State Analysis Parameters

Parameter Description

TimeSpan For a fixed system period, the period length;this is the least common multiple of the pe-riods of independent sources in the system.For a variable system period, the maximumtime span during which to look for a triggerevent marking the end of a period. Set by theSystem period length/Max simulation timespan field.

TStart Simulation start time. Set by the Simulationstart time field.

180


Steady-State Analysis Parameters (contd.)


Tolerance Relative error tolerance used in the conver-gence criterion. Set by the Termination tol-erance field.

MaxIter Maximum number of iterations allowed. Set bythe Max number of iterations field.

Display Specifies the level of detail of the diagnosticmessages displayed in the command window(iteration, final, off). Set by the Displaydrop-down list.

HideScopes Hide all Simulink scope windows during ananalysis in order to save time.

HiddenStates Specifies how to handle Simulink blocks with‘hidden’ states, i.e. states that are not stored inthe state vector (error, warning, none). Set bythe Hidden model states drop-down list.

FinalStateName Name of a MATLAB variable used to store thesteady-state vector at the end of an analysis.Set by the Steady-state variable field.

NCycles Number of steady-state cycles that should besimulated at the end of an analysis. Set by theShow steady-state cycles field.

JPert Relative perturbation of the state variablesused to calculate the approximate Jacobianmatrix.

JacobianCalculation Controls the way the Jacobian matrix is calcu-lated (full, fast). The default is fast.

NInitCycles Number of cycle-by-cycle simulations thatshould be performed before the actual steady-state analysis. This parameter can be used toprovide the algorithm with a better startingpoint. The default is 0.

181

7 Analysis Tools

These examples show how to run analyses for the block Steady State in themodel mymodel:

plsteadystate('mymodel/Steady State');

starts an analysis using the parameters specified in the dialog box.

plsteadystate('mymodel/Steady State','TStart',0,...'FinalStateName','x0');

plsteadystate('mymodel/Steady State','TStart',1,...'FinalStateName','x1');

performs two analyses with different start times and assigns the resultingsteady-state vectors to two different variables x0 and x1. This is useful e.g.if the model has a reference signal with a step change and you want to deter-mine the steady state before and after the change.

AC Sweep / Loop Gain Analysis

To perform an AC sweep, copy the AC Sweep block (see page 790) into yourmodel. The block outputs a perturbation signal, which must be injected intothe system. The system response must be fed back into the block input.

To perform a loop gain analysis, copy the Loop Gain Analysis (AC Sweep)block (see page 796) into your model and insert it into the path of a feedbackloop.

An analysis can be run interactively from the block dialogs or via a MATLABcommand. The calling syntax is

placsweep(block);

where block is the Simulink handle or the full block path of the AC Sweep orLoop Gain Analysis block. The block handle or path can be followed by param-eter/value pairs. Otherwise, the settings specified in the block dialog are used.

The following table lists the parameters of the AC Sweep and Loop Gain Anal-ysis blocks. The Parameter column shows the parameter names to be usedwith the placsweep command. The Description column indicates whetherand where you can set the value in the dialog box. Parameters that are notaccessible in the dialog box can be modified using the set_param command.

182


AC Analysis Parameters


TimeSpan Period length of the unperturbed system. Set bythe System period length field.


FreqRange Range of the perturbation frequencies. Set by theFrequency sweep range field.

FreqScale Specifies whether the sweep frequencies should bedistributed on a linear or logarithmic scale. Setby the Frequency sweep scale field.

NPoints Number of data points generated. Set by theNumber of points field.

InitialAmplitude Perturbation amplitude at the first perturbationfrequency. Set by the Amplitude at first freqfield.

Method Method used for obtaining the periodic steady-state operating point of the perturbed system:Brute force simulation - start from modelinitial state, Brute force simulationstart from unperturbed steady state,Steady-state analysis - start from modelinitial state, Steady-state analysis - startfrom unperturbed steady state.Set by the Method drop-down list.

Tolerance Relative error tolerance used in the convergencecriterion. Set by the Termination tolerance field.

MaxIter Maximum number of iterations allowed. Set by theMax number of iterations field.

Display Specifies the level of detail of the diagnosticmessages displayed in the command window(iteration, final, off). Set by the Display drop-down list.

183

7 Analysis Tools

AC Analysis Parameters (contd.)


HideScopes Hide all Simulink scope windows during an analy-sis in order to save time.

HiddenStates Specifies how to handle Simulink blocks with ’hid-den’ states, i.e. states that are not stored in thestate vector (error, warning, none). Set by theHidden model states drop-down list.

OutputName Name of a MATLAB variable used to store thetransfer function at the end of an analysis. Set bythe Output variable field.

BodePlot Plot a Bode diagram of the transfer function at theend of an analysis. Set by the Plot Bode diagramdrop-down list.

JPert Relative perturbation of the state variables used tocalculate the approximate Jacobian matrix.

NInitCycles If a steady-state analysis is used to obtain thestarting point of the ac analysis (see parameterMethod above), this parameter specifies the num-ber of cycle-by-cycle simulations that should beperformed before the steady-state analysis. Thisparameter can be used to provide the algorithmwith a better starting point. The default is 0.

These examples show how to run analyses for the block AC Sweep in the modelmymodel:

placsweep('mymodel/AC Sweep');

starts an analysis using the parameters specified in the dialog box.

placsweep('mymodel/AC Sweep','TStart',0,...'OutputName','T0');

placsweep('mymodel/AC Sweep','TStart',1,...'OutputName','T1');

184


performs two analyses with different start times and assigns the resultingtransfer functions to two different variables T0 and T1. This is useful e.g. ifthe model has a reference signal with a step change and you want to deter-mine the transfer function before and after the change.


To perform an impulse response analysis, copy the Impulse Response Analysisblock (see page 794) into your model. The block outputs a perturbation sig-nal, which must be injected into the system. The system response must be fedback into the block input.

An analysis can be run interactively from the block dialogs or via a MATLABcommand. The calling syntax is

plimpulseresponse(block);

where block is the Simulink handle or the full block path of the Impulse Re-sponse Analysis block. The block handle or path can be followed by parame-ter/value pairs. Otherwise, the settings specified in the block dialog are used.

The following table lists the parameters of the Impulse Response Analy-sis block. The Parameter column shows the parameter names to be usedwith the plimpulseresponse command. The Description column indicateswhether and where you can set the value in the dialog box. Parameters thatare not accessible in the dialog box can be modified using the set_param com-mand.

Impulse Response Analysis Parameters


TimeSpan Period length of the unperturbed system. Set by theSystem period length field.

TStart Simulation start time. Set by the Simulation starttime field.


185

7 Analysis Tools

Impulse Response Analysis Parameters (contd.)


FreqScale Specifies whether the sweep frequencies should be dis-tributed on a linear or logarithmic scale. Set by theFrequency sweep scale field.

NPoints Number of data points generated. Set by the Numberof points field.

Perturbation Perturbation amplitude of the discrete impulse. Set bythe Perturbation field.

Compensation Specifies whether and how the effect of the sam-pling should be compensated (none, discrete pulse,external reference). Set by the Compensation fordiscrete pulse drop-down list.

Tolerance Relative error tolerance used in the convergence cri-terion of the initial steady-state analysis. Set by theTermination tolerance field.

MaxIter Maximum number of iterations allowed during theinitial steady-state analysis. Set by the Max numberof iterations field.

Display Specifies the level of detail of the diagnostic messagesdisplayed in the command window (iteration, final,off). Set by the Display drop-down list.

HideScopes Hide all Simulink scope windows during an analysis inorder to save time.

HiddenStates Specifies how to handle Simulink blocks with ’hidden’states, i.e. states that are not stored in the state vector(error, warning, none). Set by the Hidden modelstates drop-down list.

OutputName Name of a MATLAB variable used to store the trans-fer function at the end of an analysis. Set by the Out-put variable field.

186


Impulse Response Analysis Parameters (contd.)



JPert Relative perturbation of the state variables used tocalculate the approximate Jacobian matrix.

NInitCycles Number of cycle-by-cycle simulations that should beperformed before the initial steady-state analysis. Thisparameter can be used to provide the algorithm with abetter starting point. The default is 0.

Multitone / Loop Gain Analysis

To perform a multitone analysis, copy the Multitone Analysis block (see page799) into your model. The block outputs a perturbation signal, which must beinjected into the system. The system response must be fed back into the blockinput.To perform a loop gain analysis, copy the Loop Gain Analysis (Multitone)block (see page 797) into your model and insert it into the path of a feedbackloop.An analysis can be run interactively from the block dialogs or via a MATLABcommand. The calling syntax is

plmultitone(block);

where block is the Simulink handle or the full block path of the MultitoneAnalysis or Loop Gain Analysis block. The block handle or path can be fol-lowed by parameter/value pairs. Otherwise, the settings specified in the blockdialog are used.The following table lists the parameters of the Multitone Analysis and LoopGain Analysis blocks. The Parameter column shows the parameter namesto be used with the placsweep command. The Description column indicateswhether and where you can set the value in the dialog box. Parameters thatare not accessible in the dialog box can be modified using the set_param com-mand.

187

7 Analysis Tools

Multitone Analysis Parameters



Amplitude Amplitude of the perturbation signal. Set by theAmplitude field.


Display Specifies the level of detail of the diagnosticmessages displayed in the command window(iteration, final, off). Set by the Display drop-down list.

HideScopes Hide all Simulink scope windows during an analy-sis in order to save time.

OutputName Name of a MATLAB variable used to store thetransfer function at the end of an analysis. Set bythe Output variable field.


Extraction of State-Space Matrices

PLECS allows you to extract the state-space matrices describing the linearportion of a circuit model for a given combination of switch positions. Thecommands used for this purpose are listed below. In each of the commandscircuit is the full Simulink path of a PLECS Circuit block.

names = plecs('get', circuit, 'StateSpaceOrder');

returns a struct containing the names of the components associated with thecircuit model’s inputs, outputs, states and switches.

plecs('set', circuit, 'SwitchVector', switchpos);

188


sets the vector of switch positions for the subsequent analysis to switchpos.

t = plecs('get', circuit, 'Topology');

returns a struct with the state-space matrices A, B, C, D and I for the vec-tor of switch positions specified by the previous command. The matrix I is theidentity matrix if all electrical states are independent. Otherwise it specifiesthe relationship between the dependent variables.

Application Example

This section demonstrates the application of the analysis tools in PLECSBlockset for the design of the regulated buck converter system operating ata switching frequency of 100 kHz shown in the figure below. The convertershall supply a regulated 15 volts to a resistive load at a nominal load currentof 5 amperes.

v_ref

15

ScopeModulator

PWM

Compensator

PID

Circuit

s

i_L

v_load

PLECSCircuit

FETDV: 28

s1

L: 50e−6 i_L1

C: 500e−6

A

v_load2

V R: 3

The examples used in this section follow the design example in [Erickson],chapter 9. They have been implemented in the demo models plBuckSweep,plBuckImpulseResponse and plBuckLoop.


We first examine the open-loop behavior of the system. In order to get thedesired output voltage we need to apply a fixed duty-cycle of Vout/Vsrc =15V/28V. You can verify this by using the Steady-State Analysis block to ob-tain the steady-state waveform of the output voltage.For this purpose you copy the block into the model and double-click it to openthe dialog box. The parameter System period length is already set to thecorrect value, i.e. 1e-5. Set the parameter Show steady-state cycles to e.g.10 so that you can more easily check that the system is indeed in the steadystate when the analysis finishes. Then click on Start analysis. The algorithmshould converge after the first iteration, and the scope should show the wave-form in the figure below.

189

7 Analysis Tools

0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1

x 10−4

14.998

15

15.002

v load

/ V

t / s

Steady-state output voltage

AC Sweep

Open-loop control-to-output transfer function In order to determine thecontrol-to-output transfer function you need to perturb the steady-state duty-cycle and measure the corresponding perturbation of the output voltage. Thisis achieved by connecting an AC Sweep block as shown below. The block out-put is the perturbation signal; it is added to the steady-state duty cycle. Theblock input is connected to the load voltage signal.

The initial amplitude of the perturbation is set to 1e-3 which is approx.2/1000 of the duty cycle. We want to sweep a frequency range between 100Hzand 50kHz with a few extra points between 800Hz and 1200Hz. This isachieved by setting the parameter to [100 800:50:1200 50000]. As ex-pected, the resulting bode plot of the transfer function shows a double poleat f0 = 1/(2π

√LC) ≈ 1kHz and a dc gain of G0 = 28V ≈ 29dB.

Open-loop output impedance Although not required for the compensatordesign we will now calculate the output impedance for demonstration pur-poses. To do so we need to inject a small ac current into the converter outputand measure the resulting perturbation of the output voltage. We thereforeconnect a controlled current source in parallel with the load resistor as shownbelow. This current source is controlled by the perturbation signal of the ACSweep block. The block input is again connected to the load voltage signal.The average steady-state output current is 5 amperes; we therefore set theinitial perturbation amplitude to 1e-2.


Alternatively you can determine the open-loop transfer functions using theImpulse Response Analysis block as shown in the figure below. In this anal-ysis method the calculation of an individual output point is relatively inex-pensive; we therefore set the number of points to 300 and extend the sweep

190


m

15/28

ScopeModulator

PWM

[m_ac]

[m_ac]


PLECSAC Sweep

Circuit

s

i_L

v_load

PLECSCircuit

FETDV: 28

s1

L: 50e−6 i_L1

C: 500e−6

A

v_load2

V R: 3

−40

−20

0

20

40|G

| / d

B

102

103

104

−180

−90

0

∠ G

/ °

f / Hz

Open-loop control-to-output transfer function

range to [10 50000]. In order to compensate for the discrete rectangularpulse used to perturb the system, we choose the setting external referencefor the control-to-output transfer function and discrete pulse for the outputimpedance.

Loop Gain Analysis

Compensator settings The compensator should attain a crossover fre-quency of fc = 5kHz. At this frequency the open-loop control-to-output transferfunction has a phase of nearly −180. It should be lifted by 52 to get a peakovershoot of 16%. This is achieved using a PD compensator with a zero atfz = 1.7kHz, a pole at fp = 14.5kHz and a dc gain of k = (fc/f0)2

√fz/fp/G0 ≈

0.3. For a zero stationary error a PI compensator with an inverted zero atfZ = 500Hz is added.

The compensator is implemented as shown above. The compensator output islimited to 0.1. . . 0.9. In order to prevent windup problems during the steady-state analysis the integrator is limited to the same range.

191

7 Analysis Tools

m

15/28Scope

Output Impedance

PLECSAC Sweep

Modulator

PWM

[i_ac]

[i_ac]

Circuit

i_ac

s

i_L

v_load

PLECSCircuit

V: 28

i_L1

v_load2

s2

i_ac1R: 3V

A

FETD

L: 50e−6

C: 500e−6

−40

−20

0

|Z| /

dBΩ

102

103

104

−90

0

90

∠ Z

/ °

f / Hz

Open-loop output impedance

m15/28

ScopeModulator

PWM

[m_ac]

[m_ac]


PLECSImpulse Resp.

Analysis

Circuit

s

i_L

v_load

PLECSCircuit

m15/28 Scope

Output Impedance

PLECSImpulse Resp.

Analysis

Modulator

PWM

[i_ac]

[i_ac]

Circuit

i_ac

s

i_L

v_load

PLECSCircuit

Using the Impulse Response Analysis block

Loop gain The gain of the closed control loop is measured by inserting theLoop Gain Analysis block into the loop path. A good place is the feedback pathas shown below. The average steady-state load voltage is 15 volts; the initialperturbation amplitude is therefore chosen as 1e-2. The convergence of theinitial steady-state analysis can be accelerated by pre-charging the capacitorto its average steady-state voltage.

The resulting bode plot of the closed-loop gain shown in the figure below. Alsoshown are the open-loop control-to-output function with a dashed line and thePID compensator transfer function with a dotted line. As you can see, the de-sign goals for crossover frequency and phase margin have been reached.

192


State-Space Averaging

Another method for obtaining the open-loop transfer functions of a circuit is atechnique called state-space averaging. This topic is fairly complex and couldeasily fill a book of its own. This manual therefore assumes that you are fa-miliar with the concept and just highlights how to use PLECS in the process.The code examples given here are collected in the demo M-file plSSADemo.

The small-signal ac model of a dc converter operating in continuous conduc-tion mode (CCM) is described by the equation system

d

dtx(t) = Ax(t) + Bu(t) +

(A1 −A2)x + (B1 −B2)u

m(t)

y(t) = Cx(t) + Du(t) +

(C1 −C2)x + (D1 −D2)um(t)

where the quantities x(t), u(t), y(t) and m(t) are small ac variation aroundthe operating point x, u, y and m. The averaged state-space matrices A, B, C

PI CompensatorPD Compensator

Out1

num(s)

den(s)Saturation1

s−K−

0.3In1

−20

0

20

40

|G| /

dB

101

102

103

104

105

−90

0

90

∠ G

/ °

f / Hz

PID compensator and transfer function

193

7 Analysis Tools

and D are defined as

A = mA1 + (1− m)A2

B = mB1 + (1− m)B2

C = mC1 + (1− m)C2

D = mD1 + (1− m)D2

where the subscript 1 denotes the interval when the switch is conducting andthe diode blocking, and the subscript 2 denotes the interval when the switch isblocking and the diode conducting.

You can use PLECS to calculate the different matrices A1, A2 etc. and fromthese the various transfer functions. Using the buck converter from the previ-ous example, the first step is to determine the internal order of the switches:

load_system('plBuckSweep');

v_ref

15

ScopeModulator

PWM

Loop Gain

PLECSLoop GainAnalysis

Compensator

PID

Circuit

s

i_L

v_load

PLECSCircuit

FETDV: 28

s1

L: 50e−6 i_L1

C: 500e−6

A

v_load2

V R: 3

−40

−20

0

20

40

|G| /

dB

102

103

104

−180

−90

0

90

∠ G

/ °

f / Hz

Closed-loop gain

194


names = plecs('get', 'plBuckSweep/Circuit', ...'StateSpaceOrder');

names.Switches

ans ='Circuit/FET''Circuit/D'

Next you retrieve the state-space matrices for the two circuit topologies:

plecs('set', 'plBuckSweep/Circuit', 'SwitchVector', [1 0]);t1 = plecs('get', 'plBuckSweep/Circuit', 'Topology');

plecs('set', 'plBuckSweep/Circuit', 'SwitchVector', [0 1]);t2 = plecs('get', 'plBuckSweep/Circuit', 'Topology');

Now you can calculate the averaged state-space matrices:

m = 15/28;A = t1.A*m + t2.A*(1-m);B = t1.B*m + t2.B*(1-m);C = t1.C*m + t2.C*(1-m);D = t1.D*m + t2.D*(1-m);

Output impedance The output impedance is the transfer function from astate-space input (the current source I_ac) to a state-space output (the volt-meter Vm). Such a transfer function is given by:

Y(s)

U(s)= C(sI− A)−1B + D

Since the circuit model is a MIMO (multi-input multi-output) model, you needto specify the indices of the proper elements in the input and output vector.You can identify them using the fields Inputs and Outputs of the struct namesthat you retrieved earlier:

names.Inputs

ans ='Circuit/V_dc''Circuit/I_ac'

195

7 Analysis Tools

names.Outputs

ans ='Circuit/Vm''Circuit/Am''Circuit/FET''Circuit/FET''Circuit/D''Circuit/D'

So, the output impedance is the transfer function from input 2 to output 1. Ifyou have the Control System Toolbox you can now display the Bode diagram:

bode(ss(A,B(:,2),C(1,:),D(1,2)), 2*pi*100, 2*pi*50000)

The figure below shows the output impedance drawn with a solid line. Thedots represent the data points returned by the ac sweep.

−40

−20

0

|Z| /

dBΩ

102

103

104

−90

0

90

∠ Z

/ °

f / Hz

Open-loop output impedance

Open-loop control-to-output transfer function The control-to-outputtransfer function describes the effect of the small ac variation m on the sys-tem outputs. From the small-signal ac model equations we find that

Y(s)

M(s)= Cco(sI−Aco)−1Bco + Dco

196


with

Aco = A

Bco =− (A1 −A2)A−1B + (B1 −B2)

u

Cco = C

Dco =− (C1 −C2)A−1B + (D1 −D2)

u

Note that Bco and Dco are column vectors since there is only one scalar inputvariable, m. The vector u is a column vector consisting of the dc input voltageand the small-signal ac current.

This leads to the following program code:

u = [28; 0];

B_co = (-(t1.A-t2.A)*(A\B)+(t1.B-t2.B))*u;D_co = (-(t1.C-t2.C)*(A\B)+(t1.D-t2.D))*u;

bode(ss(A,B_co,C(1,:),D_co(1)), 2*pi*100, 2*pi*50000)

The figure below shows the control-to-output transfer function drawn with asolid line. The dots represent the data points returned by the ac sweep.

−40

−20

0

20

40

|G| /

dB

102

103

104

−180

−90

0

∠ G

/ °

f / Hz

Open-loop control-to-output transfer function

197

7 Analysis Tools

Reference

R.W. Erickson, D. Maksimovic, "Fundamentals of Power Electronics, 2ndEd.", Kluwer Academic Publishers, 2003.

198

8

C-Scripts

C-Scripts provide a powerful and comfortable mechanism for implementingcustom control blocks in the C programming language. They enable you to in-teract with the solver engine on a level very similar to that of built-in blocks.

Typical applications where C-Scripts are useful include:

• Implementing complex non-linear and/or piecewise functions. These wouldotherwise need to be modeled with complex block diagrams that are hard toread and maintain.

• Implementing modulators or pulse generators that require exact but flexibletime step control.

• Incorporating external C code, e.g. for a DSP controller, into a simulationmodel.

There is no need to manually compile any code or even to install a compiler. Abuilt-in compiler translates your C code on-the-fly to native machine code andlinks it dynamically into PLECS.

A detailed description of how C-Scripts work is given in the following section.For a quick start you can also have a look at the C-Script examples furtherbelow.

How C-Scripts Work

Since C-Scripts interact so closely with the solver engine, a good understand-ing of how a dynamic system solver works is advantageous. This is describedin detail in the chapter “How PLECS Works” (on page 27).

8 C-Scripts

C-Script Functions

A C-Script block, like any other control block, can be described as a mathe-matical (sub-)system having a set of inputs u, outputs y and state variables xc,xd that are related to each other by a set of equations:

y = foutput(t, u, xc, xd)

xnextd = fupdate(t, u, xc, xd)

xc = fderivative(t, u, xc, xd)

A C-Script block has an individual code section for each of these functions andtwo additional sections for code to be executed at the start and terminationof a simulation. The C code that you enter in these sections is automaticallywrapped into C functions; the actual function interface is hidden to allow forfuture extensions. You can access block variables such as inputs, outputs andstates by means of special macros that are described further below. The solvercalls these C functions as required during the different stages of a simulation(see “Model Execution” on page 33).

Start Function

The start function is called at the beginning of a simulation. If the C-Scripthas continuous or discrete state variables they should be initialized here usingthe macros ContState(i) and DiscState(i).

Output Function

The output function is called during major and minor time steps in orderto update the output signals of the block. The block inputs and outputsand the current time can be accessed with the macros InputSignal(i, j),OutputSignal(i, j) and CurrentTime.

If you need to access any input signal during the output function call, youmust check the Input has direct feedthrough box on the Setup pane of theC-Script dialog. This flag influences the block execution order and the occur-rence of algebraic loops (see “Block Sorting” on page 31).

200

How C-Scripts Work

In general, output signals should be continuous and smooth during minortime steps; discontinuities or sharp bends should only occur during major timesteps. Whether or not the call is made for a major time step can be inquiredwith the IsMajorStep macro. For details see “Modeling Discontinuities” below.

Note It is not safe to make any assumptions about the progression of time be-tween calls to the output function. The output function may be called multipletimes during the same major time step, and the time may jump back and forthbetween function calls during minor time steps. Code that should execute ex-actly once per major time step should be placed in the update function.

Update Function

If the block has discrete state variables, the update function is called onceduring a major time step after the output functions of all blocks have beenprocessed. During this call, the discrete state variables should be updated us-ing the DiscState macro.

Derivative Function

If the block has continuous state variables, the derivative function is calledduring the integration loop of the solver. During this call, the continuous statederivatives should be updated using the ContDeriv macro.

Derivatives should be continuous and smooth during minor time steps; discon-tinuities or sharp bends should only occur during major time steps. For detailssee “Modeling Discontinuities” below.

Terminate Function

The terminate function is called at the end of a simulation – regardless ofwhether the simulation stop time has been reached, the simulation has beenstopped interactively, or an error has occurred. Use this function to free anyresources that you may have allocated during the start function (e.g. file han-dles, memory etc.).

201

8 C-Scripts

Store Custom State Function

This function is called at the end of a simulation before the terminate func-tion. Use this function to store any custom values which are needed to restorethe state of the C-Script. Continuous and discrete states are automaticallystored. Use the macros WriteCustomStateDouble, WriteCustomStateInt andWriteCustomStateData to serialize your data.

Restore Custom State Function

This function is called after the start function and before the first call ofthe output function. The continuous and discrete states have already beenrestored at this point. Use this function to initialize your block with apreviously stored custom state. Use the macros ReadCustomStateDouble,ReadCustomStateInt and ReadCustomStateData to deserialize your data andSetErrorMessage to report any issues to the user during restoring.

Code Declarations

This code section is used for global declarations and definitions (that is, globalin the scope of the C-Script block). This is the place to include standard li-brary headers (e.g. math.h or stdio.h) and to define macros, static variablesand helper functions that you want to use in the C-Script functions.You can also include external source files. The directory containing the modelfile is automatically added to the included search path, so you can specify thesource file path relative to the model file.

Modeling Discontinuities

If the behavior of your C-Script block changes abruptly at certain instants,you must observe the following two rules in order to obtain accurate re-sults:

1 If the time, at which a discontinuity or event occurs, is not known a prioribut depends on the block inputs and/or states, you must define one or morezero-crossing signals, which aid the solver in locating the event. Failure todo so may result in a jitter on the event times.

2 During minor time steps, continuous state derivatives and output signalsmust be continuous and smooth functions. Failure to observe this may leadto gross numerical integration errors.

202

How C-Scripts Work

Defining Zero-crossing Functions

To define zero-crossing signals, register the required number of signals onthe Setup pane of the C-Script dialog. In the output function, use the macroZCSignal(i) to assign values to the individual zero-crossing signals dependinge.g. on the block inputs or states or the current simulation time. The solverconstantly monitors all zero-crossing signals of all blocks. If any one signalchanges its sign during the current integration step, the step size is reducedso that the next major time step occurs just after the first zero-crossing. (Seealso “Event Detection Loop” on page 34.)

For instance, to model a comparator that must change its output when theinput crosses a threshold of 1, you should define the following zero-crossingsignal:

ZCSignal(0) = InputSignal(0, 0) - 1.;

Without the aid of the zero-crossing signal, the solver might make one step ata time when the input signal is e.g. 0.9 and the next step when the input sig-nal has already increased to e.g. 1.23, so that the C-Script block would changeits output too late.

With the zero-crossing signal, and provided that the input signal is continu-ous, the solver will be able to adjust the step size so that the C-Script outputwill change at the correct time.

Note If a zero-crossing signal depends solely on the simulation time, i.e. if anevent time is known a priori, it is recommended to use a discrete-variable sam-ple time and the NextSampleHit macro instead. (See “Discrete-Variable SampleTime” below.)

Keeping Functions Continuous During Minor Time Steps

The solver integrates the continuous state derivatives over a given interval(i.e. the current time step) by evaluating the derivatives at different times inthe interval. It then fits a polynomial of a certain order to approximate theintegral. (See also “Integration Loop” on page 34.) The standard Dormand-Prince solver, for instance, uses 6 derivative evaluations and approximates theintegral with a polynomial of 5th order.

203

8 C-Scripts

Obviously, the derivative of this polynomial is again a polynomial of one orderless. On the other hand, to approximate a discontinuous or even just a non-smooth derivative function, a polynomial of infinite order would be required.This discrepancy may lead to huge truncation errors. It is therefore vital todescribe the continuous state derivatives as piecewise smooth functions andmake sure that only one subdomain of these functions is active throughoutone integration step.

The output signal of a C-Script block might be used as the input signal of anintegrator and thus might become the derivative of a continuous state vari-able. Therefore, output signals should be described as piecewise smooth func-tions as well.

Returning to the example of the comparator above, the complete output func-tion code should look like this:

if (IsMajorStep)if (InputSignal(0, 0) >= 1.)

OutputSignal(0, 0) = 1.;else

OutputSignal(0, 0) = 0.;

ZCSignal(0) = InputSignal(0, 0) - 1.;

The condition if (IsMajorStep) ensures that the output signal can onlychange in major steps. It remains constant during the integration loop re-gardless of the values that the input signal assumes during these minor timesteps. The zero-crossing signal, however, is also updated in minor time stepsduring the event detection loop of the solver.

Sample Time

A C-Script block can model a continuous system, a discrete system, or evena hybrid system having both continuous and discrete properties. Dependingon which kind of system you want to model, you need to specify an appropri-ate Sample time on the Setup pane of the C-Script dialog. The sample timedetermines at which time steps (and at which stages) the solver calls the dif-ferent C-Script functions.

204

How C-Scripts Work

Continuous Sample Time

Blocks with a continuous sample time (setting 0 or [0, 0]) are executed atevery major and minor time step. You must choose a continuous sample timeif

• the C-Script models a continuous (or piecewise continuous) function,• the C-Script has continuous states or,• the C-Script registers one or more zero-crossing signals for event detection.

Semi-Continuous Sample Time

Blocks with a semi-continuous sample time (setting [0, -1]) are executed atevery major time step but not at minor time steps. You can choose a semi-continuous instead of a continuous sample time if the C-Script produces onlydiscrete output values and does not need zero-crossing signals.

Discrete-Periodic Sample Time

Blocks with a discrete-periodic sample time (setting Tp or [Tp, To]) are exe-cuted at regularly spaced major time steps. The sample period Tp must be apositive real number. The sample offset To must be a positive real number inthe interval 0 ≤ To < Tp; it may be omitted if it is zero.

The time steps, at which the output and update functions are executed, arecalculated as n · Tp + To with an integer n.

Discrete-Variable Sample Time

Blocks with a discrete-variable sample time (setting -2 or [-2, 0]) are exe-cuted at major time steps that are specified by the blocks themselves.

In a C-Script you assign the time, when the block should be executed next,to the macro NextSampleHit. This can be done either in the output or updatefunction. At the latest, after the update function call, the NextSampleHit mustbe greater than the current simulation time. Otherwise, the simulation will beaborted with an error.

If a C-Script only has a discrete-variable sample time, the time of the firstsample hit must be assigned in the start function. Otherwise, the C-Scriptwill never be executed. During the start function, the simulation start timeis available via the macro CurrentTime.

205

8 C-Scripts

Note For discrete-variable sample times, PLECS Blockset can control thetime steps taken by the Simulink solvers only indirectly by using an internalzero-crossing signal. Therfore, the actual simulation time at a discrete-variablesample hit may be slightly larger than the value that was specified as the nextsample hit.

The solvers of PLECS Standalone, however, can evaluate the sample hit re-quests directly and are therefore guaranteed to meet the requests exactly.

Multiple Sample Times

If you want to model a hybrid system you can specify multiple sample times indifferent rows of an n× 2 matrix. For example, if your C-Script has continuousstates but you must also ensure that it is executed every 0.5 seconds with anoffset of 0.1 seconds, you would enter [0, 0; 0.5, 0.1].

You can use the macro IsSampleHit(i) in the output and update functions inorder to inquire which of the registered sample times has a hit in the currenttime step. The index i is a zero-based row number in the sample time matrix.In the above example, if your C-Script should perform certain actions only atthe regular sampling intervals, you would write

if (IsSampleHit(1))// this code is only executed at t == n*0.5 + 0.1

To access the sample times during execution of the C-Script, use the macrosSampleTimePeriod(i) and SampleTimeOffset(i). In the case of inheritedsample times, the actual resolved values are returned, not [-1, 0] (see “Sam-ple Times” on page 38).

User Parameters

If you want to implement generic C-Scripts that can be used in different con-texts, you can pass external parameters into the C functions.

206

How C-Scripts Work

External parameters are entered as a comma-separated list in the Param-eters field on the Setup pane of the C-Script dialog. The individual param-eters can be specified as MATLAB expressions and can reference workspacevariables. They must evaluate to real scalars, vectors, matrices, 3d-arrays orstrings.

Within the C functions you can inquire the number of external parame-ters with the macro NumParameters. The macros ParamNumDims(i) andParamDim(i, j) return the number of dimensions of the individual parame-ters and their sizes. In the case of strings, 1 and the length of the string mea-sured in C characters (char) is returned, respectively. Note that because thestrings are UTF-8 encoded, the length returned by ParamDim(i, j) may belarger than the number of unicode characters in the string.

To access the actual parameter values, use the macro ParamRealData(i, j),where j is a linear index into the data array. For example, to access the valuein a certain row, column and page of a 3d-array, you write:

int rowIdx = 2;int colIdx = 0;int pageIdx = 1;int numRows = ParamDim(0, 0);int numCols = ParamDim(0, 1);int elIdx = rowIdx + numRows*(colIdx + numCols*pageIdx);double value = ParamRealData(0, elIdx);

To access string parameters, use the macro ParamStringData(i). For exam-ple, to use the second parameter as an error message, you may write:

SetErrorMessage(ParamStringData(1));

Runtime Checks

If the box Enable runtime checks on the Setup pane of the C-Script dialogis checked, C-Script macros that access block data (e.g. signals values, states,parameters etc.) are wrapped with protective code to check whether an arrayindex is out of range. Also, the C-Script function calls are wrapped with codeto check for solver policy violations such as modifying states during minortime steps or accessing input signals in the output function without enablingdirect feedthrough.

207

8 C-Scripts

These runtime checks have a certain overhead, so once you are sure that yourC-Script is free of errors you can disable them in order to increase the simu-lation speed. This is not recommended, however, because in this case accessviolations in your C-Script may cause PLECS to crash.

Note The runtime checks cannot guard you against access violations causedby direct memory access.

C-Script Examples

This section presents a collection of simple examples that demonstrate thedifferent features of the C-Script and that you can use as starting points foryour own projects. Note that the functionality of the example blocks is alreadyavailable from blocks in the PLECS library.

A Simple Function – Times Two

The first example implements a block that simply multiplies a signal with 2.This block is described by the following system equation:

y = foutput(t, u, xc, xd) = 2 · u

Block Setup The block has one input, one output, no states and no zero-crossing signals. It has direct feedthrough because the output function de-pends on the current input value. Since the output signal is continuous (pro-vided that the input signal is) the sample time is also continuous, i.e. [0, 0]or simply 0.

Output Function Code

OutputSignal(0, 0) = 2.*InputSignal(0, 0);

In every major and minor time step, the output function retrieves the currentinput value, multiplies it with 2 and assigns the result to the output.

208

C-Script Examples

Discrete States – Sampled Delay

This example implements a block that samples the input signals regularlywith a period of one second and outputs the samples with a delay of one pe-riod. Such a block is described by the following set of system equations:

y = foutput(t, u, xc, xd) = xd

xnextd = fupdate(t, u, xc, xd) = u

Remember that in a major time step the solver first calls the block outputfunction and then the block update function.

Block Setup The block has one input and one output. One discretestate variable is used to store the samples. The block does not have directfeedthrough because the input signal is not used in the output function butonly in the update function. The sample time is [1, 0] or simply 1.


OutputSignal(0, 0) = DiscState(0);

Update Function Code

DiscState(0) = InputSignal(0, 0);

Continuous States – Integrator

This example implements a block that continuously integrates the input sig-nal and outputs the value of the integral. Such a block is described by the fol-lowing set of system equations:

y = foutput(t, u, xc, xd) = xc

xc = fderivative(t, u, xc, xd) = u

Block Setup The block has one input and one output. One continuous statevariable is used to integrate the input signal. The block does not have directfeedthrough because the input signal is not used in the output function butonly in the derivative function. The sample time is continuous, i.e. [0, 0] orsimply 0.


OutputSignal(0, 0) = ContState(0);

209

8 C-Scripts

Derivative Function Code

ContDeriv(0) = InputSignal(0, 0);

Event Handling – Wrapping Integrator

This examples extends the previous one by implementing an integrator thatwraps around when it reaches an upper or lower boundary (e.g. 2π and 0).Such an integrator is useful for building e.g. a PLL to avoid round-off errorsthat would occur if the phase angle increased indefinitely. This wrapping prop-erty can actually not be easily described with mathematical functions. How-ever, the C code turns out to be fairly simple.

Block Setup The block has the same settings as in the previous example.Additionally, it requires two zero-crossing signals, in order to let the solverfind the exact instants, at which the integrator state reaches the upper orlower boundary.


#define PI 3.141592653589793if (IsMajorStep)if (ContState(0) > 2*PI)

ContState(0) -= 2*PI;else if (ContState(0) < 0)

ContState(0) += 2*PI;ZCSignal(0) = ContState(0);ZCSignal(1) = ContState(0) - 2*PI;

OutputSignal(0, 0) = ContState(0);

In every major time step, if the integrator state has gone beyond the upperor lower boundary, 2π is added to or subtracted from the state so that it lieswithin the boundaries again. In every major and minor time step, the zero-crossing signals are calculated so that they become zero when the state is 0resp. 2π. Finally, the integrator state is assigned to the output.

Note, that the state must not be modified during minor time steps, becausethen the solver is either itself updating the state (while integrating it) or try-ing to find the zeros of the zero-crossing functions, which in turn depend onthe state. In either case an external modification of the state will lead to un-predictable results.

210

C-Script Examples

Derivative Function Code

ContDeriv(0) = InputSignal(0, 0);

Piecewise Smooth Functions – Saturation

This example implements a saturation block that is described by the followingpiecewise system equation:

y = foutput(t, u, xc, xd) =

1, for u ≥ 1

u, for − 1 < u < 1

−1, for 1 ≤ u

When implementing this function, care must be taken to ensure that the ac-tive output equation does not change during an integration loop in order toavoid numerical errors (see “Modeling Discontinuities” on page 202).

Block Setup The block has one input, one output and no state variables. Inorder to make sure that a major step occurs whenever the input signal crossesthe upper or lower limit, two zero-crossing signals are required.


static enum NO_LIMIT, LOWER_LIMIT, UPPER_LIMIT mode;

if (IsMajorStep)if (InputSignal(0, 0) > 1.)

mode = UPPER_LIMIT;else if (InputSignal(0, 0) < -1.)

mode = LOWER_LIMIT;else

mode = NO_LIMIT;

switch (mode)case NO_LIMIT:

OutputSignal(0, 0) = InputSignal(0, 0);break;

case UPPER_LIMIT:OutputSignal(0, 0) = 1.;break;

211

8 C-Scripts

case LOWER_LIMIT:OutputSignal(0, 0) = -1.;break;

ZCSignal(0) = InputSignal(0, 0) + 1.;ZCSignal(1) = InputSignal(0, 0) - 1.;

Ensuring that only one output equation will be used throughout an entire in-tegration step requires a static mode variable that will retain its value be-tween function calls. The active mode is determined in major time steps de-pending on the input signal. In the subsequent minor time steps, the equationindicated by the mode variable will be used regardless of the input signal.

If the step size were not properly limited and the input signal went beyondthe limits during minor time steps, so would the output signal. This is pre-vented by the two zero-crossing signals that enable the solver to reduce thestep size as soon as the input signal crosses either limit.

Note Instead of the static mode variable, a discrete state variable could alsobe used to control the active equation. In this particular application a staticvariable is sufficient because information needs to be passed only from one ma-jor time step to the subsequent minor time steps.

However, if information is to be passed from one major time step to a later ma-jor time step, a discrete state variable should be used, so that it can also bestored between multiple simulation runs.

Multiple Sample Times – Turn-on Delay

A turn-on delay is often needed for inverter controls in order to prevent short-circuits during commutation. When the input signal changes from 0 to 1, theoutput signal will follow after a prescribed delay time, provided that the inputsignal is still 1 at that time. When the input signal changes to 0, the output isreset immediately.

Block Setup The block has one input and one output. One discrete statevariable is required to store the input signal value from the previous majortime step.

212

C-Script Examples

Two sample times are needed: a semi-continuous sample time so that the in-put signal will be sampled at every major time step, and a discrete-variablesample time to enforce a major time step exactly after the prescribed delaytime. The Sample time parameter is therefore set to [0, -1; -2, 0].

As an additional feature the delay time is defined as an external user parame-ter.

Code Declarations

#include <float.h>#define PREV_INPUT DiscState(0)#define DELAY ParamRealData(0, 0)

The standard header file float.h defines two numerical constants, DBL_MAXand DBL_EPSILON, that will be needed in the output function. Additionally,two convenience macros are defined in order to make the following code morereadable.

Start Function Code

if (NumParameters != 1)SetErrorMessage("One parameter required (delay time).");return;

if (ParamNumDims(0) != 2

|| ParamDim(0, 0) != 1 || ParamDim(0, 1) != 1|| DELAY <= 0.)

SetErrorMessage("Delay time must be a positive scalar.");return;

The start function checks whether the proper number of external parameters(i.e. one) has been provided, and whether this parameter has the proper di-mensions and value.


if (InputSignal(0, 0) == 0)OutputSignal(0, 0) = 0;NextSampleHit = DBL_MAX;

else if (PREV_INPUT == 0)

213

8 C-Scripts

NextSampleHit = CurrentTime + DELAY;if (NextSampleHit == CurrentTime)

NextSampleHit = CurrentTime * (1.+DBL_EPSILON);else if (IsSampleHit(1))OutputSignal(0, 0) = 1;NextSampleHit = DBL_MAX;

If the input signal is 0, the output signal is also set to 0 according to the blockspecifications. The next discrete-variable hit is set to some large number (infact: the largest possible floating point number) because it is not needed inthis case.

Otherwise, if the input signal is not 0 but it has been in the previous timestep, i.e. if it just changed from 0 to 1, a discrete-variable sample hit is re-quested at DELAY seconds later than the current time.

Finally, if both the current and previous input signal values are nonzero andthe discrete-variable sample time has been hit, i.e. if the delay time has justpassed and the current input is still nonzero, the output is set to 1 and thenext discrete-variable hit time is again reset to the largest possible floatingpoint number.

The condition if (NextSampleHit == CurrentTime) requires special expla-nation: If DELAY is very small and the current time is very large, the sum ofthese two floating point numbers might again yield the current time valuedue to roundoff errors, which would lead to a simulation error. In this casethe next sample hit is increased to the smallest possible floating point numberthat is still larger than the current time. Admittedly, this problem will onlyoccur when the current time and the delay time are more than 15 decadesapart, and so it might be considered academic.

Update Function Code

PREV_INPUT = InputSignal(0, 0);

In the update function, the current input value is stored as the previous inputvalue for the following time step.

214

C-Script Macros

Store Custom State Code

WriteCustomStateDouble(NextSampleHit);

The previous input value is stored automatically because it is a discrete state.The NextSampleHit has to be stored in the custom state.

Restore Custom State Code

NextSampleHit = ReadCustomStateDouble();

Restore the NextSampleHit value. When the simulation starts from a storedsystem state that was stored before this block was added to the schematic, theread operation will fail and PLECS reports a runtime error.

C-Script Macros

The following table summarizes the macros that can be used in the C-Scriptfunction code sections.

C-Script Data Access Macros

Macro Type Access Description

NumInputTerminals int R Returns the number of input terminals.

NumOutputTerminals int R Returns the number of output terminals.

NumInputSignals(int i)

int R Returns the number of elements (i.e. the width) ofthe signal connected to the ith input terminal.

NumOutputSignals(int i)

int R Returns the number of elements (i.e. the width) ofthe signal connected to the ith output terminal.

NumContStates int R Returns the number of continuous states.

NumDiscStates int R Returns the number of discrete states.

NumZCSignals int R Returns the number of zero-crossing signals.

NumParameters int R Returns the number of user parameters.

CurrentTime double R Returns the current simulation time (resp. thesimulation start time during the start functioncall).

215

8 C-Scripts

C-Script Data Access Macros (contd.)


NumSampleTime int R Returns the number of sample times.

SampleTimePeriod(int i)

int R Returns the period of the ith sample time.

SampleTimeOffset(int i)

int R Returns the offset of the ith sample time.

IsMajorStep int R Returns 1 during major time steps, else 0.

IsSampleHit(int i)

int R Returns 1 if the ith sample time currently has ahit, else 0.

NextSampleHit double R/W Specifies the next simulation time when the blockshould be executed. This is relevant only forblocks that have registered a discrete-variablesample time.

InputSignal(int i, int j)

double R Returns the value of the jth element of the ithinput signal.

OutputSignal(int i, int j)

double R/W Provides access to the value of the jth element ofthe ith output signal. Output signals may only bechanged during the output function call.

ContState(int i)

double R/W Provides access to the value of the ith continu-ous state. Continuous state variables may not bechanged during minor time steps.

ContDeriv(int i)

double R/W Provides access to the derivative of the ith contin-uous state.

DiscState(int i)

double R/W Provides access to the value of the ith discretestate. Discrete state variables may not be changedduring minor time steps.

ZCSignal(int i)

double R/W Provides access to the ith zero-crossing signal.

ParamNumDims(int i)

int R Returns the number of dimensions of the ith userparameter.

216

C-Script Macros



ParamDim(int i, int j)

int R Returns the jth dimension of the ith user param-eter.

ParamRealData(int i, int j)

double R Returns the value of the jth element of the ithuser parameter. The index j is a linear indexinto the parameter elements. Indices into multi-dimensional arrays must be calculated using theinformation provided by the ParamNumDims andParamDim macros. If the parameter is a string,this macro will produce a runtime error or anaccess violation if runtime checks are disabled.

ParamStringData(int i)

char* R Returns a pointer to a UTF-8 encoded, null-terminated C string that represents the ith userparameter. If the parameter is not a string, thismacro will produce a runtime error or returnsNULL if runtime checks are disabled.

WriteCustomStateDouble(double val)

WriteCustomStateInt(int val)

WriteCustomStateData(void *data, int len)

void

void

void

W Write a custom state of type double, int or customdata with len number of bytes. Use multiple callsfor multiple values.

ReadCustomStateDouble()

ReadCustomStateInt()

ReadCustomStateData(void *data, int len)

int

double

void

R Read a custom state of type double, int or customdata with len number of bytes. Use multiple callsfor multiple values.

SetErrorMessage(char *msg)

void W Use this macro to report errors that occur in yourcode. The simulation will be terminated after thecurrent simulation step. In general, this macroshould be followed by a return statement. Thepointer msg must point to static memory.

217

8 C-Scripts



SetWarningMessage(char *msg)

void W Use this macro to report warnings. The warningstatus is reset as soon as the current C-Scriptfunction returns, so you do not need to reset itmanually. The pointer msg must point to staticmemory.

Note The values of the input and output signals are not stored in contiguousmemory. Therefore, signal values may only be accessed by using the macros, notby pointer arithmetic. For example, trying to access the second output using thefollowing code will fail:

double *output = &OutputSignal(0, 0); // not recommendedoutput[1] = 1; // fails*(output + 1) = 1; // failsOutputSignal(0, 1) = 1; // ok

Note Prefer reading and writing of custom state variables with double andint values over void* custom data. The latter can not handle the byte order(big endian, little endian) of your platform. To store a vector of doubles use thefollowing code:

// platform independent code, recommendedWriteCustomStateInt(vectorSize);for (int i = 0; i < vectorSize; ++i)

WriteCustomStateDouble(vector[i]);

// platform dependent code, not recommendedWriteCustomStateData(&vectorSize, sizeof(vectorSize));WriteCustomStateData(vector, vectorSize*sizeof(double));

218

C-Script Macros

Deprecated Macros

The macros NumInputs, NumOutputs, Input(int i) and Output(int i) aredeprecated but are still supported for C-Scripts that only have a single inputand output terminal.

219

8 C-Scripts

220

9

State Machines

State machines are a formalism for event driven systems that move fromone discrete state to another in response to discrete events. PLECS lets yougraphically create and edit state machines using common concepts such asboxes for states and curved arrows for transitions, and simulate them togetherwith a surrounding system. You can feed continuous or discrete signals into astate machine e.g. to react to external events and output discrete signals froma state machine e.g. as control signals. Actions are specified in the C program-ming language and can be associated with states and transitions. Thanks totheir built-in timer events, state machines are equally useful for implementingsupervisory controls and complex modulators.

This chapter is subdivided into three sections. The first section describes howyou interact with the graphical editor to create and modify state machines.The second section describes the semantics of a state diagram and how theyinfluence the execution of the state machine. The third section contains exam-ples that highlight different features of the state machine.

9 State Machines

Working with State Machines

To create a new state machine, copy the State Machine block from the librarybrowser into your model. A double-click on the block opens a new windowwith the state machine editor.

State machine editor window

Note The State Machine uses a distinct editor. You cannot copy block dia-gram components to a state chart or state machine elements to a block diagramschematic.

222


Working with States

A state is represented by a box with rounded corners. The name of the state isdisplayed at the top of the box in a title bar with a gray background.

State

Enter:/* enter action */

An empty state

To create a new state, click on the button in the tool bar. Move the mouseanywhere on the chart and click the left mouse button to place the new state.To cancel the operation, press the Escape key, click the right mouse button,or click anywhere outside the editor window.

To duplicate an existing state, hold down the Ctrl key (cmd key on macOS),then click on the title bar of the state and drag the mouse to a new location inthe same or a different editor window.

To change the size of a state, move the mouse over one of the four corners sothat the pointer shape becomes a diagonal arrow. Hold down the mouse but-ton, drag the mouse until the dashed box has the desired size and release themouse button.

To change the name of a state, double-click on the name and edit it on thechart. Valid state names must start with a letter and can contain only lettersand numbers. Whitespace, dashes or underscores are not allowed.

To edit the actions associated with the state, double-click on a free area withinthe state. This will open a tabbed code editor, in which you can edit the En-ter, During and Exit actions for the state. If there is enough space, the ac-tion code is also displayed on the state. By double-clicking on the code, youcan edit it directly on the chart.

Hierarchical States

A state can contain other states. The containing state is called a super-stateor compound state, the contained state, a sub-state. A state that does not con-

223

9 State Machines

tain other states is called a leaf state. Compound states do not have a Duringaction.

To create hierarchical states, resize a state so that it is large enough to fullysurround another state, then move the other state into the first state.

SuperState

SubState

A super-state containing a sub-state

Note Overlapping states are forbidden and will produce an error message atsimulation start.

Working with Transitions

Transitions are represented by curved arrows from one state to another (oralso the same) state. To create a new transition, move the mouse over oneof the edges so that the pointer shape changes to crosshairs. Hold down themouse button, drag the mouse to another edge until the pointer shape changesto double crosshairs and release the mouse button. If you release the mousebutton before the pointer shape has changed to double crosshairs, the opera-tion is cancelled.

To change the start point or end point of an existing transition, move themouse pointer over either end until the pointer shape changes to an openhand, then hold down the mouse button and drag the mouse to the new lo-cation until the pointer shape changes to a double crosshair. If you release themouse button before the pointer shape has changed to double crosshairs, theoperation is cancelled and the transition remains unchanged.

Depending on its shape, a transition may have one or more control handlesthat become visible when you hover the mouse over the transition. To change

224


the shape of the transition, hold down the mouse button over a control handleand drag it to the desired location.

A double-click on a transition opens the Transition Editor. It allows you toedit the Priority, Trigger, Condition and Action of the transition. The pri-ority is also displayed at the origin of the transition arrow, and a double-clicklets you edit it directly on the chart. Trigger, condition and action combinedform the transition label in the form Trigger [Condition] / Action, whichis shown next to the transition arrow. To change the location of the label alongthe transition, hold down the mouse button over the transition and drag it tothe desired location. By double-clicking on the label you can edit it directly onthe chart.

State1 State2

1

Trigger [Condition] / Action

A transition with labels and control handle

Default Transitions

A default transition is represented by a curved arrow originating from a blackdot. It is required on the top level of a state machine to define which stateshall become active at the beginning of a simulation. If a compound state isthe direct target of any transitions, it also requires an internal default tran-sition to define which of its sub-states shall become active when an incomingtransition is activated.

To create a new default transition, click on the button in the tool bar. Movethe mouse anywhere on the chart and click the left mouse button to place theorigin of the default transition (marked with a dot). Then, move the mouseto draw the transition to an edge of the desired target state and click the leftmouse button again. To cancel the operation, press the Escape key, click theright mouse button, or click anywhere on the chart that is not the edge of astate.

225

9 State Machines

Working with Junctions

Junctions are branching points that join or fork transitions. They are repre-sented by circles. Junctions are useful e.g. if the state that shall become activeat the beginning of a simulation depends on one or more conditions. To createa new junction, click on the button in the tool bar.

State1 State2

1 [c] 2

A junction forking a default transition

Working with Annotations

Annotations are text blocks that you can place freely on a chart for documen-tation purposes. They have no influence on the execution of the state machine.To create a new annotation, double-click on an empty space in the chart andstart typing. To move an annotation, hold down the mouse button over theannotation and drag it to the desired location. To edit an annotation, double-click on it. Choose Text alignment from the Format menu to change the textalignment of the annotation.

226


State Machine Configuration

To open the configuration editor, click on the button in the tool bar.

State machine configuration editor

Input Signals

On the Inputs tab you define input signals that are fed from the surroundingsystem into the state machine. Input signals are specified by an Input vari-able and a Type.The Input variable specifies the name with which you refer to the input sig-nal in actions or expressions. It is also displayed next to the correspondinginput terminal of the State Machine block. The variable name must be uniqueand a valid C identifier, i.e. it must start with a letter and consist of only let-ters, numbers and underscores.The Type specifies whether the signal is a continuous signal or a trigger sig-nal. For continuous and trigger signals, the actual signal value is assignedto the input variable in every time step. For trigger signals, additionally anevent with the same name will be created when the input signal changes inthe prescribed way. A rising trigger event is created in the instant when theinput signal changes from zero to non-zero, a falling trigger event is createdin the instant when the input signal changes from non-zero to zero. For trig-ger signals, a trigger symbol is also displayed next to the corresponding inputterminal of the State Machine block.

227

9 State Machines

Note Signal changes from one non-zero value to another non-zero value, e.g.from a negative value to a positive value, do not cause an event to be created.

Input signals appear on the State Machine block in the order in which theyappear in the list. Use the four buttons to the left of the list to add or removeinputs or to change their order.

Output Signals

On the Outputs tab you define output signals that are fed from the state ma-chine to the surrounding system. Output signals are defined by an Outputvariable that specifies the name with which you refer to the output signal inactions. It is also displayed next to the corresponding output terminal on theState Machine block. The variable name must be unique and a valid C iden-tifier, i.e. it must start with a letter and consist of only letters, numbers andunderscores.

Output signals appear on the State Machine block in the order in which theyappear in the list. Use the four buttons to the left of the list to add or removeoutputs or to change their order.

Constants and Variables

On these tabs you define global variables that you can use in actions or ex-pressions. They must have a unique and valid C identifier, i.e. they must startwith a letter and consist of only letters, numbers and underscores.

Constants remain constant during a simulation. The value is determined bythe Value expression, which can be any valid MATLAB or Octave expressionthat evaluates to a scalar number.

Variables can be modified by actions. They are in fact additional discretestate variables in addition to the active state of the state machine. Their ini-tial value is determined by the Initial value expression, which can be anyvalid MATLAB or Octave expression that evaluates to a scalar number.

228


C Declarations

The C declarations tab is used for global declarations and definitions. It isalso the place to include standard library headers and to define macros andstatic helper functions that you want to use in actions and expressions.

In addition to the user defined variables and functions, the following pre-defined macros can be used in actions:

Predefined Action Macros


CurrentTime double R Returns the current simulation time.

SetErrorMessage(char *msg) void W Use this macro to report errors that occurin your code. The simulation will be termi-nated after the current simulation step. Ingeneral, this macro should be followed bya return statement. The pointer msg mustpoint to static memory.

SetWarningMessage(char *msg) void W Use this macro to report warnings. Thewarning status is reset after the executionof the current simulation step, so you donot need to reset it manually. The pointermsg must point to static memory.

Note User defined variable or function names must not start with fsm_ orFSM_ because these prefixes are reserved for internal symbols in the generatedcode.

Hierarchical Transition Order

This option is only relevant for hierarchical state machines (see “HierarchicalStates” on page 223 and “Execution of Hierarchical State Machines” on page234). When both a super-state and its sub-states have outgoing transitions

229

9 State Machines

that are eligible to be taken at the same time, this option determines whethertransitions from the super-state take precedence over transitions from thesub-states or vice versa.

Sample Time

This parameter determines how the state machine is executed. The table be-low lists the valid parameter values for the different sample time types. For adetailed description of the sample time types see “Sample Time” (on page 38).

Type Value

Continuous [0, 0] or 0

Discrete-Periodic [Tp, To] or Tp Tp: Sample period, Tp > 0

To: Sample offset, 0 ≤ To < Tp

Inherited [-1, 0] or -1

With a Continuous sample time, the state machine is executed at every sim-ulation step. With a Discrete-Periodic sample time, the state machine is exe-cuted only at the regularly spaced simulation steps prescribed by the sampletime values. With an Inherited sample time, the actual sample time dependson the blocks that are connected to the State Machine block.

Animation

This option is useful for debugging your state machine. When the option ischecked, the simulation is paused whenever a transition fires, and the tran-sition path including the source and target state is highlighted. The simula-tion can be continued by selecting Continue from the Simulation menu orby pressing the Space key.

230

State Machine Execution


A state machine is executed at each simulation step that the solver makes if ithas a continuous sample time or at the specified time steps if it has a discretesample time (see also “Sample Time” on page 230). During each execution, thefollowing steps are performed:

1 The triggers and conditions of all transitions leaving the currently activestate are evaluated.

2 If a transition “fires”, i.e. if both trigger and condition are true, the StateMachine executes the Exit action of the current state followed by the tran-sition action and the Enter action of the target state.

3 If no transition fires, the During action of the current state is executed.

During each execution, at most one state change can occur, i.e. at most onetransition can be taken. Note that a transition may include one or more junc-tions (see “Compound Transitions” below).

Transition Evaluation

A transition from an active state can be taken when the specified trigger eventoccurs, provided that the condition is true at the same time. Both trigger andcondition are optional. If a transition does not specify a trigger, any event (in-cluding the mere execution of the state machine) will qualify so that the tran-sition can be taken if the condition is true. If a transition does not specify acondition, it can be taken when the trigger event occurs.

Transition Priorities

It is possible that multiple transitions from the current state are eligible tobe taken at the same time. In this case, the transition with the lower prioritynumber is given precedence.

Compound Transitions

A compound transition is a complete path from one leaf state to another (orthe same) leaf state consisting of two or more transitions joined by one ormore junctions. A compound transition can only be taken when all triggerevents specified by the individual transitions occur and all conditions specified

231

9 State Machines

by the individual transitions are true. If a compound transition is taken, theactions of all individual transitions are executed in the order of the transitionson the path.

Trigger Types

PLECS distinguishes between explicit, implicit and time-based triggers.

Explicit Trigger

An explicit trigger is an input signal that is configured as a trigger signal. Itis active whenever the input signal changes in the specified way. In the exam-ple shown below, the event E is active whenever the signal connected to theinput terminal E changes from zero to a non-zero value or from a non-zerovalue to zero. If State1 is active at this time, the transition fires.

State1 State2

1 EE

State machine with explicit trigger

Note It is expected that the input signal for an explicit trigger changes onlyat discrete instants. The signal source is responsible for registering an appro-priate zero-crossing function to enable a variable-step solver to make a simula-tion step at the instant at which the signal reaches or leaves zero.

Implicit Trigger

An implicit trigger is a relational expression. It is active when the expressionbecomes true, i.e. if it evaluated to false in the previous time step and evalu-ates to true in the current time step. If the state machine uses a continuoussample time, an implicit trigger will also register a zero-crossing function to

232


enable the solver to make a simulation step at precisely the instant at whichthe expression becomes true.

Notice the fundamental difference between an implicit trigger x > 0 and acondition [x > 0] illustrated in the example below.

State1 State2

1 x>0

State1 State2

1 [x>0]

Implicit trigger (left) versus condition (right)

In the left chart, if State1 is active, the transition will be taken only when xbecomes greater than 0. However, if x is already greater than 0 when State1becomes active, nothing will happen until x becomes less than or equal to 0and afterwards greater than 0 again. If x is a continuous signal and the statemachine uses a continuous sample time, the state machine will be executedprecisely at the instant at which x crosses 0.

In the right chart, if State1 is active, the transition will be taken at any exe-cution of the state machine if x happens to be greater than 0. If x is alreadygreater than 0 when State1 becomes active, the transition will be takenduring the next execution of the state machine. However, the execution ofthe state machine does not necessarily coincide with the instant at which xcrosses 0.

Time-Based Trigger

A time-based trigger is an expression of the form AFTER(delay), where delayis an expression that evaluates to a number. If the state machine uses a con-tinuous sample time, the trigger event will be created exactly delay secondsafter the source state of the transition was entered. If the state machine usesa discrete sample time, the trigger event will be created at the first executiontime following the delay period.

Trigger Lifetime

A trigger event is only valid in the simulation step in which it is created. Ifno transition responds to the event in this time step, the event is ignored; it isnot deferred to a subsequent execution of the state machine.

233

9 State Machines

Execution of Hierarchical State Machines

In a hierarchical state machine it is not immediately obvious which transi-tions are eligible to be taken, and which actions are executed when a transi-tion is taken.

Transition Evaluation

Only leaf states, i.e. states that do not contain other states, can be the activestate. But compound states that directly or indirectly contain the active stateare also implicitly active. When the state machine searches for a transition tobe taken, it not only evaluates the transitions leaving the active leaf state butalso those that leave the implicitly active compound states.In the case where both a transition from a super-state and a transition from asub-state are eligible to be taken, the option Hierarchical Transition Orderin the State Machine Configuration dialog determines whether the tran-sition leaving the super-state is given precedence over the transition leavingthe sub-state (top to bottom) or vice versa (bottom to top). Note that in thiscontext leaf states are considered to be at the bottom of a state hierarchy.

Execution Sequence

The two states that are directly connected by a transition are designated themain source and the main target of the transition. Notice that source stateand target state may both be compound states. The lowest compound statethat contains both source state and target state is designated the lowest com-mon ancestor (LCA) state. When the transition is taken, the following actionsare executed in this order:

1 The Exit actions of all states from the active leaf state (which may be themain source state or a sub-state of it) up to (but not including) the LCAstate are executed from bottom to top.

2 The transition action is executed.

3 The Enter actions of the state hierarchy inside the LCA state to the maintarget state are executed from top to bottom.

4 If the main target is a compound state, the action of its local default tran-sition is executed followed by the Enter action of the default transition’starget state. If necessary, this process is repeated recursively until a leafstate is reached.

234

State Machine Examples

This process is illustrated in the example below. Consider that S11 is the cur-rently active state, so both S1 and S are also implicitly active.

S

S1

Exit:S1_exit();

S11

Exit:S11_exit();

S2

Enter:S2_enter();

S21

Enter:S21_enter(); / D_action();

1 T1 / T1_action();

1 T2 / T2_action();

Execution sequence in a hierarchical state machine

Transition T1 has S1 and S2 as its main source and target. Their LCA stateis S. S2 is a compound state, and therefore after it has been entered, its in-ternal default transition causes S21 to be entered. Consequently, takingT1 causes the following sequence of actions to be executed: S11_exit();S1_exit(); T1_action(); S2_enter(); D_action(); S21_enter();.

Transition T2 has S11 and S21 as its main source and target. Their LCAstate is again S. Taking T2 causes the following sequence of actions to be exe-cuted: S11_exit(); S1_exit(); T2_action(); S2_enter(); S21_enter();.


Oven Control

This example demonstrates a simple oven control. While the oven is in oper-ation, a hysteresis type control shall keep the oven temperature within a cer-tain tolerance band around a set point by switching the heating on and off. Asa safety measure, we also want to ensure that the heating is always switchedoff when the oven door is open.

The oven is modeled with a heat source, a thermal capacitance and resistanceand a thermometer. The oven control is implemented with a state machine.Its inputs are the actual and the desired temperature and the status of theoven door, which is defined as 0 when the door is open and 1 when the door isclosed. The state machine output is the command for the oven heating. The

235

9 State Machines

ActTSetT Heating

Oven Control

Door

Open

Closed

K100

TemperatureSet Point

DoorOpen DoorClosed

NoHeating

Heating

Enter:Heating = 1;

Exit:Heating = 0;

1 !Door

1 Door

1

ActT<SetT-DeltaT

1

ActT>SetT+DeltaT

1 [!Door] 2

2

1

[ActT<SetT]

Example of a simple oven control

state machine uses a constant variable DeltaT that determines the limits ofthe tolerance band around the desired temperature.

The top-level states DoorOpen and DoorClosed reflect the actual state ofthe oven door. The default transition, which is taken at the first execution ofthe state machine, is branched with a Junction. If the door is initially openthe (i.e. Door==0), DoorOpen state will be entered, else the DoorClosedstate. Notice that the unconditional “else” branch leaving the Junction has alower precedence than the conditional branch. Afterwards, the state machinewill transition from DoorOpen to DoorClosed when Door becomes non-zeroand vice versa when the input variable Door becomes zero.

DoorClosed is a compound state. Therefore, when it is the target of a transi-

236


tion, its internal default transition will be executed, which is also branchedwith a Junction. If the actual temperature is below the set point when thedefault transition executes, the Heating state will be entered, else the No-Heating state. Afterwards, the state machine will transition from Heatingto NoHeating when the actual temperature becomes greater than the upperlimit and from NoHeating to Heating, when the actual temperature becomesless than the lower limit.

The output variable Heating is set to 1 when the Heating state is entered,and to 0 when the state is left. Notice that it does not matter whether thestate is left because the transition ActT>SetT+DeltaT is taken when the tem-perature exceeds the upper limit, or because the transition !Door is takenwhen the oven door is opened. In either case, the Exit action of Heating isexecuted and the heating is turned off.

For this state machine to work properly, the Hierarchical Transition Or-der must be set to top to bottom (which is the default). This is importantbecause a door opening event might coincide with the event that the actualtemperature exceeds the upper or lower limit. The higher-level door openingevent must take precedence over the lower-level temperature events so thatthe state machine will unconditionally transition to the DoorOpen state.

Constant On-Time Control

This example demonstrates a constant on-time control for a buck converter.The outer control loop computes a current reference from the difference be-tween the actual output voltage and the voltage reference. The inner loop usesa constant on-time control scheme as follows: When the actual current be-comes less than the reference current, the FET shall be switched on for a fixedduration. After the FET has been switched off, it must remain switched off fora minimal duration before it can switch on again.

This scheme is implemented with a state machine that has the current errorIerr as its input and the FET switching signal S as its output. The constanton-time and the minimum off-time are configured as constant variables Tonand Toff_min. The state machine has two states On and Off that are used toswitch the FET on and off, and a waiting state ReadyForOn.

When state On is entered, its Enter action will set the output signal S to 1.Exactly Ton seconds after the entry of state On, the state machine is executedagain and the timer event AFTER(Ton) becomes active. This causes the statemachine to transition to state Off and the output signal S is set to 0. Ex-actly Toff_min seconds after this event, the state machine is executed again,

237

9 State Machines

A

V

Vref

VoltageCompensator

Verr Iref Ierr S

ConstantOn-TimeControl

−+ −+

Off

Enter:S = 0;

ReadyForOn

On

Enter:S = 1;

1

Ierr>0

1 AFTER(Ton)

1

[Ierr>0]

1

AFTER(Toff_min) 2

Example of a buck converter with constant on-time control

and the timer event AFTER(Toff_min) becomes active. The transition for thistimer event is branched with a Junction. If the input signal Ierr is alreadygreater than 0 at this instant, the state machine transitions directly to stateOn again. Else, if Ierr is not greater than 0, the state machine transitions tothe waiting state ReadyForOn and remains there until Ierr becomes greaterthan 0.

The default transition targets the same Junction so that the state machinewill start in the On state or the ReadyForOn state depending on whetherIerr is greater than 0 at simulation start.

238

10

Simulation Scripts

Running simulations from a script allows you to examine the effect of varyingparameters or to post-process the simulation results to extract relevant infor-mation.

In PLECS Blockset, scripts are written in the MATLAB environment.Simulink offers a scripting interface to modify parameters and run simu-lations from a script. A detailed description of the Simulink scripting op-tions is out of the scope of this manual, please refer to the documentation forSimulink instead. PLECS Blockset offers additional commands to control theparameters of PLECS Circuits.

PLECS Standalone offers two different scripting methods:

• Scripts can be executed directly in PLECS Standalone. The scripts use asyntax which is very similar to MATLAB.

• PLECS offers an XML-RPC interface that allows any other program thatcan send XML-RPC requests to control PLECS. Many scripting languagessupport XML-RPC out of the box, for example Python or Ruby. Other script-ing language extensions for XML-RPC support are available for free on theinternet.

The scripting options for PLECS Standalone are described in section “Simula-tion Scripts in PLECS Standalone” (on page 245).

Command Line Interface in PLECS Blockset

PLECS Blockset offers a Command Line Interface (CLI) to access componentand circuit parameters from scripts or directly from the MATLAB commandline. The command syntax is

plecs('cmd', 'parameter1', 'parameter2', ...)

10 Simulation Scripts

where cmd is one of the following commands: get, set, scope, thermal, export,version, hostid.

Reading and Setting Parameters of Components

The command

plecs('get', 'componentPath')plecs('get', 'componentPath', 'parameter')

returns the value of parameter of the PLECS component indicated by the com-ponentPath as a string. If parameter is omitted a cell array with all availableparameters is returned.

plecs('set', 'componentPath', 'parameter', 'value')

sets the value of parameter of the PLECS component indicated by the compo-nentPath to value.

The special parameter ’CurrentCircuit’ can be used to query the path to thecurrent PLECS Circuit. The component path has to be an empty string:

plecs('get', '', 'CurrentCircuit')

This command can only be used in the initialization commands of subsystems.

Handling of Errors and Warnings in Initialization Commands

During the execution of mask initialization commands, error messages issuedwith the MATLAB command error are caught by PLECS and shown in theDiagnostics window. To show a warning message in the Diagnostics window,use the command


Note that the native MATLAB command warning will only print the warningmessage to the MATLAB command window.

240


Handling of Traces in Scopes

plecs('scope', 'scopePath', 'HoldTrace')plecs('scope', 'scopePath', 'HoldTrace', 'traceName')

saves the values of the last simulation run to a new trace in the scope indi-cated by the scopePath. If given and unique, traceName is used as the namefor the new trace, otherwise a default name is assigned. In both cases themethod returns the name given to the trace.

plecs('scope', 'scopePath', 'RemoveTrace', 'traceName')

removes the trace named traceName from the scope indicated by thescopePath.

plecs('scope', 'scopePath', 'ClearTraces')

clears all traces in the scope indicated by the scopePath.

plecs('scope', 'scopePath', 'SaveTraces', 'fileName')

Saves the trace data of the scope at scopePath to the file fileName for laterreference. If fileName is not an absolute path, it is interpreted relative to themodel file that contains the scope.

plecs('scope', 'scopePath', 'LoadTraces', 'fileName')

Loads the trace data from the file fileName into the scope at scopePath. If file-Name is not an absolute path, it is interpreted relative to the model file thatcontains the scope.

Retrieving Scope Cursor Data

plecs('scope', 'scopePath', 'GetCursorData', [t1 t2])plecs('scope', 'scopePath', 'GetCursorData', [t1 t2], ...

'analysis1', 'analysis2', ...)

241


returns a struct with the signal values and analysis results (as specified) forthe cursor positions t1 and t2. Valid analysis names are delta, min, max,absmax, mean, rms and thd. For more information about scope cursors see sec-tion “Cursors” (on page 99).

The return value is a struct with the two fields time and cursorData. Thefield time is the vector [t1, ts]. The field cursorData is a nested cell arraywhere the outer index corresponds to the number of plots in the scope andthe inner index corresponds to the number of signals in a plot. Each cell is astruct with the fields cursor1 and cursor2 with the signal values and addi-tional fields for the analyses that you have specified. If the scope has multipletraces, the field values are vectors with one element for each trace.

So, if the return value is stored in data, to access the signal value at cursor 2for the third trace of the second signal in the first plot, you write

data.cursorData12.cursor2(3)

Exporting Scope Data

plecs('scope', 'scopePath', 'ExportCSV', 'fileName')plecs('scope', 'scopePath', 'ExportCSV', 'fileName', [t1 t2])

saves all scope data or only the specified time range as comma separated val-ues to the text file fileName. If fileName is not an absolute path, it is inter-preted relative to the model file that contains the scope.

Exporting Scope Bitmaps

plecs('scope', 'scopePath', 'ExportBitmap', 'fileName')plecs('scope', 'scopePath', 'ExportBitmap', 'fileName', ...)

saves a bitmap of the scope to the file fileName. If fileName is not an abso-lute path, it is interpreted relative to the model file that contains the scope.The file format is determined automatically from the file extension. The file-Name argument may be followed by one or more name/value pairs to overridesettings defined in the scope as described in table “Scope Settings for BitmapExport” (on page 249).

242


Converting Thermal Descriptions

plecs('thermal', 'import', valVon, valEon, valEoff)plecs('thermal', 'import', valVon, valEon, valEoff, ...

valCauer)

imports the on-state voltage drop valVon, the switching losses valEon, valEoffand the cauer chain elements valCauer into the thermal editor. The parame-ter valVon has to be a struct with two index vectors i, T and an output matrixv. The parameters valEon and valEoff have to be structs with three index vec-tors v, i, T and an output array E. The optional argument valCauer has to bea struct with two array elements, C and R. The command can be used to im-port thermal descriptions as used in PLECS 1.x into the thermal library ofPLECS 2.x and later.

plecs('thermal', 'export', 'filename')

reads the thermal data sheet from filename and returns a struct with thefields Von, Eon, Eoff, CauerChain and Comment containing the respective datafrom the thermal data sheet. The parameter filename has to be an absolutefilename to the data sheet including the .xml extension.

plecs('thermal', 'export', 'filename', 'modelName')

reads the thermal data sheet from filename and returns a struct with thefields Von, Eon, Eoff, CauerChain and Comment containing the respective datafrom the thermal data sheet. The parameter filename has to be a relative file-name to the data sheet without the .xml extension.

Other CLI Commands

To retrieve the version information from PLECS as a string, enter

plecs('version')

To retrieve a struct with host ID and MATLAB license information, enter

plecs('hostid')

To check out a license for PLECS, enter

243


[success,message] = plecs('checkout')

If the check-out succeeds, the return variable success will be set to 1 andmessage will be an empty string. Else, success will be set to 0 and messagewill contain a detailed error message. When called without left-hand sidearguments, the command will raise a MATLAB error upon an unsuccessfulcheck-out and else execute silently.

Examples

Some examples for using the command line interface in PLECS Blockset:

plecs('get', 'mdl/Circuit1')

returns the parameters of Circuit1 in the simulink model mdl.

plecs('get', 'mdl/Circuit1', 'Name')

returns the name of Circuit1.

plecs('get', 'mdl/Circuit1', 'CircuitModel')

returns the circuit simulation method of Circuit1.

plecs('get', 'mdl/Circuit1/R1')

returns the parameters of component R1 in circuit Circuit1.

plecs('set', 'mdl/Circuit1/R1', 'R', '2')

sets the resistance of component R1 in circuit Circuit1 to 2.

plecs('export', 'mdl', true, 'exported.mdl')

exports the model mdl to the model file exported.mdl which can be openedwith the PLECS Viewer. The contents of all PLECS schematics are hidden.

data = plecs('thermal', 'export', 'Infineon/SDP04S60', ...'plSMPS_CCM')

assigns the thermal description from library element Infineon/SDP04S60 inmodel plSMPS_CCM to the variable data in the MATLAB workspace.

244

Simulation Scripts in PLECS Standalone


Simulation scripts are managed in the Simulation Scripts dialog shown below.To open the dialog, select Simulation scripts... from the Simulation menuof the schematic editor.

The left hand side of the dialog window shows a list of the scripts that arecurrently configured for the model. To add a new script, click the buttonmarked + below the list. To remove the currently selected script, click on thebutton marked -. You can reorder the scripts by clicking and dragging an en-try up and down in the list.

The right hand side of the dialog window shows the script in an editor win-dow. Each script must have a unique Description.

The button Run/Stop starts the currently selected script or aborts the scriptthat is currently running.

To make changes to the script without running it, press the Accept button.The Revert button takes back any changes that have been made after the Ac-cept or Run button was pressed.

PLECS Standalone uses GNU Octave to execute simulation scripts. TheOctave language is very similar to MATLAB. A full syntax description ofthe Octave scripting language is available in the Octave documentation,http://www.gnu.org/software/octave/doc/interpreter/.

Any console output generated by Octave will appear in the Octave Consolewindow, which you can open by choosing Show Console from the Windowmenu.

245

http://www.gnu.org/software/octave/doc/interpreter/index.html#Top

http://www.gnu.org/software/octave/doc/interpreter/index.html#Top


Overview of PLECS Scripting Extensions

In addition to generic Octave commands you can use the following commandsto control PLECS from within a simulation script.

Clearing the Octave Console

The command

plecs('clc')

clears the console window. Note that the native Octave commands clc andhome do not have any effect on the console window.

Reading and Setting Component Parameters

The command

plecs('get', 'componentPath')plecs('get', 'componentPath', 'parameter')

returns the value of parameter of the PLECS component indicated by the com-ponentPath as a string. If parameter is omitted a struct array with all avail-able parameters is returned.

plecs('set', 'componentPath', 'parameter', 'value')


The special parameter ’CurrentComponent’ can be used to query the path ofthe current component as defined above. The component path has to be anempty string:

plecs('get', '', 'CurrentComponent')

The special parameter ’CurrentCircuit’ can be used to query the name ofthe model that is currently executed. It cannot be queried interactively fromthe console. The component path has to be an empty string:

plecs('get', '', 'CurrentCircuit')

246


This command is useful for constructing a component path that does not de-pend on the model name.

A leading dot (.) in the component path is substituted with the current com-ponent or model as described in “Path Substitution” (on page 250).

Handling of Errors and Warnings in Initialization Commands

During the execution of model or mask initialization commands, error mes-sages issued with the Octave command error are caught by PLECS andshown in the Diagnostics window. To show a warning message in the Diag-nostics window, use the command


Note that the native Octave command warning will only print the warningmessage to the Octave console.


plecs('scope', 'scopePath', 'HoldTrace')plecs('scope', 'scopePath', 'HoldTrace', 'traceName')

saves the values of the last simulation to a new trace in the scope indicatedby the scopePath. If given and unique, traceName is used as the name for thenew trace, otherwise a default name is assigned. In both cases the method re-turns the name given to the trace.

plecs('scope', 'scopePath', 'RemoveTrace', 'traceName')


plecs('scope', 'scopePath', 'ClearTraces')


plecs('scope', 'scopePath', 'SaveTraces', 'fileName')

247


saves the trace data of the scope at scopePath to the file fileName for later ref-erence. If fileName is not an absolute path, it is interpreted relative to themodel file that contains the scope.

plecs('scope', 'scopePath', 'LoadTraces', 'fileName')

loads the trace data from the file fileName into the scope at scopePath. If file-Name is not an absolute path, it is interpreted relative to the model file thatcontains the scope.

The scopePath is the path to the scope within the model including the modelname, e.g. ’DTC/Mechanical’. To access Bode plots from the analysis tools,use the model name followed by ’/Analyses/’ followed by the name of theanalysis, e.g. ’BuckOpenLoop/Analyses/Control to Output TF (AC Sweep)’.A leading dot (.) in the scope path is substituted with the current componentor model as described in “Path Substitution” below.

Retrieving Scope Cursor Data

plecs('scope', 'scopePath', 'GetCursorData', [t1 t2])plecs('scope', 'scopePath', 'GetCursorData', [t1 t2], ...

'analysis1', 'analysis2', ...)

returns a struct with the signal values and analysis results (as specified) forthe cursor positions t1 and t2. Valid analysis names are delta, min, max,absmax, mean, rms and thd. For more information about scope cursors see sec-tion “Cursors” (on page 99).

The return value is a struct with the two fields time and cursorData. Thefield time is the vector [t1, ts]. The field cursorData is a nested cell arraywhere the outer index corresponds to the number of plots in the scope andthe inner index corresponds to the number of signals in a plot. Each cell is astruct with the fields cursor1 and cursor2 with the signal values and addi-tional fields for the analyses that you have specified. If the scope has multipletraces, the field values are vectors with one element for each trace.

So, if the return value is stored in data, to access the signal value at cursor 2for the third trace of the second signal in the first plot, you write

data.cursorData12.cursor2(3)

248


Exporting Scope Data

plecs('scope', 'scopePath', 'ExportCSV', 'fileName')plecs('scope', 'scopePath', 'ExportCSV', 'fileName', [t1 t2])

saves all scope data or only the specified time range as comma separated val-ues to the text file fileName. If fileName is not an absolute path, it is inter-preted relative to the model file that contains the scope.

Exporting Scope Bitmaps

plecs('scope', 'scopePath', 'ExportBitmap', 'fileName')plecs('scope', 'scopePath', 'ExportBitmap', 'fileName', ...)

saves a bitmap of the scope to the file fileName. If fileName is not an absolutepath, it is interpreted relative to the model file that contains the scope. Thefile format is determined automatically from the file extension. The fileNameargument may be followed by one or more name/value pairs to override set-tings defined in the scope as follows:

Scope Settings for Bitmap Export

Name Description

Size A two-element integer vector specifying the width andheight of the bitmap in pixels.

Resolution An integer specifying the resolution of the bitmap inpixels per inch.

TimeRange A two-element real vector specifying the time range ofthe data to be shown.

XLim A two-element real vector specifying the limits ofthe x-axis. For a normal scope this is equivalent toTimeRange.

YLim A cell array containing two-element real vectors speci-fying the limits of the y-axis of the plot(s). For a scopewith a single plot a vector may be given directly.

XLabel A string specifying the x-axis label.

249


Scope Settings for Bitmap Export (contd.)

Name Description

YLabel A cell array containing strings specifying the y-axislabels of the plot(s). For a scope with a single plot astring may be given directly.

Title A cell array containing strings specifying the title ofthe plot(s). For a scope with a single plot a string maybe given directly.

LegendPosition A string specifying the legend position. Possible valuesare none, topleft, topmiddle, topright, bottomleft,bottommiddle and bottomright.

Font A string specifying the font name to be used for thelabels and the legend.

LabelFontSize An integer specifying the label font size in points.

LegendFontSize An integer specifying the legend font size in points.

Path Substitution

If a component or scope path is a simple dot (.) or starts with a dot followedby a slash (./) the dot is substituted with the current component.

When a command is executed interactively from the console, the current com-ponent is the last component that was clicked on in the schematic editor; ifthe last click was not on a component, the current component is undefined.

During the evaluation of block parameters or mask initialization commandsthe current component is the component that is currently evaluated; duringthe evaluation of the model initialization commands it is the model itself.

Starting a Simulation

plecs('simulate')plecs('simulate', optStruct)

250


starts a simulation. The optional argument optStruct can be used to overridemodel parameters; for detailed information see section “Scripted Simulationand Analysis Options” (on page 256).

If any outports exist on the top level of the simulated model, the command re-turns a struct consisting of two fields, Time and Values. Time is a vector thateither contains the simulation time for each simulation step or the values inthe OutputTimes of the SolverOpts in the optStruct parameter. The rows of thearray Values consist of the signal values at the outports. The order of the sig-nals is determined by the port numbers.

Starting an Analysis

plecs('analyze', 'analysisName')plecs('analyze', 'analysisName', optStruct)

starts the analysis defined in the Analysis Tools dialog under the name anal-ysisName. The optional argument optStruct can be used to override model pa-rameters; for detailed information see section “Scripted Simulation and Analy-sis Options” (on page 256).

For a Steady-State Analysis, if any outports exist on the top level of the sim-ulated model, the command returns a struct consisting of two fields, Time andValues as described above. The signal values at the outports are captured af-ter a steady-state operating point has been obtained.

For an AC Sweep, an Impulse Response Analysis or a Multitone Analysis, thecommand returns a struct consisting of three fields, F, Gr and Gi. F is a vectorthat contains the perturbation frequencies of the analysis. The rows of the ar-rays Gr and Gi consist of the real and imaginary part of the transfer functionas defined in the analysis. If the command is called without a return value, ascope window will open and display the Bode diagram of the transfer function.

Example Script

The following script runs a parameter sweep by setting the variable varLto the values in inductorValues. It is used in the demo model BuckParam-Sweep.

mdlVars = struct('varL', 50e-6);opts = struct('ModelVars', mdlVars);

251


plecs('scope', './Scope', 'ClearTraces');

inductorValues = [50, 100, 200];for ix = 1:length(inductorValues)opts.ModelVars.varL=inductorValues(ix) * 1e-6;out = plecs('simulate', opts);plecs('scope', './Scope', 'HoldTrace', ...

['L=' mat2str(inductorValues(ix)) 'uH']);[maxv, maxidx] = max(out.Values(1,:));printf('Max current for L=%duH: %f at %fs\n', ...

inductorValues(ix), maxv, out.Time(maxidx));end

The first two lines create a struct ModelVars with one field, varL. The struct isembedded into another struct named opts, which will be used later to initial-ize the simulation parameters.

Inside the for-loop each value of inductorValues is assigned successively tothe structure member variable varL. A new simulation is started, the result issaved in variable out for post-processing. By holding the trace in the scope thescope output will remain visible when a new simulation is started; the scopepath uses a dot to reference the current model (see “Path Substitution” onpage 250). The name of the trace is the inductance value.

The script then searches for the peak current in the simulation results andoutputs the value and the time, at which it occurred, in the Octave Console.

XML-RPC Interface in PLECS Standalone

The XML-RPC interface allows you to control PLECS Standalone from an ex-ternal program. PLECS acts as an XML-RPC server which processes requestsfrom an XML-RPC client.

XML-RPC is a lightweight protocol that is supported by numerous scriptinglanguages. For the following description, Python 2.x syntax and script ex-cerpts are used.

Establishing an XML-RPC Connection to PLECS

The XML-RPC interface in PLECS is disabled by default. It must be enabledin the PLECS preferences before a connection can be established. The TCPport to use can also be configured in the PLECS preferences.

252


The following Python code initiates an XML-RPC connection to PLECS:

import xmlrpclibserver = xmlrpclib.Server("http://localhost:1080/RPC2")

The code assumes that PLECS is configured to use TCP port 1080 for XML-RPC. Note that the URL must end with "/RPC2", which is an XML-RPC con-vention.

Note XML-RPC connections to PLECS are only allowed from clients runningon the same machine as PLECS. Therefore, the connection should always beinitiated using localhost in the server URL.

Overview of XML-RPC Commands

Commands for PLECS start with plecs followed by a dot. In Python they areinvoked on the server object, for example

server.plecs.load("myModel.plecs")

Opening and Closing a Model

The command

plecs.load('mdlFileName')

opens the model with the given mdlFileName. The filename should containthe absolute path to the file.

The command

plecs.close('mdlName')

closes the model with the given name. The model will be closed uncondition-ally without being saved, even when changes have been made.

253


Reading and Setting Component Parameters

The command

plecs.get('componentPath')plecs.get('componentPath', 'parameter')

returns the value of parameter of the PLECS component indicated by the com-ponentPath as a string. If parameter is omitted a struct array with all avail-able parameters is returned.

plecs.set('componentPath', 'parameter', 'value')



plecs.scope('scopePath', 'HoldTrace')plecs.scope('scopePath', 'HoldTrace', 'traceName')

saves the values of the last simulation to a new trace in the scope indicatedby the scopePath. If given, traceName is used as the name for the new trace,otherwise a default name is assigned.

plecs.scope('scopePath', 'RemoveTrace', 'traceName')


plecs.scope('scopePath', 'ClearTraces')


plecs.scope('scopePath', 'SaveTraces', 'fileName')

Saves the trace data of the scope at scopePath to the file fileName for laterreference. If fileName is not an absolute path, it is interpreted relative to themodel file that contains the scope.

254


plecs.scope('scopePath', 'LoadTraces', 'fileName')

Loads the trace data from the file fileName into the scope at scopePath. If file-Name is not an absolute path, it is interpreted relative to the model file thatcontains the scope.

The scopePath is the path to the scope within the model including the modelname, e.g. ’DTC/Mechanical’. To access Bode plots from the analysis tools,use the model name followed by ’/Analyses/’ followed by the name of theanalysis, e.g. ’BuckOpenLoop/Analyses/Control to Output TF (AC Sweep)’.

Starting a Simulation

The command

plecs.simulate('mdlName')plecs.simulate('mdlName', optStruct)

starts a simulation of the model named mdlName. The optional argument opt-Struct can be used to override model parameters; for detailed information seesection “Scripted Simulation and Analysis Options” (on page 256).

If any outports exist on the top level of the simulated model, the command re-turns a struct consisting of two fields, Time and Values. Time is a vector thateither contains the simulation time for each simulation step or the values inthe OutputTimes of the SolverOpts in the optStruct parameter. The rows of thearray Values consist of the signal values at the outports. The order of the sig-nals is determined by the port numbers.

Starting an Analysis

The command

plecs.analyze('mdlName', 'analysisName')plecs.analyze('mdlName', 'analysisName', optStruct)

starts the analysis named analysisName in the model named mdlName. Theoptional argument optStruct can be used to override model parameters; fordetailed information see section “Scripted Simulation and Analysis Options”(on page 256).

255


For a Steady-State Analysis, if any outports exist on the top level of the sim-ulated model, the command returns a struct consisting of two fields, Time andValues as described above. The signal values at the outports are captured af-ter a steady-state operating point has been obtained.

For an AC Sweep or an Impulse Response Analysis, the command returns astruct consisting of three fields, F, Gr and Gi. F is a vector that contains theperturbation frequencies of the analysis. The rows of the arrays Gr and Giconsist of the real and imaginary part of the transfer function as defined inthe analysis.

Example Script

The following Python script establishes an XML-RPC connection, loads amodel and simulates it twice. The scope output from each simulation is pre-served by holding the traces in the scope.

import xmlrpclibserver = xmlrpclib.Server("http://localhost:1080/RPC2")

server.plecs.load("C:/Models/BuckParamSweep.plecs")server.plecs.scope('BuckParamSweep/Scope', 'ClearTraces')

opts = 'ModelVars' : 'varL' : 50e-6 result = server.plecs.simulate("BuckParamSweep", opts)server.plecs.scope('BuckParamSweep/Scope',

'HoldTrace', 'L=50uH')

opts['ModelVars']['varL'] = 100e-6;result = server.plecs.simulate("BuckParamSweep", opts)server.plecs.scope('BuckParamSweep/Scope',

'HoldTrace', 'L=100uH')

Scripted Simulation and Analysis Options

When you start a simulation or analysis from a Simulation Script or via XML-RPC, you can pass an optional argument optStruct in order to override param-eter settings defined in the model. This enables you to run simulations for dif-ferent scenarios without having to modify the model file.

256


The argument optStruct is a struct that may contain the fields OutputFormat,ModelVars, SolverOpts and – when starting an analysis – AnalysisOpts,which are again structs as described below.

OutputFormat The optional field OutputFormat is a string that lets youchoose whether the results of a simulation or analysis should be returnedas a plain XML-RPC struct (Plain) or in binary form using the MAT-file for-mat (MatFile). The binary format is much more efficient if the result containsmany data points, but the client may not be able to interpret it, so the defaultis Plain.

ModelVars The optional field ModelVars is a struct variable that allowsyou to override variable values defined by the model initialization commands.Each field name is treated as a variable name; the field value is assigned tothe corresponding variable. Values can be numerical scalars, vectors, matricesor 3d arrays or strings.

The override values are applied after the model initialization commands havebeen evaluated and before the component parameters are evaluated as shownin the figure below.

SolverOpts The optional field SolverOpts is a struct variable that allowsyou to override the solver settings specified in the Simulation Parameters dia-log. Each field name is treated as a solver parameter name; the field value isassigned to the corresponding solver parameter. The following table lists thepossible parameters.

Solver Options in Scripted Simulations


Solver The solver to use for the simulation. Possible values areauto, dopri, radau and discrete. See section “StandaloneParameters” (on page 111) for more details.

StartTime The start time specifies the initial value of the simulationtime variable t at the beginning of a simulation, in seconds.

TimeSpan The simulation ends when the simulation time has advancedby the specified time span.

StopTime This parameter is obsolete. It is provided to keep old scriptsworking. We strongly advise against using it in new code.

257


Solver Options in Scripted Simulations (contd.)


OutputTimes A vector of time values in seconds. If any output ports existon the top level of the simulated model, the returned valuesof the simulate command are both in the range [StartTime,StartTime + TimeSpan] and elements of this vector. Thereturned time values are strictly monotonically increasingand in case of the fixed-step solver also rounded to multiplesof the base sampling time.When OutputTimes is not specified or is an empty vector,the returned values contain all major and refined simulationsteps.

Timeout A non-negative number that specifies the maximum numberof seconds (wall-clock time) that a simulation or analysis isallowed to run. After this period the simulation or analysisis stopped with a timeout error. A value of 0 disables thetimeout.

MaxStep See parameter Max Step Size in section “Standalone Pa-rameters” (on page 111). This parameter is only evaluatedfor variable step solvers.

InitStep See parameter Initial Step Size in section “Standalone Pa-rameters” (on page 111). This parameter is only evaluatedfor variable step solvers.

FixedStep This parameter specifies the fixed time increments for thesolver and also the sample time used for the state-space dis-cretization of the physical model. It is only evaluated for thefixed step solver.

AbsTol See the description for Tolerances in section “StandaloneParameters” (on page 111).

RelTol See the description for Tolerances in section “StandaloneParameters” (on page 111).

Refine See parameter Refine factor in section “Standalone Param-eters” (on page 111).

258


Scriptstart

Model initializationcommands

Componentparameterevaluation

ModelVarsevaluation

End

Scriptexecution

Modelsimulation

plecs('simulate')plecs('analyze')

Start

Model initializationcommands

Componentparameterevaluation

ModelVarsevaluation

End

XML-RPCclient

process

Modelsimulation

plecs.simulate()plecs.analyze()

Execution order for Simulation Scripts (left) and XML-RPC (right)

AnalysisOpts For an analysis the optional field AnalysisOpts is a structvariable that allows you to override the analysis settings defined in the Anal-ysis Tools dialog. Each field name is treated as an analysis parameter name,the field value is assigned to the corresponding analysis parameter. The fol-lowing tables list the possible parameters

Analysis Options in Scripted Analyses


TimeSpan System period length; this is the least commonmultiple of the periods of independent sourcesin the system.

StartTime Simulation start time.

259


Analysis Options in Scripted Analyses (contd.)


Tolerance Relative error tolerance used in the conver-gence criterion of a steady-state analysis.

MaxIter Maximum number of iterations allowed in asteady-state analysis.

JacobianPerturbation Relative perturbation of the state variablesused to calculate the approximate Jacobianmatrix.

JacobianCalculation Controls the way the Jacobian matrix is calcu-lated (full, fast). The default is fast.

InitCycles Number of cycle-by-cycle simulations thatshould be performed before the actual analysis.This parameter can be used to provide the ini-tial steady-state analysis with a better startingpoint.

ShowCycles Number of steady-state cycles that should besimulated at the end of an analysis. This pa-rameter is evaluated only for a steady-stateanalysis.

FrequencyRange Range of the perturbation frequencies. Thisparameter is evaluated only for a small-signalanalysis.

FrequencyScale Specifies whether the sweep frequen-cies should be distributed on a linear orlogarithmic scale. This parameter is eval-uated only for a small-signal analysis.

AdditionalFreqs A vector specifying frequencies to be swept inaddition to the automatically distributed fre-quencies. This parameter is evaluated only fora small-signal analysis.

260


Analysis Options in Scripted Analyses (contd.)


NumPoints The number of automatically distributed per-turbation frequencies. This parameter is evalu-ated only for a small-signal analysis.

Perturbation The full block path (excluding the model name)of the Small Signal Perturbation block thatwill be active during an analysis. This pa-rameter is evaluated only for a small-signalanalysis.

Response The full block path (excluding the model name)of the Small Signal Response block that willrecord the system response during an anal-ysis. This parameter is evaluated only for asmall-signal analysis.

AmplitudeRange The amplitude range of the sinusoidal pertur-bation signals for an ac sweep. This parameteris evaluated only for an ac sweep.

Amplitude The amplitude of the discrete pulse pertur-bation for an impulse response analysis. Thisparameter is evaluated only for an impulseresponse analysis.

ShowResults Specifies whether to show a Bode plot aftera small-signal analysis. This parameter isevaluated only for a small-signal analysis.

261


262

11

Code Generation

As a separately licensed feature, PLECS can generate C code from a simu-lation model to facilitate real-time simulations. Code generation is subjectto certain limitations, which are described in the first section of this chapter.The next two sections describe how the code generation capabilities are usedwithin PLECS Standalone and PLECS Blockset, respectively.

Code Generation for Physical Systems

As described earlier in this manual, PLECS models physical systems usingpiecewise linear state-space equations that can be described using multiplesets of state-space matrices. For details see “Physical Model Equations” (onpage 30).

During normal simulations, PLECS calculates new sets of state-space ma-trices on the fly as the individual switching components change their states.This is not possible in the generated C code because the algorithms for calcu-lating the matrices are proprietary and because the calculation would simplybe too time consuming under real-time constraints.

When generating code for a physical model, PLECS therefore embeds the ma-trices for all combinations of switch states that it expects to encounter dur-ing the execution of a simulation run. In general this means that for a systemwith n switch elements 2n sets of state-space matrices are calculated and em-bedded into the generated C code. The actual number can be reduced by elimi-nating impossible combinations. For instance, the Triple Switch (see page 753)blocks internally consists of 3 switch elements but it still only accounts for 3instead of 23 combinations because one and only one switch will conduct atany time. Even so, systems with many switches will lead to large source andexecutable files and long compile times.

11 Code Generation

Reducing the Code Size

You can reduce the size of the generated code and the required compile timeby specifying the combinations for which code should be generated. The com-binations are specified using special Model Settings blocks that are connectedto individual physical models, see Electrical Model Settings on page 421, Ro-tational Model Settings on page 610 and Translational Model Settings on page734.

If at run-time a combination is encountered, for which no code has been gener-ated, the execution is aborted with an error message.

Maximum Number of Switches

The number of switch elements is limited to 16 or 32 per physical domain de-pending on the integer word size. This is due to the fact that the switch statesof a physical domain are stored internally in a single unsigned integer vari-able. Note that some components, such as the Triple Switch (see page 753),internally consist of more than one switch element.

Handling Naturally Commutated Devices

Switched physical models are difficult to handle in real-time simulations if thenatural switching instants can occur between two time steps. This is the casefor naturally commutated components where switching events are triggeredby internal quantities of the physical model. Examples of such componentsare the diode (which turns on when the voltage becomes positive and turnsoff when the current becomes negative) or the mechanical friction components(which start slipping when the torque resp. force exceeds a certain level andbecome stuck when the speed becomes zero).

During normal simulations, PLECS handles such non-sampled switchingevents using an interpolation scheme (see “Interpolation of Non-SampledSwitching Events” on page 36). This is not practical under real-time con-straints because the computation time required for the interpolation is severaltimes larger than that of an ordinary simulation step. In real-time simula-tions, PLECS will therefore defer the switching to the immediately followingtime step. Note that this reduces the accuracy compared to a normal simula-tion.

264

Code Generation for Physical Systems

Switching Algorithm

A further difficulty with naturally commutated devices is that their conduc-tion state is usually influenced by the conduction states of other switches.During normal simulations, PLECS solves this problem by iteratively togglingthe conduction states of naturally commutated switches within one simula-tion step until the boundary conditions of all switches are satisfied (see thedescription of the Switch Manager in section “Physical Model Equations” onpage 30).

When generating code for a physical model, PLECS lets you choose betweentwo switching algorithms, Iterative and Direct Look-up. You can specify thealgorithm individually for each physical model using special Model Settingsblocks that are connected to individual physical models, see Electrical ModelSettings on page 421, Rotational Model Settings on page 610 and Transla-tional Model Settings on page 734. The default switching algorithm is DirectLook-up.

Iterative PLECS generates code that implements an iterative switchingmethod as described above. As a consequence of the iteration, simulationsteps, in which a switching occurs, require more computation time than simu-lation steps without switching events. This is usually undesirable in real-timesimulations because the longest execution time determines the feasible samplerate.

Direct Look-up Alternatively, PLECS can generate code that determines theproper switch conduction states directly as functions of the current physicalmodel states and inputs and the gate signals of externally controlled switches.In order to generate these direct look-up functions, PLECS must analyze allpossible transitions between all possible combinations of conduction states.This increases the computation time of the code generation process but yieldsnearly uniform execution times of simulation steps with or without switchingevents.

In order to reduce the number of possible combinations of switch conductionstates and thus the code generation time and the code size, PLECS introducesthe condition that naturally commutated devices (e.g. diodes or IGBTs) canonly conduct if their current is non-zero. As a consequence, a diode may blockeven though the voltage is forward-biased if there is another blocking switchconnected in series that prevents the current from flowing through the diode.This can produce unexpected voltage waveforms even though otherwise themodel behaves correctly.

265

11 Code Generation

Consider the simple circuit shown below. Two diodes are connected in seriesbut opposing each other so that no current can flow regardless of the polarityof the source voltage:

0

D1

volta

ge

0

D2

volta

geSimulation of a circuit with two opposing diodes

In the two graphs, the bold lines show the results from a normal simulation.When the source voltage is positive, D1 conducts and D2 blocks, and hence thevoltage across D1 is zero and the voltage across D2 equals the negative sourcevoltage. As the source voltage becomes negative, D1 block and D2 conducts,and accordingly the voltage across D1 equals the source voltage and the volt-age across D2 is zero.

The dotted stairstep lines show the results from generated code using the it-erative switching method. As can be seen, the diodes behave in the same wayas in the normal simulation. In the generated code using the direct look-upmethod shown with continuous stairstep lines, however, both diodes block atall times because no current can ever flow through either of them. Accord-ingly, the source voltage always divides evenly across the two diodes.

266

Unsupported Components

Unsupported Components

PLECS currently does not support code generation for the following compo-nents:

• Algebraic Constraint (see page 333)• Brushless DC Machine (see page 348)• Electrical Algebraic Component (see page 417)• Non-Excited Synchronous Machine (see page 553)• Rotational Algebraic Component (see page 601)• Switched Reluctance Machine (see page 667)• Synchronous Reluctance Machine (see page 686)• Translational Algebraic Component (see page 725)• Variable Capacitor (see page 757)• Variable Inductor (see page 760)• Variable Resistor (see page 766)• Variable Resistor with Constant Parallel Capacitor (see page 767)• Variable Resistor with Constant Series Inductor (see page 768)• Variable Resistor with Variable Parallel Capacitor (see page 769)• Variable Resistor with Variable Series Inductor (see page 771)

PLECS also does not support code generation for models that contain alge-braic loops.

267

11 Code Generation

Code Generation with PLECS Standalone

PLECS Standalone produces C code in an embedded format, generating en-try point functions that must be called from a main application. The followingfunctions are generated:

void model_initialize(double time)This function should be called once at the beginning of a simulation to ini-tialize the internal data structures and the start value of the global clockfor components that depend on the absolute time.

void model_step()void model_step(int task_id)

This function should be called at every simulation step to advance themodel by one step. The second form is used if the multi-tasking mode isenabled (see “Scheduling” on page 272) and the model has more than onetask.

void model_output()void model_output(int task_id)

This function calculates the outputs of the current simulation step. Itshould be called at every simulation step before the model_update func-tion. The second form is used if the multi-tasking mode is enabled.

void model_update()void model_update(int task_id)

This function updates the internal states of the current simulation step. Itshould be called at every simulation step after the model_output function.The second form is used if the multi-tasking mode is enabled.

void model_terminate()This function should be called at the end of a simulation to release re-sources that were acquired at the beginning of or during a simulation.

The prefix model is replaced by a model-specific string.

The model_output and model_update functions are only generated if the cor-responding option is set in the target specific settings (see “Target” on page272). In this case, the model_step function is not generated.

If a runtime error occurs during the execution of any of the three functionsabove, the variable const char * model_errorStatus points to a string withthe error message. It is initialized with NULL.

268


Generating Code

To generate code, choose Coder options... from the Coder menu. This menuonly appears if you have a license for the PLECS Coder.

The left hand side of the dialog window shows a tree view of the model andthe code-generation subsystem that it contains. Intermediate subsystems thathave not been enabled for code generation appear as disabled entries that can-not be selected.

To enable a subsystem for code generation, select the subsystem, then chooseExecution settings... from the Subsystem submenu of the Edit menu orthe context menu. In the Subsystem Settings dialog check the option Enablecode generation. Note that it is not possible to enable code generation for asubsystem that is contained by or that itself contains other subsystems thatenable code generation. Checking this option implicitly also checks the op-tion Treat as atomic unit and unchecks the option Minimize occurrenceof algebraic loops. For more information on these options see “Virtual andAtomic Subsystems” (on page 662).

269

11 Code Generation

The right hand side of the dialog window shows a tabbed dialog with the codegeneration options for the system that is selected in the tree view. To generatecode for the currently selected system, click on the Build button at the bottomof the right hand side.

Code generation can also be initiated in an Octave simulation script or via theXML-RPC interface using the commands

plecs('codegen', 'path', optStruct, 'outputDir')

or

plecs.codegen('path', optStruct, 'outputDir')

respectively, where path is a model name or a subsystem path. The parame-ters optStruct and outputDir are optional.

If optStruct is provided, it is expected to be a struct as described in “ScriptedSimulation and Analysis Options” (on page 256). This enables you e.g. to gen-erate code for different parameter values without having to modify the modelfile.

If outputDir is provided, the generated files will be placed in this folder in-stead of the folder that is specified in the model.

General

Discretization step size This parameter specifies the base sample time ofthe generated code and is used to discretize the physical model equations (see“Physical Model Discretization” on page 35) and continuous state variables ofcontrol blocks.

Discretization method This parameter specifies the algorithm used to dis-cretize the physical model equations (see “Physical Model Discretization” onpage 35).

Floating point format This parameter specifies the default data type(float or double) that is used for floating point variables in the generatedcode.

270


Usage of absolute time This setting allows you to specify the diagnosticaction to be taken if PLECS generates code for a component that depends onthe absolute time. In order to minimize round-off errors, PLECS generatescode to calculate the absolute time using a signed 64-bit integer tick counter.If a simulation runs for an infinite time, this tick counter will eventuallyreach its maximum value, where it is halted to avoid problems that might oc-cur if the counter was wrapped to the (negative) minimum value, such as aStep block (see page 661) resetting to its initial value. To put things into per-spective, assuming a step size of 1µs this would occur after 292 271 years.

Depending on this setting, PLECS will either ignore this condition or it willissue a warning or error message that indicates the components that use theabsolute time.

Base name This parameter allows you to specify a custom prefix used toname the generated files and the exported symbols such as the interface func-tions or the input, output and parameter structs. By default, i.e. if you clearthis field, the base name is derived from the model or subsystem name.

Output directory This parameter allows you to specify, where the generatedfiles are stored. This can be an absolute path or a relative path with respectto the location of the model file. The default path is a directory model_codegennext to the model file.

Parameter Inlining

These two settings specify how PLECS handles tunable parameters in thegenerated code.

Default behavior This setting specifies whether PLECS inlines the param-eter values as numeric constants directly into the code (Inline parametervalues) or generates a data structure from which the values are read (Keepparameters tunable).

Inlining parameter values reduces the code size and increases the executionspeed. However, changing an inlined parameter value requires regeneratingand recompiling the code. On the other hand, the values of tunable parame-ters can be changed at execution time without recompiling the code.

Exceptions For the components listed here, the opposite of the default be-havior applies. If the default behavior is to inline all parameter values, thecomponents listed here will keep their parameters tunable and vice versa. Toadd components to this list, simply drag them from the schematic into the list.Use the Remove button to remove components from the list. To view the

271

11 Code Generation

selected component in the schematic editor, click the Show componentbutton.

Note Physical component parameters that affect the physical model equa-tions, such as resistances or inductances, cannot be kept tunable, becausechanging such parameters in general requires a recalculation of the completeequation system. You can, however, keep the parameters of source blocks tun-able.

Target

On this tab you can select a code generation target and configure target-specific settings. By default, only the Generic target is available. For infor-mation on how to install additional code generation targets, see “Coder Config-uration” (on page 48).

The Generic target has the following settings.

Generate separate output and update functions If you choose this op-tion, the model_step function is replaced by the two functions model_outputand model_update. Choose this option when you need access to the outputs asearly as possible during task execution (e.g. to transfer the values to an ana-log or digital output, update a logger, start a DMA transfer, etc.).

Scheduling

This tab is enabled only if you have selected a target that supports multi-tasking.

Tasking mode This parameter allows you to choose between the single-tasking and multi-tasking modes.

Task configuration This setting is visible only for the multi-tasking mode.

If you choose automatic, PLECS creates a task for each unique fixed-step dis-crete sample time in the model. All blocks that have the same sample timeare assigned to the same task. Blocks with multiple sample times (i.e. a C-Script that registers multiple different sample times) are assigned to the basetask associated with the base sample time.

272


If you choose specify, the dialog will show a table that lets you define a set oftasks. A task has a Task name and a Sample time that must be an integermultiple of the base sample time. The value 0 is replaced with the base sam-ple time itself. If the selected target supports multi-core processing, a task isalso associated with a Core. The radio buttons in the Default column specifythe default task (see below).

Each task must have a unique name, and the core/sample time pairs mustalso be unique. Note that the task set must comprise a base task that is as-sociated with the base sample time and core 0 (if applicable). For this reason,these columns in the first row are locked.

To assign a block or a group of blocks to a task, copy a Task Frame (see page690) into the schematic, open the Task Frame dialog to choose the desiredtask, and drag the frame around the blocks. Blocks that are not enclosed bya Task Frame are scheduled in the default task.

Note that blocks do not need to have the same sample time as the task thatthey are assigned to; the block sample time can be continuous or an integermultiple of the task sample time.

External Mode

This tab is enabled only if you have selected a target that supports externalmode operation and if the corresponding target setting is enabled. Externalmode operation enables you to

• Capture data on a target device and show them in Scope (see page 631),XY Plot (see page 784) and Display (see page 409) blocks in the model onthe host computer.

• Change values of tunable parameters (see “Parameter Inlining” on page271) in the model on the host computer and upload the changed values toan application running on a target device.

Task Transitions in Multi-Tasking Mode

If a block in one task receives one or more input signals from a block in an-other task, PLECS automatically inserts code to ensure that the signal data istransferred in a safe manner.

273

11 Code Generation

Task Transitions on the Same Core

If the source task is faster than the destination task and the sample time ofthe destination task is an integer multiple of the sample time of the sourcetask (i.e. if the destination task is executed at instants at which the sourcetask is also executed), PLECS inserts code equivalent to a Zero Order Hold(see page 787) that operates with the slower sample time.

If the source task is slower than the destination task and the sample time ofthe source task is an integer multiple of the sample time of the destinationtask (i.e. if the source task is executed at instants at which the destinationtask is also executed), PLECS inserts code equivalent to a Delay (see page387) that operates with the slower sample time.

In all other cases, PLECS uses a double buffer with a semaphore to transferthe data.

Task Transitions Between Different Cores

For task transitions between different cores, the write operation in the sourcetask can occur simultaneously with the read operation in the destination task.PLECS uses a double buffer with two semaphores to guarantee that simulta-neous read and write operations never access the same buffer.

Simulating a Subsystem in CodeGen Mode

Enabling a subsystem for code generation also enables the Simulation Modeparameter in the Execution Settings dialog (see the Subsystem block onpage 662). When this parameter is set to Normal, which is the default, thesubsystem is simulated like a normal atomic subsystem. When the parameteris set to CodeGen, the generated code is compiled and linked to PLECS to beexecuted instead of the subsystem during a simulation.

In connection with the “Traces” feature of the scopes (see “Adding Traces” onpage 100), this allows you to easily verify the fidelity of the generated codeagainst a normal simulation.

274

Code Generation with PLECS Blockset


Standalone Code Generation

PLECS Blockset can generate C code in the same format as PLECS Stan-dalone, and you can choose to generate code for a complete Circuit block orfor an individual subsystem. To generate code, choose Coder options... fromthe Coder menu. This menu only appears if you have a license for the PLECSCoder. For details on the coder options dialog please refer to the previous sec-tion “Code Generation with PLECS Standalone” (on page 268).

Code generation can also be initiated via the MATLAB commands

plecs('codegen', 'path')plecs('codegen', 'path', 'outputDir')

If outputDir is provided, the generated files will be placed in this folder in-stead of the folder that is specified in the model.

Integration with Simulink Coder

In addition, PLECS Blockset fully integrates with Simulink Coder (formerlyReal-Time Workshop) to generate C code for your simulation model. Wheneveryou start a build process from within Simulink, PLECS automatically gener-ates the code for a circuit block and inserts it at the appropriate places intothe code generated by Simulink Coder.

Note Scopes that are placed in PLECS schematics are not updated duringa simulation using code generation. To view the simulation results, all scopesmust be placed in the Simulink model.

Simulink Coder Options

The code generation options for the Simulink Coder are configured on theSimulink Coder pane of the PLECS simulation parameters.

275

11 Code Generation

Code generation target This parameter specifies the code generation tar-get (see “Code Generation Targets” on page 276). The default, auto, meansthat PLECS selects the target depending on the Simulink Coder target.

Inline circuit parameters for RSim target Specifies for the RSim targetwhether component parameters should be evaluated at compile time and in-lined into the code (on) or evaluated at run time (off). See also “Tunable Cir-cuit Parameters in Rapid Simulations” (on page 278).

Generate license-free code (requires PLECS Coder license) If this optionis checked, PLECS will attempt to check-out a PLECS Coder license at buildtime and, if successful, will generate code for the RSim target that will runwithout requiring a PLECS license. Otherwise, the generated executable willrequire a PLECS license at run time.

Show code generation progress If this option is checked, PLECS opensa dialog window during code generation that shows the progress of the codegeneration process. You can abort the process by clicking the Cancel buttonor closing the dialog window.

Code Generation Targets

PLECS can generate code for two different Simulink Coder targets: the RapidSimulation target (or RSim target) and the Real-Time target. These two tar-gets are described in detail in the following two sections. The table belowhighlights the differences between the targets.

Comparison of Code Generation Targets

RSim Target Real-Time Target

Purpose Rapid, non-real-time simu-lations.

Real-time simulations.

Technique A compressed descriptionof the circuit schematic isembedded in the code andinterpreted at run time.

Signal and state-spaceequations are inlined asANSI C code.

Limitations none Limited support for natu-rally commutated devicesand non-linear components.

276


Comparison of Code Generation Targets (contd.)

RSim Target Real-Time Target

Inlining Parameters may be de-clared tunable, so that theyare evaluated at run time.

All parameters are inlined,i.e. evaluated at compiletime and embedded intothe generated code.

Deployment Requires distribution of thePLECS RSim module.

Generated code does nothave external dependen-cies.

Licensing If a PLECS Coder licenseis available at build time,the generated code will runwithout a license. Other-wise, a PLECS license isrequired at run time.

Requires a PLECS Coderlicense at build time.

By default, PLECS automatically selects the appropriate target dependingon the target settings of Simulink Coder. To overrule this selection, open thePLECS simulation parameters, and on the Advanced pane change the settingTarget to either RSim or RealTime.

Real-Time Target

The Real-Time Target is selected by default when you generate code using anyof the real-time targets of Simulink Coder. Code generation for the Real-Timetarget requires a separate license for the PLECS Coder for PLECS Blockset.

For a detailed description of the code generation process for physical systemsand its current limitations see “Code Generation for Physical Systems” (onpage 263).

Rapid Simulation Target

The RSim target is selected by default when you run a simulation usingSimulink’s Rapid Accelerator mode or when you generate an executable us-ing the RSim target or the S-Function target of Simulink Coder. The resulting

277

11 Code Generation

code links against the RSim module of PLECS, a shared library which is partof the standard installation.

Deploying Rapid Simulation Executables

To deploy the generated executable you need to copy the appropriate sharedlibrary file onto the target computer. The following table lists the library filesfor the supported platforms.

Library Files for Rapid Simulations

Platform Library File

Windows 32-bit plecs\bin\win32\plecsrsim.dll

Windows 64-bit plecs\bin\win64\plecsrsim.dll

Mac Intel 32-bit plecs/bin/maci/libplecsrsim.dylib

Mac Intel 64-bit plecs/bin/maci64/libplecsrsim.dylib

Linux 64-bit plecs/bin/glnxa64/libplecsrsim.so

The library file must be copied into the same directory as the executable. Al-ternatively, you can define the appropriate environment variable for your tar-get computer such that it includes the directory where you have installed thelibrary file.

Licensing Protocols for the PLECS RSim Module

Depending on the build settings the RSim module may check out a PLECSlicense for the duration of execution. It uses the environment variablePLEXIM_LICENSE_FILE to locate the license file. If the module is unable tocheck out a PLECS license, it issues an error message and stops the simula-tion.

Tunable Circuit Parameters in Rapid Simulations

By default, PLECS evaluates the parameters of all circuit components at com-pile time and inlines them into the circuit description. However, for certain

278


applications – such as rapid simulations on different parameter sets or param-eterized S-Functions – it is desirable that the parameters be evaluated at sim-ulation start instead. This can be achieved by declaring the circuit parameterstunable.

To declare circuit parameters tunable,

1 Mask the PLECS Circuit block and define all parameters that you wish tokeep tunable as mask variables. Mask variables can either be mask param-eters (that appear in the parameter dialog) or variables defined in the maskinitialization commands. For more information see “Customizing the CircuitBlock” (on page 51).

2 On the Advanced pane of the PLECS simulation parameters, uncheck theoption Inline circuit parameters for RSim target.

3 Include the variable names in the list of tunable model parameters. Pleasesee the Simulink Coder User’s Guide for details.

Limitations on Tunable Circuit Parameters If you declare circuit parame-ters tunable, the RSim module uses its own parser to evaluate parameter ex-pressions at simulation start; it currently cannot handle mask initializationcommands. You will receive runtime errors if your circuit contains maskedsubsystems using mask initialization commands, or if a parameter expressioncontains a MATLAB function call.

Other limitations apply due to the way the Simulink Coder handles tunableparameters:

• Circuit parameters must be double-precision, 2-dimensional, non-sparse ar-rays.

• The first four characters of the parameter names must be unique.

279

11 Code Generation

280

12

Processor-in-the-Loop

As a separately licensed feature, PLECS offers support for Processor-in-the-Loop (PIL) simulations, allowing the execution of control code on externalhardware tied into the virtual world of a PLECS model.

At the PLECS level, the PIL functionality consists of a specialized PIL blockthat can be found in the Processor-in-the-loop library, as well as the TargetManager, accessible from the Window menu. Also included with the PILlibrary are high-fidelity peripheral models of MCUs used for the control ofpower conversion systems.

On the embedded side, a PIL Framework library is provided to facilitate theintegration of PIL functionality into your project.

Motivation

When developing embedded control algorithms, it is quite common to be test-ing such code, or portions thereof, by executing it inside a circuit simulator.Using PLECS, this can be easily achieved by means of a C-Script or DLLblock. This approach is referred to as Software-in-the-loop (SIL). A SIL sim-ulation compiles the embedded source code for the native environment of thesimulation tool (e.g. Win64) and executes the algorithms within the simulationenvironment.

The PIL approach, on the other hand, executes the control algorithms on thereal embedded hardware. Instead of reading the actual sensors of the powerconverter, values calculated by the simulation tool are used as inputs to theembedded algorithm. Similarly, outputs of the control algorithms executingon the processor are fed back into the simulation to drive the virtual environ-ment. Note that SIL and PIL testing are also relevant when the embeddedcode is automatically generated from the simulation model.

12 Processor-in-the-Loop

One of the major advantages of PIL over SIL is that during PIL testing, ac-tual compiled code is executed on the real MCU. This allows the detection ofplatform-specific software defects such as overflow conditions and casting er-rors. Furthermore, while PIL testing does not execute the control algorithmsin true real-time, the control tasks do execute at the normal rate between twosimulation steps. Therefore, PIL simulation can be used to detect and ana-lyze potential problems related to the multi-threaded execution of control algo-rithms, including jitter and resource corruption. PIL testing can also provideuseful metrics about processor utilization.

How PIL Works

At the most basic level, a PIL simulation can be summarized as follows:

Principle of a PIL simulation

• Input variables on the target, such as current and voltage measurements,are overridden with values provided by the PLECS simulation.

• The control algorithms are executed for one control period.• Output variables on the target, such as PWM peripheral register values,

are read and fed back into the simulation.

282

How PIL Works

We refer to variables on the target which are overridden by PLECS as Over-ride Probes. Variables read by PLECS are called Read Probes.

While Override Probes are set and Read Probes are read the dispatching ofthe embedded control algorithms must be stopped. The controls must remainhalted while PLECS is updating the simulated model. In other words, the con-trol algorithm operates in a stepped mode during a PIL simulation. However,as mentioned above, when the control algorithms are executing, their behavioris identical to a true real-time operation. We therefore call this mode of opera-tion pseudo real-time.

Let us further examine the pseudo real-time operation in the context of anembedded application utilizing nested control loops where fast high-prioritytasks (such as current control) interrupt slower lower-priority tasks (such asvoltage control). An example of such a configuration with two control tasks isillustrated in the figure below. With every hardware interrupt (bold verticalbar), the lower priority task is interrupted and the main interrupt service rou-tine is executed. In addition, the lower priority task is periodically triggeredusing a software interrupt. Once both control tasks have completed, the sys-tem continues with the background task where lowest priority operations areprocessed. The timing in this figure corresponds to true real-time operation.

Control Task 1

Control Task 2

Background Task

1 2 3 4 5 6

Nested Control Tasks

The next figure illustrates the timing of the same controller during a PIL sim-ulation, with the stop and go symbols indicating when the dispatching of thecontrol tasks is halted and resumed.

After the hardware interrupt is received, the system stops the control dis-patching and enters a communication loop where the values of the OverrideProbes and Read Probes can be exchanged with the PLECS model. Once anew step request is received from the simulation, the task dispatching is

283


Control Task 1

Control Task 2

Background Task

2 3

STOP

1

STOP STOP

Pseudo real-time operation

restarted and the control tasks execute freely during the duration of one in-terrupt period. This pseudo real-time operation allows the user to analyze thecontrol system in a simulation environment in a fashion that is behaviorallyidentical to a true real-time operation. Note that only the dispatching of thecontrol tasks is stopped. The target itself is never halted as communicationwith PLECS must be maintained.

PIL Modes

The concept of using Override Probes and Read Probes allows tying actualcontrol code executing on a real MCU into a PLECS simulation without theneed to specifically recompile it for PIL.

You can think of Override Probes and Read Probes as the equivalent of testpoints which can be left in the embedded software as long as desired. Soft-ware modules with such test points can be tied into a PIL simulation at anytime.

Often, Override Probes and Read Probes are configured to access the registersof MCU peripherals, such as analog-to-digital converters (ADCs) and pulse-width modulation (PWM) modules. Additionally, specific software modules, e.g.a filter block, can be equipped with Override Probes and Read Probes. Thisallows unit-testing the module in a PIL simulation isolated from the rest ofthe embedded code.

To permit safe and controlled transitions between real-time execution of thecontrol code, driving an actual plant, and pseudo real-time execution, in con-

284

Configuring PLECS for PIL

junction with a simulated plant, the following two PIL modes are distin-guished:

• Normal Operation – Regular target operation in which PIL simulationsare inhibited.

• Ready for PIL – Target is ready for a PIL simulation, which correspondsto a safe state with the power-stage disabled.

The transition between the two modes can either be controlled by the embed-ded application, for example based on a set of digital inputs, or from PLECSusing the Target Manager.

Configuring PLECS for PIL

Once an embedded application is equipped with the PIL framework, and ap-propriate Override Probes and Read Probes are defined, it is ready for PILsimulations with PLECS.

PLECS uses the concept of Target Configurations to define global high-levelsettings that can be accessed by any PLECS model. At the circuit level, thePIL block is utilized to define lower level configurations such as the selectionof Override Probes and Read Probes used during simulation.

This is explained in further detail in the following sections.

Target Manager

The high-level configurations are made in the Target Manager, which is ac-cessible in PLECS by means of the corresponding item in the Window menu.The target manager allows defining and configuring targets for PIL simula-tion, by associating them with a symbol file and specifying the communicationparameters. Target configurations are stored globally at the PLECS level andare not saved in *.plecs or Simulink files. An example target configuration isshown in the figure below.

285


Target Manager

The left hand side of the dialog window shows a list of targets that are cur-rently configured. To add a new target configuration, click the button marked+ below the list. To remove the currently selected target, click the buttonmarked -. You can reorder the targets by clicking and dragging an entry upand down in the list.

The right hand side of the dialog window shows the parameter settings ofthe currently selected target. Each target configuration must have a uniqueName.

The target configuration specifies the Symbol file and the communicationlink settings.

The symbol file is the binary file (also called “object file”) corresponding to thecode executing on the target. PLECS will obtain most settings for PIL simu-lations, as well as the list of Override Probes and Read Probes and their at-tributes, from the symbol file.

Communication Links

A number of links are supported for communicating with the target. The de-sired link can be selected in the Device type combo box. For communicationlinks that allow detecting connected devices, pressing the Scan button willpopulate the Device name combo box with the names of all available devices.

286

Target Manager

Serial Device

The Serial device selection corresponds to conventional physical or virtualserial communication ports. On a Windows machine, such ports are labeledCOMn, where n is the number of the port.

FTDI Device

If the serial adapter is based on an FTDI chip, the low-level FTDI driver canbe used directly by selecting the FTD2XX option. This device type offers im-proved communication speed over the virtual communication port (VCP) asso-ciated with the FTDI adapter.

TCP/IP Socket

The communication can also be routed over a TCP/IP socket by selecting theTCP Socket device type.

TCP/IP Communication

In this case the Device name corresponds to the IP address (or URL) andport number, separated by a colon (:).

287


Serial over GDB

The Serial over GDB device type is used in conjunction with communica-tion over JTAG. It requires that a GDB server be running and connected tothe embedded target. The configuration of this device is similar to the TCPSocket and consists of specifying a URL (typically the localhost 127.0.0.1) anda TCP/IP port. Please review the documentation of your GDB server for moreinformation regarding port settings.

Target Properties

By pressing the Properties button, target information can be displayed asshown in the figure below.

Target Properties

In addition to reading and displaying information from the symbol file, PLECSwill also query the target for its identity and check the value against the onestored in the symbol file. This verifies the device settings and ensures that thecorrect binary file has been selected. Further, the user can request for a targetmode change to configure the embedded code to run in Normal Operationmode or in Ready for PIL mode.

PIL Block

The PIL block ties a processor into a PLECS simulation by making OverrideProbes and Read Probes, configured on the target, available as input and out-

288

PIL Block

put ports, respectively.

PIL Block

A PIL block is associated with a target defined in the target manager, whichis selected from the Target combo box. The Configure. . . button provides aconvenient shortcut to the target manager for configuring existing and newtargets.

PIL Block General Tab

The execution of the PIL block can be triggered at a fixed Discrete-Periodicrate by configuring the Sample time to a positive value. As with otherPLECS components, an Inherited sample time can be selected by setting theparameter to -1 or [-1 0].A trigger port can be enabled using the External trigger combo box. This isuseful if the control interrupt source is part of the PLECS circuit, such as an

289


ADC or PWM peripheral model.

Typically, an Inherited sample time is used in combination with a triggerport. If a Discrete-Periodic rate is specified, the trigger port will be sampledat the specified rate.

Similar to the DLL block, the Output delay setting permits delaying the out-put of each simulation step to approximate processor calculation time.

Note Make sure the value for the Output delay does not exceed the sampletime of the block, or the outputs will never be updated.

A delay of 0 is a valid setting, but it will create direct-feedthrough betweeninputs and outputs.

PIL Block Inputs Tab

The PIL block extracts the names of Override Probes and Read Probes fromthe symbol file selected in the target configuration and presents lists for selec-tion as input and output signals, as shown in the figure above.

290

PIL Block

The number of inputs and outputs of a PIL block is configurable with theNumber of inputs and Number of outputs settings. To associate OverrideProbes or Read Probes with a given input or output, select an input/outputfrom the combo box on the right half of the dialog. Then drag the desiredOverride Probes or Read Probes from the left into the area below or add themby selecting them and clicking the > button. To remove an Override Probe orRead Probe, select it and either press the Delete key or < button.

Note It is possible to multiplex several Override/Read Probe signals into oneinput/output. The sequence can be reordered by dragging the signals up anddown the list.

Starting with PLECS 3.7, the PIL block allows setting initial conditions forOverride Probes.

Also new with PLECS 3.7 is the Calibrations tab, which permits modifyingembedded code settings such as regulator gains and filter coefficients.

PIL Block Calibrations Tab

291


Calibrations can be set in the Value column. If no entry is provided, the em-bedded code will use the default value as indicated in the Default column.

292

13

Components by Category

This chapter lists the blocks of the Component library by category.

System

Configurable Subsystem Provide subsystem with exchangeable implementa-tions

Display Display signal values in the schematic

Dynamic Signal Selector Select or reorder elements from vectorized signaldepending on control signal

Electrical Ground Connect to common electrical ground

Electrical Label Connect electrical potentials by name

Electrical Port Add electrical connector to subsystem

Enable Control execution of an atomic subsystem

Pause / Stop Pause or stop the simulation

Scope Display simulation results versus time

Signal Demultiplexer Split vectorized signal

Signal From Reference signal from Signal Goto block by name

Signal Goto Make signal available by name

Signal Inport Add signal input connector to subsystem

Signal Multiplexer Combine several signals into vectorized signal

Signal Outport Add signal output connector to subsystem

13 Components by Category

Signal Selector Select or reorder elements from vectorized signal

Subsystem Create functional entity in hierarchical simulationmodel

Task Frame Associate the enclosed components with a task in amulti-tasking environment

To File Write time and signal values to file

From File Read time and signal values from file

Trigger Control execution of an atomic subsystem

Wire Multiplexer Bundle several wires into bus

Wire Selector Select or reorder elements from wire bus

XY Plot Display correlation between two signals

Assertions

Assert Dynamic Lower Limit Check whether a signal stays above another signal

Assert Dynamic Range Check whether a signal stays between two othersignals

Assert Dynamic Upper Limit Check whether a signal stays below another signal

Assertion Check whether a condition is true

Assert Lower Limit Check whether a signal stays above a constant

Assert Range Check whether a signal stays within a constantrange

Assert Upper Limit Check whether a signal stays below a constant

Control

Sources

Clock Provide current simulation time

Constant Generate constant signal

294

Control

Initial Condition Output specified initial value in the first simula-tion step

Pulse Generator Generate periodic rectangular pulses

Ramp Generate constantly rising or falling signal

Sine Wave Generate time-based sine wave with optional bias

Step Generate constant signal with instantaneous stepchange

Triangular Wave Generator Generate periodic triangular or sawtooth waveform

White Noise Generate normally distributed random numbers

Random Numbers Generate uniformly distributed random numbers

Math

Abs Calculate absolute value of input signal

Algebraic Constraint Enforce an algebraic constraint

Data Type Cast the input signal to the specified data type

Gain Multiply input signal by constant

Math Function Apply specified mathematical function

Minimum / Maximum Output input signal with highest resp. lowestvalue

Offset Add constant to input signal

Product Multiply and divide scalar or vectorized inputsignals

Rounding Round floating point signal to integer values

Signum Provide sign of input signal

Sum Add and subtract input signals

Trigonometric Function Apply specified trigonometric function

Continuous

295


Continuous PID Controller Implementation of a continuous-time controller (P,I, PI, PD or PID)

Integrator Integrate input signal with respect to time

PLL (Single-Phase) Implementation of a single phase PLL

PLL (Three-Phase) Implementation of a three phase PLL

State Space Implement linear time-invariant system as state-space model

Transfer Function Model linear time-invariant system as transferfunction

Delays

Memory Provide input signal from previous major time step

Pulse Delay Delay discrete-value input signal by fixed time

Transport Delay Delay continuous input signal by fixed time

Turn-on Delay Delay rising flank of input pulses by fixed deadtime

Discontinuous

Comparator Compare two input signals with minimal hystere-sis

Dead Zone Output zero while input signal is within dead zonelimits

Hit Crossing Detect when signal reaches or crosses given value

Manual Signal Switch Manually select one of two input signals

Multiport Signal Switch Select one of multiple input signals depending oncontrol signal

Quantizer Apply uniform quantization to input signal

Rate Limiter Limit rising and falling rate of change

296

Control

Relay Toggle between on- and off-state with configurablethreshold

Saturation Limit input signal to upper and/or lower value

Signal Switch Select one of two input signals depending on con-trol signal

Discrete

Delay Delay input signal by given number of samples

Discrete Fourier Transform Perform discrete Fourier transform on input signal

Discrete Integrator Calculate discrete integral of input signal

Discrete Mean Value Calculate running mean value of input signal

Discrete PID Controller Implementation of a discrete-time controller (P, I,PI, PD or PID)

Discrete RMS Value Calculate root mean square (RMS) value of inputsignal

Discrete State Space Implement discrete time-invariant system as state-space model

Discrete Total HarmonicDistortion

Calculate total harmonic distortion (THD) of inputsignal

Discrete Transfer Function Model discrete system as transfer function

Zero-Order Hold Sample and hold input signal periodically

Filters

Moving Average Continuously average input signal over specifiedtime period

Periodic Average Periodically average input signal over specifiedtime

Periodic Impulse Average Periodically average Dirac impulses over specifiedtime

297


Total Harmonic Distortion Calculate total harmonic distortion (THD) of inputsignal

Fourier Transform Perform Fourier transform on input signal

RMS Value Calculate root mean square (RMS) value of inputsignal

Functions & Tables

1D Look-Up Table Compute piece-wise linear function of one inputsignal

2D Look-Up Table Compute piece-wise linear function of two inputsignals

3D Look-Up Table Compute piece-wise linear function of three inputsignals

C-Script Execute custom C code

DLL Interface with externally generated dynamic-linklibrary

Fourier Series Synthesize periodic output signal from Fouriercoefficients

Function Apply arbitrary arithmetic expression to scalar orvectorized input signal

FMU Use a model stored in an FMU model

Logical

Combinatorial Logic Use binary input signals to select one row fromtruth table

Compare to Constant Compare input signal to constant threshold

D Flip-flop Implement edge-triggered flip-flop

Edge Detection Detect edges of pulse signal in given direction

JK Flip-flop Implement edge-triggered JK flip-flop

298

Control

Logical Operator Combine input signals logically

Monoflop Generate pulse of specified width when triggered

Relational Operator Compare two input signals

SR Flip-flop Implement set-reset flip-flop

Modulators

2-Pulse Generator Generate firing pulses for H-bridge thyristor recti-fier

3-Phase Overmodulation Extend linear range of modulation index for 3-phase inverters

6-Pulse Generator Generate firing pulses for 3-phase thyristor recti-fier

Blanking Time Generate commutation delay for 2-level inverterbridges

Blanking Time (3-Level) Generate commutation delay for 3-level inverterbridges

Peak Current Controller Implement peak current mode control

Sawtooth PWM Generate PWM signal using sawtooth carrier

Sawtooth PWM (3-Level) Generate 3-level PWM signal using sawtooth carri-ers

Space Vector PWM Generate PWM signals for 3-phase inverter usingspace-vector modulation

Space Vector PWM (3-Level) Generate PWM signals for 3-phase NPC inverterusing space-vector modulation

Symmetrical PWM Generate PWM signal using symmetrical triangu-lar carrier

Symmetrical PWM (3-Level) Generate 3-level PWM signal using symmetricaltriangular carriers

Transformations

299


Polar to Rectangular Convert polar coordinates to Cartesian coordinates

Rectangular to Polar Convert Cartesian coordinates to polar coordinates

Transformation 3ph->RRF Transform 3-phase signal to rotating referenceframe

Transformation 3ph->SRF Transform 3-phase signal to stationary referenceframe

Transformation RRF->3ph Transform vector in rotating reference frame into3-phase signal

Transformation RRF->SRF Transform vector from rotating to stationary refer-ence frame

Transformation SRF->3ph Transform vector in stationary reference frameinto 3-phase signal

Transformation SRF->RRF Transform vector from stationary to rotating refer-ence frame

State Machine

State Machine Model a state machine

Small Signal Analysis

(PLECS Standalone only)

Small Signal Gain Measure loop gain of closed control loop usingsmall-signal analysis

Small Signal Perturbation Generate perturbation signal for small-signal anal-ysis

Small Signal Response Measure system response for small-signal analysis

Electrical

Sources

300

Electrical

Current Source (Controlled) Generate variable current

Current Source AC Generate sinusoidal current

Current Source DC Generate constant current

Voltage Source (Controlled) Generate variable voltage

Voltage Source AC Generate sinusoidal voltage

Voltage Source AC (3-Phase) Generate 3-phase sinusoidal voltage

Voltage Source DC Generate constant voltage

Meters

Ammeter Output measured current as signal

Meter (3-Phase) Measure voltages and currents of 3-phase system

Voltmeter Output measured voltage as signal

Passive Components

Capacitor Ideal capacitor

Electrical Algebraic Compo-nent

Enforce an algebraic constraint in terms of voltageand current

Inductor Ideal inductor

Mutual Inductor Ideal mutual inductor

Mutual Inductance (2 Wind-ings)

Magnetic coupling between two lossy windings

Mutual Inductance (3 Wind-ings)

Magnetic coupling between three lossy windings

Pi-Section Line Single-phase pi-section transmission line

Piece-wise Linear Resistor Resistance defined by voltage-current pairs

Resistor Ideal resistor

Saturable Capacitor Capacitor with piece-wise linear saturation

301


Saturable Inductor Inductor with piece-wise linear saturation

Transmission Line (3ph) 3-phase transmission line

Variable Capacitor Capacitance controlled by signal

Variable Inductor Inductance controlled by signal

Variable Resistor Resistance controlled by signal

Variable Resistor with Con-stant Capacitor

Controlled resistance in parallel with constantcapacitance

Variable Resistor with Con-stant Inductor

Controlled resistance in series with constant in-ductance

Variable Resistor with Vari-able Capacitor

Controlled resistance in parallel with controlledcapacitance

Variable Resistor with Vari-able Inductor

Controlled resistance in series with controlledinductance

Power Semiconductors

Diode Ideal diode with optional forward voltage andon-resistance

Diode with Reverse Recovery Dynamic diode model with reverse recovery

GTO Ideal GTO with optional forward voltage and on-resistance

GTO (Reverse Conducting) Ideal GTO with ideal anti-parallel diode

IGBT Ideal IGBT with optional forward voltage andon-resistance

IGBT with Diode Ideal IGBT with ideal anti-parallel diode

IGBT with Limited di/dt Dynamic IGBT model with finite current slopesduring turn-on and turn-off

IGCT (Reverse Blocking) Ideal IGCT with optional forward voltage andon-resistance

IGCT (Reverse Conducting) Ideal IGCT with ideal anti-parallel diode

MOSFET Ideal MOSFET with optional on-resistance

302

Electrical

MOSFET with Diode Ideal MOSFET with ideal anti-parallel diode

MOSFET with Limited di/dt Dynamic MOSFET model with finite currentslopes during turn-on and turn-off

Thyristor Ideal thyristor (SCR) with optional forward voltageand on-resistance

Thyristor with Reverse Recov-ery

Dynamic thyristor (SCR) model with reverse recov-ery

TRIAC Ideal TRIAC with optional forward voltage andon-resistance

Zener Diode Zener diode with controlled reverse breakdownvoltage

Power Modules

3-Level Half Bridge (ANPC) Single leg of a 3-level active neutral-point clampedhalf-bridge converter.

3-Level Half Bridge (T-Type) Single leg of a 3-level T-type half-bridge converter.

5-Level Half Bridge (ANPC), Single leg of a 5-level active neutral-point clampedhalf-bridge converter.

3-Phase Current SourceInverter

3-phase 2-level current source inverter IGBT mod-ule.

3-Phase Voltage SourceInverter

3-phase 2-level voltage source inverter IGBT mod-ule.

Dual Active Bridge Converter Dual Active Bridge converter module.

Flying Capacitor Half Bridge Multi-level inverter half bridge with flying capaci-tors.

Full-Bridge LLC ResonantConverter

Full-Bridge LLC Resonant Converter convertermodule.

Half-Bridge LLC ResonantConverter

Half-Bridge LLC Resonant Converter convertermodule.

IGBT Chopper (Low-SideSwitch)

Chopper used in boost converters.

303


IGBT Chopper (High-SideSwitch)

Chopper used in buck converters.

IGBT Chopper (Low-SideSwitch with Reverse Diode)

Chopper used in boost converters.

IGBT Chopper (High-SideSwitch with Reverse Diode)

Chopper used in buck converters.

IGBT Half Bridge Single leg of a 2-level voltage source inverter.

IGBT 3-Level Half Bridge(NPC)

Single leg of a 3-level neutral-point clamped volt-age source inverter.

IGBT Half Bridges (Low-/High-Side Connected)

Series-connected inverter cells for modular multi-level converters.

IGBT Full Bridges (SeriesConnected)

Series-connected inverter cells for modular multi-level converters.

Phase-Shifted Full-BridgeConverter

Phase-Shifted Full-Bridge converter module.

Switches

Breaker AC circuit breaker opening at zero current

Double Switch Changeover switch with two positions

Manual Double Switch Manual changeover switch with two positions

Manual Switch Manual on-off switch

Manual Triple Switch Manual changeover switch with three positions

Set/Reset Switch Bistable on-off switch

Switch On-off switch

Triple Switch Changeover switch with three positions

Transformers

Ideal Transformer Ideally coupled windings without inductance

304

Electrical

Linear Transformer (2 Wind-ings)

Single-phase transformer with winding resistanceand optional core loss

Linear Transformer (3 Wind-ings)

Single-phase transformer with winding resistanceand optional core loss

Saturable Transformers Single-phase transformers with two resp. threewindings and core saturation

Transformers (3ph, 2 Wind-ings)

3-phase transformers in Yy, Yd, Yz, Dy, Dd and Dzconnection

Transformers (3ph, 3 Wind-ings)

3-phase transformers in Ydy and Ydz connection

Machines

Brushless DC Machine Detailed model of brushless DC machine excitedby permanent magnets

Brushless DC Machine (Sim-ple)

Simplified model of brushless DC machine excitedby permanent magnets

DC Machine Simple model of DC machine

Induction Machine (Slip Ring) Non-saturable induction machine with slip-ringrotor

Induction Machine (OpenStator Windings)

Non-saturable induction machine with squirrel-cage rotor and open stator windings

Induction Machine (SquirrelCage)

Non-saturable induction machine with squirrel-cage rotor

Induction Machine with Satu-ration

Induction machine with slip-ring rotor and main-flux saturation

Non-Excited SynchronousMachine

Non-excited synchronous machine configurablewith lookup tables

Permanent Magnet Syn-chronous Machine

Synchronous machine excited by permanent mag-nets

Switched Reluctance Machine Detailed model of switched reluctance machinewith open windings

305


Synchronous Machine (RoundRotor)

Smooth air-gap synchronous machine with main-flux saturation

Synchronous Machine(Salient Pole)

Salient-pole synchronous machine with main-fluxsaturation

Synchronous ReluctanceMachine

Synchronous reluctance machine configurable withlookup tables

306

Thermal

Converters

Diode Rectifier (3ph) 3-phase diode rectifier

Ideal 3-Level Converter (3ph) Switch-based 3-phase 3-level converter

Ideal Converter (3ph) Switch-based 3-phase converter

IGBT 3-Level Converter (3ph) 3-phase 3-level neutral-point clamped IGBT con-verter

IGBT Converter (3ph) 3-phase IGBT converter

MOSFET Converter (3ph) 3-phase MOSFET converter

Thyristor Rectifier/Inverter 3-phase thyristor rectifier/inverter

Electronics

Op-Amp Ideal operational amplifier with finite gain

Op-Amp with Limited Output Ideal operational amplifier with limited outputvoltage

Model Settings

Electrical Model Settings Configure settings for an individual electrical cir-cuit

Thermal

Ambient Temperature Connect to Heat Sink on which component isplaced

Constant Heat Flow Generate constant heat flow

Constant Temperature Provide constant temperature

Controlled Heat Flow Generate variable heat flow

Controlled Temperature Provide variable temperature

307


Heat Flow Meter Output measured heat flow as signal

Heat Sink Isotherm environment for placing components

Thermal Capacitor Thermal capacitance of piece of material

Thermal Chain Thermal impedance implemented as RC chain

Thermal Ground Connect to common reference temperature

Thermal Model Settings Configure settings for an individual thermal sys-tem

Thermal Port Add thermal connector to subsystem

Thermal Resistor Thermal resistance of piece of material

Thermometer Output measured temperature as signal

Magnetic

Winding Ideal winding defining an electro-magnetic inter-face

Magnetic Permeance Linear magnetic permeance

Linear Core Linear magnetic core element

Air Gap Air gap in a magnetic core

Leakage Flux Path Permeance of linear leakage flux path

Saturable Core Magnetic core element with saturation

Hysteretic Core Magnetic core element with static hysteresis

Variable Magnetic Perme-ance

Variable permeance controlled by external signal

Magnetic Resistance Effective magnetic resistance for modeling losses

MMF Meter Output the measured magneto-motive force

Flux Rate Meter Output the measured rate-of-change of magneticflux

MMF Source (Constant) Generate a constant magneto-motive force

MMF Source (Controlled) Generate a variable magneto-motive force

308

Mechanical

Magnetic Port Add magnetic connector to subsystem

Mechanical

Translational

Sources

Force (Constant) Generate constant force

Force (Controlled) Generate variable force

Translational Speed (Con-stant)

Maintain constant linear speed

Translational Speed (Con-trolled)

Maintain variable linear speed

Sensors

Force Sensor Output measured force as signal

Translational Speed Sensor Output measured linear speed as signal

Position Sensor Output measured absolute or relative position assignal

Components

Translational Reference Connect to translational reference frame

Translational Port Add translational flange to subsystem

Mass Model sliding mass with inertia

Translational Spring Ideal translational spring

Translational Damper Ideal viscous translational damper

Translational Clutch Ideal translational clutch

Translational Backlash Ideal translational backlash

309


Translational Hard Stop Ideal translational single- or double-sided hardstop

Translational Friction Ideal translational stick/slip friction

Rack and Pinion Ideal conversion between translational and rota-tional motion

Translational Algebraic Com-ponent

Define an algebraic constraint in terms of forceand speed

Model Settings

Translational Model Settings Configure settings for an individual mechanicalsystem

Rotational

Sources

Torque (Constant) Generate constant torque

Torque (Controlled) Generate variable torque

Rotational Speed (Constant) Maintain constant angular speed

Rotational Speed (Controlled) Maintain variable angular speed

Sensors

Torque Sensor Output measured torque as signal

Rotational Speed Sensor Output measured angular speed as signal

Angle Sensor Output measured absolute or relative angle assignal

Components

310

Additional Simulink Blocks

Rotational Reference Connect to rotational reference frame

Rotational Port Add rotational flange to subsystem

Inertia Model rotating body with inertia

Torsion Spring Ideal torsion spring

Rotational Damper Ideal viscous rotational damper

Rotational Clutch Ideal rotational clutch

Rotational Backlash Ideal rotational backlash

Rotational Hard Stop Ideal rotational single- or double-sided hard stop

Rotational Friction Ideal rotational stick/slip friction

Gear Ideal gear

Planetary Gear Set Ideal planetary gear set

Rack and Pinion Ideal conversion between translational and rota-tional motion

Rotational Algebraic Compo-nent

Define an algebraic constraint in terms of torqueand angular speed

Model Settings

Rotational Model Settings Configure settings for an individual mechanicalsystem


(PLECS Blockset only)

AC Sweep Perform AC sweep

Impulse Response Analysis Perform impulse response analysis

Loop Gain Analysis Determine loop gain of closed control loop

Steady-State Analysis Determine periodic steady-state operating point

Timer Generate piece-wise constant signal

311


312

14

Component Reference

This chapter lists the contents of the Component library in alphabetical order.

14 Component Reference

1D Look-Up Table

Purpose Compute piece-wise linear function of one input signal

Library Control / Functions & Tables

Description

1DTable

The 1D Look-Up Table block maps an input signal to an output signal. Youdefine the mapping function by specifying a vector of input values and a vec-tor of output values. If the input signal lies within the range of the input vec-tor, the output value is calculated by linear interpolation between the appro-priate two points. If the input signal is out of bounds, the block extrapolatesusing the first or last two points.

Step transitions are achieved by repeating an input value with different out-put values. If the input signal exactly matches the input value of such a dis-continuity, the output signal will be the output value of the mapping functionthat is first encountered when moving away from the origin. If the discontinu-ity is at input value 0, the output signal will be the average of the two outputvalues. Provided zero-crossing signals are not active (see “Locate discontinu-ities” below) this behavior can be overridden by defining three output valuesfor the same input value; in this case the middle output value will be chosen.

Use the 2D Look-Up Table block (see page 316) to map two input signals to anoutput signal.

Parameters Vector of input values xThe vector of input values x. This vector must be the same size as the out-put vector and monotonically increasing. It should not contain more thanthree identical values.

Vector of output values f(x)The vector containing the output values f(x). This vector must be thesame size as the input vector.

Locate discontinuitiesWhen set to on, the Look-Up Table defines zero-crossing signals that pre-vent a variable-step solver from inadvertently stepping over a discontinu-ity of the input-output mapping or its derivative.

Note that the use of zero-crossing signals forces the mapping to be left- orright-continuous. Therefore, it is not possible to specify an arbitrary out-put value at a step discontinuity: if three output values are defined for the

314

1D Look-Up Table

same input, the middle output value is neglected. Moreover, if the step dis-continuity is at input value 0, no averaging is performed: the first outputvalue corresponding to 0 is selected instead.

When set to off, the Look-Up Table does not explicitly influence the stepstaken by a variable-step solver.

Probe Signals InputThe block input signal.

OutputThe block output signal.

315


2D Look-Up Table

Purpose Compute piece-wise linear function of two input signals


Description

2DTable

xy

The 2D Look-Up Table block maps two input signals to an output signal. Youdefine the mapping function by specifying two vectors of input values and amatrix of output values. The input vector x corresponds to the rows of the out-put matrix, the input vector y, to the columns.

The output value is interpolated or extrapolated from the block parametersusing the technique described for the 1D Look-Up Table block (see page 314).

Parameters Vector of input values xThe vector of input values x. This vector must be the same size as thenumber of rows in the output matrix and monotonically increasing. Itshould not contain more than three identical values.

Vector of input values yThe vector of input values y. This vector must be the same size as thenumber of columns in the output matrix and monotonically increasing. Itshould not contain more than three identical values.

Matrix of output values f(x,y)The matrix containing the output values f(x, y). The number of rows andcolumns must match the size of the input vectors.



Probe Signals Input xThe block input signal x.

Input yThe block input signal y.


316

2-Pulse Generator

2-Pulse Generator

Purpose Generate firing pulses for H-bridge thyristor rectifier

Library Control / Modulators

Description This block generates the pulses used to fire the thyristors of an H-bridge rec-tifier. The inputs of the block are a logical enable signal, a ramp signal ϕ (pro-duced e.g. by a PLL), and the firing angle alpha.

317


3-Level Half Bridge (ANPC)

Purpose 3-level active neutral-point clamped half-bridge converter module

Library Electrical / Power Modules

Description

S1

S2

S3

S4

S5

S6

This power module implements a single leg of a 3-level active neutral-pointclamped voltage source converter. It contains six IGBTs S1 to S6 as indicatedin the figure. The power module offers two configurations:

Switched All power semiconductors inside the module are modeled withideal switches. The individual IGBTs are controlled with logical gate signals.An IGBT is on if the corresponding gate signal is not zero. For compatibilitywith the averaged configuration it is recommended to use the value 1 for non-zero gate signals.

Sub-cycle average The module as a whole is modeled with controlledvoltage and current sources. The DC side of the inverter bridge has currentsource behavior and must be connected to positively biased capacitors or volt-age sources. The phase terminal is typically connected to an inductor. Thecontrol inputs are the relative on-times of the IGBTs with values between 0and 1.

In the average configuration the half bridge can be operated in two ways:

• The control signals are instantaneous logical gate signals having the values0 and 1.

• The control signals are the duty cycles of the individual IGBTs. They areeither computed directly from the modulation index or by periodically av-eraging the digital gate signals over a fixed period of time, e.g. using thePeriodic Average block (see page 562). The averaging period does not needto be synchronized with the PWM and can be as large as the inverse of theswitching frequency.

In both use cases, the average implementation correctly accounts for blankingtimes, i.e. when during commutation less than two IGBTs are turned on. Italso supports discontinuous conduction mode, e.g. when charging the DC linkcapacitors via the reverse diodes.

Since the duty cycle is simulated accurately even with relatively large timesteps, the average configuration is particularly well suited for real-time simu-lations with high switching frequencies.

318


Note The sub-cycle average implementation cannot model a shoot-through orclamping of the DC side. Therefore, the sums of the control signals for switchesS1 and S4, switches S1 and S3 and switches S2 and S4 must not exceed 1 atany time. Additionally, the control signals for switches S1 and S5 and switchS4 and S6 must not exceed 1 at any time. Also, the applied DC voltages mustnever become negative.

Parameters ConfigurationSwitched or averaged circuit model.

Semiconductor symbolThis setting lets you choose between IGBT and MOSFET for the symbol theactive semiconductor switches. This setting does not change the electricalbehavior of the power module in simulation.

AssertionsWhen set to on, the block will flag an error if the sums of the control sig-nals for S1 and S4, S1 and S3, S2 and S4, S1 and S5, or S4 and S6 exceed1 at any time.

319


3-Level Half Bridge (T-Type)

Purpose 3-level T-type half-bridge converter module


Description This power module implements a single leg of a 3-level T-Type voltage sourceconverter. It contains four IGBTs: IGBT 1 between DC positive and phase out-put, IGBT 2 (left) and IGBT 3 (right) between DC neutral and phase outputand IGBT 4 between phase output and DC negative. The power module offerstwo configurations:








320

3-Level Half Bridge (T-Type)

Note The sub-cycle average implementation cannot model a shoot-through orclamping of the DC side. Therefore, the sums of the control signals for the firstand fourth IGBT and first and third IGBT and second and fourth IGBT mustnot exceed 1 at any time. Also, the applied DC voltages must never become neg-ative.



Neutral-point connectionSpecifies if IGBT 2 and 3 are series connected with Common collector(drain for MOSFETs) or Common emitter (source for MOSFETs).

AssertionsWhen set to on, the block will flag an error if the sums of the control sig-nals for IGBT 1 and 4 or IGBT 1 and 3 or IGBT 2 and 4 exceed 1.

321



Purpose 5-level active neutral-point clamped half-bridge converter module


Description

S1

S2

S3

S4

S5

S7

S8

S6

This power module implements a single leg of a 5-level active neutral-pointclamped voltage source converter. It contains eight IGBTs S1 to S8 as indi-cated in the figure showing the component symbol. The power module offerstwo configurations:








322


Note The sub-cycle average implementation cannot model a shoot-through orclamping of the DC side. Therefore, the sums of the control signals for switchesmust respect the given restrictions summarized below under the Assertionsparameter at any time. Also, the applied DC voltages must never become nega-tive.



AssertionsWhen set to on, the block will flag an error if the sums of the control sig-nals for:• S1 and S2• S3 and S4• S5 and S8• S6 and S7become large than zero at any point in time.

323


3-Phase Current Source Inverter

Purpose 3-phase 2-level current source inverter IGBT module


Description

This power module implements a 3-phase 2-level current source inverter. Itoffers two configurations:


Sub-cycle average The module as a whole is modeled with controlledvoltage and current sources. The DC side of the inverter has voltage sourcebehavior and must be connected to positively biased inductors or currentsources. The phase terminals are typically connected to filter capacitors. Onlydelta-connected filter capacitors are allowed since no neutral point is consid-ered in the model. The six control inputs are the relative on-times of the IG-BTs with values between 0 and 1.

In the average configuration the 3-phase 2-level current source inverter can beoperated in two ways:



324

3-Phase Current Source Inverter

In both use cases, the average implementation correctly accounts for livetimes, i.e. when during commutation at least one of the upper IGBTs and oneof the lower IGBTs are both turned on to sustain the dc-side externally con-nected current source.

It also supports rectifier operation mode, when power is flowing from AC sideto DC side. In rectifier mode, both cases of free-wheeling diode on dc-side andno free-wheeling diode are included. It has to be specified correctly underParameters of the mask dialogue window.


Note The sub-cycle average implementation cannot model an open circuitof the DC side. Therefore for inverter mode, the sum of the control signals forthe upper three IGBTs and the lower three IGBTs must larger than 1 at anypoint in time. The block will flag an error if this condition is not met. For recti-fier mode, please see the description Free-wheeling Diode parameter below.Also, the applied DC currents must never become negative.


Free-wheeling diode on DC sideThis parameter is only applicable for rectifier mode. The option no meansno extra free-wheeling diode on the DC side is modeled and that the sumof the control signals for the upper three IGBTs and the lower three IG-BTs must be larger than 1 at any point in time. Otherwise the block willflag an error. The option yes means an extra DC-side free-wheeling diodeis included. In this case no flag error will be triggered when the sum of thecontrol signals for the upper three IGBTs and the lower three IGBTs issmaller than 1, because the DC current can flow through this extra free-wheeling diode.

325


3-Phase Voltage Source Inverter

Purpose 3-phase 2-level voltage source inverter IGBT module


Description1

11

1

1

1

1

1

1

1

1

This power module implements a 3-phase 2-level voltage source inverter. Itoffers two configurations:


Sub-cycle average The module as a whole is implemented with 3 half-bridge power modules which are modelled with controlled voltage and currentsources. The DC side of the inverter has current source behavior and must beconnected to a positively biased capacitor or voltage source. The output termi-nal is typically connected to an inductor. The control inputs are the relativeon-times of the IGBTs with values between 0 and 1.

In the average configuration the 3-phase 2-level voltage source inverter can beoperated in two ways:



326

3-Phase Voltage Source Inverter

In both use cases, the average implementation correctly accounts for blank-ing times, i.e. when during commutation both IGBTs are turned off. It alsosupports discontinuous conduction mode, e.g. when charging the DC link ca-pacitor via the reverse diodes.


Note The sub-cycle average implementation cannot model a shoot-through orclamping of the DC side. Therefore, the sums of the control signals for the highand low side IGBTs in each half-bridge must not exceed 1 at any time. Also, theapplied DC voltages must never become negative.



AssertionsWhen set to on, the block will flag an error if the sums of the control sig-nals for any of the four half-bridges exceed 1.

327


3D Look-Up Table

Purpose Compute piece-wise linear function of three input signals


Description

3DTable

xyz

The 3D Look-Up Table block maps three input signals to an output signal.You define the mapping function by specifying three vectors of input valuesand an array of output values. The input vectors x, y and z correspond to thefirst, second and third dimension of the output array.

The output value is interpolated or extrapolated from the block parametersusing the technique described for the 1D Look-Up Table block (see page 314).

Parameters Vector of input values xThe vector of input values x. This vector must be the same size as the sizeof the first dimension in the output array and monotonically increasing. Itshould not contain more than three identical values.

Vector of input values yThe vector of input values y. This vector must be the same size as the sizeof the second dimension in the output array and monotonically increasing.It should not contain more than three identical values.

Vector of input values zThe vector of input values z. This vector must be the same size as the sizeof the third dimension in the output array and monotonically increasing. Itshould not contain more than three identical values.

3D array of output values f(x,y,z)The array containing the output values f(x, y, z). The dimensions mustmatch the size of the input vectors.



Probe Signals Input xThe block input signal x.

Input yThe block input signal y.

328

3D Look-Up Table

Input zThe block input signal z.


329


3-Phase Overmodulation

Purpose Extend linear range of modulation index for 3-phase inverters


Description For three-phase signals, this block extends the linear range of the modulationindex from [-1 1] to [-1.154 1.154] by adding a zero-sequence offset. This blockmay be used for the control of three-phase converters without neutral pointconnection such as the IGBT Converter (see page 470).The figures below illustrates the working principle of the 3-Phase Overmodu-lation block in conjunction with the Symmetrical PWM (see page 671).

−1

0

1

Original modulation indices

−1

0

1

Offset

−1

0

1

Corrected modulation indices

−1

0

1

Resulting pulses

330

6-Pulse Generator

6-Pulse Generator

Purpose Generate firing pulses for 3-phase thyristor rectifier


Description This block generates the pulses used to fire the thyristors of a 6-pulse rectifieror inverter. The inputs of the block are a logical enable signal, a ramp signalϕ (produced e.g. by a PLL), and the firing angle alpha.

If the “Double pulses” option is selected, each thyristor receives two pulses:one when the firing angle is reached, and a second, when the next thyristor isfired.

Parameters Pulse widthThe width of the firing pulses in radians with respect to one period of fun-damental frequency.

Pulse type“Double pulses” enables a second firing pulse for each thyristor.

331


Abs

Purpose Calculate absolute value of input signal

Library Control / Math

Description The Abs block outputs the absolute value of the input signals, y = |u|.



332

Algebraic Constraint

Algebraic Constraint

Purpose Enforce an algebraic constraint by solving a system of equations


Description The Algebraic Constraint block outputs the value that produces zero at the in-put. The output must affect the input by means of a direct feedthrough path.The block ensures that the input signal is zero at all times.

The direct feedthrough path defines a function f of the output signal x. TheAlgebraic Constraint block solves the system of equations f(x) = 0. The inputand output signals must have the same width, i.e. the number of equationsmust equal the number of unknowns.

Note The Algebraic Constraint block creates an algebraic loop. See section“Block Sorting” (on page 31) for more information on algebraic loops.

Parameters Initial guessA guess of the solution x at the start of the simulation. The parameter canbe either a scalar or a vector with the same width as the output and inputsignals. If a scalar is specified, the value is used as an initial guess for allcomponents of the output signal. The default is 0.

Probe Signals ResidualThe constraint residual f .

SolutionThe computed solution x.

333


Ambient Temperature

Purpose Connect to Heat Sink on which component is placed

Library Thermal

Description The Ambient Temperature is only useful in subsystems. When placed in asubsystem, it provides a thermal connection to the heat sink that encloses thesubsystem.

For more information see section “Heat Sinks and Subsystems” (on page 124).

Note Ambient Temperature blocks may not be used in schematics that con-tain Thermal Port blocks (see page 695).

334

Air Gap

Air Gap

Purpose Air gap in a magnetic core

Library Magnetic

Description This component models an air gap in a magnetic core. It establishes a linearrelationship between the magnetic flux Φ and the magneto-motive force F

Φ

F=µ0A

l

where µ0 = 4π × 10−7 N/A2 is the magnetic constant, A is the cross-sectionalarea and l the length of the flux path.

Parameters Cross-sectional areaEffective cross-sectional area A of the air gap, in m2.

Length of flux pathEffective length l of the air gap, in m.

Initial MMFMagneto-motive force at simulation start, in ampere-turns (A).

Probe Signals MMFThe magneto-motive force measured from the marked to the unmarkedterminal, in ampere-turns (A).

FluxThe magnetic flux flowing through the component, in webers (Wb). A fluxentering at the marked terminal is counted as positive.

Field strengthThe magnetic field strength H in the air gap, in A/m.

Flux densityThe magnetic flux density B in the air gap, in teslas (T).

335


Ammeter

Purpose Output measured current as signal

Library Electrical / Meters

Description

A

The Ammeter measures the current through the component and provides itas a signal at the output. The direction of a positive current is indicated witha small arrow in the component symbol. The output signal can be made ac-cessible in Simulink with an Output block (see page 641) or by dragging thecomponent into the dialog box of a Probe block.

Note The Ammeter is ideal, i.e. it has zero internal resistance. Hence, if mul-tiple ammeters are connected in parallel the current through an individual am-meter is undefined. This produces a run-time error.

Likewise, if switches connected in parallel are all in closed position the currentthrough the individual switches is not properly defined. Although this does notproduce a run-time error it may lead to unexpected simulation results.

Probe Signal Measured currentThe measured current in amperes (A).

336

Angle Sensor

Angle Sensor

Purpose Output measured absolute or relative angle as signal

Library Mechanical / Rotational / Sensors

Description The Angle Sensor measures the relative angle of the flange marked with a dotwith respect to the other flange. If the other flange is connected to the refer-ence frame, the absolute angle is measured.

Note Speed and angle sensors are ideally compliant. Hence, if multiple speedor angle sensors are connected in series the speed or angle measured by an in-dividual sensor is undefined. This produces a run-time error.

Parameters Second flangeControls whether the second flange is accessible or connected to the rota-tional reference frame.

Initial angleThe angle at simulation start, in radians.

Probe Signal AngleThe measured angle, in radians.

337


Assert Dynamic Lower Limit

Purpose Issue a warning or an error message when the input exceeds the specified dy-namic lower limit

Library Assertions

Description This block checks whether the middle input signal lies above the other inputsignal. When the check fails, a message is added to the diagnostics windowand the simulation may be paused or stopped.

Parameters LimitEither include or exclude, indicating whether the limit is included in orexcluded from the allowed range.

ActionOne of the following: ignore: the assertion is ignored; warning: whenthe assertion fails, a warning is added to the diagnostics window;warning/pause: when the assertion fails, a warning is added to the diag-nostics window and the simulation is paused; error: when the assertionfails, an error is added to the diagnostics window and the simulation isstopped.

This parameter can be overwritten on a per model basis (see “Simula-tion Parameters” on page 107). Note that during analyses and simulationscripts, assertions may be partly disabled (see “Assertions” on page 90).

MessageThe message that is displayed in the diagnostics window when the asser-tion fails.

Probe Signals InputThe middle input signal.

Assertion value1 while the input is above the lower limit and 0 otherwise.

Lower limitThe lower limit input signal.

338

Assert Dynamic Range

Assert Dynamic Range

Purpose Issue a warning or an error message when the input leaves the specified dy-namic range

Library Assertions

Description This block checks whether the middle input signal lies between the two otherinput signals. When the check fails, a message is added to the diagnosticswindow and the simulation may be paused or stopped.

Parameters LimitsEither include or exclude, indicating whether the limits are included inor excluded from the allowed range.





Assertion value1 while the input is within the range and 0 otherwise.

Upper limitThe upper limit input signal.

Lower limitThe lower limit input signal.

339


Assert Dynamic Upper Limit

Purpose Issue a warning or an error message when the input exceeds the specified dy-namic upper limit

Library Assertions

Description This block checks whether the middle input signal lies below the other inputsignal. When the check fails, a message is added to the diagnostics windowand the simulation may be paused or stopped.

Parameters LimitEither include or exclude, indicating whether the limit is included in orexcluded from the allowed range.





Assertion value1 while the input is below the upper limit and 0 otherwise.

Upper limitThe upper limit input signal.

340

Assertion

Assertion

Purpose Issue a warning or an error message when the input becomes 0

Library Assertions

Description The assertion block checks whether a condition stays true during the simula-tion. While the input signal is non-zero, the block does nothing. When the in-put signal becomes zero, the specified message appears. Depending on the “ac-tion” setting, the message is added either as a warning or as an error to thediagnostics window. If it is added as a warning, it is possible to additionallyautomatically pause the simulation. If it is added as an error, the simulationalways stops. To disable the assertion, set its action to ignore.

Parameters ActionOne of the following: ignore: the assertion is ignored; warning: whenthe assertion fails, a warning is added to the diagnostics window;warning/pause: when the assertion fails, a warning is added to the diag-nostics window and the simulation is paused; error: when the assertionfails, an error is added to the diagnostics window and the simulation isstopped.



Highlight levelThe number of levels the highlight is propagated upwards in the compo-nent hierarchy when the assertion fails. A highlight level of 0 means thatthe assertion block itself will be highlighted when the assertion fails. Ahighlight level of 1 means that the component containing the assertionblock will be highlighted when the assertion fails, etc.

341


Assert Lower Limit

Purpose Issue a warning or an error message when the input exceeds the specifiedlower limit

Library Assertions

Description This block checks whether the input signal lies above the specified lower limit.When the check fails, a message is added to the diagnostics window and thesimulation may be paused or stopped.

Parameters Lower limitA constant specifying the lower limit for the input signal.

LimitEither include or exclude, indicating whether the limit is included in orexcluded from the allowed range.





Assertion value1 while the input is above the lower limit and 0 otherwise.

342

Assert Range

Assert Range

Purpose Issue a warning or an error message when the input leaves the specifiedrange

Library Assertions

Description This block checks whether the input signal lies between the specified lowerand upper limits. When the check fails, a message is added to the diagnosticswindow and the simulation may be paused or stopped.

Parameters Upper limitA constant specifying the upper limit for the input signal.

Lower limitA constant specifying the lower limit for the input signal.

LimitsEither include or exclude, indicating whether the limits are included inor excluded from the allowed range.





Assertion value1 while the input is within the range and 0 otherwise.

343


Assert Upper Limit

Purpose Issue a warning or an error message when the input exceeds the specified up-per limit

Library Assertions

Description This block checks whether the input signal lies below the specified upperlimit. When the check fails, a message is added to the diagnostics window andthe simulation may be paused or stopped.

Parameters Upper limitA constant specifying the upper limit for the input signal.

LimitEither include or exclude, indicating whether the limit is included in orexcluded from the allowed range.





Assertion value1 while the input is below the upper limit and 0 otherwise.

344

Blanking Time

Blanking Time

Purpose Generate commutation delay for 2-level inverter bridges


Description This block generates a blanking time for 2-level inverter bridges so thatthe turn-on of one switch is delayed with respect to the turn-off of the otherswitch in the same inverter leg.

The input s is a switching function with the values -1 and 1 generated by a 2-level modulator such as the Symmetrical PWM generator (see page 671). Thevalues of the output s’ are either -1 (lower switch turned on), 0 (both switchesoff) or 1 (upper switch on). If the input is a vector, the output is also a vectorof the same width.

Parameter Delay timeThe delay in seconds (s) between the turn-off of one switch and the turn-onof the other switch in an inverter leg.

345


Blanking Time (3-Level)

Purpose Generate commutation delay for 3-level inverter bridges


Description This block generates a blanking time for 3-level inverter bridges so thatthe turn-on of one switch is delayed with respect to the turn-off of the otherswitch in the same inverter leg.

The input s is a switching function with the values -1, 0 and 1 generated by a3-level modulator such as the Symmetrical PWM (3-Level) generator (see page673). The values of the output s’ are either -1, -0.5, 0, 0.5 or 1. If the input isa vector, the output is also a vector of the same width.

Parameter Delay timeThe delay in seconds (s) between the turn-off of one switch and the turn-onof another switch in an inverter leg.

346

Breaker

Breaker

Purpose AC circuit breaker opening at zero current

Library Electrical / Switches

Description This component provides an ideal short or open circuit between its two electri-cal terminals. The switch closes when the controlling signal becomes non-zero.It opens when both the signal and the current are zero. Therefore, this circuitbreaker can be used to interrupt inductive AC currents.

Parameter Initial conductivityInitial conduction state of the breaker. The breaker is initially open if theparameter evaluates to zero, otherwise closed. This parameter may eitherbe a scalar or a vector corresponding to the implicit width of the compo-nent. The default value is 0.

Probe Signals Breaker currentThe current through the component in amperes (A). A positive currentflows from the left to the right terminal in the above breaker icon.

Breaker conductivityConduction state of the internal switch. The signal outputs 0 if thebreaker is open, and 1 if it is closed.

347


Brushless DC Machine

Purpose Detailed model of brushless DC machine excited by permanent magnets

Library Electrical / Machines

Description A brushless DC machine is a type of permanent magnet synchronous machinein which the back electromotive force (EMF) is not sinusoidal but has a moreor less trapezoidal shape. Additionally, the variation of the stator inductancewith the rotor position is not necessarily sinusoidal.

The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motor mode,otherwise in generator mode. In the component icon, phase a of the statorwinding is marked with a dot.

Electrical System

La(θe)R ea(θe,ωm)ia

The back EMF voltages are determined by a shape function ke and the me-chanical rotor speed ωm. The shape function in turn is expressed as a fourierseries of the electrical rotor angle θe:

ex(θe, ωm) = ke,x(θe) · ωm

ke,a(θe) =∑n

Kc,n cos(nθe) +Ks,n sin(nθe)

ke,b(θe) =∑n

Kc,n cos(nθe −2πn

3) +Ks,n sin(nθe −

2πn

3)

ke,c(θe) =∑n

Kc,n cos(nθe +2πn

3) +Ks,n sin(nθe +

2πn

3)

348

Brushless DC Machine

The stator self inductance is also expressed as a fourier series of the electricalrotor angle. The mutual inductance M between the stator phases is assumedto be constant. Since the stator windings are star connected, the mutual in-ductance can simply be subtracted from the self inductance:

La(θe) = L0 −M +∑n

Lc,n cos(nθe) + Ls,n sin(nθe)

Electromechanical System

The electromagnetic torque is a superposition of the torque caused by the per-manent magnet and a reluctance torque caused by the non-constant stator in-ductance:

Te =∑

x=a,b,c

ke,xix +p

2

dLxdθe

i2x

The cogging torque is again expressed as a fourier series of the electrical rotorangle:

Tcog(θe) =∑n

Tc,n cos(nθe) + Ts,n sin(nθe)

Mechanical System

Mechanical rotor speed:

ωm =1

J(Te + Tcog(θe)− Fωm − Tm)

Mechanical and electrical rotor angle:

θm = ωm

θe = p · θm

Parameters Back EMF shape coefficientsFourier coefficients Kc,n and Ks,n of the back EMF shape function ke,a(θe)in Vs.

Stator resistanceThe stator resistance R in ohms (Ω).

Stator inductanceThe constant inductance L0 − M and the fourier coefficients Lc,n, Ls,n ofthe phase a inductance La(θe) in henries (H).

349


Cogging torque coefficientsFourier coefficients Tc,n, Ts,n of the cogging torque Tcog(θe) in Nm.

InertiaCombined rotor and load inertia J in Nms2.

Friction coefficientViscous friction F in Nms.

Number of pole pairsNumber of pole pairs p.

Initial rotor speedInitial mechanical speed ωm,0 in radians per second (s−1).

Initial rotor angleInitial mechanical rotor angle θm,0 in radians.

Initial stator currentsA two-element vector containing the initial stator currents ia,0 and ib,0 ofphase a and b in amperes (A).

Probe Signals Stator phase currentsThe three-phase stator winding currents ia, ib and ic, in A. Currents flow-ing into the machine are considered positive.

Back EMFThe back EMF voltages ea, eb, ec in volts (V).

Rotational speedThe rotational speed ωm of the rotor in radians per second (s−1).

Rotor positionThe mechanical rotor angle θm in radians.

Electrical torqueThe electrical torque Te of the machine in Nm.

Cogging torqueThe cogging torque Tcog of the machine in Nm.

ReferencesD. Hanselman, "Brushless permanent magnet motor design, 2nd ed.", The

Writers’ Collective, Mar. 2003.

P. Pillay, R. Krishnan, "Modeling, simulation, and analysis of permanent-magnet motor drives, Part II: The brushless DC motor drive", IEEETrans. on Ind. App., Vol. 25, No. 2, Mar./Apr. 1989.

350

Brushless DC Machine (Simple)


Purpose Simple model of brushless DC machine excited by permanent magnets


Description The simplified Brushless DC Machine is a model of a permanent magnet syn-chronous machine with sinusoidal or trapezoidal back EMF.

The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motor mode,otherwise in generator mode. In the component icon, phase a of the statorwinding is marked with a dot.

Electrical System

LR ea(θe,ωm)ia

The back EMF voltages are determined by a shape function ke and the me-chanical rotor speed ωm. The shape function is a sinusoidal or an ideal trape-zoidal function scaled with the back EMF constant KE.

ex(θe, ωm) = ke,x(θe) · ωm

Sinusoidal back EMF

e

ke,a

/6 5 /6 2K

E

KE

351


Trapezoidal back EMF

e

ke,a

/6 5 /6 2K

E

KE

Electromechanical System

The electromagnetic torque is:

Te =∑

x=a,b,c

ke,xix

Mechanical System

Mechanical rotor speed:

ωm =1

J(Te − Fωm − Tm)

Mechanical and electrical rotor angle:

θm = ωm

θe = p · θm

Parameters Back EMF shapeChoose between sinusoidal and trapezoidal back EMF.

Back EMF constantThe back EMF constant KE in Vs.

Stator resistanceThe stator resistance R in ohms (Ω).

Stator inductanceThe stator inductance L−M in henries (H).



352








Stator flux (dq)The stator flux linkages Ψd and Ψq in the stationary reference frame inVs.




ReferencesD. Hanselman, "Brushless permanent magnet motor design, 2nd ed.", The

Writers’ Collective, Mar. 2003.

P. Pillay, R. Krishnan, "Modeling, simulation, and analysis of permanent-magnet motor drives, Part II: The brushless DC motor drive", IEEETrans. on Ind. App., Vol. 25, No. 2, Mar./Apr. 1989.

See also For back EMF shapes other than sinusoidal or trapezoidal, and/or if the sta-tor inductance L is angle dependent please use the sophisticated model of theBrushless DC Machine (see page 348). The sophisticated BLDC machine canbe configured as a simple BLDC machine with sinusoidal back EMF if the pa-rameters are converted as follows:

Kc,n = [0]

353


Ks,n = [−KE]

L0−M = L−M

Lc,n = [0]

Ls,n = [0]

For machines with sinusoidal back EMF you may also consider to use the Per-manent Magnet Synchronous Machine (see page 564). The parameters can beconverted as follows provided that the stator inductance L is independent ofthe rotor angle:

[Ld Lq] = [L−M L−M ]

ϕ′m = KE/p

354

C-Script

C-Script

Purpose Execute custom C code


Description The C-Script block allows for custom functionality to be implemented in theC programming language. For a detailed description of C-Scripts see chapter“C-Scripts” (on page 199).

The C-Script dialog consists of two tabbed panes that are described below.

Setup

Number of inputs, outputsA positive integer or a vector of positive integers. The length of the vec-tor specifies the number of input or output terminals, the elements in thevector specify the widths of the single terminals. For dynamic sizing setthe width of one or more input terminals to -1; the width will then be de-termined at simulation start depending on the number of elements in thesignal that is connected to the input port. All occurrences of -1 in the in-put and output widths and any other data vector will be expanded to thesame width.

Number of cont. states, disc. states, zero-crossingsA positive or zero integer specifying the sizes of the different data vectors(i.e. continuous and discrete state variables, and zero-crossing signals) thatthe C-Script registers with the solver.

Sample timeA scalar or an n × 2 matrix specifying the block sample time(s). The tablebelow lists the valid parameter values for the different sample time types.For a detailed description of the sample time types see “Sample Time” (onpage 204).

355


Type Value

Continuous [0, 0] or 0

Semi-Continuous [0, -1]

Discrete-Periodic [Tp, To] or Tp Tp: Sample period, Tp > 0

To: Sample offset, 0 ≤ To < Tp

Discrete-Variable [-2, 0] or -2

Direct feedthroughA vector of zeros and ones specifying the direct feedthrough flags for theinput signals. An input signal has direct feedthrough if you need to accessthe current input signal value during the output function call. This has aninfluence on the block sorting order and the occurrence of algebraic loops(see “Block Sorting” on page 31). If the C-Script block has one input termi-nal, a flag in the vector is applied to the respective single element of theinput signal; if the block has multiple input terminals, a flag is applied tothe whole signal of the respective terminal. You can also specify a singlescalar, which then applies to all input signals of all terminals.

Language standardThe language standard used by the compiler. Possible values are C90, C99and C11. The default is C99.

Enable GNU extensionsIf this box is checked, the compiler enables GNU C language features notfound in ISO standard C. These extensions are disabled by default. Forbackward compatibility, the extensions are enabled in models saved withPLECS 4.0 or older in C-Script blocks using the C99 language standard.

Enable runtime checksIf this box is checked, protective code is added to guard against accessviolations when working with block data (i.e. signal values, states, zero-crossing signals etc.). The C-Script function calls are also wrapped withprotective code to prevent you from violating solver policies such as ac-cessing input signals in the output function without enabling directfeedthrough.It is strongly recommended to leave the runtime checks enabled.

ParametersA comma-separated list of expressions that are passed as external param-eters into the C functions. The expressions can reference workspace vari-ables and must evaluate to scalars, vectors, matrices, 3d-arrays or strings.

356

C-Script

Code

The Code pane consists of a combobox for selecting a particular code sectionand a text editor that lets you edit the currently selected code section. For de-tails on the individual sections see “C-Script Functions” (on page 200). Thedifferent macros that you need to use in order to access block data such as in-put/output signals and states are listed in “C-Script Macros” (on page 215).

If you have made changes to the C code, it will be compiled when you clickon Apply or OK. Any errors or warnings that occur during compilation arelisted in a diagnostic window. Small badges next to the line numbers indicatethe problematic code lines. If you move the mouse cursor near such a badge, atooltip with the diagnostics for that line will appear.

A “Find” dialog for finding and optionally replacing certain text is availablefrom the context menu or by pressing Ctrl-F. The dialog has an option tosearch the current code section only (“This section") or all code sections of theC-Script (“All sections").

Probe Signals Input iThe ith input signal.

Output iThe ith output signal.

357


Capacitor

Purpose Ideal capacitor

Library Electrical / Passive Components

Description This component provides one or more ideal capacitors between its two electri-cal terminals. If the component is vectorized, a coupling can be modeled be-tween the internal capacitors. Capacitors may be switched in parallel only iftheir momentary voltages are equal.

See section “Configuring PLECS” (on page 45) for information on how tochange the graphical representation of capacitors.

Note A capacitor may not be connected in parallel with an ideal voltagesource. Doing so would create a dependency between an input variable (thesource voltage) and a state variable (the capacitor voltage) in the underlyingstate-space equations.

Parameters CapacitanceThe value of the capacitor, in farads (F). All finite positive and negativevalues are accepted, including 0. The default is 100e-6.

In a vectorized component, all internal capacitors have the same value ifthe parameter is a scalar. To specify the capacitances individually use avector [C1 C2 . . . Cn] . The length n of the vector determines the compo-nent’s width:

i1

i2...

in

=

C1 0 · · · 0

0 C2 · · · 0...

.... . .

...

0 0 · · · Cn

·

ddtv1

ddtv2

...ddtvn

In order to model a coupling between the internal capacitors enter asquare matrix. The size n of the matrix corresponds to the width of thecomponent:

358

Capacitor

i1

i2...

in

=

C1 C1,2 · · · C1,n

C2,1 C2 · · · C2,n

......

. . ....

Cn,1 Cn,2 · · · Cn

·

ddtv1

ddtv2

...ddtvn

The capacitance matrix must be invertible, i.e. it may not be singular.

Initial voltageThe initial voltage of the capacitor at simulation start, in volts (V). Thisparameter may either be a scalar or a vector corresponding to the width ofthe component. The positive pole is marked with a “+”. The initial voltagedefault is 0.

Probe Signals Capacitor voltageThe voltage measured across the capacitor, in volts (V). A positive voltageis measured when the potential at the terminal marked with “+” is greaterthan the potential at the unmarked terminal.

Capacitor currentThe current flowing through the capacitor, in amperes (A).

359


Clock

Purpose Provide current simulation time

Library Control / Sources

Description The Clock block outputs the current simulation time.

Probe Signal OutputThe time signal.

360

Combinatorial Logic

Combinatorial Logic

Purpose Use binary input signals to select one row from truth table

Library Control / Logical

Description The Combinatorial Logic block interprets its input as a vector of boolean val-ues and outputs a row from the Truth table according to the input values.For an input vector of width n, the truth table must have 2n rows and the rownumber is calculated as r = 1 +

∑i 2n−iui where ui = 1 if the ith input signal

is greater than 0, ui = 0 otherwise, i.e. the first element of the input vector isinterpreted as the most significant bit and the nth element as the least signifi-cant bit.

For example, when using a truth table1.5 0

4 2.5

3 1.5

5.5 0

the output is:

Input Output

[0 0] [1.5 0]

[0 1] [4 2.5]

[1 0] [3 1.5]

[1 1] [5.5 0]

Parameter Truth tableThe truth table used to calculate the output. The table must have 2n rows,and n determines the width of the input signal. The number of columnsdetermines the width of the output signal.

Probe Signals InputThe input signals.

OutputThe output signals.

361


Comparator

Purpose Compare two input signals with minimal hysteresis

Library Control / Discontinuous

Description The Comparator compares two input signals. If the non-inverting input isgreater than the inverting input, the output is 1. The output is set to 0 if thenon-inverting input is less than the inverting one. The output does not changeif both inputs are equal.


OutputThe output signals.

362

Compare to Constant

Compare to Constant

Purpose Compare the input signal to a constant threshold


Description The Compare to Constant block compares the input signal to a thresholdvalue. If the comparison is true it outputs 1, otherwise 0. The input signal isthe first argument and the threshold value the second argument for the com-parison operator.

Parameters Relational operatorChooses which comparison operation is applied to the input signal and thethreshold value. Available operators are• equal (==),• unequal (∼=),• less (<),• less or equal (<=),• greater or equal (>=),• greater (>).

Threshold valueThe value to which the input signal is compared.


OutputThe output signal.

363


Configurable Subsystem

Purpose Provide subsystem with exchangeable implementations

Library System

Description A configurable subsystem is a subsystem that has multiple, exchangeable con-figurations. Each subsystem configuration has its own schematic diagram.

All subsystem configurations of the configurable subsystem share the sameinput, output and physical terminals. Once a port element has been addedto one of the internal schematics it becomes available in all other internalschematics.

By selecting Look under mask from the Subsystem submenu of the Editmenu or the block’s context menu the schematic view of the configurable sub-system is opened. The schematic for each configuration can be accessed bythe tabs on top of the schematic view. New configurations can be added andremoved from the context menu of the tab bar, accessible by right-click. Adouble-click on a configuration tab allows for the corresponding configurationto be renamed.

Note A subsystem (see the Subsystem block on page 662) can be converted toa configurable subsystem by selecting Convert to configurable subsystemfrom the Subsystem submenu of the Edit menu or the block’s context menu.

Parameters ConfigurationThe name of the internal schematic that is used during simulation. Thevariable Configuration can be used in the mask initialization commandsto check the current configuration. It contains an integer value starting at1 for the first configuration.

Additional parameters for the Configurable Subsystem can be created bymasking the block (see “Mask Parameters” (on page 71) for more details).

Probe Signals Probe signals for the Configurable Subsystem can be created by masking theblock (see “Mask Probe Signals” (on page 77) for more details).

364

Configurable Subsystem

Only the probed components from the current configuration are used duringsimulation. To ensure that a Probe signal behaves the same for all configura-tions, it should contain the same number of component signals from each sub-system in the same order. If a configuration does not provide a specific signal,a dummy component (e.g. a Constant block on page 366) can be used.

365


Constant

Purpose Generate constant signal


Description

1

The Constant block outputs a constant signal.

The constant value is displayed in the block if it is large enough, otherwise adefault text is shown. To resize the block, select it, then drag one of its selec-tion handles.

Parameter ValueThe constant value. This parameter may either be a scalar or a vectordefining the width of the component. The default value is 1.

Output data typeThe data type of the output signal. See “Data Types” (on page 42).

Probe Signal OutputThe constant signal.

366

Constant Heat Flow

Constant Heat Flow

Purpose Generate constant heat flow

Library Thermal

Description The Constant Heat Flow generates a constant heat flow between the two ther-mal ports. The direction of a positive heat flow through the component ismarked with an arrow.

Parameter Heat flowThe magnitude of the heat flow, in watts (W). The default is 1.

Probe Signal Heat flowThe heat flow in watts (W).

367


Constant Temperature

Purpose Provide constant temperature

Library Thermal

Description The Constant Temperature generates a constant temperature difference be-tween its two thermal connectors or between the thermal connector and thethermal reference. The temperature difference is considered positive if the ter-minal marked with a “+” has a higher temperature.

Parameter TemperatureThe temperature difference generated by the component, in kelvin (K). Thedefault is 0.

Probe Signal TemperatureThe temperature difference in kelvin (K).

368

Continuous PID Controller


Purpose Implementation of a continuous-time controller (P, I, PI, PD or PID)

Library Control / Continuous

Description

ContinuousPID

e uPID(s)

This block implements a highly configurable continuous-time controller withtwo different anti-windup mechanisms, see subsection Anti-windup meth-ods. The output signal is a weighted sum of at maximum three types of con-trol actions: proportional action, integral action and derivative action. A prac-tical implementation of the derivative action needs an additional first-orderlow-pass filter. The selection of the filter time constant Kf is a trade-off be-tween filtering noise and avoiding interactions with the dominant PID con-troller dynamics. This leads to the transfer function below:

CPID(s) =U(s)

E(s)= Kp +

Ki

s+

Kds1Kfs+ 1

.

+++

Kp

ProportionalGain

Kd

DerivativeGain

Ki

IntegralGain

1/s

+−

1/s

Kf

Derivativefiltercoefficientue

Implementation of a PID controller in parallel form

Anti-windup Methods

Set-point changes together with actuator saturation limits can lead to theintegrator windup effect and degraded controller performance. To avoid thisphenomenon, this component implements the following two mechanisms.

369


Saturation

+++

Kp

ProportionalGain

Kd

DerivativeGain

Ki

IntegralGain

1/s++ +−

+−

1/s

Kf

Derivativefiltercoefficient

Kb

Back-calculationgain

ue u'

Anti-windup scheme with back-calculation

Back-Calculation

The Back-calculation method changes the integral action when the con-troller output is in saturation. The integral term is reduced/increased whenthe controller output is higher/lower than the upper/lower saturation limit.This is done by feeding back the difference between the saturated and the un-saturated controller output. The value of the back-calculation gain Kbc de-termines the rate at which the integrator is reset and is therefore crucial forperformance of the anti-windup mechanism. A common choice for this back-calculation gain is:

Kbc =

√Kd

Ki.

However, this rule can only be applied to full PID controllers. In the case of aPI controller, where Kd = 0, it is suggested that

Kbc =Kp

Ki.

Conditional Integration

The Conditional integration method stops the integration when the con-troller output saturates and the control error e and the control variable u havethe same sign. This means, the integral action is still applied if it helps topush the controller output out of saturation.

370


Saturation

+++

Kp

ProportionalGain

Kd

DerivativeGain

Ki

IntegralGain

1/s +−

+−

1/s

Kf


**

AND

**> 0

NOT

u'

Anti-windup scheme with conditional integration

Anti-Windup with External Saturation

If the saturation is placed externally to the PID controller block, i.e. Satu-ration is set to external, one can still use the above described anti-windupmethods. To feedback the saturated output of the external Saturation block(see page 626) an additional subsystem port u∗ is made visible if the Satura-tion parameter is set to external and the Anti-windup method parametersis set to an option other than none, see the figure below.

ContinuousPID

e uu*

PID(s)

Saturation

REFSetpoint

+−

Scope

nnsn+..+n0dnsn+..+d0Plant

TransferFcn

++

Feedforward

+−

Anti-windup scheme with external saturation

Parameters

371


Basic

Controller typeSpecifies the controller type. The controller can be of type P, I, PI, PD orPID.

Parameter sourceSpecifies whether the controller parameters are provided via the mask pa-rameters (internal) or via input signals (external).

Proportional gain KpThe proportional gain of the controller. This parameter is shown only ifthe Controller type parameter is set to P, PI, PD or PID and the Parame-ter source parameter is set to internal.

Integral gain KiThe integral gain of the controller. This parameter is shown only if theController type parameter is set to I, PI or PID and the Parametersource parameter is set to internal.

Derivative gain KdThe derivative gain of the controller. This parameter is shown only ifthe Controller type parameter is set to PD or PID and the Parametersource parameter is set to internal.

Derivative filter coefficient KfThe filter coefficient which specifies the pole location of the first-order fil-ter in the derivative term. This parameter is shown only if the Controllertype parameter is set to PD or PID and the Parameter source parameteris set to internal.

External resetThe behavior of the external reset input. The values rising, falling andeither cause a reset of the integrator on the rising, falling or both edgesof the reset signal. A rising edge is detected when the signal changes from0 to a positive value, a falling edge is detected when the signal changesfrom a positive value to 0. If level is chosen, the output signal keeps theinitial value while the reset input is not 0. Only the integrator in the inte-gral action is reset.

Initial condition sourceSpecifies wheter the initial condition is provided via the Initial conditionparameter (internal) or via an input signal (external).

372


Initial conditionThe initial condition of the integrator in the integral action. The valuemay be a scalar or a vector corresponding to the implicit width of the com-ponent. This parameter is shown only if the Initial condition source pa-rameter is set to internal.

Anti-Windup

SaturationSpecifies if the internally placed saturation (internal) is used or if theuser wants to place the saturation externally (external) to the PID Con-troller block (see page 369). If external is selected, the internal Satura-tion block (see page 626) is not active.

Saturation limitsSpecifies whether the saturation limits are provided via the mask parame-ters (constant) or via input signals (variable).

Upper saturation limitAn upper limit for the output signal. If the value is inf the output sig-nal is unlimited. If input and output are vectorized signals a vector can beused. The number of elements in the vector must match the number of in-put signals. This parameter is shown only if the Saturation parameter isset to internal and the Saturation limits parameter is set to constant.

Lower saturation limitA lower limit for the output signal. If the value is -inf the output signalis unlimited. If input and output are vectorized signals a vector can beused. The number of elements in the vector must match the number of in-put signals. This parameter is shown only if the Saturation parameter isset to internal and the Saturation limits parameter is set to constant.

Anti-Windup methodSpecifies the method to avoid windup of the integral action. See Anti-windup methods above.

Back-calculation gainThe gain of the back-calculation anti-windup method. This parame-ter is shown only of the Anti-windup method parameter is set toBack-calculation.

Probe Signals Proportional actionProportion of the proportional action of the controller output signal.

373


Integral actionProportion of the integral action of the controller output signal.

Derivative actionProportion of the derivative action of the controller output signal.

Controller output before saturationThe input signal of the saturation block.

Controller output after saturationThe output signal of the saturation block.

ReferencesA. Visioli, “Practical PID Control - Advances in industrial control”, Springer-

Verlag, 2006.

374

Controlled Heat Flow

Controlled Heat Flow

Purpose Generate variable heat flow

Library Thermal

Description The Controlled Heat Flow generates a variable heat flow between the twothermal ports. The direction of a positive heat flow through the component ismarked with an arrow. The momentary heat flow is determined by the signalfed into the input of the component.

Parameter Allow state-space inliningFor expert use only! When set to on and the input signal is a linear com-bination of thermal measurements, PLECS will eliminate the input vari-able from the state-space equations and substitute it with the correspond-ing output variables. The default is off.

Probe Signal Heat flowThe heat flow in watts (W).

375


Controlled Temperature

Purpose Provide variable temperature

Library Thermal

Description The Controlled Temperature generates a variable temperature difference be-tween its two thermal connectors or between the thermal connector and thethermal reference. The temperature difference is considered positive if the ter-minal marked with a “+” has a higher temperature. The momentary temper-ature difference is determined by the signal fed into the input of the compo-nent.

Parameter Allow state-space inliningFor expert use only! When set to on and the input signal is a linear com-bination of thermal measurements, PLECS will eliminate the input vari-able from the state-space equations and substitute it with the correspond-ing output variables. The default is off.

Probe Signal TemperatureThe temperature difference in kelvin (K).

376

Current Source (Controlled)

Current Source (Controlled)

Purpose Generate variable current

Library Electrical / Sources

Description The Controlled Current Source generates a variable current between its twoelectrical terminals. The direction of a positive current through the componentis marked with an arrow. The momentary current is determined by the signalfed into the input of the component.

Note A current source may not be open-circuited or connected in series to aninductor or any other current source.

Parameters Discretization behaviorSpecifies whether a zero-order hold or a first-order hold is applied to theinput signal when the model is discretized. For details, see “PhysicalModel Discretization” (on page 35).

The option Non-causal zero-order hold applies a zero-order hold withthe input signal value from the current simulation step instead of the pre-vious one. This option can be used to compensate for a known delay of theinput signal.

Allow state-space inliningFor expert use only! When set to on and the input signal is a linear com-bination of electrical measurements, PLECS will eliminate the input vari-able from the state-space equations and substitute it with the correspond-ing output variables. The default is off.

Probe Signals Source currentThe source current in amperes (A).

Source voltageThe voltage measured across the source, in volts (V).

Source powerThe instantaneous output power of the source, in watts (W).

377


Current Source AC

Purpose Generate sinusoidal current


Description The AC Current Source generates a sinusoidal current between its two elec-trical terminals. The direction of a positive current is marked with an arrow.The momentary current i is determined by the equation:

i = A · sin(ω · t+ ϕ)

where t is the simulation time.

If a variable-step solver is used, the solver step size is automatically limited toensure that a smooth current waveform is produced.


Parameters Each of the following parameters may either be a scalar or a vector corre-sponding to the implicit width of the component:

AmplitudeThe amplitude A of the current, in amperes (A). The default is 1.

FrequencyThe angular frequency ω, in s−1. The default is 2*pi*50 which corre-sponds to 50 Hz.

PhaseThe phase shift ϕ, in radians. The default is 0.




378

Current Source DC

Current Source DC

Purpose Generate constant current


Description The DC Current Source generates a constant current between its two electri-cal terminals. The direction of a positive current through the component ismarked with an arrow.


Parameter CurrentThe magnitude of the constant current, in amperes (A). This parametermay either be a scalar or a vector defining the width of the component.The default value is 1.




379


D Flip-flop

Purpose Implement edge-triggered flip-flop


Description The D flip-flop sets its output Q to the value of its input D when an edge onthe clock input is detected. The behavior is shown in the following truth table:

D Clk Q /Q

0 0 No change No change




0 Triggering edge 0 1

1 Triggering edge 1 0

The input D is latched, i.e. when a triggering edge in the clock signal is de-tected the value of D from the previous simulation step is used to set the out-put. In other words, D must be stable for at least one simulation step beforethe flip-flop is triggered by the clock signal.

Parameters Trigger edgeThe direction of the edge on which the D input is read.

Initial stateThe state of the flip-flop at simulation start.

Probe Signals DThe input signal D.

ClkThe clock input signal.

QThe output signals Q.

/QThe output signals /Q.

380

Dual Active Bridge Converter

Dual Active Bridge Converter

Purpose Dual Active Bridge converter module


Description1

1

1

1

1

1

1

1

1

1

1

1

L

n:1

Cr

Switched All power semiconductors inside the module are modeled withideal switches. The individual IGBTs are controlled with logical gate signals.An IGBT is on if the corresponding gate signal is not zero. For compatibilitywith the sub-step event configuration it is recommended to use the value 1 fornon-zero gate signals.

Sub-step events The module is implemented with controlled currentsources, on both primary and secondary terminals, instead of ideal switches.Both sides of the converter have current source behavior and must be con-nected to positively biased capacitors or voltage sources.

The control signals are the relative on-times of the IGBTs with values be-tween 0 and 1. They can be seen as the duty cycles of the individual IGBTsduring the simulation step. They are computed by periodically averaging thedigital gate signals over a fixed period of time.

Since the inductor current and capacitor voltage are simulated accurately,even with relatively large time steps, the sub-steps configuration is particu-larly well suited for real-time simulations with high switching frequencies.However, it is not recommended to use discretisation step sizes (sample timeparameter) larger than one fifth of the switching period.

This type of implementation is an extension of the classical “sub-cycle aver-age" implementation, used in the PLECS power modules, which yields moreaccurate simulation results than a purely switched configuration. The accu-racy improvement is obtained by performing sub-step calculations within onesimulation step, which results in the calculation of as many inductor currentvalues as switching combinations encountered during one simulation step.

381


This approach allows for a more accurate calculation of the average inductorcurrent, which is critical to obtain an accurate capacitor voltage calculation.Nevertheless, if the the capacitor voltage changes rapidly between two simula-tion steps, the accuracy of the calculations given by the power module will de-grade. Therefore, in order to maintain high accuracy in the simulated results,the usage of low values of resonant capacitance is not recommended.

Note The sub-steps event implementation cannot model a shoot-through orclamping of the DC side. Therefore, the sums of the control signals for the up-per and lower IGBTs in the same leg must not exceed 1 at any time. Also, theapplied DC voltages must never become negative.

Parameters ConfigurationAllows you to chose between Switched or Sub-step events configuration.


Include resonant capacitorAllows you to include (yes) or remove (no) the resonant capacitor.

Stray inductanceA non-zero scalar specifying the primary side stray inductance of thetransformer, in henries (H).

Winding resistanceA scalar specifying the resistance of the primary winding RL, in ohms (Ω).

Turns ratioA scalar specifying the primary side turns by secondary side turns ratio.

Resonant capacitanceIf the Include resonant capacitor option is set to yes, this parameterrequires a non-zero scalar for the resonant capacitance, in farads (F).

Sample timeIf the Configuration is set to Sub-step events, this parameter requiresa non-zero scalar for the sample time of the component, in seconds (s).


382

Data Type

Data Type

Purpose Cast the input signal to the specified data type.


Description This block casts the input signal to the specified data type. If the input signalalready has the specified data type, this block does nothing.

Parameters Data typeThe data type of the output signal. See “Data Types” (on page 42).

383


DC Machine

Purpose Simple model of DC machine


Description The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motor mode,otherwise in generator mode. In the component icon, the positive poles of ar-mature and field winding are marked with dots.

Electrical System

LaRa

Ea

Lf Rfva

+

−

+

−vf

if

ia

Electromagnetic torque:

Te = Laf · if · iaInduced voltage of the armature winding:

Ea = Laf · if · ωm

Mechanical System

ωm =1


Parameters Armature resistanceArmature winding resistance Ra in ohms (Ω).

Armature inductanceArmature winding inductance La in henries (H).

Field resistanceField winding resistance Rf in ohms (Ω).

384

DC Machine

Armature inductanceField winding inductance Lf in henries (H).

Field-armature mutual inductanceField-armature mutual inductance Laf in henries (H).




Initial rotor positionInitial mechanical rotor angle θm,0 in radians.

Initial armature currentInitial current ia,0 in the armature winding in amperes (A).

Initial field currentInitial current if,0 in the field winding in amperes (A).

Probe Signals Armature currentThe current ia in the armature winding, in amperes (A).

Field currentThe current if in the field winding, in amperes (A).




385


Dead Zone

Purpose Output zero while input signal is within dead zone limits


Description The Dead Zone block outputs zero while the input is within the limits of thedead zone. When the input signal is outside of the dead zone limits, the out-put signal equals the input signal minus the nearest dead zone limit.

Parameters Lower dead zone limitThe lower limit of the dead zone.

Upper dead zone limitThe upper limit of the dead zone.



386

Delay

Delay

Purpose Delay input signal by given number of samples

Library Control / Discrete

Description The Delay block delays the input signal by N sample periods.

Parameters Delay orderThe number of delay periods applied to the input signal.

Initial conditionA scalar, vector or matrix that defines the initial values of the internalstates. The number of rows must be 1 or equal to the width of the in-put signal; the number of columns must be 1 or equal to the delay order.Scalar dimensions are expanded as needed.

Sample timeThe length of the sample period in sec. See also the Discrete-Periodicsample time type in section “Sample Times” (on page 38).

Probe Signals InputThe input signal.

OutputThe delayed output signal.

387


Diode

Purpose Ideal diode with optional forward voltage and on-resistance

Library Electrical / Power Semiconductors

Description The Diode is a semiconductor device controlled only by the voltage across itand the current through the device. The Diode model is basically an idealswitch that closes when the voltage between anode and cathode becomes pos-itive and opens when the current through the component becomes negative.In addition to the ideal switch, a forward voltage and an on-resistance may bespecified. These parameters may either be scalars or vectors corresponding tothe implicit width of the component. If unsure set both values to 0.

Parameters The following parameters may either be scalars or vectors corresponding tothe implicit width of the component:

Forward voltageAdditional dc voltage Vf in volts (V) between anode and cathode when thediode is conducting. The default is 0.

On-resistanceThe resistance Ron of the conducting device, in ohms (Ω). The default is 0.

Thermal descriptionSwitching losses, conduction losses and thermal equivalent circuit of thecomponent. For more information see chapter “Thermal Modeling” (onpage 119). If no thermal description is given the losses are calculatedbased on the voltage drop von = Vf +Ron · i.

Initial temperatureThis parameter is used only if the device has an internal thermalimpedance and specifies the temperature of the thermal capacitance at thejunction at simulation start. The temperatures of the other thermal capac-itances are initialized based on a thermal “DC” analysis. If the parameteris left blank, all temperatures are initialized from the external tempera-ture. See also “Temperature Initialization” (on page 125).

Note Under blocking conditions the diode voltage is negative. Hence youshould define the turn-on and turn-off loss tables for negative voltages. Seechapter “Diode Losses” (on page 145) for more information.

388

Diode

Probe Signals Diode voltageThe voltage measured between anode and cathode.

Diode currentThe current through the diode flowing from anode to cathode.

Diode conductivityConduction state of the internal switch. The signal outputs 0 when thediode is blocking, and 1 when it is conducting.

Diode junction temperatureTemperature of the first thermal capacitor in the equivalent Cauer net-work.

Diode conduction lossContinuous thermal conduction losses in watts (W). Only defined if thecomponent is placed on a heat sink.

Diode switching lossInstantaneous thermal switching losses in joules (J). Only defined if thecomponent is placed on a heat sink.

389


Diode with Reverse Recovery

Purpose Dynamic diode model with reverse recovery


Description This component is a behavioral model of a diode which reproduces the ef-fect of reverse recovery. This effect can be observed when a forward biaseddiode is rapidly turned off. It takes some time until the excess charge storedin the diode during conduction is removed. During this time the diode rep-resents a short circuit instead of an open circuit, and a negative current canflow through the diode. The diode finally turns off when the charge is sweptout by the reverse current and lost by internal recombination.

Note

• Due to the small time-constant introduced by the turn-off transient a stiffsolver is recommended for this device model.

• If multiple diodes are connected in series the off-resistance may not be infi-nite.

The following figure illustrates the relationship between the diode parametersand the turn-off current waveform. If0 and dIr/dt denote the continuous for-ward current and the rated turn-off current slope under test conditions. Theturn-off time trr is defined as the period between the zero-crossing of the cur-rent and the instant when it becomes equal to 10% of the maximum reversecurrent Irrm. The reverse recovery charge is denoted Qrr. Only two out of thethree parameters trr, Irrm, and Qrr need to be specified since they are linkedgeometrically. The remaining parameter should be set to 0. If all three param-eters are given, Qrr is ignored.

The equivalent circuit of the diode model is shown below. It is composed of aresistance, and inductance, and a controlled current source which is linearlydependent on the inductor voltage. The values of these internal elements areautomatically calculated from the diode parameters.

Parameters Forward voltageAdditional dc voltage Vf in volts (V) between anode and cathode when thediode is conducting. The default is 0.

390

Diode with Reverse Recovery

−Irrm

/10

trr

If0

dIr/dt

Qrr

t

iD

−Irrm

RL vL K · vL

Ron

Roff

Lrr


Off-resistanceThe resistance Roff of the blocking device, in ohms (Ω). The default is 1e6.This parameter may be set to inf unless multiple diodes are connected inseries.

Continuous forward currentThe continuous forward current If0 under test conditions.

Current slope at turn-offThe turn-off current slope dIr/dt under test conditions.

Reverse recovery timeThe turn-off time trr under test conditions.

Peak recovery currentThe absolute peak value of the reverse current Irrm under test conditions.

391


Reverse recovery chargeThe reverse recovery charge Qrr under test conditions. If both trr and Irrmare specified, this parameter is ignored.

LrrThis inductance acts as a probe measuring the di/dt. It should be set to avery small value. The default is 10e-10.



Diode conductivityConduction state of the internal switch. The signal outputs 0 when thediode is blocking, and 1 when it is conducting.

ReferencesA. Courtay, "MAST power diode and thyristor models including automatic

parameter extraction", SABER User Group Meeting Brighton, UK, Sept.1995.

392

Diode Rectifier (3ph)

Diode Rectifier (3ph)

Purpose 3-phase diode rectifier

Library Electrical / Converters

Description Implements a three-phase rectifier based on the Diode model (see page 388).The electrical circuit for the rectifier is given below:

D2

a

b

c

D1

D4

D3

D6

D5

Parameters For a description of the parameters see the documentation of the Diode (onpage 388).

Probe Signals The Diode Rectifier provides six probe signals, each a vector containing theappropriate quantities of the six individual diodes: voltage, current, conduc-tivity, conduction loss and switching loss. The vector elements are ordered ac-cording to the natural sequence of commutation.

393


Discrete Fourier Transform

Purpose Perform discrete Fourier transform on input signal


Description This block calculates the discrete Fourier transform of a periodic input signalbased on discrete samples. The sample time, the number of samples and theharmonic order(s) can be specified. The fundamental frequency f1 of the run-ning window is:

f1 =1

sample time× number of samples.

The outputs of the block are the magnitude and phase angle of the specifiedharmonics.

If you specify more than one harmonic, the outputs will be vectors with thecorresponding width. Alternatively you can specify a single harmonic and feeda vector signal into the block.

Parameters Sample timeThe time interval between samples. See also the Discrete-Periodic sam-ple time type in section “Sample Times” (on page 38).

Number of samplesThe number of samples used to calculate the Fourier transform.

Harmonic orders nA scalar or vector specifying the harmonic component(s) you are interestedin. Enter 0 for the dc component, 1 for the fundamental component, etc.This parameter should be scalar if the input signal is a vector.


MagnitudeThe first output signal, i.e. the computed magnitude.

PhaseThe second output signal, i.e. the computed phase angle, in radians.

394

Discrete Integrator

Discrete Integrator

Purpose Discrete integration of the input signal


Description The Discrete Integrator block outputs the integral of its input signal at thecurrent sample time step. The integrator state may saturate at an upper andlower limit, or it can be wrapped between two limits. It can be reset to its ini-tial value by an external trigger signal.

Integration Methods

You can choose between three integration methods using the Integrationmethod parameter: Forward Euler, Backward Euler and Trapezoidal. Theoutput and update equations for these methods are listed below:

Forward Euler

First simulation step:

y[0] = x[0]

x[1] = y[0]

Subsequent simulation steps:

y[k] = x[k] + T · u[k − 1]

x[k + 1] = y[k]

Backward Euler


y[0] = x[0]

x[1] = y[0]


y[k] = x[k] + T · u[k]

x[k + 1] = y[k]

395


Trapezoidal


y[0] = x[0]

x[1] = y[0]


y[k] = x[k] +T

2· (u[k − 1] + u[k])

x[k + 1] = y[k]

In the above equations, if the block has a fixed-step discrete sample time (ei-ther inherited or specified explicitly), T equals the sample period. If the blockis executed within a triggered subsystem, T equals the time span between theprevious and the current trigger.

The first simulation step refers to the first time the block executes after a sim-ulation has been started from the initial block parameters (as opposed to astored system state) or – if the block is executed within an enabled subsys-tem – after the block has been enabled. If the block is executed within a trig-gered subsystem, the first execution after simulation start is always treated asa first simulation step even if the simulation is restarted from a stored systemstate because the value of T cannot be determined in this case.

Note If the Backward Euler or Trapezoidal integration method is used, theinput signal has direct feedthrough on the output signal.

Reset Behavior

The integrator may be reset to its initial condition by an external input signal.This is controlled by the External reset parameter. The available options arerising/falling/either edge or level as described below:

396

Discrete Integrator

Rising Edge Reset

The block output and state are reset to the initial condition if the current re-set input value is non-zero and the previous reset input value was zero.

Falling Edge Reset

The block output and state are reset to the initial condition if the current re-set input value is zero and the previous reset input value was non-zero.

Either Edge Reset

The block output and state are reset to the initial condition if the current re-set input value is non-zero and the previous reset input value was zero or ifthe current reset input value is zero and the previous reset input value wasnon-zero.

Level Reset

The block output and state are reset to and held at the initial condition whilethe current reset input value is non-zero.

Note Both the external reset input and the initial condition input have directfeedthrough on the output signal. Therefore, feeding back the output signal tocreate the reset signal or an initial value will create an algebraic loop. This canbe avoided by using the state port instead.

Parameters External resetThe behaviour of the external reset input. See Reset Behavior above.

Initial condition sourceSpecifies whether the initial condition is provided via the Initial condi-tion parameter (internal) or via an input signal (external).

Initial conditionThe initial condition of the integrator. The value may be a scalar or a vec-tor corresponding to the width of the component. This parameter is shownonly if the Initial condition source parameter is set to internal.

397


Show state portSpecifies whether to show an additional state output port. The state portis updated at a slightly different point in the block execution order (i.e. be-fore the reset and initial condition inputs are evaluated) and may thereforebe used to calculate an input signal for the external reset input or the ini-tial condition input.

Enable wrappingWhen set to on, the integrator state is wrapped between the Upper wrap-ping limit and Lower wrapping limit parameters. The default is off.Note that wrapping is mutually exclusive with saturation.

Upper saturation limitAn upper limit for the integrator state. If the value is inf, the state is un-limited. This parameter is visible only if Enable wrapping is set to off.

Lower saturation limitA lower limit for the integrator state. If the value is -inf, the state is un-limited. This parameter is visible only if Enable wrapping is set to off.

Upper wrapping limitThe upper wrapping limit for the integrator state. When the state exceedsthe upper limit, it is wrapped to the lower limit. This parameter is visibleonly if Enable wrapping is set to on.

Lower wrapping limitThe lower wrapping limit for the integrator state. When the state exceedsthe lower limit, it is wrapped to the upper limit. This parameter is visibleonly if Enable wrapping is set to on.

Integration methodThe method used to integrate the input signal. See Integration Methodsabove.

Sample timeThe time interval between samples. See also the Discrete-Periodic sam-ple time type in section “Sample Times” (on page 38).

Probe Signal StateThe internal state of the integrator.

398

Discrete Mean Value

Discrete Mean Value

Purpose Calculate running mean value of input signal


Description This block calculates the running mean of the input signal based on discretesamples. The sample time and the number of samples can be specified. Theblock is implemented with a shift register. The output of the block is the sumof all register values divided by the number of samples.

Parameters Initial conditionThe initial condition describes the input signal before simulation start. Ifthe input is a scalar signal the parameter can either be a scalar or a col-umn vector. The number of elements in the vector must match the value ofthe parameter Number of samples - 1. If input and output are vectorizedsignals a matrix can be used. The number of rows must be 1 or match thenumber of input signals. The default value of this parameter is 0.


Number of samplesThe number of samples used to calculate the mean value.


MeanThe output signal, i.e. the computed mean value.

399


Discrete PID Controller

Purpose Implementation of a discrete-time controller (P, I, PI, PD or PID)


Description

DiscretePID

e uPID(z)

This block implements a highly configurable discrete-time controller with twodifferent anti-windup mechanisms. The output signal is a weighted sum of atmaximum three types of control actions: proportional action, integral actionand derivative action. The derivative action is filtered with a first-order low-

+++

Kp

ProportionalGain

Kd

DerivativeGain

Ki

IntegralGain

+− Kf


Tz-1

Tz-1

Implementation of a discrete PID controller in parallel form

pass filter. This filter is always integrated with the Forward Euler method.The selection of the filter time constant Kf is a trade-off between filteringnoise and avoid interactions with the dominant PID controller dynamics. Thisleads to the discrete transfer function below:

CPID(z) =U(z)

E(z)= Kp +Kiq(z) +Kd

Kf

1 +KfTz−1

.

If Forward Euler is selected in the Integration Method parameter, then

q(z) =T

z − 1,

for Backward Euler

q(z) =Tz

z − 1,

400


and for Trapezoidal

q(z) =T

2

z + 1

z − 1.

All other block parameters are explained in the continuous version of the PIDcontroller (see page 369).

ParametersBasic

Controller typeSpecifies the controller type. The controller can be of type P, I, PI, PD orPID.

Parameter sourceSpecifies whether the controller parameters are provided via the mask pa-rameters (internal) or via input signals (external).

Proportional gain KpThe proportional gain of the controller. This parameter is shown only ifthe Controller type parameter is set to P, PI, PD or PID and the Parame-ter source parameter is set to internal.

Integral gain KiThe integral gain of the controller. This parameter is shown only if theController type parameter is set to I, PI or PID and the Parametersource parameter is set to internal.

Derivative gain KdThe derivative gain of the controller. This parameter is shown only ifthe Controller type parameter is set to PD or PID and the Parametersource parameter is set to internal.

Derivative filter coefficient KfThe filter coefficient which specifies the pole location of the first-order fil-ter in the derivative term.

External resetThe behavior of the external reset input. The values rising, falling andeither cause a reset of the integrator on the rising, falling or both edgesof the reset signal. A rising edge is detected when the signal changes from0 to a positive value, a falling edge is detected when the signal changesfrom a positive value to 0. If level is chosen, the output signal keeps theinitial value while the reset input is not 0. Only the integrator in the inte-gral action is reset.

401


Initial condition sourceSpecifies wheter the initial condition is provided via the Initial conditionparameter (internal) or via an input signal (external).

Initial conditionThe initial condition of the integrator in the integral action. The valuemay be a scalar or a vector corresponding to the implicit width of the com-ponent. This parameter is shown only if the Initial condition source pa-rameter is set to internal.

Anti-Windup

SaturationSpecifies if the internally placed saturation (internal) is used or if theuser wants to place the saturation externally (external). If external isselected, the internal Saturation block (see page 626) is not active.

Saturation limitsSpecifies whether the saturation limits are provided via the mask parame-ters (constant) or via input signals (variable).

Upper saturation limitAn upper limit for the output signal. If the value is inf the output signalis unlimited. If input and output are vectorized signals a vector must beused. The number of elements in the vector must match the number of in-put signals. This parameter is shown only if the Saturation parameter isset to internal and the Saturation limits parameter is set to constant.

Lower saturation limitA lower limit for the output signal. If the value is -inf the output signalis unlimited. If input and output are vectorized signals a vector must beused. The number of elements in the vector must match the number of in-put signals. This parameter is shown only if the Saturation parameter isset to internal and the Saturation limits parameter is set to constant.

Anti-Windup methodSpecifies the method to avoid windup of the integral action. See also theAnti-windup Methods in the PID Controller block (see page 369).

Back-calculation gainThe gain of the back-calculation anti-windup method. This parame-ter is shown only of the Anti-windup method parameter is set toBack-calculation.

402


Discrete-time settings

Integration methodThe method used to integrate the input signal. This parameter affects theintegrator of the integral action only. Please note, that the first-order low-pass filter in the derivative action is always integrated using the ForwardEuler method. See also the Integration Methods in the Discrete Integra-tor Block (see page 395).


Probe Signals Proportional actionProportion of the proportional action of the controller output signal.

Integral actionProportion of the integral action of the controller output signal.

Derivative actionProportion of the derivative action of the controller output signal.

Controller output before saturationThe input signal of the saturation block.

Controller output after saturationThe output signal of the saturation block.

ReferencesA. Visioli, “Practical PID Control - Advances in industrial control”, Springer-

Verlag, 2006.

403


Discrete RMS Value

Purpose Calculate root mean square (RMS) value of input signal


Description This block calculates the RMS value of a periodic input signal based on dis-crete samples. The sample time and the number of samples can be specified.The fundamental frequency f of the running window is

f =1


The Discrete RMS Value block is implemented with the Discrete Mean Valueblock (see page 399).

Parameters Initial conditionThe initial condition describes the input signal before simulation start. Ifthe input is a scalar signal the parameter can either be a scalar or a col-umn vector. The number of elements in the vector must match the value ofthe parameter Number of samples - 1. If input and output are vectorizedsignals a matrix can be used. The number of rows must be 1 or match thenumber of input signals. The default value of this parameter is 0.


Number of samplesThe number of samples used to calculate the RMS value.

404

Discrete State Space

Discrete State Space

Purpose Implement discrete time-invariant system as state-space model


Description The Discrete State Space block models a state space system of the formxi+1 = Axi + Bui, yi = Cxi + Dui, where xi is the state vector at sample timestep i, u is the input vector, and y is the output vector.

Parameters A,B,C,DThe coefficient matrices for the discrete state space system. The dimen-sions for the coefficient matrices must conform to the dimensions shown inthe diagram below:

where n is the number of states, m is the width of the input signal and pis the width of the output signal.


Initial conditionA vector of initial values for the state vector, x.

Probe Signals InputThe input vector, u.

OutputThe output vector, y.

405


Discrete Total Harmonic Distortion

Purpose Calculate total harmonic distortion (THD) of input signal


Description This block calculates the total harmonic distortion of a periodic input signalbased on discrete samples. The sample time and the number of samples canbe specified. The THD is defined as:

THD =

√√√√ ∑ν≥2

U2ν

U21

=

√U2

rms − U20 − U2

1

U21

where Uν is the RMS value of the νth harmonic of the input signal and Urms isits overall RMS value. The fundamental frequency f1 of the running windowis

f1 =1


Parameters Sample timeThe time interval between samples. See also the Discrete-Periodic sam-ple time type in section “Sample Times” (on page 38).

Number of samplesThe number of samples used to calculate the THD.

406

Discrete Transfer Function

Discrete Transfer Function

Purpose Model discrete system as transfer function


Description The Discrete Transfer Function models a discrete time-invariant system thatis expressed in the z-domain:

Y (z)

U(z)=nnz

n + · · ·+ n1z + n0

dnzn + · · ·+ d1z + d0

The transfer function is displayed in the block if it is large enough, otherwisea default text is shown. To resize the block, select it, then drag one of its se-lection handles.

Parameters Numerator coefficientsA vector of the z term coefficients [nn . . . n1, n0] for the numerator, writtenin descending order of powers of z. For example, the numerator z3 + 2zwould be entered as [1,0,2,0].The output of the Transfer Function is vectorizable by entering a matrixfor the numerator.

Denominator coefficientsA vector of the z term coefficients [dn . . . d1, d0] for the denominator, writtenin descending order of powers of z.

Note The order of the denominator (highest power of z) must be greater thanor equal to the order of the numerator.


Initial conditionThe initial condition vector of the internal states of the Transfer Functionin the form [xn . . . x1, x0]. The initial conditions must be specified for thecontroller normal form, depicted below for the transfer function:

Y (z)

U(z)=n2z

2 + n1z + n0

d2z2 + d1z + d0

407


a1

a0

a2

b0

b1

b2z-1

++

+++−

++

x1 x0 Y(z)U(z)z-1

ZOH

where

bi = didn

for i < n

bn = 1dn

ai = ni − nndidn

for i < n

an = nn

For the normalized transfer function (with nn = 0 and dn = 1) this simpli-fies to bi = di and ai = ni.



408

Display

Display

Purpose Display signal values in the schematic

Library System

Description The display block shows the numeric value of the input signal. The value isupdated while the simulation is running.

Parameters NotationThis parameter determines if the value of the signal is displayed in deci-mal or scientific notation, e.g. “0.123” or “1.23e-1”, respectively.

PrecisionThe precision determines the number of digits after the dot. The allowedrange of this parameter is 0 to 16.

409


DLL

Purpose Interface with externally generated dynamic-link library


Description The DLL block allows you to load a user generated DLL. The DLL may be im-plemented in any programming language on any development environmentthat the system platform supports. For convenience, all code snippets in thisdescription are given in C.

The DLL must supply two functions, plecsSetSizes and plecsOutput. Addi-tionally it may implement the functions plecsStart and plecsTerminate.

The complete DLL interface is described in the fileinclude/plecs/DllHeader.h in the PLECS installation directory. Thisfile should be included when implementing the DLL.

void plecsSetSizes(struct SimulationSizes* aSizes)

This function is called once during the initialization of a new simulation.

The parameter struct SimulationSizes is defined as follows:

struct SimulationSizes int numInputs;int numOutputs;int numStates;int numParameters;

;

In the implementation of plecsSetSizes the DLL has to set all the fields ofthe supplied structure.

numInputsThe width of the input signal that the DLL expects. The length of theinput array in the SimulationState struct is set to this value.

numOutputsThe number of outputs that the DLL generates. The width of the out-put signal of the DLL block and the length of the output array in theSimulationState struct is set to this value.

410

DLL

numStatesThe number of discrete states that the DLL uses. The length of the statesarray in the SimulationState struct is set to this value.

numParametersThe length of the parameter vector that the DLL expects. A vector withnumParameters elements must be supplied in the Parameters field of thecomponent parameters of the DLL block. The parameters are passed inthe parameters array in the SimulationState struct.

void plecsOutput(struct SimulationState* aState)

This function is called whenever the simulation time reaches a multiple of theSample time of the DLL block.

The parameter struct SimulationState is defined as follows:

struct SimulationState const double* const inputs;double* const outputs;double* const states;const double* const parameters;const double time;const char* errorMessage;void* userData;

;

inputsThe values of the input signal for the current simulation step. The valuesare read-only. The array length is the value of the numInputs field thatwas set in the plecsSetSizes method.

outputsThe output values for the current simulation step. These values must beset by the DLL. The array length is the value of the numOutputs field thatwas set in the plecsSetSizes method.

statesThe values of the discrete states of the DLL. These values can be read andmodified by the DLL. The array length is the value of the numStates fieldthat was set in the plecsSetSizes method.

parametersThe values of the parameters that were set in the Parameters field in thecomponent parameters of the DLL block. The values are read-only. The

411


array length is the value of the numParameters field that was set in theplecsSetSizes method.

timeThe simulation time of the current simulation step.

errorMessageThe DLL may indicate an error condition by setting an error message. Thesimulation will be stopped after the current simulation step.

userDataA pointer to pass data from one call into the DLL to another. The value isnot touched by PLECS.

void plecsStart(struct SimulationState* aState)

This function is called once at the start of a new simulation. It may be usedto set initial outputs or states, initialize internal data structures, acquire re-sources etc.

The values of the inputs array in the SimulationState struct are undefinedin the plecsStart function.

void plecsTerminate(struct SimulationState* aState)

This function is called once when the simulation is finished. It may be used tofree any resources that were acquired by the DLL.

Note The processor architecture of the DLL must match the processor archi-tecture of PLECS. If, for example, a 32-bit version of PLECS is used on a 64-bitWindows machine, a 32-bit DLL must be built. The processor architecture usedby PLECS is displayed in the About PLECS ... dialog, accessible from the Filemenu.

Parameters FilenameThe filename of the DLL. If the filename does not contain the full pathof the DLL, the DLL is searched relative to the directory containing themodel file. If no DLL is found with the given filename, a platform specificending will be attached to the filename and the lookup is retried. The end-ings and search order are listed in the table below.

412

DLL

Platform Filename search order

Windows 32-bit filename, filename.dll, filename_32.dll

Windows 64-bit filename, filename.dll, filename_64.dll

macOS 32-bit filename, filename.dylib, filename_32.dylib

macOS 64-bit filename, filename.dylib, filename_64.dylib

Linux 64-bit filename, filename.so, filename_64.so

Sample timeDetermines the time steps, at which the output function of the DLL iscalled. Valid inputs are a Discrete-Periodic or an Inherited sampletime. See also section “Sample Times” (on page 38).

Output delayAllows you to delay the output in each simulation step. This is usefulwhen modeling, for example, a DSP that needs a certain processing timeto calculate the new outputs. The output delay must be smaller than thesample time. If the output delay is a positive number, the DLL block hasno direct feedthrough, i.e. its outputs can be fed back to its inputs with-out causing an algebraic loop. If an inherited sample time is specified, theoutput delay must be zero.

ParametersArray of parameter values to pass to the DLL. The length of the arraymust match the value of the numParameters field that the DLL sets in theplecsSetSizes method.



413


Double Switch

Purpose Changeover switch with two positions


Description This changeover switch provides an ideal short or open circuit. If the inputsignal is zero the switch is in the upper position. For all other values theswitch is in the lower position.

Parameter Initial positionInitial position of the switch. The switch is initially in the upper positionif the parameter evaluates to zero. For all other values it is in the lowerposition. This parameter may either be a scalar or a vector correspondingto the implicit width of the component. The default value is 0.

Probe Signal Switch positionState of the internal switches. The signal outputs 0 if the switch is in theupper position, and 1 if it is in the lower position.

414

Dynamic Signal Selector

Dynamic Signal Selector

Purpose Select or reorder elements from vectorized signal depending on control signal.

Library System

Description The block generates an output vector signal that consists of the specified el-ements of the input vector signal. The elements can be dynamically selectedwith the control input.

See also the Signal Selector block (see page 643).

Parameters Default indexThe default element if the control signal is out of range.



Switch positionThe state of the switch position. This is the control signal or, in case thecontrol signal is out of range, the default index.

Out of rangeA boolean value that is true if the control input is out of range.

415


Edge Detection

Purpose Detect edges of pulse signal in given direction


Description The output of the edge detection block changes to 1 when an edge is detectedon the input signal. It returns to 0 in the following simulation step.

The block allows you to detect the following edges:

risingThe output is set to 1 when the input changes from 0 to a non-zero value.

fallingThe output is set to 1 when the input changes from a non-zero value to 0.

eitherThe output is set to 1 when the input changes from 0 to a non-zero valueor vice versa.

Parameter Edge directionThe direction of the edges to detect, as described above.



416

Electrical Algebraic Component

Electrical Algebraic Component

Purpose Define an algebraic constraint in terms of voltage and current


Description The Electrical Algebraic Component enforces an arbitrary algebraic constraintinvolving voltage and current. The small dot marks the positive terminal.

The output signal “v” measures the voltage across the component from thepositive to the negative terminal. The output signal “i” measures the currentflowing into the positive terminal. The two output signals must affect the in-put signal “0” by means of a direct feedthrough path. The component ensuresthat the input signal is zero at all times.

The direct feedthrough path defines a function f(v, i), which in turn implicitlydetermines the current-voltage characteristic of the component through theconstraint f(v, i) = 0. For instance, the choice f(v, i) := v − R · i causes theElectrical Algebraic Component to act as an ideal resistor with resistance R.

The Electrical Algebraic Component can be vectorized. The three signals “v”,“i” and “0” must have the same width.

By way of illustration, the following schematic shows a possible implementa-tion of a variable resistor:

Note The Electrical Algebraic Component creates an algebraic loop. See sec-tion “Block Sorting” (on page 31) for more information on algebraic loops.

417


Probe Signals Component voltageThe voltage measured across the component from the positive to the nega-tive terminal.

Component currentThe current flowing into the positive terminal of the component.

Component powerThe power consumed by the component.

418

Electrical Ground

Electrical Ground

Purpose Connect to common electrical ground

Library System

Description The ground block implements an electrical connection to the ground.

Note PLECS does not require a circuit to be grounded at one or more points.The ground block just provides a convenient means to connect distant points toa common potential.

419


Electrical Label

Purpose Connect electrical potentials by name

Library System

Description The Electrical Label block provides an electrical connection between otherElectrical Label blocks with identical tag names within the same scope.

The parameter dialog of the Electrical Label block provides a list of links tothe corresponding blocks, i.e. all other Electrical Label blocks with a match-ing tag name and scope. Note that the list is not updated until you click theApply button after changing the tag name or scope.

Parameters Tag name:The tag name is used to find other matching Electrical Label blocks to con-nect to.

Scope:The scope specifies the search depth for the matching Electrical Labelblocks. Using the value Global the complete PLECS circuit is searched.When set to Schematic only the schematic containing the Electrical Labelblock is searched. The setting Masked Subsystem causes a lookup withinthe hierarchy of the masked subsystem in which the block is contained. Ifthe block is not contained in a masked subsystem a global lookup is done.

420

Electrical Model Settings

Electrical Model Settings

Purpose Configure settings for an individual electrical model.

Library Electrical / Model Settings

Description The Electrical Model Settings block lets you configure parameter settings thatinfluence the code generation for a particular electrical system, see also “CodeGeneration for Physical Systems” (on page 263).

The block affects the electrical circuit that it is attached to by its electricalterminal. At most one Model Settings block may be attached to an individualstate-space system. An electrical model can be split into multiple state-spacesystems if the underlying model equations are fully decoupled. See also theoptions Enable state-space splitting and Display state-space splitting inthe “Simulation Parameters” (on page 107).

Parameters Switching algorithmThis parameter allows you two choose between two algorithms to deter-mine the switch conduction states in the generated code. See “SwitchingAlgorithm” (on page 265) for details.

Matrix coding styleThis setting allows you to specify the format used for storing the state-space matrices for a physical model. When set to sparse, only the non-zero matrix entries and their row and column indices are stored. Whenset to full, matrices are stored as full m × n arrays. When set to full(inlined), the matrices are additionally embedded in helper functions,which may enable the compiler to further optimize the matrix-vector-multiplications at the cost of increased code size.

TopologiesThis parameter lets you specify a matrix containing the combinations ofswitch conduction states, for which code should be generated, see also “Re-ducing the Code Size” (on page 264). The columns represent the switchelements of the physical model and each row represents one combinationof switch states (zero for an open switch and non-zero for a closed switch).

The default is an empty matrix [], which means that all possible combina-tions are included.

421


Electrical Port

Purpose Add electrical connector to subsystem

Library System

Description Electrical ports are used to establish electrical connections between aschematic and the subschematic of a subsystem (see page 662). If you copyan Electrical Port block into the schematic of a subsystem, a terminal will becreated on the subsystem block. The name of the port block will appear as theterminal label. If you choose to hide the block name, the terminal label willalso disappear.

Terminals can be moved around the edges of the subsystem by holding downthe Shift key while dragging the terminal with the left mouse button or byusing the middle mouse button.

Electrical Ports in a Top-Level Schematic

In PLECS Blockset, if an Electrical Port is placed in a top-level schematic, thePLECS Circuit block in the Simulink model will show a corresponding elec-trical terminal, which may be connected with other electrical terminals of thesame or a different PLECS Circuit block. The Electrical Port is also assigneda unique physical port number. Together with the parameter Location oncircuit block the port number determines the position of the electrical ter-minal of the PLECS Circuit block.

For compatibility reasons you can also place an Electrical Port in a top-levelschematic in PLECS Standalone. However, since there is no parent system toconnect to, such a port will act like an isolated node.

Parameter WidthThe width of the connected wire. The default auto means that the width isinherited from connected components.

Port numberIf an Electrical Port is placed in a top-level schematic in PLECS Blockset,this parameter determines the position, at which the corresponding termi-nal appears on the PLECS Circuit block.

Location on circuit blockIf an Electrical Port is placed in a top-level schematic in PLECS Block-set, this parameter specifies the side of the PLECS Circuit block on which

422

Electrical Port

the corresponding terminal appears. By convention, left refers to the sideon which also input terminals are shown, and right refers to the side onwhich also output terminals are shown.

423


Enable

Purpose Control execution of an atomic subsystem

Library System

Description The Enable block is used in an atomic subsystem (see “Virtual and AtomicSubsystems” on page 662) to create an enabled subsystem. When you copy anEnable block into the schematic of a subsystem, a corresponding enable ter-minal will be created on the Subsystem block. In order to move this terminalaround the edges of the Subsystem block, hold down the Shift key while drag-ging the terminal with the left mouse button or use the middle mouse button.

An enabled subsystem is executed while the enable signal is non-zero. Theenable signal may be a vector signal. In this case the enabled subsystem isexecuted while any enabled signal is non-zero.

If the sample time of the Subsystem block is not inherited, the enable signalwill be evaluated only at the instants specified by the sample time parameter.

Note An enabled subsystem may not contain any physical components.

Parameters WidthThe width of the enable signal. The default auto means that the width isinherited from connected blocks.

Show output portWhen this parameter is set to on, the Enable block shows an output termi-nal for accessing the enable signal within the subsystem.


Probe Signal OutputThe output signal of the Enable block.

424

Flux Rate Meter

Flux Rate Meter

Purpose Output the measured rate-of-change of magnetic flux

Library Magnetic

Description The Flux Rate Meter measures the rate-of-change Φ of the magnetic fluxthrough the component and provides it as a signal at the output. The direc-tion of a positive flux is indicated with a small arrow in the component sym-bol. The output signal can be made accessible in Simulink with an Outputblock (see page 641) or by dragging the component into the dialog box of aProbe block.

The magnetic flux Φ cannot be measured directly in the circuit. However, mostpermeance components provide the magnetic flux as a probe signal.

Note The Flux Rate Meter is ideal, i.e. it has infinite internal permeance.Hence, if multiple Flux Rate Meters are connected in parallel the flux throughan individual meter is undefined. This produces a run-time error.

Probe Signal Flux rateThe rate-of-change Φ of magnetic flux flowing through the component, inWb/s or V.

425


Flying Capacitor Half Bridge

Purpose Multi-level inverter half bridge with flying capacitors


Description

1

1

1

This component implements a multi-level inverter half bridge with flying ca-pacitors. The vectorized terminals for the capacitors are ordered from outer toinner voltage levels. The vectorized control inputs are ordered from the top tothe bottom switch. The power module offers two configurations:








426

Flying Capacitor Half Bridge

Note The sub-cycle average implementation cannot model a shoot-throughor clamping of the DC side. Therefore, the sums of the two outermost controlsignals for each flying capacitor cell must not exceed 1 at any time. Also, theapplied DC voltages must never become negative.



Number of capacitorsSpecifies how many capacitors and how many voltage levels the halfbridge power module contains.

AssertionsWhen set to on, the block will flag an error if the sums of the control sig-nals for the upe

427


Force (Constant)

Purpose Generate constant force

Library Mechanical / Translational / Sources

Description The Constant Force generates a constant force between its two flanges. Thedirection of a positive force is indicated by the arrow.

Note A force source may not be left unconnected or connected in series with aspring or any other force source.

Parameters Second flangeControls whether the second flange is accessible or connected to the trans-lational reference frame.

ForceThe magnitude of the torque, in Newton (N). The default value is 1.

Probe Signals ForceThe generated force, in Newton (N).

SpeedThe speed of the flange that the arrow points to with respect to the otherflange, in m

s .

428

Force (Controlled)

Force (Controlled)

Purpose Generate variable force


Description The Controlled Force generates a variable force between its two flanges. Thedirection of a positive force is indicated by the arrow. The momentary force isdetermined by the signal fed into the input of the component.

Note A force source may not be left unconnected or connected in series with aspring or any other force source.


Allow state-space inliningFor expert use only! When set to on and the input signal is a linear com-bination of mechanical measurements, PLECS will eliminate the inputvariable from the state-space equations and substitute it with the corre-sponding output variables. The default is off.

Probe Signals ForceThe generated force, in Newton (N).

SpeedThe speed of the flange that the arrow points to with respect to the otherflange, in m

s .

429


Force Sensor

Purpose Output measured force as signal

Library Mechanical / Translational / Sensors

Description The Force Sensor measures the force between its two flanges and provides itas a signal at the output of the component. A force flow from the unmarkedflange towards the flange marked with a dot is considered positive.

Note A force sensor is ideally rigid. Hence, if multiple force sensors are con-nected in parallel the force measured by an individual sensor is undefined. Thisproduces a run-time error.

Parameter Second flangeControls whether the second flange is accessible or connected to the trans-lational reference frame.

Probe Signal ForceThe measured force, in Newton (N).

430

Fourier Series

Fourier Series

Purpose Synthesize periodic output signal from Fourier coefficients


Description

FourierSeries

The Fourier Series block calculates the series

y =a0

2+∑n

an · cos(nx) + bn · sin(nx)

as a function of the input signal x.

Parameters Fourier coefficientsThe coefficients a0, an, and bn of the fourier series. The vectors an and bnmust have the same length.



431


Fourier Transform

Purpose Perform Fourier transform on input signal

Library Control / Filters

Description

FT

This block calculates the Fourier transform of a periodic input signal. Thesample time, the fundamental frequency and the harmonic order(s) can bespecified. The outputs of the block are the magnitude and phase angle of thespecified harmonics.

If you specify more than one harmonic, the outputs will be vectors with thecorresponding width. Alternatively you can specify a single harmonic and feeda vector signal into the block.

Parameters Sample timeThe time interval between samples. See also the Discrete-Periodic sam-ple time type in section “Sample Times” (on page 38). If a sample timeof 0 is specified, a continuous implementation based on the Moving Aver-age block (see page 545) is active. The Discrete-Periodic implementationcan potentially force a variable-step solver to take small integration steps.This may slow down the simulation. The default value of this parameter is0.

Fundamental frequencyThe fundamental frequency of the periodic input signal.

Harmonic orders nA scalar or vector specifying the harmonic component(s) you are interestedin. Enter 0 for the dc component, 1 for the fundamental component, etc.This parameter should be scalar if the input signal is a vector.


MagnitudeThe first output signal, i.e. the computed magnitude.

PhaseThe second output signal, i.e. the computed phase angle, in radians.

432

From File

From File

Purpose Read time stamps and signal values from a file.

Library System

Description While a simulation is running, the From File block reads time stamps andsignal values from a file. The file format can be either a text file with commaseparated values (csv) or a MATLAB data file (mat).The file should contain one column for the time stamps and one or morecolumns for the signal values. Each row should specify one timestamp and thesignal values for that time stamp.During the simulation, the signal values for the current simulation time areread from the file and made available as a vectorized signal at the output ofthe From File block.

Parameters FilenameThe name or path of the data file to read from. Relative paths are inter-preted relative to the model directory.If you choose the option literal, the string that you enter is taken literallyas the basename of the data file. So, if you enter e.g. MyFile, the file namewill be MyFile.csv or MyFile.mat.If you choose the option evaluate, the string that you enter is inter-preted as a MATLAB/Octave expression that must yield a string, whichin turn is taken as the basename of the data file. So, if you enter e.g.[’MyFile’ num2str(index)] and the current workspace contains avariable index with a value of 2, the file name will be MyFile2.csv orMyFile2.mat.

File typeThe file format the specified data file has to comply to. The block can readtext files with comma separated values (csv) or MATLAB data files (mat).

Number of outputsThe number of signal values in each data record (row) of the file (which isthe number of columns minus one). If this number does not correspond tothe actual number of signal values provided by the file, an error messageis shown.

Output before first time stampThe method used to determine the output of the From File block for sim-ulation times before the first time stamp in the data file. Possible values

433


are linear extrapolation, hold first value and specify value. If theparameter is set to specify value, an additional parameter field Initialoutput value is shown to define the output value before the first timestamp.

Initial output valueThe output value before the first signal value specified in the data file.This parameter is only visible if Output before first time stamp is setto specify value. The value can be given as a scalar or a vector. If it isa scalar it is used for all signals, if it is a vector its size has to match theNumber of outputs parameter.

Output within time rangeThe method used to determine the output of the From File block for simu-lation times between time stamps specified in the data file. Possible valuesare linear interpolation and zero order hold.

Output after last time stampThe method used to determine the output of the From File block for simu-lation times after the last time stamp in the data file. Possible values arelinear extrapolation, hold last value and specify value. If the pa-rameter is set to specify value, an additional parameter field Final out-put value is shown to define the output value after the last time stamp.

Final output valueThe output value after the last signal value specified in the data file.This parameter is only visible if Output after first time stamp is setto specify value. The value can be given as a scalar or a vector. If it isa scalar it is used for all signals, if it is a vector its size has to match theNumber of outputs parameter.

Locate discontinuitiesPossible values are on and off. If this parameter is set to on, t he solverwill ensure a time step at each time stamp specified in the data file. Thissetting requires a variable step solver.

434

Function

Function

Purpose Apply arbitrary arithmetic expression to scalar or vectorized input signal


Description

f (u)

The Function block applies an arithmetic expression specified in C languagesyntax to its input. The input may be a scalar or vectorized continuous signal,the output is always a scalar continuous signal. The expression may consist ofone or more of the following components:

• u — the input of the block. If the input is vectorized, u(i) or u[i] repre-sents the ith element of the vector. To access the first element, enter u(1),u[1], or u alone.

• Brackets• Numeric constants, including pi

• Arithmetic operators (+ - * / ˆ)• Relational operators (== != > < >= <=)• Logical operators (&& || !)• Mathematical functions — abs, acos, asin, atan, atan2, cos, cosh, exp, log,

log10, max, min, mod, pow, sgn, sin, sinh, sqrt, tan, and tanh.• Workspace variables

Parameter ExpressionThe expression applied to the input signal, in C language syntax.



435


FMU

Purpose Include a Functional Mockup Unit in a model


Description The FMU block imports existing Functional Mockup Units (FMUs) into aPLECS model. This block supports the FMI Model Exchange interface stan-dard in version 2.0.

To specify an FMU file, select the FMU block and choose Edit FMU file...from the Edit menu or from the block’s context menu. If no FMU file has beenspecified yet, you can also just double-click on the block. Click on the ... but-ton next to the FMU file field to choose an existing FMU file. By default, theFMU file is specified with a path relative to the model file, but you can changethis with the FMU file reference selector.

When you click OK, PLECS creates a folder filename.fmu.expanded next tothe FMU file and updates the input and output terminals of the block accord-ing to the FMU description.

Once the FMU file has been specified, a double-click on the FMU block willopen a dialog that allows you to view and edit the parameters that are definedby the FMU file. If the FMU file contains documentation, you can view this byclicking on the Help button of the parameter dialog.

436

Full-Bridge LLC Resonant Converter


Purpose Full-Bridge LLC Resonant Converter converter module


Description1

1

1

1

1

1

1

1 n:1 1

Lm

L

Cr

Switched All power semiconductors inside the module are modeled withideal switches. The individual IGBTs are controlled with logical gate signals.An IGBT is on if the corresponding gate signal is not zero. For compatibilitywith the sub-step events configuration it is recommended to use the value 1for non-zero gate signals.



Since the inductors current and capacitor voltage are simulated accurately,even with relatively large time steps, the sub-steps configuration is particu-larly well suited for real-time simulations with high switching frequencies.However, it is not recommended to use discretisation step sizes (sample timeparameter) larger than one fifth of the switching period.

This type of implementation is an extension of the classical “sub-cycle aver-age" implementation, used in the PLECS power modules, which yields moreaccurate simulation results than a purely switched configuration. The accu-racy improvement is obtained by performing sub-step calculations within onesimulation step, which results in the calculation of as many inductors currentvalues as switching combinations encountered during one simulation step.

437


This approach allows for a more accurate calculation of the average inductorscurrent, which is critical to obtain an accurate capacitor voltage calculation.Nevertheless, if the the capacitor voltage changes rapidly between two simula-tion steps, the accuracy of the calculations given by the power module will de-grade. Therefore, in order to maintain high accuracy in the simulated results,the usage of low values of resonant capacitance is not recommended.




Output rectifierThis setting lets you choose between Half bridge and Full bridge outputrectifier topology.



Magentization inductanceA non-zero scalar specifying the primary side magnetization inductance ofthe transformer, in henries (H).




438



439


Gain

Purpose Multiply input signal by constant


Description The Gain block multiplies the input signal with the gain value. The multipli-cation can either be an element-wise (K · u) or a matrix multiplication (K ∗ u).

Parameters GainThe gain value to multiply with the input signal. For element-wise multi-plication the gain value can be a scalar or a vector matching the width ofthe input signal. For matrix multiplication the gain value can be a scalar,a vector or a matrix which has as many columns as the width of the inputsignal.

MultiplicationSpecifies whether element-wise (K · u) or matrix multiplication (K ∗ u)should be used.

Output data typeThe data type of the output signal. See “Data Types” (on page 42). If youchoose inherited, the minimum data type is int8_t.



440

Gear

Gear

Purpose Ideal gear

Library Mechanical / Rotational / Components

Description The Gear models an ideal gearbox with two shafts rotating in the same direc-tion. The shaft moving with ω2 is marked with a dot. The relation betweenthe torques and angular speeds of the two shafts is described with the follow-ing equations:

ω2 = g · ω1

τ1 = g · τ2

where g is the gearbox ratio.

Parameter Gear ratioThe gearbox ratio g. A negative gearbox ratio will cause the shafts to ro-tate in opposite directions.

441


GTO

Purpose Ideal GTO with optional forward voltage and on-resistance


Description The Gate Turn Off Thyristor can also be switched off via the gate. Like a nor-mal thyristor it closes when the voltage between anode and cathode is positiveand a positive gate signal is applied. It opens when the current becomes nega-tive or the gate signal becomes negative.


Forward voltageAdditional dc voltage Vf in volts (V) between anode and cathode when theGTO is conducting. The default is 0.


Initial conductivityInitial conduction state of the GTO. The GTO is initially blocking if theparameter evaluates to zero, otherwise it is conducting.



Probe Signals GTO voltageThe voltage measured between anode and cathode.

GTO currentThe current through the GTO flowing from anode to cathode.

442

GTO

GTO gate signalThe gate input signal of the GTO.

GTO conductivityConduction state of the internal switch. The signal outputs 0 when theGTO is blocking, and 1 when it is conducting.

GTO junction temperatureTemperature of the first thermal capacitor in the equivalent Cauer net-work.

GTO conduction lossContinuous thermal conduction losses in watts (W). Only defined if thecomponent is placed on a heat sink.

GTO switching lossInstantaneous thermal switching losses in joules (J). Only defined if thecomponent is placed on a heat sink.

443


GTO (Reverse Conducting)

Purpose Ideal GTO with ideal anti-parallel diode


Description This model of a Gate Turn Off Thyristor has an integrated anti-parallel diode.The diode is usually included in power GTO packages.


Initial conductivityInitial conduction state of the GTO. The GTO is initially blocking if theparameter evaluates to zero, otherwise it is conducting.

Thermal descriptionSwitching losses, conduction losses and thermal equivalent circuit of thecomponent. For more information see chapters “Thermal Modeling” (onpage 119) and “Losses of Semiconductor Switch with Diode” (on page 146)for more information.


Probe Signals Device voltageThe voltage measured between anode and cathode.

Device currentThe current through the device flowing from anode to cathode.

Device gate signalThe gate input signal of the device.

Device conductivityConduction state of the internal switch. The signal outputs 0 when thedevice is blocking, and 1 when it is conducting.

444

GTO (Reverse Conducting)

Device junction temperatureTemperature of the first thermal capacitor in the equivalent Cauer net-work.

Device conduction lossContinuous thermal conduction losses in watts (W). Only defined if thecomponent is placed on a heat sink.

Device switching lossInstantaneous thermal switching losses in joules (J). Only defined if thecomponent is placed on a heat sink.

445


Half-Bridge LLC Resonant Converter

Purpose Half-Bridge LLC Resonant Converter converter module


Description1

1

1

1

1

1

n:1 1

Lm

L

Cr


Sub-step events The module is implemented with controlled currentsources, on both, primary and secondary terminals, instead of ideal switches.


This type of implementation is an extension of the classical“sub-cycle average"implementation, used in the PLECS power modules, which yields more accu-rate simulation results. The accuracy improvement is obtained by performingsub-step calculations within one simulation steps. This results in the calcula-tion of as many inductor current values as switching combination encounteredduring one simulation step. This allows for a more accurate calculation of theaverage inductors current and capacitor voltage.

Since the inductor current and capacitor’s voltage, are simulated accurately,even with relatively large time steps, the sub-steps configuration is particu-larly well suited for real-time simulations with high switching frequencies.

446

Half-Bridge LLC Resonant Converter


Note In order to maintain high accuracy in the simulated results, the usageof low values of resonant capacitance is not recommended. If the magnitude ofthe voltage variation across the capacitance changes rapidly between two simu-lation steps, the accuracy of the calculations in the power module will degrade.

Note The discretisation step size (sample time parameter) should not belarger than one fifth of the switching period.






Magentization inductanceA non-zero scalar specifying the primary side magnetization inductance ofthe transformer, in henries (H).


447





448

Heat Flow Meter

Heat Flow Meter

Purpose Output measured heat flow as signal

Library Thermal

Description

W

The Heat Flow Meter measures the heat flow through the component and pro-vides it as a signal at the output. The direction of a positive heat flow is indi-cated by the small arrow at one of the thermal ports. The output signal canbe made accessible in Simulink with a Output block (see page 641) or by drag-ging the component into the dialog box of a Probe block.

Probe Signal Measured heat flowThe measured heat flow in watts (W).

449


Heat Sink

Purpose Isotherm environment for placing components

Library Thermal

Description The Heat Sink absorbs the thermal losses dissipated by the componentswithin its boundaries. At the same time it defines an isotherm environmentand propagates its temperature to the components which it encloses. Tochange the size of a Heat Sink, select it, then drag one of its selection handles.

With the parameter Number of terminals you can add and remove thermalconnectors to the heat sink in order to connect it to an external thermal net-work. The connectors can be dragged along the edge of the heat sink with themouse by holding down the Shift key or using the middle mouse button. Inorder to remove a thermal connector, disconnect it, then reduce the Numberof terminals. PLECS will not allow you to remove connected terminals.

For additional information see chapter “Thermal Modeling” (on page 119).

Parameters Number of terminalsThis parameter allows you to change the number of external thermal con-nectors of a heat sink. The default is 0.

Thermal capacitanceThe value of the internal thermal capacitance, in J/K. The default is 1.

If the capacitance is set to zero, the heat sink must be connected to an ex-ternal thermal capacitance or to a fixed temperature.

Initial temperatureThe initial temperature difference between the heat sink and the thermalreference at simulation start, in kelvin (K). The default is 0. If left blankor if the value is nan, PLECS will initialize the value based on a thermal“DC” analysis, see “Temperature Initialization” (on page 125).

Probe Signal TemperatureThe temperature difference between the heat sink and the thermal refer-ence, in kelvin (K).

450

Hit Crossing

Hit Crossing

Purpose Detect when signal reaches or crosses given value


Description The Hit Crossing block detects when the input signal reaches or crosses avalue in the specified direction. If a variable-step solver is used, a simulationstep is forced at the time when the crossing occurs. The output signal is 1 forone simulation time step when a crossing occurs, 0 otherwise.

Parameters Hit crossing offsetThe offset that the input signal has to reach or cross.

Hit crossing directionThe value rising causes hit crossings only when the input signal is rising.If falling is chosen, only hit crossings for a falling input signal are de-tected. The setting either causes hit crossing for rising and falling signalsto be detected.

ThresholdThe threshold value used for the switch criteria.

Show output portThe output terminal of the Hit Crossing block will be hidden if the param-eter is set to off. This setting only makes sense to force a simulation stepwhile using a variable-step solver.


Crossing signalOutputs 1 for one simulation time step when a crossing occurs, 0 other-wise. This probe signal is identical to the output signal.

451


Hysteretic Core

Purpose Magnetic core element with static hysteresis

Library Magnetic

Description This component models a segment of a magnetic core. It establishes a non-linear relationship between the magnetic field strength H and the flux den-sity B. The hysteresis characteristics is based on a Preisach model with aLorentzian distribution function.

The figure below shows a fully excited major hysteresis curve with some mi-nor reversal loops. The major curve is defined by the saturation point (Hsat,Bsat), the coercitive field strength Hc, the remanence flux density Br and thesaturated permeability µsat.

µsat

H

B

Hc Hsat

Br

Bsat

Parameters Cross-sectional areaCross-sectional area A of the flux path, in m2.

Length of flux pathLength l of the flux path, in m.

Coercitive field strengthCoercitive field strength Hc for B = 0, in A/m.

Remanence flux densityRemanence flux density Br for H = 0, in teslas (T).

Saturation field strengthField strength Hsat at the saturation point, in A/m.

452

Hysteretic Core

Saturation flux densityFlux density Bsat at the saturation point, in teslas (T).

Saturated rel. permeabilityRelative permeability µr,sat = µsat/µ0 of the core material for H > Hsat.



Field strengthThe magnetic field strength H in the core element, in A/m.

Flux densityThe magnetic flux density B in the core element, in teslas (T).

Loss energyThe energy dissipated in the core, in joules (J). An energy pulse is gener-ated each time a minor or major hysteresis loop is closed.

453


Ideal 3-Level Converter (3ph)

Purpose Switch-based 3-phase 3-level converter


Description Implements a three-phase three-level converter with ideal switches. The con-verter is modeled using the Triple Switch component (see page 753). The gateinput is a vector of three signals – one per leg. The phase output is connectedto the positive, neutral, and negative dc level according to the sign of the cor-responding gate signal.

The electrical circuit for the converter is shown below:

0

a

b

c

–

+

454

Ideal Converter (3ph)

Ideal Converter (3ph)

Purpose Switch-based 3-phase converter


Description Implements a three-phase two-level converter with ideal bi-positionalswitches. The converter is modeled using the Double Switch component (seepage 414). The gate input is a vector of three signals – one per leg. The phaseoutput is connected to the positive dc level upon a positive gate signal, andelse to the negative dc level.


+

a

b

c

–

455


Ideal Transformer

Purpose Ideally coupled windings with or without magnetizing inductance

Library Electrical / Transformers

Description This component represents a transformer with two or more ideally coupledwindings. At all windings w, the voltage vw across the winding divided by thecorresponding number of turns nw is the same:

v1

n1=v2

n2=v3

n3= . . .

If the transformer does not have a finite magnetizing inductance (i.e. the in-ductance value is set to inf), the currents iw of all windings multiplied withthe corresponding number of turns add up to zero:

0 = i1 · n1 + i2 · n2 + i3 · n3 + . . .

If the transformer does have a finite magnetizing inductance, the currents iwof all windings multiplied with the corresponding number of turns add up tothe magnetizing current multiplied with the number of turns in the first wind-ing:

im · n1 = i1 · n1 + i2 · n2 + i3 · n3 + . . .

In the transformer symbol, the first primary side winding is marked with alittle circle. The orientation of the other windings is indicated by a dot. Cur-rents entering a terminal marked with the circle or a dot are considered posi-tive.

Use the Polarity parameter to change the orientation of a specific winding.This is equivalent to making the corresponding number of turns nw negative.

Parameters Number of windingsA two-element vector [w1 w2] containing the number of windings on theprimary side w1 and on the secondary side w2. The default is [1 1], whichrepresents a two-winding transformer with opposite windings.

Number of turnsA row vector specifying the number of turns for each winding. The vectorlength must match the total number of primary and secondary side wind-ings. First, all primary side windings are specified, followed by the specifi-cations for all secondary side windings.

456

Ideal Transformer

PolarityA string consisting of one + or - per winding specifying the winding polar-ity. A single + or - is applied to all windings.

Magnetizing inductanceA non-zero scalar specifying the magnetizing inductance referred to thefirst winding, in henries (H).

Initial magnetizing currentA scalar specifying the initial current through the magnetizing inductanceat simulation start, in Amperes (A). Must be zero if the magnetizing induc-tance is infinite inf.

457


IGBT

Purpose Ideal IGBT with optional forward voltage and on-resistance


Description The Insulated Gate Bipolar Transistor is a semiconductor switch that is con-trolled via the external gate. It conducts a current from collector to emitteronly if the gate signal is not zero.


Forward voltageAdditional dc voltage Vf in volts (V) between collector and emitter whenthe IGBT is conducting. The default is 0.


Initial conductivityInitial conduction state of the IGBT. The IGBT is initially blocking if theparameter evaluates to zero, otherwise it is conducting.



Probe Signals IGBT voltageThe voltage measured between collector and emitter.

458

IGBT

IGBT currentThe current through the IGBT flowing from collector to emitter.

IGBT gate signalThe gate input signal of the IGBT.

IGBT conductivityConduction state of the internal switch. The signal outputs 0 when theIGBT is blocking, and 1 when it is conducting.

IGBT junction temperatureTemperature of the first thermal capacitor in the equivalent Cauer net-work.

IGBT conduction lossContinuous thermal conduction losses in watts (W). Only defined if thecomponent is placed on a heat sink.

IGBT switching lossInstantaneous thermal switching losses in joules (J). Only defined if thecomponent is placed on a heat sink.

459


IGBT 3-Level Converter (3ph)

Purpose 3-phase 3-level neutral-point clamped IGBT converter


Description Implements a three-phase three-level IGBT converter with neutral pointclamping. The gate input is a vector of three signals – one per leg. The top-most IGBT, connected to the positive dc level, is turned on if the correspond-ing gate signal is ≥ 1, and the second IGBT if the signal is ≥ 0. The thirdIGBT is turned on for signals ≤ 0 and the lowest one for signals ≤ −1. Gatesignal values of 1, 0 and −1 connect the phase output to the positive, neu-tral and negative dc level. By applying a non-zero signal at the inhibit inputmarked with “x” you can turn off all IGBTs.

You can choose between two different converter models:

• The basic IGBT 3-Level Converter is modeled using the component IGBTwith Diode (see page 478). No parameters can be entered.

• The IGBT 3-Level Converter with Parasitics is based on individualIGBT (see page 458) and Diode (see page 388) components. In this modelyou may specify forward voltages and on-resistances separately for the IG-BTs and the diodes.

Note Due to the switching conditions of the IGBT with Diode (see page 478),this device cannot be turned off actively while the current is exactly zero. Thismay result in unexpected voltage waveforms if the converter is not loaded.

To resolve this problem, either use the IGBT 3-Level Converter with Para-sitics, or allow a small non-zero load current to flow by connecting a large loadresistance to the converter.

460

IGBT 3-Level Converter (3ph)


0

a

b

c

–

+

Parameters For a description of the parameters see the documentation of the IGBT withDiode (on page 478), the IGBT (on page 458) and the Diode (on page 388).

Probe Signals The three-level IGBT converters provide 36 probe signals grouped by leg.Each signal is a vector containing the appropriate quantities of the individ-ual devices: voltage, current, conductivity, conduction loss and switching loss.The vector elements are ordered top-to-bottom.

For the IGBT 3-Level Converter with Parasitics the diode probe signalvectors are in the order: anti-parallel diodes (top-to-bottom), clamping diodes(top-to-bottom).

461


IGBT 3-Level Half Bridge (NPC)

Purpose 3-level neutral-point clamped IGBT module


Description This power module implements a single leg of a 3-level neutral-point clampedvoltage source inverter. It offers two configurations:








462

IGBT 3-Level Half Bridge (NPC)

Note The sub-cycle average implementation cannot model a shoot-through orclamping of the DC side. Therefore, the sums of the control signals for the firstand third IGBT and second and fourth IGBT must not exceed 1 at any time.Also, the applied DC voltages must never become negative.


AssertionsWhen set to on, the block will flag an error if the sums of the control sig-nals for IGBT 1 and 3 or IGBT 2 and 4 exceed 1.

463


IGBT Chopper (High-Side Switch)

Purpose Buck converter IGBT module


Description This power module implements a chopper used in buck converters. It offerstwo configurations:

Switched The power semiconductors inside the module are modeled withideal switches. The IGBT is controlled with a logical gate signal; it is on if thegate signal is not zero. For compatibility with the averaged configuration it isrecommended to use the value 1 for non-zero gate signals.

Sub-cycle average The module as a whole is modeled with controlledvoltage and current sources. The electrical input of the chopper has currentsource behavior and must be connected to a positively biased capacitor or volt-age source. The output terminal is typically connected to an inductor. The con-trol input is the relative on-time of the IGBT with values between 0 and 1.

In the average configuration the chopper can be operated in two ways:

• The control signal is the instantaneous logical gate signal having the values0 and 1.

• The control signal is the duty cycle of the IGBT. It is either computed di-rectly from the modulation index or by periodically averaging the digitalgate signal over a fixed period of time, e.g. using the Periodic Average block(see page 562). The averaging period does not need to be synchronized withthe PWM and can be as large as the inverse of the switching frequency.

In both use cases, the average implementation supports continuous and dis-continuous conduction mode.


Note The sub-cycle average implementation cannot model clamping of theinput side. Therefore, the applied DC voltage must never become negative.

Parameter ConfigurationSwitched or averaged circuit model.

464

IGBT Chopper (High-Side Switch with Reverse Diode)

IGBT Chopper (High-Side Switch with Reverse Diode)

Purpose Buck converter IGBT module with reverse diode


Description This power module implements a chopper used in buck converters. It offerstwo configurations:







Since the duty cycle is simulated accurately even with relatively large timesteps, the average configuration is particularly well suited for real-time sim-ulations with high switching frequencies. If the reversed diode is not needed,the alternative chopper module (see page 464) is preferred to minimize modelcomplexity.


465



466

IGBT Chopper (Low-Side Switch)

IGBT Chopper (Low-Side Switch)

Purpose Boost converter IGBT module


Description This power module implements a chopper used in boost converters. It offerstwo configurations:










467


IGBT Chopper (Low-Side Switch with Reverse Diode)

Purpose Boost converter IGBT module with reverse diode


Description This power module implements a chopper used in boost converters. It offerstwo configurations:







Since the duty cycle is simulated accurately even with relatively large timesteps, the average configuration is particularly well suited for real-time sim-ulations with high switching frequencies. If the reversed diode is not needed,the alternative chopper module (see page 467) is preferred to minimize modelcomplexity.


468

IGBT Chopper (Low-Side Switch with Reverse Diode)


469


IGBT Converter (3ph)

Purpose 3-phase IGBT converter


Description Implements a three-phase two-level IGBT converter with reverse diodes. Thegate input is a vector of three signals – one per leg. The upper IGBT, con-nected to the positive dc level, is on if the corresponding gate signal is posi-tive. The lower IGBT is on if the gate signal is negative. If the gate signal iszero both IGBTs in the leg are switched off.


• The basic IGBT Converter is modeled using the component IGBT withDiode (see page 478). PLECS needs only six internal switches to repre-sent this converter, so the simulation is faster compared to the detailed con-verter. No electrical parameters can be entered, but the thermal losses maybe specified.

• The IGBT Converter with Parasitics is based on individual IGBT (seepage 458) and Diode (see page 388) components. In this model you mayspecify all electrical and thermal parameters separately for the IGBTs andthe diodes.

Note Due to the switching conditions of the IGBT with Diode (see page 478),this device cannot be turned off actively while the current is exactly zero. Thismay result in unexpected voltage waveforms if the converter is not loaded.

To resolve this problem, either use the IGBT Converter with Parasitics, orallow a small non-zero load current to flow by connecting a large load resistanceto the converter.

470

IGBT Converter (3ph)


–

a

b

c

+

Parameters For a description of the parameters see the documentation of the IGBT withDiode (on page 478), the IGBT (on page 458) and the Diode (on page 388).

Probe Signals The two-level IGBT converters provide six or twelve probe signals, each a vec-tor containing the appropriate quantities of the individual devices: voltage,current, conductivity, conduction loss and switching loss. The vector elementsare ordered top-to-bottom, left-to-right: a+, a-, b+, b-, c+, c-.

471


IGBT Full Bridges (Series Connected)

Purpose Series-connected IGBT full-bridge inverters


Description This component implements multiple series-connected inverter cells for usein modular multilevel converters. All control signals as well as the DC linkterminals are vectorized with their width matching the number of cells. Thecomponent offers two configurations:

Switched All power semiconductors are modeled with ideal switches. Theindividual IGBTs are controlled with logical gate signals. An IGBT is on if thecorresponding gate signal is not zero. For compatibility with the averaged con-figuration it is recommended to use the value 1 for non-zero gate signals.

Sub-cycle average The component as a whole is modeled with controlledvoltage and current sources. The DC sides of the inverter cells have currentsource behavior and and must be connected to positively biased capacitors orvoltage sources. The DC sides must remain galvanically isolated from eachother. The output terminals are typically connected to an inductor. The controlinputs are the relative on-times of the IGBTs with values between 0 and 1.

In the average configuration the inverters can be operated in two ways:



In both use cases, the average implementation correctly accounts for blank-ing times, i.e. when during commutation both IGBTs in one inverter leg areturned off. It also supports discontinuous conduction mode, e.g. when chargingthe DC link capacitors via the reverse diodes.

Since the duty cycle is simulated accurately even with relatively large timesteps, the average configuration is particularly well suited for real-time sim-ulations with high switching frequencies. It can also increase the speed of of-fline simulations, because the number of internal switches is greatly reduced.

472

IGBT Full Bridges (Series Connected)

Note The sub-cycle average implementation cannot model a shoot-through,i.e. the situation where both IGBTs in a leg are turned on at the same time.Therefore, the sum of the control signals for the upper and lower IGBT in aleg must not exceed 1 at any time. Since the DC sides are not clamped, the DCvoltages must never become negative.


Number of cellsNumber of series-connected full-bridge inverters.

AssertionsWhen set to on, the block will flag an error if the sum of the control sig-nals for the upper and lower IGBT in a leg exceeds 1.

473


IGBT Half Bridge

Purpose 2-level half-bridge IGBT module


Description This power module implements a single leg of 2-level voltage source inverter.It offers two configurations:

Switched The power semiconductors are modeled with ideal switches. Theindividual IGBTs are controlled with logical gate signals. An IGBT is on if thecorresponding gate signal is not zero. For compatibility with the averaged con-figuration it is recommended to use the value 1 for non-zero gate signals.

Sub-cycle average The module as a whole is modeled with controlledvoltage and current sources. The DC side of the inverter has current sourcebehavior and must be connected to a positively biased capacitor or voltagesource. The output terminal is typically connected to an inductor. The controlinputs are the relative on-times of the IGBTs with values between 0 and 1.




In both use cases, the average implementation correctly accounts for blankingtimes, i.e. when during commutation both IGBTs are turned off. It also sup-ports discontinuous conduction mode, e.g. when charging the DC link capacitorvia the reverse diodes.


474

IGBT Half Bridge

Note The sub-cycle average implementation cannot model a shoot-through,i.e. the situation where both IGBTs in a leg are turned on at the same time.Therefore, the sum of the control signals for the upper and lower IGBT mustnot exceed 1 at any time. Since the DC side is not clamped, the DC voltagemust never become negative.


AssertionsWhen set to on, the block will flag an error if the sum of the control sig-nals for the upper and lower IGBT exceeds 1.

475



Purpose Series-connected IGBT half-bridge inverters


Description These components implement multiple series-connected inverter cells for usein modular multilevel converters. All control signals as well as the DC linkterminals are vectorized with their width matching the number of cells. Thecomponents offer two configurations:

Switched All power semiconductors are modeled with ideal switches. Theindividual IGBTs are controlled with logical gate signals. An IGBT is on if thecorresponding gate signal is not zero. For compatibility with the averaged con-figuration it is recommended to use the value 1 for non-zero gate signals.

Sub-cycle average The component as a whole is modeled with controlledvoltage and current sources. The DC sides of the inverter cells have currentsource behavior and and must be connected to positively biased capacitors orvoltage sources. The DC sides must remain galvanically isolated from eachother. The output terminals are typically connected to an inductor. The controlinputs are the relative on-times of the IGBTs with values between 0 and 1.

In the average configuration the inverters can be operated in two ways:



In both use cases, the average implementation correctly accounts for blank-ing times, i.e. when during commutation both IGBTs in one inverter cell areturned off. It also supports discontinuous conduction mode, e.g. when chargingthe DC link capacitors via the reverse diodes.

Since the duty cycle is simulated accurately even with relatively large timesteps, the average configuration is particularly well suited for real-time sim-ulations with high switching frequencies. It can also increase the speed of of-fline simulations, because the number of internal switches is greatly reduced.

476


Note The sub-cycle average implementation cannot model a shoot-through,i.e. the situation where both IGBTs in a leg are turned on at the same time.Therefore, the sum of the control signals for the upper and lower IGBT mustnot exceed 1 at any time. Since the DC sides are not clamped, the DC voltagesmust never become negative.


Number of cellsNumber of series-connected half-bridge inverters.

AssertionsWhen set to on, the block will flag an error if the sum of the control sig-nals for the upper and lower IGBT exceeds 1.

477


IGBT with Diode

Purpose Ideal IGBT with ideal anti-parallel diode


Description This model of an Insulated Gate Bipolar Transistor has an integrated anti-parallel diode. The diode is usually required in AC applications such as volt-age source inverters.

This device is modeled as a single ideal switch that closes when the gate sig-nal is not zero or the voltage becomes negative and opens when the gate sig-nal is zero and the current becomes positive.

Note Due to the switching conditions described above, this device cannot beturned off actively while the current is exactly zero. This may result in unex-pected voltage waveforms if the device is used e.g. in an unloaded converter.

To resolve this problem, either use an individual IGBT (see page 458) with anindividual anti-parallel Diode (see page 388), or allow a small non-zero load cur-rent to flow by connecting a large load resistance to the converter.

Parameters Initial conductivityInitial conduction state of the device. The device is initially blocking if theparameter evaluates to zero, otherwise it is conducting. This parametermay either be a scalar or a vector corresponding to the implicit width ofthe component. The default value is 0.

Thermal descriptionSwitching losses, conduction losses and thermal equivalent circuit of thecomponent. For more information see chapters “Thermal Modeling” (onpage 119) and “Losses of Semiconductor Switch with Diode” (on page 146).


478

IGBT with Diode

Probe Signals Device voltageThe voltage measured between collector/cathode and emitter/anode. Thedevice voltage can never be negative.

Device currentThe current through the device. The current is positive if it flows throughthe IGBT from collector to emitter and negative if it flows through thediode from anode to cathode.






479


IGBT with Limited di/dt

Purpose Dynamic IGBT model with finite current slopes during turn-on and turn-off


Description In contrast to the ideal IGBT model (see page 458) that switches instanta-neously, this model includes collector current transients during switching.Thanks to the continuous current decay during turn-off, stray inductancesmay be connected in series with the device. In converter applications, the di/dtlimitation during turn-on determines the magnitude of the reverse recoveryeffect in the free-wheeling diodes.

This IGBT model is used to simulate overvoltages produced by parasitic induc-tances in the circuit. Since the voltage and current transient waveforms aresimplified, the model is not suited for the simulation of switching losses.

Note

• Due to the small time-constants introduced by the turn-on and turn-off tran-sients a stiff solver is recommended for this device model.

• If multiple IGBTs are connected in series the off-resistance may not be infi-nite.

The behavior of this IGBT model is demonstrated with the following test cir-cuit. The free-wheeling diode for the inductive load is modeled with reverserecovery (see page 390).

Gate11

L_dcV_dc

L_sigma

Drr1

IGBT2

480


The diagram below shows the collector current iC(t) of the IGBT and the re-sulting collector-emitter voltage vCE(t) during switching:

vCE

0

100 %

tf

tr

t

iC

toff

ton

010 %

90 %100 %

Collector current and collector-emitter voltage

At t = toff the gate signal becomes zero, and the device current iC begins tofall. The current slope follows an aperiodic oscillation

iC(t) = iC(toff)

e−2.4 (t− toff)

tf

(1 +

2.4 (t− toff)

tf

)where tf is the fall time specified in the component parameters. As illustratedin the diagram, the maximum rate-of-change during turn-off is determined bytf .

At t = ton a positive gate signal is applied. Unless the rate-of-change is limitedby other circuit components, the current rises linearly with constant di/dt. Themaximum di/dt depends on the rated continuous collector current IC and therise time tr specified in the component parameters:

481


dimax

dt= 0.8 · IC

tr

The second diagram shows the collector current transients for different on-state currents. It can be seen that the fall time is independent of the on-statecurrent. Since di/dt during turn-on is constant, the actual rise time is propor-tional to the on-state current. In a real IGBT, the rise time would only varyslightly with different on-state currents. Hence, assuming constant di/dt isa worst-case estimate in respect of the reverse-recovery current in the free-wheeling diode.

t

iC

toff

ton

0

50 %

75 %

100 %

Parameters Blocking voltageMaximum voltage VCES in volts (V) that under any conditions should beapplied between collector and emitter.

Continuous collector currentMaximum dc current IC in amperes (A) that the IGBT can conduct.

Forward voltageAdditional dc voltage Vf in volts (V) between collector and emitter whenthe IGBT is conducting. The default is 0.


Off-resistanceThe resistance Roff of the blocking device, in ohms (Ω). The default is 1e6.This parameter may be set to inf unless multiple IGBTs are connected inseries.

Rise timeTime tr in seconds between instants when the collector current has risenfrom 10 % to 90 % of the continuous collector current IC (see figure above).

482


Fall timeTime tf in seconds between instants when the collector current hasdropped from 90 % to 10 % of its initial value along an extrapolatedstraight line tangent to the maximum rate-of-change of the current (seefigure above).

Stray inductanceInternal inductance Lσ in henries (H) measured between the collector andemitter terminals.

Initial currentThe initial current through the component at simulation start, in amperes(A). The default is 0.

Probe Signals IGBT voltageThe voltage measured between collector and emitter.

IGBT currentThe current through the IGBT flowing from collector to emitter.

IGBT conductivityConduction state of the internal switch. The signal outputs 0 when theIGBT is blocking, and 1 when it is conducting.

483


IGCT (Reverse Blocking)

Purpose Ideal IGCT with optional forward voltage and on-resistance


Description The Integrated Gate Commutated Thyristor is a semiconductor switch that iscontrolled via the external gate. It conducts a current from anode to cathodeonly if the gate signal is not zero.


Forward voltageAdditional dc voltage Vf in volts (V) between anode and cathode when theIGCT is conducting. The default is 0.


Initial conductivityInitial conduction state of the IGCT. The IGCT is initially blocking if theparameter evaluates to zero, otherwise it is conducting.



Probe Signals IGCT voltageThe voltage measured between anode and cathode.

IGCT currentThe current through the IGCT flowing from anode to cathode.

484

IGCT (Reverse Blocking)

IGCT gate signalThe gate input signal of the IGCT.

IGCT conductivityConduction state of the internal switch. The signal outputs 0 when theIGCT is blocking, and 1 when it is conducting.

IGCT junction temperatureTemperature of the first thermal capacitor in the equivalent Cauer net-work.

IGCT conduction lossContinuous thermal conduction losses in watts (W). Only defined if thecomponent is placed on a heat sink.

IGCT switching lossInstantaneous thermal switching losses in joules (J). Only defined if thecomponent is placed on a heat sink.

485


IGCT (Reverse Conducting)

Purpose Ideal IGCT with ideal anti-parallel diode


Description This model of an Integrated Gate Commutated Thyristor has an integratedanti-parallel diode. The diode is usually included in power IGCT packages.




Probe Signals Device voltageThe voltage measured between anode and cathode. The device voltage cannever be negative.

Device currentThe current through the device. The current is positive if it flows throughthe IGCT from anode to cathode and negative if it flows through the diodefrom cathode to anode.


486

IGCT (Reverse Conducting)





487


Induction Machine (Slip Ring)

Purpose Non-saturable induction machine with slip-ring rotor


Description This model of a slip-ring induction machine can only be used with the continu-ous state-space method. If you want to use the discrete state-space method orif you need to take saturation into account, please use the Induction Machinewith Saturation (see page 498).

The machine model is based on a stationary reference frame (Clarke transfor-mation). A sophisticated implementation of the Clarke transformation facil-itates the connection of external inductances in series with the stator wind-ings. However, external inductors cannot be connected to the rotor windingsdue to the current sources in the model. In this case, external inductors mustbe included in the leakage inductance of the rotor.

The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motor mode,otherwise in generator mode. All electrical variables and parameters areviewed from the stator side. In the component icon, phase a of the stator androtor windings is marked with a dot.

In order to inspect the implementation, please select the component in yourcircuit and choose Look under mask from the Subsystem submenu of theEdit menu. If you want to make changes, you must first choose Break li-brary link and then Unprotect, both from the same menu.

Electrical System

The rotor flux is computed as

Ψr,d = L′lr i′r,d + Lm

(is,d + i′r,d

)Ψr,q = L′lr i

′r,q + Lm

(is,q + i′r,q

)The three-phase voltages vs,ab and vs,bc at the stator terminals are trans-formed into dq quantities: vs,d

vs,q

=

23

13

0 1√3

· vs,ab

vs,bc

488


Rs Lls

Lm

L'lr -ω∙ Ψ 'r,q R'r

+

−

vs,d

+

−

v'r,d

is,d i'r,d

d-axis

Rs Lls

Lm

L'lr R'r-ω∙ Ψ 'r,d

+

−

vs,q

+

−

v'r,q

is,q i'r,q

q-axis

Likewise, the stator currents in the stationary reference frame are trans-formed back into three-phase currents:

is,a

is,b

is,c

=

1 0

− 12

√3

2

− 12 −

√3

2

· is,d

is,q

Similar equations apply to the voltages and currents at the rotor terminalswith θ being the electrical rotor position: v′r,d

v′r,q

=2

3

cos θ − cos(θ − 2π

3

)sin θ − sin

(θ − 2π

3

) · v′r,ab

v′r,bc

i′r,a

i′r,b

i′r,c

=

cos θ sin θ

cos(θ + 2π

3

)sin(θ + 2π

3

)cos(θ − 2π

3

)sin(θ − 2π

3

) · i′r,d

i′r,q

Electro-Mechanical System


489


Te =3

2pLm

(is,q i

′r,d − is,d i′r,q

)

Mechanical System

Mechanical rotor speed ωm:

ωm =1


ω = pωm

Mechanical rotor angle θm:

θm = ωm

θ = p θm

Parameters Stator resistanceStator winding resistance Rs in ohms (Ω).

Stator leakage inductanceStator leakage inductance Lls in henries (H).

Rotor resistanceRotor winding resistance R′r in ohms (Ω), referred to the stator side.

Rotor leakage inductanceRotor leakage inductance L′lr in henries (H), referred to the stator side.

Magnetizing inductanceMagnetizing inductance Lm in henries (H), referred to the stator side.




Initial rotor speedInitial mechanical rotor speed ωm,0 in s−1.

Initial rotor positionInitial mechanical rotor angle θm,0 in radians. If θm,0 is an integer multipleof 2π/p the stator windings are aligned with the rotor windings at simula-tion start.

490


Initial stator currentsA two-element vector containing the initial stator currents is,a,0 and is,b,0of phases a and b in amperes (A).

Initial stator fluxA two-element vector containing the initial stator flux Ψ′s,d,0 and Ψ′s,q,0 inthe stationary reference frame in Vs.

Probe Signals Stator phase currentsThe three-phase stator winding currents is,a, is,b and is,c, in A. Currentsflowing into the machine are considered positive.

Rotor phase currentsThe three-phase rotor winding currents i′r,a, i′r,b and i′s,c in A, referred tothe stator side. Currents flowing into the machine are considered positive.

Stator flux (dq)The stator flux linkages Ψs,d and Ψs,q in the stationary reference frame inVs:

Ψs,d = Lls is,d + Lm

(is,d + i′r,d

)Ψs,q = Lls is,q + Lm

(is,q + i′r,q

)Magnetizing flux (dq)

The magnetizing flux linkages Ψm,d and Ψm,q in the stationary referenceframe in Vs:

Ψm,d = Lm

(is,d + i′r,d

)Ψm,q = Lm

(is,q + i′r,q

)Rotor flux (dq)

The rotor flux linkages Ψ′r,d and Ψ′r,q in the stationary reference frame inVs.




491


Induction Machine (Open Stator Windings)

Purpose Non-saturable induction machine with squirrel-cage rotor and open statorwindings


Description This model of a squirrel-cage induction machine can only be used with thecontinuous state-space method. The machine model is based on a stationaryreference frame (Clarke transformation). A sophisticated implementation ofthe Clarke transformation facilitates the connection of external inductances inseries with the stator windings.

The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motor mode,otherwise in generator mode. All electrical variables and parameters areviewed from the stator side. In the component icon, the positive terminal ofphase a of the stator windings is marked with a dot.

In order to inspect the implementation, please select the component in yourcircuit and choose Look under mask from the Subsystem submenu of theEdit menu.

Electrical System:



(is,d + i′r,d

)Ψr,q = L′lr i

′r,q + Lm

(is,q + i′r,q

)The three-phase voltages vs,a, vs,b and vs,c across the individual stator wind-ings are transformed into dq0 quantities:

vs,d

vs,q

vs,0

=

23 − 1

3 − 13

0 1√3− 1√

3

13

13

13

·vs,a

vs,b

vs,c


492

Induction Machine (Open Stator Windings)

Rs Lls

Lm

L'lr R'r-ω∙ Ψ 'r,q

+

−

vs,d

is,d i'r,d

d-axis

Rs Lls

Lm


+

−

vs,q

is,q i'r,q

q-axis

Rs

Lls

+

−

vs,0

is,0

0-axis

is,a

is,b

is,c

=

1 0 1

− 12

√3

2 1

− 12 −

√3

2 1

·is,d

is,q

is,0



Te =3

2pLm

(is,q i


)493


Mechanical System


ωm =1


ω = pωm


θm = ωm

θ = p θm

Parameters Most parameters for the Induction Machine with slip-ring rotor (see page 488)are also applicable for this machine. Only the following parameter differs:

Initial stator currentsA three-element vector containing the initial stator currents is,a,0, is,b,0 andis,c,0 of phase a, b and c in amperes (A).

Probe Signals Most probe signals for the Induction Machine with slip-ring rotor (see page488) are also available with this machine. Only the following probe signal isdifferent:

Rotor currentsThe rotor currents i′r,d and i′r,q in the stationary reference frame in A, re-ferred to the stator side.

494

Induction Machine (Squirrel Cage)


Purpose Non-saturable induction machine with squirrel-cage rotor


Description This model of a squirrel-cage induction machine can only be used with thecontinuous state-space method. If you want to use the discrete state-spacemethod or if you need to take saturation into account, please use the Induc-tion Machine with Saturation (see page 498) and short-circuit the rotor termi-nals.

The machine model is based on a stationary reference frame (Clarke transfor-mation). A sophisticated implementation of the Clarke transformation facil-itates the connection of external inductances in series with the stator wind-ings.

The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motormode, otherwise in generator mode. All electrical variables and parametersare viewed from the stator side. In the component icon, phase a of the statorwinding is marked with a dot.

In order to inspect the implementation, please select the component in yourcircuit and choose Look under mask from the Subsystem submenu of theEdit menu.

Electrical System



(is,d + i′r,d

)Ψr,q = L′lr i

′r,q + Lm

(is,q + i′r,q

)The three-phase voltages vs,ab and vs,bc at the stator terminals are trans-formed into dq quantities: vs,d

vs,q

=

23

13

0 1√3

· vs,ab

vs,bc

495


Rs Lls

Lm

L'lr R'r-ω∙ Ψ 'r,q

+

−

vs,d

is,d i'r,d

d-axis

Rs Lls

Lm


+

−

vs,q

is,q i'r,q

q-axis


is,a

is,b

is,c

=

1 0

− 12

√3

2

− 12 −

√3

2

· is,d

is,q



Te =3

2pLm

(is,q i


)Mechanical System


ωm =1


ω = pωm

496



θm = ωm

θ = p θm

Parameters Same as for the Induction Machine with slip-ring rotor (see page 488).

Probe Signals Most probe signals for the Induction Machine with slip-ring rotor (see page488) are also available with this squirrel-cage machine. Only the followingprobe signal is different:

Rotor currentsThe rotor currents i′r,d and i′r,q in the stationary reference frame in A, re-ferred to the stator side.

497


Induction Machine with Saturation

Purpose Induction machine with slip-ring rotor and main-flux saturation

Description The Induction Machine with Saturation models main flux saturation by meansof a continuous function.The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motor mode,otherwise in generator mode. All electrical variables and parameters areviewed from the stator side. In the component icon, phase a of the stator androtor winding is marked with a dot.

Electrical System:

Rs Lls

Lm

L'lr -ω∙ Ψ 'r,q R'r

+

−

vs,d

+

−

v'r,d

is,d i'r,d

d-axis

Rs Lls

Lm


+

−

vs,q

+

−

v'r,q

is,q i'r,q

q-axis

The rotor flux is defined as


(is,d + i′r,d

)Ψr,q = L′lr i

′r,q + Lm

(is,q + i′r,q

).

The machine model offers two different implementations of the electrical sys-tem: a traditional stationary reference frame and a voltage-behind-reactanceformulation.

498


Stationary Reference Frame This implementation is based on machineequations in the stationary reference frame (Clarke transformation). Constantcoefficients in the stator and rotor equations make the model numerically ef-ficient. However, interfacing the reference frame with the external 3-phasenetwork may be difficult. Since the coordinate transformations are based onvoltage-controlled current sources inductors and naturally commutated de-vices such as diode rectifiers may not be directly connected to the stator ter-minals. In these cases, fictitious RC snubbers are required to create the neces-sary voltages across the terminals. The implementation can be used with boththe continuous and the discrete state-space method.

Voltage behind Reactance This formulation allows for direct interfacing ofarbitrary external networks with the 3-phase stator terminals. The rotor dy-namics are expressed using explicit state-variable equations while the statorbranch equations are described in circuit form. However, due to the resultingtime-varying inductance matrices, this implementation is numerically less effi-cient than the traditional reference frame.

In both implementations, the value of the main flux inductances Lm,d andLm,q are not constant but depend on the main flux linkage Ψm as illustratedin the Ψm/im diagram. For flux linkages far below the transition flux ΨT, the

∂Ψ/∂i = Lm,0

∂Ψ/∂i = Lm,sat

fT = 4

fT = 2

fT = 1

fT = 0.5

im

Ψm

ΨT

relationship between flux and current is almost linear and is determined bythe unsaturated magnetizing inductance Lm,0. For large flux linkages the re-lationship is governed by the saturated magnetizing inductance Lm,sat. ΨT de-fines the knee of the transition between unsaturated and saturated main fluxinductance. The tightness of the transition is defined with the form factor fT.If you do not have detailed information about the saturation characteristic of

499


your machine, fT = 1 is a good starting value. The function

plsaturation(Lm0,Lmsat,PsiT,fT)

plots the main flux vs. current curve and the magnetizing inductance vs. cur-rent curve for the parameters specified.

The model accounts for steady-state cross-saturation, i.e. the steady-statemagnetizing inductances along the d-axis and q-axis are functions of the cur-rents in both axes. In the implementation, the stator currents and the mainflux linkage are chosen as state variables. With this type of model, the repre-sentation of dynamic cross-saturation can be neglected without affecting themachine’s performance. The computation of the time derivative of the mainflux inductance is not required.




Te =3

2p (is,q Ψs,d − is,d Ψs,q)

Mechanical System


ωm =1


ω = pωm


θm = ωm

θ = p θm

500


Parameters ModelImplementation in the stationary reference frame or as a voltage behindreactance.

Stator resistanceStator winding resistance Rs in ohms (Ω).

Stator leakage inductanceStator leakage inductance Lls in henries (H).

Rotor resistanceRotor winding resistance R′r in ohms (Ω), referred to the stator side.

Rotor leakage inductanceRotor leakage inductance L′lr in henries (H), referred to the stator side.

Unsaturated magnetizing inductanceUnsaturated main flux inductance Lm,0, in henries (H), referred to the sta-tor side.

Saturated magnetizing inductanceSaturated main flux inductance Lm,sat in henries (H), referred to the statorside. If you do not want to model saturation, set Lm,sat = Lm,0.

Magnetizing flux at saturation transitionTransition flux linkage ΨT, in Vs, defining the knee between unsaturatedand saturated main flux inductance.

Tightness of saturation transitionForm factor fT defining the tightness of the transition between unsatu-rated and saturated main flux inductance. The default is 1.




Initial rotor speedInitial mechanical rotor speed ωm,0 in s−1.

Initial rotor positionInitial mechanical rotor angle θm,0 in radians. If θm,0 is an integer multipleof 2π/p the stator windings are aligned with the rotor windings at simula-tion start.

501


Initial stator currentsA two-element vector containing the initial stator currents is,a,0 and is,b,0of phases a and b in amperes (A).

Initial stator fluxA two-element vector containing the initial stator flux Ψs,d,0 and Ψs,q,0 inthe stationary reference frame in Vs.

Probe Signals Stator phase currentsThe three-phase stator winding currents is,a, is,b and is,c, in A. Currentsflowing into the machine are considered positive.

Rotor phase currentsThe three-phase rotor winding currents i′r,a, i′r,b and i′s,c in A, referred tothe stator side. Currents flowing into the machine are considered positive.

Stator flux (dq)The stator flux linkages Ψs,d and Ψs,q in the stationary reference frame inVs.

Magnetizing flux (dq)The magnetizing flux linkages Ψm,d and Ψm,q in the stationary referenceframe in Vs.

Rotor flux (dq)The rotor flux linkages Ψ′r,d and Ψ′r,q in the stationary reference frame inVs, referred to the stator side.




ReferencesD. C. Aliprantis, O. Wasynczuk, C. D. Rodriguez Valdez, “A voltage-behind-

reactance synchronous machine model with saturation and arbitrary ro-tor network representation”, IEEE Transactions on Energy Conversion,Vol. 23, No. 2, June 2008.

K. A. Corzine, B. T. Kuhn, S. D. Sudhoff, H. J. Hegner, “An improved methodfor incorporating magnetic saturation in the Q-D synchronous ma-chine model”, IEEE Transactions on Energy Conversion, Vol. 13, No. 3,Sept. 1998.

502


E. Levi, “A unified approach to main flux saturation modelling in D-Q axismodels of induction machines”, IEEE Transactions on Energy Conver-sion, Vol. 10, No. 3, Sept. 1995.

E. Levi, “Impact of cross-saturation on accuracy of saturated induction ma-chine models”, IEEE Transactions on Energy Conversion, Vol. 12, No. 3,Sept. 1997.

503


Inductor

Purpose Ideal inductor


Description This component provides one or multiple ideal inductors between its two elec-trical terminals. If the component is vectorized, a magnetic coupling can bespecified between the internal inductors. Inductors may be switched in seriesonly if their momentary currents are equal.

Note An inductor may not be connected in series with a current source. Doingso would create a dependency between an input variable (the source current)and a state variable (the inductor current) in the underlying state-space equa-tions.

Parameters InductanceThe inductance in henries (H). All finite positive and negative values areaccepted, including 0. The default is 0.001.

In a vectorized component, all internal inductors have the same induc-tance if the parameter is a scalar. To specify the inductances individuallyuse a vector [L1 L2 . . . Ln] . The length n of the vector determines the com-ponent’s width:

v1

v2

...

vn

=

L1 0 · · · 0

0 L2 · · · 0...

.... . .

...

0 0 · · · Ln

·

ddt i1

ddt i2

...ddt in

In order to model a magnetic coupling between the internal inductors en-ter a square matrix. The size n of the matrix corresponds to the width ofthe component. Li is the self inductance of the internal inductor and Mi,j

the mutual inductance:

504

Inductor

v1

v2

...

vn

=

L1 M1,2 · · · M1,n

M2,1 L2 · · · M2,n

......

. . ....

Mn,1 Mn,2 · · · Ln

·

ddt i1

ddt i2

...ddt in

The inductance matrix must be invertible, i.e. it may not be singular. Asingular inductance matrix results for example when two or more induc-tors are ideally coupled. To model this, use an inductor in parallel with anIdeal Transformer (see page 456).

The relationship between the coupling factor ki,j and the mutual induc-tance Mi,j is

Mi,j = Mj,i = ki,j ·√Li · Lj

Initial currentThe initial current through the inductor at simulation start, in amperes(A). This parameter may either be a scalar or a vector corresponding tothe width of the component. The direction of a positive initial current isindicated by a small arrow in the component symbol. The default of theinitial current is 0.

Probe Signals Inductor currentThe current flowing through the inductor, in amperes (A). The direction ofa positive current is indicated with a small arrow in the component sym-bol.

Inductor voltageThe voltage measured across the inductor, in volts (V).

505


Inertia

Purpose Model a rotating body with inertia


Description This component models a rotating body with inertia and two rigidly connectedflanges. The angular speed is determined by the equation

d

dtω =

1

J· (τ1 + τ2)

where τ1 and τ2 are the torques acting at the two flanges towards the body.

Parameters Moment of inertiaThe moment of inertia J , in kg·m2

rad2 .

Initial speedThe initial angular speed ω0, in rad

s .

Initial angleThe initial angle θ0, in radians. May be specified in order to provide properinitial conditions if absolute angles are measured anywhere in the system.Otherwise, this parameter can be left blank.

Probe Signals SpeedThe angular speed of the body.

AngleThe absolute angle of the body (wrapped between −π and π).

506

Initial Condition

Initial Condition

Purpose Output specified initial value in the first simulation step


Description The Initial Condition block outputs the initial value in the very first simula-tion step and the input value at all subsequent steps.

If this block is placed inside an algebraic loop, it provides an initial guess ofthe value of its output signal to be used by the equation solver at the start ofa simulation. See the section “Block Sorting” (on page 31) for more informa-tion on algebraic loops.

Parameter Initial valueThe initial output value in the first simulation step.

507


Integrator

Purpose Integrate input signal with respect to time


Description The Integrator block outputs the integral of its input signal at the currenttime step. The integrator state may saturate at an upper and lower limit, orit can be wrapped between two limits. It can be reset to its initial value by anexternal trigger signal. The initial value may be provided either via a parame-ter or via an input signal.

Interaction with the Solver

Simulation with the Continuous State-Space Method When simulatedwith the continuous method, the input signal is simply passed on to the solverfor integration.

Simulation with the Discrete State-Space Method When simulated withthe discrete method, the input signal is integrated within PLECS using theForward Euler method.

Parameters External resetThe behaviour of the external reset input. The values rising, falling andeither cause a reset of the integrator on the rising, falling or both edgesof the reset signal. A rising edge is detected when the signal changes from0 to a positive value, a falling edge is detected when the signal changesfrom a positive value to 0. If the value level is chosen, the output signalkeeps the initial value while the reset input is not 0.

Initial condition sourceSpecifies whether the initial condition is provided via the Initial condi-tion parameter (internal) or via an input signal (external).

Initial conditionThe initial condition of the integrator. The value may be a scalar or a vec-tor corresponding to the implicit width of the component. This param-eter is shown only if the Initial condition source parameter is set tointernal.

508

Integrator

Show state portSpecifies whether to show an additional state output port. The state portis updated at a slightly different point in the block execution order (i.e. be-fore the reset and initial condition inputs are evaluated) and may thereforebe used to calculate an input signal for the external reset input or the ini-tial condition input.

Enable wrappingWhen set to on, the integrator state is wrapped between the Upper wrap-ping limit and Lower wrapping limit parameters. The default is off.Note that wrapping is mutually exclusive with saturation.

Upper saturation limitAn upper limit for the integrator state. If the value is inf, the state is un-limited. This parameter is visible only if Enable wrapping is set to off.

Lower saturation limitA lower limit for the integrator state. If the value is -inf, the state is un-limited. This parameter is visible only if Enable wrapping is set to off.

Upper wrapping limitThe upper wrapping limit for the integrator state. When the state exceedsthe upper limit, it is wrapped to the lower limit. This parameter is visibleonly if Enable wrapping is set to on.

Lower wrapping limitThe lower wrapping limit for the integrator state. When the state exceedsthe lower limit, it is wrapped to the upper limit. This parameter is visibleonly if Enable wrapping is set to on.

Probe Signal StateThe internal state of the integrator.

Note Both the external reset input and the initial condition input have directfeedthrough on the output signal. Therefore, feeding back the output signal tocreate the reset signal or an initial value will create an algebraic loop. This canbe avoided by using the state port instead.

509


JK Flip-flop

Purpose Implement edge-triggered JK flip-flop


Description The JK flip-flop changes its output when an edge in the clock signal is de-tected according to the following truth table:

J K Q /Q


0 1 0 1

1 0 1 0

1 1 /Qprev Qprev

As long as no edge is detected in the clock signal the outputs remain stable.

When a trigger occurs and J = K = 1 the outputs are toggled, i.e change from1 to 0 or vice versa.

The inputs J and K are latched, i.e. when a triggering edge in the clock signalis detected the values of J and K from the previous simulation step are usedto set the output. In other words, J and K must be stable for at least one sim-ulation step before the flip-flop is triggered by the clock signal.

Parameters Trigger edgeThe direction of the edge on which the inputs are read.

Initial stateThe state of the flip-flop at simulation start.

Probe Signals JThe input signal J.

KThe input signal K.

ClkThe clock input signal.


510

JK Flip-flop


511


Leakage Flux Path

Purpose Permeance of linear leakage flux path

Library Magnetic

Description This component models a magnetic leakage flux path. It establishes a linearrelationship between the magnetic flux Φ and the magneto-motive force F .Magnetic permeance P is the reciprocal of magnetic reluctance R:

P =1

R=

Φ

FThis component is equivalent to the Magnetic Permeance (see page 519). Theonly difference is the symbol.

Parameters Effective PermeanceMagnetic permeance of the leakage flux path, in webers per ampere-turn(Wb/A).




512

Linear Core

Linear Core

Purpose Linear magnetic core element

Library Magnetic

Description This component models a segment of a magnetic core. It establishes a linearrelationship between the magnetic flux Φ and the magneto-motive force F

Φ

F=µ0µrA

l

where µ0 = 4π × 10−7 N/A2 is the magnetic constant, µr is the relative per-meability of the material, A is the cross-sectional area and l the length of theflux path.

Parameters Cross-sectional areaCross-sectional area A of the flux path, in m2.


Rel. permeabilityRelative permeability µr of the core material.






513


Linear Transformer (2 Windings)

Purpose Single-phase transformer with winding resistance and optional core loss


Description This transformer models two coupled windings on the same core. The magne-tization inductance Lm and the core loss resistance Rm are modeled as linearelements. Their values are referred to the primary side. A stiff solver is rec-ommended if Rm is not infinite.

The electrical circuit for this component is given below:

Rm

L1 R1

Lm

i1 L2 R2 i2

n2n1

In the transformer symbol, the primary side winding is marked with a littlecircle. The secondary side winding is marked with a dot.

Parameters Leakage inductanceA two-element vector containing the leakage inductance of the primaryside L1 and the secondary side L2. The inductivity is given in henries (H).

Winding resistanceA two-element vector containing the resistance of the primary winding R1

and the secondary winding R2, in ohms (Ω).

Winding ratioThe ratio n1/n2 between the number of turns of the primary and sec-ondary winding.

Magnetization inductanceThe magnetization inductance Lm, in henries (H). The value is referred tothe primary side.

514


Core loss resistanceAn equivalent resistance Rm representing the iron losses in the trans-former core. The value in ohms (Ω) is referred to the primary side.

Initial currentA two-element vector containing the initial currents on the primary sidei1 and the secondary side i2, in amperes (A). The currents are consideredpositive if flowing into the transformer at the marked terminals. The de-fault is [0 0].

515



Purpose Single-phase transformer with winding resistance and optional core loss


Description This transformer models three coupled windings on the same core. The mag-netization inductance Lm and the core loss resistance Rm are modeled as lin-ear elements. Their values are referred to the primary side. A stiff solver isrecommended if Rm is not infinite.


RmLm

i1

n1

n2

n3

L3 R3 i3

L2 R2 i2L1 R1

In the transformer symbol, the primary side winding is marked with a littlecircle. The secondary winding is marked with a dot at the outside terminal,the tertiary winding with a dot at the inside terminal.

Parameters Leakage inductanceA three-element vector containing the leakage inductance of the primaryside L1, the secondary side L2 and the tertiary side L3. The inductivity isgiven in henries (H).

Winding resistanceA three-element vector containing the resistance of the primary windingR1, the secondary winding R2 and the tertiary winding R3, in ohms (Ω).

No. of turnsA three-element vector containing the number of turns of the primarywinding n1, the secondary winding n2 and the tertiary winding n3.

Magnetization inductanceThe magnetization inductance Lm, in henries (H). The value is referred tothe primary side.

516


Core loss resistanceAn equivalent resistance Rm representing the iron losses in the trans-former core. The value in ohms (Ω) is referred to the primary side.

Initial currentA three-element vector containing the initial currents on the primary sidei1, the secondary side i2 and the tertiary side i3, in amperes (A). The cur-rents are considered positive if flowing into the transformer at the markedterminals. The default is [0 0 0].

517


Logical Operator

Purpose Combine input signals logically


Description The selected Logical Operator is applied to the input signals. The output ofthe Logical Operator is 1 if the logical operation returns true, otherwise 0. Incase of a single input, the operator is applied to all elements of the input vec-tor.

Parameters OperatorChooses which logical operator is applied to the input signals. Availableoperators are• AND y = un & un−1 & . . . & u1 & u0

• OR y = un | un−1 | . . . | u1 | u0

• NAND y = ∼(un & un−1 & . . . & u1 & u0)

• NOR y = ∼(un | un−1 | . . . | u1 | u0)

• XOR y = un xor un−1 xor . . . xor u1 xor u0

• NOT y = ∼u

Number of inputsThe number of input terminals. If the NOT operator is selected, the numberof inputs is automatically set to 1.



518

Magnetic Permeance

Magnetic Permeance

Purpose Linear magnetic permeance

Library Magnetic

Description This component provides a magnetic flux path. It establishes a linear relation-ship between the magnetic flux Φ and the magneto-motive force F . Magneticpermeance P is the reciprocal of magnetic reluctance R:

P =1

R=

Φ

F

Parameters PermeanceMagnetic permeance of the flux path, in webers per ampere-turn (Wb/A).




519


Magnetic Port

Purpose Add magnetic connector to subsystem

Library Magnetic

Description Magnetic ports are used to establish magnetic connections between aschematic and the subschematic of a subsystem (see page 662). If you copy aMagnetic Port block into the schematic of a subsystem, a terminal will be cre-ated on the subsystem block. The name of the port block will appear as theterminal label. If you choose to hide the block name by unselecting the showname option in the block menu, the terminal label will also disappear.


Magnetic Ports in a Top-Level Schematic

In PLECS Blockset, if a Magnetic Port is placed in a top-level schematic, thePLECS Circuit block in the Simulink model will show a corresponding mag-netic terminal, which may be connected with other magnetic terminals of thesame or a different PLECS Circuit block. The Magnetic Port is also assigned aunique physical port number. Together with the parameter Location on cir-cuit block the port number determines the position of the magnetic terminalof the PLECS Circuit block.

For compatibility reasons you can also place an Magnetic Port in a top-levelschematic in PLECS Standalone. However, since there is no parent system toconnect to, such a port will act like an isolated node.

Parameter WidthThe width of the connected magnetic path. The default auto means thatthe width is inherited from connected components.

Port numberIf a Magnetic Port is placed in a top-level schematic in PLECS Blockset,this parameter determines the position, at which the corresponding termi-nal appears on the PLECS Circuit block.

Location on circuit blockIf a Magnetic Port is placed in a top-level schematic in PLECS Blockset,this parameter specifies the side of the PLECS Circuit block on which the

520

Magnetic Port

corresponding terminal appears. By convention, left refers to the sideon which also input terminals are shown, and right refers to the side onwhich also output terminals are shown.

521


Magnetic Resistance

Purpose Effective magnetic resistance for modeling losses

Library Magnetic

Description Magnetic resistances (analogous to electrical resistors) are used to modelfrequency-depending losses in the magnetic circuit. They can be connected inseries or in parallel to a permeance, depending on the nature of the specificloss. The energy relationship is maintained as the power

Ploss = F Φ = F 2/Rm

converted into heat in a magnetic resistance corresponds to the power lost inthe electrical circuit.

Parameter ResistanceEffective magnetic resistance Rm, in A · (Wb/s)−1.

Probe Signal MMFThe magneto-motive force measured from the marked to the unmarkedterminal, in ampere-turns (A).

522

Manual Double Switch

Manual Double Switch

Purpose Manual changeover switch with two positions


Description This changeover switch provides an ideal switch with two positions. The po-sition can be toggled between upper (0) and lower (1) by double-clicking thecomponent. Which input signal currently is connected to the output signal isindicated in the icon.

Parameter Switch positionThe current position of the switch. Possible values are 0 (upper position)and 1 (lower position).

Probe Signal Switch positionState of the internal switch. The signal outputs 0 if the switch is in theupper position, and 1 if it is in the lower position.

523


Manual Signal Switch

Purpose Switch between two input signals by double-clicking the component


Description The Signal Switch can be in the on-state or the off-state, connecting the firstor the second input to the output, respectively. The state can be toggled bydouble-clicking the component. Which input signal currently is connected tothe output signal is indicated in the icon.

Parameter StateThe current switch state, either “on” or “off”.

Probe Signals InputsThe block input signals.


Switch positionThe current state of the switch. The output is 0 while the switch is in theoff-state and 1 while it is in the on-state.

524

Manual Switch

Manual Switch

Purpose Manual on-off switch


Description This Switch provides an ideal short or open circuit between its two electricalterminals. The position can be toggled between upper (0, off) and lower (1, on)by double-clicking the component. Which input signal currently is connectedto the output signal is indicated in the icon.

Parameter Switch positionThe current position of the switch. Possible values are 0 (upper position,off) and 1 (lower position, on).

Probe Signal Switch positionState of the internal switch. The signal outputs 0 if the switch is in theupper position (off), and 1 if it is in the lower position (on).

525


Manual Triple Switch

Purpose Manual changeover switch with three positions


Description This changeover switch provides an ideal switch with three positions. The po-sition can be toggled between upper (-1), middle (0) and lower (1) by double-clicking the component. Which input signal currently is connected to the out-put signal is indicated in the icon.

Parameter Switch positionThe current position of the switch. Possible values are -1 (upper position),0 (middle position) and 1 (lower position).

Probe Signal Switch positionState of the internal switch. The signal outputs 0 if the switch is in themiddle position, 1 if it is in the lower position and -1 if it is in the upperposition.

526

Mass

Mass

Purpose Model a sliding body with inertia

Library Mechanical / Translational / Components

Description This component models a sliding body with inertia and two rigidly connectedflanges. The translational speed is determined by the equation

d

dtv =

1

m· (F1 + F2)

where F1 and F2 are the forces acting at the two flanges towards the body.

Parameters MassThe mass m, in kg.

Initial speedThe initial speed v0, in m

s .

Initial positionThe initial position x0, in meters. May be specified in order to provideproper initial conditions if absolute positions are measured anywhere inthe system. Otherwise, this parameter can be left blank.

Probe Signals SpeedThe speed of the body.

PositionThe absolute position of the body.

527


Math Function

Purpose Apply specified mathematical function


Description The Math Function block calculates the output by applying the specified func-tion to the input. For functions that require two inputs, the first input ismarked with a black dot.

Parameter FunctionChooses which function is applied to the input signals. Available functionsare• square y = u2

• square root y =√u

• exponential y = eu

• logarithm y = ln(u)

• power y = uv

• mod y = mod(u, v)

• rem y = rem(u, v)

mod and rem both return the floating-point remainder of u/v. If u and vhave different signs, the result of rem has the same sign as u while the re-sult of mod has the same sign as v.



528

Memory

Memory

Purpose Provide input signal from previous major time step

Library Control / Delays

Description The Memory block delays the input signal by a single major time step takenby the solver.

Note

• The Memory block implicitly has a semi-continuous sample time. If you needto specify a sample time explicitly, please use the Delay block instead (seepage 387).

• If a variable-step solver is used the delay time of the Memory block alsovaries. If you use the Memory block to decouple an algebraic loop, this willproduce a dead-time with an uncontrolled jitter. Please consider using a lowpass filter instead.

Parameter Initial conditionThe initial output during the first major time step.



529


Meter (3-Phase)

Purpose Measure voltages and currents of 3-phase system


Description The meter block acts as a set of volt- and ammeters. Voltages can be mea-sured from line to ground (Va, Vb and Vc) or from line to line (Vab, Vbc, Vca) de-pending on the Voltage measurement parameter. The output for voltage andcurrent is a vectorized signal with three elements.

Parameter Voltage measurementDetermine whether the voltages are measured from line to ground or fromline to line.

Probe Signals Measured voltageThe measured voltages as a vector with three elements.

Measured currentThe measured currents as a vector with three elements.

530

Minimum / Maximum

Minimum / Maximum

Purpose Output input signal with highest resp. lowest value


Description The Minimum / Maximum block compares its input signals against each other.If the Operation parameter is set to Minimum, the output will be set to thevalue of the input signal with the lowest value. If the Operation parameteris set to Maximum, the output will be set to the value of the input signal withthe highest value.

In case of a single input, all elements of the input vector are compared. Vec-torized input signals of the same width are compared element wise and resultin a vectorized output signal. If vectorized and scalar input signals are mixed,the scalar input signals are expanded to the width of the vectorized input sig-nals.

Parameters OperationSelects between Minimum and Maximum as described above.

Number of inputsThe number of inputs.



531


MMF Meter

Purpose Output the measured magneto-motive force

Library Magnetic

Description The MMF Meter measures the magneto-motive force between its two mag-netic terminals and provides it as a signal at the output of the component.A positive MMF is measured when the magnetic potential at the terminalmarked with a “+” is greater than at the unmarked one. The output signalcan be made accessible in Simulink with an Output block (see page 641) or bydragging the component into the dialog box of a Probe block.

Note The MMF Meter is ideal, i.e. it has an zero internal permeance. Hence,if multiple meters are connected in series the MMF across an individual meteris undefined. This produces a run-time error.

Probe Signal MMFThe measured magneto-motive force in ampere-turns (A).

532

MMF Source (Constant)

MMF Source (Constant)

Purpose Generate a constant magneto-motive force

Library Magnetic

Description The Constant MMF Source generates a constant magneto-motive force (MMF)between its two magnetic terminals. The MMF is considered positive at theterminal marked with a “+”.

Note An MMF source may not be short-circuited or connected in parallel to apermeance or any other MMF source.

Parameter VoltageThe magnitude of the MMF, in ampere-turns (A). The default value is 1.

Probe Signal MMFThe magneto-motive force of the source, in ampere-turns (A).

533


MMF Source (Controlled)

Purpose Generate a variable magneto-motive force

Library Magnetic

Description The Controlled MMF Source generates a variable magneto-motive force(MMF) between its two terminals. The MMF is considered positive at the ter-minal marked with a “+”. The momentary MMF is determined by the signalfed into the input of the component.

Note An MMF source may not be short-circuited or connected in parallel to apermeance or any other MMF source.

Parameter Allow state-space inliningFor expert use only! When set to on and the input signal is a linear com-bination of magnetic measurements, PLECS will eliminate the input vari-able from the state-space equations and substitute it with the correspond-ing output variables. The default is off.

Probe Signal MMFThe magneto-motive force of the source, in ampere-turns (A).

534

Model Reference

Model Reference

This block is included only in the PLECS Standalone library.

Purpose Reference a subsystem from another model

Library System

Description A Model Reference allows you to reference a subsystem from another model sothat when the original subsystem is changed, the reference is updated auto-matically. This concept is similar to library links with the difference that thereferenced model file path can be specified relative to the referencing model.

To define a model reference, double-click on the Model Reference block to openthe Model Reference dialog, then drag the subsystem that you want to refer-ence into the dialog. The labels Model file and Subsystem path will be up-dated to reflect the subsystem that is referenced. By default, the referencedmodel file is specified with a path relative to the referencing model, but youcan change this with the Model file reference selector.

When you click OK to apply the settings, the Model Reference block is re-placed with a copy of the referenced subsystem that is marked with a smallsolid curved arrow ( ) in the lower left corner of the component icon. A right-click on this arrow opens a context menu that allows you to break the link, toedit the model reference, or to show the original subsystem.

535


Monoflop

Purpose Generate pulse of specified duration when triggered


Description The output of the Monoflop changes to 1 when the trigger condition is fulfilled.When the trigger condition is no longer fulfilled, the output stays 1 for thegiven duration and changes to 0 afterwards.

Depending on the trigger type the behavior is as follows:

risingThe output is set to 1 for the given duration when the input changes from0 to a non-zero value.

fallingThe output is set to 1 for the given duration when the input changes froma non-zero value to 0.

levelThe output is set to 1 when the input is a non-zero value. It stays 1 forthe given duration after the input returns to 0. With this trigger type, theMonoflop acts like a Turn-off delay.

The Monoflop can be retriggered, i.e. if the trigger condition is fulfilled againwhile the output is 1, the pulse duration is extended.

The pulse duration can be specified statically via a parameter or dynamicallyduring the simulation via an input signal.

Parameters Trigger typeThe trigger type as described above.

Pulse duration sourceSpecifies whether the duration is determined by the Pulse duration pa-rameter (internal) or by an external input signal (external).

Pulse durationThe duration for which the output is set to 1, in seconds. If set to 0, theMonoflop is disabled and outputs 0 at all times.

Duration rounding (fixed-step)If the duration is determined by an external signal and the Monoflop isused with a fixed-step solver, this parameter specifies how the duration isrounded to an integer multiple of the fixed step size.

536

Monoflop



537


MOSFET

Purpose Ideal MOSFET with optional on-resistance


Description The Metal Oxide Semiconductor Field Effect Transistor is a semiconductorswitch that is controlled via the external gate. It conducts a current fromdrain to source (or vice-versa) only if the gate signal is not zero.



Initial conductivityInitial conduction state of the MOSFET. The MOSFET is initially blockingif the parameter evaluates to zero, otherwise it is conducting.

Thermal descriptionSwitching losses, conduction losses and thermal equivalent circuit of thecomponent. For more information see chapter “Thermal Modeling” (onpage 119). If no thermal description is given the losses are calculatedbased on the voltage drop von = Ron · i.


Probe Signals MOSFET voltageThe voltage measured between drain and source.

MOSFET currentThe current through the MOSFET flowing from drain to source.

MOSFET gate signalThe gate input signal of the MOSFET.

538

MOSFET

MOSFET conductivityConduction state of the internal switch. The signal outputs 0 when theMOSFET is blocking, and 1 when it is conducting.

MOSFET junction temperatureTemperature of the first thermal capacitor in the equivalent Cauer net-work.

MOSFET conduction lossContinuous thermal conduction losses in watts (W). Only defined if thecomponent is placed on a heat sink.

MOSET switching lossInstantaneous thermal switching losses in joules (J). Only defined if thecomponent is placed on a heat sink.

539


MOSFET Converter (3ph)

Purpose 3-phase MOSFET converter


Description Implements a three-phase two-level MOSFET converter with reverse diodes.The gate input is a vector of three signals – one per leg. The upper MOSFET,connected to the positive dc level, is on if the corresponding gate signal is posi-tive. The lower MOSFET is on if the gate signal is negative. If the gate signalis zero both MOSFETs in the leg are switched off.


• The basic MOSFET Converter is modeled using the component MOSFETwith Diode (see page 541). PLECS needs only six internal switches to simu-late this converter. Only the on-resistances of the MOSFETs can be entered.

• The MOSFET Converter with Parasitics is based on individual MOSFET(see page 538) and Diode (see page 388) components. In this model you mayspecify forward voltages and on-resistances separately for the MOSFETsand diodes.

Note Due to the switching conditions of the MOSFET with Diode (see page541), this device cannot be turned off actively while the current is exactly zero.This may result in unexpected voltage waveforms if the converter is not loaded.

To resolve this problem, either use the MOSFET Converter with Parasitics,or allow a small non-zero load current to flow by connecting a large load resis-tance to the converter.

Parameters For a description of the parameters see the documentation of the MOSFETwith Diode (on page 541), the MOSFET (on page 538) and the Diode (on page388).

Probe Signals The two-level MOSFET converters provide six or twelve probe signals, each avector containing the appropriate quantities of the individual devices: voltage,current, conductivity, conduction loss and switching loss. The vector elementsare ordered top-to-bottom, left-to-right: a+, a-, b+, b-, c+, c-.

540

MOSFET with Diode

MOSFET with Diode

Purpose Ideal MOSFET with ideal anti-parallel diode


Description This model of a Metal Oxide Semiconductor Field Effect Transistor has an in-tegrated anti-parallel diode. The diode is usually included in power MOSFETpackages.

This device is modeled as a single ideal switch that closes when the gate sig-nal is not zero or the voltage becomes negative and opens when the gate sig-nal is zero and the current becomes positive.

Note Due to the switching conditions described above, this device cannot beturned off actively while the current is exactly zero. This may result in unex-pected voltage waveforms if the device is used e.g. in an unloaded converter.

To resolve this problem, either use an individual MOSFET (see page 538) withan individual anti-parallel Diode (see page 388), or allow a small non-zero loadcurrent to flow by connecting a large load resistance to the converter.




541


Probe Signals Device voltageThe voltage measured between drain and source. The device voltage cannever be negative.

Device currentThe current through the device. The current is positive if it flows throughthe MOSFET from drain to source and negative if it flows through thediode from source to drain.






542

MOSFET with Limited di/dt

MOSFET with Limited di/dt

Purpose Dynamic MOSFET model with finite current slopes during turn-on and turn-off


Description In contrast to the ideal MOSFET model (see page 538) that switches instan-taneously, this model includes drain current transients during switching.Thanks to the continuous current decay during turn-off, stray inductancesmay be connected in series with the device.

This MOSFET model is used to simulate overvoltages produced by parasiticinductances and the reverse recovery effect of diodes. Due to simplified voltageand current transient waveforms, the model is not suited for the simulationof switching losses. The dynamic behavior of this MOSFET model is identicalwith the one of the IGBT with limited di/dt (see page 480).

Note

• Due to the small time-constants introduced by the turn-on and turn-off tran-sients a stiff solver is recommended for this device model.

• If multiple MOSFETs are connected in series the off-resistance may not beinfinite.

Parameters Blocking voltageMaximum voltage VDSS in volts (V) that under any conditions should beapplied between drain and source.

Continuous drain currentMaximum dc current ID in amperes (A) that the MOSFET can conduct.


Off-resistanceThe resistance Roff of the blocking device, in ohms (Ω). The default is 1e6.This parameter may be set to inf unless multiple MOSFETs are con-nected in series.

543


Rise timeTime tr in seconds between instants when the drain current has risen from10 % to 90 % of the continuous drain current ID.

Fall timeTime tf in seconds between instants when the drain current has droppedfrom 90 % to 10 % of its initial value along an extrapolated straight linetangent the maximum rate-of-change of the current.

Fall timeTime tf in seconds between instants when the drain current has droppedfrom 90 % to 10 % of its initial value along an extrapolated straight linetangent the maximum rate-of-change of the current decay.

Stray inductanceInternal inductance Lσ in henries (H) measured between the drain andsource terminals.

Initial currentThe initial current through the component at simulation start, in amperes(A). The default is 0.

Probe Signals MOSFET voltageThe voltage measured between drain and source.

MOSFET currentThe current through the MOSFET flowing from drain to source.

MOSFET conductivityConduction state of the internal switch. The signal outputs 0 when theMOSFET is blocking, and 1 when it is conducting.

544

Moving Average

Moving Average

Purpose Continuously average input signal over specified time period


Description The Moving Average filter averages a continuous input signal u over the spec-ified averaging time T . The output y is continuously updated in every simula-tion step:

y(t) =1

T

ˆ t

t−Tu(τ) dτ

The implementation of this block avoids accumulating numerical integrationerrors typically associated with continuous-time implementations of FIR fil-ters. However, the Moving Average filter is computationally more expensiveand less accurate than the similar Periodic Average (see page 562).

Parameters Initial ConditionThe initial condition describes the input signal before simulation start. Ifthe input is a scalar signal the parameter must be a scalar too. If inputand output are vectorized signals a vector can be used. The number of el-ements in the vector must match the number of input signals. The defaultvalue of this parameter is 0.

Averaging timeThe length of the averaging period in sec.


OutputThe filtered output signal.

545


Multiport Signal Switch

Purpose Select one of multiple input signals depending on control signal.


Description The block output is connected to the block input specified by the scalar valueat the control terminal. If the control terminal signal is not in the range of theavailable input terminals, the default input terminal is used.

Parameters Number of inputsThe number of input terminals. It has to be a literal integer value biggerthan 2.

Default inputThe default input terminal if the control signal is out of range.



Switch positionThe state of the switch position. This is the control signal or, in case thecontrol signal is out of range, the default input parameter.

Out of rangeA boolean value that is true if the control input is out of range.

546

Mutual Inductor

Mutual Inductor

Purpose Ideal mutual inductor


Description This component provides two or more coupled inductors. Electrically, it isequivalent with a vectorized Inductor (see page 504). In contrast to the vec-torized Inductor, this component displays the individual inductors in theschematic as separate windings.

In the symbol of the mutual inductor, the positive terminal of winding 1 ismarked with a little circle. The positive terminals of all other windings aremarked with dots.

Note An inductor may not be connected in series with a current source. Doingso would create a dependency between an input variable (the source current)and a state variable (the inductor current) in the underlying state-space equa-tions.

Parameters Number of windingsThe number of ideal inductors represented by the component.

InductanceThe inductance in henries (H). All finite positive and negative values areaccepted, including 0.

If the parameter is a scalar or a vector no coupling exists between thewindings. In order to model a magnetic coupling between the windings asquare matrix must be entered. The size n of the matrix corresponds tothe number of windings. Li is the self inductance of the internal inductorand Mi,j the mutual inductance:

v1

v2

...

vn

=

L1 M1,2 · · · M1,n

M2,1 L2 · · · M2,n

......

. . ....

Mn,1 Mn,2 · · · Ln

·

ddt i1

ddt i2

...ddt in

547


The inductance matrix must be invertible, i.e. it may not be singular. Asingular inductance matrix results for example when two or more induc-tors are ideally coupled. To model this, use an inductor in parallel with anIdeal Transformer (see page 456).

The relationship between the coupling factor ki,j and the mutual induc-tance Mi,j is

Mi,j = Mj,i = ki,j ·√Li · Lj

Initial currentThe initial current in the windings at simulation start, in amperes (A).This parameter may either be a scalar or a vector corresponding to thenumber of windings. The direction of the initial current inside the com-ponent is from the positive to the negative terminal. The default of theinitial current is 0.

Probe Signals Winding i currentThe current flowing through winding i, in amperes (A).

Winding i voltageThe voltage measured across winding i, in volts (V).

548

Mutual Inductance (2 Windings)


Purpose Magnetic coupling between two lossy windings


Description This component implements a magnetic coupling between two separate wind-ings. For both windings the self inductance and resistance are specified in-dividually. The mutual inductance and resistance are modeled as linear ele-ments.


1:1

i2i1

Rm

Lm

L1−Lm R1−Rm L2−Lm R2−Rm

In the symbol of the mutual inductance, the positive terminal of the primarywinding is marked with a little circle. The positive terminal of the secondarywinding is marked with a dot.

Parameters Self inductanceA two-element vector containing the self inductance for the primary wind-ing L1 and the secondary winding L2. The inductivity is given in henries(H).

Winding resistanceA two-element vector containing the self resistance of the primary windingR1 and the secondary winding R2, in ohms (Ω).

Mutual inductanceThe mutual inductance Lm, in henries (H).

Mutual resistanceThe mutual resistance Rm, in ohms (Ω).

Initial currentA two-element vector containing the initial currents on the primary sidei1 and the secondary side i2, in amperes (A). The direction of the initial

549


current inside the component is from the positive to the negative terminal.The default value is [0 0].



550



Purpose Magnetic coupling between three lossy windings


Description This component implements a magnetic coupling between three separatewindings. For all windings the self inductance and resistance are specified in-dividually. The mutual inductance and resistance are modeled as linear ele-ments.


R3−Rm

i1

Rm

Lm

L1−Lm R1−Rm

1:1 :1

i3L3−Lm

i2L2−Lm R2−Rm

In the symbol of the mutual inductance, the positive terminal of the primarywinding is marked with a little circle. The positive terminals of the secondaryand tertiary windings are marked with dots.

Parameters Self inductanceA three-element vector containing the self inductance for the primarywinding L1, the secondary winding L2 and the tertiary winding L3. Theinductivity is given in henries (H).

Winding resistanceA three-element vector containing the self resistance of the primary wind-ing R1, the secondary winding R2 and the tertiary winding R3, in ohms(Ω).

Mutual inductanceThe mutual inductance Lm, in henries (H).

Mutual resistanceThe mutual resistance Rm, in ohms (Ω).

551


Initial currentA three-element vector containing the initial currents on the primary sidei1, the secondary side i2 and the tertiary side i3, in amperes (A). The direc-tion of the initial current inside the component is from the positive to thenegative terminal. The default value is [0 0 0].



552

Non-Excited Synchronous Machine


Purpose Non-excited synchronous machine configurable with lookup tables


Description This three-phase synchronous machine has a solid rotor with optional per-manent magnets. Magnetization, saliency, saturation and cross-coupling aremodeled by means of corresponding flux linkage and incremental inductancelookup tables.

The machine can operate as either a motor or generator. If the mechanicaltorque has the same sign as the rotational speed, the machine is operating inmotor mode; otherwise it is in generator mode. In the component icon, phase ais marked with a dot.

In order to inspect the implementation, please select the component in yourcircuit and choose Look under mask from the Subsystem submenu of theEdit menu. If you want to make changes, you must first choose Break li-brary link both from the same menu.

Electrical System

The model is realized by means of the Voltage Behind Reactance (VBR) for-mulation and is therefore appropriate to simulate switching dead-time andfailure modes.

Electrical equation expressed in synchronous frame by means of space-vectornotation:

−→vs = Rs ·−→is + (Lσs + Lmi) · (

d−→isdt

+ j · ω · −→is ) +−→es

−→es = j · ω · −→ϕm − Lmi · j · ω ·−→is

with

−→x =

xd

xq

where j · −→x rotates the synchronous frame vector, −→x , clockwise by 90.

These equations are transformed back into the stationary frame to control theVBR network. The zero-sequence impedance of the machine is set to Lss.

553




Te =3

2p (ϕd iq − ϕq id)

Mechanical System


ωm =1


θm = ωm

ParametersGeneral

Stator resistanceArmature or stator resistance Rs in Ω.

Stator leakage inductanceLeakage inductance of stator windings in henries (H). Stator leakage mustbe set to a non-zero value.


Initial stator currentsA two-element vector containing the initial stator currents ia,0 and ib,0 ofphase a and b in amperes (A). ic,0 is calculated assuming a neutral connec-tion.

Magnetizing Inductance

Id lookup vectord-axis current vector serving as input values to flux linkage and incremen-tal inductance lookup tables. Must be a vector with 2 or more elements,and monotonically increasing, i.e. [0 ... id,max]. The values are in amperes(A).

Iq lookup vectorq-axis current vector serving as input values to flux linkage and incremen-tal inductance lookup tables. Must be a vector with 2 or more elements,

554


and monotonically increasing, i.e. [0 ... iq,max]. The values are in amperes(A).

Psid (Id, Iq) lookup tabled-axis flux linkage lookup table (2D). The number of rows and columnsmust match the size of the d- and q-axis currents, respectively. The valuesare in Volt-seconds (Vs).

Psiq (Id, Iq) lookup tableq-axis flux linkage lookup table (2D). The number of rows and columnsmust match the size of the d- and q-axis currents, respectively. The valuesare in Volt-seconds (Vs).

Lmidd (Id, Iq) lookup tabled-axis self incremental inductance lookup table (2D). The number of rowsand columns must match the size of the d- and q-axis currents, respec-tively. If Lmi data is not specified, or set to [], the incremental inductanceis calculated from the flux linkage data. The values are in henries (H).

Lmiqq (Id, Iq) lookup tableq-axis self incremental inductance lookup table (2D). The number of rowsand columns must match the size of the d- and q-axis currents, respec-tively. If Lmi data is not specified, or set to [], the incremental inductanceis calculated from the flux linkage data. The values are in henries (H).

Lmidq (Id, Iq) lookup tableMutual incremental inductance lookup table (2D). The number of rows andcolumns must match the size of the d- and q-axis currents, respectively. IfLmi data is not specified, or set to [], the incremental inductance is calcu-lated from the flux linkage data. The values are in henries (H).

Generated table size [d, q]User-specified dimension to generate derived current vectors and corre-sponding flux linkage and incremental inductance lookup tables.

If left empty, the supplied data is used as-is. If specified, the dimensions ofthe rows and columns must be 2 or more.

Specifying a scalar value, n, will generate equally spaced, n-element d-and q-axis current vectors. The corresponding 2D lookup tables for fluxlinkage and incremental inductance are also generated.

Specifying a vector, [m,n], will generate equally spaced d- and q-axis cur-rent vectors. The d-axis current vector will have m elements and the q-axis current vector will have n elements. The corresponding 2D lookup ta-bles for flux linkage and incremental inductance are also generated.

555


The size of the generated tables affect the model initialization and simu-lation speeds. A smaller size leads to faster model initialization and sim-ulation speeds, but lower resolution in the generated tables. A larger sizeincreases the resolution but adversely affects the model initialization andsimulation speeds. Care must be taken when configuring this parameter.

Current out of rangeConfigure to ignore, warn, warn and pause simulation, or generate errorand stop simulation if the d-axis or q-axis currents are outside the speci-fied range.

Mechanical



Initial rotor speedInitial mechanical rotor speed ωm,0 in radians per second (s−1).



Stator flux (dq)The stator flux linkages ϕd and ϕq in the rotating reference frame.




References H. Bühler, “Réglage de systèmes d’électronique de puissance, vol 1: Théorie”,Presses Polytechniques et universitaires romandes, Lausanne, 1997.

H. Bühler, “Réglage de systèmes d’électronique de puissance, vol 2: Entraîne-ments réglés”, Presses Polytechniques et universitaires romandes, Lau-sanne, 1997.

556

Offset

Offset

Purpose Add constant offset to input signal


Description The Offset block adds a constant to the input signal.

Parameter OffsetThe offset to add to the input signal. This value may be negative to sub-tract an offset from the signal.




557


Op-Amp

Purpose Ideal operational amplifier with finite gain

Library Electrical / Electronics

Description

+

-

This Op-Amp amplifies a voltage between the non-inverting “+” and inverting“–” input with a specified gain. The resulting voltage is applied between theoutput and ground terminal. Output and ground are electrically isolated fromthe inputs. If you want to build a linear amplifier the output voltage mustsomehow be fed back to the inverting input. The demo models plOpAmps andplActiveLowPass demonstrate different applications with op-amps.

Parameter Open-loop gainThe voltage gain of the Op-Amp. The default is 1e6.

558

Op-Amp with Limited Output

Op-Amp with Limited Output

Purpose Ideal operational amplifier with limited output voltage

Library Electrical / Electronics

Description

+

-

This component amplifies a voltage between the non-inverting “+” and invert-ing “–” input with a specified gain, taking into account the specified outputvoltage limits. The resulting voltage is applied between the output and groundterminal. Output and ground are electrically isolated from the inputs. If youwant to build a linear amplifier the output voltage must somehow be fed backto the inverting input. The demo model plOpAmps shows a possible applicationof the Limited Op-Amp.

Parameters Open-loop gainThe voltage gain of the amplifier if operating in linear mode. The defaultis 1e6.

Output voltage limitsA two-element vector containing the minimum and maximum output volt-age Vmin and Vmax in volts (V). The default is [−10 10].

559


Pause / Stop

Purpose Pauses or stops the simulation when the input becomes non-zero

Library System

Description This block pauses or stops the simulation when the input signal changes fromzero to a non-zero value.

Note In PLECS Standalone, pause blocks are ignored during analyses andsimulation scripts.

Parameter ActionUse pause or stop to specify whether the block should pause or stop thesimulation. To disable the block, use ignore.

560

Peak Current Controller

Peak Current Controller

Purpose Implement peak current mode control


Description This block implements current mode control in a switching converter. At thebeginning of each switching cycle, the output is set. When the Isense input ex-ceeds the Iref input, the output is reset.

Parameters Switching frequencyThe switching frequency of the output signal.

Minimum duty cycleThis sets the minimum time the output remains on for at the beginning ofeach switching period. This value must be non-negative and less than themaximum duty cycle.

Maximum duty cycleThis defines the maximum permissible duty cycle of the switch output. IfIsense < Iref , the output will turn off if the duty cycle exceeds this maxi-mum value. The maximum duty cycle must be less than 100 %.

Slope compensationSlope compensation can be applied to ensure stability when the outputduty cycle exceeds 50 %. Entering a parameter, Islope, reduces Iref duringeach switching cycle as follows: I ′ref = Iref − Islope · t/Ts, where t is thetime elapsed from the start of the switching cycle and Ts is the switchingperiod. Slope compensation can be omitted by setting Islope to 0.

561


Periodic Average

Purpose Periodically average input signal over specified time


Description This block periodically averages a continuous input signal u over the specifiedaveraging time T . The output y is updated at the end of each averaging pe-riod. Mathematically, this block corresponds to a moving average filter wherethe output is processed by a zero-order hold:

y(t) =1

T

ˆ t

t−Tu(τ) dτ · rect

(t− n+ 1/2

T

)However, the implementation of Periodic Average filter is computationally lessexpensive and more accurate than the continuous Moving Average (see page545) filter.

The block is suited to determine average conduction losses of power semicon-ductors. To determine average switching losses, use the Periodic Impulse Aver-age (see page 563).

Parameter Averaging timeThe length of the averaging period (in sec.) and the sample time of theoutput signal. See also the Discrete-Periodic sample time type in section“Sample Times” (on page 38).



562

Periodic Impulse Average

Periodic Impulse Average

Purpose Periodically average Dirac impulses over specified time


Description This block periodically averages an input signal u consisting of a series ofDirac impulses δ. The output y is updated at the end of each averaging periodT . Mathematically, this block corresponds to a moving average filter where theoutput is processed by a zero-order hold:

y(t) =1

T

ˆ t

t−Tu(τ) dτ · rect

(t− n+ 1/2

T

)The block is suited to determine average switching losses of power semicon-ductors. To determine average conduction losses, use the Periodic Average (seepage 562).

Parameter Averaging timeThe length of the averaging period (in sec.) and the sample time of theoutput signal. See also the Discrete-Periodic sample time type in section“Sample Times” (on page 38).



563


Permanent Magnet Synchronous Machine

Purpose Synchronous machine excited by permanent magnets


Description This three-phase permanent magnet synchronous machine has a sinusoidalback EMF.

The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motor mode,otherwise in generator mode. All electrical variables and parameters areviewed from the stator side. In the component icon, phase a is marked witha dot.

Electrical System

Ld

Rsp∙ωm∙ φqid

vd

+

−

d-axis

Lq

Rsp∙ωm∙ φd

vq

+

−

iq

q-axis

Stator flux linkages:

ϕq = Lq iq

ϕd = Ld id + ϕ′m

564


The machine model offers two different implementations of the electrical sys-tem: a traditional rotor reference frame and a voltage-behind-reactance formu-lation.

Rotor Reference Frame Using Park’s transformation, the 3-phase circuitequations in physical variables are transformed to the dq rotor referenceframe. This results in constant coefficients in the differential equations mak-ing the model numerically efficient. However, interfacing the dq model withthe external 3-phase network may be difficult. Since the coordinate transfor-mations are based on voltage-controlled current sources, inductors and nat-urally commutated devices such as diode rectifiers may not be directly con-nected to the stator terminals.

Voltage behind Reactance This formulation allows for direct interfacingof arbitrary external networks with the 3-phase stator terminals. The elec-trical system is described in circuit form. Due to the resulting time-varyinginductance matrices, this implementation is numerically less efficient than thetraditional rotor reference frame.



Te =3


Mechanical System


ωm =1


θm = ωm

Parameters ModelImplementation in the rotor reference frame or as a voltage behind reac-tance.


565


Stator inductanceA two-element vector containing the combined stator leakage and magne-tizing inductance. Ld is referred to the d-axis and Lq to the q-axis of therotor. The values are in henries (H).

Flux induced by magnetsConstant flux linkage ϕ′m in Vs induced by the magnets in the stator wind-ings.








Stator flux (dq)The stator flux linkages ϕd and ϕq in the rotating reference frame in Vs:

ϕq = Lq iq

ϕd = Ld id + ϕ′m




566


See also If the stator inductance is independent of the rotor angle, i.e. Ld = Lq, it iscomputational more efficient to use the simplified Brushless DC Machine (seepage 351) with a sinusoidal back EMF. The parameters need to be convertedas follows:

L−M = Ld = Lq

KE = −ϕ′m · p

For back EMF shapes other than sinusoidal, and/or if the stator inductancehas a complex angle dependency please use the sophisticated model of theBrushless DC Machine (see page 348). The sophisticated BLDC machine canbe configured as a PMSM with sinusoidal back EMF if the parameters areconverted as follows:

Kc,n = [0]

Ks,n = [−ϕ′m · p]

L0−M =Ld + Lq

2

Lc,n = [0 Ld−Lq]

Ls,n = [0 0]

567


Phase-Shifted Full-Bridge Converter

Purpose Phase-Shifted Full-Bridge converter module


Description

1

1

1

1

1

1

1

1 n:1 1

L

Lf

Switched All power semiconductors inside the module are modeled withideal switches. The individual IGBTs are controlled with logical gate signals.An IGBT is on if the corresponding gate signal is not zero. For compatibilitywith the sub-steps event configuration it is recommended to use the value 1for non-zero gate signals.



Since the inductors current are simulated accurately, even with relativelylarge time steps, the sub-steps configuration is particularly well suited forreal-time simulations with high switching frequencies. However, it is not rec-ommended to use discretisation step sizes (sample time parameter) largerthan one fifth of the switching period.

This type of implementation is an extension of the classical “sub-cycle aver-age" implementation, used in the PLECS power modules, which yields moreaccurate simulation results than a purely switched configuration. The accu-racy improvement is obtained by performing sub-step calculations within onesimulation step, which results in the calculation of as many inductor current

568

Phase-Shifted Full-Bridge Converter

values as switching combinations encountered during one simulation step.This approach allows for a more accurate calculation of the average induc-tor current. Nevertheless, if the the output capacitor voltage changes rapidlybetween two simulation steps, the accuracy of the calculations given by thepower module will degrade. Therefore, in order to maintain high accuracy inthe simulated results, the usage of low values of output filter capacitance isnot recommended.








Filter inductanceA non-zero scalar specifying the output filter inductance of the, in henries(H).


569



570

Pi-Section Line

Pi-Section Line

Purpose Single-phase pi-section transmission line


Description The Pi-Section Line implements a single-phase transmission line with param-eters lumped in pi sections.

A transmission line is characterized by a uniform distribution of inductance,resistance, capacitance and conductance along the line. However, in manycases these distributed parameters can be approximated by cascading multiplepi sections with discrete components. The figure below illustrates the electri-cal circuit used for the line model.

R

C

2

G

2C

C

2GGC

G

2

L R L R L

Let l be the length of the line and n the number of pi sections representingthe line. The inductance L, the resistance R, the capacitance C and the con-ductance G of the discrete elements can then be calculated from their per-unit-length counterparts L′, R′, C ′ and G′ using the following equations:

L =l

nL′, R =

l

nR′, C =

l

nC ′, G =

l

nG′

Parameters Inductance per unit lengthThe series line inductance L′ per unit length. If the length l is specified inmeters (m) the unit of L′ is henries per meter (H/m).

Resistance per unit lengthThe series line resistance R′ per unit length. If the length l is specified inmeters (m) the unit of R′ is ohms per meter (Ω/m).

Capacitance per unit lengthThe capacitance C ′ between the line conductors per unit length. If thelength l is specified in meters (m) the unit of C ′ is farads per meter (F/m).

571


Conductance per unit lengthThe conductance G′ between the line conductors per unit length. If thelength l is specified in meters (m) the unit of G′ is siemens per meter(S/m).

LengthThe length l of the line. The unit of l must match the units L′, R′, C ′ andG′ are based on.

Number of pi sectionsNumber of sections used to model the transmission line. The default is 3.

Initial voltageA scalar value specifying the initial voltage of all capacitors at simulationstart, in volts (V).

572

Piece-wise Linear Resistor

Piece-wise Linear Resistor

Purpose Resistance defined by voltage-current pairs


Description This component models a piece-wise linear resistor. The resistance character-istic is defined by a set of voltage-current values.

u

i

U1

U3

U4

I1

I3

I4

The operating mode of the piece-wise linear resistor is illustrated in the di-agram below. The voltage across the device dictates which internal switch isclosed. The values 0 V / 0 A must always be defined in the set of voltage / cur-rent values to ensure the current is zero at zero voltage.

573


Note In order to model a saturation characteristic with n segments, this com-ponent requires n ideal switches. It is therefore advisable to keep the number ofsegments low in order to maintain a high simulation speed.

Parameters Voltage valuesA vector of voltage values U in volts (V) that defines the piece-wise linearcharacteristic. The voltage values must be strictly monotonic increasing.At least two values are required. The value 0 must be present, the corre-sponding current value must also be 0.

Current valuesA vector of current values I in amperes (A) that defines the piece-wise lin-ear characteristic. The current values must be strictly monotonic increas-ing. The number of current values must match the number of voltage val-ues. The value 0 must be present, the corresponding voltage value mustalso be 0.

Probe Signals Resistor voltage dropThe voltage measured across the component, in volts (V). The positive ter-minal of the resistor is marked with a small black dot.

Resistor currentThe current flowing through the component, in amperes (A).

Resistor powerThe power consumed by the resistor, in watts (W).

574

Planetary Gear Set

Planetary Gear Set

Purpose Ideal planetary gear set


Description This component models a planetary gear set with a sun gear, planet gears con-nected via a carrier, and a ring gear. The component is divided into two sub-components: a ring-planet gear subsystem and a sun-planet gear subsystem,as shown in the figure below.

The planetary gear set has three external shafts: ring gear shaft (R), sun gearshaft (S), and carrier shaft (C). The relation between the angular speeds of thegears and carrier are described by the following equations:

Nsωs + Npωp − (Ns + Np)ωc = 0

Nrωr −Npωp − (Nr −Np)ωc = 0

where Nr, Ns, and Np correspond to the number of teeth on the ring, sun, andeach planet gear respectively, and ωr, ωs, ωp, and ωc correspond to the angularspeed of the ring gear, sun gear, planet gears, and carrier respectively.

These equations can further be simplified to

Nsωs + Nrωr = (Ns + Nr)ωc

The model includes an internal lumped moment of inertia representing theplanet gears (which is set to zero by default). The moments of inertia of the

575


ring and sun gears and the carrier can be modeled by connecting an Inertia(see page 506) to the corresponding shaft.

ParametersMain

Number of sun teethNumber of teeth on the sun gear.

Number of planet teethNumber of teeth on each planet gear.

Number of ring teethNumber of teeth on the ring gear.

Planet gear

Moment of inertia of planet gearCombined planet gear inertia J in Nms2.

Initial speed of planet gearInitial angular speed of each planet gear (ωp) in rad

s .

Probe Signals Sun gear speedAngular speed of sun gear (ωs) in rad

s .

Planet gear speedAngular speed of each planet gear (ωp) in rad

s .

CarrierAngular speed of carrier (ωc) in rad

s .

Ring gear speedAngular speed of ring gear (ωr) in rad

s .

576

Polar to Rectangular

Polar to Rectangular

Purpose Convert polar coordinates to Cartesian coordinates

Library Control / Transformations

Description This block transforms a signal representing polar coordinates [r, θ] into rectan-gular coordinates [x, y]:

x = r ∗ cos(θ)

y = r ∗ sin(θ)where θ is in radians.

577


PLL (Single-Phase)

Purpose Implementation of a single phase PLL


Description This block implements two different types of a single-phase Phase LockedLoop (PLL). The single-phase PLL component provides at its output terminalsan estimation of the input signal frequency, signal amplitude and the phase-angle.

PLL Types

Three fundamental blocks can be identified in a basic single-phase PLL struc-ture.

• Phase detector: Generates an output signal that is proportional to thephase difference between the input signal and the signal generated by thePLL itself.

• Controller: Usually a PI controller to attenuate high-frequency componentsand to eliminate the steady-state phase-error.

• Frequency/phase-angle generator: Generates a phase-angle signal based onthe estimated angular frequency. Typically, this block is constituted by awrapping integrator.

** e uPI(s) ++

w0

wrappingintegrator

thetaw cosv v'

Phasedetector Controller Frequency/phase-angledetector

Basic structure of a single-phase PLL

Two different types of a single-phase PLL are implemented. The main dif-ference between the two methods is how the phase detector works. Pleasenote that both PLL implementations use an amplitude normalization scheme.Therefore, information about the nominal input signal amplitude is notneeded.

578

PLL (Single-Phase)

Enhanced PLL

The performance of the basic PLL implementation is enhanced by filtering theinput signal with an adaptive notch filter (ANF). When the input signal hasthe same phase-angle and frequency as the estimation of the PLL itself, theoutput of the ANF becomes zero. Due to this, oscillations at the output of thephase detector are canceled out and the signal phase-angle is accurately esti-mated by the basic PLL structure.

v v'+−

-cos(theta')

**k

ANFgain

1/s**

Enhanced structure with adaptive notch filter

SOGI

VVab

+− k +− ** 1/s

**1/s

omega

General structure of the SOGI adaptive filter

This implementation uses an ortogonal signal generator based on second ordergeneralized integrator (SOGI). Based on the input signal, two sine waves witha phase shift of 90 are generated. The first of the two components has thesame phase and magnitude as the fundamental of the input signal. From thestructure given in above figure the following relevant transfer functions of thestructure can be derived:

Vα(s)

V (s)=

kω′s

s2 + kω′s+ ω′2

Vβ(s)

V (s)=

kω′2

s2 + kω′s+ ω′2

579


To avoid problems due to input signal frequency fluctuations the resonancefrequency ω′ is provided by the estimated frequency of the PLL structure. Thefiltering effort can be adjusted with the filter gain k. If k decreases, the band-pass filter will become narrower resulting in heavier filtering, but resulting ina slower system response. Especially when working under distorted grid con-ditions reducing the filter gain k may be beneficial.

Parameters

Basic

PLL typeSpecifies the PLL type. The single-phase PLL can be of type Enhanced PLLor SOGI. For further explanations on the different PLL implementationssee PLL types above.

Nominal frequencyThe nominal frequency of the fundamental component in hertz orrad/second, see below.

Nominal input voltageThe estimated nominal peak voltage of the input signal. This value isneeded to correctly initialize all states in the PLL structure. If this infor-mation is not known, this parameter can be set to zero.

Initial phase-angleThe initial phase-angle of the input signal in rad, per unit (p.u.) or de-grees, see below. The parameter value should be in the range [0 2π], [0 1]or [0 360] respectively.

Sin/Cos outputActivates an additional signal output terminal (on) with an unitary signalsynchronous with the input signal. In addition also a 90 degree delayedsignal is provided. If the parameter is set to off the signal terminal is hid-den.

Units for frequency and phaseThe frequency and phase can be expressed in terms of (rad/sec, rad),(Hz, p.u.) or (Hz, degrees). If the phase is expressed in per unit (p.u.),a value of 1 is equivalent to the period length of the nominal frequency.This parameter also changes the unit of the frequency output of the PLLcomponent.

580

PLL (Single-Phase)

Controller design

Controller designSpecifies the controller design approach. If the parameter is set to Basicthe PI controller gains are automatically set to have a settling time of ap-proximately 0.06 seconds. By using the Advanced approach, the user canspecify the controller gains Kp and Ki and the filter gain k freely. Pleasenote, that it is not required to scale the controller gains by the rated inputsignal amplitude since the input signal is normalized.

Proportional gain KpThe proportional gain of the PI controller. This parameter is shown only ifthe Controller design parameter is set to Advanced.

Integral gain KiThe integral gain of the PI controller. This parameter is shown only if theController design parameter is set to Advanced.

ANF gain kChanges the filter bandwidth of the adaptive notch filter in the enhancedPLL structure. This parameter is shown only if the Controller designparameter is set to Advanced and the PLL type parameter to EnhancedPLL.

SOGI filter gain kChanges the filter bandwidth of the SOGI structure. Reducing k leadsto a narrower bandpass-filter. This parameter is shown only if the Con-troller design parameter is set to Advanced and the PLL type parameterto SOGI.

Probe Signals ThetaThe estimated phase-angle of the input signal.

AmplitudeThe estimated amplitude of the input signal.

FrequencyThe estimated frequency of the input signal.

Sin/CosA unitary fundamental signal running synchronous with the input signaland a 90 degree delayed signal of it.

Input SignalThe input signal of the PLL block.

References581


R. Teodorescu, et. al., “Grid Converters for Photovoltaic and Wind Power Sys-tems”, John Wiley & Sons Ltd., 2011.

582

PLL (Three-Phase)

PLL (Three-Phase)

Purpose Implementation of a three-phase PLL


Description This block implements two different types of a three-phase Phase Locked Loop(PLL). The PLL block provides an estimation of the phase-angle, amplitudeand frequency of the three-phase input signal.

PLL Types

General PLL Structure

The general PLL structure shown of a three-phase PLL can be divided intothree basic blocks:

• Phase detector: Generates an output signal that is proportional to thephase difference between the input signal and the signal generated by thePLL itself.

• Controller: Usually a PI controller to attenuate high-frequency componentsand to eliminate the steady-state phase-error.

• Frequency/phase-angle generator: Generates a phase-angle signal based onthe estimated angular frequency. Typically, this block is constituted by awrapping integrator.

Vabctheta

Phasedetector

wrappingintegrator

phiw++

w0

ContinuousPIDController

e uPI(s)

General PLL block diagram

The main difference between the two offered three-phase PLLs lies in thephase detector part.

583


SRF-PLL

A basic synchronization technique in three-phase applications is the syn-chronously rotating reference frame PLL (SRF-PLL). The three-phase volt-age vector in the natural reference frame is transformed in the rotating refer-ence frame by using the Park transformation. The instantaneous phase angleis controlled by a feedback loop that regulates the q component to zero. Un-der steady-state operation, i.e. when the q component is zero, the d compo-nent depicts the amplitude of the input voltage vector. This simple approachworks fine if the grid voltage is not affected by harmonics or unbalances. Toavoid the impact of voltage harmonics on the accuracy of the estimated phase-angle and frequency, the controller bandwidth has to be set as high as possi-ble. However, under unbalanced grid conditions, a double-frequency ripple ofthe input signal frequency is visible on the output signals of the PLL if thecontrol-loop bandwidth is set to high. Therefore, a trade-off between those twocontrol goals has to be made.

Vabc

theta'

Vdq3ph->SRF

abcαβ

SRF->RRF

αβdq

Phase detector of the SRF-PLL

DSRF-PLL

The decoupled double synchronous reference frame PLL uses two synchronousreference frames, rotating with positive and negative synchronous speeds, re-spectively. This allows the decoupling of the effect of the negative sequencecomponent on the dq-signals. This is of high interest when synchronizing tonon-ideal grids, i.e unbalanced voltage conditions. Since the double-frequencyripple caused by the unbalanced grid condition is avoided, a higher controlbandwidth compared to the SRF-PLL can be set. The transfer function of thelow-pass filter in above scheme can be written as:

Vout(s)

Vin(s)=

kω0

s+ kω0

By decreasing the filter gain k, the bandwidth of the LPF can be reduced ac-cordingly.

Parameters584

PLL (Three-Phase)

Vabc theta'

Vdq

3ph->SRF

abcαβ

Tdq+1αβ

dq

Decouplingnetwork+1

dq'dq

dqf

Tdq-1

αβdq

Decouplingnetwork-1

dq'dq

dqf

LPF1

LPF2

Phase detector of the DSRF-PLL

Basic

PLL typeSpecifies the PLL type. The three-phase PLL can be of type SRF-PLL orDSRF-PLL. For further explanations on the different PLL implementationssee PLL types above.

Nominal frequencyThe nominal frequency of the fundamental component in hertz orrad/second, see below.

Nominal input voltageThe estimated nominal peak voltage of the input signal. This value isneeded to correctly initialize all states in the PLL structure. If this infor-mation is not known, this parameter can be set to zero.

Initial phase-angleThe initial phase-angle of the input signal in rad, per unit (p.u.) or de-grees, see below. The parameter value should be in the range [0 2π], [0 1]or [0 360] respectively.

Units for frequency and phaseThe frequency and phase can be expressed in terms of (rad/sec, rad),(Hz, p.u.) or (Hz, degrees). If the phase is expressed in per unit (p.u.),a value of 1 is equivalent to the period length of the nominal frequency.This parameter also changes the unit of the frequency output of the PLLcomponent.

585


Controller design

Controller designSpecifies the controller design approach. If the parameter is set to Basicthe PI controller gains are automatically set. If the PLL type parame-ter is set to SRF-PLL the PLL is designed to have a controller crossoverfrequency of half the nominal frequency defined in the parameter Nomi-nal frequency and a phase margin of at least 60. Otherwise, if the PLLtype parameter is set to DSRF-PLL the PLL is designed to have a controllercrossover frequency equal to the nominal frequency defined in the parame-ter Nominal frequency and a phase margin of at least 60. By using theAdvanced approach, the user can specify the controller Kp and Ki and thefilter gain k freely. Please note, the controller gains have not to be scaledby the rated input signal amplitude since the both schemes use an ampli-tude normalization scheme.

Proportional gain KpThe proportional gain of the PI controller. This parameter is shown only ifthe Controller design parameter is set to Advanced.

Integral gain KiThe integral gain of the PI controller. This parameter is shown only if theController design parameter is set to Advanced.

Filter coefficient kThe filter gain of the PI controller. This parameter is shown only if theController design parameter is set to Advanced and the PLL type pa-rameter is set to DSRF-PLL.

Probe Signals ThetaThe estimated phase-angle of the input signal.

AmplitudeThe estimated amplitude of the input signal.

FrequencyThe estimated frequency of the input signal.

Input SignalThe input signal of the three-phase PLL block.

ReferencesR. Teodorescu, et. al., “Grid Converters for Photovoltaic and Wind Power Sys-

tems”, John Wiley & Sons Ltd., 2011.

586

Position Sensor

Position Sensor

Purpose Output measured absolute or relative position as signal


Description The Position Sensor measures the relative position of the flange marked witha dot with respect to the other flange. If the other flange is connected to thereference frame, the absolute position is measured.

Note Speed and position sensors are ideally compliant. Hence, if multiplespeed or position sensors are connected in series the speed or position measuredby an individual sensor is undefined. This produces a run-time error.


Initial positionThe position at simulation start.

Probe Signal PositionThe measured position.

587


Product

Purpose Multiply and divide scalar or vectorized input signals


Description The Product block multiplies or divides input signals. If the division operator/ is used, the reciprocal of the input signal is used for multiplication.

In case of a single input, all elements of the input vector are multiplied. Vec-torized input signals of the same width are multiplied element wise and resultin a vectorized output signal. If vectorized and scalar input signals are mixed,the scalar input signals are expanded to the width of the vectorized input sig-nals.

Parameter List of operators or number of inputsThe inputs can be specified either with• a string containing * or / for each input and | for spacers, or• a positive integer declaring the number of inputs to be multiplied.




588

Pulse Delay

Pulse Delay

Purpose Delay discrete-value input signal by fixed time


Description The Pulse Delay applies a fixed time delay to an input signal that changesat discrete instants and is otherwise constant. The signal can be a scalar orvector.

Whenever a change of an input signal is detected at a simulation time t, thePulse Delay records the new signal value in an internal buffer and schedulesan event that forces the solver to make a step exactly at the simulation timet+ TD in order to output the delayed input value.

A typical application of the Pulse Delay is to delay the pulses of a modulator.

Note

• The Pulse Delay should not be used to delay continuous signals as this willlead to excessive memory consumption. Besides, the output of the Pulse De-lay is always piece-wise constant. To delay continuously changing signals,use the continuous Transport Delay (see page 748).

• The Pulse Delay should also not be used to delay signals that have a fixedsample time. To delay such signals, use a Zero Order Hold (see page 787) ora Delay (see page 387) depending on the duration of the delay with respect tothe sample time of the input signal.Suppose that the input signal has a sample time Ts and you want to delay itby a time TD. Calculate the delay order O = bTD

Tsc (i.e. the integer part of the

division) and an offset time To = mod(TD, Ts). If O is zero, use a Zero OrderHold with the sample time [Ts, To]. If O is greater than zero, use a Delay withthe sample time [Ts, To] and the delay order O. For more information regard-ing sample times, see “Sample Times” (on page 38).

Parameters Time delay Td

Time by which the input signal is delayed.

Initial outputOutput value after simulation start before the input values appear at theoutput.

589


Pulse Generator

Purpose Generate periodic rectangular pulses


Description The Pulse Generator outputs a signal that periodically switches between ahigh- and low-state.

Parameters High-state outputThe value of the output signal in the high-state.

Low-state outputThe value of the output signal in the low-state.

FrequencyThe frequency of the output signal in hertz (Hz).

Duty cycleThe fraction of the period length during which the output signal is in thehigh-state. The duty cycle value must be in the range [0 1]. For example,a value of 0.1 means that the signal is in the high-state for the first 10%of the period time.

Phase delayThe phase delay in seconds (s). If the phase delay is 0 the period begins atthe start of the high state.


Probe Signal OutputThe output signal of the pulse generator.

590

Quantizer

Quantizer

Purpose Apply uniform quantization to input signal


Description The Quantizer maps the input signal to an integer multiple of the quantiza-tion interval:

y = q ∗ round

(u

q

)

Parameters Quantization intervalThe quantum q used in the mapping function.

Step detectionWhen set to on, the Quantizer produces a zero-crossing signal that en-ables the solver to detect the precise instants, at which the output needsto change. This may be necessary when quantizing a continuous signal.

When set to off, the Quantizer will not influence the step size of thesolver.



591


Rack and Pinion

Purpose Ideal conversion between translational and rotational motion

Libraries Mechanical / Translational / ComponentsMechanical / Rotational / Components

Description The Rack and Pinion models an ideal converter between translational and ro-tational motion. The relation between the torque, force and speeds of the twoflanges is described with the following equations:

v = R · ωτ = R · F

where R is the pinion radius.

Parameter Pinion radiusThe pinion radius R. A negative value will cause the flanges to move inopposite directions.

592

Ramp

Ramp

Purpose Generate constantly rising or falling signal


Description The Ramp block generates a signal that increases or decreases linearly overtime once the start time is reached. The output can be limited to a final value.

Parameters SlopeThe slope of the signal (per second).

Start timeThe time at which the ramp starts.

Initial outputThe output value before the start time is reached.

Final outputThe final value for the output signal. If the parameter is set to inf theoutput signal is unlimited.

Probe Signal OutputThe output signal of the pulse generator.

593


Random Numbers

Purpose Generate uniformly distributed random numbers


Description The Random Numbers block generates uniformly distributed random num-bers. The boundaries of the generated values can be configured in the compo-nent dialog. The figure below illustrates the distribution for two different setsof parameters. The seed of the generator initializes the algorithm at the sim-

x

\ (x)

ï4 ï2 0 2 4

0.1

0.2

0.3

0.4 [min, max] = [+/ï 1.5]

[min, max] = [+/ï 4.0]

ulation start. For the same seed, the sequence of random numbers is repro-duced in every simulation run. If this behavior is undesired the system timecan be used as a seed. To minimize correlation effects, it is recommended touse different seeds if multiple random generators are used in one model.

Parameters MinimumThe lower boundary of the random numbers.

MaximumThe upper boundary of the random numbers.

SeedThe seed used to initialize the Random Numbers generator.

Sample TimeThe sampling period used for generating random output values.

Reference Mersenne Twister: http://en.wikipedia.org/wiki/Mersenne_twister

594

http://en.wikipedia.org/wiki/Mersenne_twister

Rate Limiter

Rate Limiter

Purpose Limit rising and falling rate of change


Description The Rate Limiter restricts the first derivative of the signal passing through it.While the rate of change is within the specified limits, the output follows theinput. When the rate of change exceeds the rising or falling limit, the outputfalls behind the input with a fixed slope until output and input become equalagain.

Parameters Rising rate limitThe maximum rate of change of the output signal (typically positive).

Falling rate limitThe minimum rate of change of the output signal (typically negative).

Sample time modeThis parameter lets you choose whether the block operates with a contin-uous sample time, or whether the sample time is inherited from the input.For backward compatibility, the default for models created with PLECS 4.3or older is inherited. Otherwise, the default is continuous.



595


Rectangular to Polar

Purpose Convert Cartesian coordinates to polar coordinates


Description This block transforms a signal representing rectangular coordinates [x, y] intopolar coordinates [r, θ]:

r =√x2 + y2

θ = atan2(x, y)

θ is calculated in the range −π ≤ θ ≤ π.

596

Relational Operator

Relational Operator

Purpose Compare two input signals


Description The Relational Operator compares two input signals. If the comparison is trueit outputs 1, otherwise 0. The first input is marked with a dot.

Parameter Relational operatorChooses which comparison operation is applied to the input signals. Avail-able operators are• equal (==),• unequal (∼=),• less (<),• less or equal (<=),• greater or equal (>=),• greater (>).



597


Relay

Purpose Toggle between on- and off-state with configurable threshold


Description The output of the Relay block depends on its internal state. If the input sig-nal exceeds the upper threshold, the relay will be in the on-state. It will be inthe off-state if the inputs is less than the lower threshold. The relay does notchange for input values between the thresholds.

Parameters Upper thresholdThe highest value that the input signal may reach before the statechanges to the on-state.

Lower thresholdThe lowest value that the input signal may reach before the state changesto the off-state.

On-state outputThe value of the output signal while the relay is in the on-state.

Off-state outputThe value of the output signal while the relay is in the off-state.

Initial stateThe state of the relay at simulation start. Possible values are on and off.




598

Resistor

Resistor

Purpose Ideal resistor


Description This component provides an ideal resistor between its two electrical termi-nals. See section “Configuring PLECS” (on page 45) for information on how tochange the graphical representation of resistors.

Parameter ResistanceThe resistance in ohms (Ω). All positive and negative values are accepted,including 0 and inf (∞). The default is 1.

In a vectorized component, all internal resistors have the same resistanceif the parameter is a scalar. To specify the resistances individually use avector [R1 R2 . . . Rn] . The length n of the vector determines the width ofthe component.

Probe Signals When the resistor is probed, a small dot in the component icon marks the pos-itive terminal.

Resistor voltageThe voltage measured across the resistor from the positive to the negativeterminal, in volts (V).

Resistor currentThe current flowing through the resistor, in amperes (A). A current enter-ing the resistor at the positive terminal is counted positive.

Resistor powerThe power consumed by the resistor, in watts (W).

599


RMS Value

Purpose Calculate root mean square (RMS) value of input signal


Description This block calculates the RMS value of a periodic input signal. The sampletime, fundamental frequency and the initial condition can be specified.

Parameters Initial conditionThe initial condition describes the input signal before simulation start. Ifthe input is a scalar signal the parameter must be a scalar too. If inputand output are vectorized signals a vector can be used. The number of el-ements in the vector must match the number of input signals. The defaultvalue of this parameter is 0.

Sample timeThe time interval between samples. See also the Discrete-Periodic sam-ple time type in section “Sample Times” (on page 38). If a sample timeof 0 is specified, a continuous implementation based on the Moving Aver-age block (see page 545) is active. The Discrete-Periodic implementationcan potentially force a variable-step solver to take small integration steps.This may slow down the simulation. The default value of this parameter is0.


600

Rotational Algebraic Component

Rotational Algebraic Component

Purpose Define an algebraic constraint in terms of torque and angular speed


Description The Rotational Algebraic Component enforces an arbitrary algebraic con-straint involving torque and angular speed.

The output signal “ω” measures the angular speed of the marked flange withrespect to the unmarked one. The output signal “τ” measures the torque flowfrom the unmarked towards the marked flange. The two output signals mustaffect the input signal “0” by means of a direct feedthrough path. The compo-nent ensures that the input signal is zero at all times.

The direct feedthrough path defines a function f(ω, τ), which in turn implicitlydetermines the characteristic curve of the component through the constraintf(ω, τ) = 0. For instance, the choice f(ω, τ) := τ + D · ω causes the Rota-tional Algebraic Component to act as a Rotational Damper (see page 605) withdamping constant D.

The Rotational Algebraic Component offers no direct way to specify an initialdisplacement. In case you need to do so, place a Rotational Damper with zerodamping constant in parallel to the component and set the initial displace-ment property thereof.

By way of illustration, the following schematic shows a possible implementa-tion of a rotational damper with variable damping constant and prescribedinitial displacement:

601


Note The Rotational Algebraic Component creates an algebraic loop. See sec-tion “Block Sorting” (on page 31) for more information on algebraic loops.

Probe Signals Component torqueThe torque flow from the unmarked towards the marked flange.

Component speedThe angular speed of the marked flange with respect to the unmarked one.


602

Rotational Backlash

Rotational Backlash

Purpose Ideal rotational backlash


Description The Rotational Backlash models an ideal symmetrical, two-sided Hard Stop(see page 608) in a rotational system, which restricts the relative displace-ment of the two flanges between an upper and lower limit of ± b

2 . While thedisplacement is within the limits, no torque is transmitted. When the dis-placement hits either limit, the flanges become rigidly connected until thetransmitted torque reverses.

Parameters Total backlashThe total permitted displacement b between the flanges, in radians.

Initial displacementThe initial displacement of the flanges, in radians. May be specified in or-der to provide proper initial conditions if absolute angles are measuredanywhere in the system. Otherwise, this parameter can be left blank.

Probe Signals TorqueThe transmitted torque flowing from the unmarked to the marked flange,in Newton meters (Nm).

DisplacementThe displacement of the marked flange with respect to the unmarkedflange, in radians.

StateThe internal state of the component: -1 in lower limit, 0 inside limits, +1in upper limit.

603


Rotational Clutch

Purpose Ideal rotational clutch


Description The Rotational Clutch models an ideal clutch in a rotational system. Whenengaged, it makes an ideally rigid connection between the flanges; when dis-engaged, it transmits zero torque. The clutch engages when the input signalbecomes non-zero and disengages when the input signal becomes zero.

Parameters Initial stateThe initial state (engaged/disengaged) of the clutch.


604

Rotational Damper

Rotational Damper

Purpose Ideal viscous rotational damper


Description The Rotational Damper models an ideal linear damper in a rotational systemdescribed with the following equations:

τ = −D · ω

where τ is the torque flow from the unmarked towards the marked flange andω is the angular speed of the marked flange with respect to the unmarkedone.

Parameters Damper constantThe damping (viscous friction) constant D, in Nms

rad .


605


Rotational Friction

Purpose Ideal rotational stick/slip friction


Description The Rotational Friction models any combination of static, Coulomb and vis-cous friction between two flanges in a rotational system. While the componentis stuck, it exerts whatever torque is necessary in order to maintain zero rela-tive speed between the flanges, up to the limit of the breakaway torque τbrk.When the breakaway torque is exceeded, the flanges begin sliding againsteach other, and the component exerts a torque that consists of the Coulombfriction torque τC and a speed-dependent viscous friction torque cv · ω.

The figure below shows the speed/torque characteristic and the state chartof the component. Note that the friction torque is opposed to the movement,hence the negative sign.

Sticking

Slidingbackward

Slidingforward

τ > τbrk τ < -τbrk

ω > 0 ω < 0

τbrk

ω

-τ

τCcv⋅ω

Parameters Breakaway friction torqueThe maximum magnitude of the stiction torque τbrk, in Newton metersNm. Must be greater than or equal to zero.

Coulomb friction torqueThe magnitude of the (constant) Coulomb friction torque τC, in Newtonmeters Nm. Must be greater than or equal to zero and less than or equalto the breakaway friction torque.

Viscous friction coefficientThe proportionality coefficient cv that determines the speed dependent vis-cous friction torque, in Nms

rad .

606

Rotational Friction

Probe Signals TorqueThe transmitted torque τ flowing from the unmarked to the markedflange, in Newton meters (Nm).

SpeedThe angular speed ω of the marked flange with respect to the unmarkedflange, in rad

s .

StateThe internal state of the component: -1 sliding backward, 0 stuck, +1 slid-ing forward.

607


Rotational Hard Stop

Purpose Ideal rotational hard stop


Description The Rotational Hard Stop models an ideal one- or two-sided hard stop in a ro-tational system, which restricts the relative displacement of the two flangesbetween an upper and lower limit. While the displacement is within the lim-its, no torque is transmitted. When the displacement hits either limit, the dis-placement is clamped at the limit and the flanges become rigidly connecteduntil the transmitted torque reverses.

The figure below shows the displacement/torque characteristic and the statechart of the component.

Insidelimits

Lowerlimit

Upperlimit

θ < θmin

θ := θmin θ := θmax

θ > θmax

τ < 0 τ > 0

τ := 0θmin θmax θ

τ

Parameters Upper limitThe maximum displacement θmax between the flanges. Set to inf to dis-able this limit.

Lower limitThe minimum displacement θmin between the flanges. Set to -inf to dis-able this limit.


608

Rotational Hard Stop

Probe Signals TorqueThe transmitted torque τ flowing from the unmarked to the markedflange, in Newton meters (Nm).

DisplacementThe displacement θ of the marked flange with respect to the unmarkedflange, in radians.


609


Rotational Model Settings

Purpose Configure settings for an individual mechanical model.

Library Mechanical / Rotational / Model Settings

Description The Rotational Model Settings block lets you configure parameter settingsthat influence the code generation for a particular mechanical system, see also“Code Generation for Physical Systems” (on page 263).

The block affects the mechanical system that it is attached to by its rotationalterminal. At most one Model Settings block may be attached to an individ-ual state-space system. A mechanical model can be split into multiple state-space systems if the underlying model equations are fully decoupled. Notethat a rotational system and a translational system that are coupled e.g. witha Rack and Pinion (see page 592) have coupled model equations. See also theoptions Enable state-space splitting and Display state-space splitting inthe “Simulation Parameters” (on page 107).

Parameters Switching algorithmThis parameter allows you two choose between two algorithms to deter-mine the clutch states in the generated code. See “Switching Algorithm”(on page 265) for details.


TopologiesThis parameter lets you specify a matrix containing the combinations ofclutch states, for which code should be generated, see also “Reducing theCode Size” (on page 264). The columns represent the clutch elements ofthe physical model and each row represents one combination of clutchstates (zero for an open clutch and non-zero for a closed clutch).


610

Rotational Port

Rotational Port

Purpose Add rotational flange to subsystem


Description Rotational ports are used to establish rotational mechanical connections be-tween a schematic and the subschematic of a subsystem (see page 662). If youcopy a Rotational Port block into the schematic of a subsystem, a terminal willbe created on the subsystem block. The name of the port block will appear asthe terminal label. If you choose to hide the block name by unselecting theshow name option in the block menu, the terminal label will also disappear.


Rotational Ports in a Top-Level Schematic

In PLECS Blockset, if a Rotational Port is placed in a top-level schematic, thePLECS Circuit block in the Simulink model will show a corresponding rota-tional terminal, which may be connected with other rotational terminals ofthe same or a different PLECS Circuit block. The Rotational Port is also as-signed a unique physical port number. Together with the parameter Locationon circuit block the port number determines the position of the rotationalterminal of the PLECS Circuit block.

For compatibility reasons you can also place an Rotational Port in a top-levelschematic in PLECS Standalone. However, since there is no parent system toconnect to, such a port will act like an isolated node.

Parameter Port numberIf a Rotational Port is placed in a top-level schematic in PLECS Blockset,this parameter determines the position, at which the corresponding termi-nal appears on the PLECS Circuit block.

Location on circuit blockIf a Rotational Port is placed in a top-level schematic in PLECS Blockset,this parameter specifies the side of the PLECS Circuit block on which thecorresponding terminal appears. By convention, left refers to the sideon which also input terminals are shown, and right refers to the side onwhich also output terminals are shown.

611


Rotational Reference

Purpose Connect to common rotational reference frame


Description The Rotational Reference implements a connection to the rotational referenceframe that has a fixed absolute angle of zero.

612

Rotational Speed (Constant)

Rotational Speed (Constant)

Purpose Maintain constant rotational speed

Library Mechanical / Rotational / Sources

Description The Constant Rotational Speed maintains a constant angular speed betweenits two flanges regardless of the torque required. The speed is considered posi-tive at the flange marked with a “+”.

Note A speed source may not be short-circuited or connected in parallel withother speed sources, nor may a speed source directly drive an inertia.


SpeedThe magnitude of the speed, in rad

s . The default value is 1.

Probe Signals TorqueThe generated torque τ flowing from the unmarked to the marked flange,in Newton meters (Nm).

SpeedThe angular speed, in rad

s .

613


Rotational Speed (Controlled)

Purpose Maintain variable rotational speed


Description The Controlled Rotational Speed maintains a variable angular speed betweenits two flanges regardless of the torque required. The speed is considered pos-itive at the flange marked with a “+”. The momentary speed is determined bythe signal fed into the input of the component.

Note A speed source may not be short-circuited or connected in parallel withother speed sources, nor may a speed source directly drive an inertia.



Probe Signals TorqueThe generated torque τ flowing from the unmarked to the marked flange,in Newton meters (Nm).

SpeedThe angular speed, in rad

s .

614

Rotational Speed Sensor

Rotational Speed Sensor

Purpose Output measured angular speed as signal


Description The Rotational Speed Sensor measures the angular speed of the flangemarked with a dot with respect to the other flange.

Note Speed and angle sensors are ideally compliant. Hence, if multiple speedor angle sensors are connected in series the speed or angle measured by an in-dividual sensor is undefined. This produces a run-time error.

Parameter Second flangeControls whether the second flange is accessible or connected to the rota-tional reference frame.

Probe Signal SpeedThe measured angular speed, in rad

s .

615


Rounding

Purpose Round floating point signal to integer values


Description This component rounds the value of a floating point signal on its input to aninteger value. The rounding algorithm can be selected in the component pa-rameter:

floorThe output is the largest integer not greater than the input, for examplefloor(1.7) = 1 and floor(−1.3) = −2.

ceilThe output is the smallest integer not less than the input, for exampleceil(1.3) = 2 and ceil(−1.7) = −1.

roundThe output is the integer nearest to the input, for example round(1.4) = 1,round(−1.3) = −1 and round(−1.5) = −2.

fixedThe output is the integer value of the input with all decimal places trun-cated, for example fixed(1.7) = 1 and fixed(−1.7) = −1.

Parameter OperationThe rounding algorithm as described above.




616

Saturable Capacitor

Saturable Capacitor

Purpose Capacitor with piece-wise linear saturation


Description This component provides a saturable capacitor between its two electrical ter-minals. The capacitor has a symmetrical piece-wise linear saturation charac-teristic defined by positive voltage/charge pairs.

Note In order to model a saturation characteristic with n segments, this com-ponent requires n ideal capacitors and 2(n − 1) ideal switches. It is thereforeadvisable to use as few segments as possible.

Parameters Voltage valuesA vector of positive voltage values in volts (V) defining the piece-wise lin-ear saturation characteristic. The voltage values must be positive andstrictly monotonic increasing. At least one value is required.

Charge valuesA vector of positive charge values in As defining the piece-wise linear sat-uration characteristic. The charge values must be positive and strictlymonotonic increasing. The number of charge values must match the num-ber of voltage values.

Initial voltageThe initial voltage across the capacitor at simulation start, in volts (V).This parameter may either be a scalar or a vector corresponding to the im-plicit width of the component. The positive pole is marked with a “+”. Theinitial voltage default is 0.



Saturation levelThe saturation level indicates which sector of the piece-wise linear charac-teristic is currently applied. During linear operation, i.e. operation in the

617


first sector, the saturation level is 0. The saturation level is negative fornegative charge and voltage values.

618

Saturable Core

Saturable Core

Purpose Magnetic core element with saturation

Library Magnetic

Description This component models a segment of a magnetic core. It establishes a non-linear relationship between the magnetic field strength H and the flux densityB to model saturation effects. The user can choose between the following fit-ting functions:

atan fit

The atan fit is based on the arctangent function:

B =2

πBsat tan−1

(πH

2a

)+ µsatH

coth fit

The coth fit was adapted from the Langevian equation for bulk magnetizationwithout interdomain coupling, and is given as:

B = Bsat

(coth

3H

a− a

3H

)+ µsatH

Both fitting functions have three degrees of freedom which are set by the coef-ficients µsat, Bsat and a. µsat is the fully saturated permeability, which usuallycorresponds to the magnetic constant µ0, i.e. the permeability of air. Bsat de-fines the knee of the saturation transition between unsaturated and saturatedpermeability:

Bsat = (B − µsatH)∣∣∣H→∞

The coefficient a is determined by the unsaturated permeability µunsat at H =0:

a = Bsat/ (µunsat − µsat)

619


coth fit

atan fit

µunsat

µsat

H

B

Bsat

The figure below illustrates the saturation characteristics for both fitting func-tions. The saturation curves differ only around the transition between unsat-urated and saturated permeability. The coth fit expresses a slightly tightertransition than the atan fit.

Parameters Fitting functionsSaturation characteristic modeled with atan or coth fit.

Cross-sectional areaCross-sectional area A of the flux path, in m2.


Unsaturated rel. permeabilityRelative permeability µr,unsat = µunsat/µ0 of the core material for H → 0.

Saturated rel. permeabilityRelative permeability µr,sat = µsat/µ0 of the core material for H →∞.

Flux density saturationKnee Bsat of the saturation transition between unsaturated and saturatedpermeability.



620

Saturable Core




621


Saturable Inductor

Purpose Inductor with piece-wise linear saturation


Description This component provides a saturable inductor between its two electrical termi-nals. The inductor has a symmetrical piece-wise linear saturation characteris-tic defined by positive current/flux pairs.

L0

1

i

Ψ

I1

I2

I3

Ψ1

Ψ2

Ψ3

The operating mode of the saturable inductor is illustrated in the schematicbelow. In the unsaturated state the current flows only through the main in-ductor L0. When the absolute value of the current exceeds the threshold I1,

622

Saturable Inductor

the breaker in series with the auxiliary inductor L1 is closed. The differentialinductivity of the component thus becomes Ldiff = L0L1

L0+L1. On the other hand,

the total inductivity is calculated as Ltot = L0i0+L1i1i0+i1

, where i0 and i1 are themomentary inductor currents.

Note In order to model a saturation characteristic with n segments, this com-ponent requires n ideal inductors and 2(n − 1) ideal switches. It is thereforeadvisable to use as few segments as possible.

Parameters Current valuesA vector of positive current values I in amperes (A) defining the piece-wiselinear saturation characteristic. The current values must be positive andstrictly monotonic increasing. At least one value is required.

Flux valuesA vector of positive flux values Ψ in Vs defining the piece-wise linear satu-ration characteristic. The flux values must be positive and strictly mono-tonic increasing. The number of flux values must match the number ofcurrent values.

Initial currentThe initial current through the inductor at simulation start, in amperes(A). This parameter may either be a scalar or a vector corresponding to theimplicit width of the component. The direction of a positive initial currentis indicated by a small arrow at one of the terminals. The initial currentdefault is 0.

Probe Signals Inductor currentThe current flowing through the inductor, in amperes (A). The direction ofa positive current is indicated with a small arrow at one of the terminals.


Saturation levelThe saturation level indicates which sector of the piece-wise linear charac-teristic is currently applied. During linear operation, i.e. operation in thefirst sector, the saturation level is 0. The saturation level is negative fornegative flux and current values.

623


Saturable Transformers

Purpose Single-phase transformers with two resp. three windings and core saturation


Description These transformers model two or three coupled windings on the same core.

Lm,0

1

im

Ψm

im

(1) im

(2) im

(3)

Ψm

(1)

Ψm

(2)

Ψm

(3)

The core saturation characteristic is piece-wise linear and is modeled usingthe Saturable Inductor (see page 622). The magnetizing current im and fluxΨm value pairs are referred to the primary side. To model a transformer with-out saturation enter 1 as the magnetizing current values and the desired mag-netizing inductance Lm as the flux values. A stiff Simulink solver is recom-mended if the iron losses are not negligible, i.e. Rfe is not infinite.

In the transformer symbol, the primary side winding is marked with a littlecircle. The secondary winding is marked with a dot at the outside terminal,the tertiary winding with a dot at the inside terminal.

Parameters Leakage inductanceA vector containing the leakage inductance of the primary side L1, the sec-ondary side L2 and, if applicable, the tertiary side L3. The inductivity isgiven in henries (H).

Winding resistanceA vector containing the resistance of the primary winding R1, the sec-ondary winding R2 and, if applicable, the tertiary winding R3, in ohms (Ω).

624

Saturable Transformers

No. of turnsA vector containing the number of turns of the primary winding n1, thesecondary winding n2 and the tertiary winding n3, if applicable.

Magnetizing current valuesA vector of positive current values in amperes (A) defining the piece-wiselinear saturation characteristic of the transformer legs. The current valuesmust be positive and strictly monotonic increasing. At least one value isrequired.

Magnetizing flux valuesA vector of positive flux values in Vs defining the piece-wise linear satura-tion characteristic. The flux values must be positive and strictly monotonicincreasing. The number of flux values must match the number of currentvalues.

Core loss resistanceAn equivalent resistance Rfe representing the iron losses in the trans-former core. The value in ohms (Ω) is referred to the primary side.

Initial currentA vector containing the initial currents on the primary side i1, the sec-ondary side i2 and the tertiary side i3, if applicable. The currents aregiven in amperes (A) and considered positive if flowing into the trans-former at the marked terminals. The default is [0 0 0].

625


Saturation

Purpose Limit input signal to upper and/or lower value


Description The saturation block limits a signal to an upper and/or lower value. If the in-put signal is within the saturation limits the output signal is identical to theinput signal.

Parameters Upper limitThe highest value that the input signal may reach before the output signalis clipped. If the value is set to inf the output is unlimited.

Lower limitThe lowest value that the input signal may reach before the output signalis clipped. If the value is set to -inf the output is unlimited.



626

Sawtooth PWM

Sawtooth PWM

Purpose Generate PWM signal using sawtooth carrier


Description 2-level PWM generator with a sawtooth carrier. The input m is the modula-tion index, and the output s is the switching function. If the modulation indexis a vector the switching function is also a vector of the same width.

The block can be used to control the IGBT Converter (see page 470) or theideal Converter (see page 455). In these cases the modulation index must havea width of 3 to match the number of inverter legs.

The following figures illustrate different sampling methods offered by themodulator block. In the figure on the left, Natural Sampling is used. The rightfigure shows Regular Sampling, i.e. the modulation index is updated at thevertical flanks of the carrier. In both figures carrier signals with falling rampsare employed.

−1

0

1

Switc

hing

fun

ctio

n

−1

0

1

Natural Sampling

Mod

ulat

ion

inde

x

1/f

Regular Sampling

1/f

627


Parameters SamplingChoose between Natural and Regular Sampling.

RampChoose between rising and falling ramps in the carrier signal.

Carrier frequencyThe frequency f of the carrier signal, in Hz.

Carrier offsetThe time offset of the carrier signal, in p.u. of the carrier period.

Input limitsThe range of the modulation index. The default is [-1 1].

Output valuesValues of the switching function in off-state and on-state. The default is[-1 1].

628

Sawtooth PWM (3-Level)

Sawtooth PWM (3-Level)

Purpose Generate 3-level PWM signal using sawtooth carriers


Description 3-level PWM generator with a sawtooth carrier. The input m is the modula-tion index. The switching function s outputs either 1, 0 or -1. If the modula-tion index is a vector the switching function is also a vector of the same width.

The block can be used to control the 3-Level IGBT Converter (see page 460)or the ideal 3-Level Converter (see page 454). In these cases the modulationindex must have a width of 3 to match the number of inverter legs.

The figures below illustrate different sampling methods offered by the modula-tor block. In the left figure, Natural Sampling is used. The right figure showsRegular Sampling, i.e. the modulation index is updated at the vertical flanksof the carrier. In both figures carrier signals with rising ramps are employed.

−1

0

1

Switc

hing

fun

ctio

n

−1

0

1

Natural sampling

Mod

ulat

ion

inde

x

1/f

Regular sampling

1/f

629


Parameters SamplingChoose between Natural and Regular Sampling.

RampChoose between rising and falling ramps in the carrier signal.

Carrier frequencyThe frequency f of the carrier signal, in Hz.



630

Scope

Scope

Purpose Display simulation results versus time

Library System

Description The PLECS scope displays the measured signals of a simulation. It can beused in PLECS circuits as well as in Simulink models.

A number of analysis tools and data display options allow detailed analysisof the measured signals. For more information on how to work with the scopesee section “Using the PLECS Scope” (on page 95).

ParametersScope Setup

Number of plotsThis parameter specifies the number of plots shown in the scope window.Each plot corresponds to a terminal on the outside of the block. For eachplot, a tab is displayed in the lower part of the dialog where the plot set-tings can be edited.

Sample timeThe block sample time used to sample the input signals. The default is -1(inherited). Other valid settings are 0 (continuous) or a valid fixed-stepdiscrete sample time pair (see “Sample Times” on page 38).

Limit samplesIf this option is selected, the PLECS scope will only save the last n samplevalues during a simulation. It can be used in long simulations to limit theamount of memory that is used by PLECS. If the option is unchecked, allsample values are stored in memory.

Time Axis Parameters

Display time axisThe time axis is either shown underneath each plot or underneath the lastplot only.

Time axis labelThe time axis label is shown below the time axis in the scope.

631


Time rangeThe time range value determines the initial time range that is displayedin the scope. If set to auto, the simulation time range is used.

Scrolling modeThe scrolling mode determines the way in which the x-axis is scrolled ifduring a simulation the current simulation time goes beyond the right x-axis limit.

In the paged mode, the plots are cleared when the simulation timereaches the right limit and the x-axis is scrolled by one full x-axis span,i.e. the former right limit becomes the new left limit.

In the continuous mode, the plots are continuously scrolled so that newdata is always drawn at the right plot border. Note that this mode may af-fect runtime performance as it causes frequent updates of relatively largescreen areas.

Individual Plot Parameters

TitleThe name which is displayed above the plot.

Axis labelThe axis label is displayed on the left of the y-axis.

Y-limitsThe initial lower and upper bound of the y-axis. If set to auto, the y-axislimits are automatically chosen based on the minimum and maximumcurve value in the visible time range. If you check the Keep baseline op-tion, the limits are chosen so that the specified baseline value is alwaysincluded.

632

Set/Reset Switch

Set/Reset Switch

Purpose Bistable on-off switch


Description This component provides an ideal short or open circuit between its two elec-trical terminals. The switch closes when the closing signal (the upper input inthe component icon) becomes non-zero. It opens when the opening signal (thelower input) becomes non-zero. The Set/Reset Switch provides the basis for allother switches and power semiconductor models in PLECS.

Parameters Initial conductivityInitial conduction state of the switch. The switch is initially open if the pa-rameter evaluates to zero, otherwise closed. This parameter may either bea scalar or a vector corresponding to the implicit width of the component.The default value is 0.

Thermal descriptionSwitching losses, conduction losses and thermal equivalent circuit of thecomponent. For more information see chapter “Thermal Modeling” (onpage 119).


Probe Signals Switch conductivityConduction state of the switch. The signal outputs 0 if the switch is open,and 1 if it is closed.

Switch temperatureTemperature of the first thermal capacitor in the equivalent Cauer net-work.

Switch conduction lossContinuous thermal conduction losses in watts (W). Only defined if thecomponent is placed on a heat sink.

633


Switch switching lossInstantaneous thermal switching losses in joules (J). Only defined if thecomponent is placed on a heat sink.

634

Signal Demultiplexer

Signal Demultiplexer

Purpose Split vectorized signal

Library System

Description This demultiplexer extracts the components of a input signal and outputsthem as separate signals. The output signals may be scalars or vectors. In theblock icon, the first output is marked with a dot.

Parameter Number of outputsThis parameter allows you to specify the number and width of the outputsignals. You can choose between the following formats for this parameter:

Scalar: A scalar specifies the number of scalar outputs. If this format isused all output signals have a width of 1.

Vector: The length of the vector determines the number of outputs. Eachelement specifies the width of the corresponding output signal.

635


Signal From

Purpose Reference signal from Signal Goto block by name

Library System

Description The Signal From block references another signal from a Signal Goto block. AllSignal From blocks connect to the Signal Goto block with the same tag withinthe given scope. If no matching Signal Goto block is found an error messagewill be displayed when starting a simulation.

The parameter dialog of the Signal From block provides a link to the corre-sponding Signal Goto block. Note that the link is not updated until you clickthe Apply button after changing the tag name or scope.

Parameters Tag name:The tag names of the Signal From and Signal Goto blocks must match toestablish a connection.

Scope:The scope specifies the search depth for the matching Signal Goto block.Using the value Global the complete PLECS circuit is searched. Whenset to Schematic only the schematic containing the Signal From blockis searched. The setting Masked Subsystem causes a lookup within thehierarchy of the masked subsystem in which the block is contained. If theblock is not contained in a masked subsystem a global lookup is done.

636

Signal Goto

Signal Goto

Purpose Make signal available by name

Library System

Description The Signal Goto block forwards its input signal to a number of Signal Fromblocks within the same scope. All Signal From blocks connect to the SignalGoto block with the same tag within the given scope. It is not allowed to havemultiple Signal Goto blocks with the same tag name within the same scope.

The parameter dialog of the Signal Goto block provides a list of links to thecorresponding blocks, i.e. all Signal From blocks with a matching tag nameand scope. Note that the list is not updated until you click the Apply buttonafter changing the tag name or scope.

Parameters Tag name:The tag names of the Signal From and Signal Goto blocks must match toestablish a connection.

Scope:The scope specifies the search depth for the matching Signal From blocks.Using the value Global the complete PLECS circuit is searched. Whenset to Schematic only the schematic containing the Signal From blockis searched. The setting Masked Subsystem causes a lookup within thehierarchy of the masked subsystem in which the block is contained. If theblock is not contained in a masked subsystem a global lookup is done.

637


Signal Inport

Purpose Add signal input connector to subsystem

Library System

Description

1

Inports are used to feed signals from a schematic into a subschematic. InPLECS Blockset, inports are also used to feed signals from a Simulink modelinto a PLECS circuit. If you copy an input block into a schematic an input ter-minal will be created on the corresponding subsystem block. The name of theinput block will appear as the terminal label. If you choose to hide the blockname by unselecting the show button in the dialog box the terminal label willalso disappear.

Input Blocks in a Top-Level Circuit

If an input block is placed in a top-level schematic a unique input port numberis assigned to the block. In PLECS Blockset, this port number determines theposition of the corresponding input terminal of the PLECS Circuit block in theSimulink model.

For top-level inputs in PLECS Blockset you can also specify whether the in-put signal is used as a continuous signal in order to control e.g. sources or asa discrete gate signal in order to feed control the gate of a switch or semicon-ductor. Continuous signal inputs have direct feedthrough which can lead toalgebraic loops if there is a direct path from a circuit output to a (continuous)circuit input. In contrast, gate signal inputs do not have direct feedthrough.However, they are expected to change only at discrete instants. Using a gatesignal input to feed a continuous signal into a Circuit block can lead to un-expected results. The standard setting auto causes PLECS to determine thesignal type based on the internal connectivity.

Input Blocks in a Subsystem

If placed in a subschematic the inputs are not identified by numbers since ter-minals on subsystem blocks can be freely positioned. Which terminal corre-sponds to which input block can only be seen from the block name. In order tomove a terminal with the mouse around the edges of a subsystem block holddown the Shift key while dragging the terminal with the left mouse button oruse the middle mouse button.

638

Signal Inport

Parameters WidthThe width of the input signal. The default auto means that the width isinherited from connected blocks.

Signal typeThe input signal type (see the description above). This parameter appearsonly in PLECS Blockset if the block is placed in a top-level schematic.

Port numberThe terminal number of the input block. This parameter appears only inPLECS Blockset if the block is placed in a top-level schematic.

Output data typeThe data type of the output signal. See “Data Types” (on page 42). Thisparameter appears only if the block is placed in a top-level schematic or inan atomic subsystem (see “Virtual and Atomic Subsystems” on page 662).

639


Signal Multiplexer

Purpose Combine several signals into vectorized signal

Library System

Description This multiplexer combines several signals into a vectorized signal. The inputsignals may be scalars or vectors. In the block icon, the first input is markedwith a dot.

Parameter Number of inputsThis parameter allows you to specify the number and width of the inputsignals. You can choose between the following formats for this parameter:

Scalar: A scalar specifies the number of scalar inputs to the block. If thisformat is used the block accepts only signals with a width of 1.

Vector: The length of the vector determines the number of inputs. Eachelement specifies the width of the corresponding input signal.

640

Signal Outport

Signal Outport

Purpose Add signal output connector to subsystem

Library System

Description

1

Outports are used to feed signals from subschematic to the parent schematic.In PLECS Blockset, outports are also used to feed signals from a PLECS cir-cuit back to Simulink. If you copy an output block into a schematic an outputterminal will be created on the corresponding subsystem block. The name ofthe output block will appear as the terminal label. If you choose to hide theblock name by unselecting the show button in the dialog box the terminalname will also disappear.

Output Blocks in a Top-Level Circuit

If an output block is placed in a top-level circuit a unique output port numberis assigned to the block. In PLECS Blockset, this port number determines theposition of the corresponding output terminal of the PLECS Circuit block inthe Simulink model.

Output Blocks in a Subsystem

If placed in a subschematic the outputs are not identified by numbers sinceterminals on subsystem blocks can be freely positioned. Which terminal cor-responds to which output block can only be seen from the block name. In or-der to move a terminal with the mouse around the edges of a subsystem holddown the Shift key while dragging the terminal with the left mouse button oruse the middle mouse button.

Parameters WidthThe width of the output signal. The default auto means that the width isinherited from connected blocks.

Output when disabledThis parameter appears only if the block is placed in an enabled subsys-tem (see the Enable block on page 424) and determines the output signalwhile the subsystem is disabled. If you select held, the output will holdthe most recent value before the subsystem was disabled. If you selectreset, the output will be reset to the initial output value (see below).

641


Initial outputThis parameter appears only if the block is placed in an enabled and/ortriggered subsystem (see the Enable block on page 424 and the Triggerblock on page 754) and specifies the initial output before the subsystem isfirst enabled or triggered.

Port numberThe terminal number of the output block. This parameter appears only ifthe block is placed in a top-level circuit.

642

Signal Selector

Signal Selector

Purpose Select or reorder elements from vectorized signal

Library System

Description The Signal Selector block generates an output vector signal that consists ofthe specified elements of the input vector signal.

See also the Dynamic Signal Selector block (see page 415).

Parameters Input widthThe width of the input signal vector.

Output indicesA vector with the indices of the input elements that the output vectorshould contain.

643


Signal Switch

Purpose Select one of two input signals depending on control signal


Description While the Signal Switch is in the off-state the output is connected to the in-put terminal indicated in the icon. When the switch criteria is met, the switchchanges to the on-state and the output is connected to the opposite input ter-minal.

Parameters CriteriaThe switch criteria which has to be met to put the switch in the on-state.Available choices are• u >= Threshold,• u > Threshold and• u ∼= Threshold.

ThresholdThe threshold value used for the switch criteria.



Switch positionThe state of the switch. The output is 0 while the switch is in the off-stateand 1 while it is in the on-state.

644

Signum

Signum

Purpose Provide sign of input signal


Description The Signum block outputs 1 for positive, -1 for negative and 0 for 0 input val-ues.



645


Sine Wave

Purpose Generate time-based sine wave with optional bias


Description The Sine Wave block generates a sinusoidal output signal with an optionalbias according to the equation

y = A · sin(ω · t+ ϕ) + C ω = 2πf

If a variable-step solver is used, the solver step size is automatically limited toensure that a smooth waveform is produced.

Parameters AmplitudeThe amplitude A of the sine wave signal.

BiasThe offset C that is added to the sine wave signal.

FrequencyThe frequency of the sine wave in hertz (f ) or rad/second (ω), see below.

PhaseThe phase ϕ of the sine wave in rad, per unit (p.u.) or degrees, see below.The parameter value should be in the range [0 2π], [0 1] or [0 360] re-spectively.

Units for frequency and phaseThe frequency and phase can be expressed in terms of (rad/sec, rad),(Hz, p.u.) or (Hz, degrees). If the phase is expressed in per unit (p.u.),a value of 1 is equivalent to the period length.

Probe Signal OutputThe block output signal.

646

Small Signal Gain

Small Signal Gain


Purpose Measure loop gain of closed control loop using small-signal analysis

Library Control / Small Signal Analysis

Description This block uses the Small Signal Perturbation block see page 648 and theSmall Signal Response block see page 649 to inject a perturbation into afeedback loop and measure the system response. To see the implementationchoose Look under mask from the Subsystem submenu of the block’s con-text menu.

For detailed information regarding small-signal analysis see chapter “AnalysisTools” (on page 165).

Parameter Compensate for negative feedbackWhen set to on, the underlying Small Signal Response block inverts thereference input in order to compensate for a negative unity gain that isintroduced when the feedback signal is subtracted from a reference signal.

When set to off, the reference input is taken as is.

647


Small Signal Perturbation


Purpose Generate perturbation signal for small-signal analysis


Description During a small-signal analysis that references this block, it generates the ap-propriate perturbation signal: a sinusoidal signal for an AC Sweep and a dis-crete pulse for an Impulse Response Analysis. At all other times the perturba-tion is zero.


Parameter Show feed-through inputWhen set to on, the block displays an input port. The output signal is thesum of the input signal and the perturbation. The default is off.

648

Small Signal Response

Small Signal Response


Purpose Measure system response for small-signal analysis


Description During a small-signal analysis that references this block, it records the sig-nal(s) that are connected to the block input(s) in order to calculate the trans-fer function

G(s) =Y (s)

U(s)

If the reference input is shown, U(s) is calculated from the signal that is con-nected to it. Otherwise, U(s) is calculated from the perturbation signal gener-ated by the corresponding Small Signal Perturbation block see page 648.


Parameters Show reference inputSpecifies whether or not the block shows the reference input port.

Invert reference inputSpecifies whether or not the reference input signal is inverted, i.e. multi-plied with -1.

649


Space Vector PWM

Purpose Generate PWM signals for 3-phase inverter using space-vector modulationtechnique


Description The space vector modulator generates a reference voltage vector, −→Vs, at the acterminals of a three phase voltage source converter shown below. The refer-ence vector is defined in the αβ coordinate system: −→Vs = V ∗α + j V ∗β .

Vdc

leg A leg B leg C

Vsabc

Operation The construction of the reference voltage vector, −→Vs, is graphically depicted be-low. Internally, the space vector modulator consists of a sector detection andvector timing calculation function that is executed at the beginning of theswitching cycle. In this function, the operating sector and relative on-timesof the switching vectors are calculated. During a switching cycle, a vector gen-eration and sequencing function is called at the switching instants to updatethe switch output.

The sector detection calculation determines the sector in which the referencevoltage vector −→Vs resides. The relative on-times, τa, τb, τ0, for the switching vec-tors −→Va,

−→Vb and −→V0 are then calculated. In each sector, two unique switching

vectors named −→Va and −→Vb are available. Two zero vectors, named−→V 1

0 ,−→V 2

0 arealso available. The relationship between the relative on-times and the refer-ence vector is shown below for an arbitrary sector. The relative on-times arecalculated by projecting the reference vector onto the vectors −→Va and −→Vb.

The vector generation and sequencing function creates a switching cy-cle by time-averaging the switching vectors according to their on-time

650

Space Vector PWM

vs

Sector 2

Sector 1Sector 3

Sector 4 Sector 6

Sector 5

v *v *

Construction of the reference vector −→Vs.

values. There are many possible switching sequences that can be imple-mented since the order in which the vectors −→Va,

−→Vb,−→V0 are applied dur-

ing a switching cycle is arbitrary. In addition, one or both of the −→V0 vec-tors can be used. For further information, please read the documenta-tion that accompanies the demo model "Space Vector Control of a ThreePhase Rectifier using PLECS". This documentation can be found atwww.plexim.com/sites/default/files/plecs_svm.pdf.

651

http://www.plexim.com/support/application-examples/189

http://www.plexim.com/support/application-examples/189

http://www.plexim.com/sites/default/files/plecs_svm.pdf


Vb

Va

vsV0V0 Va

Vb

V0,1 2

0

b

a

Relationship between relative on times, τa, τb, τ0, switching vectors, −→Va,−→Vb,−→V0,

and reference vector, −→Vs.

Parameters Modulation strategyThe modulation strategy can be set to ‘Alternating zero vector’ or ‘Symmet-rical’ using a combo box. With alternating zero vector modulation, only oneof the two −→V0 switching vectors is used during a switching sequence. Oneswitch leg is always clamped to the positive or negative dc bus voltage andonly two of the three inverter legs are switched.

With symmetrical modulation, the two −→V0 switching vectors are used: oneat the beginning and one at the middle of a switching sequence. All threeinverter legs are switched during a switching sequence.

Switching frequencyThe switching frequency in Hz.

Switch output valuesThe switch output values in the high and low state. The values shouldbe selected to match the inverter’s gate control logic so that a high valueturns on the upper switch in the leg and the low value turns on the lowerswitch. The default values are [−1 1].

Inputs andOutputs

DC voltageThe input signal Vdc is the voltage measured on the dc side of the inverter.

Reference voltageThis input, labeled V ∗αβ , is a two-dimensional vector signal comprising theelements [V ∗α , V

∗β ].

652

Space Vector PWM

Switch outputThe output labeled sw is formed from three switch control signals,[Sa, Sb, Sc], which control the inverter legs A, B, and C. Each switch signalcontrols the upper and lower switches in the respective leg.

Probe Signals sectorA value in the set of [1..6] that indicates the sector in which the referer-ence vector, −→Vs, is located.

tauA vector signal comprising the three relative on-time values, [τa, τb, τ0].

swA vector signal consisting of the three gate signals for the inverter legs,[Sa, Sb, Sc].

653


Space Vector PWM (3-Level)

Purpose Generate PWM signals for a 3-phase 3-level neutral-point clamped inverterusing space-vector modulation technique


Description The 3-level space-vector modulator generates a voltage vector on the ac ter-minals of a neutral-point clamped 3-phase inverter according to a referencesignal provided in the stationary αβ reference frame.

By controlling the semiconductor gate signals, each ac terminal can be con-nected either to the high (+), low (-) or neutral (o) point of the dc link. Thisresults in 27 vectors including 12 short vectors, 6 medium vectors and 6 longvectors, as well as 3 zero vectors. Under the assumption of balanced voltageson the capacitors Vdc+ and Vdc− the space-vector diagram is graphically de-picted below.

654


-+- o+-

+o-

+--

+-o

+-+ o-+ --+

-o+

-++

-+o

++-

++o oo-

+oo o--

+o+ o-o --o

oo+

-oo o++

o+o -o-

Sector

3

Sector

2

Sector

1

Sector

4 Sector

6

Zone 2

Zone 3

Zone 1

Zone 4

The hexagon area can be divided in to six sectors (1 to 6), each of which hasfour zones (1 to 4). As an example, consider the reference voltage ~V ∗ to be lo-cated in zone 2 of sector 1. In order to generate the reference voltage ~V ∗ onthe ac terminals, the adjacent vectors ~V1, ~V3 and ~V5 are selected and weightedby time. The on-time of each vector with respect to the switching period is cal-culated as:

τa = 1− 2k sin (θ)

τb = 2k sin(π

3+ θ)− 1

τc = 1− 2k sin(π

3− θ)

This block implements a symmetrical sequence to achieve minimum total har-monic distortion (THD). The short vectors have redundant switch states, e.g.~V1 can be either generated by the combination (+oo) or (o--). In order to keepthe dc link voltages balanced, both switch states must be applied for the same

655


V0

V1

V2

V5

V4

V3

V *

Sector

1

τ a

τ bτ c

θ

duration during one switching period. The resulting switch pattern is illus-trated below:

τ c4

τ a4

τ b2

τ c4

τ a2

τ c4

τ b2

τ a4

τ c4

Sa

Sb

Sc

Parameters Switching frequencyThe switching frequency in Hz.

Output valuesThe switch output values in the high, neutral and low state. The defaultvalues are [-1 0 1].

Inputs andOutputs

DC voltageThe input signal Vdc is the sum of the two dc link voltages Vdc+ and Vdc−.

656


Reference voltageThis input, labeled V ∗αβ , is a two-dimensional vector signal comprising theelements [V ∗α , V

∗β ].

Switch outputThe output labeled sw is formed from the three switch signals [Sa, Sb, Sc],which control the converter legs A, B and C. Each switch signal deter-mines if the corresponding ac terminal shall be connected to the positive,neutral or negative side of the dc link.

Probe Signals sectorA value in the set of [1..6] that indicates the sector in which the referencevector, ~V ∗, is located.

zoneA value in the set of [1..4] that indicates the zone in which the referencevector, ~V ∗, is located.

tauA vector signal comprising the three relative on-time values, [τa, τb, τc].

swA vector signal consisting of the three gate signals for the inverter legs,[Sa, Sb, Sc].

657


SR Flip-flop

Purpose Implement set-reset flip-flop


Description The SR Flip-flop behaves like a pair of cross-coupled NOR logic gates. Theoutput values correspond to the following truth table:

S R Q /Q


0 1 0 1

1 0 1 0

1 1 Restricted (0) Restricted (0)

The combination S = R = 1 is restricted because both outputs will be set to 0,violating the condition Q = not(/Q). If both inputs change from 1 to 0 in thesame simulation step, Q will be set to 0 and /Q to 1.

Parameter Initial stateThe state of the flip-flop at simulation start.

Probe Signals SThe input signal S.

RThe input signal R.



658

State Machine

State Machine

Purpose Model a state machine

Library Control / State Machine

Description The State Machine block lets you graphically create and edit state machinesand simulate them together with a surrounding system. For a detailed de-scription of State Machines see chapter “State Machines” (on page 221).

659


State Space

Purpose Implement linear time-invariant system as state-space model


Description The State Space block models a state space system of the formx = Ax + Bu, y = Cx + Du, where x is the state vector, u is the input vector,and y is the output vector.

Parameters A,B,C,DThe coefficient matrices for the state space system. The dimensions for thecoefficient matrices must conform to the dimensions shown in the diagrambelow:

where n is the number of states, m is the width of the input signal and pis the width of the output signal.

Initial conditionA vector of initial values for the state vector, x.

Probe Signals InputThe input vector, u.

OutputThe output vector, y.

660

Step

Step

Purpose Output a signal step.


Description The Step block generates an output signal that changes its value at a givenpoint in time.

Parameters Step timeThe time at which the output signal changes its value.

Initial outputThe value of the output signal before the step time is reached.

Final outputThe value of the output signal after the step time is reached.



661


Subsystem

Purpose Create functional entity in hierarchical simulation model

Library System

Description A subsystem block represents a system within another system. In order tocreate a subsystem, copy the subsystem block from the library into yourschematic. You can then open the subsystem block and copy components intothe subsystem’s window.

The input, output, and physical terminals on the block icon correspond to theinput, output, and physical port blocks in the subsystem’s schematic. If theblock names are not hidden, they appear as terminal labels on the subsystemblock.

You can move terminals with the mouse around the edges of the subsystem byholding down the Shift key while dragging them with the left mouse buttonor by using the middle mouse button.

Note A subsystem can be converted to a configurable subsystem (see the Con-figurable Subsystem block on page 364) by selecting Convert to configurablesubsystem from the Subsystem submenu of the Edit menu or the block’s con-text menu.

Virtual and Atomic Subsystems

By default, PLECS treats subsystems as virtual, which means that they onlyrepresent a graphical grouping of the components that they comprise. At sim-ulation start, virtual subsystems are flattened and the components they com-prise are ordered individually when PLECS determines their proper executionorder (see “Block Sorting” on page 31).

In an atomic subsystem, on the other hand, the components are not onlygrouped graphically but they are also executed as a group. This is necessaryif the execution depends on a condition such as a common sample time or anenable and/or a trigger signal (see the Enable block on page 424 and the Trig-ger block on page 754).

662

Subsystem

Whether a subsystem is virtual or atomic is controlled by the subsystem exe-cution settings.

Note A subsystem that has physical terminals cannot be made atomic.

ExecutionSettings

To open the dialog for editing the subsystem settings, select the block, thenchoose Execution settings... from the Subsystem submenu of the Editmenu or the block’s context menu.

Treat as atomic unitIf this parameter is checked, PLECS treats the subsystem as atomic, oth-erwise as virtual (see “Virtual and Atomic Subsystems” above).

Minimize occurrence of algebraic loopsThis parameter only applies to atomic subsystems. If it is unchecked,PLECS assumes that all inputs of the subsystem have direct feedthrough,i.e. the output functions of the blocks feeding these inputs must be exe-cuted before the output function of the subsystem itself can be executed(see “Block Sorting” on page 31). If the atomic subsystem is part of a feed-back loop this can result in algebraic loop errors where a virtual subsys-tem could be used without problems.

If the parameter is checked, PLECS determines the actual feedthrough be-havior of the individual inputs from the internal connectivity. A subsysteminput that is internally only connected to non-direct feedthrough inputs ofother blocks (e.g. the inputs of Integrator, Memory or Delay blocks) doesnot have direct feedthrough. This can help reduce the occurrence of alge-braic loops.

Sample timeThis parameter is enabled only if the subsystem is atomic and specifies thesample time with which the subsystem and the components that it com-prises are executed. A setting of auto (which is the default) causes thesubsystem to choose its sample time based on the components that it com-prises.

Enable code generationChecking this option causes the subsystem to be added to the list of sys-tems in the Coder Options dialog (see “Generating Code” on page 269).Note that it is not possible to enable code generation for a subsystem thatis contained by or that itself contains other subsystems that enable code

663


generation. Checking this option also implicitly makes the subsystematomic and disables the minimization of algebraic loops.

Discretization step sizeThis parameter is enabled only if code generation is enabled. It specifiesthe base sample time for the generated code and is used to discretize thephysical model equations (see “Physical Model Discretization” on page 35)and continuous state variables of control blocks.

Simulation modeThis parameter is enabled only if code generation is enabled. When thisparameter is set to Normal, which is the default, the subsystem is simu-lated like a normal atomic subsystem. When the parameter is set to Code-Gen, the generated code is compiled and linked to PLECS to be executedinstead of the subsystem during a simulation.

In connection with the “Traces” feature of the scopes (see “Adding Traces”on page 100), this allows you to easily verify the fidelity of the generatedcode against a normal simulation.

Parameters You can create a dialog box for your Subsystem by masking the block (see“Mask Parameters” on page 71 for more details).

664

Sum

Sum

Purpose Add and subtract input signals


Description The Sum block adds or subtracts input signals. In case of a single input, allelements of the input vector are summed or subtracted. Vectorized input sig-nals of the same width are added or subtracted element wise and result in avectorized output signal. If vectorized and scalar input signals are mixed, thescalar input signals are expanded to the width of the vectorized input signals.

Parameters Icon shapeSpecifies whether the block is drawn with a round or a rectangular shape.Round shape icons permit a maximum of three inputs.

List of signs or number of inputsThe inputs can be specified either with• a string containing + or - for each input and | for spacers, or• a positive integer declaring the number of summands.




665


Switch

Purpose On-off switch


Description This Switch provides an ideal short or open circuit between its two electricalterminals. The switch is open when the input signal is zero, otherwise closed.

Parameter Initial conductivityInitial conduction state of the switch. The switch is initially open if the pa-rameter evaluates to zero, otherwise closed. This parameter may either bea scalar or a vector corresponding to the implicit width of the component.The default value is 0.

Probe Signal Switch conductivityConduction state of the switch. The signal outputs 0 if the switch is open,and 1 if it is closed.

666

Switched Reluctance Machine


Purpose Detailed model of switched reluctance machine with open windings


Description These components represent analytical models of three common switched re-luctance machine types: three-phase 6/4 SRM, four-phase 8/6 SRM and five-phase 10/8 SRM.

The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motor mode,otherwise in generator mode. In the component icon, the positive terminals ofthe stator windings are marked with a dot.

Note The Switched Reluctance Machine models can only be simulated withthe Continuous State-Space Method.

The machine flux linkage is modeled as a non-linear function of the stator cur-rent and rotor angle Ψ(i, θ) accounting for both the magnetization characteris-tic of the iron and the variable air gap.

∂Ψ/∂i = La

∂Ψ/∂i = Lsat

∂Ψ/∂i = Lu

i

Ψ

Ψsat

667


In the unaligned rotor position the flux linkage is approximated as a linearfunction:

Ψu(i) = Lu · i

In the aligned rotor position the flux linkage is a non-linear function of thestator current:

Ψa(i) = Ψsat ·(1− e−K·i

)+ Lsat · i

where

K =La − Lsat

Ψsat

For intermediate rotor positions the flux linkage is written as a weighted sumof these two extremes

Ψ(i, θ) = Ψu(i) + f(θ) · (Ψa(i)−Ψu(i))

using the weighting function

f(θ) =1

2+

1

2cos

(Nr

[θ + 2π · x

Ns

])where Nr is the number of rotor poles, Ns is the number of stator poles, andx = 0 . . . (Ns/2− 1) is the index of the stator phase.

Electrical System

∂Ψ/∂iR ∂Ψ/∂θ ∙ ω

+

−

v

i

The terminal voltage of a stator phase is determined by the equation

v = R · i+dΨ

dt= R · i+

∂Ψ

∂i· didt

+∂Ψ

∂θ· dθdt

The electromagnetic torque produced by one phase is the derivative of the co-energy with respect to the rotor angle:

T (i, θ) =∂

∂θ

ˆ i

0

Ψ(i′, θ)di′

668


The total torque Te of the machine is given by the sum of the individual phasetorques.

Mechanical System

Rotor speed:

d

dtω =

1

J(Te − Fω − Tm)

Rotor angle:

d

dtθ = ω

Parameters Stator resistanceStator resistance R in ohms (Ω).

Unaligned stator inductanceStator inductance Lu in the unaligned rotor position, in henries (H).

Initial aligned stator inductanceInitial stator inductance La in the aligned rotor position, in henries (H).

Saturated aligned stator inductanceSaturated stator inductance Lsat in the aligned rotor position, in henries(H).

Aligned saturation flux linkageFlux linkage Ψsat at which the stator saturates in the aligned position, inVs.





Initial stator currentsA three-element vector containing the initial stator currents ia,0, ib,0 andic,0 of phases a, b and c in amperes (A).

669




Stator flux linkageThe flux linkages in the individual phases of the machine in Vs.




ReferencesD.A. Torrey, J.A. Lang, “Modelling a nonlinear variable-reluctance motor

drive”, IEE Proceedings, Vol. 137, Pt. B, No. 5, Sept. 1990.

D.A. Torrey, X.-M. Niu, E.J. Unkauf, “Analytical modelling of variable-reluctance machine magnetisation characteristic”, IEE Proceedings Elec-tric Power Applications, Vol. 142, No. 1, Jan. 1995.

670

Symmetrical PWM

Symmetrical PWM

Purpose Generate PWM signal using symmetrical triangular carrier


Description 2-level PWM generator with a symmetrical triangular carrier. The input m isthe modulation index, and the output s is the switching function. If the mod-ulation index is a vector the switching function is also a vector of the samewidth.

The block can be used to control the IGBT Converter (see page 470) or theideal Converter (see page 455). In these cases the modulation index must havea width of 3 according to the number of inverter legs.

The block offers different sampling methods for the modulation index. The fig-ure below illustrates Natural Sampling.

−1

0

1

Switc

hing

fun

ctio

n

−1

0

1

Natural Sampling

Mod

ulat

ion

inde

x

1/f

The following figures illustrate the different Regular Sampling methods. Inthe figure on the left, double edge sampling is used, i.e. the modulation in-dex is updated at both tips of the triangular carrier. In the right figure, single

671


edge sampling is employed. Here, the modulation index is updated only at theupper tips of the carrier.

−1

0

1

Switc

hing

fun

ctio

n

−1

0

1

Double edge sampling

Mod

ulat

ion

inde

x

1/f

Single edge sampling

1/f

Parameters SamplingSelect a sampling method. If you select Natural Sampling the carriersignal may begin with 0 or 1 at simulation start. The Regular Samplingmethod lets you choose between double edge or single edge sampling.

Carrier frequencyThe frequency f of the triangular carrier signal, in Hz.



Output valuesValues of the switching function in off-state and on-state. The default is[-1 1].

672

Symmetrical PWM (3-Level)

Symmetrical PWM (3-Level)

Purpose Generate 3-level PWM signal using symmetrical triangular carriers


Description 3-level PWM generator with two symmetrical triangular carriers. The input mis the modulation index. The switching function s outputs either 1, 0 or -1. Ifthe modulation index is a vector the switching function is also a vector of thesame width.

The block can be used to control the 3-Level IGBT Converter (see page 460)or the ideal 3-Level Converter (see page 454). In these cases the modulationindex must have a width of 3 according to the number of inverter legs.

The figures below illustrate the Natural Sampling method. In the left figure,the negative carrier signal is obtained by flipping the positive carrier verti-cally around the time axis. In the right figure, the positive carrier is verti-cally shifted to construct the negative carrier. The latter technique reducesthe switching frequency and hence the semiconductor stress in three-phaseconverters.

−1

0

1

Switc

hing

fun

ctio

n

−1

0

1

Mod

ulat

ion

inde

x

Negative carrier flipped

1/f

Negative carrier shifted

1/f

673


The figures below illustrate the different Regular Sampling methods offeredby this block. With double edge sampling (left figure) the modulation indexis updated at the carrier tips and zero-crossings. With single edge sampling(right figure) the modulation index is updated only at the outer tips.

−1

0

1

Switc

hing

fun

ctio

n

−1

0

1

Double edge samplingM

odul

atio

n in

dex

1/f

Single edge sampling

1/f

Parameters SamplingSelect a sampling method. If you select Natural Sampling the carriersignal may begin with 0 or 1 at simulation start. The Regular Samplingmethod lets you choose between double edge and single edge sampling.

Carrier frequencyThe frequency f of the triangular carrier signals, in Hz.


Negative carrierSelect the phase shift between the negative and positive carrier signals.The negative carrier may be constructed from the positive carrier either byflipping or shifting.


674

Synchronous Machine (Round Rotor)


Purpose Smooth air-gap synchronous machine with main-flux saturation


Description This synchronous machine has one damper winding on the direct axis and twodamper windings on the quadrature axis of the rotor. Main flux saturation ismodeled by means of a continuous function.

The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motormode, otherwise in generator mode. All electrical variables and parametersare viewed from the stator side. In the component icon, phase a of the statorwinding and the positive pole of the field winding are marked with a dot.


Electrical System


Ψd = Lls id + Lm,d

(id + i′f + i′k,d

)Ψq = Lls iq + Lm,q

(iq + i′g + i′k,q

)The machine model offers two different implementations of the electrical sys-tem: a traditional rotor reference frame and a voltage-behind-reactance formu-lation.

Rotor Reference Frame Using Park’s transformation, the 3-phase circuitequations in physical variables are transformed to the dq rotor referenceframe. This results in constant coefficients in the stator and rotor equationsmaking the model numerically efficient. However, interfacing the dq modelwith the external 3-phase network may be difficult. Since the coordinatetransformations are based on voltage-controlled current sources, inductors andnaturally commutated devices such as diode rectifiers may not be directly con-nected to the stator terminals. In these cases, fictitious RC snubbers are re-quired to create the necessary voltages across the terminals.

675


Rs Lls

Lm,d

p∙ωm∙ Ψq

+

−

vd +

−

v'f

id

L'lfR'f

i'f

L'lk,dR'k,d i'k,d

d-axis

Rs Lls

Lm,q

p∙ωm∙ Ψq

+

−

vq

iq

L'lk,q2 R'k,q2

i'k,q2

L'lk,q1R'k,q1 i'k,q1

q-axis

Voltage behind Reactance This formulation allows for direct interfacing ofarbitrary external networks with the 3-phase stator terminals. The rotor dy-namics are expressed using explicit state-variable equations while the statorbranch equations are described in circuit form. However, due to the resultingtime-varying inductance matrices, this implementation is numerically less effi-cient than the traditional rotor reference frame.

In both implementations, the value of the main flux inductance Lm is not con-stant but depends on the main flux linkage Ψm as illustrated in the Ψm/im di-agram. For flux linkages Ψm far below the transition flux ΨT, the relationshipbetween flux and current is almost linear and determined by the unsaturatedmagnetizing inductance Lm,0. For large flux linkages the relationship is gov-erned by the saturated magnetizing inductance Lm,sat. ΨT defines the kneeof the transition between unsaturated and saturated main flux inductance.The tightness of the transition is defined with the form factor fT. If you do nothave detailed information about the saturation characteristic of your machine,fT = 1 is a good starting value. The function


676



∂Ψ/∂i = Lm,0

∂Ψ/∂i = Lm,sat

fT = 4

fT = 2

fT = 1

fT = 0.5

im

Ψm

ΨT

The model accounts for steady-state cross-saturation, i.e. the steady-statemagnetizing inductances along the d-axis and q-axis are functions of the cur-rents in both axes. For rotating reference frame formulation, the stator cur-rents, the field current and the main flux linkage are chosen as state vari-ables. With this choice of state variables, the representation of dynamic cross-saturation could be neglected without affecting the performance of the ma-chine. The computation of the time derivative of the main flux inductance wasnot required.



Te =3

2p (iq Ψd − id Ψq)

Mechanical System


ωm =1


θm = ωm

677


Parameters Most parameters for the Salient Pole Synchronous Machine (see page 680) arealso applicable to this round rotor machine. The following parameters are dif-ferent:

Unsaturated magnetizing inductanceThe unsaturated magnetizing inductance Lm,0. The value in henries (H) isreferred to the stator side.

Saturated magnetizing inductanceThe saturated magnetizing inductance Lm,sat, in H. If no saturation is tobe modeled, set Lm,sat = Lm,0.

Damper resistanceA three-element vector containing the damper winding resistance R′k,d,R′k,q1 and R′k,q2 of the d-axis and the q-axis. The values in ohms (Ω) arereferred to the stator side.

Damper leakage inductanceA three-element vector containing the damper winding leakage inductanceL′lk,d, L′lk,q1 and L′lk,q2 of the d-axis and the q-axis. The values in henries(H) are referred to the stator side.

Initial field/damper currentA two-element vector containing the initial currents if,0 in the field wind-ing and i′k,q1,0 in one of the damper windings in amperes (A). The currentin the damper winding is referred to the stator side.

Probe Signals Most probe signals for the Salient Pole Synchronous Machine (see page 680)are also available with this machine. Only the following probe signal is differ-ent:

Damper currentsThe damper currents i′k,d, i′k,q1 and i′k,q2 in the stationary reference framein A, referred to the stator side.

References D. C. Aliprantis, O. Wasynczuk, C. D. Rodriguez Valdez, “A voltage-behind-reactance synchronous machine model with saturation and arbitrary ro-tor network representation”, IEEE Transactions on Energy Conversion,Vol. 23, No. 2, June 2008.


678


E. Levi, “Modelling of magnetic saturation in smooth air-gap synchronousmachines”, IEEE Transactions on Energy Conversion, Vol. 12, No. 2,March 1997.

E. Levi, “Impact of cross-saturation on accuracy of saturated synchronousmachine models”, IEEE Transactions on Energy Conversion, Vol. 15,No. 2, June 2000.

679


Synchronous Machine (Salient Pole)

Purpose Salient pole synchronous machine with main-flux saturation


Description This synchronous machine has one damper winding each on the direct and thequadrature axis of the rotor. Main flux saturation is modeled by means of acontinuous function.

The machine operates as a motor or generator; if the mechanical torque hasthe same sign as the rotational speed the machine is operating in motormode, otherwise in generator mode. All electrical variables and parametersare viewed from the stator side. In the component icon, phase a of the statorwinding and the positive pole of the field winding are marked with a dot.

Electrical System

Rs Lls

Lm,d

p∙ωm∙ Ψq

+

−

vd +

−

v'f

id

L'lfR'f

i'f

L'lk,dR'k,d i'k,d

d-axis

Rs Lls

Lm,q

L'lk,q R'k,qp∙ωm∙ Ψq

+

−

vq

iq i'k,q

q-axis

680



Ψd = Lls id + Lm,d

(id + i′f + i′k,d

)Ψq = Lls iq + Lm,q

(iq + i′k,q

)The machine model offers two different implementations of the electrical sys-tem: a traditional rotor reference frame and a voltage-behind-reactance formu-lation.

Rotor Reference Frame Using Park’s transformation, the 3-phase circuitequations in physical variables are transformed to the dq rotor referenceframe. This results in constant coefficients in the stator and rotor equationsmaking the model numerically efficient. However, interfacing the dq modelwith the external 3-phase network may be difficult. Since the coordinatetransformations are based on voltage-controlled current sources, inductors andnaturally commutated devices such as diode rectifiers may not be directly con-nected to the stator terminals. In these cases, fictitious RC snubbers are re-quired to create the necessary voltages across the terminals.

Voltage behind Reactance This formulation allows for direct interfacing ofarbitrary external networks with the 3-phase stator terminals. The rotor dy-namics are expressed using explicit state-variable equations while the statorbranch equations are described in circuit form. However, due to the resultingtime-varying inductance matrices, this implementation is numerically less effi-cient than the traditional rotor reference frame.

In both implementations, the value of the main flux inductances Lm,d andLm,q are not constant but depend on the main flux linkage Ψm as illustratedin the Ψm/im diagram. In this machine model, the anisotropic factor

∂Ψ/∂i = Lm,0

∂Ψ/∂i = Lm,sat

fT = 4

fT = 2

fT = 1

fT = 0.5

im

Ψm

ΨT

681


m =√Lm,q,0/Lm,d,0 ≡

√Lm,q/Lm,d = const.

is assumed to be constant at all saturation levels. The equivalent magnetizingflux Ψm in an isotropic machine is defined as

Ψm =√

Ψ2m,d + Ψ2

m,q/m2 .

For flux linkages Ψm far below the transition flux ΨT, the relationship be-tween flux and current is almost linear and determined by the unsaturatedmagnetizing inductance Lm,0. For large flux linkages the relationship is gov-erned by the saturated magnetizing inductance Lm,sat. ΨT defines the kneeof the transition between unsaturated and saturated main flux inductance.The tightness of the transition is defined with the form factor fT. If you do nothave detailed information about the saturation characteristic of your machine,fT = 1 is a good starting value. The function



The model accounts for steady-state cross-saturation, i.e. the steady-statemagnetizing inductances along the d-axis and q-axis are functions of the cur-rents in both axes. For rotating reference frame formulation, the stator cur-rents, the field current and the main flux linkage are chosen as state vari-ables. With this choice of state variables, the representation of dynamic cross-saturation could be neglected without affecting the performance of the ma-chine. The computation of the time derivative of the main flux inductance wasnot required.



Te =3

2p (iq Ψd − id Ψq)

Mechanical System


ωm =1


682


θm = ωm

Parameters ModelImplementation in the rotor reference frame or as a voltage behind reac-tance.

Stator resistanceArmature or stator winding resistance Rs in ohms (Ω).

Stator leakage inductanceArmature or stator leakage inductance Lls in henries (H).

Unsaturated magnetizing inductanceA two-element vector containing the unsaturated stator magnetizing in-ductance Lm,d,0 and Lm,q,0 of the d-axis and the q-axis. The values in hen-ries (H) are referred to the stator side.

Saturated magnetizing inductanceThe saturated stator magnetizing inductance Lm,d,sat along the d-axis, inH. If no saturation is to be modeled, set Lm,d,sat = Lm,d,0.

Magnetizing flux at saturation transitionTransition flux linkage ΨT, in Vs, defining the knee between unsaturatedand saturated main flux inductance.

Tightness of saturation transitionForm factor fT defining the tightness of the transition between unsatu-rated and saturated main flux inductance. The default is 1.

Field resistanced-axis field winding resistance R′f in ohms (Ω), referred to the stator side.

Field leakage inductanced-axis field winding leakage inductance L′lf in henries (H), referred to thestator side.

Damper resistanceA two-element vector containing the damper winding resistance R′k,d andR′k,q of the d-axis and the q-axis. The values in ohms (Ω) are referred tothe stator side.

Damper leakage inductanceA two-element vector containing the damper winding leakage inductanceL′lk,d and L′lk,q of the d-axis and the q-axis. The values in henries (H) arereferred to the stator side.


683





Initial rotor positionInitial mechanical rotor angle θm,0 in radians. If θm,0 is an integer multipleof 2π/p the d-axis is aligned with phase a of the stator windings at simula-tion start.


Initial field currentInitial current if,0 in the field winding in amperes (A).

Initial stator fluxA two-element vector containing the initial stator flux Ψ′d,0 and Ψ′q,0 in therotor reference frame in Vs.


Field currentsThe excitation current if in A.

Damper currentsThe damper currents i′k,d and i′k,q in the stationary reference frame, in A.

Stator flux (dq)The stator flux linkages Ψd and Ψq in the stationary reference frame inVs.

Magnetizing flux (dq)The magnetizing flux linkages Ψm,d and Ψm,q in the stationary referenceframe in Vs.



684



ReferencesD. C. Aliprantis, O. Wasynczuk, C. D. Rodriguez Valdez, “A voltage-behind-

reactance synchronous machine model with saturation and arbitrary ro-tor network representation”, IEEE Transactions on Energy Conversion,Vol. 23, No. 2, June 2008.


E. Levi, “Saturation modelling in D-Q axis models of salient pole syn-chronous machines”, IEEE Transactions on Energy Conversion, Vol. 14,No. 1, March 1999.

E. Levi, “Impact of cross-saturation on accuracy of saturated synchronousmachine models”, IEEE Transactions on Energy Conversion, Vol. 15,No. 2, June 2000.

685


Synchronous Reluctance Machine

Purpose Synchronous reluctance machine configurable with lookup tables


Description This three-phase synchronous reluctance machine has a solid rotor withoutpermanent magnets. Saliency, saturation and cross-coupling are modeled bymeans of corresponding inductance lookup tables.

Two sets of one-dimensional inductance tables must be provided, one foreach axis (d, q), where the first curve corresponds to the case with no cross-saturation, and the second to the case with maximum cross-saturation.

0 5 10 15 20Current [A]

0

0.05

0.1

0.15

0.2

0.25

Indu

ctan

ce [H

]

Ld, iq = 0Ld, iq = maxLq, id = 0Lq, id = max

From this information, complete flux linkage and incremental inductance ta-bles are derived, using an interpolation method that ensures a conservativemagnetic circuit.

The machine can operate as either a motor or generator. If the mechanicaltorque has the same sign as the rotational speed, the machine is operating inmotor mode; otherwise it is in generator mode. In the component icon, phase ais marked with a dot.

686


Electrical System

The model utilizes the Non-Excited Synchronous Machine (see page 553) com-ponent. Use this component directly to model permanent magnet-assistedsynchronous reluctance machines, or if more complete flux/inductance datais available. The electrical system is realized by means of the Voltage BehindReactance (VBR) formulation and is therefore appropriate to simulate switch-ing dead-time and failure modes.



Te =3


Mechanical System


ωm =1


θm = ωm

ParametersGeneral


Stator leakage inductanceLeakage inductance of stator windings in henries (H). Stator leakage mustbe set to a non-zero value.


Initial stator currentsA two-element vector containing the initial stator currents ia,0 and ib,0 ofphase a and b in amperes (A). ic,0 is calculated assuming a neutral connec-tion.

687


Magnetizing Inductance

Current lookup vectord- and q-axis peak current vector serving as input to inductance lookupvectors. Must be a one dimensional vector with 3 or more elements, andmonotonically increasing, i.e. [0 ... id,max] and [0 ... iq,max]. The values are inamperes (A).

Ld (iq = 0) lookup vectord-axis inductance when there is no cross saturation (iq = 0). Must be thesame size as the Current lookup vector. The values are in henries (H).

Ld (iq = max) lookup vectord-axis inductance when there is maximum cross saturation (iq = iq,max).If no cross-saturated data is available this can be left empty. Must be thesame size as the Current lookup vector. The values are in henries (H).

Lq (id = 0) lookup vectorq-axis inductance in when there is no cross saturation (id = 0). Must bethe same size as the Current lookup vector. The values are in henries (H).

Lq (id = max) lookup vectorq-axis inductance when there is maximum cross saturation (id = id,max).If no cross-saturated data is available this can be left empty. Must be thesame size as the Current lookup vector. The values are in henries (H).

Generated table sizeUser-specified dimension to derive lookup tables for flux linkages andincremental inductances to be used in the underlying Non-Excited Syn-chronous Machine (see page 553) component.

If left empty, the specified data is used as-is.

Specifying a scalar value, n, will generate equally spaced, n-element d-and q-axis current vectors. The corresponding 2D lookup tables for fluxlinkage and incremental inductance are also generated. The dimensions ofthe generated tables must be 3 or more.

The size of the generated tables affect the model initialization and simu-lation speeds. A smaller size leads to faster model initialization and sim-ulation speeds, but lower resolution in the generated tables. A larger sizeincreases the resolution but adversely affects the model initialization andsimulation speeds. Care must be taken when configuring this parameter.

688


Current out of rangeConfigure to ignore, warn, warn and pause simulation, or generate errorand stop simulation if the d- or q-axis currents are outside the specifiedrange.

Co-energy plausibility checkThe change in co-energy (∆W) between zero and maximum cross satura-tion is calculated for both the d-axis (∆Wd) and q-axis (∆Wq). Configureto check if ∆Wd,q are within 5% or 10% of each other to validate the inputdata. This check can be disabled.

Mechanical





Probe Signals All probe signals for the Non-Excited Synchronous Machine (see page 553) arealso available with this machine.

ReferencesA. Vagati, M. Pastorelli, F. Scapino, G. Franceschini, “Impact of cross satura-

tion in synchronous reluctance motors of the transverse-laminated type”,IEEE Transactions on Industry Applications, Vol. 36, No. 4, Aug 2000.

A. Vagati, M. Pastorelli, G. Franceschini, “Effect of magnetic cross-coupling insynchronous reluctance motors”, Article in PCIM conference proceedings,June 1997.

689


Task Frame

Purpose Associate the enclosed components with a task in a multi-tasking environment

Library System

Description The Task Frame is used to configure a model for execution in a multi-taskingenvironment. To use a Task Frame, you must first configure a set of tasks onthe Scheduling tab of the Coder Options dialog (see “Scheduling” on page272). Once you have done this, you can double click on the label to open theparameter dialog and choose the desired task from the list.

The execution of all components inside the frame will be scheduled in the se-lected task. Multiple Task Frames can reference the same task; in this caseall components inside these frames will be scheduled in the same task.

If the frame contains a Subsystem (see page 662), the task will also be as-signed to the components in the sub-schematic; however, you can override thismechanism by placing Task Frames in the sub-schematic.

To move a Task Frame, press the left mouse button on the label or on anedge and drag the frame to the desired location. To change the size of a TaskFrame, select it, then drag one of the selection handles.

690

Thermal Capacitor

Thermal Capacitor

Purpose Thermal capacitance of piece of material

Library Thermal

Description This component provides an ideal thermal capacitance between its two ther-mal ports or between the thermal port and the thermal reference. See sec-tion “Configuring PLECS” (on page 45) for information on how to change thegraphical representation of thermal capacitors.

Parameters CapacitanceThe value of the capacitor, in J/K. All finite positive and negative valuesare accepted, including 0. The default is 1.

Initial temperatureThe initial temperature difference between the thermal ports or betweenthe thermal port and thermal reference at simulation start, in kelvin (K).The default is 0. If left blank or if the value is nan, PLECS will initializethe value based on a thermal “DC” analysis, see “Temperature Initializa-tion” (on page 125).

Probe Signal TemperatureThe temperature difference measured across the capacitance. A positivevalue is measured when the temperature at the terminal marked with “+”is greater than the temperature at the unmarked terminal.

691


Thermal Chain

Purpose Thermal impedance implemented as RC chain

Library Thermal

Description This component implements a thermal RC chain of variable length. Using theelements of the vectors provided in the component parameters Thermal re-sistances and Thermal capacitances a subsystem is built as shown below.The thermal capacitor C1 is connected to the terminal marked with a dot.

R1

C1 Cn

RnR2

C2...

Parameters Thermal resistancesA vector containing the values of the thermal resistors R1 . . . Rn, in K/W.

Thermal capacitancesA vector containing the values of the thermal capacitors C1 . . . Cn, in J/K.

Initial temperatureA scalar value specifying the initial temperature of all thermal capaci-tors at simulation start, in kelvin (K). The default is 0. If left blank or ifthe value is nan, PLECS will initialize the value based on a thermal “DC”analysis, see “Temperature Initialization” (on page 125).

692

Thermal Ground

Thermal Ground

Purpose Connect to common reference temperature

Library Thermal

Description The Thermal Ground implements a connection to the thermal reference.

693


Thermal Model Settings

Purpose Configure settings for an individual thermal model.

Library Thermal

Description The Thermal Model Settings block lets you configure parameter settings thatinfluence the code generation for a particular thermal system, see also “CodeGeneration for Physical Systems” (on page 263).

The block affects the thermal system that it is attached to by its terminal. Atmost one Model Settings block may be attached to an individual state-spacesystem. All thermal models within an atomic subsystem are combined into asingle common state-space system.

Parameters Matrix coding styleThis setting allows you to specify the format used for storing the state-space matrices for a physical model. When set to sparse, only the non-zero matrix entries and their row and column indices are stored. Whenset to full, matrices are stored as full m × n arrays. When set to full(inlined), the matrices are additionally embedded in helper functions,which may enable the compiler to further optimize the matrix-vector-multiplications at the cost of increased code size.

694

Thermal Port

Thermal Port

Purpose Add thermal connector to subsystem

Library Thermal

Description Thermal ports are used to establish thermal connections between a schematicand the subschematic of a subsystem (see page 662). If you copy a ThermalPort block into the schematic of a subsystem, a terminal will be created on thesubsystem block. The name of the port block will appear as the terminal label.If you choose to hide the block name by unselecting the show button in thedialog box, the terminal label will also disappear.

Terminals can be moved around the edges of the subsystem by holding downthe Shift key or by using the middle mouse button.

Thermal Ports in a Top-Level Schematic

In PLECS Blockset, if a Thermal Port is placed in a top-level schematic, thePLECS Circuit block in the Simulink model will show a corresponding ther-mal terminal, which may be connected with other thermal terminals of thesame or a different PLECS Circuit block. The Thermal Port is also assigned aunique physical port number. Together with the parameter Location on cir-cuit block the port number determines the position of the thermal terminalof the PLECS Circuit block.

For compatibility reasons you can also place an Thermal Port in a top-levelschematic in PLECS Standalone. However, since there is no parent system toconnect to, such a port will act like an isolated node.

Note Thermal Port blocks may not be used in schematics that contain Ambi-ent Temperature blocks (see page 334).

Parameter Port numberIf a Thermal Port is placed in a top-level schematic in PLECS Blockset,this parameter determines the position, at which the corresponding termi-nal appears on the PLECS Circuit block.

695


Location on circuit blockIf a Thermal Port is placed in a top-level schematic in PLECS Blockset,this parameter specifies the side of the PLECS Circuit block on which thecorresponding terminal appears. By convention, left refers to the sideon which also input terminals are shown and right refers to the side onwhich also output terminals are shown.

696

Thermal Resistor

Thermal Resistor

Purpose Thermal resistance of piece of material

Library Thermal

Description This component provides an ideal one-dimensional thermal resistor betweenits two thermal ports. See section “Configuring PLECS” (on page 45) for in-formation on how to change the graphical representation of thermal resistors.

Parameter Thermal resistanceThe resistance in K/W. All positive and negative values are accepted, in-cluding 0 and inf (∞). The default is 1.

697


Thermometer

Purpose Output measured temperature as signal

Library Thermal

Description

K K

The Thermometer measures the temperature difference between its two ther-mal ports or between the thermal port and thermal reference and provides itas a signal at the output of the component. The output signal can be madeaccessible in Simulink with a Output block (see page 641) or by dragging thecomponent into the dialog box of a Probe block.

Probe Signal Measured temperatureThe measured temperature in kelvin (K).

698

Thyristor

Thyristor

Purpose Ideal thyristor (SCR) with optional forward voltage and on-resistance


Description The Thyristor can conduct current only in one direction—like the diode. In ad-dition to the diode it can be controlled by an external gate signal. The thyris-tor is modeled by an ideal switch that closes when the voltage between an-ode and cathode is positive and a non-zero gate signal is applied. The switchremains closed until the current becomes negative. A thyristor cannot beswitched off via the gate.


Forward voltageAdditional dc voltage Vf in volts (V) between anode and cathode when thethyristor is conducting. The default is 0.


Initial conductivityInitial conduction state of the thyristor. The thyristor is initially blockingif the parameter evaluates to zero, otherwise it is conducting.



Probe Signals Thyristor voltageThe voltage measured between anode and cathode.

699


Thyristor currentThe current through the thyristor flowing from anode to cathode.

Thyristor gate signalThe gate input signal of the thyristor.

Thyristor conductivityConduction state of the internal switch. The signal outputs 0 when thethyristor is blocking, and 1 when it is conducting.

Thyristor junction temperatureTemperature of the first thermal capacitor in the equivalent Cauer net-work.

Thyristor conduction lossContinuous thermal conduction losses in watts (W). Only defined if thecomponent is placed on a heat sink.

Thyristor switching lossInstantaneous thermal switching losses in joules (J). Only defined if thecomponent is placed on a heat sink.

700

Thyristor Rectifier/Inverter

Thyristor Rectifier/Inverter

Purpose 3-phase thyristor rectifier/inverter


Description Implements a three-phase rectifier or inverter based on the Thyristor model(see page 699). The gate input is a vector of six signals ordered according tothe natural sequence of commutation. This sequence corresponds to the num-bering of the thyristors in the electrical circuits below. The rectifier is shownon the left side, the inverter on the right:

Thy2

a

b

c

Thy1

Thy4 Thy6

Thy3 Thy5 Thy6Thy4

Thy1

a

b

c

Thy2

Thy5Thy3

Parameters For a description of the parameters see the documentation of the Thyristor (onpage 699).

Probe Signals The thyristor converters provide six probe signals, each a vector containingthe appropriate quantities of the six individual thyristors: voltage, current,conduction loss and switching loss. The vector elements are ordered accordingto the natural sequence of commutation.

701


Thyristor with Reverse Recovery

Purpose Dynamic thyristor (SCR) model with reverse recovery


Description This component is a behavioral model of a thyristor which reproduces the ef-fect of reverse recovery. The effect can be observed when a forward biasedthyristor is rapidly turned off. It takes some time until the excess chargestored in the thyristor during conduction is removed. During this time thethyristor represents a short circuit instead of an open circuit, and a negativecurrent can flow through the thyristor. The thyristor finally turns off when thecharge is swept out by the reverse current and lost by internal recombination.The same effect is modeled in the Diode with Reverse Recovery (see page 390)and described there in detail.

Note

• Due to the small time-constant introduced by the turn-off transient a stiffsolver is recommended for this device model.

• If multiple thyristors are connected in series the off-resistance may not beinfinite.

Parameters Forward voltageAdditional dc voltage Vf in volts (V) between anode and cathode when thethyristor is conducting. The default is 0.


Off-resistanceThe resistance Roff of the blocking device, in ohms (Ω). The default is 1e6.This parameter may be set to inf unless multiple thyristors are connectedin series.

Continuous forward currentThe continuous forward current If0 under test conditions.

Current slope at turn-offThe turn-off current slope dIr/dt under test conditions.

702

Thyristor with Reverse Recovery

Reverse recovery timeThe turn-off time trr under test conditions.

Peak recovery currentThe absolute peak value of the reverse current Irrm under test conditions.

Reverse recovery chargeThe reverse recovery charge Qrr under test conditions. If both trr and Irrmare specified, this parameter is ignored.

LrrThis inductance acts as a probe measuring the di/dt. It should be set to avery small value. The default is 10e-10.

Probe Signals Thyristor voltageThe voltage measured between anode and cathode.

Thyristor currentThe current through the thyristor flowing from anode to cathode.

Thyristor conductivityConduction state of the internal switch. The signal outputs 0 when thethyristor is blocking, and 1 when it is conducting.

ReferencesA. Courtay, "MAST power diode and thyristor models including automatic

parameter extraction", SABER User Group Meeting Brighton, UK, Sept.1995.

703


To File

Purpose Write time stamps and signal values to a file.

Library System

Description While a simulation is running, the To File block writes the time stamps andthe values of its input signals to a file. The file format can be either a text filewith comma separated values (csv) or a MATLAB data file (mat). CSV filescan be imported by all common spreadsheet tools like Microsoft Excel.In a csv file a new row is appended for each time step. When writing to aMATLAB file the resulting data contains a column for each time step.The first value for each data record is the simulation time of the current simu-lation step. The value is followed by the signal values of the input signal.

Parameters FilenameThe name of the data file to write to. Files will be stored relative to themodel directory unless an absolute file path is given. The data file will becreated if it doesn’t exist. An existing file of the same name will be over-written.If you choose the option literal, the string that you enter is taken literallyas the basename of the data file. So, if you enter e.g. MyFile, the file namewill be MyFile.csv or MyFile.mat.If you choose the option evaluate, the string that you enter is inter-preted as a MATLAB/Octave expression that must yield a string, whichin turn is taken as the basename of the data file. So, if you enter e.g.[’MyFile’ num2str(index)] and the current workspace contains avariable index with a value of 2, the file name will be MyFile2.csv orMyFile2.mat.

File typeThe file format to use for the data file. The file can be written as a text filewith comma separated values (csv) or as a MATLAB data file (mat).

Write signal namesControls whether the signal names are written to the file as the first rowbefore the data records. This parameter is shown only if the File type pa-rameter is set to csv.

Sample timeFor positive values the input data will be written to the data file once inthe given simulation interval. If the value is set to 0 the input data is

704

To File

written to the data file in each simulation step. See also the Discrete-Periodic sample time type in section “Sample Times” (on page 38).

705


Torque (Constant)

Purpose Generate constant torque


Description The Constant Torque generates a constant torque between its two flanges. Thedirection of a positive torque is indicated by the arrow.

Note A torque source may not be left unconnected or connected in series witha spring or any other torque source.


TorqueThe magnitude of the torque, in Newton meters (Nm). The default value is1.

Probe Signals TorqueThe generated torque, in Newton meters (Nm).

SpeedThe speed of the flange that the arrow points to with respect to the otherflange, in rad

s .

706

Torque (Controlled)

Torque (Controlled)

Purpose Generate variable torque


Description The Controlled Torque generates a variable torque between its two flanges.The direction of a positive torque is indicated by the arrow. The momentarytorque is determined by the signal fed into the input of the component.

Note A torque source may not be left unconnected or connected in series witha spring or any other torque source.



TorqueThe generated torque, in Newton meters (Nm).

SpeedThe speed of the flange that the arrow points to with respect to the otherflange, in rad

s .

707


Torque Sensor

Purpose Output measured torque as signal


Description The Torque Sensor measures the torque between its two flanges and pro-vides it as a signal at the output of the component. A torque flow from theunmarked flange towards the flange marked with a dot is considered positive.

Note A torque sensor is ideally rigid. Hence, if multiple torque sensors areconnected in parallel the torque measured by an individual sensor is undefined.This produces a run-time error.

Parameter Second flangeControls whether the second flange is accessible or connected to the rota-tional reference frame.

Probe Signal TorqueThe measured torque, in Newton meters (Nm).

708

Torsion Spring

Torsion Spring

Purpose Ideal torsion spring


Description The Torsion Spring models an ideal linear spring in a rotational system de-scribed with the following equations:

τ = −c ·∆θ∆θ = θ − θ0

d

dtθ = ω

where τ is the torque flow from the unmarked towards the marked flange, θis the angle of the marked flange with respect to the unmarked one, and θ0 isthe equilibrium flange displacement.

Note An torsion spring may not be connected in series with a torque source.Doing so would create a dependency between an input variable (the sourcetorque) and a state variable (the spring torque) in the underlying state-spaceequations.

Parameters Spring constantThe spring rate or stiffness c, in Nm

rad .

Equilibrium (unstretched) displacementThe displacement θ0 between the two flanges of the unloaded spring, inradians.

Initial deformationThe initial deformation (torsion) ∆θ0 of the spring, in radians.

Probe Signals TorqueThe spring torque τ , in Newton meters (Nm).

DeformationThe spring deformation ∆θ, in radians.

709


Total Harmonic Distortion

Purpose Calculate total harmonic distortion (THD) of input signal


Description This block calculates the total harmonic distortion of a periodic input signal.The sample time and the fundamental frequency can be specified. The THD isdefined as:

THD =

√√√√ ∑ν≥2

U2ν

U21

=

√U2

rms − U20 − U2

1

U21

where Uν is the RMS value of the νth harmonic of the input signal and Urms isits overall RMS value.

Parameters Sample timeThe time interval between samples. See also the Discrete-Periodic sam-ple time type in section “Sample Times” (on page 38). If a sample timeof 0 is specified, a continuous implementation based on the Moving Aver-age block (see page 545) is active. The Discrete-Periodic implementationcan potentially force a variable-step solver to take small integration steps.This may slow down the simulation. The default value of this parameter is0.


710

Transfer Function

Transfer Function

Purpose Model linear time-invariant system as transfer function


Description The Transfer Function models a linear time-invariant system that is ex-pressed in the Laplace domain in terms of the argument s:

Y (s)

U(s)=nns

n + · · ·+ n1s+ n0

dnsn + · · ·+ d1s+ d0

The transfer function is displayed in the block if it is large enough, otherwisea default text is shown. To resize the block, select it, then drag one of its se-lection handles.

Parameters Numerator coefficientsA vector of the s term coefficients [nn . . . n1, n0] for the numerator, writtenin descending order of powers of s. For example, the numerator s3 + 2swould be entered as [1,0,2,0].The output of the Transfer Function is vectorizable by entering a matrixfor the numerator.

Denominator coefficientsA vector of the s term coefficients [dn . . . d1, d0] for the denominator, writtenin descending order of powers of s.

Note The order of the denominator (highest power of s) must be greater thanor equal to the order of the numerator.

Initial conditionThe initial condition vector of the internal states of the Transfer Functionin the form [xn . . . x1, x0]. The initial conditions must be specified for thecontroller normal form, depicted below for the the transfer function

Y (s)

U(s)=n2s

2 + n1s+ n0

d2s2 + d1s+ d0

711


a1

a0

a2

b0

b1

b21/s

++

++1/s+−

++

x1 x0 Y(s)U(s)

where

bi = didn

for i < n

bn = 1dn

ai = ni − nndidn

for i < n

an = nn

For the normalized transfer function (with nn = 0 and dn = 1) this simpli-fies to bi = di and ai = ni.



712

Transformation 3ph->RRF

Transformation 3ph->RRF

Purpose Transform 3-phase signal to rotating reference frame


Description This block transforms a three-phase signal [xa xb xc] into a two-dimensionalvector [yd yq] in a rotating reference frame. The first input is the three-phasesignal. The second input is the rotation angle ϕ of the rotating referenceframe. ϕ is given in radians.

yd

yq

=2

3

cosϕ − sinϕ

cos (ϕ− 120) − sin (ϕ− 120)

cos (ϕ+ 120) − sin (ϕ+ 120)

T

·

xa

xb

xc

Any zero-sequence component in the three-phase signals is discarded.

713


Transformation 3ph->SRF

Purpose Transform 3-phase signal to stationary reference frame


Description This block transforms a three-phase signal [xa xb xc] into a two-dimensionalvector [yα yβ ] in the stationary reference frame:

yαyβ

=

2

3−1

3−1

3

01√3− 1√

3

·xa

xb

xc

Any zero-sequence component in the three-phase signals is discarded.

714

Transformation RRF->3ph

Transformation RRF->3ph

Purpose Transform vector in rotating reference frame into 3-phase signal


Description This block transforms a two-dimensional vector [xd xq] in a rotating referenceframe into a three-phase signal [ya yb yc]. The first input of the block is thevector [xd xq]. The second input is the rotation angle ϕ of the rotating refer-ence frame. ϕ is given in radians.

ya

yb

yc

=

cosϕ − sinϕ

cos (ϕ− 120) − sin (ϕ− 120)

cos (ϕ+ 120) − sin (ϕ+ 120)

·xd

xq

The resulting three-phase signal does not have any zero-sequence component.

715


Transformation RRF->SRF

Purpose Transform vector from rotating to stationary reference frame


Description This block transforms a two-dimensional vector [xd xq] from a rotating refer-ence frame into a vector [yα yβ ] in the stationary reference frame. The first in-put of the block is the vector [xd xq]. The second input is the angle ϕ betweenthe rotating and the stationary frame. ϕ is given in radians.

yαyβ

=

cosω1t − sinω1t

sinω1t cosω1t

·xd

xq

716

Transformation SRF->3ph

Transformation SRF->3ph

Purpose Transform vector in stationary reference frame into 3-phase signal


Description This block transforms a two-dimensional vector [xα xβ ] in the stationary refer-ence frame into a three-phase signal [ya yb yc].

ya

yb

yc

=

1 0

−1

2

√3

2

−1

2−√

3

2

·

xαxβ

The resulting three-phase signal does not have any zero-sequence component.

717


Transformation SRF->RRF

Purpose Transform vector from stationary to rotating reference frame


Description This block transforms a two-dimensional vector [xα xβ ] in the stationary refer-ence frame into a vector [yd yq] in a rotating reference frame. The first inputis the vector [xα xβ ]. The second input is the angle ϕ between the rotating andthe stationary frame. ϕ is given in radians.

yd

yq

=

cosω1t sinω1t

− sinω1t cosω1t

·xαxβ

718

Transformers (3ph, 2 Windings)


Purpose 3-phase transformers in Yy, Yd, Yz, Dy, Dd and Dz connection


Description This group of components implements two-winding, three-phase transformerswith a three-leg or five-leg core. The transformer core is assumed symmetri-cal, i.e. all phases have the same parameters. Depending on the chosen com-ponent , the windings are wired in star (Y) or delta (D) connection on the pri-mary side. On the secondary side, the windings are either in star (y), delta (d)or zig-zag (z) connection. Star and zig-zag windings have an accessible neutralpoint.

The phase angle difference between the primary and the secondary side canbe chosen. For Yy and Dd connections, the phase lag must be an integer mul-tiple of 60 . For Yd and Dy connections the phase lag must be an odd integermultiple of 30 . The phase lag of zig-zag windings can be chosen arbitrarily.The windings of the secondary side are allocated to the transformer legs ac-cording to the phase lag. Please note that the phase-to-phase voltage of deltawindings is by a factor of 1/

√3 lower than the voltage of star or delta wind-

ings if the number of turns are equal.

Lm,0

1

im

Ψm

im

(1) im

(2) im

(3)

Ψm

(1)

Ψm

(2)

Ψm

(3)

The core saturation characteristic of the transformer legs is piece-wise linearand is modeled using the Saturable Inductor (see page 622). The magnetiz-ing current im and flux Ψm value pairs are referred to the primary side. Tomodel a transformer without saturation enter 1 as the magnetizing current

719


values and the desired magnetizing inductance Lm as the flux values. A stiffSimulink solver is recommended if the iron losses are not negligible, i.e. Rfe isnot infinite.

Parameters Leakage inductanceA two-element vector containing the leakage inductance of the primaryside L1 and the secondary side L2. The inductivity is given in henries (H).

Winding resistanceA two-element vector containing the resistance of the primary winding R1

and the secondary winding R2, in ohms (Ω).

No. of turnsA two-element vector containing the number of turns of the primary wind-ing n1 and the secondary winding n2.




No. of core legsThe number of legs of the transformer core. This value may either be 3 or5.

Phase lag of secondary sideThe phase angle between the primary side and the secondary side, in de-grees. Unless the secondary side is in zig-zag connection, the angle canonly be varied in steps of 60 .

Initial currents wdg. 1A vector containing the initial currents on the primary side i1,a, i1,b and,if the winding has a neutral point, i1,c. The currents are given in amperes(A) and considered positive if flowing into the transformer. The default is[0 0 0].

720


Initial currents wdg. 2A vector containing the initial currents on the secondary side i2,a, i2,b and,if the winding has a neutral point, i2,c. The currents are given in amperes(A) and considered positive if flowing into the transformer. The default is[0 0 0].

721



Purpose Three-phase transformers in Ydy and Ydz connection.


Description This group of components implements three-winding, three-phase transform-ers with a three-leg or five-leg core. The transformer core is assumed symmet-rical, i.e. all phases have the same parameters. The primary winding is in starconnection with an accessible neutral point and the secondary winding is indelta connection. Depending on the chosen component, the tertiary winding iswired either in star (y) or zig-zag (z) connection.

The phase angle difference between the primary and the secondary side mustbe an odd integer multiple of 30 . If the tertiary winding is in star connectionthe phase lag against the primary side must be an integer multiple of 60 . Ifit is in zig-zag connection, the phase lag can be chosen arbitrarily. The wind-ings of the secondary and tertiary side are allocated to the transformer legsaccording to the phase lags. Please note that the phase-to-phase voltage ofdelta windings is by a factor of 1/

√3 lower than the voltage of star or delta

windings if the number of turns are equal.

Lm,0

1

im

Ψm

im

(1) im

(2) im

(3)

Ψm

(1)

Ψm

(2)

Ψm

(3)

The core saturation characteristic of the transformer legs is piece-wise linearand is modeled using the Saturable Inductor (see page 622). The magnetiz-ing current im and flux Ψm value pairs are referred to the primary side. Tomodel a transformer without saturation enter 1 as the magnetizing currentvalues and the desired magnetizing inductance Lm as the flux values. A stiff

722


Simulink solver is recommended if the iron losses are not negligible, i.e. Rfe isnot infinite.

Parameters Leakage inductanceA three-element vector containing the leakage inductance of the primaryside L1, the secondary side L2 and the tertiary side L3. The inductivity isgiven in henries (H).

Winding resistanceA three-element vector containing the resistance of the primary windingR1, the secondary winding R2 and the tertiary winding R3, in ohms (Ω).

No. of turnsA three-element vector containing the number of turns of the primarywinding n1, the secondary winding n2 and the tertiary winding n3.




No. of core legsThe number of legs of the transformer core. This value may either be 3 or5.

Phase lag of secondary sideThe phase angle between the primary side and the secondary side, in de-grees. Unless the secondary side is in zig-zag connection, the angle canonly be varied in steps of 60 .

Initial currents wdg. 1A vector containing the initial currents on the primary side i1,a, i1,b andi1,c. The currents are given in amperes (A) and considered positive if flow-ing into the transformer. The default is [0 0 0].

723


Initial currents wdg. 2A vector containing the initial currents on the secondary side i2,a and i2,b.The currents are given in amperes (A) and considered positive if flowinginto the transformer. The default is [0 0 0].

Initial currents wdg. 3A vector containing the initial currents on the tertiary side i3,a, i3,b andi3,c. The currents are given in amperes (A) and considered positive if flow-ing into the transformer. The default is [0 0 0].

724

Translational Algebraic Component

Translational Algebraic Component

Purpose Define an algebraic constraint in terms of force and speed


Description The Translational Algebraic Component enforces an arbitrary algebraic con-straint involving force and speed.

The output signal “v” measures the speed of the marked flange with respect tothe unmarked one. The output signal “F” measures the force flow from the un-marked towards the marked flange. The two output signals must affect the in-put signal “0” by means of a direct feedthrough path. The component ensuresthat the input signal is zero at all times.

The direct feedthrough path defines a function f(v, F ), which in turn implic-itly determines the speed-force characteristic of the component through theconstraint f(v, F ) = 0. For instance, the choice f(v, F ) := F + D · v causesthe Translational Algebraic Component to act as a Translational Damper (seepage 729) with damping constant D.

The Translational Algebraic Component offers no direct way to specify an ini-tial displacement. In case you need to do so, place a Translational Damperwith zero damping constant in parallel to the component and set the initialdisplacement property thereof.

By way of illustration, the following schematic shows a possible implementa-tion of a translational damper with variable damping constant and prescribedinitial displacement:

725


Note The Translational Algebraic Component creates an algebraic loop. Seesection “Block Sorting” (on page 31) for more information on algebraic loops.

Probe Signals Component forceThe force flow from the unmarked towards the marked flange.

Component speedThe speed of the marked flange with respect to the unmarked one.


726

Translational Backlash

Translational Backlash

Purpose Ideal translational backlash


Description The Translational Backlash models an ideal symmetrical, two-sided Hard Stop(see page 732) in a translational system, which restricts the relative displace-ment of the two flanges between an upper and lower limit of ± b

2 . While thedisplacement is within the limits, no force is transmitted. When the displace-ment hits either limit, the flanges become rigidly connected until the trans-mitted force reverses.

Parameters Total backlashThe total permitted displacement b between the flanges, in meters.

Initial displacementThe initial displacement of the flanges, in meters. May be specified in or-der to provide proper initial conditions if absolute positions are measuredanywhere in the system. Otherwise, this parameter can be left blank.

Probe Signals ForceThe transmitted force flowing from the unmarked to the marked flange, inNewton (N).

DisplacementThe displacement of the marked flange with respect to the unmarkedflange, in meters (m).


727


Translational Clutch

Purpose Ideal translational clutch


Description The Translational Clutch models an ideal clutch in a translational system.When engaged, it makes an ideally rigid connection between the flanges; whendisengaged, it transmits zero force. The clutch engages when the input signalbecomes non-zero and disengages when the input signal becomes zero.

Parameters Initial stateThe initial state (engaged/disengaged) of the clutch.


728

Translational Damper

Translational Damper

Purpose Ideal viscous translational damper


Description The Translational Damper models an ideal linear damper in a translationalsystem described with the following equations:

F = −D · v

where F is the force flow from the unmarked towards the marked flange and vis the speed of the marked flange with respect to the unmarked one.

Parameters Damper constantThe damping (viscous friction) constant D, in Ns

m .


729


Translational Friction

Purpose Ideal translational stick/slip friction


Description The Translational Friction models any combination of static, Coulomb and vis-cous friction between two flanges in a translational system. While the compo-nent is stuck, it exerts whatever force is necessary in order to maintain zerorelative speed between the flanges, up to the limit of the breakaway force Fbrk.When the breakaway force is exceeded, the flanges begin sliding against eachother, and the component exerts a force that consists of the Coulomb frictionforce FC and a speed-dependent viscous friction force cv · v.

The figure below shows the speed/force characteristic and the state chart ofthe component. Note that the friction force is opposed to the movement, hencethe negative sign.

Sticking

Slidingbackward

Slidingforward

F > Fbrk F < -Fbrk

v > 0 v < 0

Fbrk

v

-F

FCcv⋅v

Parameters Breakaway friction forceThe maximum magnitude of the stiction force Fbrk, in Newton. Must begreater than or equal to zero.

Coulomb friction forceThe magnitude of the (constant) Coulomb friction force FC, in Newton.Must be greater than or equal to zero and less than or equal to the break-away friction force.

Viscous friction coefficientThe proportionality coefficient cv that determines the speed dependent vis-cous friction force, in Ns

m .

730

Translational Friction

Probe Signals ForceThe transmitted force F flowing from the unmarked to the marked flange,in Newton (N).

SpeedThe speed v of the marked flange with respect to the unmarked flange, inms .

StateThe internal state of the component: -1 sliding backward, 0 stuck, +1 slid-ing forward.

731


Translational Hard Stop

Purpose Ideal translational hard stop


Description The Translational Hard Stop models an ideal one- or two-sided hard stop ina translational system, which restricts the relative displacement of the twoflanges between an upper and lower limit. While the displacement is withinthe limits, no force is transmitted. When the displacement hits either limit,the displacement is clamped at the limit and the flanges become rigidly con-nected until the transmitted force reverses.

The figure below shows the displacement/force characteristic and the statechart of the component.

Insidelimits

Lowerlimit

Upperlimit

x < xmin

x := xmin x := xmax

x > xmax

F < 0 F > 0

F := 0xmin xmax x

F

Parameters Upper limitThe maximum displacement xmax between the flanges, in meters. Set toinf to disable this limit.

Lower limitThe minimum displacement xmin between the flanges, in meters. Set to-inf to disable this limit.

Initial displacementThe initial displacement of the flanges, in meters.

Probe Signals ForceThe transmitted force F flowing from the unmarked to the marked flange,in Newton (N).

732

Translational Hard Stop

DisplacementThe displacement x of the marked flange with respect to the unmarkedflange, in meters (m).


733


Translational Model Settings

Purpose Configure settings for an individual mechanical model.

Library Mechanical / Translational / Model Settings

Description The Translational Model Settings block lets you configure parameter settingsthat influence the code generation for a particular mechanical system, see also“Code Generation for Physical Systems” (on page 263).

The block affects the mechanical system that it is attached to by its transla-tional terminal. At most one Model Settings block may be attached to an in-dividual state-space system. A mechanical model can be split into multiplestate-space systems if the underlying model equations are fully decoupled.Note that a rotational system and a translational system that are coupled e.g.with a Rack and Pinion (see page 592) have coupled model equations. See alsothe options Enable state-space splitting and Display state-space split-ting in the “Simulation Parameters” (on page 107).

Parameters Switching algorithmThis parameter allows you two choose between two algorithms to deter-mine the clutch states in the generated code. See “Switching Algorithm”(on page 265) for details.


TopologiesThis parameter lets you specify a matrix containing the combinations ofclutch states, for which code should be generated, see also “Reducing theCode Size” (on page 264). The columns represent the clutch elements ofthe physical model and each row represents one combination of clutchstates (zero for an open clutch and non-zero for a closed clutch).


734

Translational Port

Translational Port

Purpose Add translational flange to subsystem


Description Translational ports are used to establish translational mechanical connectionsbetween a schematic and the subschematic of a subsystem (see page 662). Ifyou copy a Translational Port block into the schematic of a subsystem, a ter-minal will be created on the subsystem block. The name of the port block willappear as the terminal label. If you choose to hide the block name by unse-lecting the show name option in the block menu, the terminal label will alsodisappear.Terminals can be moved around the edges of the subsystem by holding downthe Shift key while dragging the terminal with the left mouse button or byusing the middle mouse button.

Translational Ports in a Top-Level Schematic

In PLECS Blockset, if a Translational Port is placed in a top-level schematic,the PLECS Circuit block in the Simulink model will show a correspondingtranslational terminal, which may be connected with other translational ter-minals of the same or a different PLECS Circuit block. The Translational Portis also assigned a unique physical port number. Together with the parameterLocation on circuit block the port number determines the position of thetranslational terminal of the PLECS Circuit block.For compatibility reasons you can also place an Translational Port in a top-level schematic in PLECS Standalone. However, since there is no parent sys-tem to connect to, such a port will act like an isolated node.

Parameter Port numberIf a Translational Port is placed in a top-level schematic in PLECS Block-set, this parameter determines the position, at which the correspondingterminal appears on the PLECS Circuit block.

Location on circuit blockIf a Translational Port is placed in a top-level schematic in PLECS Block-set, this parameter specifies the side of the PLECS Circuit block on whichthe corresponding terminal appears. By convention, left refers to the sideon which also input terminals are shown, and right refers to the side onwhich also output terminals are shown.

735


Translational Reference

Purpose Connect to common translational reference frame


Description The Translational Reference implements a connection to the translational ref-erence frame that has a fixed absolute position of zero.

736

Translational Speed (Constant)

Translational Speed (Constant)

Purpose Maintain constant translational speed


Description The Constant Translational Speed maintains a constant linear speed betweenits two flanges regardless of the force required. The speed is considered posi-tive at the flange marked with a “+”.

Note A speed source may not be short-circuited or connected in parallel withother speed sources, nor may a speed source directly drive a mass.


SpeedThe magnitude of the speed, in m

s . The default value is 1.

Probe Signals ForceThe generated force flowing from the unmarked flange to the markedflange, in Newton (N).

SpeedThe speed, in m

s .

737


Translational Speed (Controlled)

Purpose Maintain variable translational speed


Description The Controlled Translational Speed maintains a variable linear speed betweenits two flanges regardless of the force required. The speed is considered posi-tive at the flange marked with a “+”. The momentary speed is determined bythe signal fed into the input of the component.

Note A speed source may not be short-circuited or connected in parallel withother speed sources, nor may a speed source directly drive a mass.



Probe Signals ForceThe generated force flowing from the unmarked flange to the markedflange, in Newton (N).

SpeedThe speed, in m

s .

738

Translational Speed Sensor

Translational Speed Sensor

Purpose Output measured linear speed as signal


Description The Translational Speed Sensor measures the linear speed of the flangemarked with a dot with respect to the other flange.

Note Speed and position sensors are ideally compliant. Hence, if multiplespeed or position sensors are connected in series the speed or position measuredby an individual sensor is undefined. This produces a run-time error.

Parameter Second flangeControls whether the second flange is accessible or connected to the trans-lational reference frame.

Probe Signal SpeedThe measured speed, in m

s .

739


Translational Spring

Purpose Ideal translational spring


Description The Translational Spring models an ideal linear spring in a translational sys-tem described with the following equations:

F = −c ·∆x∆x = x− x0

d

dtx = v

where F is the force flow from the unmarked towards the marked flange, x isthe displacement of the marked flange with respect to the unmarked one, andx0 is the equilibrium displacement.

Note An translational spring may not be connected in series with a forcesource. Doing so would create a dependency between an input variable (thesource force) and a state variable (the spring force) in the underlying state-space equations.

Parameters Spring constantThe spring rate or stiffness c, in N

m .

Equilibrium (unstretched) displacementThe displacement x0 between the two flanges of the unloaded spring, inmeters.

Initial deformationThe initial deformation ∆x0 of the spring, in meters.

Probe Signals ForceThe spring force F , in Newton (N).

DeformationThe spring deformation ∆x, in meters (m).

740

Transmission Line (3ph)


Purpose 3-phase transmission line


Description This component implements a three-phase transmission line. A transmissionline is characterized by a uniform distribution of inductances, resistances andneutral capacitances along the line. In multi-wire lines, there are also uni-formly distributed mutual inductances and coupling capacitances.

The user has the choice between two different implementations: one withseries-connected pi sections of lumped elements and another one with dis-tributed parameters based on traveling wave theory. A stiff solver is recom-mended for simulating models containing this component.

Pi-Section Line

In many cases, the uniformly distributed parameters of a transmission linecan be approximated by a series of pi sections consisting of lumped inductors,capacitors and resistors. The figure below illustrates a single pi section exem-plified for a 2-phase line. Depending on the desired fidelity at higher frequen-cies, the number of series-connected pi sections can be configured.

U in1

U in2

C N1

mutual inductance

U out2

U out1___2

C N2___2

C 12___2

C 12___2

C N1___2

C N2___2

L 2R 2

L 1R 1

Let l be the length of the line and n the number of pi sections representingthe line. The inductance L, the resistance R, the neutral capacitance CN aswell as the coupling capacitances Cij and mutual inductances Lij of the dis-crete elements can then be calculated from their per-unit-length counterpartsL′, R′, C ′N , C ′ij and L′ij using the following equations:

L =l

nL′, R =

l

nR′, CN =

l

nC ′N

741


Cij =l

nC ′ij , Lij =

l

nL′ij

It is possible to specify the parameters for each phase individually in orderto model asymmetric lines. In this case, the parameters must be provided invector format. Otherwise, the parameter can be a scalar assigning the samevalue to all phases.

Distributed Parameter Line

The implementation of a distributed parameter line is based on the travelingwave theory, which describes the time delay phenomenon. This approach isnumerically more efficient due to the absence of numerous state variables andshould be used in large models.

Modeling asymmetric lines is not supported, therefore all parameters need tobe scalar.

Single-Phase Lossless Line

L'dx L'dx

C'dx C'dx

... ...L'dx L'dx

C'dx C'dx

Consider a lossless transmission line with inductance L′ and capacitance C ′per unit length. At a certain point x along the total length d, the relation be-tween the line voltage and current can be described with partial differentialequations:

− ∂e∂x

= L′ · ∂i∂t

− ∂i∂x

= C ′ · ∂e∂t

Since a wave entering the sending end “s” of the line must remain unchangedwhen it arrives at the receiving end “r” (and vice versa), the following expres-sion is derived:

is =1

Z· es(t)− Ish

742


ir =1

Z· er(t)− Irh

where

Ish =1

Z· er(t− τ) + ir(t− τ)

Irh =1

Z· es(t− τ) + is(t− τ)

with surge impedance Z =√

L′

C′ and travel time τ = d ·√L′C ′. This model can

be represented by a two-port equivalent circuit, where the electrical conditionsat port “s” are transferred after a time delay τ to port “r’ via the controlledcurrent source Irh.

i s i r

e s e rZ I sh I rh Z

+

-

+

-

Approximation of Series Resistance

i s R/4 length = 0.5*d length = 0.5*dR/2 R/4 i r

+

-

+

-

e re s

Since the shunt conductance is usually negligible, the series resistance is re-sponsible for the major part of the power losses. Such series resistance canbe approximated by three lumped resistors, two of which with the value R

4

are placed at both ends of the line while one with the value R2 is placed in the

743


middle. R = R′ · d is the total series resistance of the line. After aggregationand substitution, the original expression of the two equivalent current sourcebecomes:

Ish =1 + h

2· ( 1

ZR· er(t− τ) + h · ir(t− τ)) +

1− h2

(1

ZR· es(t− τ) + h · is(t− τ))

Irh =1 + h

2· ( 1

ZR· es(t− τ) + h · is(t− τ)) +

1− h2

(1

ZR· er(t− τ) + h · ir(t− τ))

with ZR = Z + R4 and h =

Z−R4

Z+ R4

.

Three-Phase Line

L M'dx

... ...

... ...

... ...

... ...

... ...

... ...

+

+

+

-

+

+

+

-

e s,a

e s,b

e s,c

e r,a

e r,b

e r,c

R'dx L S'dx

C K'dx

C E'dx

i s,a

i s,b

i s,c

i r,a

i r,b

i r,c

The differential equations of a 3-phase system with vector variables ~e =[ea, eb, ec]

T , ~i = [ia, ib, ic]T can be expressed as:

− ∂~e∂x

= L′ · ∂~i

∂t+ R′ ·~i

− ∂~i

∂x= C′ · ∂~e

∂t

Under the assumption of symmetrical phase parameters, the per unit lengthinductance, capacitance and resistance can be written in matrix form:

L′ =

L′S L′M L′M

L′M L′S L′M

L′M L′M L′S

744


C′ =

C ′E + 2 · C ′K −C ′K −C ′K−C ′K C ′E + 2 · C ′K −C ′K−C ′K −C ′K C ′E + 2 · C ′K

R′ =

R′ 0 0

0 R′ 0

0 0 R′

The presence of off-diagonal elements (mutual inductance and coupling capac-itance) in the matrix make it difficult to solve the equation system. However,this can be overcome with the help of modal transformations. If the differen-tial equations are multiplied by a transformation matrix T on the left side

−(T · ∂~e∂x

) = (T · L′ ·T−1) · (T · ∂~i

∂t) + (T ·R′ ·T−1) · (T ·~i)

−(T · ∂~i

∂x) = (T · L′ ·T−1) · (T · ∂~e

∂t)

with

T =

1 1 1

1 −2 1

1 1 −2

the off-diagonal elements of the inductance, capacitance and resistance matrixcan be eliminated:

L′mod = T · L′ ·T−1 =

L′u 0 0

0 L′v 0

0 0 L′w

C′mod = T ·C′ ·T−1 =

C ′u 0 0

0 C ′v 0

0 0 C ′w

745


R′mod = T ·R′ ·T−1 =

R′ 0 0

0 R′ 0

0 0 R′

= R′

Thus the original system, in which the three phases are coupled, has beenconverted to three decoupled systems in the modal domain (denoted as u, v,w). They can be treated separately in the same way as the single-phase sys-tem.

The simulation output in the modal domain should be eventually transformedback into the phase domain via the inverse of the matrix T′.

746


Parameters Self inductance per unit lengthThe series self inductance L′S per unit length. If the length l is specified inmeters (m) the unit of L′S is henries per meter (H/m).For a pi-section line, the self inductance can be specified individually perphase by providing a 3-element vector of the form L′ = [L′1 L′2 L′3].

Mutual inductance per unit lengthThe series mutual inductance L′M per unit length. If the length l is speci-fied in meters (m) the unit of L′M is henries per meter (H/m).In a pi-section line, the mutual inductances M ′ij between the i-th and j-thphase can be specified individually by providing a 3-element vector M′ =[M ′12 M ′13 M ′23] containing the upper triangular coupling matrix.

Resistance per unit lengthThe series resistance R′ per unit length. If the length l is specified in me-ters (m) the unit of R′ is ohms per meter (Ω/m).For a pi-section line, the parameter can be a vector of the form R′ =[R′1 R′2 R′3].

Neutral capacitance per unit lengthThe line-to-neutral capacitance C ′N per unit length. If the length l is speci-fied in meters (m) the unit of C ′N is farads per meter (F/m).For a pi-section line, this parameter can be a vector of the form C ′N =[C ′N1 C ′N2 C ′N1].

Coupling capacitance per unit lengthThe line-to-line capacitance C ′C per unit length. If the length l is specifiedin meters (m) the unit of C ′C is farads per meter (F/m).In a pi-section line, the coupling capacitance C ′ij between the i-th and j-thphase can be specified individually by providing a 3-element vector C′ =[C ′12 C ′13 C ′23] containing the upper triangular coupling matrix.

LengthThe length l of the line. The unit of l must match the units L′S, L′M, R′, C ′Nand C ′C are based on.

Number of pi sectionsNumber of sections used to model the transmission line. The default is 3.This parameter only affects the pi-section implementation.

ReferenceH. Dommel: “Digital Computer Solution of Electromagnetic Transients in

Single and Multiple Networks”, IEEE Transactions on Power Apparatusand Systems, Vol. PAS88, No. 4, April, 1969

747


Transport Delay

Purpose Delay continuous input signal by fixed or variable time


Description The Transport Delay outputs a signal that approximates a past value of theinput signal:

y(t) ≈ u(t− Td)

For this purpose, the Transport Delay continuously records the input signalsin an internal buffer. The output values are computed by looking up the sam-ples nearest to t − Td in the input buffer and performing a first order (linear)interpolation. The input signal can be a scalar or vector.

Note The Transport Delay should not be used to delay non-smooth signalssuch as rectangular or triangular signals because the solver is not guaranteedto make a simulation step at the precise instants required to accurately repro-duce the discontinuities in the delayed signal.

• To generate phase-shifted rectangular or triangular signals, use the PulseGenerator (see page 590) or the Triangular Wave Generator (see page 751)and set the Phase delay parameter appropriately.

• To delay arbitrary signals that only change at discrete instants, use the PulseDelay (see page 589).

Parameters Time delay sourceSpecifies whether the delay is determined by the Time delay parameter(internal) or by an external input signal (external).

Time delay Td

Time by which the input signal is delayed.

Maximum time delaySpecifies the maximum possible delay for the external delay input signal.

Initial outputOutput value after simulation start before the input values appear at theoutput.

748

TRIAC

TRIAC

Purpose Ideal TRIAC with optional forward voltage and on-resistance


Description The TRIAC can conduct current in both directions. It is built using two anti-parallel thyristors (see page 699) and controlled by an external gate signal.The TRIAC is modeled by two ideal switches that close if the voltage is pos-itive and a non-zero gate signal is applied. The conducting switch remainsclosed until the current passes through zero. A TRIAC cannot be switched offvia the gate.


Forward voltageAdditional dc voltage Vf in volts (V) when one of the thyristors is conduct-ing. The default is 0.


Initial conductivityInitial conduction state of the TRIAC. The TRIAC is initially blocking ifthe parameter evaluates to zero, otherwise it is conducting.



Probe Signals TRIAC voltageThe voltage measured between the terminals.

749


TRIAC currentThe current flowing through the device to the terminal with the gate.

TRIAC gate signalThe gate input signal of the device.

TRIAC conductivityConduction state of the internal switch. The signal outputs 0 when theTRIAC is blocking, and 1 when it is conducting.

TRIAC junction temperatureTemperature of the first thermal capacitor in the equivalent Cauer net-work.

TRIAC conduction lossContinuous thermal conduction losses in watts (W). Only defined if thecomponent is placed on a heat sink.

TRIAC switching lossInstantaneous thermal switching losses in joules (J). Only defined if thecomponent is placed on a heat sink.

750

Triangular Wave Generator

Triangular Wave Generator

Purpose Generate periodic triangular or sawtooth waveform


Description The Triangular Wave Generator produces a signal that periodically changesbetween a minimum and a maximum value and vice versa in a linear way.

Parameters Minimum signal valueThe minimum value of the signal.

Maximum signal valueThe maximum value of the signal.

FrequencyThe frequency of the signal in Hertz.

Duty cycleThe ratio of the rising edge to the period length. The value must be in therange [0 1]. A value of 1 produces a sawtooth waveform with a perpen-dicular falling edge. A value of 0 produces a reverse sawtooth waveformwith a perpendicular rising edge. A value of 0.5 produces a symmetricaltriangular wave.

Phase delayThe phase delay of the triangular wave in seconds. If the phase is set to 0,the waveform begins at the rising edge.


751


Trigonometric Function

Purpose Apply specified trigonometric function


Description The Trigonometric Function calculates the specified function using the inputsignal as argument. The atan2 function calculates the principal value of thearc tangent of y/x. The quadrant of the return value is determined by thesigns of x and y. The y input is marked with a small black dot.

Parameters FunctionChooses which trigonometric function is calculated. Available functions aresin, cos, tan, asin, acos, atan and atan2.

UnitSpecifies the unit of the input signal (for sin, cos and tan) or output sig-nal (for asin, acos and atan). The unit can be radians [0 . . . 2π] or degress[0 . . . 360].



752

Triple Switch

Triple Switch

Purpose Changeover switch with three positions


Description This changeover switch provides an ideal short or open circuit. The switch po-sition drawn in the icon applies if the input signal is zero. For values greaterthan zero the switch is the lower position. For values less than zero it is inthe upper position.

Parameter Initial positionInitial position of the switch. The switch is initially in the middle positionif the parameter evaluates to zero. For values greater than zero it is in thelower position, for values less than zero it is in the upper position. Thisparameter may either be a scalar or a vector corresponding to the implicitwidth of the component. The default value is 0.

Probe Signal Switch positionState of the internal switches. The signal outputs 0 if the switch is in themiddle position, 1 if it is in the lower position and -1 if it is in the upperposition.

753


Trigger

Purpose Control execution of an atomic subsystem

Library System

Description The Trigger block is used in an atomic subsystem (see “Virtual and AtomicSubsystems” on page 662) to create a triggered subsystem. When you copy aTrigger block into the schematic of a subsystem, a corresponding trigger ter-minal will be created on the Subsystem block. In order to move this terminalaround the edges of the Subsystem block, hold down the Shift key while drag-ging the terminal with the left mouse button or use the middle mouse button.

A triggered subsystem is executed when the trigger signal changes in themanner specified by the Trigger type parameter:

risingThe subsystem is executed when the trigger signal changes from 0 to anon-zero value.

fallingThe subsystem is executed when the trigger signal changes from a non-zero value to 0.

eitherThe subsystem is executed when the trigger signal changes from 0 to anon-zero value or vice versa.

The trigger signal may be a vector signal. In this case the triggered subsystemis executed when any trigger signal changes in the specified manner.

If the sample time of the Subsystem block is not inherited, the trigger signalwill be evaluated only at the instants specified by the sample time parameter.

Note A triggered subsystem can only contain components that have an in-herited or constant sample time. In particular, it cannot contain any physicalcomponents.

Parameters WidthThe width of the trigger signal. The default auto means that the width isinherited from connected blocks.

754

Trigger

Trigger typeThe direction of the edges of the trigger signal upon which the subsystemis executed, as described above.

Show output portWhen this parameter is set to on, the Trigger block shows an output ter-minal with the same width as the trigger signal. The output signal will be1 when the trigger signal has a rising edge, -1 when the trigger signal hasa falling edge and 0 at all other times.

Probe Signal OutputThe output signal of the Trigger block as described for the parameterShow output port.

755


Turn-on Delay

Purpose Delay rising flank of input pulses by fixed dead time


Description This block is used to delay the turn-on command for power semiconduc-tors:

• When the input signal changes from 0 to non-zero, the output signal will beset to 1 after the dead time has passed, provided that the input signal hasremained non-zero.

• When the input signal becomes 0, the output is immediately set to 0.

Parameter Dead time sourceSpecifies whether the dead time is determined by the Dead time parame-ter (internal) or by an external input signal (external).

Dead timeTime by which the turn-on event is delayed. If set to 0, the delay is dis-abled, i.e. the output is set to 1 immediately when the input signal be-comes non-zero.

Dead time rounding (fixed-step)If the dead time is determined by an external signal and the Turn-on De-lay is used with a fixed-step solver, this parameter specifies how the deadtime is rounded to an integer multiple of the fixed-step size.



756

Variable Capacitor

Variable Capacitor

Purpose Capacitance controlled by signal


Description This component models a variable capacitor. The capacitance is determined bythe signal fed into the input of the component. The current through a variablecapacitance is determined by the equation

i =d

dtC · v + C · d

dtv

Since v is the state variable the equation above must be solved for dvdt . The

control signal must provide the values of both C and ddtC in the following

form:[C1 C2 . . . Cn

ddtC1

ddtC2 . . .

ddtCn

]. It is the responsibility of the user to

provide the appropriate signals for a particular purpose (see further below).

If the component has multiple phases you can choose to include the ca-pacitive coupling of the phases. In this case the control signal vectormust contain the elements of the capacitance matrix (row by row) fol-lowed by their derivatives with respect to time, e.g. for two coupled phases:[C11 C12 C21 C22

ddtC11

ddtC12

ddtC21

ddtC22

]. The control signal thus has a width

of 2 · n2, n being the number of phases.

Note The momentary capacitance may not be set to zero. In case of coupledcapacitors, the capacitance matrix may not be singular.

There are two common use cases for variable capacitors, which are describedin detail below: saturable capacitors, in which the capacitance is a function ofthe voltage and electrostatic actuators, in which the capacitance is a functionof an external quantity, such as a capacitor with movable plates.

Saturable Capacitor Modeling

When specifying the characteristic of a saturable capacitor, you need to distin-guish carefully between the total capacitance Ctot(v) = Q/v and the differen-tial capacitance Cdiff(v) = dQ/dv.

757


With the total capacitance Ctot(v) = Q/v you have

i =dQ

dt

=d

dt(Ctot · v)

= Ctot ·dv

dt+

dCtot

dt· v

= Ctot ·dv

dt+

dCtot

dv· dv

dt· v

=

(Ctot +

dCtot

dv· v)· dv

dt,

which can be implemented as follows:

Ctot(v)

dCtot/dv **

++

0

V

With the differential capacitance Cdiff(v) = dQ/dv you have

i =dQ

dt

=dQ

dv· dv

dt

= Cdiff ·dv

dt,


Cdiff(v)

0

V

Note that in both cases the ddtC-input of the Variable Capacitor is zero!

758

Variable Capacitor

Actuator Modeling

In an electrostatic actuator the capacitance is determined by an externalquantity such as the distance x between the movable plates of a capacitor:C = C(x). Therefore you have

i = C · dv

dt+

dC

dt· v

= C · dv

dt+

dC

dx· dx

dt· v ,


dx/dt

1/sC(x)

dC/dx**

x

Note that x is preferably calculated as the integral of dx/dt rather than calcu-lating dx/dt as the derivative of x.

Parameters Capacitive couplingSpecifies whether the phases should be coupled capacitively. This parame-ter determines how the elements of the control signal are interpreted. Thedefault is off.

Initial voltageThe initial voltage of the capacitor at simulation start, in volts (V). Thisparameter may either be a scalar or a vector corresponding to the implicitwidth of the component. The positive pole is marked with a “+”. The initialvoltage default is 0.



759


Variable Inductor

Purpose Inductance controlled by signal


Description This component models a variable inductor. The inductance is determined bythe signal fed into the input of the component. The voltage across a variableinductance is determined by the equation

v = L · di

dt+

dL

dt· i

Since i is the state variable the equation above must be solved for didt . The con-

trol signal must provide the values of both L and ddtL in the following form:[

L1 L2 . . . LnddtL1

ddtL2 . . .

ddtLn

]. It is the responsibility of the user to provide

the appropriate signals for a particular purpose (see further below).

If the component has multiple phases you can choose to include the in-ductive coupling of the phases. In this case the control signal vector mustcontain the elements of the inductivity matrix (row by row) followedby their derivatives with respect to time, e.g. for two coupled phases:[L11 L12 L21 L22

ddtL11

ddtL12

ddtL21

ddtL22



Note The momentary inductance may not be set to zero. In case of coupledinductors, the inductivity matrix may not be singular.

760

Variable Inductor

There are two common use cases for variable inductors, which are describedin detail below: saturable inductors, in which the inductance is a function ofthe current and actuators, in which the inductance is a function of an externalquantity, such as a solenoid with a movable core.

For a more complex example of a variable inductor that depends on both theinductor current and an external quantity see the Switched Reluctance Ma-chine (on page 667).

Saturable Inductor Modeling

When specifying the characteristic of a saturable inductor, you need to distin-guish carefully between the total inductivity Ltot(i) = Ψ/i and the differentialinductivity Ldiff(i) = dΨ/di. See also the piece-wise linear Saturable Inductor(on page 622).

With the total inductivity Ltot(i) = Ψ/i you have

v =dΨ

dt

=d

dt(Ltot · i)

= Ltot ·di

dt+dLtot

dt· i

= Ltot ·di

dt+dLtot

di· di

dt· i

=

(Ltot +

dLtot

di· i)· di

dt,


A

Ltot(i)

dLtot/di **

++

0

With the differential inductivity Ldiff(i) = dΨ/di you have

761


v =dΨ

dt

=dΨ

di· di

dt

= Ldiff ·di

dt,


A

Ldiff(i)

0

Note that in both cases the ddtL-input of the Variable Inductor is zero!

Actuator Modeling

In an actuator the inductivity is determined by an external quantity such asthe position x of the movable core in a solenoid: L = L(x). Therefore you have

v = L · di

dt+

dL

dt· i

= L · di

dt+

dL

dx· dx

dt· i ,


dx/dt

1/sL(x)

dL/dx**

x

Note that x is preferably calculated as the integral of dx/dt rather than calcu-lating dx/dt as the derivative of x.

762

Variable Inductor

Parameters Inductive couplingSpecifies whether the phases should be coupled inductively. This parame-ter determines how the elements of the control signal are interpreted. Thedefault is off.

Initial currentThe initial current through the inductor at simulation start, in amperes(A). This parameter may either be a scalar or a vector corresponding to theimplicit width of the component. The direction of a positive initial currentis indicated by a small arrow in the component symbol. The default of theinitial current is 0.

Probe Signals Inductor currentThe current flowing through the inductor, in amperes (A). The direction ofa positive current is indicated with a small arrow in the component sym-bol.


763


Variable Magnetic Permeance

Purpose Variable permeance controlled by external signal

Library Magnetic

Description This component provides a magnetic flux path with a variable permeance. Thecomponent is used to model non-linear magnetic material properties such assaturation and hysteresis. The permeance is determined by the signal fed intothe input of the component. The flux-rate through a variable permeance P(t)is governed by the equation:

Φ =d

dt(P · F ) = P · dF

dt+

d

dtP · F

Since F is the state variable the equation above must be solved for dFdt . The

control signal must provide the values of P(t), ddtP(t) and Φ as a vector. It is

the responsibility of the user to provide the appropriate signals.

Modeling non-linear material properties

When specifying the characteristic of a non-linear permeance, we need to dis-tinguish carefully between the total permeance Ptot(F ) = Φ/F and the differ-ential permeance Pdiff(F ) = dΦ/dF .

If the total permeance Ptot(F ) is known the flux-rate Φ through a time-varying permeance is calculated as:

Φ =dΦ

dt

=d

dt(Ptot · F )

= Ptot ·dF

dt+

dPtot

dt· F

= Ptot ·dF

dt+

dPtot

dF· dF

dt· F

=

(Ptot +

dPtot

dF· F)· dF

dt

In this case, the control signal for the variable permeance component is:

764

Variable Magnetic Permeance

P(t)

ddtP(t)

Φ(t)

=

Ptot + d

dF Ptot · F

0

Ptot · F

In most cases, however, the differential permeance Pdiff(F ) is provided to char-acterize magnetic saturation and hysteresis. With

Φ =dΦ

dt

=dΦ

dF· dF

dt

= Pdiff ·dF

dt

the control signal isP(t)

ddtP(t)

Φ(t)

=

Pdiff

0

Ptot · F

Parameter Initial MMF

Magneto-motive force at simulation start, in ampere-turns (A).



765


Variable Resistor

Purpose Resistance controlled by a signal


Description This component provides an ideal resistor whose resistance is controlled bythe input signal.

Note The Variable Resistor creates an algebraic loop. See section “Block Sort-ing” (on page 31) for more information on algebraic loops.

Probe Signals The small dot in the component icon marks the positive terminal.

Resistor voltageThe voltage measured across the resistor from the positive to the negativeterminal.

Resistor currentThe current flowing into the positive terminal.

Resistor powerThe power consumed by the resistor.

766

Variable Resistor with Constant Capacitor

Variable Resistor with Constant Capacitor

Purpose Controlled resistance in parallel with constant capacitance


Description This component models a variable resistor with a constant capacitor connectedin parallel. The resistance is determined by the signal fed into the input ofthe component. It may not be set to zero.

Note In this component the resistor is implemented as a voltage-dependentcurrent source. Without the parallel capacitor, which fixes the momentary volt-age, this would result in an algebraic loop. Therefore, the capacitance may notbe set to zero.

Parameters CapacitanceThe value of the capacitor, in farads (F). All finite positive and negativevalues are accepted, excluding 0. The default is 100e-6.

In a vectorized component, all internal capacitors have the same value ifthe parameter is a scalar. To specify the capacitances individually use avector [C1 C2 . . . Cn] . The length n of the vector determines the width ofthe component.

Initial voltageThe initial voltage of the capacitor at simulation start, in volts (V). Thisparameter may either be a scalar or a vector corresponding to the width ofthe component. The positive pole is marked with a “+”. The initial voltagedefault is 0.

Probe Signal Capacitor voltageThe voltage measured across the capacitor, in volts (V). A positive voltageis measured when the potential at the terminal marked with “+” is greaterthan the potential at the unmarked terminal.

767


Variable Resistor with Constant Inductor

Purpose Controlled resistance in series with constant inductance


Description This component models a variable resistor with a constant inductor connectedin series. The resistance is determined by the signal fed into the input of thecomponent.

Note In this component the resistor is implemented as a current-dependentvoltage source. Without the series inductor, which fixes the momentary current,this would result in an algebraic loop. Therefore, the inductance may not be setto zero.

Parameters InductanceThe inductance in henries (H). All finite positive and negative values areaccepted, excluding 0. The default is 1e-3.

In a vectorized component, all internal inductors have the same induc-tance if the parameter is a scalar. To specify the inductances individuallyuse a vector [L1 L2 . . . Ln]. The length n of the vector determines the widthof the component.

Initial currentThe initial current through the component at simulation start, in amperes(A). This parameter may either be a scalar or a vector corresponding tothe width of the component. The direction of a positive initial current isindicated by a small arrow in the component symbol. The default of theinitial current is 0.

Probe Signal Inductor currentThe current flowing through the inductor, in amperes (A). The direction ofa positive current is indicated with a small arrow in the component sym-bol.

768

Variable Resistor with Variable Capacitor

Variable Resistor with Variable Capacitor

Purpose Controlled resistance in parallel with controlled capacitance


Description This component models a variable resistor with a variable capacitor connectedin parallel. The resistance and capacitance are determined by the signals fedinto the inputs of the component. The current through this component is de-termined by the equation

i =

(1

R+

d

dtC

)· v + C · d

dtv

The control signal for the capacitor must provide the values of both C and ddtC

in the following form:[C1 C2 . . . Cn

ddtC1

ddtC2 . . .

ddtCn

]. It is the responsibil-

ity of the user to provide the appropriate signals for a particular purpose. Fordetailed information see the Variable Capacitor (on page 757).

If the component has multiple phases you can choose to include the ca-pacitive coupling of the phases. In this case the control signal vectormust contain the elements of the capacitance matrix (row by row) fol-lowed by their derivatives with respect to time, e.g. for two coupled phases:[C11 C12 C21 C22

ddtC11

ddtC12

ddtC21

ddtC22



Note The momentary capacitance and the resistance may not be set to zero.In case of coupled capacitors, the capacitance matrix may not be singular.

Parameters Capacitive couplingSpecifies whether the phases should be coupled capacitively. This parame-ter determines how the elements of the control signal are interpreted. Thedefault is off.

Initial voltageThe initial voltage of the capacitor at simulation start, in volts (V). Thisparameter may either be a scalar or a vector corresponding to the implicitwidth of the component. The positive pole is marked with a “+”. The initialvoltage default is 0.

769


Probe Signal Capacitor voltageThe voltage measured across the capacitor, in volts (V). A positive voltageis measured when the potential at the terminal marked with “+” is greaterthan the potential at the unmarked terminal.

770

Variable Resistor with Variable Inductor

Variable Resistor with Variable Inductor

Purpose Controlled resistance in series with controlled inductance


Description This component models a variable resistor with a variable inductor connectedin series. The resistance and inductance are determined by the signals fedinto the inputs of the component. The voltage across this component is deter-mined by the equation

v =

(R+

d

dtL

)· i+ L · d

dti

The control signal for the inductor must provide the values of both L and ddtL

in the following form:[L1 L2 . . . Ln

ddtL1

ddtL2 . . .

ddtLn

]. It is the responsibility

of the user to provide the appropriate signals for a particular purpose. For de-tailed information see the Variable Inductor (on page 760).

If the component has multiple phases you can choose to include the in-ductive coupling of the phases. In this case the control signal vector mustcontain the elements of the inductivity matrix (row by row) followedby their derivatives with respect to time, e.g. for two coupled phases:[L11 L12 L21 L22

ddtL11

ddtL12

ddtL21

ddtL22



Note

• The momentary inductance may not be set to zero. In case of coupled induc-tors, the inductivity matrix may not be singular.

• The control signal for the momentary inductance values must be continuous.Discontinuous changes will produce non-physical results.

Parameters Inductive couplingSpecifies whether the phases should be coupled inductively. This parame-ter determines how the elements of the control signal are interpreted. Thedefault is off.

Initial currentThe initial current through the component at simulation start, in amperes(A). This parameter may either be a scalar or a vector corresponding to the

771


implicit width of the component. The direction of a positive initial currentis indicated by a small arrow in the component symbol. The default of theinitial current is 0.

Probe Signal Inductor currentThe current flowing through the inductor, in amperes (A). The direction ofa positive current is indicated with a small arrow in the component sym-bol.

772

Voltage Source (Controlled)

Voltage Source (Controlled)

Purpose Generate variable voltage


Description The Controlled Voltage Source generates a variable voltage between its twoelectrical terminals. The voltage is considered positive at the terminal markedwith a “+”. The momentary voltage is determined by the signal fed into theinput of the component.

Note A voltage source may not be short-circuited or connected in parallel to acapacitor or any other voltage source.

Parameters Discretization behaviorSpecifies whether a zero-order hold or a first-order hold is applied to theinput signal when the model is discretized. For details, see “PhysicalModel Discretization” (on page 35).

The option Non-causal zero-order hold applies a zero-order hold withthe input signal value from the current simulation step instead of the pre-vious one. This option can be used to compensate for a known delay of theinput signal.

Allow state-space inliningFor expert use only! When set to on and the input signal is a linear com-bination of electrical measurements, PLECS will eliminate the input vari-able from the state-space equations and substitute it with the correspond-ing output variables. The default is off.

Probe Signals Source voltageThe source voltage in volts (V).

Source currentThe current flowing through the source, in amperes (A).


773


Voltage Source AC

Purpose Generate sinusoidal voltage


Description The AC Voltage Source generates a sinusoidal voltage between its two electri-cal terminals. The voltage is considered positive at the terminal marked witha “+”. The momentary voltage v is determined by the equation

v = A · sin(ω · t+ ϕ)

where t is the simulation time.

If a variable-step solver is used, the solver step size is automatically limited toensure that a smooth voltage waveform is produced.


Parameters Each of the following parameters may either be a scalar or a vector corre-sponding to the implicit width of the component:

AmplitudeThe amplitude A of the voltage, in volts (V). The default is 1.

FrequencyThe angular frequency ω, in s−1. The default is 2*pi*50 which corre-sponds to 50 Hz.

PhaseThe phase shift ϕ, in radians. The default is 0.




774

Voltage Source AC (3-Phase)

Voltage Source AC (3-Phase)

Purpose Generate 3-phase sinusoidal voltage


Description The three phase Voltage Source generates three sinusoidal voltages betweenits electrical terminals. The first phase is marked with a small black dot. Themomentary voltages vi are determined by the equation

vi = Ai · sin(2π · f · t+ ϕi + ∆ϕi)

where t is the simulation time and ϕ0 = 0, ϕ1 = −2/3 · π and ϕ2 = 2/3 · π.


Parameters AmplitudeThe amplitude A of the voltage, in volts (V). The value can be given as ascalar or as a vector with three elements [A0, A1, A2].

FrequencyThe frequency f , in Hertz (Hz).

Phase offsetThe phase offset ∆ϕ, in radians. The value can be given as a scalar or as avector with three elements [∆ϕ0,∆ϕ1,∆ϕ2].

Neutral pointShow or hide the neutral point terminal.

Probe Signals Source voltageThe source voltages in volts (V) as a vectorized signal.

Source currentThe currents flowing through the source, in amperes (A) as a vectorizedsignal.

Source powerThe combined instantaneous output power of the source, in watts (W).

775


Voltage Source DC

Purpose Generate constant voltage


Description The DC Voltage Source generates a constant voltage between its two electricalterminals. The voltage is considered positive at the terminal marked with a“+”.


Parameter VoltageThe magnitude of the constant voltage, in volts (V). This parameter mayeither be a scalar or a vector defining the width of the component. The de-fault value is 1.




776

Voltmeter

Voltmeter

Purpose Output measured voltage as signal


Description

V

The Voltmeter measures the voltage between its two electrical terminalsand provides it as a signal at the output of the component. A positive volt-age is measured when the potential at the terminal marked with a “+” isgreater than at the unmarked one. The output signal can be made accessiblein Simulink with an Output block (see page 641) or by dragging the compo-nent into the dialog box of a Probe block.

Note The Voltmeter is ideal, i.e. it has an infinite internal resistance. Hence,if multiple voltmeters are connected in series the voltage across an individualvoltmeter is undefined. This produces a run-time error.

Likewise, if switches connected in series are all in open position the voltagesacross the individual switches are not properly defined. Although this does notproduce a run-time error it may lead to unexpected simulation results.

Probe Signal Measured voltageThe measured voltage in volts (V).

777


White Noise

Purpose Generate normally distributed random numbers


Description The White Noise block generates normally distributed (Gaussian) randomnumbers for modeling band-limited white noise. The mean and the standarddeviation of the underlying distribution can be configured in the componentdialog. The figure below illustrates the distribution for three different sets ofparameters. The seed of the generator initializes the algorithm at the simula-

tion start. For the same seed, the sequence of random numbers is reproducedin every simulation run. If this behavior is undesired the system time can beused as a seed. To minimize correlation effects, it is recommended to use dif-ferent seeds if multiple random generators are used in one model.

Parameters Mean µThe mean value of the distribution.

Standard deviation σThe standard deviation of the distribution.

SeedThe seed used to initialize the White Noise generator.

Sample TimeThe sampling period used for generating random output values.

778

White Noise

ReferencesMersenne Twister: http://en.wikipedia.org/wiki/Mersenne_twister

Leva, J. L., “A Fast Normal Random Number Generator", ACM Transactionson Mathematical Software, vol. 18, no. 4, pp. 449-453, 1992.

779

http://en.wikipedia.org/wiki/Mersenne_twister


Winding

Purpose Ideal winding defining an electro-magnetic interface

Library Magnetic

Description The Winding forms the interface between the electrical and the magnetic do-main. A winding of N turns is described with the equations:

v = N Φ

i =F

N

where v and i are voltage and current at the electrical terminals. F is themagneto-motive force (MMF) and Φ is the rate-of-change of the magnetic fluxthrough the winding. The left-hand side of the equations above refers to theelectrical domain, the right-hand side to the magnetic domain.

The sign conventions used for the electrical and magnetic quantities are il-lustrated in the figure below for the two polarities of the winding. Notice thepositions of the black dot and the brown arrow in the winding symbol.

+

-

+

-

-

+

+

-

v

i

i

vF F

ΦΦ

Parameters Number of turnsSpecifies the number of winding turns.

PolaritySpecifies the polarity of the winding. Choosing a negative polarity is equiv-alent to specifying a negative number of turns.

Probe Signals Winding voltageThe voltage measured from the positive (marked) to the negative electricalterminal of the winding, in volts (V).

Winding currentThe current flowing through the winding, in amperes (A). A current enter-ing the winding at the marked terminal is counted as positive.

780

Winding

MMFThe magneto-motive force measured from the marked to the unmarkedmagnetic terminal, in ampere-turns (A).

781


Wire Multiplexer

Purpose Bundle several wires into bus

Library System

Description This multiplexer combines several individual wires into a wire bus. The indi-vidual wires may themselves be buses. In the block icon, the first individualwire is marked with a dot.

Parameter WidthThis parameter allows you to specify the number and/or width of the indi-vidual wires. You can choose between the following formats for this param-eter:

Scalar: A scalar specifies the number of individual wires each having awidth of 1.

Vector: The length of the vector determines the number of individualwires. Each element specifies the width of the corresponding individualwire.

782

Wire Selector

Wire Selector

Purpose Select or reorder elements from wire bus

Library System

Description The Wire Selector block connects the individual elements of the output bus tothe specified elements of the input bus. The input bus is marked with a dot.

Parameters Input widthThe width of the input bus.

Output indicesA vector with the indices of the input elements that the output bus shouldcontain.

783


XY Plot

Purpose Display correlation between two signals

Library System

Description The XY Plot displays the relationship between two signals. It can be used inPLECS circuits as well as in Simulink models. For detailed information onhow to work with the XY Plot see section “Using the XY Plot” (on page 105).

Parameters TitleThe name which is displayed above the plot.

Sample timeThe block sample time used to sample the input signals. The default is -1(inherited). Other valid settings are 0 (continuous) or a valid fixed-stepdiscrete sample time pair (see “Sample Times” on page 38).

Limit samplesIf this option is selected, the XY Plot will only save the last n sample val-ues during a simulation. It can be used in long simulations to limit theamount of memory that is used by PLECS. If the option is unchecked allsample values are stored in memory.

Time rangeThis option may be used for periodic systems to limit the displayed data toa given number of periods.

The time range value determines the time range that is displayed in theplot. If set to auto, the data over the whole simulation time range is used.If a limit is given and the simulation time reaches an integer multiple ofthis limit the plot is cleared except for the data covering the last n timeranges, where n is the number entered under Show last. The plot is ap-pended until the simulation time reaches the next integer multiple of thetime range.

Plot styleThis option lets you choose whether you would like to plot trajectories, vec-tors or a combination of both. If vectors are drawn, the aspect ratio (seebelow) is automatically fixed to 1:1.

784

XY Plot

Keep aspect ratio (x:y)If this option is selected, the aspect ratio of the axes is kept constant. Aratio of x : y ensures that the length of x units on the x-axis matches thelength of y units on the y-axis.

Axis labelsThe axis labels that are displayed on the x- and y-axis.

X- and Y-limitsThe initial lower and upper bound of the x- and y-axis. If set to auto, theaxes are automatically scaled such that all data is visible. Note that set-ting any of the limits to auto is computationally expensive and may havea considerable impact on the simulation speed.

785


Zener Diode

Purpose Zener diode with controlled reverse breakdown voltage


Description The Zener diode is a type of diode that permits current to flow in forward di-rection like a normal diode (see page 388), but also in reverse direction if thevoltage is larger than the rated breakdown or Zener voltage. Zener diodes arewidely used to regulate the voltage across a circuit.

Parameters Zener voltageBreakdown voltage Vz in reverse direction, in volts (V). If the diode is re-verse conducting the voltage drop across the diode is determined by thisZener voltage plus the voltage across the Zener resistance.

Zener resistanceThe resistance Rz, in ohms (Ω), if the diode is reverse conducting.

Forward voltageAdditional dc voltage Vf in volts (V) between anode and cathode when thediode is forward conducting. The default is 0.

On-resistanceThe resistance Rf of the forward conducting device, in ohms (Ω). The de-fault is 0.



Forward conductivityConduction state of the positive internal switch. The signal outputs 1when the diode is conducting in forward direction, and 0 otherwise.

Reverse conductivityConduction state of the negative internal switch. The signal outputs 1when the diode is conducting in reverse direction, and 0 otherwise.

786

Zero Order Hold

Zero Order Hold

Purpose Sample and hold input signal periodically


Description The Zero Order Hold samples the input signal and holds this value at its out-put for a specified sample time.

Parameter Sample timeThe length of the hold time in seconds. See also the Discrete-Periodicsample time type in section “Sample Times” (on page 38).



787


788

15


This chapter lists the contents of the PLECS Extras library for PLECS Block-set in alphabetical order.

15 Additional Simulink Blocks

AC Sweep

Purpose Perform AC sweep

Library PLECS Extras / Analysis Tools

Description The AC Sweep block enables you to determine the transfer function of ageneric system from a single input to one or more outputs. The analysis isperformed by injecting a small sinusoidal signal at different frequencies intothe system and extracting the same frequencies from the system output(s) byFourier analysis. The perturbation signal is available at the block output. Thesystem outputs to be analyzed must be fed into the block’s input port.

An ac sweep can be started either by clicking the button Start analysis orwith the MATLAB command

placsweep(block);

where block is the Simulink handle or the full block path of the AC Sweepblock. The block handle or path can be followed by parameter/value pairs thatoverride the settings in the dialog box.

For additional information see section “AC Analysis” (on page 168).

Parameters System period lengthThe period length of the unperturbed system.

Simulation start timeThe simulation start time for the ac sweep.

Frequency sweep rangeA vector containing the lowest and highest perturbation frequency.

Frequency sweep scaleSpecifies whether the sweep frequencies should be distributed on a linearor logarithmic scale.

Number of pointsThe number of data points generated.

Amplitude at first freqThe amplitude of the perturbation signal at the lowest frequency. The am-plitudes at the other frequencies are calculated as

Ai = A1 ·√fi/f1

790

AC Sweep

Show reference inputIf this parameter is set to on, the block will show an additional input port,and the signal that is connected to it is used to determine the spectrumU(s) for the calculation of the transfer function G(s) = Y (s)/U(s). Other-wise, U(s) is determined by the internally generated perturbation signal.

MethodSpecifies the method to use for obtaining the steady-state operating pointof the system for each perturbation frequency.

Brute force simulation simply simulates the system on a cycle-by-cyclebasis until the difference between the state variables at the beginning andend of a cycle become sufficiently small. With this setting the parameterMax number of iterations actually limits the number of cycles until asteady state is reached.

Steady-state analysis performs a steady-state analysis for each pertur-bation frequency.

Start from model initial state uses the initial state values specifiedin the model – either in the individual blocks or in the simulation parame-ters.

Start from unperturbed steady state performs a steady-state analysisof the unperturbed system to determine the initial state vector for the acsweep.

Termination toleranceThe relative error bound for all state variables. The analysis continues un-til|x(t0)− x(t0 + T )|

max |x|≤ rtol

for each state variable.

Max number of iterationsThe maximum number of iterations allowed.

Output variableThe name of a MATLAB variable used to store the transfer function at theend of an analysis. If the analysis was run interactively from the GUI, thevariable is assigned in the MATLAB base workspace. If the analysis wasrun with the placsweep command, the variable is assigned in the caller’sworkspace.

Plot bode diagramSpecifies whether to plot the transfer function in a bode diagram.

791


Display levelSpecifies the level of detail of the diagnostic messages displayed in thecommand window (iteration, final, off).

Hidden model statesSpecifies how to handle Simulink blocks with ’hidden’ states, i.e. statesthat are not stored in the state vector (error, warning, none).

792

Discrete Analysis

Discrete Analysis

Please refer to the documentation on the following components:

• Discrete Fourier Transform (see page 394)• Discrete Mean Value (see page 399)• Discrete RMS Value (see page 404)• Discrete Total Harmonic Distortion (see page 406)

793



Purpose Perform impulse response analysis


Description The Impulse Response Analysis block enables you to determine the transferfunction of a generic system from a single input to one or more outputs. Theanalysis is performed by injecting a small rectangular pulse into the systemand computing the inverse Laplace transform of the system response(s). Theperturbation signal is available at the block output. The system outputs to beanalyzed must be fed into the block’s input port.

An analysis can be started either by clicking the button Start analysis orwith the MATLAB command

plimpulseresponse(block);

where block is the Simulink handle or the full block path of the Impulse Re-sponse Analysis block. The block handle or path can be followed by parame-ter/value pairs that override the settings in the dialog box.

For additional information see section “Impulse Response Analysis” (on page168).

Parameters System period lengthThe period length of the unperturbed system.

Simulation start timeThe simulation start time for the impulse response analysis.

Frequency sweep rangeA vector containing the lowest and highest perturbation frequency.

Frequency sweep scaleSpecifies whether the sweep frequencies should be distributed on a linearor logarithmic scale.

Number of pointsThe number of data points generated.

PerturbationThe amplitude of the perturbation signal.

794


Compensation for discrete pulseSpecifies whether and how the effect of the sampling should be compen-sated. See section “Compensation for Discrete Pulse” (on page 169) for anexplanation of the parameter values.

Termination toleranceThe relative error bound used in the initial steady-state analysis.

Max number of iterationsThe maximum number of iterations allowed during the initial steady-stateanalysis.

Output variableThe name of a MATLAB variable used to store the transfer function at theend of an analysis. If the analysis was run interactively from the GUI, thevariable is assigned in the MATLAB base workspace. If the analysis wasrun with the placsweep command, the variable is assigned in the caller’sworkspace.




795


Loop Gain Analysis (AC Sweep)

Purpose Determine loop gain of closed control loop


Description The Loop Gain Analysis block enables you to determine the gain of a closedcontrol loop. To measure the loop gain, insert the block anywhere in the con-trol loop. The loop gain is determined by adding a small sinusoidal signal atvarious frequencies and extracting the same frequencies from the system be-fore and after the summation point by Fourier analysis.


placsweep(block);

where block is the Simulink handle or the full block path of the Loop GainAnalysis block. Otherwise, the block remains inactive and does not influencethe control loop.

For additional information see section “AC Analysis” (on page 168).

Note The Loop Gain Analysis block works only on scalar signals. In order toanalyze the gain of a vectorized control loop you need to demultiplex the vectorsignal into individual scalar signals before inserting the Loop Gain Analysisblock.

Parameters The parameters are identical to those of the AC Sweep block (see page 790).

796

Loop Gain Analysis (Multitone)

Loop Gain Analysis (Multitone)

Purpose Determine loop gain of closed control loop


Description The Loop Gain Analysis block enables you to determine the gain of a closedcontrol loop. To measure the loop gain, insert the block anywhere in the con-trol loop. The loop gain is determined by adding a small sinusoidal signal atvarious frequencies and extracting the same frequencies from the system be-fore and after the summation point by Fourier analysis.


plmultitone(block);

where block is the Simulink handle or the full block path of the Loop GainAnalysis block. Otherwise, the block remains inactive and does not influencethe control loop.

For additional information see section “Multitone Analysis” (on page 170).

Note The Loop Gain Analysis block works only on scalar signals. In order toanalyze the gain of a vectorized control loop you need to demultiplex the vectorsignal into individual scalar signals before inserting the Loop Gain Analysisblock.

Parameters The parameters are identical to those of the Multitone Analysis block (seepage 799).

797


Modulators


• 2-Pulse Generator (see page 317)• 3-Phase Overmodulation (see page 330)• 6-Pulse Generator (see page 331)• Blanking Time (see page 345)• Blanking Time (3-Level) (see page 346)• Sawtooth PWM (see page 627)• Sawtooth PWM (3-Level) (see page 629)• Symmetrical PWM (see page 671)• Symmetrical PWM (3-Level) (see page 673)• Peak Current Controller (see page 561)

798

Multitone Analysis

Multitone Analysis

Purpose Perform a multitone analysis


Description The Multitone Analysis block enables you to determine the transfer functionof a generic system from a single input to one or more outputs. The analysis isperformed by injecting a small multitone signal containing different frequen-cies into the system and extracting the same frequencies from the system out-put(s) by Fourier analysis. The perturbation signal is available at the blockoutput. The system outputs to be analyzed must be fed into the block’s inputport.

A multitone analysis can be started either by clicking the button Start analy-sis or with the MATLAB command

plmultitone(block);

where block is the Simulink handle or the full block path of the MultitoneAnalysis block. The block handle or path can be followed by parameter/valuepairs that override the settings in the dialog box.

For additional information see section “Multitone Analysis” (on page 170).

Parameters Frequency rangeA vector containing the lowest and highest perturbation frequency.

AmplitudeThe amplitude of the perturbation signal.

Show reference inputIf this parameter is set to on, the block will show an additional input port,and the signal that is connected to it is used to determine the spectrumU(s) for the calculation of the transfer function G(s) = Y (s)/U(s). Other-wise, U(s) is determined by the internally generated perturbation signal.

Init. simulation periodThe duration of an initial simulation performed before the response ismeasured. It is assumed that during this period, the system reaches itssteady state. The total simulation duration will be the sum of this parame-ter and one period of the base frequency signal.

799


Output variableThe name of a MATLAB variable used to store the transfer function at theend of an analysis. If the analysis was run interactively from the GUI,the variable is assigned in the MATLAB base workspace. If the analysiswas run with the plmultitone command, the variable is assigned in thecaller’s workspace.



800



Purpose Determine periodic steady-state operating point


Description The Steady-State Analysis block enables you to determine the steady-stateoperating point of a generic periodic system. Copy this block anywhere intothe model that you want to analyze.

A steady-state analysis can be started either by clicking the button Startanalysis or with the MATLAB command

plsteadystate(block);

where block is the Simulink handle or the full block path of the Steady-StateAnalysis block. The block handle or path can be followed by parameter/valuepairs that override the settings in the dialog box.

For additional information see section “Steady-State Analysis” (on page 165).

Parameters System periodSpecifies whether the system period is fixed, i.e. predetermined and con-stant, or variable (e.g. in case of a hysteresis type controller). If variableis selected, a trigger input will be drawn which is used to determine theend of a period.

Trigger typeSpecifies which trigger event on the input signal (rising, falling) marksthe end of a variable system period.

System period length/Max simulation time spanFor a fixed system period, the period length; for a variable system period,the maximum time span during which to look for a trigger event markingthe end of a period.

Simulation start timeThe simulation start time for the steady-state analysis.

Termination toleranceThe relative error bound. The analysis continues until both the maximumrelative error in the state variables and the maximum relative changefrom one iteration to the next are smaller than this bound for each statevariable.

801


Max number of iterationsThe maximum number of iterations allowed.

Steady-state variableThe name of a MATLAB variable used to store the periodic steady-statevector at the end of an analysis. If the analysis was run interactively fromthe GUI, the variable is assigned in the MATLAB base workspace. If theanalysis was run with the plsteadystate command, the variable is as-signed in the caller’s workspace.

Show steady-state cyclesThe number of cycles shown in the Simulink scopes at the end of an analy-sis.

Display levelSpecifies the level of detail (iteration, final, off) of the diagnostic mes-sages displayed in the command window.


802

Timer

Timer

Purpose Generate piece-wise constant signal

Library PLECS Extras / Control Blocks

Description The Timer block generates a signal that changes at discrete instants andis otherwise constant. You can use the Timer block e.g. in order to controlswitches such as circuit breakers.

Parameters Time valuesA vector containing the transition times. This vector must have the samelength as the vector of output values. Before the first transition time theoutput is zero.

Output valuesA vector containing the output values corresponding to the transitiontimes. This vector must have the same length as the vector of time values.

803


Transformations


• Transformation 3ph->RRF (see page 713)• Transformation 3ph->SRF (see page 714)• Transformation RRF->3ph (see page 715)• Transformation RRF->SRF (see page 716)• Transformation SRF->3ph (see page 717)• Transformation SRF->RRF (see page 718)

804

electrical engineering software

Plexim GmbH [email protected] www.plexim.com

User Manual Version 3.4

The siMUlaTion plaTforM for power elecTronic sysTeMs

plec

s User M

anual Version 3.4

the simulation platform for power electronic systems · integration with simulink coder. . . . . ....

Documents