Rltool for Scilab:
A GUI based tool for SISO system design
Version 1.6 (July 2005)

Ishan Pendharkar
Department of Electrical Engineering,
Indian Institute of Technology Bombay
Mumbai -- 400076, INDIA.
E-mail: ishan@ee.iitb.ac.in, ishan@iitbombay.org

Chapter 1  Overview of Rltool for Scilab

Welcome to help pages of RLTOOL, version 1.6. The latest details about RLTOOL are available at:
http://www.ee.iitb.ac.in/uma/~ ishan/scilab/rltool.htm
If you are using Rltool, you are requested to send a e-mail with the subject ``rltool'' to ishan@ee.iitb.ac.in. Your e-mail address will not be kept confidential.

1.1  Description

Rltool for Scilab is a graphics based tool for designing compensators for SISO continuous plants.

1.2  Targetted users

The intention behind developing this package is to provide a free and easy to use tool for students taking a first course in control engineering. Learning is more fun if computer based teaching is used to supplement classroom lectures. It is intended to make Rltool for Scilab as simple and user friendly as possible and yet have some powerful and innovative features.

1.3  Features

  1. Handle single input single output (SISO) continuous time transfer functions.
  2. Choose between Time Domain and Frequency Domain Design.
  3. Edit of poles and zeros at the click of a mouse.
  4. View various openloop and closed loop plots.
  5. Save and Load plants as required.

1.4  How to install Rltool for Scilab

1.4.1  For Linux users

I assume that you have obtained the file rltool1.*.tar.gz and have saved it at the location ``PATH'' on your computer. For example, I have downloaded the file in my home directory /home/ishan , hence PATH = /home/ishan
  1. Unzip the zipped file. The fact that you are reading this README shows you completed step 1 :) This has generated a directory called rltool in my home directory. So my PATH is /home/ishan/rltool

  2. Start scilab

  3. At the scilab prompt, type
    --> exec /home/ishan/rltool/builder.sce
    you need to do this only ONCE. This ``compiles'' the *.sci files and generated binary files.

  4. To ``load'' rltool into Scilab, type the following at the Scilab prompt
    --> exec /home/ishan/rltool/loader.sce
    you will need to ``load'' rltool every time you start a FRESH scilab session, or issue an explicit ``clear'' instruction at the Scilab prompt

  5. Type rlt() to start using rltool

  6. If you are the root, you may want to ``build'' rltool once so that multiple users can access it simultaneously.

1.4.2  For Windows users

I assume that you have obtained the file rltool1.*.tar.gz and have saved it at the location ``PATH'' on your computer. For example, I have downloaded the file in my home directory C:\ishan , hence PATH = C:\ishan
  1. Unzip the zipped file. The fact that you are reading this README shows you completed step 1 :) This has generated a directory called rltool in my home directory. So my PATH is C:\ishan\rltool.

  2. Start scilab

  3. At the scilab prompt, type
    --> exec C:\ishan\rltool\builder.sce
    you need to do this only ONCE. This ``compiles'' the *.sci files and generated binary files.

  4. To ``load'' rltool into Scilab, type the following at the Scilab prompt
    --> exec C:\ishan\rltool\loader.sce
    you will need to ``load'' rltool every time you start a FRESH scilab session, or issue an explicit ``clear'' instruction at the Scilab prompt
  5. Type rlt() to start using rltool
  6. If you are the administrator, you may want to ``build'' rltool once so that multiple users can access it simultaneously.

Chapter 2  Detailed Help on usage

2.1  Starting RLTOOL

Load the rltool library as per instructions in the README file. If the library loads properly the following message is displayed on Scilab prompt:
mode(-1);
rltool is loaded. Type "rlt()" to start rltool-1.6
Type ``rlt()'' to start this programme.

2.2  Rootlocus

On typing ``rlt()'', the you will be prompted to either select a new rltool session or load a previous saved file. If a new session is selected, the you will be prompted to enter the transfer function as numerator / denominator in the variable 's'. Rltool will automatically load the plant you were working with in the previous session of rltool. Click ``Ok'' to confirm this plant. You may wish to edit the plant, in that case type in the new plant and click ``Ok''.

