

IFR-Fuzzy-Toolbox  USER MANUAL

------------------------------------------------------------------------------
  Copyright (c) 1994, University of Stuttgart, IFR, All rights reserved.

  Permission to use, copy, modify, and distribute this software and its
  documentation for any non-commercial purpose without fee is hereby granted,
  provided that the above copyright notice appears in all copies and that
  both that copyright notice and this permission notice appear in
  supporting documentation.
 
  THE IFR DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
  ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL
  THE IFR BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR
  ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS,
  WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION,
  ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS
  SOFTWARE.
---------------------------------------------------------------------------



  The IFR fuzzy-control toolbox for MATLAB is an outcome of a senior project during the time between October 1992 and March 1993 at the "Institut fuer Flugmechanik und Flugregelung" (Flight Mechanics and Control) of the University of Stuttgart. (we call such projects 'Studienarbeit') 
  It was our goal to provide the MATLAB community with an easy to use toolbox to do fuzzy-control design, wich allows the user to explore and facilitate design of  fuzzy-control systems. Computationally extensive functions are provided as Cmex files.
  The original design was based on MATLAB 3.5, but the new GUI features of MATLAB 4.0 sounded promising - therefore we decided to use some of them. However, the use of those features was a mixed blessing. Sometimes it became necessary to do a little "dirty programming" (we had to save data temporarely and to load them back in again).

  Anyway, we hope you enjoy the use of this toolbox.
