PLECS 3.7 Online Help

Simulation Parameters

PLECS Blockset Parameters

This section describes the simulation parameters available in the PLECS Blockset for Simulink. For the standalone simulation parameters please refer to the next section.

To open the parameter dialog, select PLECS parameters from the Simulation menu of the schematic editor.

Circuit Model Options

Diode Turn-On Threshold This parameter globally controls the turn-on behavior of line commutated devices such as diodes, thyristors, GTOs and similar semiconductors. A diode starts conducting as soon as the voltage across it becomes larger than the sum of the forward voltage and the threshold voltage. Similar conditions apply to the other line commutated devices. The default value for this parameter is 1e-3.

For most applications the threshold could also be set to zero. However, in certain cases it is necessary to set this parameter to a small positive value to prevent line commutated devices from bouncing. Bouncing occurs if a switch receives an opening command and a closing command repeatedly in subsequent simulation steps or even within the same simulation step. Such a situation can arise in large, stiff systems that contain many interconnected switches.


Note  The Diode Turn-On Threshold is not equivalent to the voltage drop across a device when it is conducting. The turn-on threshold only delays the instant when a device turns on. The voltage drop across a device is solely determined by the forward voltage and/or on-resistance specified in the device parameters.

Type This parameter lets you choose between the continuous and discrete state-space method for setting up the physical model equations. For details please refer to section Physical Model Equations.

When you choose Continuous state-space, PLECS employs the Simulink solver to solve the differential equations and integrate the state variables. The Switch Manager communicates with the solver in order to ensure that switching occurs at the correct time. This is done with Simulink's zero-crossing detection capability. For this reason the continuous method can only be used with 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 you should 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-Space Discretization. All other continuous state variables are updated using 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 Simulink samples the circuit. A setting of auto or -1 means that the sample time is inherited from the Simulink model.

Refine factor This parameter controls the internal step size which PLECS uses to discretize the state-space equations. The discretization time step Dt   is thus calculated as the sample time divided by the refine factor. The refine factor must be a positive integer. The default is 1.

Choosing a refine factor larger than 1 allows you to use a sample time that is convenient for your discrete controller while at the same time taking into account the usually faster dynamics of the electrical system.

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. It controls 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 variables are consistent after a switching event. The defaults are 1e-3 for the relative tolerance and 1e-6 for the absolute tolerance.


Note  The discrete method cannot be used with circuits that contain direct non-linear feedbacks because in conjunction with Tustin's method this would lead to algebraic loops.

This applies for instance to the non-saturable induction machine models. If you must simulate an induction machine with the discrete method, use the Saturable Induction Machine instead. The non-linear feedback paths in this model contain Integrator blocks which prevent the algebraic loops.


Diagnostics

Zero crossing detection disabled In order to accurately determine the proper switching times of power semiconductors, PLECS highly depends on the solver's capability to locate zero crossings. If you switch off the zero crossing detection in the Simulink solver or use the less accurate "Adaptive" detection algorithm, PLECS will therefore issue a diagnostic message. This option allows you to specify the severity level (warning or error) of this message.

If you encounter problems due to many consecutive zero crossings, it is usually not advisable to modify the zero crossing detection settings. Consecutive zero crossings are often caused by insufficient simulation accuracy, typically in conjunction with a stiff model. In this case it may help to tighten the relative 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 ode23tb and, where applicable, set the Simulink solver option Solver reset method to Robust.

Number of consecutive gate signal changes If you configure a Signal Inport block in a top-level schematic to be a gate signal, PLECS expects this signal to change only at discrete instants. If instead the signal changes in more than the specified number of consecutive simulation time steps, PLECS will issue an error message to indicate that there may be a problem in the gate signal generator. You can disable this diagnostic by entering 0.