A Rootlocus plot of the transfer function is displayed. Open loop poles are shown by crosses and zeros by circles. This window is shown in Figure (2.1). The various menus in the window are:
  1. ``File'': Load, save or print the rootlocus.
  2. ``Zoom'': Select a part of the rootlocus using the mouse and zoom onto it.
  3. ``UnZoom'': See the entire rootlocus (remove Zoom, if any).
  4. ``Grid'' : Menus under this head control the apperance of grids on all plots. These are:
    1. ``On'': Put a cartesian grid on all plots in the current session.
    2. ``Off'': Remove (if already present) a cartesian grid from all plots in the current session.
    3. ``Zeta/Wn'': Plot a constant z and wn curve on the rootlocus for a given value of z and wn.
    4. ``sgrid'': Plot a constant z and wn grid on the rootlocus.
  5. ``Response'': Various plots and responses can be viewed.
    1. ``Closed loop'': Closed loop responses for a given gain. More details are given in Section 2.6.
    2. ``Nyquist'': Nyquist plot.
    3. ``Nichols'': Nichols chart.
    4. ``Details'': Numerical values of poles and zeros, gain etc.
    5. ``Popov'': The Popov-plot of the system.
  6. ``Design'': There are two modes available in Rltool, namely Rootlocus and Frequency.
    1. ``Root Locus'': This is the default mode. Most options here are with a view towards time-domain design.
    2. ``Frequency'': This mode is still under development. Currently very limited options are available, like bode plots, sensitivity plots etc.
  7. ``Plant'': This menu provides utilities for editing the system. More details are given in Section 2.5.
  8. ``Save'': Save the current session and/or load previous sessions.
  9. ``Settings'': This menu provides all settings available to the user. More details are given in Section 2.9.
  10. ``Help'': A short online help is included on most topics. Click the sub-menu under this head to see the help. For example, help on rootlocus is included in ``Help®Root Locus''.
  11. ``Measure'': This feature allows a user to ``measure'' the gain at a point on the rootlocus. The user is first prompted to select a point. If this point is on the rootlocus, relevant information is displayed/updated.

2.3  The control center

Immediately after starting rltool, a user will see the control center GUI. A user can use and configure most features using this simple GUI. Following is a brief description of features:
  1. Menus: Menus are mostly similar to the ones described in Section 2.2.
  2. ``Plant'' button: Click on this button to edit the current transfer function.
  3. ``Gain'' button: This displays the current gain selected by the user.
  4. Gain set (text mode): This field displays a message ``Type Gain Here'' by default. A user can type in a positive real valued gain in this field. Click on ``Ok'' to load this gain into Rltool.
  5. Slider: A user can select gain with a slider. The value of the gain selected is shown immediately above the slider.
  6. Max. Gain: This popup menu lets a user select the maximum allowed gain for the rootlocus. Options are 10, 50, 100, 500,...100,000. A user may also set the maximum allowed gain to a different value using the Settings menu.
  7. Exit button: Click on this button to quit rltool.
The most convenient way to use Rltool is to set a gain using the slider. The current gain is displayed above the slider bar and also in the ``gain'' button on the control center. Also, a window containing the following closed loop plots is continuously updated:
  1. Closed loop pole(s) and zero(s)
  2. Closed loop unit step response.
  3. Closed loop bode plot.
  4. Sensitivity plot
Note that ``closed loop plant'' may include either ``gain in feedback'' or ``gain in forward path''. Please see the ``Settings'' section for how to do this. A user can also set the units (hz or rad/sec) for bode and sensitivity plots. Please see the section on "Settings".

2.4  Frequency design

Rltool comes with two design modes... time domain (rootlocus) and frequency domain. You can select the frequency domain mode by clicking on ``Design ®Frequency''. You will see the frequency magnitude plot of the open loop transfer function. The magnitude is shown in decibel and frequency in rad/sec. Click on the plot to determine the magnitude and frequency. The frequency domain part is still under development. It will be a great idea to take up this aspect and design it further! You can ofcourse return to the rootlocus mode by clicking on ``Design ®Root Locus''.

2.5  Editing of Plants

