Simulation Scripts

Running simulations from a script allows you to perform automated tasks such as examining the effect of varying parameters or post-processing the simulation results to extract relevant information.

PLECS Standalone offers two different scripting methods:

Simulation scripts written in Octave can be executed directly in PLECS Standalone. This is described in section Simulation Scripts in PLECS Standalone.
PLECS offers an RPC interface that allows any other program that can send XML-RPC or JSON-RPC requests to control PLECS. Many scripting languages support XML-RPC or JSON-RPC out of the box, for example Python or Ruby. Other scripting language extensions for XML-RPC or JSON-RPC support are available for free on the internet. This is described in section RPC Interface in PLECS Standalone.

In PLECS Blockset, scripts are written and executed in the MATLAB environment. Simulink offers a scripting interface to modify parameters and run simulations from a script. A detailed description of the Simulink scripting options is out of the scope of this manual, please refer to the documentation for Simulink instead. PLECS Blockset offers additional commands to control the parameters of PLECS Circuits. They are described in section Command Line Interface in PLECS Blockset.

Simulation Scripts in PLECS Standalone

Simulation scripts are managed in the Simulation Scripts dialog shown in Fig. 116. To open the dialog, select Simulation scripts… from the Simulation menu of the schematic editor.

../_images/SimulationScriptDlg.png — Fig. 116 Simulation Scripts dialog in PLECS Standalone

The left hand side of the dialog window shows a list of the scripts that are currently configured for the model. To add a new script, click the button marked + below the list. To remove the currently selected script, click on the button marked -. You can reorder the scripts by clicking and dragging an entry up and down in the list.

The right hand side of the dialog window shows the script in an editor window. Each script must have a unique Description.

The button Run/Stop starts the currently selected script or aborts the script that 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 Accept or Run button was pressed.

PLECS Standalone uses GNU Octave to execute simulation scripts. The Octave language is very similar to MATLAB. A full syntax description of the Octave scripting language is available in the Octave documentation.

Any console output generated by Octave will appear in the Octave Console window, which you can open by choosing Show Console from the Window menu.

Overview of PLECS Scripting Extensions

In addition to generic Octave commands you can use the following commands to 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 and home 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 componentPath as a string. If parameter is omitted, a struct array with all available parameters is returned.

plecs('set', componentPath, parameter, value)

sets the value of parameter of the PLECS component indicated by the componentPath to value.

The special parameter CurrentComponent can be used to query the path of the current component as defined above. The component path has to be an empty string:

plecs('get', '', 'CurrentComponent')

The special parameter CurrentCircuit can be used to query the name of the model that is currently executed. It cannot be queried interactively from the console. The component path has to be an empty string:

plecs('get', '', 'CurrentCircuit')

This command is useful for constructing a component path that does not depend on the model name.

A leading dot (.) in the component path is substituted with the current component or model as described in Path Substitution.

Handling of Information, Warnings and Errors in Initialization Commands

During the execution of mask initialization commands,

plecs('info', infoMessage)
plecs('warning', warningMessage)
plecs('error', errorMessage)

add entries to the Diagnostics window. Error messages issued with the Octave command error are caught by PLECS and are also shown in the Diagnostics window.

Note that the native Octave command warning will only print the warning message to the Octave console.

Handling of Traces in Scopes

plecs('scope', scopePath, 'HoldTrace')
plecs('scope', scopePath, 'HoldTrace', traceName)

saves the values of the last simulation to a new trace in the scope indicated by the scopePath. If given and unique, traceName is used as the name for the new trace, otherwise a default name is assigned. In both cases the method returns the name given to the trace.

plecs('scope', scopePath, 'RemoveTrace', traceName)

removes the trace named traceName from the scope indicated by the scopePath.

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 later reference. If fileName is not an absolute path, it is interpreted relative to the model file that contains the scope.

plecs('scope', scopePath, 'LoadTraces', fileName)

loads the trace data from the file fileName into the scope at scopePath. If fileName is not an absolute path, it is interpreted relative to the model file that contains the scope.

The scopePath is the path to the scope within the model including the model name, e.g. 'DTC/Mechanical'. To access Bode plots from the analysis tools, use the model name followed by '/Analyses/' followed by the name of the analysis, e.g. 'BuckOpenLoop/Analyses/Control to Output TF (AC Sweep)'. A leading dot (.) in the scope path is substituted with the current component or model as described in Path Substitution.

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) for the cursor positions t1 and t2. Valid analysis names are delta, min, max, absmax, mean, rms and thd. For more information about scope cursors see the Cursors section.

