Mercurial > hg > octave-jordi

changeset 4050:6481f41a79f3

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
[project @ 2002-08-17 02:18:18 by jwe]
author jwe
date Sat, 17 Aug 2002 02:18:18 +0000
parents a35a3c5d4740
children b79da8779a0e
files ChangeLog Makeconf.in liboctave/DASPK-opts.in liboctave/DASRT-opts.in liboctave/DASRT.cc liboctave/DASSL-opts.in liboctave/NLEqn-opts.in mk-opts.pl
diffstat 8 files changed, 300 insertions(+), 45 deletions(-) [+]
line wrap: on
line diff
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,7 @@
+2002-08-16  John W. Eaton  <jwe@bevo.che.wisc.edu>
+
+	* Makeconf.in (%.d : %.cc): Add $*.df to LHS of dependency list.
+
 2002-08-15  Paul Kienzle <pkienzle@users.sf.net>
 
 	* mk-opts.pl: Add support for INCLUDE = "...".
--- a/Makeconf.in
+++ b/Makeconf.in
@@ -312,7 +312,7 @@
 	  sed \
               $(DEPEND_EXTRA_SED_PATTERN) \
 	      -e 's,^[^:]*/\(.*\.o\):,\1:,' \
-	      -e 's,$*\.o,pic/& & $@,g' > $@-t
+	      -e 's,$*\.o,pic/& & $*.df $@,g' > $@-t
 	@mv $@-t $@
 
 # And one for .c files.too:
--- a/liboctave/DASPK-opts.in
+++ b/liboctave/DASPK-opts.in
@@ -4,6 +4,11 @@
 
 OPTION
   NAME = "absolute tolerance"
+  DOC_ITEM
+Absolute tolerance.  May be either vector or scalar.  If a vector, it
+must match the dimension of the state vector, and the relative
+tolerance must also be a vector of the same length.
+  END_DOC_ITEM
   TYPE = "Array<double>"
   SET_ARG_TYPE = "const $TYPE&"
   INIT_BODY
@@ -25,6 +30,17 @@
 
 OPTION
   NAME = "relative tolerance"
+  DOC_ITEM
+Relative tolerance.  May be either vector or scalar.  If a vector, it
+must match the dimension of the state vector, and the absolute
+tolerance must also be a vector of the same length.
+
+The local error test applied at each integration step is
+
+@example
+  abs (local error in x(i)) <= rtol(i) * abs (Y(i)) + atol(i)
+@end example
+  END_DOC_ITEM
   TYPE = "Array<double>"
   SET_ARG_TYPE = "const $TYPE&"
   INIT_BODY
@@ -46,6 +62,108 @@
 
 OPTION
   NAME = "compute consistent initial condition"
