INSTALLATION
============


Table of Contents
=================

1. Quick installation guide
2. Recommended directory tree and file list
3. Where to install the DFP?
   3.1. Recommended "system-wide" installation
   3.2. Recommended "individual" installation 
4. Modifying the DFPRCDEF.M file
   4.1. Specifying DFP directories
   4.2. Specifying the customizable DFP colors
   4.3. User customization
5. Changing the MATLAB path
   5.1. Changing the MATLAB path for a "system-wide" installation
   5.2. Changing the MATLAB path for an "individual" installation
6. Starting DFP
7. How fast is DFP?
8. Can I run DFP on a monochrome monitor?
9. Where to get UITOOLS?


1. Quick installation guide
===========================
This section is primarily for experienced and impatient MATLAB users. I 
assume that DFP is installed into a directory with the generic name DFP_ROOT,
i.e., DFP_ROOT is an abbreviation for the full pathname of this directory. 
For example, on a UNIX system DFP_ROOT = /usr/local/dfp, and on a PC running 
Windows DFP_ROOT = c:\local\dfp.  The following quick guide uses the notation 
compatible with a UNIX system.  Modify them according to your own system.

o Step 1: Create the root directory DFP_ROOT and the directory tree
          shown in Figure 1 below.

o Step 2: Copy the files from the distribution into the directory tree
          you have generated in Step 1 as shown in Figure 1.
          If you have obtained an "archived" version of DFP (such as
          "dfp.tgz", "dfp.zip", or "dfp.sh") then this step will be
          automatically done for you as you expand the "archive" file.

o Step 3: If you do not have UITOOLS installed on your system, then copy
          all 9 files in the DFP_ROOT/uitools directory into the 
          DFP_ROOT directory as shown in Figure 1.
          For full UITOOLS installation see Section 9 entitled "Where to 
          get UITOOLS?"

o Step 4: Modify the file DFPRCDEF.M file in the DFP_ROOT directory. Change
          DFP_Directory     = ''; 
          DFP_SourceCodeDir = ''; 
          DFP_TemplatesDir  = 'DFP_ROOT/codegen/mot56k/template/" 
                                            (NOTE the trailing "/")

o Step 5: Either in the 
             MATLABRC.M file add "DFP_ROOT" to the matlabpath command
          or in your own
             STARTUP.M file add the line "path(path,'DFP_ROOT')".

o Step 6: Start MATLAB and at the MATLAB prompt type "dfp".


If you have any difficulty installing DFP, please read the detailed
instructions and explanations in the remainder of this file.


2. Recommended directory tree and file list
===========================================

Let DFP_ROOT be the directory where the DFP package is to be installed. 
The recommended directory tree for installing DFP is as shown:

    DFP_ROOT/
       |     Contents.m    Readme.m      arrow.m       d_almncb.m
       |     d_append.m    d_axldlg.m    d_cfmtcb.m    d_codgen.m
       |     d_csldcb.m    d_datest.m    d_disply.m    d_dplydr.m
       |     d_error.m     d_fileio.m    d_format.m    d_global.m
       |     d_grmncb.m    d_implmt.m    d_inpdlg.m    d_logo.m
       |     d_mtdcb.m     d_mtdint.m    d_mtdsup.m    d_namesv.m
       |     d_navgcb.m    d_navgtr.m    d_numncb.m    d_outpcb.m
       |     d_output.m    d_prbwcb.m    d_prclcb.m    d_probaw.m
       |     d_proclr.m    d_propsv.m    d_propts.m    d_quant.m
       |     d_recocb.m    d_recoef.m    d_resize.m    d_rstdef.m
       |     d_scmncb.m    d_setlbl.m    d_spmncb.m    d_tgdraw.m
       |     d_tgmncb.m    d_tgtgen.m    d_transf.m    d_tspcb.m 
       |     d_tspchk.m    d_tspint.m    d_tspsup.m    dateme.m
       |     dec2bin.m     dfp.m         dfprcdef.m    difford.m
       |     firlsa.m      hilbord.m     int2hex.m     int2oct.m
       |     kaiseord.m    lat2poly.m    limiter.m     poly2lat.m
       |     timedate.m    uiprint.m
       |     === if you do not have UITOOLS ===
       |     fwhich.m      inpolygon.m   isdir.m       ishandle.m
       |     makecopy.m    matqparse.m   mexext.m      remapfig.m
       |     winmenu.m
       |
       +---> doc/
       |         bugs.txt  install.txt   usrguide.txt
       |
       +---> codegen/
             |
             +--> mot56k/
                  |
                  +--> helpfile/
                  |             fir_dir.hlp   fir_lat.hlp
                  |             iir_dir.hlp   iir_lat.hlp   iir_sos.hlp
                  +--> macrolib/
                  |             aiset.asm     firdir.asm    firlat.asm
                  |             iirdir.asm    iirlat.asm    iirsos.asm
                  +--> samples/
                  |             Contents
                  |             fd_coef.asm   fd_full.asm   fd_macro.asm
                  |             fl_coef.asm   fl_full.asm   fl_macro.asm
                  |             id_coef.asm   id_full.asm   id_macro.asm
                  |             il_coef.asm   il_full.asm   il_macro.asm
                  |             is_coef.asm   is_full.asm   is_macro.asm
                  +--> template/
                                fir_d00.asm   fir_d02.asm
                                fir_l00.asm   fir_l02.asm
                                iir_d00.asm   iir_d02.asm
                                iir_l00.asm   iir_l02.asm
                                iir_s00.asm   iir_s02.asm


                   Figure 1: DFP directory structure



3. Where to install the DFP?
============================

The locations of the DFP files and directories are not critical. I suggest,
however, to install the DFP files in a place that confirms the recommended 
MATLAB practise.  This means that the most appropriate place is a directory
where all other MATLAB or local toolboxes reside.  Let MATLAB_ROOT be
the directory where MATLAB has been locally installed, let HOME be the
user's home directory, and let DFP_ROOT be the directory where the DFP 
package is to be installed.  The following two cases represent recommended 
directories for "system-wide" and "individual" installations, respectively.
In either case, once a decision about DFP_ROOT is made, please follow the
directory structure as shown in Figure 1, and copy the M-files, filter
template files, sample filter files, and document files to appropriate
directories under DFP_ROOT.

   If you happen to be using a UNIX system, and do not have to write
permissions for a "system-wide" installation, then you have no choice
but to go with the "individual" installation option.  On an (individual)
LINUX system or on your own machine (be it a PC/Windows or Mac) you can
go with either "system-wide" or "individual" installation.  Please note that,
I used the the UNIX file separator "/" to describe the directory tree.  In 
your case, depending to the OS you happen to be using, the directory separator
will probably be different.


3.1. Recommended "system-wide" installation
-------------------------------------------

            MATLAB_ROOT
                |
                +---> bin/
                |     ...
                +---> toolbox/
                          |
                          +---> matlab/
                          |     ...
                          +---> signal/
                          |     ...
                          +---> local/
                                  |
                                  +---> local_toolbox1/
                                  |
                                  +---> local_toolbox2/
                                  |     ...   
                                  +---> dfp/


In this case DFP_ROOT = MATLAB_ROOT/toolbox/local/dfp.


3.2. Recommended "individual" installation:
-------------------------------------------

           HOME/
             |
             +---> matlab/
                      |
                      +---> toolbox/
                               |
                               +---> dfp/

In this case DFP_ROOT = HOME/matlab/toolbox/local/dfp.



4. Modifying the DFPRCDEF.M file
================================

The script file DFPRCDEF.M contains the global default values for the
user customizable DFP parameters/variables.  In particular, these are
the color definitions for the [DFP: Display] figure, directories, number
of points used to generate the frequency plots, and the state of the 
figure resize property.

    If you look at the file D_GLOBAL.M, you will notice many other color and
dimension definitions than those specified in the DFPRCDEF.M file.  They
represent definitions that affect the look and feel of the DFP figures.  You
may modify them to your heart's content, but beware of the fact that I spend 
a lot of time to achieve, in my opinion, a pleasing and consistent look for 
the DFP figures.  Therefore, if you modify these "other" parameters and if 
things do not look "nice" any more, do not blame me.


4.1. Specifying DFP directories
-------------------------------
I recommend strongly that the user should not modify the file DFPRCDEF.M
EXCEPT for the directory names and EXCEPT during the initial installation 
time.  The following information allows you to properly initialize the DFP 
directories:

o DFP_Directory :
  Directory where the *.mat files will reside.  The *.mat 
  files generated by DFP contain all the information which allows the 
  user to recreate the current design at some later time.  This 
  directory is the reference point for the 
  [DFP: Navigator]-[File]-[Open or Save] uimenu selections.

o DFP_SourceCodeDir :  
  If the user exercises the filter code generation option then this 
  directory serves as the reference directory for storing the DFP
  generated filter code files.

o DFP_TemplatesDir :  
  When the user asks DFP to generate filter code, DFP 
  combines a number of template files with the filter specific
  coefficient data.  This directory tells DFP where it can
  find the template files.


REMARK 1: 
  MATLAB requires that you specify directory names as strings.
  Therefore, please make sure that a directory name is given 
  within single quotes as a valid MATLAB string variable.  
  For example, on a UNIX system to set the DFP_TemplatesDir to 
  /usr/local/matlab/toolbox/dfp/templates the correct syntax is: 
  DFP_TemplatesDir = '/usr/local/matlab/toolbox/dfp/templates/';

REMARK 2: 
  When specifying the directories please make sure that the last
  character in each string variable is a proper file separator 
  character for that particular OS.  For example, the last character 
  should be a "/", and a "\" on a UNIX system and on a DOS system, 
  respectively:
  UNIX: DFP_TemplatesDir = '/usr/local/matlab/toolbox/dfp/templates/';
  DOS : DFP_TemplatesDir = 'c:\usr\local\matlab\toolbox\dfp\template\';

REMARK 3: 
  If you specify a directory name as an empty string such as,
  DFP_Directory = ''; then MATLAB simply references the present
  working directory.  Thus, if you frequently find yourself using DFP from
  different directories, and if you want to keep the DFP generated files 
  separate then a good strategy will be to set the directories 
  DFP_Directory and DFP_SourceCodeDir to the empty string, ''.

REMARK 4: 
  In most cases, the user does not need to change the "DFP_TemplatesDir".


4.2. Specifying the customizable DFP colors
-------------------------------------------
Under normal operating condition no color customization should be done through
the DFPRCDEF.M file.  "Normal operating conditions" means that you agree with
my choice of colors.  If you are a system administrator for a site with many 
MATLAB users, and if for some reason you dread my selection of colors, and 
if you want to impose your esthetic values (instead of mine) on each user,
then feel free to change the color definitions in the DFPRCDEF.M file.

    If a user wants to alter the customizable DISPLAY colors, this should 
be done through the [File]-[Properties]-[Customize] menu selection in the 
[DFP: Navigator] window. 


4.3. User customization
-----------------------
DFP uses two customization files: DFPRCDEF.M and DFPRC.M.   The first one is
the system-wide global initialization file.   When DFP starts via the function 
DFP.M, it first reads DFPRCDEF.M, and then checks whether there exists a 
file with the name DFPRC.M somewhere in the MATLAB path. If DFPRC.M exists, 
DFP opens this file and any directory or color definitions in DFPRC.M
overrides the global values specified in DFPRCDEF.M.  Typically, each user
will keep his/her DFPRC.M file in his/her local MATLAB directory.



5. Changing the MATLAB path
===========================
MATLAB should be able to locate the files in the DFP.  This can be
accomplished by either starting MATLAB from the directory where all the DFP
M-files reside, or modifying the MATLAB PATH variable to include the DFP
directory.  Clearly, the second alternative is the preferred method, as it
frees the user from starting and/or using DFP always from the same directory.

5.1. Changing the MATLAB path for a "system-wide" installation
--------------------------------------------------------------
Open the master startup file MATLABRC.M which is usually found in the 
MATLAB_ROOT directory.  You will notice a line which starts with the command
"matlabpath" which then lists all the MATLAB and toolbox directories.
Append to the end of this statement the directory DFP_ROOT, where DFP_ROOT 
again represents the directory under which all the DFP files can be found.  
With this method, each user who starts MATLAB will have full access to DFP.

5.2. Changing the MATLAB path for an "individual" installation
--------------------------------------------------------------
If you have downloaded DFP as an individual and want to run it as such, then
the proper DFP path specification is through your own STARTUP.M file which
normally resides in your HOME/matlab directory.  Edit your own STARTUP.M file
such that it contain the line:

  path( path, DFP_ROOT )

where DFP_ROOT represents the directory under which all the DFP files can be
found.


6. Starting DFP
===============
If you have followed all the preceding installation instructions, then 
simply type "dfp" (no quotes) at the MATLAB prompt.  This command will first
print a banner screen, indicating the DFP version and then notifies the user 
about the progress of initialization.   Once DFP generates all the figures, 
the [DFP: Navigator] screen becomes visible in the top-left corner of your
screen and you can start using DFP to design digital filters.