(and don't hesitate to email us if you find any bugs - and you might find some!).


Bernhard Kaempf and Stephan Molt
                                    Stuttgart, December-February, 1993-1994





CONTENTS of this MANUAL: 

 Part I:    How to use the toolbox
 Part II:   F__*.M files for simulation
 Part III:  Objects in the fuzzy-control toolbox
 Part IV:   List of Matlab-Commands in Fuzzy-Toolbox
 Part V:    C-Routines for Fuzzy-Toolbox
 Part VI:   Demo


-----------------------------------------------------------------------------

                     Part I: How to use the toolbox
                     ==============================
	
  To prepare and design a fuzzy-controller the followin steps are necessary:

 (1) You have to define your input-variables to the fuzzy-controller
     by using the command INDEF.

       MATLAB:   in=INDEF()


 (2) You have to define your out-variables of the fuzzy-controller
      by using OUTDEF.

       MATLAB:   set=OUTDEF(in)


 (3) You have to define your linguistic variables by using MAKESET.

       MATLAB:   sd=MAKESET(set)


 (4) You have to define your rules by using MAKERULE (under Version
     3.x) or by using DESIGNRULE (Version 4.0).

       MATLAB:   rule=MAKERULE(set,sd)


  So far you prepared all the necessesary data-objects  of a fuzzy-control system and you can start simulating. Therefore,


(5) You have to adjust the m-files 
       F__SIMUL, F__FC, F__DEQ, F__STATE and F__INIT.

-------------------------------------------------------------------------------

                   Part II: F__*.M files for simulation
                   ====================================


  To simplify the usage of the fuzzy-control-toolox for matlab, five files are provided: F__SIMUL (the main simulation routine), F__INIT (an initialisation procedure), F__DEQ (to define the necessary differential equations), F__STATE (that calculates the new state-vector) and F__FC (the fuzzy-control routine).
  It is not necessary to use those matlab-files (ever user can design his or her own simulation routines) - but it's a lot easier for experimenting and debugging if you begin to control your own systems with fuzzy-control.
  The following two pictures will provide further information. If you consider a control system like
		

    y_com       |-------------------|   u   |----------|       y
      -->o--->--|  Fuzzy-Controller |--->---|  System  |->--|------>
       - |      |-------------------|       |----------|    |
         |                                                  |
         |                                                  |
         |                             negative feedback    |
         |----------<---------------------------------------|



it is simulated by F__SIMUL like this:


F__SIMUL

     -> F__INIT -> Initialisation

   ----- Time-Loop ------------
   |
   |
   | -> F__FC            % the fuzzy-control vector u is computed 
   | -> F__STATE         % computes new state-vector by using deriva-
   |     |               % tives form F__DEQ
   |      -> F__DEQ
   |
   ------ End of Time-Loop -----


A short description of those matlab-files follows.


F__SIMUL.M
==========

  This is the main simulation routine. It consists mainly of commands to
call the other F__*.M files and a time-loop.


F__INIT.M
=========

  F__INIT determines the initial values of state and constants needed to
describe the system correctly (e.g. heat-capacity of a room).
  If UNFUZZY2 - method is used matrices Rs and Sp are also returned.


F__STATE.M
==========

  F__STATE determines the new state-vector either by integrating the dif-
ferential equations (see F__DEQ.M) or by solving the discrete-time system mo-
del.
  F__STATE has two righthand-side arguments (xold - the old state-vector,
and u - the control-input) and one lefthand-side argument (xnew - the new
state-vector).
  F__STATE is called by the main simulation routine F__SIMUL.


F__DEQ.M
========

  This file defines the differential equations that are necessary to des-
cribe the system correctly. Mostly, this function is called by F__STATE.M,
using the matlab-integration routine ODE45 or ODE23.
  If it is possible to describe the system without differential equations
(i.e. by transformation into the z-plane) this file is not needed.


F__FC.M
=======

  This routine contains the fuzzy-controller. The arguments are the mea-
sured state-vector y, the rule-matrix and other matrices needed to further des-
cribe the rules. The return-value of this routine is the control-vector u.


  As said above, it is not necessary to use these five matlab-files, but
it's a lot easier for the beginner.


--------------------------------------------------------------------------------

               Part III: Objects in the fuzzy-control toolbox
               ==============================================

  Matlab doesn't allow to program object-oriented like C++ or other OOP
languages. Every object that is used in Matlab has the form of a (n x m) mat-
rix.
  However, a few different objects have been defined, that are described
in this part.


  Object-Type	Produced by	Used by
  =======================================
  EXTSETDESC    editset.m     ext_ana.mex,
                              ext_inf.mex,
                              showset.m

   SETDESC      makeset.m     analyse.mex,
                              editrule.m,
                              editset.m,
                              evaluate.mex,
                              ext_inf.mex,
                              inferenz.mex,
                              designrule.m (Version 4.0),
                              makerule.m (Version 3.0),
                              showset.m

   INSET       indef.m        outdef.m

   SET         outdef.m       editset.m,
                              evaluate.mex,
                              makerule.m (Version 3.0),
                              designrule.m (Version 4.0),
                              showset.m,
                              showvar.m

   RULE        makerule.m     editrule.m,
               designrule.m   evaluate.mex,
                              ext_inf.mex,
                              inferenz.m



------------------------------------------------------------------------------


             Part IV: List of Matlab-Commands in Fuzzy-Toolbox
             =================================================

  In this part all matlab-files are listed, which are important for the
user. Those *.m-files, that are only necessary to draw a box on the screen for
example, are omitted. (It is impossible to realize a very thorough concept of
information-hiding in the matlab-language. Therefore the only possible way is
to omit the comments of the unimportant *.m-files.)


a) List ordered by subjects

Operation on Fuzzy-Sets
=======================

ADD      M         adds two fuzzy-figures
CHSGN    M         changes the sign of a fuzzy-figure
DISCRET  M         transforms a trapezoidal fuzzy-figure into a discrete fuzzy-
                   figure
DIV      M         divides two fuzzy-figures
EXPF     M         returns the exponential value of a fuzzy-figure; i.e.
                   exp(f), where f is fuzzy
LNF      M         returns the logarithmic value of a fuzzy-figure; i.e.
                   ln(f), where f is fuzzy
MUL      M         multiplies two fuzzy-figures
RECIPROC M         builds 1/f where f is a fuzzy-figure
SUB      M         subtracts two fuzzy-figures
TALEVEL  M         returns the borders of the alpha-level of a fuzzy-figure
TUNFUZZY M         returns the "crisp" counterpart of a trapezoidal fuzzy-
                   figure 
