/[ascend]/trunk/tcltk/generic/interface/Integrators.h
ViewVC logotype

Diff of /trunk/tcltk/generic/interface/Integrators.h

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 689 by johnpye, Wed Jun 21 08:03:18 2006 UTC revision 690 by johnpye, Thu Jun 22 00:48:31 2006 UTC
# Line 1  Line 1 
1  /*  ASCEND modelling environment  /*  ASCEND modelling environment
2      Copyright 1997, Carnegie Mellon University      Copyright 1997, Carnegie Mellon University
3      Copyright (C) 2006 Carnegie Mellon University      Copyright (C) 2006 Carnegie Mellon University
4    
5      This program is free software; you can redistribute it and/or modify      This program is free software; you can redistribute it and/or modify
6      it under the terms of the GNU General Public License as published by      it under the terms of the GNU General Public License as published by
7      the Free Software Foundation; either version 2, or (at your option)      the Free Software Foundation; either version 2, or (at your option)
8      any later version.      any later version.
9    
10      This program is distributed in the hope that it will be useful,      This program is distributed in the hope that it will be useful,
11      but WITHOUT ANY WARRANTY; without even the implied warranty of      but WITHOUT ANY WARRANTY; without even the implied warranty of
12      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the      MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
13      GNU General Public License for more details.      GNU General Public License for more details.
14    
15      You should have received a copy of the GNU General Public License      You should have received a copy of the GNU General Public License
16      along with this program; if not, write to the Free Software      along with this program; if not, write to the Free Software
17      Foundation, Inc., 59 Temple Place - Suite 330,      Foundation, Inc., 59 Temple Place - Suite 330,
18      Boston, MA 02111-1307, USA.      Boston, MA 02111-1307, USA.
19  *//** @file  *//** @file
20      Implementation of the Integration Interface.      Implementation of the Integration Interface.
21    
22      This module defines the general integration auxillaries for Ascend.      This module defines the general integration auxillaries for Ascend.
23    
24      Requires      Requires
25      #include "tcl.h"      #include "tcl.h"
26      #include "utilities/ascConfig.h      #include "utilities/ascConfig.h
27      #include "general/list.h"      #include "general/list.h"
28      #include "compiler/instance_enum.h"      #include "compiler/instance_enum.h"
29      #include "compiler/dimen.h"      #include "compiler/dimen.h"
30      #include "solver/slv_client.h"      #include "solver/slv_client.h"
31      #include "compiler/interface.h"      #include "compiler/interface.h"
32      #include <stdio.h>   (for current INTEG_DEBUG functions)      #include <stdio.h>   (for current INTEG_DEBUG functions)
33  *//*  *//*
34      Author:       Boyd T. Safrit      Author:       Boyd T. Safrit
35      by Kirk Abbott and Ben Allan      by Kirk Abbott and Ben Allan
36      Created: 1/94      Created: 1/94
37      Version: $Revision: 1.16 $      Version: $Revision: 1.16 $
38      Version control file: $RCSfile: Integrators.h,v $      Version control file: $RCSfile: Integrators.h,v $
39      Date last modified: $Date: 2003/08/23 18:43:06 $      Date last modified: $Date: 2003/08/23 18:43:06 $
40      Last modified by: $Author: ballan $      Last modified by: $Author: ballan $
41    
42      Changes:  8/95  Added support code for BLSODE, an      Changes:  8/95  Added support code for BLSODE, an
43                      experimental user interface                      experimental user interface
44                      which identifies states, derivatives,                      which identifies states, derivatives,
45                      observations, and tolerances by flags.                      observations, and tolerances by flags.
46                      Interface redesign (ASCEND side) by                      Interface redesign (ASCEND side) by
47                      Jennifer Stokes and (C side) Ben Allan.                      Jennifer Stokes and (C side) Ben Allan.
48                      The only required vector left is that                      The only required vector left is that
49                      defining the time steps to calculate                      defining the time steps to calculate
50                      results at. All state and observation                      results at. All state and observation
51                      data are (optionally) logged to files.                      data are (optionally) logged to files.
52                5/96  Removed old lsode interface routines.                5/96  Removed old lsode interface routines.
53                      The Piela version of lsode is dead.                      The Piela version of lsode is dead.
54                8/96  Removed the var == instance assumption from                8/96  Removed the var == instance assumption from
55                      the implementation.                      the implementation.
56  */  */
57    
58    
59  #ifndef ASCTK_INTEGRATORS_H  #ifndef ASCTK_INTEGRATORS_H
60  #define ASCTK_INTEGRATORS_H  #define ASCTK_INTEGRATORS_H
61    
62  #include <solver/integrator.h>  #include <solver/integrator.h>
63    
64  extern int Asc_IntegSetYFileCmd(ClientData cdata, Tcl_Interp *interp,  extern int Asc_IntegSetYFileCmd(ClientData cdata, Tcl_Interp *interp,
65                                  int argc, CONST84 char *argv[]);                                  int argc, CONST84 char *argv[]);
66  /**<  /**<
67   *  Set the next filename to be used for integration state variable   *  Set the next filename to be used for integration state variable
68   *  logging. Does not check the filesystem sanity of the given name.<br><br>   *  logging. Does not check the filesystem sanity of the given name.<br><br>
69   *   *
70   *  Registered as: integrate_set_y_file filename   *  Registered as: integrate_set_y_file filename
71   */   */
72    
73  extern int Asc_IntegSetObsFileCmd(ClientData cdata, Tcl_Interp *interp,  extern int Asc_IntegSetObsFileCmd(ClientData cdata, Tcl_Interp *interp,
74                                    int argc, CONST84 char *argv[]);                                    int argc, CONST84 char *argv[]);
75  /**<  /**<
76   *  Set the next filename to be used for integration observation variable   *  Set the next filename to be used for integration observation variable
77   *  logging. Does not check the filesystem sanity of the given name.<br><br>   *  logging. Does not check the filesystem sanity of the given name.<br><br>
78   *   *
79   *  Registered as: integrate_set_obs_file filename   *  Registered as: integrate_set_obs_file filename
80   */   */
81    
82  extern int Asc_IntegSetFileUnitsCmd(ClientData cdata, Tcl_Interp *interp,  extern int Asc_IntegSetFileUnitsCmd(ClientData cdata, Tcl_Interp *interp,
83                                      int argc, CONST84 char *argv[]);                                      int argc, CONST84 char *argv[]);
84  /**<  /**<
85   *  Sets output to be in SI (internal) units or in the user set display   *  Sets output to be in SI (internal) units or in the user set display
86   *  units. If display is selected and the variable to be printed cannot   *  units. If display is selected and the variable to be printed cannot
87   *  be displayed in the display units because of floating point errors   *  be displayed in the display units because of floating point errors
88   *  in conversion, the value will be printed in SI units and a warning   *  in conversion, the value will be printed in SI units and a warning
89   *  issued to stderr. The user is then expected to deal with the problem   *  issued to stderr. The user is then expected to deal with the problem
90   *  of inconsistency in his output.   *  of inconsistency in his output.
91   *  Only the first letter of the argument is significant.<br><br>   *  Only the first letter of the argument is significant.<br><br>
92   *   *
93   *  Registered as: integrate_logunits <display,si>   *  Registered as: integrate_logunits <display,si>
94   */   */
95    
96  extern int Asc_IntegSetFileFormatCmd(ClientData cdata, Tcl_Interp *interp,  extern int Asc_IntegSetFileFormatCmd(ClientData cdata, Tcl_Interp *interp,
97                                       int argc, CONST84 char *argv[]);                                       int argc, CONST84 char *argv[]);
98  /**<  /**<
99   *  Sets output data to be in fixed column width (with extra white) or in   *  Sets output data to be in fixed column width (with extra white) or in
100   *  space separated columns whose width is variable from line to line.   *  space separated columns whose width is variable from line to line.
101   *  Only the first letter of the argument is significant.<br><br>   *  Only the first letter of the argument is significant.<br><br>
102   *   *
103   *  Registered as: integrate_logformat <fixed,variable>   *  Registered as: integrate_logformat <fixed,variable>
104   */   */
105    
106    
107    
108  extern int Asc_IntegGetXSamplesCmd(ClientData cdata, Tcl_Interp *interp,  extern int Asc_IntegGetXSamplesCmd(ClientData cdata, Tcl_Interp *interp,
109                                     int argc, CONST84 char *argv[]);                                     int argc, CONST84 char *argv[]);
110  /**<  /**<
111   *  Returns the current vector of independent variable samples as fed to   *  Returns the current vector of independent variable samples as fed to
112   *  smarter integrators such as lsode. Returns 2 element list:   *  smarter integrators such as lsode. Returns 2 element list:
113   *  {units of x} {list of doubles in the units indicated in the first   *  {units of x} {list of doubles in the units indicated in the first
114   *  element}. In the event that display is given but the sample values   *  element}. In the event that display is given but the sample values
115   *  (which are stored in si) cannot be converted to display units, the   *  (which are stored in si) cannot be converted to display units, the
116   *  units of x in the first element will change and the SI values will   *  units of x in the first element will change and the SI values will
117   *  be returned in the second element. If display is not given, samples   *  be returned in the second element. If display is not given, samples
118   *  will be returned in SI units.   *  will be returned in SI units.
119   *  The units used will be dimensionally consistent with those specified   *  The units used will be dimensionally consistent with those specified
120   *  when integrate_set_samples was called.   *  when integrate_set_samples was called.
121   *  Only the first letter of the optional argument display is significant.<br><br>   *  Only the first letter of the optional argument display is significant.<br><br>
122   *   *
123   *  Registered as: integrate_get_samples [display]   *  Registered as: integrate_get_samples [display]
124   */   */
125    
126  extern int Asc_IntegSetXSamplesCmd(ClientData data, Tcl_Interp *interp,  extern int Asc_IntegSetXSamplesCmd(ClientData data, Tcl_Interp *interp,
127                                     int argc, CONST84 char *argv[]);                                     int argc, CONST84 char *argv[]);
128  /**<  /**<
129   *  Takes the values given and sets the intervals for smarter   *  Takes the values given and sets the intervals for smarter
130   *  integrators accordingly. Values will be converted to SI values   *  integrators accordingly. Values will be converted to SI values
131   *  using the units given. ?,* is a legal unit, in which case the   *  using the units given. ?,* is a legal unit, in which case the
132   *  values will be assumed to be SI requiring no conversion.   *  values will be assumed to be SI requiring no conversion.
133   *  If no arguments are given, we will free memory allocated for storage   *  If no arguments are given, we will free memory allocated for storage
134   *  of the list, otherwise at least 2 values are required.<br><br>   *  of the list, otherwise at least 2 values are required.<br><br>
135   *   *
136   *  Note: It is the users responsibility to make sure that the dimens/   *  Note: It is the users responsibility to make sure that the dimens/
137   *  units this is called with match the independent variable in the ivp.   *  units this is called with match the independent variable in the ivp.
138   *  C clients are given the power to verify this.   *  C clients are given the power to verify this.
139   *  Also, the units given must already exist: we do not create them.<br><br>   *  Also, the units given must already exist: we do not create them.<br><br>
140   *   *
141   *  Registered as:  integrate_set_samples <units> <value [value...] value>   *  Registered as:  integrate_set_samples <units> <value [value...] value>
142   */   */
143    
144  extern int Asc_IntegInstIntegrableCmd(ClientData cdata, Tcl_Interp *interp,  extern int Asc_IntegInstIntegrableCmd(ClientData cdata, Tcl_Interp *interp,
145                                        int argc, CONST84 char *argv[]);                                        int argc, CONST84 char *argv[]);
146  /**<  /**<
147   *  Returns "1" if instance is integrable by the named integrator, "0"   *  Returns "1" if instance is integrable by the named integrator, "0"
148   *  otherwise. Currently valid names are: lsode   *  otherwise. Currently valid names are: lsode
149   *  The instance examined is "current", "search", or "solver".<br><br>   *  The instance examined is "current", "search", or "solver".<br><br>
150   *   *
151   *  Registered as:  integrate_able <instance> <NAME>   *  Registered as:  integrate_able <instance> <NAME>
152   */   */
153    
154    
155  extern int Asc_IntegSetupCmd(ClientData cdata,Tcl_Interp *interp,  extern int Asc_IntegSetupCmd(ClientData cdata,Tcl_Interp *interp,
156                               int argc, CONST84 char *argv[]);                               int argc, CONST84 char *argv[]);
157  /**<  /**<
158   *  Set up the integrator.   *  Set up the integrator.
159   *  itype is one of the supported integrator types (currently:   *  itype is one of the supported integrator types (currently:
160   *  BLSODE)   *  BLSODE)
161   *  n1 is the start index to run the integrator from.   *  n1 is the start index to run the integrator from.
162   *  n2 is the end index to stop at.   *  n2 is the end index to stop at.
163   *   *
164   *  Registered as:  integrateSetup itype n1 n2   *  Registered as:  integrateSetup itype n1 n2
165   */   */
166    
167  extern int Asc_IntegCleanupCmd(ClientData cdata, Tcl_Interp *interp,  extern int Asc_IntegCleanupCmd(ClientData cdata, Tcl_Interp *interp,
168                                 int argc, CONST84 char *argv[]);                                 int argc, CONST84 char *argv[]);
169  /**<  /**<
170   *  Do any C level housekeeping need after calling integration.   *  Do any C level housekeeping need after calling integration.
171   *  Always use integrate_setup/integrate_cleanup in pairs.<br><br>   *  Always use integrate_setup/integrate_cleanup in pairs.<br><br>
172   *   *
173   *  Registered as:  integrate_cleanup   *  Registered as:  integrate_cleanup
174   */   */
175    
176  /*  functions affecting the logging of data during integration */  /*  functions affecting the logging of data during integration */
177  extern FILE *Asc_IntegOpenYFile(void);  extern FILE *Asc_IntegOpenYFile(void);
178  /**<  /**<
179   *  Returns the pointer to a file to which state   *  Returns the pointer to a file to which state
180   *  variables should be written at each recorded time interval. Other   *  variables should be written at each recorded time interval. Other
181   *  info may be written here as well, but that is up to the designer   *  info may be written here as well, but that is up to the designer
182   *  of the specific integrator interface. The filename used will be   *  of the specific integrator interface. The filename used will be
183   *  the one most recently set via Asc_IntegSetYFileCmd().  If no   *  the one most recently set via Asc_IntegSetYFileCmd().  If no
184   *  name (or an empty name) has been set via Asc_IntegSetYFileCmd(),   *  name (or an empty name) has been set via Asc_IntegSetYFileCmd(),
185   *  the file returned will be NULL.<br><br>   *  the file returned will be NULL.<br><br>
186   *   *
187   *  This function may return NULL, in which case do not write to   *  This function may return NULL, in which case do not write to
188   *  them as there was some problem opening the file.   *  them as there was some problem opening the file.
189   *  If opened successfully, the file returned will have DATASET and   *  If opened successfully, the file returned will have DATASET and
190   *  the open time stamped at the bottom. This will separate multiple   *  the open time stamped at the bottom. This will separate multiple
191   *  runs or changes in the same run.<br><br>   *  runs or changes in the same run.<br><br>
192   *   *
193   *  Closing the files is your job.  When finished with the file, you   *  Closing the files is your job.  When finished with the file, you
194   *  should call Asc_IntegReleaseYFile() before closing it.   *  should call Asc_IntegReleaseYFile() before closing it.
195   */   */
196  extern FILE *Asc_IntegOpenObsFile(void);  extern FILE *Asc_IntegOpenObsFile(void);
197  /**<  /**<
198   *  Returns the pointer to a file to which observation   *  Returns the pointer to a file to which observation
199   *  variables should be written at each recorded time interval. Other   *  variables should be written at each recorded time interval. Other
200   *  info may be written here as well, but that is up to the designer   *  info may be written here as well, but that is up to the designer
201   *  of the specific integrator interface. The filename used will be   *  of the specific integrator interface. The filename used will be
202   *  the one most recently set via Asc_IntegSetObsFileCmd().  If no   *  the one most recently set via Asc_IntegSetObsFileCmd().  If no
203   *  name (or an empty name) has been set via Asc_IntegSetObsFileCmd(),   *  name (or an empty name) has been set via Asc_IntegSetObsFileCmd(),
204   *  the file returned will be NULL.<br><br>   *  the file returned will be NULL.<br><br>
205   *   *
206   *  This function may return NULL, in which case do not write to   *  This function may return NULL, in which case do not write to
207   *  them as there was some problem opening the file.   *  them as there was some problem opening the file.
208   *  If opened successfully, the file returned will have DATASET and   *  If opened successfully, the file returned will have DATASET and
209   *  the open time stamped at the bottom. This will separate multiple   *  the open time stamped at the bottom. This will separate multiple
210   *  runs or changes in the same run.<br><br>   *  runs or changes in the same run.<br><br>
211   *   *
212   *  Closing the files is your job.  When finished with the file, you   *  Closing the files is your job.  When finished with the file, you
213   *  should call Asc_IntegReleaseObsFile() before closing it.   *  should call Asc_IntegReleaseObsFile() before closing it.
214   */   */
215    
216  /**  /**
217      these functions don't involve Tcl/Tk but they do implement stuff      these functions don't involve Tcl/Tk but they do implement stuff
218      in a way that might not be useful to other interfaces.      in a way that might not be useful to other interfaces.
219  */  */
220    
221  extern FILE *Asc_IntegGetYFile(void);  extern FILE *Asc_IntegGetYFile(void);
222  /**<  /**<
223   *  Returns the current FILE * for writing state variables,   *  Returns the current FILE * for writing state variables,
224   *  or NULL if none.   *  or NULL if none.
225   */   */
226  extern FILE *Asc_IntegGetObsFile(void);  extern FILE *Asc_IntegGetObsFile(void);
227  /**<  /**<
228   *  Returns the current FILE * for writing observation variables,   *  Returns the current FILE * for writing observation variables,
229   *  or NULL if none.   *  or NULL if none.
230   */   */
231  extern void Asc_IntegReleaseYFile(void);  extern void Asc_IntegReleaseYFile(void);
232  extern void Asc_IntegReleaseObsFile(void);  extern void Asc_IntegReleaseObsFile(void);
233  /**<  /**<
234   *  Releases the internally-stored FILE * for observation variables.   *  Releases the internally-stored FILE * for observation variables.
235   *  This does not close the file (which you still need to do).   *  This does not close the file (which you still need to do).
236   *  This function should be called just before closing the files,   *  This function should be called just before closing the files,
237   *  though it may be called sooner if you want to keep the file pointer   *  though it may be called sooner if you want to keep the file pointer
238   *  returned all to yourself.   *  returned all to yourself.
239   */   */
240    
241    
242  extern void Asc_IntegPrintYHeader(FILE *fp, IntegratorSystem *blsys);  extern void Asc_IntegPrintYHeader(FILE *fp, IntegratorSystem *blsys);
243  /**<  /**<
244   *  Prints Y header info to the file given.   *  Prints Y header info to the file given.
245   *  If FILE is NULL, returns immediately.   *  If FILE is NULL, returns immediately.
246   *  If FILE ok, but blsys NULL prints warning to stderr and returns.   *  If FILE ok, but blsys NULL prints warning to stderr and returns.
247   *  At the moment, the written header info is:   *  At the moment, the written header info is:
248   *      A vertical listing of   *      A vertical listing of
249   *      ode_id/obs_id instance_name_as_seen_in_solver.d UNITS   *      ode_id/obs_id instance_name_as_seen_in_solver.d UNITS
250   *      then a row (which will line up with printed values)   *      then a row (which will line up with printed values)
251   *      of the ode_id/obs_id.   *      of the ode_id/obs_id.
252   */   */
253  extern void Asc_IntegPrintObsHeader(FILE *fp, IntegratorSystem *blsys);  extern void Asc_IntegPrintObsHeader(FILE *fp, IntegratorSystem *blsys);
254  /**<  /**<
255   *  Prints observation header info to the file given.   *  Prints observation header info to the file given.
256   *  If FILE is NULL, returns immediately.   *  If FILE is NULL, returns immediately.
257   *  If FILE ok, but blsys NULL prints warning to stderr and returns.   *  If FILE ok, but blsys NULL prints warning to stderr and returns.
258   *  At the moment header info is:   *  At the moment header info is:
259   *      A vertical listing of   *      A vertical listing of
260   *      ode_id/obs_id instance_name_as_seen_in_solver.d UNITS   *      ode_id/obs_id instance_name_as_seen_in_solver.d UNITS
261   *      then a row (which will line up with printed values)   *      then a row (which will line up with printed values)
262   *      of the ode_id/obs_id.   *      of the ode_id/obs_id.
263   */   */
264    
265  extern void Asc_IntegPrintYLine(FILE *fp, IntegratorSystem *blsys);  extern void Asc_IntegPrintYLine(FILE *fp, IntegratorSystem *blsys);
266  /**<  /**<
267   *  Prints a Y line to the file given.   *  Prints a Y line to the file given.
268   *  If FILE is NULL, returns immediately.   *  If FILE is NULL, returns immediately.
269   *  If FILE ok, but blsys NULL prints warning to stderr and returns.   *  If FILE ok, but blsys NULL prints warning to stderr and returns.
270   *  Each line is a set of values, identified by the header, following   *  Each line is a set of values, identified by the header, following
271   *  the value of the independent variable. These lines are of arbitrary   *  the value of the independent variable. These lines are of arbitrary
272   *  length since it is expected that some other program will be   *  length since it is expected that some other program will be
273   *  reading the output, not a human.   *  reading the output, not a human.
274   */   */
275  extern void Asc_IntegPrintObsLine(FILE *fp, IntegratorSystem *blsys);  extern void Asc_IntegPrintObsLine(FILE *fp, IntegratorSystem *blsys);
276  /**<  /**<
277   *  Prints an observation line to the file given.   *  Prints an observation line to the file given.
278   *  If FILE is NULL, returns immediately.   *  If FILE is NULL, returns immediately.
279   *  If FILE ok, but blsys NULL prints warning to stderr and returns.   *  If FILE ok, but blsys NULL prints warning to stderr and returns.
280   *  Each line is a set of values, identified by the header, following   *  Each line is a set of values, identified by the header, following
281   *  the value of the independent variable. These lines are of arbitrary   *  the value of the independent variable. These lines are of arbitrary
282   *  length since it is expected that some other program will be   *  length since it is expected that some other program will be
283   *  reading the output, not a human.   *  reading the output, not a human.
284   */   */
285    
286  /*---------------------------------------  /*---------------------------------------
287    Output reporting interface    Output reporting interface
288  */  */
289    
290  /**  /**
291      Returns an IntegratorReporter struct. You are responsible for destroying      Returns an IntegratorReporter struct. You are responsible for destroying
292      this struct when you're finished with it.      this struct when you're finished with it.
293  */  */
294  IntegratorReporter *Asc_GetIntegReporter();  IntegratorReporter *Asc_GetIntegReporter();
295  int Asc_IntegReporterInit(IntegratorSystem *blsys);  int Asc_IntegReporterInit(IntegratorSystem *blsys);
296  int Asc_IntegReporterWrite(IntegratorSystem *blsys);  int Asc_IntegReporterWrite(IntegratorSystem *blsys);
297  int Asc_IntegReporterWriteObs(IntegratorSystem *blsys);  int Asc_IntegReporterWriteObs(IntegratorSystem *blsys);
298  int Asc_IntegReporterClose(IntegratorSystem *blsys);  int Asc_IntegReporterClose(IntegratorSystem *blsys);
299    
300  #endif  /* ASCTK_INTEGRATORS_H */  #endif  /* ASCTK_INTEGRATORS_H */

Legend:
Removed from v.689  
changed lines
  Added in v.690

john.pye@anu.edu.au
ViewVC Help
Powered by ViewVC 1.1.22