These utilities are provided under the ``Plant'' tab on the main window. In the Root Locus mode, you can edit your plant at the click of a mouse. The following options are provided. The function of most of these should be obvious:
  1. Undo: Undo one change in the (open loop) plant.
  2. Add pole: Select the pole to be added by clicking on the graphics window. If you select a point with nonzero real part, both the point and its complex conjugate are added. That is, if G(s) is the current open loop transfer function and you select a complex point z, the new open loop plant will be
    G(s
    1
    (s-z)(s-z*)
    where z* denotes the complex conjugate of z.
  3. Remove pole: Click on the open loop pole that you want to remove. If you click on a pole with nonzero real part, both the pole and its complex conjugate are removed.
  4. Add zero: Similar to Add pole. Zero(s) are added to open loop transfer function.
  5. Remove zero: Similar to Remove pole. Zero(s) are removed from the open loop transfer function.
  6. Add cascade: You will be prompted to enter a transfer function H(s)=a(s)/b(s). If G(s) is the current transfer function, it is modified to
    G(sH(s)
    You will be prompted to ``accept'' this product. You can edit it if you wish (to truncate some spurious decimal places etc). This command is like a simultaneous addition of pole(s) and zero(s). However, in this case you are required to enter these through the keyboard, instead of using the mouse for the selection.
  7. Remove cascade: is like dividing G(s) by H(s), i.e. the open loop plant is modified to
    G(s)
    H(s)
  8. Edit plant: The current plant is displayed in a dialogue box. You can modify it directly by typing in the appropriate value.

2.6  Closed loop responses

There is a great deal of flexibility in rltool to see various closed loop responses. First you will have to select one ``gain configuration'' out of the possible two. Click on ``Settings ®Gain Configuration''. You will see a selection dialogue box with two choices:

You can choose the gain to be in the forward path as shown in the figure.

This corresponds to the option ``K in forward path''. You can choose to put ``K in the feedback path''. However, ``K in forward path'' is the default.

To see closed loop responses, click on ``Response ®Closed Loop''. You will be prompted to click on a point of the rootlocus to select the ``operating point'' at which you want to see the closed loop response. Once you select the operating point, you are done!

Rltool calculates the closed loop transfer function for the configuration you have selected, i.e. the closed loop transfer function for ``K in forward path'' is
G K
1+G K
and the closed loop transfer function for ``K in feedback path'' is
G
1+GK
You will see a selection menu that shows the following:
  1. The gain corresponding to operating point you selected.
  2. Whether the closed loop system is stable or unstable.
  3. Impulse response: Click here to see the impulse response!
  4. Step response selection: Unit step response is displayed. A ``details'' button in the step response also displays parameters such as percent overshoot, rise time, settling time, z corresponding to second order approximation etc.
  5. Ramp response: Unit ramp response.
  6. Arbitrary input: You can enter piece-wise linear, single valued inputs through a graphics window. Use the mouse (press left button and drag) to ``draw'' this input. There are a host of features like ``undo'', ``abort'' etc which can be used. You can also resize your window to suit the range of your input. Click ``Edit ®Ok'' when you are done. If your input is single-valued, you will see the response of the closed loop system to this input.
  7. Sinusoidal input: The input is of the form
    A sin (w t)
    Output is simulated, by default for one of the input and is plotted. The default settings are A=1 and w=1   rad/sec. These can be changed by clicking on ``Settings'' button in the sinusoidal response window. You must close this window to return to the response selection menu.
  8. Frequency response (bode plot) of closed loop system. There is a choice in the units (Rad/sec) or (Hz). These are available in ``Options'' menu in the frequency response window.
  9. Sensitivity plot: Sensitivity is defined as the transfer function between the input u(t) and the error e(t). For the system shown in the above figure, the sensitivity can be found to be
    1
    1+kG(s)
    This transfer function is evaluated on the imaginary axis (by substituting s=iw) and the resulting (magnitude) plot is shown for various values of w. Options are similar to above.
Click on ``cancel'' to close the response selection menu and return to the main window of rltool.

2.7  Other responses

2.7.1  Nyquist plot

Nyquist plot of the open loop plant G(s) can be seen by clicking on ``Response ®Nyquist''. The gain and phase margin is displayed on the plot. If you find that your plot is too coarse or cluttered, you can change the minimum and maximum frequency in ``Settings ®Nyquist-Nichols plot''. The frequency units can be changed in ``Settings ®Frequency units''.

2.7.2  Nichols plot

Nichols plot for G(s) is obtained by selecting ``Response ®Nichols''. If the grid (in the main menu) is set to ``on'' you will see the logarithmic grid superimposed on the Nichols plot. Here too, you can select the desired frequency units.

2.7.3  Popov plot

The Popov plot can be used to predict the stability of the closed loop system with a sector bound nonlinearity in loop. We plot real part of G(iw) on the real axis and w Imaginary   G(iw) on the imaginary axis. A simple construction then gives the range of the ``Popov sector'' and the ``multiplier''. Please see any standard text on nonlinear systems for more details on the Popov plot.

2.8  Saving and loading plants

To save your current plant, click on ``Save ®Save''. You will be prompted to enter the filename to which the plant should be written.

To load an existing plant from a file, click on "Save ®Load". You will be prompted to enter the filename.

You must have the appropriate read/write permissions to do this operation.

2.9  Settings

We now look at the various settings that a user can access:
  1. Rootlocus: Set the maximum allowed gain, Kmax in rootlocus. The rootlocus is plotted for the gain range (0,Kmax).
  2. Magnitude plot: Set the minimum frequency, maximum frequency and the frequency step for the (open loop frequency) Magnitude plot. The unit for the frequency is rad/sec.
  3. Nyquist-Nichols plot: Frequency settings similar to above, for Nyquist plot and Nichols plot.
  4. Bode plot: Frequency settings for the (closed loop) Bode plot.
  5. Dynamic response: Set the maximum simulation time and the timestep for all dynamic responses (impulse, step, ramp, arbitrary input, sinusoidal input).
  6. Sensitivity plot: Frequency settings for the sensitivity plot.
  7. Graphics attributes: Graphics attributes like font, colour etc can be set from here.
  8. Gain configuration: Two options are possible for using rltool
    (a) Gain, K, is in the forward path.
    (b) Gain is in the feedback path.
    The default is (a). Selecting a particular gain configuration also results in that being displayed in the control center. For example, figure 2.2 shows that the current mode is ``Gain in forward path''.
  9. Browser path: Applicable only for *nix systems. You can set a default browser path for viewing this HTML manual while running rltool. The default browser is mozilla (only because this browser happens to be bundled into most *nix systems that I have seen). You can, for instance, type the full path to konqueror, or Opera, or any other web browser. This browser will be used to open the HTML manual while running rltool. Also see ``Help ®HTML manual''

2.10  Help

A short online help is provided on some topics.

Chapter 3  Some FAQs

Q. Can I see this HTML manual from within RLTOOL?
A. On *nix systems, you can set your default browser path in ``Settings ®browser path''. Click on ``Help ®HTML manual'' to load this html manual in your favourite browser. I do not know how to implement this for windows. If you do, please get in touch with me.

Q. What sort of plants does RLTOOL handle?
A. RLTOOL, ver 1.6 handles real valued SISO continuous time plants (proper scalar transfer functions).

Q. How do I enter transfer functions for RLTOOL?
A. The default value is 1/s. You can change this by editing the numerator and denominator. You should enter these as polynomials in s. For example, 3s2+2s+5 should be entered as 3*s2+2*s+5.

Q. My rootlocus plot shows "hanging" incomplete lines, what should I do?
A. You need to increase the maximum allowable gain. To do this, write the appropriate value in Settings --> Rootlocus.

Q. I can't make out details on my rootlocus plot, what should I do?
A. Use the zoom utility for a bigger picture. Alternately, reduce the maximum allowed gain and you would get a more detailed plot.

Q. Though I don't click on a open loop pole/zero, the mouse handler reads the click as a open loop pole/zero, what should I do?
A. This happens because of tolerances set in RLTOOL. You can change the tolerances in Limits() macro. Alternately, ZOOM the region before selecting the point.

Q. Why is my Nyquist plot drawn only for positive frequencies? Why is it coarse?
A. This is the default. You can put the lower limit of frequency as -1000 Hz for instance and you would get a symmetric Nyquist plot. If it is too coarse, reduce the step size. This can be found in Settings --> Nyquist plot.

Q. I can't UNDO changes to my plant, what should I do?
A. RLTOOL requires to save your configuration details in a file called .rltoolcfg.sci. This is located in your present working directory. If you don't have write permissions in your present working directory, a warning message is displayed and you can't use the UNDO feature.

Q. Which dynamic responses can I see?
A. You can view the following CLOSED LOOP responses: IMPULSE, STEP, RAMP, ARBITRARY INPUT. Click on Response --> Dynamic to select the "operating point" on the rootlocus. You will then see a pop-up window which will prompt you to select the desired plot.

Q. Can I simulate with any arbitrary inputs?
A. No! At present you can simulate with inputs that are (1) piece-wise linear (2) continuous (3) single-valued. You will receive an error message if your input is not of this type.

Q. Can I change the size of the plotting frame in defining the arbitrary input?
A. Yes, click on Edit->size in the plotting frame. Enter the required x and y co-ordinates. The default is x=[0,1], y=[0,1]. You may change these as required.

Q. My step/ramp/impulse response is incomplete/coarse, what should I do?
A. You need to set parameters for maximum time for incomplete response. For a finer resolution, decrease the step size. These settings are located at Settings --> Dynamic response.

Q. Sometimes I see an error message while plotting the step response/ frequency response why is this? What should I do about it?
A. This happens when the pole and zero are too close by and the mouse handler can't distinguish between the two points. When pole and zero are close by, zoom the region by the ZOOM utility before selecting a point (gain).

Q. What should I do if I get a warning/error message?
A. Look up the quick reference on errors or warnings in RLTOOL. It will probably help you remove your error.

Q. I think I have found a bug, what should I do?
A. Please mail the bug report to ishan[AT]iitbombay.org. I would appreciate if you also let me know the remedy. It will help improve RLTOOL.

Q. My RLTOOL crashes , what should I do?
A. Mail your "plant" along with the explicit details to the author. It will help improve RLTOOL.

Q. I would like the feature XYZ to be in RLTOOL, what should I do?
A. Code it into RLTOOL and submit a fresh update. Alternately, let me know about it by e-mail. I shall try to add that feature sometime...

END OF FAQ.

Chapter 4  Error and warning messages

  1. ``Error Entering input'': There is an error while entering numerator and denominator polynomials. Ensure that the entered format is correct. For example, a polynomial s2+3s+2 should be entered as s2+3*s+2.
  2. ``Numerator and denominator are equal'': This error message is displayed when all poles and zeros of your transfer function cancel each other and you get a constant, memoryless system.
  3. ``plzr() function couldnot handle your transfer function. See Scilab error code 60'': This is typically displayed when you have very high gains in the system (order of 1e10) and calculations are very sensitive. Reduce the maximum permissible gain of the rootlocus plot.
  4. ``Warning! I need write permission in <directory name>. Please change your present working directory'':This warning is displayed when your present working directory is one in which you don't have a write permission. Set your appropriate working directory using "Settings->PWD".
  5. ``Warning! Couldnot undo changes. No previous data available'': This warning is displayed when you don't have read /write permission in your present working directory. Solution is as above.
  6. ``Sorry! I couldnot plot your step/ramp/impulse response. Due to numerical tolerances a pole zero cancellation has occured. Please reselect the point'': This error message is displayed when the closed loop transfer function is not proper (due to spurious pole-zero cancellations). Please reduce the maximum permissible gain in Settings->Rootlocus. or zoom the branch of the rootlocus before selecting the point
  7. ``Sorry! I couldnot plot your frequency response. Due to numerical tolerances a pole zero cancellation has occured. Please reselect the point''. Same as above.
  8. ``Error entering input. Input is not single valued'': While defining the arbitrary input, ensure that (1) input is piecewise linear (2) continuous (3) Single valued. If you don't ensure these, you will see this error. You will be prompted to select the response again.
  9. ``Error Saving Plant. Ensure that you have write permissions'': You don't have write permission in your pwd.
  10. ``Error loading Plant. Ensure that the file exists and you have read permission'': Either the file you are asking for doesn't exist or you don't have read permission. Change your pwd() or check the filename.

Chapter 5  Acknowledgment

Since version, 1.2 the following modified codes provided by Dr. Jos Paulo Vilela Soares da Cunha have been included. These enable a user to plot various frequency domain plots (Bode, magnitude, Nyquist, Nichols etc) in both Hz. and rad/sec. (as opposed to Hz only in native Scilab functions). Users may address queries about these codes to the author at jpaulo@ieee.org
  • Bode
  • Nyquist
  • Gain
  • Nichols

To make this toolbox self contained, the following relevant files from Stephane Mottlet's Graphics toolbox have been added the the macros/ folder.
loadDefaultGraphicState.sci
loadGraphicState.sci
saveGraphicState.sci
graphinit.sci
fig.sci

Prof. John Bechhoefer (Simon Fraser University) reported several bugs and gave excellent ideas for further improvement.


This document was translated from LATEX by HEVEA.