samer@4: function x0=iterate(varargin)
samer@4: % iterate - Simulate recursive iteration of a function
samer@4: %
samer@4: % iterate :: 
samer@4: %    (A=>(A | empty)) ~'function to iterate, can return [] to terminate',
samer@4: %    A                ~'initial state',
samer@4: %    options iterate_timed_options
samer@4: % -> A                ~'final state'.
samer@4: %
samer@4: % iterate :: 
samer@4: %    cell {
samer@4: %       (A->(A | empty)) ~'function to iterate, can return [] to terminate',
samer@4: %       A                ~'initial state'
samer@4: %    }                   ~'iterated system as a cell array',
samer@13: %    options iterate_options
samer@4: % -> A                ~'final state'.
samer@4: %
samer@13: % iterate_options = {
samer@4: %       its     :: natural /inf ~'Iteration limit';
samer@13: %       quiet   :: bool    /1   ~'controls verbosity';
samer@4: %       pre     :: A=>void      ~'something to do before each iteration';
samer@4: %       post    :: A=>void      ~'something to do after each iteration';
samer@4: %       save    :: natural /0   ~'iterations between state saving (0=off)';
samer@4: %       id      :: string  /'iterstate@' ~'name of mat file to save to';
samer@13: %       recover :: bool    /0   ~'recover from saved state';
samer@13: %       drawnow :: bool    /1   ~'controls graphics updating';
samer@13: %       pause   :: natural /0   ~'pause between iterations (in ms) or 1 for indefinite'
samer@4: %    }.
samer@4: %
samer@4: % The function must return an empty array to force termination.
samer@4: 
samer@4: if iscell(varargin{1})
samer@4: 	[f,x]=varargin{1}{:};
samer@37: 	varargs=varargin(2:end);
samer@4: else
samer@4: 	f=varargin{1};
samer@4: 	x=varargin{2};
samer@37: 	varargs=varargin(3:end);
samer@4: end
samer@4: 
samer@37: opts=options('its',inf,'quiet',1,'save',0,'recover',0,'id','iterstate@',varargs{:});
samer@4: pauserfn=pauser(opts);
samer@4: post=isfield(opts,'post');
samer@4: pre=isfield(opts,'pre');
samer@4: 
samer@4: i=0; 
samer@4: if opts.recover
samer@4: 	if exist([opts.id,'.mat'],'file')
samer@4: 		fprintf('Attempting to recover from saved state %s.mat\n',opts.id);
samer@4: 		load(opts.id);
samer@4: 		fprintf('Continuing from iteration %d\n',i);
samer@4: 	else
samer@4: 		fprintf('Recovery file %s.mat does not exist.\n',opts.id);
samer@4: 	end
samer@4: end
samer@4: 
samer@4: if ~post && ~pre && opts.quiet && opts.save==0
samer@4: 	while ~isempty(x) && i<opts.its,
samer@4: 		i=i+1;
samer@4: 		x0=x; x=f(x0); 
samer@4: 		pauserfn();
samer@4: 	end
samer@4: else
samer@4: 	if opts.save>0
samer@4: 		fprintf('Will save every %d iterations to %s.mat\n',opts.save,opts.id);
samer@4: 	end
samer@4: 
samer@4: 	if isfinite(opts.its), itformat=sprintf('%%%dd. ',ceil(log10(opts.its)));
samer@4: 	else itformat='%d. '; end
samer@4: 
samer@4: 
samer@4: 	while ~isempty(x) && i<opts.its,
samer@4: 		i=i+1;
samer@4: 		if ~opts.quiet, fprintf(itformat,i); end
samer@4: 		if pre, opts.pre(x); end
samer@4: 		x0=x; x=feval(f,x0); 
samer@4: 		if post, opts.post(x); end
samer@4: 
samer@4: 		% save state every opts.save iterations
samer@4: 		if mod(i,opts.save)==0, 
samer@4: 			fprintf('\nsaving at %d.\n',i);
samer@4: 			save(opts.id,'x','i'); 
samer@4: 		end
samer@4: 		pauserfn();
samer@4: 	end
samer@4: 	if opts.save>0, 
samer@4: 		fprintf('Deleting recovery file %s.mat\n',opts.id);
samer@4: 		delete([opts.id '.mat']); 
samer@4: 	end
samer@4: end
samer@4: if ~isempty(x), x0=x; end 
samer@4: 	
samer@4: 
samer@4: