Contents
MORLAB Demo: Frequency Evaluation and Visualization
This demo script contains the handling of the frequency evaluation and visualization functions ml_bodemag, ml_frobeniusplot and ml_sigmaplot.
% % This program is free software: you can redistribute it and/or modify % it under the terms of the GNU Affero General Public License as published % by the Free Software Foundation, either version 3 of the License, or % (at your option) any later version. % % This program is distributed in the hope that it will be useful, % but WITHOUT ANY WARRANTY; without even the implied warranty of % MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the % GNU Affero General Public License for more details. % % You should have received a copy of the GNU Affero General Public License % along with this program. If not, see <http://www.gnu.org/licenses/>. % % Copyright (C) 2006-2019 Peter Benner, Steffen W. R. Werner %
General Handling
MORLAB provides three different functions for frequency evaluation:
- ml_sigmaplot plotting the largest singular value of the transfer function over the imaginary axis
- ml_frobeniusplot plotting the Frobenius norm of the transfer function over the imaginary axis
- ml_bodemag plotting the absolute values of the single transfer function entries over the imaginary axis
For a better demonstration, we load a prepared datafile containing matrices of a standard unstable state-space system:
if exist('OCTAVE_VERSION', 'builtin') orig_warn = warning('off', 'Octave:data-file-in-path'); load morlab_data_std_unstab.mat; warning(orig_warn); else load morlab_data_std_unstab.mat; end
For using the plot functions, we need to put the system matrices either into a struct or, if the System Control Toolbox (control package) is installed, an ss object. For simplicity we decide here for the struct version.
sys = struct( ... 'A', A, ... 'B', B, ... 'C', C, ... 'D', D);
We start with the most simplest way of using the visualization by just calling the sigma plot function.
ml_sigmaplot(sys);

This produces a sigma plot of the function in the default frequency range of [1e-4, 1e+4] rad/sec. This range as well as the units of frequency and magnitude scale can be changed by optional parameters given in an option struct. For example, we want to have Hz as frequency unit and a linear scale for the magnitude. We creat the option struct
opts = struct( ... 'FreqUnit', 'Hz', ... 'MagScale', 'linear');
Now we call again the plot function but with the changed parameters:
ml_sigmaplot(sys, opts);

An important feature of the frequency evaluation functions are the output arguments. For the moment, we suppress the creation of the frequency plot and consider just the output arguments:
[w, mag, tf, info] = ml_sigmaplot(sys, struct('ShowPlot', 0));
We shortly explain the meaning of those outputs:
- w contains the frequency points in rad/sec or Hz where the transfer function was evaluated,
- mag contains the computed magnitudes, the results differ for the different plot functions,
- tf contains the computed transfer function evaluations,
- info is a struct with the number of computed frequency points and possibel error values between given systems, if this option was used.
Ways of Frequency Sampling
An important feature of the frequency evaluation functions is the way of determining the points for sampling. Here MORLAB supports different ways of sampling. First, the default way of sampling is the adaptive one. This can also be activated by setting the parameter FreqSample
opts = struct('FreqSample', 'adapt');
By default, the adaptive mode uses 3 initial equidistant points and refines the grid then adaptively to reach a certain tolerance given by the parameter AccuracyTol. To make the adaptive sampling visible, we change the line style of the plot to points by
opts.LineSpecs = '.';
ml_sigmaplot(sys, opts);

One can see that in regions with more system behavior and difficult curves, the method is automatically placing more points. The initial points can be controlled by setting the parameter InitPoints to either an integer for the number of equidistant initial points or a vector of initial frequencies.
To change the sampling to an equidistant one set
opts.FreqSample = 'equal';
Now the parameter MaxPoints, which sets an upper bound for the number of frequency points in the adaptive setting, is used as exact number of equidistant points.
opts.MaxPoints = 200; ml_sigmaplot(sys, opts);

A third way of sampling is just giving a vector of frequency points to the FreqSample parameter:
opts.FreqSample = logspace(-2, 2, 50); ml_sigmaplot(sys, opts);

Multiple Systems and Error Plots
Another feature of the MORLAB frequency evaluation functions is the ability to accept multiple systems of different types. The limitations of the systems is the restriction of having the same inputs and outputs. We construct a second system
sys2 = struct( ... 'A', -1, ... 'B', ones(1, 3), ... 'C', ones(2, 1));
Now the function will create to graphs in the plot, for each system one.
ml_sigmaplot(sys, sys2);

If multiple systems are given, the evaluation functions support difference modi. Those allow the computation of absolute and relative error transfer functions based on the given systems. In this case, the first given system is taken as the primary one and all following systems will be substracted from the first one to create the results. Let's compute as an example the relative error plot between sys and sys2.
opts = struct('DiffMode', 'rel'); ml_sigmaplot(sys, sys2, opts);

The magnitude values of the error systems are then given in the info output argument.
Multiple systems can be given either as demonstrated above or in an one-dimensional cell array, where each entry is a system.
ml_sigmaplot({sys, sys2});

Remarks
- All frequency evaluation functions are basically equivalent in use but differ in the computed values and results. Therefore, all examples here work for all the functions in the same way.
- The functions support sparse system matrices by using structs as input arguments.
- The functions support all implemented system types of MORLAB. The underlying system type is automatically determined by the matrices in the ss object or the struct.
See Also