UNFUZZY2 M         used for defuzzy-fication of a fuzzy-figure; the height-
                   method is used



Managing the Fuzzy-Controller
=============================

EDITRULE M         allows you to edit (and append) your rulebase (Matlab4.x)
                   with GUI.
EDITRULE_PC M      allows you to edit (and append) your rulebase (Matlab 3.x)
EDITSET  M         allows you to edit the defined sets
INDEF    M         defines the input-variables into the fuzzy-controller
DESIGNRULE M       tool to design the rules of the fuzzy-controller
MAKESET  M         tool to design the sets of the fuzzy-variables
OUTDEF   M         defines the output-variables of the fuzzy-controller
TUNFUZZY M         returns the "crisp" counterpart of a trapezoidal fuzzy-
                   figure 
UNFUZZY2 M         used for defuzzy-fication of a fuzzy-figure; the height-
                   method is used


Display Operations
==================

COLID    M         returns a colour-identifier
DSHOW    M         displays a discrete fuzzy-figure on the graphic-screen
SHOWSET  M         shows all sets of a fuzzy-variable on the graphic-screen
SHOWRULE M         a tool to check your already designed rules
SHOWVAR  M         shows all in- and output variables of the fuzzy-controller
TSHOW    M         shows a trapezoidal fuzzy-figure on the graphic-screen



b) List ordered alphabetically

  add.m
  chsgn.m        colid.m        cop.m
  designrule.m   discret.m      div.m         dshow.m
  editrule.m     editrule_pc.m  editset.m     expf.m
  helpshow.m
  indef.m
  lnf.m
  makeset.m      makeset_pc.m   mul.m          
  outdef.m
  prepare.m
  reciproc.m
  showrule.m     showset.m      showvar.m     sub.m
  talevel.m      tshow.m        tunfuzzy.m     
  unfuzzy2.m
 
-------------------------------------------------------------------------------


                 Part V: C-Routines for Fuzzy-Toolbox
                 ====================================
                 
  Some people don't like to get involved into reading *.c-files (I think
they are right!) - so the parameters of the *.c-files that are included in the 
fuzzy-control-toolbox are listed below as well as a short description of them.	



ANALYSE  C        analyses the measured values to look which rules may
                  be used
                  
                  Syntax:
                  Am = analyse(nr_in,max_sd,sd,Mm,1)

                  nr_in   : total nr. of input variables
                  max_sd  : maximum number of sets in the sd-matrix
                  sd      : set-description matrix
                  Mm      : matrix of measured input-variables
                  1 or 2  : decides what to do if the measured variable
                            is out of range; (2 means that a "hit" in the
                            zero-region will be calculated, and 1 means that
                            the "hit" will be recognized in the border-sets)
                            
                  see also: f__fc.m


                  
                  
EVALUATE C        evaluates the result of the analyse-command

                  Syntax:
                  [Aij,Aj] = evaluate(Am,rule,sd,aggop)

                  Am     : the result of the analyse-command
                  rule   : matrix containing the rules
                  sd     : set-description matrix
                  aggop  : aggregation-operator, where
                  
                           aggop=1: minimum-operator
                           aggop=2: bounded difference
                           aggop=3: einstein product
                           aggop=4: algebraic product
                           aggop=5: hamacher product
                           aggop=6: fuzzy-and 




EXT_ANA  C        analyse-command for an extended set-description matrix;

                  Syntax
                  Am = ext_ana(nin,nout,extsd,Mm,max_sd)
                  
                  nin    : total number of input-variables
                  nout   : total number of output-variables
                  extsd  : extended set-description matrix
                  Mm     : matrix containing the measured input-
                           variables
                  max_sd : maximum number of sections in the extsd-
                           matrix
                           