Division by zero This option determines the diagnostic action to take if PLECS encounters a division by zero in a Product block or a Function block. A division by zero yields ± ∞  or nan (,,not a number", if you divide 0∕0  ). Using these values as inputs for other blocks may lead to unexpected model behavior. Possible choices are ignore, warning and error. In new models, the default is error. In models created with PLECS 3.6 or earlier, the default is warning.

Negative switch loss This option determines the diagnostic action to take if PLECS encounters negative loss values during the calculation of switch losses (see Loss Calculation). PLECS can issue an error or a warning message or can continue silently, In the latter two cases, the losses that are injected into the thermal model are cropped to zero.

Assertion action Use this option to override the action that is executed when an assertion fails (see Assertion block). The default is use local settings, which uses the actions specified in each individual assertion. Assertions with the individual setting ignore are always ignored, even if this option is different from use local settings. Note that during analyses and simulation scripts, assertions may be partly disabled (see Assertions).

Sample times

Synchronize fixed-step sample times This option specifies whether PLECS should attempt to find a common base sample rate for blocks that specify a discrete sample time.

Use single base sample rate This option specifies whether PLECS should attempt to find a single common base sample rate for all blocks that specify a discrete sample time.

These options can only be modified for a Continuous State-Space model; for a Discrete State-Space model they are checked by default. For details see section Multirate Systems.

Code generation

Target This option specifies the code generation target that is used when you generate code with the Simulink Coder. For details on the available targets see section Code Generation Targets.

Inline circuit parameters for RSim target This option controls whether PLECS inlines parameter values or whether it should keep them tunable when it creates code for the RSim target. For details see section Tunable Circuit Parameters in Rapid Simulations.

State-space calculation

Use extended precision When this option is checked, PLECS uses higher-precision arithmetics for the internal calculation of the state-space matrices for a physical model. Check this option if PLECS reports that the system matrix is close to singular.

PLECS Standalone Parameters

This section describes the simulation parameters available for PLECS Standalone. For the PLECS Blockset simulation parameters please refer to the previous section.

To open the parameter dialog, select Simulation parameters from the Simulation menu of the schematic editor or press Ctrl-E.

Simulation Time

Start Time The start time specifies the initial value of the simulation time variable t   at the beginning of a simulation, in seconds. The initial conditions specified in the block parameters must match the specified start time.

Stop Time The simulation ends when the simulation time has advanced to the specified stop time.

Solver

These two parameters let you choose between variable-step and fixed-step solvers. A fixed-step solver uses the same step size - i.e. the simulation time increment - throughout a simulation. The step size must be chosen by the user so as to achieve a good balance between accuracy and computational effort.

A variable-step solver can adopt the step size during the simulation depending on model dynamics. At times of rapid state changes the step size is reduced to maintain accuracy; when the model states change only slowly, the step size is increased to save unnecessary computations. The step size can also be adjusted in order to accurately simulate discontinuities. For these reasons, a variable-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 for non-stiff systems and is selected by default. A stiff system can be sloppily defined 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 the recommendation to switch to a stiff solver.

RADAU is a variable-step solver for stiff systems using a fifth-order accurate fully-implicit three-stage Runge-Kutta formula (Radau IIa). For non-stiff systems DOPRI is more efficient than RADAU.

The fixed-step solver Discrete does not actually solve any differential equations but just advances the simulation time with fixed increments. If this solver is chosen, the linear state-space equations of the physical model are discretized as described in section State-Space Discretization. All other continuous state variables are updated using the Forward Euler method. Events and discontinuities that occur between simulation steps are accounted for by a linear interpolation method.

Variable-Step Solver Options

Max Step Size The maximum step size specifies the largest time step that the solver can take and should not be chosen unnecessarily small. If you suspect that the solver is missing events, try reducing the maximum step size. However, if you just require more output points for smoother curves, you should increase the refine factor (see below).

Initial Step Size This parameter can be used to suggest a step size to be used for the first integration step. The default setting auto causes the solver to choose the step size according to the initial state derivatives. You should only change this parameter if you suspect that the solver is missing an event at the beginning of a simulation.

Tolerances The relative and absolute specify the acceptable local integration errors for the individual state variables according to

erri ≤ rtol⋅|xi|+ atoli

If all error estimates are smaller than the limit, the solver will increase the step 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 the absolute tolerance for each state variable individually, based on the maximum absolute value encountered so far.

Refine factor The refine factor is an efficient method for generating additional output points in order to achieve smoother results. For each successful integration step, the solver calculates r- 1   intermediate steps by interpolating the continuous states based on a higher-order polynomial. This is computationally 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 the solver and also the sample time used for the state-space discretization of the physical model.

Circuit Model Options

Diode Turn-On Threshold This parameter globally controls the turn-on behavior of line commutated devices such as diodes, thyristors, GTOs and similar semiconductors. A diode starts conducting as soon as the voltage across it becomes larger than the sum of the forward voltage and the threshold voltage. Similar conditions apply to the other line commutated devices. The default value for this parameter is 1e-3.

For most applications the threshold could also be set to zero. However, in certain cases it is necessary to set this parameter to a small positive value to prevent line commutated devices from bouncing. Bouncing occurs if a switch receives an opening command and a closing command repeatedly in subsequent simulation steps or even within the same simulation step. Such a situation can arise in large, stiff systems that contain many interconnected switches.


Note  The Diode Turn-On Threshold is not equivalent to the voltage drop across a device when it is conducting. The turn-on threshold only delays the instant when a device turns on. The voltage drop across a device is solely determined by the forward voltage and/or on-resistance specified in the device parameters.

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. It controls 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 variables are consistent after a switching event. The defaults are 1e-3 for the relative tolerance and 1e-6 for the absolute tolerance.

Sample times

Synchronize fixed-step sample times This option specifies whether PLECS should attempt to find a common base sample rate for blocks that specify a discrete sample time.

Use single base sample rate This option specifies whether PLECS should attempt to find a single common base sample rate for all blocks that specify a discrete sample time.

These options can only be modified for a variable-step solver; for a fixed-step solver they are checked by default. For details see section Multirate Systems.

Diagnostics

Division by zero This option determines the diagnostic action to take if PLECS encounters a division by zero in a Product block or a Function block. A division by zero yields ± ∞  or nan (,,not a number", if you divide 0∕0  ). Using these values as inputs for other blocks may lead to unexpected model behavior. Possible choices are ignore, warning and error. In new models, the default is error. In models created with PLECS 3.6 or earlier, the default is warning.

Negative switch loss This option determines the diagnostic action to take if PLECS encounters negative loss values during the calculation of switch losses (see Loss Calculation). PLECS can issue an error or a warning message or can continue silently, In the latter two cases, the losses that 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 a model becomes ,,stiff" during the simulation. Stiff models cannot be solved efficiently with non-stiff solvers, because they constantly need to adjust the step size at relatively small values to keep the solution from becoming numerically unstable.

If the DOPRI solver detects stiffness in model, it will raise a warning or error message depending on this parameter setting with the recommendation to use the stiff RADAU solver instead.

Max. number of consecutive zero-crossings This parameter only applies to variable-step solvers. For a model that contains discontinuities (also termed ,,zero-crossings"), a variable-step solver will reduce the step size so as to make a simulation step precisely at the time when a discontinuity occurs (see Event Detection Loop). If many discontinuities occur in subsequent steps, the simulation may come to an apparent halt without actually stopping because the solver is forced to reduce the step size to an excessively small value.

This parameter specifies an upper limit for the number of discontinuities in consecutive simulation steps before PLECS stops the simulation with an error message that shows the responsible component(s). To disable this diagnostic, set this parameter to 0.

State-space calculation

Use extended precision When this option is checked, PLECS uses higher-precision arithmetics for the internal calculation of the state-space matrices for a physical model. Check this option if PLECS reports that the system matrix is close to singular.

Assertions

Assertion action Use this option to override the action that is executed when an assertion fails (see Assertion block). The default is use local settings, which uses the actions specified in each individual assertion. Assertions with the individual setting ignore are always ignored, even if this option is different from use local settings. Note that during analyses and simulation scripts, assertions may be partly disabled (see Assertions).

System State

This parameter controls how the system state is initialized at the beginning of a simulation. The system state comprises

Block parameters When this option is selected, the state variables are initialized with the values specified in the individual block parameters.

Stored system state When this option is selected, the state variables are initialized globally from a previously stored system state; the initial values specified in the individual block parameters are ignored. This option is disabled if no state has been stored.

Store system state... Pressing this button after a transient simulation run or an analysis will store the final system state along with a time stamp and an optional comment. When you save the model, this information will be stored in the model file so that it can be used in future sessions.


Note  Adding or removing blocks that have continuous or discrete state variables associated with them will invalidate a stored system state.

Model Initialization Commands

The model initialization commands are executed when a simulation is started in order to populate the base workspace. You can use variables defined in the base workspace when specifying component parameters (see Specifying Component Parameters).


Note  The maximum length of variable names is 63 characters. This is due to the way, in which a workspace is stored in PLECS and exchanged with Octave.