The return value is a struct with the two fields time and cursorData. The field time is the vector [t1, t2]. The field cursorData is a nested cell array where the outer index corresponds to the number of plots in the scope and the inner index corresponds to the number of signals in a plot. Each cell is a struct with the fields cursor1 and cursor2 with the signal values and additional fields for the analyses that you have specified. If the scope has multiple traces, 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 2 for the third trace of the second signal in the first plot, you write

data.cursorData{1}{2}.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 values to the text file fileName. If fileName is not an absolute path, it is interpreted 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 absolute path, it is interpreted relative to the model file that contains the scope. The file format is determined automatically from the file extension. The fileName argument may be followed by one or more name/value pairs to override settings defined in the scope as follows:

Table 17 Scope Settings for Bitmap Export
Name	Description
`Size`	A two-element integer vector specifying the width and height of the bitmap in pixels.
`Resolution`	An integer specifying the resolution of the bitmap in pixels per inch.
`TimeRange`	A two-element real vector specifying the time range of the data to be shown.
`XLim`	A two-element real vector specifying the limits of the x-axis. For a normal scope this is equivalent to `TimeRange`.
`YLim`	A cell array containing two-element real vectors specifying the limits of the y-axis of the plot(s). For a scope with a single plot a vector may be given directly.
`XLabel`	A string specifying the x-axis label.
`YLabel`	A cell array containing strings specifying the y-axis labels of the plot(s). For a scope with a single plot a string may be given directly.
`Title`	A cell array containing strings specifying the title of the plot(s). For a scope with a single plot a string may be given directly.
`LegendPosition`	A string specifying the legend position. Possible values are `none`, `topleft`, `topmiddle`, `topright`, `bottomleft`, `bottommiddle` and `bottomright`.
`Font`	A string specifying the font name to be used for the labels 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 followed by a slash (./), the dot is substituted with the current component.

When a command is executed interactively from the console, the current component is the last component that was clicked on in the schematic editor; if the last click was not on a component, the current component is undefined.

During the evaluation of block parameters or mask initialization commands the current component is the component that is currently evaluated; during the evaluation of the model initialization commands it is the model itself.

Running a Simulation

plecs('simulate')
plecs('simulate', optStruct)

runs a simulation. The optional argument optStruct can be used to override model parameters; for detailed information see section Scripted Simulation and Analysis Options.

If any outports exist on the top level of the simulated model, the command returns a struct consisting of two fields, Time and Values. Time is a vector of simulation time stamps. Values is an \(m \times n\) array containing the output values, where \(m\) is the number of time stamps and \(n\) is the number of output signals. The order of the signals is determined by the port numbers.

By default, the simulation result contains all simulation steps that the solver makes. This can be controlled with the solver options OutputTimes and OutputTimesOption, where OutputTimes is a double vector and OutputTimesOption is a string as described in Tab. 19.

Running an Analysis

plecs('analyze', analysisName)
plecs('analyze', analysisName, optStruct)

runs the analysis defined in the Analysis Tools dialog under the name analysisName. The optional argument optStruct can be used to override model parameters; for detailed information see section Scripted Simulation and Analysis Options.

For a Steady-State Analysis, if any outports exist on the top level of the simulated model, the command returns a struct consisting of two fields, Time and Values as described above. The signal values at the outports are captured after a steady-state operating point has been obtained. By default, the simulation result contains all simulation steps that the solver makes. This can be controlled with the solver options OutputTimes and OutputTimesOption, where OutputTimes is a double vector and OutputTimesOption is a string as described in Tab. 19.

For an AC Sweep, an Impulse Response Analysis or a Multitone Analysis, the command returns a struct consisting of three fields, F, Gr and Gi. F is a vector that contains the perturbation frequencies of the analysis. The rows of the arrays Gr and Gi consist of the real and imaginary part of the transfer function as defined in the analysis. If the command is called without a return value, a scope window will open and display the Bode diagram of the transfer function.

Running Multiple Simulations or Analyses in Parallel

Instead of a single optStruct argument you can also pass a \(1 \times N\) cell array of option structures to the simulate and analyze commands:

plecs('simulate', optStructs)
plecs('analyze', analysisName, optStructs)

PLECS will then automatically distribute the individual simulations or analyses to the CPU cores available on your computer. After completion, the commands return a \(1 \times N\) cell array containing the individual result structs or – in case of a runtime error – a string with the error message. To avoid memory problems when running a large number of parallel simulations, you can define an appropriate OutputTimes vector in the SolverOpts struct in order to reduce the number of data points.

Additionally, you can define a callback function that is called whenever an individual simulation or analysis has completed. The arguments of this callback function are the index of the corresponding option set in the input cell array and the result of the simulation or analysis. The return value of the callback function is stored in the output cell array instead of the simulation or analysis result.

The following code example shows how such a callback function can be used to replace the simulation result with a single aggregated value (the maximum value of a certain output signal).

% Aggregate the simulation results in a callback function.
function result = callback(index, result)
   if isstruct(result)
      % If the simulation succeeded,
      % replace the simulation result with
      % the maximum value of the first output signal.
      result = max(result.Values(1,:));
   end
end

out = plecs('simulate', optStructs, ...
            @(index, result) callback(index, result));

The notation using an anonymous function handle is due to a technical limitation of Octave 4.4 regarding nested functions.

Example Script

The following script runs a parameter sweep by setting the variable varL to the values in inductorValues. It is used in the demo model BuckParamSweep.

mdlVars = struct('varL', 50e-6);
opts = struct('ModelVars', mdlVars);

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 is embedded into another struct named opts, which will be used later to initialize the simulation parameters.

Inside the for-loop each value of inductorValues is assigned successively to the structure member variable varL. A new simulation is started, the result is saved in variable out for post-processing. By holding the trace in the scope the scope output will remain visible when a new simulation is started; the scope path uses a dot to reference the current model (see Path Substitution). The name of the trace is the inductance value.

The script then searches for the peak current in the simulation results and outputs the value and the time, at which it occurred, in the Octave Console.

RPC Interface in PLECS Standalone

The RPC interface allows you to control PLECS Standalone from an external program. PLECS acts as an HTTP server which processes XML-RPC or JSON-RPC requests from clients. PLECS automatically determines the actual protocol used by a client from the request and sends the response using the same protocol.

The RPC interface in PLECS is disabled by default. It must be enabled in the PLECS preferences before a connection can be established. The TCP port to use can also be configured in the PLECS preferences.

Note

RPC connections to PLECS are only allowed from clients running on the same computer as PLECS. Therefore, the connection should always be initiated using localhost in the server URL.

Usage Examples

The code examples in this section assume that PLECS is configured to use TCP port 1080 for RPC.

Using XML-RPC in Python

The following Python 3 code initializes an XML-RPC client for PLECS:

import xmlrpc.client
proxy = xmlrpc.client.ServerProxy("http://localhost:1080")

Using JSON-RPC in MATLAB

To facilitate interaction between PLECS Standalone and MATLAB, Plexim provides a MATLAB class that can be downloaded from our GitHub matlab-jsonrpc repository. After copying the class file jsonrpc.m to your MATLAB path, you can initialize a JSON-RPC client for PLECS as follows:

proxy = jsonrpc('http://localhost:1080')

Overview of RPC Commands

Commands for PLECS start with plecs followed by a dot. If you are using a Python or MATLAB client as described above, you invoke a command by appending it to the proxy object using a dot, e.g.:

proxy.plecs.load('C:/path/to/myModel.plecs')

Opening and Closing a Model

The command

plecs.load(mdlFileName)

opens the model with the given mdlFileName. The filename should contain the absolute path to the file.

The command

plecs.close(mdlName)

closes the model with the given name. The model will be closed unconditionally without being saved, even if it has unsaved changes.

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 componentPath as a string. If parameter is omitted, a struct array with all available parameters is returned.

plecs.set(componentPath, parameter, value)

sets the value of parameter of the PLECS component indicated by the componentPath to value.

Handling of Traces in Scopes

plecs.scope(scopePath, 'HoldTrace')
plecs.scope(scopePath, 'HoldTrace', traceName)

saves the values of the last simulation to a new trace in the scope indicated by 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)

removes the trace named traceName from the scope indicated by the scopePath.

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 later reference. If fileName is not an absolute path, it is interpreted relative to the model file that contains the scope.

