FAQ of shapeit
Frequently Asked Questions on installation and use of ShapeIt.
Questions and answers
Before panicking about some error messages that ShapeIt might return, or being disappointed that you can't seem to make ShapeIt work on your pc: take a deep breath, relax, and read the questions on this page. If you recognize one or some of them, I have some good news: the answers are also on this page! So make sure to read those too...
When running shapeit_setup_runonce Matlab returns all kinds of errors and warnings. Should I be worried?
Yes and no. The good news is that as long as somewhere between all error messages there is a message somewhat like
added C:\Program Files\MATLAB\R2010a\toolbox\shapeit to matlab path
the basic functionality of ShapeIt can be used normally. This means it will open, you can load data and start your loopshaping job. So far so good. However, the error messages during installation indicate that the C-files which come with ShapeIt were not compiled correctly. As a consequence the optimization aid (in the full version) will not work, and you cannot use the "Save to Simulink" button. See the question on compiling how to solve this problem. If you didn't get the "added path" message, ShapeIt will not open from outside its directory, which is discussed in the question on the Matlab path.
I can't open ShapeIt. Why does Matlab return "Undefined function or variable" when I type shapeit?
Matlab returns this error since it cannot locate the ShapeIt directory. This means this directory is not properly added to the Matlab path, which should have been done during installation by running shapeit_setup_runonce. Try to run this function again, and see if it returns something like
added C:\Program Files\MATLAB\R2010a\toolbox\shapeit to matlab path
somewhere (or try to use the pathtool routine in Matlab to do this by hand). If it fails, you probably do not have enough rights within Matlab (you're probably using Vista or 7...). See the first part of the question on compiling to solve this.
ShapeIt doesn't open, it returns the error message "Unrecognized function or variable 'tf'. What should I do?
This Matlab error indicates that a function (in this case tf) in the Control System Toolbox of Matlab cannot be found, most likely because that specific toolbox is not installed on your pc (or you don't have a valid license for it). ShapeIt relies heavily on this toolbox, and hence will not function without it. The solution is thus simple: install the Control System Toolbox (or get a proper license) and then start ShapeIt again.
When I press "Save to Simulink" Matlab returns errors like "S-function 'dleadlag' doesn't exist". Is ShapeIt broken or did I do something wrong?
No, ShapeIt is not broken, and no, you didn't do anything wrong. That is, not now. Something did go wrong during installation of ShapeIt:
- Either the ShapeIt C-files were not compiled; i.e. the S-functions 'dpd', 'dweakint', 'dleadlag', 'dnotch', 'dlowpass1' and 'dlowpass2' that Simulink needs (with extensions like .mexw32 or .mexw64) are physically not on your pc. See the question on compiling for the solution.
- Or when compiling did go right, you didn't add the ShapeIt directory to the Matlab search path. Hence, the S-functions are on your pc, but Matlab cannot find them. Please refer to these previous remarks on the Matlab path. Or simply change your working directory to the ShapeIt directory (although that's only a temporary solution).
Note that ShapeIt itself works perfectly even though you get this error; you're only not able to run the Simulink files that ShapeIt creates (containing so-called DCtools blocks). This shouldn't be a problem though; you know your controller parameters, so you can easily build the controller yourself using the standard Simulink blocks.
The optimization aid doesn't work, as ShapeIt returns error messages. What's going on?
There can be two reasons.
- First, the installation isn't completed as Matlab didn't compile the necessary C-file (in this case costfcn_fast.c). See the question on compiling to solve this.
- Second, you do not have the Genetic Algorithm and Direct Search toolbox installed in Matlab, on which the optimization aid relies. Buy and/or install this toolbox to solve this. There are ideas to replace this toolbox by a free ShapeIt-embedded version somewhere in the far future, but that will probably not help you now...
Remember that ShapeIt can work perfectly without the optimization aid, as it still allows you to use all other functionalities.
Why can't I compile the C-files in the ShapeIt directory?
There can be multiple reasons for this, and they all have to do with your specific Matlab and/or Windows installation. It can be both a matter of rights and the absence of a C-compiler.
-
You do not have sufficient rights
If you receive an error like:
LINK : fatal error LNK1104: cannot open file 'C:\...\toolbox\shapeit\*.mexw64'
C:\PROGRA~1\MATLAB\R2013B\BIN\MEX.PL: Error: Link of '*.mexw64' failed.
Then there is a problem with your writing rights. Since compiling (or mexing) C-files produces binary files (which are placed in your shapeit directory) Matlab requires writing permission. Especially when using windows Vista or Windows 7, it is often forbidden for programs to create such files. To fix this, Matlab needs to be run as administrator. Hence, close Matlab and restart it with admin-rights (for Windows 7: right-click the Matlab executable, select 'properties', select the tab 'Compatiiity' and check the box 'run this program as administrator'), then go to the ShapeIt directory and run shapeit_setup_runonce again. If you still get the original error, move the shapeit folder to a different directory (anything other then 'C:\program files\*' and try again. -
You do not have a Matlab-compatible C-compiler
Of course compiling is only possible if you have a suitable compiler. You can identify (and select) the installed compilers by typing mex -setup in Matlab. Normally, any 32-bits Matlab for Windows comes with the Matlab LCC compiler. If you have a different version of Matlab, you probably don't have any and mex -setup will return "[0] None". Possible solutions in that case:- If you have a Linux installation (either 32-bits or 64-bits) of Matlab: just install the free gcc compiler on your pc (using either a Package Manager or by typing sudo apt-get install gcc in a terminal window), type mex -setup again in Matlab, and then run shapeit_setup_runonce.
- If you have a 64-bits Windows installation: bestway is to install a C-compiler on your computer, but good compilers for Windows are often expensive. There are some free alternatives however, like Windows SDK 7.1, which you can find on the MathWorks website. Remember to run mex -setup and shapeit_setup_runonce after installation. If there are still problems after the installation, there is some support from Matlab MathWorks Support Team
- If you are on Windows, and the previous suggestion didn't work, the easiest workaround is simply to install a 32-bits Matlab version. That one should have the LCC compiler included, and hence installation of ShapeIt should be peanuts then.
Note that you can check whether compilation went successful by looking for the binary files in your ShapeIt directory. Their extension is either .mexw32 / .mexw64 (32- or 64-bits Windows), .mexglx / .mexa64 (32- or 64-bits Linux) or .mexmaci / .mexmaci64 (32- or 64-bits Macintosh).
Installing / compiling still doesn't work. Am I missing a file simstruc.h?
If you tried everything that is described in the question on compiling, but you still can't seem to compile, you're probably using Windows 7 and a Matlab version older than release 2010bSP1. When you tried to compile or install, Matlab probably returned messages like
fatal error C1083: Cannot open include file: 'simstruc.h': No such file or directory
or maybe
Could not find include file "simstruc.h".
This may sound very clumsy, but this turns out to be caused by the space in the name of your programs folder: "Program Files". (Actually, it IS clumsy, but you have to blame Microsoft for making such a rookie mistake in their Windows versions...) Instead of removing this space, and thereby messing up all other installed programs, the Mathworks came up with a workaround, which you can read here (you need a MathWorks account to read it). In short:
- Exit Matlab,
- Download a certain zip-file,
- Extract the contents of the zip-file to your Matlab-directory (make sure you have administrator rights to do this).
Restart Matlab, and try to compile again. It should work now.
Installation went succesfull, but ShapeIt still doesn't open, due to some conflict with "figpos" or so?
The problem here is that apparently you have a function figpos installed in Matlab (or pos if you are using a ShapeIt version older than v0.14). It can easily be solved by removing this function from the Matlab search path. To do so, type
which figpos
to retrieve the path of the figpos or pos function. Then open the pathtool and remove this directory from the Matlab search path.
To be honest, this error is caused by a not-so-nice implementation in the ShapeIt startup script. It will be solved in v0.15.
Installation went perfect! But Matlab still returns weird errors when I try to open ShapeIt. How come?
If typing shapeit in your Matlab command window after successful installation returns errors like
"??? Error: File: C:\Program Files\MATLAB\R2010a\toolbox\shapeit\shapeit.p Line: 534 Column: 13 "identifier" expected, "(" found."
it's time to upgrade your Matlab installation. You're using Matlab 6.5, aren't you? That is so 2003! Read the requirements again: ShapeIt only works for Matlab 7 or higher. Figure handling is done completely different in older versions of Matlab, so ShapeIt will simply not work. Not now, not in future. So upgrade to a newer Matlab. But let's be honest, you should have done that years ago...
Can ShapeIt handle MIMO systems?
No, ShapeIt is designed for SISO loopshaping purposes. You can at most load separate subsystems of your MIMO plant into ShapeIt, but of course this doesn't consider any interaction between the subsystems, which is therefore not very useful to do. If you try to load a MIMO system into ShapeIt it will simply do nothing; it doesn't load your plant (or a part of it), nor does it generate a warning. Hence, be careful there. An error warning will be implemented in a future release.
What kind of controller does ShapeIt create when I press "Save to Simulink"?
This export functionality of ShapeIt uses the so-called DCtools controller blockset. The controller blocks in DCtools invoke special C-files included in the ShapeIt installation, which are discrete time approximations of the continuous time controller blocks used in the ShapeIt interface. The discretization is performed using a tustin method with prewarping, based on the sample time provided by your specific Simulink simulation. Since DCtools contains sample based controllers, it can be used in a real-time experiment.
What kind of optimization does ShapeIt use?
The optimization aid uses Genetic algorithms to find the optimum of the controller. This optimum is described by a so-called fitness function or costfunction, which tries to maximize the low-frequent gain and minimize the high-frequent gain, subject to the constraints (bandwidth and margins) defined in the lower left corner of your ShapeIt window. Although Genetic Algorithms are supposed to find global optima, the final solution can still depend on the initial conditions of the optimization. Furthermore, there might still be some small bugs in the efficient C-code implementation of the routine, yielding e.g. a destabilizing controller as optimum. Hence, always analyze your result afterward, and e-mail me if you've found such a bug.