EXT_INF  C        inference for extended set description matrices; the in-
                  ference is important to apply rules and calculate the
                  output of those rules
                  
                  Syntax:
                  [f_d] = ext_inf(Aj,rule,infop,nr_out,sd,dstep,
                                  or_op,extsd)
                                  
                  Aj     : result of evaluate-command
                  rule   : matrix of rules
                  infop  : inference-operator, where
                  
                           infop=2 clipping
                           infop=3 linear modulation
                  nr_out : index-number of output that you want to cal-
                           culate (mostly there is a loop over nr_out, if 
                           you have got more than one output-variable)
                  sd     : set-description matrix
                  dstep  : width of discrete steps that the result f_d will
                           have
                  or_op  : or-operator (see description of ODER.C)
                  extsd  : extended set-dscription matrix




HCHK     C        performs a heap-check to see if the heap was corrupted




INFERENZ C        inference-operation

                  Syntax:
                  u_d=inferenz(Aj,rule,infop,nrout,sd,dstep,or_op)
                  
                  Aj     : result of evaluation
                  rule   : rule-matrix
                  infop  : inference-operator (see above)
                  sd     : set-description matrix
                  dstep  : (see above)
                  or_op  : (see above)




                  
ODER     C        or-operator
                  
                  note: ODER.C is called from inferenz for example; in
                        this case you don't need to worry about the syntax.
                        The syntax is only important if you want to combine
                        two discrete-fuzzy-figures with OR
                         

                  Syntax:
                  [f_d] = oder(x_d,y_d,d_step,or_op)
                  
                  x_d   : discrete fuzzy-figure
                  y_d   : discrete fuzzy-figure
                  d_step: width of discretization of the two figures
                  or_op : or-operator, where
                  
                          or_op=1 maximum-operator
                          or_op=2 bounded sum
                          or_op=3 einstein sum
                          or_op=4 algebraic sum
                          or_op=5 hamacher sum
                          or_op=6 fuzzy-or


                  

OPERATOR C         lists all operators







UND      C         combines two fuzzy-figures with AND; the syntax is the
                   same as under ODER.C described; 
                   the arguments for the AND-operator are the according AND-
                   operators to the above OR-Operators






UNFUZZY1 C         defuzzy-fication of a discrete fuzzy-figure using the 
                   center of gravity-method
                   
                   Syntax:
                   f = unfuzzy1(f_d,dstep)
                   
                   f_d   : discrete fuzzy-figure
                   dstep : width of discrete steps of f_d








                           Part VI: Demo
                           =============

	All of the things told above may sound a bit theoretically, so we de-
cided to give you a demo to play with an already designed fuzzy-control-sys-
tem. In this demo we will regard a fuzzy-controller that has the task to con-
trol the inside temperature of a room. The measured values will be the tem-
perature T itself and the temperature slope DT. The command to the system will
be the slope of the heating power DP.
	The differential equation describing this problem is:

	d (theta)      F * alpha                1
        --------- = -  --------- * (theta) +  ----- * P
          dt             m * c                m * c

( comparable to the "normal" form of a linear control problem:

	dx/dt     =         A    *    x    +     B  *  u ),

where	F	is the surface of the room,
	alpha	is the heat-coefficient,
	m	is the mass of the air inside the room,
	c	is the specific heat capacity,
	theta	is the difference between the outside and the inside tem-
		perature and
	P	is the heating power.



	Then, the following rules will apply:



				(DT)

	    |	NB	NS	ZE	PS	PB
	------------------------------------------- 
	NB  |			PB
	    |
	NS  |			PS
	    |
(T)	ZE  |	PB	PS	ZE	NS	NB
	    |
	PS  |			NS
	    |
	PB  |			NB


  For those of you who aren't familiar with those rule-matrices: the
entry in row one and column three can be interpreted as the following rule:

  "If the temparature T is negative big (NB) and the temperature slope DT
  is zero (ZE) then the change of the heating power must be positive big
  (PB)."

  You will find the demo-program in the demo-directory. There is also an demo.txt file and a temp_demo.mat file that includes all necessary parameters for this control-problem.
To start the demonstration, you have to:

   1.   Load the *.mat-file
      or
        follow the design step as proposed in demo.txt  

   2.   Run the simulation by typing 
            [temperature,time]=f__simul(rule,sd,set);




						Again, good luck and much fun!
