octave_packages/odepkg-0.8.2/odeset.m

   1 %# Copyright (C) 2006-2012, Thomas Treichl <treichl@users.sourceforge.net>
   2 %# OdePkg - A package for solving ordinary differential equations and more
   3 %#
   4 %# This program is free software; you can redistribute it and/or modify
   5 %# it under the terms of the GNU General Public License as published by
   6 %# the Free Software Foundation; either version 2 of the License, or
   7 %# (at your option) any later version.
   8 %#
   9 %# This program is distributed in the hope that it will be useful,
  10 %# but WITHOUT ANY WARRANTY; without even the implied warranty of
  11 %# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  12 %# GNU General Public License for more details.
  13 %#
  14 %# You should have received a copy of the GNU General Public License
  15 %# along with this program; If not, see <http://www.gnu.org/licenses/>.
  16
  17 %# -*- texinfo -*-
  18 %# @deftypefn  {Function File} {[@var{odestruct}] =} odeset ()
  19 %# @deftypefnx {Command}  {[@var{odestruct}] =} odeset (@var{"field1"}, @var{value1}, @var{"field2"}, @var{value2}, @dots{})
  20 %# @deftypefnx {Command}  {[@var{odestruct}] =} odeset (@var{oldstruct}, @var{"field1"}, @var{value1}, @var{"field2"}, @var{value2}, @dots{})
  21 %# @deftypefnx {Command}  {[@var{odestruct}] =} odeset (@var{oldstruct}, @var{newstruct})
  22 %#
  23 %# If this function is called without an input argument then return a new OdePkg options structure array that contains all the necessary fields and sets the values of all fields to default values.
  24 %#
  25 %# If this function is called with string input arguments @var{"field1"}, @var{"field2"}, @dots{} identifying valid OdePkg options then return a new OdePkg options structure with all necessary fields and set the values of the fields @var{"field1"}, @var{"field2"}, @dots{} to the values @var{value1}, @var{value2}, @dots{}
  26 %#
  27 %# If this function is called with a first input argument @var{oldstruct} of type structure array then overwrite all values of the options @var{"field1"}, @var{"field2"}, @dots{} of the structure @var{oldstruct} with new values @var{value1}, @var{value2}, @dots{} and return the modified structure array.
  28 %#
  29 %# If this function is called with two input argumnets @var{oldstruct} and @var{newstruct} of type structure array then overwrite all values in the fields from the structure @var{oldstruct} with new values of the fields from the structure @var{newstruct}. Empty values of @var{newstruct} will not overwrite values in @var{oldstruct}.
  30 %#
  31 %# For a detailed explanation about valid fields and field values in an OdePkg structure aaray have a look at the @file{odepkg.pdf}, Section 'ODE/DAE/IDE/DDE options' or run the command @command{doc odepkg} to open the tutorial.
  32 %#
  33 %# Run examples with the command
  34 %# @example
  35 %# demo odeset
  36 %# @end example
  37 %# @end deftypefn
  38 %#
  39 %# @seealso{odepkg}
  40
  41 function [vret] = odeset (varargin)
  42
  43   %# Create a template OdePkg structure
  44   vtemplate = struct ...
  45     ('RelTol', [], ...
  46      'AbsTol', [], ...
  47      'NormControl', 'off', ...
  48      'NonNegative', [], ...
  49      'OutputFcn', [], ...
  50      'OutputSel', [], ...
  51      'OutputSave',[],...
  52      'Refine', 0, ...
  53      'Stats', 'off', ...
  54      'InitialStep', [], ...
  55      'MaxStep', [], ...
  56      'Events', [], ...
  57      'Jacobian', [], ...
  58      'JPattern', [], ...
  59      'Vectorized', 'off', ...
  60      'Mass', [], ...
  61      'MStateDependence', 'weak', ...
  62      'MvPattern', [], ...
  63      'MassSingular', 'maybe', ...
  64      'InitialSlope', [], ...
  65      'MaxOrder', [], ...
  66      'BDF', [], ...
  67      'NewtonTol', [], ...
  68      'MaxNewtonIterations', []);
  69
  70   %# Check number and types of all input arguments
  71   if (nargin == 0 && nargout == 1)
  72     vret = odepkg_structure_check (vtemplate);
  73     return;
  74
  75   elseif (nargin == 0)
  76     help ('odeset');
  77     error ('OdePkg:InvalidArgument', ...
  78       'Number of input arguments must be greater than zero');
  79
  80   elseif (length (varargin) < 2)
  81     usage ('odeset ("field1", "value1", ...)');
  82
  83   elseif (ischar (varargin{1}) && mod (length (varargin), 2) == 0)
  84     %# Check if there is an odd number of input arguments. If this is
  85     %# true then save all the structure names in varg and its values in
  86     %# vval and increment vnmb for every option that is found.
  87     vnmb = 1;
  88     for vcntarg = 1:2:length (varargin)
  89       if (ischar (varargin{vcntarg}))
  90         varg{vnmb} = varargin{vcntarg};
  91         vval{vnmb} = varargin{vcntarg+1};
  92         vnmb = vnmb + 1;
  93       else
  94         error ('OdePkg:InvalidArgument', ...
  95           'Input argument number %d is no valid string', vcntarg);
  96       end
  97     end
  98
  99     %# Create and return a new OdePkg structure and fill up all new
 100     %# field values that have been found.
 101     for vcntarg = 1:(vnmb-1)
 102       vtemplate.(varg{vcntarg}) = vval{vcntarg};
 103     end
 104     vret = odepkg_structure_check (vtemplate);
 105
 106   elseif (isstruct (varargin{1}) && ischar (varargin{2}) && ...
 107     mod (length (varargin), 2) == 1)
 108     %# Check if there is an even number of input arguments. If this is
 109     %# true then the first input argument also must be a valid OdePkg
 110     %# structure. Save all the structure names in varg and its values in
 111     %# vval and increment the vnmb counter for every option that is
 112     %# found.
 113     vnmb = 1;
 114     for vcntarg = 2:2:length (varargin)
 115       if (ischar (varargin{vcntarg}))
 116         varg{vnmb} = varargin{vcntarg};
 117         vval{vnmb} = varargin{vcntarg+1};
 118         vnmb = vnmb + 1;
 119       else
 120         error ('OdePkg:InvalidArgument', ...
 121           'Input argument number %d is no valid string', vcntarg);
 122       end
 123     end
 124
 125     %# Use the old OdePkg structure and fill up all new field values
 126     %# that have been found.
 127     vret = odepkg_structure_check (varargin{1});
 128     for vcntarg = 1:(vnmb-1)
 129       vret.(varg{vcntarg}) = vval{vcntarg};
 130     end
 131     vret = odepkg_structure_check (vret);
 132
 133   elseif (isstruct (varargin{1}) && isstruct (varargin{2}) && ...
 134     length (varargin) == 2)
 135     %# Check if the two input arguments are valid OdePkg structures and
 136     %# also check if there does not exist any other input argument.
 137     vret = odepkg_structure_check (varargin{1});
 138     vnew = odepkg_structure_check (varargin{2});
 139     vfld = fieldnames (vnew);
 140     vlen = length (vfld);
 141     for vcntfld = 1:vlen
 142       if (~isempty (vnew.(vfld{vcntfld})))
 143         vret.(vfld{vcntfld}) = vnew.(vfld{vcntfld});
 144       end
 145     end
 146     vret = odepkg_structure_check (vret);
 147
 148   else
 149     error ('OdePkg:InvalidArgument', ...
 150       'Check types and number of all input arguments');
 151   end
 152 end
 153
 154 %# All tests that are needed to check if a correct resp. valid option
 155 %# has been set are implemented in odepkg_structure_check.m.
 156 %!test odeoptA = odeset ();
 157 %!test odeoptB = odeset ('AbsTol', 1e-2, 'RelTol', 1e-1);
 158 %!     if (odeoptB.AbsTol ~= 1e-2), error; end
 159 %!     if (odeoptB.RelTol ~= 1e-1), error; end
 160 %!test odeoptB = odeset ('AbsTol', 1e-2, 'RelTol', 1e-1);
 161 %!     odeoptC = odeset (odeoptB, 'NormControl', 'on');
 162 %!test odeoptB = odeset ('AbsTol', 1e-2, 'RelTol', 1e-1);
 163 %!     odeoptC = odeset (odeoptB, 'NormControl', 'on');
 164 %!     odeoptD = odeset (odeoptC, odeoptB);
 165
 166 %!demo
 167 %! # A new OdePkg options structure with default values is created.
 168 %!
 169 %! odeoptA = odeset ();
 170 %!
 171 %!demo
 172 %! # A new OdePkg options structure with manually set options
 173 %! # "AbsTol" and "RelTol" is created.
 174 %!
 175 %! odeoptB = odeset ('AbsTol', 1e-2, 'RelTol', 1e-1);
 176 %!
 177 %!demo
 178 %! # A new OdePkg options structure from odeoptB is created with
 179 %! # a modified value for option "NormControl".
 180 %!
 181 %! odeoptB = odeset ('AbsTol', 1e-2, 'RelTol', 1e-1);
 182 %! odeoptC = odeset (odeoptB, 'NormControl', 'on');
 183
 184 %# Local Variables: ***
 185 %# mode: octave ***
 186 %# End: ***