7. HOW FAST IS DFP?
===================
MATLAB is not known for its blazing speed.  This observation becomes 
particularly relevant for GUI based MATLAB applications.  While developing 
DFP, I tested it on a limited number of computer platforms.  The following 
is my subjective observations on how fast DFP feels on each one of these
platforms.   First the computers:

     Computer Type                CPU         RAM      OS
     ===============================================================
     A. Sun SPARCstation 1                    16 MB    SunOS 4.1.1
     B. Sun SPARCstation SLC                  16 MB    SunOS 4.1.1
     C. Sun SPARCstation IPC                  24 MB    Solaris 2.5
     D. Sun SPARCstation LX                   24 MB    Solaris 2.5
     E. Sun SPARCstation 5                    32 MB    Solaris 2.5
     F. Sun SPARCstation ULTRA1   143 MHz     32 MB    Solaris 2.5
     G. Sun ENTERPRISEServer2     167 MHz    256 MB    Solaris 2.5.1
     H. Intel-486DX2               66 MHz     32 MB    Windows95
     I. Intel-486DX2               66 MHz     32 MB    Linux 1.2.1
     J. Intel-Pentium             166 MHz     64 MB    Linux 2.0
     K. Intel-Pentium Pro         200 MHz     64 MB    Linux 2.0

     A,B,C: Usable, but "molasses" is a word that comes to my mind.  
            Especially slow at startup.
     D,E  : Very decent performance, yet at times I wished for faster response,
            slow startup, slow filter design updates, but no major complaints.
     F,G  : This is how DFP is meant to be run.  Snappy, responsive.  Instant
            updates, with almost no delay.
     H    : Not bad, but feels slow in screen updates, slower than the same
            computer running Linux.
     I    : Very reasonable performance.  Feels faster than running on a
            SPARCstation 5.
     J    : Very good. Subjectively, this machine is on par with the 143 MHz
            Ultra-1
     K    : I want one.


8. Can I run DFP on a monochrome monitor?
=========================================
At startup DFP attempts to determine whether MATLAB is running on a 
color or on a monochrome monitor.  In particular, DFP inquires about the 
state of the 'BlackandWhite' property of the root window.  If the
'BlackandWhite' property of the root window is 'off', DFP concludes
that MATLAB is running on a color monitor.  This information is in turn
shared with other DFP functions by the true state of the global variable 
DFP_ColorMonitor.

    This method is not completely fool-proof.  The 'BlackandWhite'
property of the root window is set by MATLAB and the OS.  Since,
the current release of DFP has not been tested on all MATLAB supported
platforms, it is conceivable that this method may incorrectly identify 
the underlying video mode.  If this happens to be the case for your
setup, you can force DFP to switch to the monochrome monitor mode.  Edit
the file D_GLOBAL.M, and explicitly set the variable DFP_ColorMonitor to
'off' for color mode and to 'on' for monochrome mode.

    I have not been able to test DFP on a grayscale monitor.  I expect
that if MATLAB is running on a black and white monitor which is capable
of supporting shades of gray, then MATLAB would return 'on' for the 
'BlackandWhite' root window property, and an integer value greater than 
1 for the 'ScreenDepth' root window property.  If this is indeed the case, 
then DFP will switch to a monochrome mode.  Yet, the proper way of handling 
the grayscale case would be to continue with color mode definitions 
which would now be mapped onto corresponding gray scale values.  Color
definitions do not always map "nicely" onto gray scales.  Therefore, if
you are running MATLAB on a grayscale monitor, may I kindly ask that you
force DFP into a color mode (see the above paragraph), and observe
whether the individual elements, such as plots, axes, uicontrol objects,
texts, etc. are discernible.  I would appreciate if you would inform me
about your observations.

9. Where to get UITOOLS?
========================
DFP requires a number of M-files from the Mathworks UITOOLS distribution 
which may not be part of standard Matlab distribution.  If at the Matlab 
prompt you type

    >> help uitools

and receive the message

    >> uitools not found

then you need UITOOLS.  If you want to download the entire UTOOLS
package, they are available from the Mathworks ftp site 
"ftp://ftp.mathworks.com/pub/mathworks/" You will find the UITOOLS in the 
"/pub/mathworks/toolbox/uitools/" directory.  

    If you want only the required ones (there are only 9), they are
part of the DFP distribution and can be found in the DFP_ROOT/uitools
directory.  Simply copy them to the DFP_ROOT directory.  



    Author: Mehmet Zeytinoglu (mzeytin@ee.ryerson.ca)
            Department of Electrical and Computer Engineering
            Ryerson Polytechnic University
            Toronto, Ontario, M5B 2K3 
            CANADA

    Copyright (c) 1997 Mehmet Zeytinoglu

    $Revision: 1.4 $
    $Date: 1997/03/11 13:39:22 $

