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

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

Parent Directory Parent Directory | Revision Log Revision Log


Revision 670 - (hide annotations) (download) (as text)
Wed Jun 21 07:57:19 2006 UTC (14 years, 7 months ago) by johnpye
File MIME type: text/x-chdr
File size: 35014 byte(s)
woops, somehow managed to fail to merge the stuff from the DAE branch (changeset 702 to 819) 
into the trunk. This should correct that.
1 johnpye 670 /* ASCEND modelling environment
2     Copyright 1997, Carnegie Mellon University
3     Copyright (C) 2006 Carnegie Mellon University
4    
5     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
7     the Free Software Foundation; either version 2, or (at your option)
8     any later version.
9    
10     This program is distributed in the hope that it will be useful,
11     but WITHOUT ANY WARRANTY; without even the implied warranty of
12     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
13     GNU General Public License for more details.
14    
15     You should have received a copy of the GNU General Public License
16     along with this program; if not, write to the Free Software
17     Foundation, Inc., 59 Temple Place - Suite 330,
18     Boston, MA 02111-1307, USA.
19     *//** @file
20     Implementation of the Integration Interface.
21    
22     This module defines the general integration auxillaries for Ascend.
23    
24     Requires
25     #include "tcl.h"
26     #include "utilities/ascConfig.h
27     #include "general/list.h"
28     #include "compiler/instance_enum.h"
29     #include "compiler/dimen.h"
30     #include "solver/slv_client.h"
31     #include "compiler/interface.h"
32     #include <stdio.h> (for current INTEG_DEBUG functions)
33     *//*
34     Author: Boyd T. Safrit
35     by Kirk Abbott and Ben Allan
36     Created: 1/94
37     Version: $Revision: 1.16 $
38     Version control file: $RCSfile: Integrators.h,v $
39     Date last modified: $Date: 2003/08/23 18:43:06 $
40     Last modified by: $Author: ballan $
41    
42     Changes: 8/95 Added support code for BLSODE, an
43     experimental user interface
44     which identifies states, derivatives,
45     observations, and tolerances by flags.
46     Interface redesign (ASCEND side) by
47     Jennifer Stokes and (C side) Ben Allan.
48     The only required vector left is that
49     defining the time steps to calculate
50     results at. All state and observation
51     data are (optionally) logged to files.
52     5/96 Removed old lsode interface routines.
53     The Piela version of lsode is dead.
54     8/96 Removed the var == instance assumption from
55     the implementation.
56     */
57    
58    
59     #ifndef ASCTK_INTEGRATORS_H
60     #define ASCTK_INTEGRATORS_H
61    
62     #include <solver/integrator.h>
63    
64     extern int Asc_IntegSetYFileCmd(ClientData cdata, Tcl_Interp *interp,
65     int argc, CONST84 char *argv[]);
66     /**<
67     * 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>
69     *
70     * Registered as: integrate_set_y_file filename
71     */
72    
73     extern int Asc_IntegSetObsFileCmd(ClientData cdata, Tcl_Interp *interp,
74     int argc, CONST84 char *argv[]);
75     /**<
76     * 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>
78     *
79     * Registered as: integrate_set_obs_file filename
80     */
81    
82     extern int Asc_IntegSetFileUnitsCmd(ClientData cdata, Tcl_Interp *interp,
83     int argc, CONST84 char *argv[]);
84     /**<
85     * 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
87     * 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
89     * issued to stderr. The user is then expected to deal with the problem
90     * of inconsistency in his output.
91     * Only the first letter of the argument is significant.<br><br>
92     *
93     * Registered as: integrate_logunits <display,si>
94     */
95    
96     extern int Asc_IntegSetFileFormatCmd(ClientData cdata, Tcl_Interp *interp,
97     int argc, CONST84 char *argv[]);
98     /**<
99     * 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.
101     * Only the first letter of the argument is significant.<br><br>
102     *
103     * Registered as: integrate_logformat <fixed,variable>
104     */
105    
106    
107    
108     extern int Asc_IntegGetXSamplesCmd(ClientData cdata, Tcl_Interp *interp,
109     int argc, CONST84 char *argv[]);
110     /**<
111     * Returns the current vector of independent variable samples as fed to
112     * smarter integrators such as lsode. Returns 2 element list:
113     * {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
115     * (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
117     * be returned in the second element. If display is not given, samples
118     * will be returned in SI units.
119     * The units used will be dimensionally consistent with those specified
120     * when integrate_set_samples was called.
121     * Only the first letter of the optional argument display is significant.<br><br>
122     *
123     * Registered as: integrate_get_samples [display]
124     */
125    
126     extern int Asc_IntegSetXSamplesCmd(ClientData data, Tcl_Interp *interp,
127     int argc, CONST84 char *argv[]);
128     /**<
129     * Takes the values given and sets the intervals for smarter
130     * integrators accordingly. Values will be converted to SI values
131     * using the units given. ?,* is a legal unit, in which case the
132     * values will be assumed to be SI requiring no conversion.
133     * 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>
135     *
136     * 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.
138     * C clients are given the power to verify this.
139     * 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>
142     */
143    
144     extern int Asc_IntegInstIntegrableCmd(ClientData cdata, Tcl_Interp *interp,
145     int argc, CONST84 char *argv[]);
146     /**<
147     * Returns "1" if instance is integrable by the named integrator, "0"
148     * otherwise. Currently valid names are: lsode
149     * The instance examined is "current", "search", or "solver".<br><br>
150     *
151     * Registered as: integrate_able <instance> <NAME>
152     */
153    
154    
155     extern int Asc_IntegSetupCmd(ClientData cdata,Tcl_Interp *interp,
156     int argc, CONST84 char *argv[]);
157     /**<
158     * Set up the integrator.
159     * itype is one of the supported integrator types (currently:
160     * BLSODE)
161     * n1 is the start index to run the integrator from.
162     * n2 is the end index to stop at.
163     *
164     * Registered as: integrateSetup itype n1 n2
165     */
166    
167     extern int Asc_IntegCleanupCmd(ClientData cdata, Tcl_Interp *interp,
168     int argc, CONST84 char *argv[]);
169     /**<
170     * Do any C level housekeeping need after calling integration.
171     * Always use integrate_setup/integrate_cleanup in pairs.<br><br>
172     *
173     * Registered as: integrate_cleanup
174     */
175    
176     /* functions affecting the logging of data during integration */
177     extern FILE *Asc_IntegOpenYFile(void);
178     /**<
179     * Returns the pointer to a file to which state
180     * 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
182     * of the specific integrator interface. The filename used will be
183     * the one most recently set via Asc_IntegSetYFileCmd(). If no
184     * name (or an empty name) has been set via Asc_IntegSetYFileCmd(),
185     * the file returned will be NULL.<br><br>
186     *
187     * This function may return NULL, in which case do not write to
188     * them as there was some problem opening the file.
189     * If opened successfully, the file returned will have DATASET and
190     * the open time stamped at the bottom. This will separate multiple
191     * runs or changes in the same run.<br><br>
192     *
193     * Closing the files is your job. When finished with the file, you
194     * should call Asc_IntegReleaseYFile() before closing it.
195     */
196     extern FILE *Asc_IntegOpenObsFile(void);
197     /**<
198     * Returns the pointer to a file to which observation
199     * 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
201     * of the specific integrator interface. The filename used will be
202     * the one most recently set via Asc_IntegSetObsFileCmd(). If no
203     * name (or an empty name) has been set via Asc_IntegSetObsFileCmd(),
204     * the file returned will be NULL.<br><br>
205     *
206     * This function may return NULL, in which case do not write to
207     * them as there was some problem opening the file.
208     * If opened successfully, the file returned will have DATASET and
209     * the open time stamped at the bottom. This will separate multiple
210     * runs or changes in the same run.<br><br>
211     *
212     * Closing the files is your job. When finished with the file, you
213     * should call Asc_IntegReleaseObsFile() before closing it.
214     */
215    
216     /**
217     these functions don't involve Tcl/Tk but they do implement stuff
218     in a way that might not be useful to other interfaces.
219     */
220    
221     extern FILE *Asc_IntegGetYFile(void);
222     /**<
223     * Returns the current FILE * for writing state variables,
224     * or NULL if none.
225     */
226     extern FILE *Asc_IntegGetObsFile(void);
227     /**<
228     * Returns the current FILE * for writing observation variables,
229     * or NULL if none.
230     */
231     extern void Asc_IntegReleaseYFile(void);
232     extern void Asc_IntegReleaseObsFile(void);
233     /**<
234     * Releases the internally-stored FILE * for observation variables.
235     * This does not close the file (which you still need to do).
236     * 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
238     * returned all to yourself.
239     */
240    
241    
242     extern void Asc_IntegPrintYHeader(FILE *fp, IntegratorSystem *blsys);
243     /**<
244     * Prints Y header info to the file given.
245     * If FILE is NULL, returns immediately.
246     * If FILE ok, but blsys NULL prints warning to stderr and returns.
247     * At the moment, the written header info is:
248     * A vertical listing of
249     * ode_id/obs_id instance_name_as_seen_in_solver.d UNITS
250     * then a row (which will line up with printed values)
251     * of the ode_id/obs_id.
252     */
253     extern void Asc_IntegPrintObsHeader(FILE *fp, IntegratorSystem *blsys);
254     /**<
255     * Prints observation header info to the file given.
256     * If FILE is NULL, returns immediately.
257     * If FILE ok, but blsys NULL prints warning to stderr and returns.
258     * At the moment header info is:
259     * A vertical listing of
260     * ode_id/obs_id instance_name_as_seen_in_solver.d UNITS
261     * then a row (which will line up with printed values)
262     * of the ode_id/obs_id.
263     */
264    
265     extern void Asc_IntegPrintYLine(FILE *fp, IntegratorSystem *blsys);
266     /**<
267     * Prints a Y line to the file given.
268     * If FILE is NULL, returns immediately.
269     * 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
271     * the value of the independent variable. These lines are of arbitrary
272     * length since it is expected that some other program will be
273     * reading the output, not a human.
274     */
275     extern void Asc_IntegPrintObsLine(FILE *fp, IntegratorSystem *blsys);
276     /**<
277     * Prints an observation line to the file given.
278     * If FILE is NULL, returns immediately.
279     * 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
281     * the value of the independent variable. These lines are of arbitrary
282     * length since it is expected that some other program will be
283     * reading the output, not a human.
284     */
285    
286     /*---------------------------------------
287     Output reporting interface
288     */
289    
290     /**
291     Returns an IntegratorReporter struct. You are responsible for destroying
292     this struct when you're finished with it.
293     */
294     IntegratorReporter *Asc_GetIntegReporter();
295     int Asc_IntegReporterInit(IntegratorSystem *blsys);
296     int Asc_IntegReporterWrite(IntegratorSystem *blsys);
297     int Asc_IntegReporterWriteObs(IntegratorSystem *blsys);
298     int Asc_IntegReporterClose(IntegratorSystem *blsys);
299    
300     #endif /* ASCTK_INTEGRATORS_H */
301    
302 johnpye 571 /*
303     * Integrators.h
304     * by Kirk Abbott and Ben Allan
305     * Created: 1/94
306     * Version: $Revision: 1.16 $
307     * Version control file: $RCSfile: Integrators.h,v $
308     * Date last modified: $Date: 2003/08/23 18:43:06 $
309     * Last modified by: $Author: ballan $
310     *
311     * This file is part of the ASCEND Tcl/Tk interface
312     *
313     * Copyright 1997, Carnegie Mellon University
314     *
315     * The ASCEND Tcl/Tk interface is free software; you can redistribute
316     * it and/or modify it under the terms of the GNU General Public License as
317     * published by the Free Software Foundation; either version 2 of the
318     * License, or (at your option) any later version.
319     *
320     * The ASCEND Tcl/Tk interface is distributed in hope that it will be
321     * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
322     * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
323     * General Public License for more details.
324     *
325     * You should have received a copy of the GNU General Public License
326     * along with the program; if not, write to the Free Software Foundation,
327     * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
328     * COPYING. COPYING is found in ../compiler.
329     */
330    
331     /** @file
332     * Implementation of the Integration Interface.
333     * <pre>
334 johnpye 670 * Author: Boyd T. Safrit
335 johnpye 571 *
336     * Changes: 8/95 Added support code for blsode, an
337     * experimental user interface
338     * which identifies states, derivatives,
339     * observations, and tolerances by flags.
340     * Interface redesign (ASCEND side) by
341     * Jennifer Stokes and (C side) Ben Allan.
342     * The only required vector left is that
343     * defining the time steps to calculate
344     * results at. All state and observation
345     * data are (optionally) logged to files.
346     * 5/96 Removed old lsode interface routines.
347     * The Piela version of lsode is dead.
348     * 8/96 Removed the var == instance assumption from
349     * the implementation.
350     *
351     * Description: This module defines the general integration
352     * auxillaries for Ascend.
353     *
354     * Requires #include "tcl.h"
355     * #include "utilities/ascConfig.h
356     * #include "general/list.h"
357     * #include "compiler/instance_enum.h"
358     * #include "compiler/dimen.h"
359     * #include "solver/slv_client.h"
360     * #include "compiler/interface.h"
361     * #include <stdio.h> (for current INTEG_DEBUG functions)
362     * </pre>
363     */
364    
365 johnpye 670 <<<<<<< .working
366     =======
367     This program is distributed in the hope that it will be useful,
368     but WITHOUT ANY WARRANTY; without even the implied warranty of
369     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
370     GNU General Public License for more details.
371    
372     You should have received a copy of the GNU General Public License
373     along with this program; if not, write to the Free Software
374     Foundation, Inc., 59 Temple Place - Suite 330,
375     Boston, MA 02111-1307, USA.
376     *//** @file
377     Implementation of the Integration Interface.
378    
379     This module defines the general integration auxillaries for Ascend.
380    
381     Requires
382     #include "tcl.h"
383     #include "utilities/ascConfig.h
384     #include "general/list.h"
385     #include "compiler/instance_enum.h"
386     #include "compiler/dimen.h"
387     #include "solver/slv_client.h"
388     #include "compiler/interface.h"
389     #include <stdio.h> (for current INTEG_DEBUG functions)
390     *//*
391     Author: Boyd T. Safrit
392     by Kirk Abbott and Ben Allan
393     Created: 1/94
394     Version: $Revision: 1.16 $
395     Version control file: $RCSfile: Integrators.h,v $
396     Date last modified: $Date: 2003/08/23 18:43:06 $
397     Last modified by: $Author: ballan $
398    
399     Changes: 8/95 Added support code for BLSODE, an
400     experimental user interface
401     which identifies states, derivatives,
402     observations, and tolerances by flags.
403     Interface redesign (ASCEND side) by
404     Jennifer Stokes and (C side) Ben Allan.
405     The only required vector left is that
406     defining the time steps to calculate
407     results at. All state and observation
408     data are (optionally) logged to files.
409     5/96 Removed old lsode interface routines.
410     The Piela version of lsode is dead.
411     8/96 Removed the var == instance assumption from
412     the implementation.
413     */
414    
415    
416     >>>>>>> .merge-right.r820
417 johnpye 571 #ifndef ASCTK_INTEGRATORS_H
418     #define ASCTK_INTEGRATORS_H
419    
420 johnpye 670 <<<<<<< .working
421     /**
422 johnpye 571 * Define as TRUE to enable debug message printing.
423 johnpye 670 * @todo this needs to go away.
424 johnpye 571 */
425     #define INTEG_DEBUG FALSE
426 johnpye 670 =======
427     #include <solver/integrator.h>
428     >>>>>>> .merge-right.r820
429 johnpye 571 #define print_debug(msg, value) if (INTEG_DEBUG) FPRINTF(stdout, msg, value)
430     /**< Print a debug message with value if INTEG_DEBUG is TRUE. */
431     #define print_debugstring(msg) if (INTEG_DEBUG) FPRINTF(stdout, msg)
432     /**< Print a debug message string if INTEG_DEBUG is TRUE. */
433    
434 johnpye 670 <<<<<<< .working
435 johnpye 571 /** The integrators that are supported */
436     enum Integrator_type {
437     BLSODE,
438     /* SDASSL, */
439     UNKNOWN
440     };
441    
442     struct Integ_DiffData {
443     long n_eqns; /**< dimension of state vector */
444     int *input_indices; /**< vector of state vars indexes */
445     int *output_indices; /**< vector of derivative var indexes */
446     struct var_variable **y_vars; /**< NULL terminated list of states vars */
447     struct var_variable **ydot_vars; /**< NULL terminated list of derivative vars*/
448     struct rel_relation **rlist; /**< NULL terminated list of relevant rels
449     to be differentiated */
450     double **dydx_dx; /**< change in derivatives wrt states
451     I prefer to call this: d(ydot)/dy */
452     };
453    
454     extern struct Integ_DiffData g_intg_diff;
455     /**<
456     * global creature for C's FEX and JEX like functions to access data
457     * when called from Fortran.
458     */
459    
460     /**
461     * Experimental ivp problem description token. anyone making a copy of
462     * the y, ydot, or obs pointers who plans to free that pointer later
463     * should increment the reference count for that pointer so if blsys
464     * is destroyed later we don't end up double freeing it. Note this
465     * scheme will only work for the first copy and could be eliminated
466     * if we decoupled blsode from lsode as we will once things restabilize.
467     */
468     struct Integ_system_t {
469     /* temporaries for build. these elements will be NULL to clients */
470     struct gl_list_t *indepvars; /**< all apparent independent vars */
471     struct gl_list_t *dynvars; /**< all state and deriv instances plus indices */
472     struct gl_list_t *obslist; /**< observation instance plus indices */
473     struct gl_list_t *states; /**< ordered list of state variables and indices*/
474     struct gl_list_t *derivs; /**< ordered list of derivative (ydot) insts */
475     /* persistent, these elements are valid to C clients. */
476     struct var_variable *x; /**< independent variable */
477     struct var_variable **y; /**< array form of states */
478     struct var_variable **ydot; /**< array form of derivatives */
479     struct var_variable **obs; /**< array form of observed variables */
480     long *y_id; /**< array form of y/ydot user indices */
481     long *obs_id; /**< array form of obs user indices */
482     long n_y;
483     long n_obs;
484     int ycount; /**< number of external references to y */
485     int ydotcount; /**< number of external references to ydot */
486     int obscount; /**< number of external references to obs */
487     int maxsteps; /**< most steps between mesh poins */
488     double stepzero; /**< initial step length, SI units. */
489     double stepmin; /**< shortest step length, SI units. */
490     double stepmax; /**< longest step length, SI units. */
491     };
492    
493     extern int Asc_IntegInstIntegrable(struct Instance *inst,
494     enum Integrator_type integrator);
495     /**<
496     * Takes an instance and a type of integrator and determines
497     * if the instance can be integrated using this integrator.
498     */
499    
500     extern int Asc_IntegCheckStatus(slv_status_t status);
501     /**<
502     * Takes a status and checks for convergence. If converged then return 1
503     * else return 0 and print error message if appropriate.
504     */
505    
506     /* functions affecting the logging of data during integration */
507     extern FILE *Asc_IntegOpenYFile(void);
508     /**<
509     * Returns the pointer to a file to which state
510     * variables should be written at each recorded time interval. Other
511     * info may be written here as well, but that is up to the designer
512     * of the specific integrator interface. The filename used will be
513 johnpye 670 * the one most recently set via Asc_IntegSetYFileCmd(). If no
514 johnpye 571 * name (or an empty name) has been set via Asc_IntegSetYFileCmd(),
515     * the file returned will be NULL.<br><br>
516     *
517     * This function may return NULL, in which case do not write to
518     * them as there was some problem opening the file.
519     * If opened successfully, the file returned will have DATASET and
520     * the open time stamped at the bottom. This will separate multiple
521     * runs or changes in the same run.<br><br>
522     *
523 johnpye 670 * Closing the files is your job. When finished with the file, you
524 johnpye 571 * should call Asc_IntegReleaseYFile() before closing it.
525     */
526     extern FILE *Asc_IntegOpenObsFile(void);
527     /**<
528     * Returns the pointer to a file to which observation
529     * variables should be written at each recorded time interval. Other
530     * info may be written here as well, but that is up to the designer
531     * of the specific integrator interface. The filename used will be
532 johnpye 670 * the one most recently set via Asc_IntegSetObsFileCmd(). If no
533 johnpye 571 * name (or an empty name) has been set via Asc_IntegSetObsFileCmd(),
534     * the file returned will be NULL.<br><br>
535     *
536     * This function may return NULL, in which case do not write to
537     * them as there was some problem opening the file.
538     * If opened successfully, the file returned will have DATASET and
539     * the open time stamped at the bottom. This will separate multiple
540     * runs or changes in the same run.<br><br>
541     *
542 johnpye 670 * Closing the files is your job. When finished with the file, you
543 johnpye 571 * should call Asc_IntegReleaseObsFile() before closing it.
544     */
545     extern FILE *Asc_IntegGetYFile(void);
546     /**<
547     * Returns the current FILE * for writing state variables,
548     * or NULL if none.
549     */
550     extern FILE *Asc_IntegGetObsFile(void);
551     /**<
552     * Returns the current FILE * for writing observation variables,
553     * or NULL if none.
554     */
555     extern void Asc_IntegReleaseYFile(void);
556     extern void Asc_IntegReleaseObsFile(void);
557     /**<
558     * Releases the internally-stored FILE * for observation variables.
559     * This does not close the file (which you still need to do).
560     * This function should be called just before closing the files,
561     * though it may be called sooner if you want to keep the file pointer
562     * returned all to yourself.
563     */
564    
565     extern void Asc_IntegPrintYHeader(FILE *fp, struct Integ_system_t *blsys);
566     /**<
567     * Prints Y header info to the file given.
568     * If FILE is NULL, returns immediately.
569     * If FILE ok, but blsys NULL prints warning to stderr and returns.
570     * At the moment, the written header info is:
571     * A vertical listing of
572     * ode_id/obs_id instance_name_as_seen_in_solver.d UNITS
573     * then a row (which will line up with printed values)
574     * of the ode_id/obs_id.
575     */
576     extern void Asc_IntegPrintObsHeader(FILE *fp, struct Integ_system_t *blsys);
577     /**<
578     * Prints observation header info to the file given.
579     * If FILE is NULL, returns immediately.
580     * If FILE ok, but blsys NULL prints warning to stderr and returns.
581     * At the moment header info is:
582     * A vertical listing of
583     * ode_id/obs_id instance_name_as_seen_in_solver.d UNITS
584     * then a row (which will line up with printed values)
585     * of the ode_id/obs_id.
586     */
587    
588     extern void Asc_IntegPrintYLine(FILE *fp, struct Integ_system_t *blsys);
589     /**<
590     * Prints a Y line to the file given.
591     * If FILE is NULL, returns immediately.
592     * If FILE ok, but blsys NULL prints warning to stderr and returns.
593     * Each line is a set of values, identified by the header, following
594     * the value of the independent variable. These lines are of arbitrary
595     * length since it is expected that some other program will be
596     * reading the output, not a human.
597     */
598     extern void Asc_IntegPrintObsLine(FILE *fp, struct Integ_system_t *blsys);
599     /**<
600     * Prints an observation line to the file given.
601     * If FILE is NULL, returns immediately.
602     * If FILE ok, but blsys NULL prints warning to stderr and returns.
603     * Each line is a set of values, identified by the header, following
604     * the value of the independent variable. These lines are of arbitrary
605     * length since it is expected that some other program will be
606     * reading the output, not a human.
607     */
608    
609 johnpye 670 =======
610     >>>>>>> .merge-right.r820
611 johnpye 571 extern int Asc_IntegSetYFileCmd(ClientData cdata, Tcl_Interp *interp,
612     int argc, CONST84 char *argv[]);
613     /**<
614     * Set the next filename to be used for integration state variable
615     * logging. Does not check the filesystem sanity of the given name.<br><br>
616     *
617     * Registered as: integrate_set_y_file filename
618     */
619    
620     extern int Asc_IntegSetObsFileCmd(ClientData cdata, Tcl_Interp *interp,
621     int argc, CONST84 char *argv[]);
622     /**<
623     * Set the next filename to be used for integration observation variable
624     * logging. Does not check the filesystem sanity of the given name.<br><br>
625     *
626     * Registered as: integrate_set_obs_file filename
627     */
628    
629     extern int Asc_IntegSetFileUnitsCmd(ClientData cdata, Tcl_Interp *interp,
630     int argc, CONST84 char *argv[]);
631     /**<
632     * Sets output to be in SI (internal) units or in the user set display
633     * units. If display is selected and the variable to be printed cannot
634     * be displayed in the display units because of floating point errors
635     * in conversion, the value will be printed in SI units and a warning
636     * issued to stderr. The user is then expected to deal with the problem
637     * of inconsistency in his output.
638     * Only the first letter of the argument is significant.<br><br>
639     *
640     * Registered as: integrate_logunits <display,si>
641     */
642    
643     extern int Asc_IntegSetFileFormatCmd(ClientData cdata, Tcl_Interp *interp,
644     int argc, CONST84 char *argv[]);
645     /**<
646     * Sets output data to be in fixed column width (with extra white) or in
647     * space separated columns whose width is variable from line to line.
648     * Only the first letter of the argument is significant.<br><br>
649     *
650     * Registered as: integrate_logformat <fixed,variable>
651     */
652    
653    
654    
655     extern int Asc_IntegGetXSamplesCmd(ClientData cdata, Tcl_Interp *interp,
656     int argc, CONST84 char *argv[]);
657     /**<
658     * Returns the current vector of independent variable samples as fed to
659     * smarter integrators such as lsode. Returns 2 element list:
660     * {units of x} {list of doubles in the units indicated in the first
661     * element}. In the event that display is given but the sample values
662     * (which are stored in si) cannot be converted to display units, the
663     * units of x in the first element will change and the SI values will
664     * be returned in the second element. If display is not given, samples
665     * will be returned in SI units.
666     * The units used will be dimensionally consistent with those specified
667     * when integrate_set_samples was called.
668     * Only the first letter of the optional argument display is significant.<br><br>
669     *
670     * Registered as: integrate_get_samples [display]
671     */
672    
673     extern int Asc_IntegSetXSamplesCmd(ClientData data, Tcl_Interp *interp,
674     int argc, CONST84 char *argv[]);
675     /**<
676     * Takes the values given and sets the intervals for smarter
677     * integrators accordingly. Values will be converted to SI values
678     * using the units given. ?,* is a legal unit, in which case the
679     * values will be assumed to be SI requiring no conversion.
680     * If no arguments are given, we will free memory allocated for storage
681     * of the list, otherwise at least 2 values are required.<br><br>
682     *
683     * Note: It is the users responsibility to make sure that the dimens/
684     * units this is called with match the independent variable in the ivp.
685     * C clients are given the power to verify this.
686     * Also, the units given must already exist: we do not create them.<br><br>
687     *
688     * Registered as: integrate_set_samples <units> <value [value...] value>
689     */
690    
691     extern int Asc_IntegInstIntegrableCmd(ClientData cdata, Tcl_Interp *interp,
692     int argc, CONST84 char *argv[]);
693     /**<
694     * Returns "1" if instance is integrable by the named integrator, "0"
695     * otherwise. Currently valid names are: lsode
696     * The instance examined is "current", "search", or "solver".<br><br>
697     *
698     * Registered as: integrate_able <instance> <NAME>
699     */
700    
701    
702 johnpye 670 extern int Asc_IntegSetupCmd(ClientData cdata,Tcl_Interp *interp,
703     int argc, CONST84 char *argv[]);
704     /**<
705     * Set up the integrator.
706     * itype is one of the supported integrator types (currently:
707     * BLSODE)
708     * n1 is the start index to run the integrator from.
709     * n2 is the end index to stop at.
710     *
711     * Registered as: integrateSetup itype n1 n2
712 johnpye 571 */
713    
714 johnpye 670 extern int Asc_IntegCleanupCmd(ClientData cdata, Tcl_Interp *interp,
715     int argc, CONST84 char *argv[]);
716     /**<
717     * Do any C level housekeeping need after calling integration.
718     * Always use integrate_setup/integrate_cleanup in pairs.<br><br>
719     *
720     * Registered as: integrate_cleanup
721 johnpye 571 */
722    
723 johnpye 670 /* functions affecting the logging of data during integration */
724     extern FILE *Asc_IntegOpenYFile(void);
725 johnpye 571 /**<
726 johnpye 670 * Returns the pointer to a file to which state
727     * variables should be written at each recorded time interval. Other
728     * info may be written here as well, but that is up to the designer
729     * of the specific integrator interface. The filename used will be
730     * the one most recently set via Asc_IntegSetYFileCmd(). If no
731     * name (or an empty name) has been set via Asc_IntegSetYFileCmd(),
732     * the file returned will be NULL.<br><br>
733     *
734     * This function may return NULL, in which case do not write to
735     * them as there was some problem opening the file.
736     * If opened successfully, the file returned will have DATASET and
737     * the open time stamped at the bottom. This will separate multiple
738     * runs or changes in the same run.<br><br>
739     *
740     * Closing the files is your job. When finished with the file, you
741     * should call Asc_IntegReleaseYFile() before closing it.
742 johnpye 571 */
743 johnpye 670 extern FILE *Asc_IntegOpenObsFile(void);
744 johnpye 571 /**<
745 johnpye 670 * Returns the pointer to a file to which observation
746     * variables should be written at each recorded time interval. Other
747     * info may be written here as well, but that is up to the designer
748     * of the specific integrator interface. The filename used will be
749     * the one most recently set via Asc_IntegSetObsFileCmd(). If no
750     * name (or an empty name) has been set via Asc_IntegSetObsFileCmd(),
751     * the file returned will be NULL.<br><br>
752     *
753     * This function may return NULL, in which case do not write to
754     * them as there was some problem opening the file.
755     * If opened successfully, the file returned will have DATASET and
756     * the open time stamped at the bottom. This will separate multiple
757     * runs or changes in the same run.<br><br>
758     *
759     * Closing the files is your job. When finished with the file, you
760     * should call Asc_IntegReleaseObsFile() before closing it.
761 johnpye 571 */
762    
763 johnpye 670 /**
764     these functions don't involve Tcl/Tk but they do implement stuff
765     in a way that might not be useful to other interfaces.
766     */
767    
768     extern FILE *Asc_IntegGetYFile(void);
769 johnpye 571 /**<
770 johnpye 670 * Returns the current FILE * for writing state variables,
771     * or NULL if none.
772 johnpye 571 */
773 johnpye 670 extern FILE *Asc_IntegGetObsFile(void);
774 johnpye 571 /**<
775 johnpye 670 * Returns the current FILE * for writing observation variables,
776     * or NULL if none.
777 johnpye 571 */
778 johnpye 670 extern void Asc_IntegReleaseYFile(void);
779     extern void Asc_IntegReleaseObsFile(void);
780 johnpye 571 /**<
781 johnpye 670 * Releases the internally-stored FILE * for observation variables.
782     * This does not close the file (which you still need to do).
783     * This function should be called just before closing the files,
784     * though it may be called sooner if you want to keep the file pointer
785     * returned all to yourself.
786 johnpye 571 */
787    
788 johnpye 670
789     extern void Asc_IntegPrintYHeader(FILE *fp, IntegratorSystem *blsys);
790 johnpye 571 /**<
791 johnpye 670 * Prints Y header info to the file given.
792     * If FILE is NULL, returns immediately.
793     * If FILE ok, but blsys NULL prints warning to stderr and returns.
794     * At the moment, the written header info is:
795     * A vertical listing of
796     * ode_id/obs_id instance_name_as_seen_in_solver.d UNITS
797     * then a row (which will line up with printed values)
798     * of the ode_id/obs_id.
799 johnpye 571 */
800 johnpye 670 extern void Asc_IntegPrintObsHeader(FILE *fp, IntegratorSystem *blsys);
801 johnpye 571 /**<
802 johnpye 670 * Prints observation header info to the file given.
803     * If FILE is NULL, returns immediately.
804     * If FILE ok, but blsys NULL prints warning to stderr and returns.
805     * At the moment header info is:
806     * A vertical listing of
807     * ode_id/obs_id instance_name_as_seen_in_solver.d UNITS
808     * then a row (which will line up with printed values)
809     * of the ode_id/obs_id.
810 johnpye 571 */
811    
812 johnpye 670 extern void Asc_IntegPrintYLine(FILE *fp, IntegratorSystem *blsys);
813 johnpye 571 /**<
814 johnpye 670 * Prints a Y line to the file given.
815     * If FILE is NULL, returns immediately.
816     * If FILE ok, but blsys NULL prints warning to stderr and returns.
817     * Each line is a set of values, identified by the header, following
818     * the value of the independent variable. These lines are of arbitrary
819     * length since it is expected that some other program will be
820     * reading the output, not a human.
821 johnpye 571 */
822 johnpye 670 extern void Asc_IntegPrintObsLine(FILE *fp, IntegratorSystem *blsys);
823 johnpye 571 /**<
824 johnpye 670 * Prints an observation line to the file given.
825     * If FILE is NULL, returns immediately.
826     * If FILE ok, but blsys NULL prints warning to stderr and returns.
827     * Each line is a set of values, identified by the header, following
828     * the value of the independent variable. These lines are of arbitrary
829     * length since it is expected that some other program will be
830     * reading the output, not a human.
831 johnpye 571 */
832    
833 johnpye 670 /*---------------------------------------
834     Output reporting interface
835     */
836    
837     /**
838     Returns an IntegratorReporter struct. You are responsible for destroying
839     this struct when you're finished with it.
840     */
841     IntegratorReporter *Asc_GetIntegReporter();
842     int Asc_IntegReporterInit(IntegratorSystem *blsys);
843     int Asc_IntegReporterWrite(IntegratorSystem *blsys);
844     int Asc_IntegReporterWriteObs(IntegratorSystem *blsys);
845     int Asc_IntegReporterClose(IntegratorSystem *blsys);
846    
847 johnpye 571 #endif /* ASCTK_INTEGRATORS_H */
848    

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