Description of sliterproc

Home > sltoolbox > learn > sliterproc.m

sliterproc

PURPOSE

SLITERPROC Runs a general iterative process

SYNOPSIS

function [objects, info] = sliterproc(objects, iterfunctor, cmpfunctor, hasrecord, varargin)

DESCRIPTION

SLITERPROC Runs a general iterative process

 $ Syntax $
   - objects = sliterproc(objects, iterfunctor, cmpfunctor, hasrecord, ...)
   - [objects, info] = sliterproc(objects, iterfunctor, cmpfunctor, hasrecord, ...)

 $ Arguments $
   - objects:      The models and data referred to in the process
                   The input one is the initial objects
                   The output one is the resulting objects.
   - iterfunctor:  the functor invoked in each iteration, in the form:
                   objects = f(objects, ...)
                   If the process needs to be recorded, it is like:
                   [objects, rec] = f(objects, ...)
   - cmpfunctor:   The functor to compare two set of objects and 
                   determine whether the process is converged.
                   It is in the following form:
                   is_converged = f(objects_prev, objects_current, ...)
   - hasrecord:    whether the process is recorded
   - info:         The struct of iteration information
                   - converged:  whether the process has been converged
                   - numiters:   the number of iterations
                   - records:    the struct array of the records
                     (this field exists when the process is recorded)
   
 $ Description $
   - objects = sliterproc(objects, iterfunctor, cmpfunctor, ...) runs
     a specified iterative process on a set of models and data. 
     You can specify the following properties to control the iteration:
     \*
     \t    Table.  Iteration Process Control Parameters
     \h      name      &        description
           'maxiter'   &  The maximum number of iterations 
                          (default = inf)
           'cvgcount'  &  How many continous converged iteration is 
                          satisfied before it stops the whole process.
                          (default = 1)
           'verbose'   &  Whether to show the process of iteration     
                          (default = true)
           'titlebreak'&  Whether to break the line after displaying
                          the iteration title. (default = true);
     \*
     The properties given above are called iteration control properties.
     They are typically specified as a whole in a cell array in the
     caller.

 $ History $
   - Created by Dahua Lin on Aug 31, 2006

CROSS-REFERENCE INFORMATION

This function calls:

• raise_lackinput RAISE_LACKINPUT Raises an error indicating lack of input argument
• slevalfunctor SLEVALFUNCTOR Evaluates a functor
• slparseprops SLPARSEPROPS Parses input parameters
• slsharedisp SLSHAREDISP Displays message using a shared configuration
• slsharedisp_attach SLSHAREDISP_ATTACH Attachs to global display options
• slsharedisp_decindent SLSHAREDISP_DECINDENT Decreases the indent of the displayer
• slsharedisp_detach SLSHAREDISP_DETACH Detachs current function from global display
• slsharedisp_incindent SLSHAREDISP_INCINDENT Increases the indent of the displayer
• slsharedisp_word SLSHAREDISP_WORD Displays message without line breaking

This function is called by:

• slproglearn SLPROGLEARN Performs Progressive Learning from sample source
• slreevallearn SLREEVALLEARN Performs an iterative learning based on re-evaluation

SOURCE CODE

0001 function [objects, info] = sliterproc(objects, iterfunctor, cmpfunctor, hasrecord, varargin)
0002 %SLITERPROC Runs a general iterative process
0003 %
0004 % $ Syntax $
0005 %   - objects = sliterproc(objects, iterfunctor, cmpfunctor, hasrecord, ...)
0006 %   - [objects, info] = sliterproc(objects, iterfunctor, cmpfunctor, hasrecord, ...)
0007 %
0008 % $ Arguments $
0009 %   - objects:      The models and data referred to in the process
0010 %                   The input one is the initial objects
0011 %                   The output one is the resulting objects.
0012 %   - iterfunctor:  the functor invoked in each iteration, in the form:
0013 %                   objects = f(objects, ...)
0014 %                   If the process needs to be recorded, it is like:
0015 %                   [objects, rec] = f(objects, ...)
0016 %   - cmpfunctor:   The functor to compare two set of objects and
0017 %                   determine whether the process is converged.
0018 %                   It is in the following form:
0019 %                   is_converged = f(objects_prev, objects_current, ...)
0020 %   - hasrecord:    whether the process is recorded
0021 %   - info:         The struct of iteration information
0022 %                   - converged:  whether the process has been converged
0023 %                   - numiters:   the number of iterations
0024 %                   - records:    the struct array of the records
0025 %                     (this field exists when the process is recorded)
0026 %
0027 % $ Description $
0028 %   - objects = sliterproc(objects, iterfunctor, cmpfunctor, ...) runs
0029 %     a specified iterative process on a set of models and data.
0030 %     You can specify the following properties to control the iteration:
0031 %     \*
0032 %     \t    Table.  Iteration Process Control Parameters
0033 %     \h      name      &        description
0034 %           'maxiter'   &  The maximum number of iterations
0035 %                          (default = inf)
0036 %           'cvgcount'  &  How many continous converged iteration is
0037 %                          satisfied before it stops the whole process.
0038 %                          (default = 1)
0039 %           'verbose'   &  Whether to show the process of iteration
0040 %                          (default = true)
0041 %           'titlebreak'&  Whether to break the line after displaying
0042 %                          the iteration title. (default = true);
0043 %     \*
0044 %     The properties given above are called iteration control properties.
0045 %     They are typically specified as a whole in a cell array in the
0046 %     caller.
0047 %
0048 % $ History $
0049 %   - Created by Dahua Lin on Aug 31, 2006
0050 %
0051 
0052 %% parse and verify input
0053 
0054 if nargin < 4
0055     raise_lackinput('sliterproc', 4);
0056 end
0057 
0058 opts.maxiter = inf;
0059 opts.cvgcount = 1;
0060 opts.verbose = true;
0061 opts.titlebreak = true;
0062 opts = slparseprops(opts, varargin{:});
0063 
0064 %% Main skeleton
0065 
0066 slsharedisp_attach('sliterproc', 'show', opts.verbose);
0067 
0068 niter = 0;
0069 nconverged = 0;
0070 while niter < opts.maxiter && nconverged < opts.cvgcount
0071     
0072     niter = niter + 1;
0073     
0074     if opts.titlebreak
0075         slsharedisp('Iteration %d', niter);
0076     else
0077         slsharedisp_word('Iteration %d: ', niter);
0078     end
0079     
0080     slsharedisp_incindent;
0081     
0082     % run iteration
0083     objects_prev = objects;
0084     if hasrecord
0085         [objects, records(niter, 1)] = slevalfunctor(iterfunctor, objects);
0086     else
0087         objects = slevalfunctor(iterfunctor, objects);
0088     end
0089     
0090     % compare and determine convergence
0091     isconverged = slevalfunctor(cmpfunctor, objects_prev, objects);
0092     if isconverged
0093         nconverged = nconverged + 1;
0094     else
0095         nconverged = 0;
0096     end        
0097     
0098     slsharedisp_decindent;
0099     
0100 end
0101 
0102 isconverged = (nconverged >= opts.cvgcount);
0103 if isconverged
0104     slsharedisp('Iteration process converged');
0105 end
0106 
0107 
0108 slsharedisp_detach();
0109 
0110 %% Output information
0111 
0112 if nargout >= 2
0113     info.converged = isconverged;
0114     info.numiters = niter;
0115     if hasrecord
0116         info.records = records;
0117     end
0118 end
0119 
0120

---

Generated on Wed 20-Sep-2006 12:43:11 by m2html © 2003