+  DOC_ITEM
+Denoting the differential variables in the state vector by @samp{Y_d}
+and the algebraic variables by @samp{Y_a}, @code{ddaspk} can solve
+one of two initialization problems:
+
+@enumerate
+@item Given Y_d, calculate Y_a and Y'_d
+@item Given Y', calculate Y.
+@end enumerate
+
+In either case, initial values for the given components are input, and
+initial guesses for the unknown components must also be provided as
+input.  Set this option to 1 to solve the first problem, or 2 to solve
+the second (the default default is 0, so you must provide a set of
+initial conditions that are consistent).
+
+If this option is set to a nonzero value, you must also set the
+@code{\"algebraic variables\"} option to declare which variables in the
+problem are algebraic.
+  END_DOC_ITEM
+  TYPE = "int"
+  INIT_VALUE = "0"
+  SET_EXPR = "val"
+END_OPTION
+
+OPTION
+  NAME = "use initial condition heuristics"
+  DOC_ITEM
+Set to a nonzero value to use the initial condition heuristics options
+described below.
+  END_DOC_ITEM
+  TYPE = "int"
+  INIT_VALUE = "0"
+  SET_EXPR = "val"
+END_OPTION
+
+OPTION
+  NAME = "initial condition heuristics"
+  DOC_ITEM
+A vector of the following parameters that can be used to control the
+initial condition calculation.
+
+@table @code
+@item MXNIT
+Maximum number of Newton iterations (default is 5).
+@item MXNJ
+Maximum number of Jacobian evaluations (default is 6).
+@item MXNH
+Maximum number of values of the artificial stepsize parameter to be
+tried if the @code{\"compute consistent initial condition\"} option has
+been set to 1 (default is 5).
+
+Note that the maximum number of Newton iterations allowed in all is
+@code{MXNIT*MXNJ*MXNH} if the @code{\"compute consistent initial
+condition\"} option has been set to 1 and @code{MXNIT*MXNJ} if it is
+set to 2.
+@item LSOFF
+Set to a nonzero value to disable the linesearch algorithm (default is
+0).
+@item STPTOL
+Minimum scaled step in linesearch algorithm (default is eps^(2/3)).
+@item EPINIT
+Swing factor in the Newton iteration convergence test.  The test is
+applied to the residual vector, premultiplied by the approximate
+Jacobian.  For convergence, the weighted RMS norm of this vector
+(scaled by the error weights) must be less than @code{EPINIT*EPCON},
+where @code{EPCON} = 0.33 is the analogous test constant used in the
+time steps. The default is @code{EPINIT} = 0.01.
+@end table
+  END_DOC_ITEM
+  TYPE = "Array<double>"
+  SET_ARG_TYPE = "const $TYPE&"
+  INIT_BODY
+    $OPTVAR.resize (6, 0.0);
+    $OPTVAR(0) = 5.0;
+    $OPTVAR(1) = 6.0;
+    $OPTVAR(2) = 5.0;
+    $OPTVAR(3) = 0.0;
+    $OPTVAR(4) = ::pow (DBL_EPSILON, 2.0/3.0);
+    $OPTVAR(5) = 0.01;
+  END_INIT_BODY
+  SET_EXPR = "val"
+END_OPTION
+
+OPTION
+  NAME = "print initial condition info"
+  DOC_ITEM
+Set this option to a nonzero value to display detailed information
+about the initial condition calculation (default is 0).
+  END_DOC_ITEM
+  TYPE = "int"
+  INIT_VALUE = "0"
+  SET_EXPR = "val"
+END_OPTION
+
+OPTION
+  NAME = "exclude algebraic variables from error test"
+  DOC_ITEM
+Set to a nonzero value to exclude algebraic variables from the error
+test.  You must also set the @code{\"algebraic variables\"} option to
+declare which variables in the problem are algebraic (default is 0).
+  END_DOC_ITEM
   TYPE = "int"
   INIT_VALUE = "0"
   SET_EXPR = "val"
@@ -53,6 +171,16 @@
 
 OPTION
   NAME = "algebraic variables"
+  DOC_ITEM
+A vector of the same length as the state vector.  A nonzero element
+indicates that the corresponding element of the state vector is an
+algebraic variable (i.e., its derivative does not appear explicitly
+in the equation set.
+
+This option is required by the
+@code{compute consistent initial condition\"} and
+@code{\"exclude algebraic variables from error test\"} options.
+  END_DOC_ITEM
   TYPE = "Array<int>"
   SET_ARG_TYPE = const $TYPE&
   INIT_BODY
@@ -74,6 +202,17 @@
 
 OPTION
   NAME = "enforce inequality constraints"
+  DOC_ITEM
+Set to one of the following values to enforce the inequality
+constraints specified by the @code{\"inequality constraint types\"}
+option (default is 0).
+
+@enumerate
+@item To have constraint checking only in the initial condition calculation.
+@item To enforce constraint checking during the integration.
+@item To enforce both options 1 and 2.
+@end enumerate
+  END_DOC_ITEM
   TYPE = "int"
   INIT_VALUE = "0"
   SET_EXPR = "val"
@@ -81,6 +220,28 @@
 
 OPTION
   NAME = "inequality constraint types"
+  DOC_ITEM
+A vector of the same length as the state specifying the type of
+inequality constraint.  Each element of the vector corresponds to an
+element of the state and should be assigned one of the following
+codes 
+
+@table @asis
+@item -2
+Less than zero.
+@item -1
+Less than or equal to zero.
+@item 0
+Not constrained.
+@item 1
+Greater than or equal to zero.
+@item 2
+Greater than zero.
+@end table
+
+This option only has an effect if the
+@code{\"enforce inequality constraints\"} option is nonzero.
+  END_DOC_ITEM
   TYPE = "Array<int>"
   SET_ARG_TYPE = const $TYPE&
   INIT_BODY
@@ -101,37 +262,14 @@
 END_OPTION
 
 OPTION
-  NAME = "exclude algebraic variables from error test"
-  TYPE = "int"
-  INIT_VALUE = "0"
-  SET_EXPR = "val"
-END_OPTION
-
-OPTION
-  NAME = "use initial condition heuristics"
-  TYPE = "int"
-  INIT_VALUE = "0"
-  SET_EXPR = "val"
-END_OPTION
-
-OPTION
-  NAME = "initial condition heuristics"
-  TYPE = "Array<double>"
-  SET_ARG_TYPE = "const $TYPE&"
-  INIT_BODY
-    $OPTVAR.resize (6, 0.0);
-    $OPTVAR(0) = 5.0;
-    $OPTVAR(1) = 6.0;
-    $OPTVAR(2) = 5.0;
-    $OPTVAR(3) = 0.0;
-    $OPTVAR(4) = ::pow (DBL_EPSILON, 2.0/3.0);
-    $OPTVAR(5) = 0.01;
-  END_INIT_BODY
-  SET_EXPR = "val"
-END_OPTION
-
-OPTION
   NAME = "initial step size"
+  DOC_ITEM
+Differential-algebraic problems may occaisionally suffer from severe
+scaling difficulties on the first step.  If you know a great deal
+about the scaling of your problem, you can help to alleviate this
+problem by specifying an initial stepsize (default is computed
+automatically).
+  END_DOC_ITEM
   TYPE = "double"
   INIT_VALUE = "-1.0"
   SET_EXPR = "(val >= 0.0) ? val : -1.0"
@@ -139,21 +277,22 @@
 
 OPTION
   NAME = "maximum order"
+  DOC_ITEM
+Restrict the maximum order of the solution method.  This option must
+be between 1 and 5, inclusive (default is 5).
+  END_DOC_ITEM
   TYPE = "int"
-  INIT_VALUE = "-1"
+  INIT_VALUE = "5"
   SET_EXPR = "val"
 END_OPTION
 
 OPTION
   NAME = "maximum step size"
+  DOC_ITEM
+Setting the maximum stepsize will avoid passing over very large
+regions (default is not specified).
+  END_DOC_ITEM
   TYPE = "double"
   INIT_VALUE = "-1.0"
   SET_EXPR = "(val >= 0.0) ? val : -1.0"
 END_OPTION
-
-OPTION
-  NAME = "print initial condition info"
-  TYPE = "int"
-  INIT_VALUE = "0"
-  SET_EXPR = "val"
-END_OPTION
--- a/liboctave/DASRT-opts.in
+++ b/liboctave/DASRT-opts.in
@@ -4,6 +4,11 @@
 
 OPTION
   NAME = "absolute tolerance"
+  DOC_ITEM
+Absolute tolerance.  May be either vector or scalar.  If a vector, it
+must match the dimension of the state vector, and the relative
+tolerance must also be a vector of the same length.
+  END_DOC_ITEM
   TYPE = "Array<double>"
   SET_ARG_TYPE = "const $TYPE&"
   INIT_BODY
@@ -25,6 +30,16 @@
 
 OPTION
   NAME = "relative tolerance"
+  DOC_ITEM
+Relative tolerance.  May be either vector or scalar.  If a vector, it
+must match the dimension of the state vector, and the absolute
+tolerance must also be a vector of the same length.
+
+The local error test applied at each integration step is
+@example
+  abs (local error in x(i)) <= rtol(i) * abs (Y(i)) + atol(i)
+@end example
+  END_DOC_ITEM
   TYPE = "Array<double>"
   SET_ARG_TYPE = "const $TYPE&"
   INIT_BODY
@@ -46,6 +61,12 @@
 
 OPTION
   NAME = "initial step size"
+  DOC_ITEM
+Differential-algebraic problems may occaisionally suffer from severe
+scaling difficulties on the first step.  If you know a great deal
+about the scaling of your problem, you can help to alleviate this
+problem by specifying an initial stepsize.
+  END_DOC_ITEM
   TYPE = "double"
   INIT_VALUE = "-1.0"
   SET_EXPR = "(val >= 0.0) ? val : -1.0"
@@ -53,6 +74,10 @@
 
 OPTION
   NAME = "maximum order"
+  DOC_ITEM
+Restrict the maximum order of the solution method.  This option must
+be between 1 and 5, inclusive.
+  END_DOC_ITEM
   TYPE = "int"
   INIT_VALUE = "-1"
   SET_EXPR = "val"
@@ -60,6 +85,10 @@
 
 OPTION
   NAME = "maximum step size"
+  DOC_ITEM
+Setting the maximum stepsize will avoid passing over very large
+regions.
+  END_DOC_ITEM
   TYPE = "double"
   INIT_VALUE = "-1.0"
   SET_EXPR = "(val >= 0.0) ? val : -1.0"
@@ -67,6 +96,10 @@
 
 OPTION
   NAME = "step limit"
+  DOC_ITEM
+Maximum number of integration steps to attempt on a single call to the
+underlying Fortran code.
+  END_DOC_ITEM
   TYPE = "int"
   INIT_VALUE = "-1"
   SET_EXPR = "(val >= 0) ? val : -1"
--- a/liboctave/DASRT.cc
+++ b/liboctave/DASRT.cc
@@ -242,17 +242,19 @@
 
       // DASRT_options
 
-      if (maximum_step_size () >= 0.0)
+      double mss = maximum_step_size ();
+      if (mss >= 0.0)
 	{
-	  rwork(1) = maximum_step_size ();
+	  rwork(1) = mss;
 	  info(6) = 1;
 	}
       else
 	info(6) = 0;
 
-      if (initial_step_size () >= 0.0)
+      double iss = initial_step_size ();
+      if (iss >= 0.0)
 	{
-	  rwork(2) = initial_step_size ();
+	  rwork(2) = iss;
 	  info(7) = 1;
 	}
       else
--- a/liboctave/DASSL-opts.in
+++ b/liboctave/DASSL-opts.in
@@ -4,6 +4,11 @@
 
 OPTION
   NAME = "absolute tolerance"
+  DOC_ITEM
+Absolute tolerance.  May be either vector or scalar.  If a vector, it
+must match the dimension of the state vector, and the relative
+tolerance must also be a vector of the same length.
+  END_DOC_ITEM
   TYPE = "Array<double>"
   SET_ARG_TYPE = "const $TYPE&"
   INIT_BODY
@@ -25,6 +30,16 @@
 
 OPTION
   NAME = "relative tolerance"
+  DOC_ITEM
+Relative tolerance.  May be either vector or scalar.  If a vector, it
+must match the dimension of the state vector, and the absolute
+tolerance must also be a vector of the same length.
+
+The local error test applied at each integration step is
+@example
+  abs (local error in x(i)) <= rtol(i) * abs (Y(i)) + atol(i)
+@end example
+  END_DOC_ITEM
   TYPE = "Array<double>"
   SET_ARG_TYPE = "const $TYPE&"
   INIT_BODY
@@ -46,6 +61,11 @@
 
 OPTION
   NAME = "compute consistent initial condition"
+  DOC_ITEM
+If nonzero, dassl will attempt to compute a consistent set of intial
+conditions.  This is generally not reliable, so it is best to provide
+a consistent set and leave this option set to zero.
+  END_DOC_ITEM
   TYPE = "int"
   INIT_VALUE = "0"
   SET_EXPR = "val"
@@ -53,6 +73,13 @@
 
 OPTION
   NAME = "enforce nonnegativity constraints"
+  DOC_ITEM
+If you know that the solutions to your equations will always be
+nonnegative, it may help to set this parameter to a nonzero
+value.  However, it is probably best to try leaving this option set to
+zero first, and only setting it to a nonzero value if that doesn't
+work very well.
+  END_DOC_ITEM
   TYPE = "int"
   INIT_VALUE = "0"
   SET_EXPR = "val"
@@ -60,6 +87,12 @@
 
 OPTION
   NAME = "initial step size"
+  DOC_ITEM
+Differential-algebraic problems may occaisionally suffer from severe
+scaling difficulties on the first step.  If you know a great deal
+about the scaling of your problem, you can help to alleviate this
+problem by specifying an initial stepsize.
+  END_DOC_ITEM
   TYPE = "double"
   INIT_VALUE = "-1.0"
   SET_EXPR = "(val >= 0.0) ? val : -1.0"
@@ -67,6 +100,10 @@
 
 OPTION
   NAME = "maximum order"
+  DOC_ITEM
+Restrict the maximum order of the solution method.  This option must
+be between 1 and 5, inclusive.
+  END_DOC_ITEM
   TYPE = "int"
   INIT_VALUE = "-1"
   SET_EXPR = "val"
@@ -74,6 +111,10 @@
 
 OPTION
   NAME = "maximum step size"
+  DOC_ITEM
+Setting the maximum stepsize will avoid passing over very large
+regions.
+  END_DOC_ITEM
   TYPE = "double"
   INIT_VALUE = "-1.0"
   SET_EXPR = "(val >= 0.0) ? val : -1.0"
--- a/liboctave/NLEqn-opts.in
+++ b/liboctave/NLEqn-opts.in
@@ -16,6 +16,9 @@
 
 OPTION
   NAME = "tolerance"
+  DOC_ITEM
+Nonnegative relative tolerance.
+  END_DOC_ITEM
   TYPE = "double"
   INIT_VALUE = "::sqrt (DBL_EPSILON)"
   SET_EXPR = "(val > 0.0) ? val : ::sqrt (DBL_EPSILON)"
--- a/mk-opts.pl
+++ b/mk-opts.pl
@@ -20,6 +20,7 @@
 # DOC_STRING doc END_DOC_STRING
 # OPTION
 #   NAME = string
+#   DOC_ITEM doc END_DOC_ITEM
 #   TYPE = string
 #   SET_ARG_TYPE = string   (optional, defaults to TYPE)
 #   INIT_VALUE = string | INIT_BODY code END_INIT_BODY
@@ -107,7 +108,7 @@
 
 sub parse_option_block
 {
-  local ($have_init_body, $have_set_body, $have_set_code);
+  local ($have_doc_item, $have_init_body, $have_set_body, $have_set_code);
 
   while (<INFILE>)
     {
@@ -126,6 +127,12 @@
           $kw_tok[$opt_num] = [ split (/\s+/, $name[$opt_num]) ];
           $n_toks[$opt_num] = @{$kw_tok[$opt_num]};
         }
+      elsif (/^\s*DOC_ITEM\s*$/)
+        {
+          die "duplicate DOC_ITEM" if ($have_doc_item);
+          &parse_doc_item;
+          $have_doc_item = 1;
+        }
       elsif (/^\s*TYPE\s*=\s*"(.*)"\s*$/)
         {
           die "duplicate TYPE" if ($type[$opt_num] ne "");
@@ -292,6 +299,18 @@
   $doc_string =~ s/\n/\\n\\\n/g;
 }
 
+sub parse_doc_item
+{
+  while (<INFILE>)
+    {
+      last if (/^\s*END_DOC_ITEM\s*$/);
+
+      $doc_item[$opt_num] .= $_;
+    }
+
+  $doc_item[$opt_num] =~ s/\n/\\n\\\n/g;
+}
+
 sub parse_init_body
 {
   while (<INFILE>)
@@ -794,7 +813,21 @@
   print "DEFUN_DLD ($opt_fcn_name, args, ,
   \"-*- texinfo -*-\\n\\
 \@deftypefn {Loadable Function} {} $opt_fcn_name (\@var{opt}, \@var{val})\\n\\
-$doc_string\@end deftypefn\")
+$doc_string\\n\\
+Options include\\n\\
+\\n\\
+\@table \@code\\n\\\n";
+
+  for ($i = 0; $i < $opt_num; $i++)
+    {
+      print "\@item \\\"$name[$i]\\\"\\n\\\n";
+      if ($doc_item[$i] ne "")
+	{
+	  print "$doc_item[$i]";
+	}
+    }
+
+  print "\@end table\\n\\\n\@end deftypefn\")
 {
   octave_value_list retval;