plecs.scope(scopePath, 'LoadTraces', fileName)

Loads the trace data from the file fileName into the scope at scopePath. If fileName is not an absolute path, it is interpreted relative to the model file that contains the scope.

The scopePath is the path to the scope within the model including the model name, e.g. 'DTC/Mechanical'. To access Bode plots from the analysis tools, use the model name followed by '/Analyses/' followed by the name of the analysis, e.g. 'BuckOpenLoop/Analyses/Control to Output TF (AC Sweep)'.

Running a Simulation

The command

plecs.simulate(mdlName)
plecs.simulate(mdlName, optStruct)

runs a simulation of the model named mdlName. The optional argument optStruct can be used to override model parameters and solver options; for more information about this struct see section Scripted Simulation and Analysis Options.

If any outports exist on the top level of the simulated model, the command returns a struct consisting of two fields, Time and Values. Time is a vector of simulation time stamps. Values is an \(m \times n\) array containing the output values, where \(m\) is the number of time stamps and \(n\) is the number of output signals. The order of the signals is determined by the port numbers.

By default, the simulation result contains all simulation steps that the solver makes. This can be controlled with the solver options OutputTimes and OutputTimesOption, where OutputTimes is a double vector and OutputTimesOption is a string as described in Tab. 19.

Note

Running a simulation is a blocking command. The RPC server can execute only one blocking command at a time and will answer requests to execute a second blocking command with an error message. If you want to run multiple simulations in parallel via RPC, see Running Multiple Simulations or Analyses in Parallel (RPC).

Running an Analysis

The command

plecs.analyze(mdlName, analysisName)
plecs.analyze(mdlName, analysisName, optStruct)

runs the analysis named analysisName in the model named mdlName. The optional argument optStruct can be used to override model parameters; for detailed information see section Scripted Simulation and Analysis Options.

For a Steady-State Analysis, if any outports exist on the top level of the simulated model, the command returns a struct consisting of two fields, Time and Values as described above. The signal values at the outports are captured after a steady-state operating point has been obtained. By default, the simulation result contains all simulation steps that the solver makes. This can be controlled with the solver options OutputTimes and OutputTimesOption, where OutputTimes is a double vector and OutputTimesOption is a string as described in Tab. 19.

For an AC Sweep, an Impulse Response Analysis or a Multitone Analysis, the command returns a struct consisting of three fields, F, Gr and Gi. F is a vector that contains the perturbation frequencies of the analysis. The rows of the arrays Gr and Gi consist of the real and imaginary part of the transfer function as defined in the analysis.

Note

Running an analysis is a blocking command. The RPC server can execute only one blocking command at a time and will answer requests to execute a second blocking command with an error message. If you want to run multiple analyses in parallel via RPC, see Running Multiple Simulations or Analyses in Parallel (RPC).

Running Multiple Simulations or Analyses in Parallel (RPC)

Instead of a single optStruct argument you can also pass a list of option structures to the simulate and analyze commands:

plecs.simulate(mdlName, optStructs)
plecs.analyze(mdlName, analysisName, optStructs)

PLECS will then automatically distribute the individual simulations or analyses to the CPU cores available on your computer. After completion, the commands return a list containing the individual result structs or – in case of a runtime error – a string with the error message. To avoid memory problems when running a large number of parallel simulations, you can define an appropriate OutputTimes vector in the SolverOpts struct in order to reduce the number of data points.

Example Script

The following Python script establishes an XML-RPC connection, loads a model and simulates it twice. The scope output from each simulation is preserved by holding the traces in the scope.

import xmlrpc.client
proxy = xmlrpc.client.ServerProxy("http://localhost:1080")

proxy.plecs.load("C:/Models/BuckParamSweep.plecs")
proxy.plecs.scope('BuckParamSweep/Scope', 'ClearTraces')

opts = {'ModelVars' :  { 'varL' : 50e-6 } }
result = proxy.plecs.simulate("BuckParamSweep", opts)
proxy.plecs.scope('BuckParamSweep/Scope',
                  'HoldTrace', 'L=50uH')

opts['ModelVars']['varL'] = 100e-6;
result = proxy.plecs.simulate("BuckParamSweep", opts)
proxy.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 RPC, you can pass an optional argument optStruct in order to override parameter settings defined in the model. This enables you to run simulations for different scenarios without having to modify the model file.

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 you choose whether the results of a simulation or analysis should be returned as a RPC struct (Plain) or in binary form using the MAT-file format (MatFile). The binary format is much more efficient if the result contains many data points, but the client may not be able to interpret it, so the default is Plain.

ModelVars

The optional field ModelVars is a struct variable that allows you to override variable values defined by the model initialization commands. Each field name is treated as a variable name; the field value is assigned to the corresponding variable. Values can be numerical scalars, vectors, matrices or 3d arrays or strings.

The override values are applied after the model initialization commands have been evaluated and before the component parameters are evaluated as shown in Fig. 117.

../_images/simulation_script.svg — Fig. 117 Execution order for Simulation Scripts (left) and RPC (right)

SolverOpts

The optional field SolverOpts is a struct variable that allows you to override the solver settings specified in the Simulation Parameters dialog. Each field name is treated as a solver parameter name; the field value is assigned to the corresponding solver parameter. Tab. 18 lists the possible parameters.

Table 18 Solver Options in Scripted Simulations
Parameter	Description
`Solver`	The solver to use for the simulation. Possible values are `auto`, `dopri`, `radau` and `discrete` (see PLECS Standalone Parameters).
`StartTime`	The start time specifies the initial value of the simulation time variable \(t\) at the beginning of a simulation, in seconds \((\mathrm{s})\).
`TimeSpan`	The simulation ends when the simulation time has advanced by the specified time span.
`StopTime`	This option is obsolete. It is provided to keep old scripts working. We strongly advise against using it in new code.
`OutputTimes` `OutputTimesOption`	These options control the simulation times that are included in the result of a scripted simulation. See the table below.
`InitialSystemState`	Specifies the initial system state used for the simulation. This will override the System State setting in the simulation parameters (see System State). The system state struct can be retrieved after the completion of a simulation or steady-state analysis using the command plecs('get', mdlName, 'SystemState')
`Timeout`	A non-negative number that specifies the maximum number of seconds (wall-clock time) that a simulation or analysis is allowed to run. After this period the simulation or analysis is stopped with a timeout error. A value of `0` disables the timeout.
`MaxStep`	See the description for Max Step Size in section PLECS Standalone Parameters. This parameter is only evaluated for variable step solvers.
`InitStep`	See the description for Initial Step Size in section PLECS Standalone Parameters. This parameter is only evaluated for variable step solvers.
`FixedStep`	This option specifies the fixed time increments for the solver and also the sample time used for the state-space discretization of the physical model. It is only evaluated for the fixed step solver.
`AbsTol`	See the description for Tolerances in section PLECS Standalone Parameters.
`RelTol`	See the description for Tolerances in section PLECS Standalone Parameters.
`Refine`	See parameter Refine factor in section PLECS Standalone Parameters.

Table 19 Control of Output Times in Scripted Simulations
OutputTimesOption	Interpretation of OutputTimes
`specified`	The simulation result contains only the simulation times specified in the `OutputTimes` vector. This is also the default behavior if only the vector `OutputTimes` is provided and `OutputTimesOption` is omitted.
`additional`	The simulation result contains the simulation times specified in the `OutputTimes` vector in addition to all simulation steps that the solver makes.
`range`	The simulation result contains all simulation steps that the solver makes within the time span from `OutputTimes(1)` to `OutputTimes(end)`. If the vector `OutputTimes` contains more than two values, the additional simulation times are also included in the result.

AnalysisOpts: For an analysis the optional field AnalysisOpts is a struct variable that allows you to override the analysis settings defined in the Analysis Tools dialog. Each field name is treated as an analysis parameter name, the field value is assigned to the corresponding analysis parameter. The following tables list the possible parameters:

Table 20 Analysis Options in Scripted Analyses
Parameter	Description
`TimeSpan`	System period length; this is the least common multiple of the periods of independent sources in the system.
`StartTime`	Simulation start time.
`Tolerance`	Relative error tolerance used in the convergence criterion of a steady-state analysis.
`MaxIter`	Maximum number of iterations allowed in a steady-state analysis.
`JacobianPerturbation`	Relative perturbation of the state variables used to calculate the approximate Jacobian matrix.
`JacobianCalculation`	Controls the way the Jacobian matrix is calculated (`full`, `fast`). The default is `fast`.
`InitCycles`	Number of cycle-by-cycle simulations that should be performed before the actual analysis. This parameter can be used to provide the initial steady-state analysis with a better starting point.
`ShowCycles`	Number of steady-state cycles that should be simulated at the end of an analysis. This parameter is evaluated only for a steady-state analysis.
`FrequencyRange`	Range of the perturbation frequencies. This parameter is evaluated only for a small-signal analysis.
`FrequencyScale`	Specifies whether the sweep frequencies should be distributed on a `linear` or `logarithmic` scale. This parameter is evaluated only for a small-signal analysis.
`AdditionalFreqs`	A vector specifying frequencies to be swept in addition to the automatically distributed frequencies. This parameter is evaluated only for a small-signal analysis.
`NumPoints`	The number of automatically distributed perturbation frequencies. This parameter is evaluated only for a small-signal analysis.
`Perturbation`	The full block path (excluding the model name) of the Small Signal Perturbation block that will be active during an analysis. This parameter is evaluated only for a small-signal analysis.
`Response`	The full block path (excluding the model name) of the Small Signal Response block that will record the system response during an analysis. This parameter is evaluated only for a small-signal analysis.
`AmplitudeRange`	The amplitude range of the sinusoidal perturbation signals for an ac sweep. This parameter is evaluated only for an ac sweep.
`Amplitude`	The amplitude of the discrete pulse perturbation for an impulse response analysis. This parameter is evaluated only for an impulse response analysis.
`MaxNumberOfThreads`	The maximum number of parallel threads that may be used during the analysis.
`ShowResults`	Specifies whether to show a Bode plot after a small-signal analysis. This parameter is evaluated only for a small-signal analysis.

Command Line Interface in PLECS Blockset

PLECS Blockset offers a Command Line Interface (CLI) to access component and circuit parameters from scripts or directly from the MATLAB command line. The command syntax is

plecs(cmd, parameter1, parameter2, ...)

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 componentPath as a string. If parameter is omitted, a struct array with all available parameters is returned.

plecs('set', componentPath, parameter, value)

sets the value of parameter of the PLECS component indicated by the componentPath to value.

The special parameter CurrentCircuit can be used to query the path to the current 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 Information, Warnings and Errors in Initialization Commands

During the execution of mask initialization commands the following commands add entries in the Diagnostics window:

plecs('info', infoMessage)
plecs('warning', warningMessage)
plecs('error', errorMessage)

Notice that the plecs('error', errorMessage) command by itself does not cause an early exit of the execution of the mask initialization commands, so it should generally be followed by a return statement to avoid subsequent errors.

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 indicated by the scopePath. If given and unique, traceName is used as the name for the new trace, otherwise a default name is assigned. In both cases the method returns the name given to the trace.

plecs('scope', scopePath, 'RemoveTrace', traceName)

removes the trace named traceName from the scope indicated by the scopePath.

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 later reference. If fileName is not an absolute path, it is interpreted relative to the model file that contains the scope.

plecs('scope', scopePath, 'LoadTraces', fileName)

Loads the trace data from the file fileName into the scope at scopePath. If fileName is not an absolute path, it is interpreted relative to the model file that contains the scope.

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) for the cursor positions t1 and t2. Valid analysis names are delta, min, max, absmax, mean, rms and thd. For more information about scope cursors see the Cursors section.

The return value is a struct with the two fields time and cursorData. The field time is the vector [t1, ts]. The field cursorData is a nested cell array where the outer index corresponds to the number of plots in the scope and the inner index corresponds to the number of signals in a plot. Each cell is a struct with the fields cursor1 and cursor2 with the signal values and additional fields for the analyses that you have specified. If the scope has multiple traces, 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 2 for the third trace of the second signal in the first plot, you write

data.cursorData{1}{2}.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 values to the text file fileName. If fileName is not an absolute path, it is interpreted 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 absolute path, it is interpreted relative to the model file that contains the scope. The file format is determined automatically from the file extension. The fileName argument may be followed by one or more name/value pairs to override settings defined in the scope as described in Tab. 17.

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:

[success, message] = plecs('checkout')

If the check-out succeeds, the return variable success will be set to 1 and message will be an empty string. Else, success will be set to 0 and message will contain a detailed error message. When called without left-hand side arguments, the command will raise a MATLAB error upon an unsuccessful check-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.