/[ascend]/trunk/base/generic/solver/integrator.h
ViewVC logotype

Contents of /trunk/base/generic/solver/integrator.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 854 - (show annotations) (download) (as text)
Wed Sep 20 13:36:40 2006 UTC (15 years, 9 months ago) by johnpye
File MIME type: text/x-chdr
File size: 14418 byte(s)
First tentative version in 'integration reporting':
Values of observed variables from the simulation are added to an Observer table after simulation completes.
This is not very efficiently coded at this stage but is a start.
Also some minor changes to text and comments in some base/generic files.
1 /* ASCEND modelling environment
2 Copyright (C) 2006 Carnegie Mellon University
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, or (at your option)
7 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, write to the Free Software
16 Foundation, Inc., 59 Temple Place - Suite 330,
17 Boston, MA 02111-1307, USA.
18 *//** @file
19 Implementation of non-GUI-specific parts of the Integration Interface.
20
21 Here we are integrating a model with independent variable t for a specified
22 set of timesteps, and and observing the values of certain of the
23 independent variables.
24
25 You can specify the values of the time steps that you want via the
26 'samplelist' interface.
27
28 You can have your results reported however you like using the
29 'IntegratorReporter' interface.
30
31 There's nothing here yet to explicitly support DAEs -- that's the next task.
32
33 (old annotation:)
34 The following functions fetch and set parts with names specific to
35 the type definitions in ivp.lib, the ASCEND initial value problem
36 model file. They are for use by any ivp solver interface.
37 All names are given at the scope of ivp.
38
39 *//*
40 by John Pye, May 2006.
41
42 Derived from tcltk/.../Integrators.h (with heavy editing).
43 Removed all global variables and created a 'IntegratorReporter' interface
44 for reporting results of integration to whatever interface you're using.
45 */
46
47 #ifndef ASC_INTEGRATOR_H
48 #define ASC_INTEGRATOR_H
49
50 #include <utilities/ascConfig.h>
51 #include <utilities/ascMalloc.h>
52 #include <general/list.h>
53 #include <general/dstring.h>
54 #include <compiler/compiler.h>
55 #include <compiler/instance_enum.h>
56
57 #include <compiler/fractions.h>
58 #include <compiler/dimen.h>
59 #include <compiler/units.h>
60 #include <compiler/module.h>
61 #include <compiler/library.h>
62 #include <compiler/expr_types.h>
63 #include <compiler/child.h>
64 #include <compiler/type_desc.h>
65 #include <compiler/atomvalue.h>
66 #include <compiler/instance_name.h>
67 #include <compiler/instquery.h>
68 #include <compiler/parentchild.h>
69 #include <compiler/symtab.h>
70 #include <compiler/instance_io.h>
71
72 #include "slv_types.h"
73 #include "mtx.h"
74 #include "var.h"
75 #include "rel.h"
76 #include "discrete.h"
77 #include "conditional.h"
78 #include "logrel.h"
79 #include "bnd.h"
80 #include "slv_common.h"
81 #include "samplelist.h"
82
83 /*---------------------------*/
84 /**
85 Struct containin the list of supported integrators
86 */
87 typedef enum{
88 INTEG_UNKNOWN,
89 INTEG_LSODE,
90 INTEG_IDA
91 } IntegratorEngine;
92
93 /*------------------------
94 abstraction of the integrator output interface
95 */
96 struct IntegratorSystemStruct;
97
98 typedef int IntegratorOutputInitFn(struct IntegratorSystemStruct *);
99 typedef int IntegratorOutputWriteFn(struct IntegratorSystemStruct *);
100 typedef int IntegratorOutputWriteObsFn(struct IntegratorSystemStruct *);
101 typedef int IntegratorOutputCloseFn(struct IntegratorSystemStruct *);
102
103 /**
104 This struct allows arbitrary functions to be used for the reporting
105 of integrator progress.
106 */
107 typedef struct{
108 IntegratorOutputInitFn *init;
109 IntegratorOutputWriteFn *write;
110 IntegratorOutputWriteObsFn *write_obs;
111 IntegratorOutputCloseFn *close;
112 } IntegratorReporter;
113
114 /*------------------------------------*/
115 /**
116 Initial value problem description struct. Anyone making a copy of
117 the y, ydot, or obs pointers who plans to free that pointer later
118 should increment the reference count for that pointer so if blsys
119 is destroyed later we don't end up double freeing it. Note this
120 scheme will only work for the first copy and could be eliminated
121 if we decoupled blsode from lsode as we will once things restabilize.
122
123 JP: adding to this structure the instance being solved, the engine
124 that we're solving it with, and a struct containing the output function ptrs
125 */
126 struct IntegratorSystemStruct{
127 struct Instance *instance; /**< not sure if this one is really necessary... -- JP */
128 slv_system_t system; /**< the system that we're integrating in ASCEND */
129 IntegratorEngine engine; /**< enum containing the ID of the integrator engine we're using */
130 IntegratorReporter *reporter;/**< functions for reporting integration results */
131 SampleList *samples; /**< pointer to the list of samples. we *don't own* this **/
132 void *enginedata; /**< space where the integrator engine can store stuff */
133 void *clientdata; /**< any stuff that the GUI/CLI needs to associate with this */
134
135 int nstates; /**< was a local global in integrator.c, moved it here. */
136 int nderivs; /**< ditto, as for nstates */
137
138 /* temporaries for build. these elements will be NULL to clients */
139 struct gl_list_t *indepvars; /**< all apparent independent vars */
140 struct gl_list_t *dynvars; /**< all state and deriv instances plus indices */
141 struct gl_list_t *obslist; /**< observation instance plus indices */
142 struct gl_list_t *states; /**< ordered list of state variables and indices*/
143 struct gl_list_t *derivs; /**< ordered list of derivative (ydot) insts */
144
145 /* persistent, these elements are valid to C clients. */
146 struct var_variable *x; /**< independent variable */
147 struct var_variable **y; /**< array form of states */
148 struct var_variable **ydot; /**< array form of derivatives */
149 struct var_variable **obs; /**< array form of observed variables */
150 long *y_id; /**< array form of y/ydot user indices */
151 long *obs_id; /**< array form of obs user indices */
152 long n_y;
153 long n_obs;
154 long currentstep; /**< current step number (also @see integrator_getnsamples) */
155 int ycount; /**< number of external references to y */
156 int ydotcount; /**< number of external references to ydot */
157 int obscount; /**< number of external references to obs */
158 int maxsubsteps; /**< most steps between mesh poins */
159 double stepzero; /**< initial step length, SI units. */
160 double minstep; /**< shortest step length, SI units. */
161 double maxstep; /**< longest step length, SI units. */
162 };
163
164 typedef struct IntegratorSystemStruct IntegratorSystem;
165
166 /*------------------------------------------------------------------------------
167 PUBLIC INTERFACE (for use by the GUI/CLI)]
168 */
169
170 ASC_DLLSPEC(IntegratorSystem *) integrator_new(slv_system_t sys, struct Instance *inst);
171
172 ASC_DLLSPEC(int) integrator_analyse(IntegratorSystem *blsys);
173
174 ASC_DLLSPEC(int) integrator_solve(IntegratorSystem *blsys, long i0, long i1);
175 /**<
176 Takes the type of integrator and sets up the global variables into the
177 current integration instance.
178
179 @return 1 on success, 0 on failure.
180 */
181
182 ASC_DLLSPEC(void) integrator_free(IntegratorSystem *blsys);
183 /**<
184 Deallocates any memory used and sets all integration global points to NULL.
185 */
186
187 ASC_DLLSPEC(int) integrator_set_engine(IntegratorSystem *blsys, IntegratorEngine engine);
188 /**
189 Sets the engine for this integrator. Checks that the integrator can be used
190 on the given system.
191
192 @return 1 on success, if engine is compatible with the system being integrated.
193 */
194
195 ASC_DLLSPEC(IntegratorEngine) integrator_get_engine(const IntegratorSystem *blsys);
196 /**
197 Returns the engine (ID) selected for use in this IntegratorSystem (may return
198 INTEG_UNKNOWN if none or invalid setting).
199 */
200
201 ASC_DLLSPEC(int) integrator_set_reporter(IntegratorSystem *blsys
202 , IntegratorReporter *r);
203 /**<
204 Use this function from your interface to tell the integrator how it needs
205 to make its output. You need to pass in a struct containing the required
206 function pointers. (We will wrap IntegratorReporter and access it from
207 Python, eventually)
208 */
209
210 ASC_DLLSPEC(int) integrator_find_indep_var(IntegratorSystem *blsys);
211 /**<
212 Attempt to locate the independent variable. It will be stored in the blsys
213 structure if found.
214 @return 1 if found, 0 if not found.
215 */
216
217 extern int integrator_checkstatus(slv_status_t status);
218 /**<
219 * Takes a status and checks for convergence. If converged then return 1
220 * else return 0 and print error message if appropriate.
221 */
222
223 ASC_DLLSPEC(void) integrator_set_samples(IntegratorSystem *blsys, SampleList *samples);
224 /**<
225 Sets values of time samples to the values given (ns of them) and
226 keeps both the dim pointer and vector given. The vector and dimp
227 given may be freed by calling this again, but xsamples owns
228 them until then. If called with ns<1 or values==NULL, will free any
229 previously captured values/dimp. If called with dimp==NULL, will
230 assume WildDimension. Don't call this with a dimp we can't free later.
231 Return is 1 if for some reason we can't set as expected, 0 otherwise.
232 */
233
234 ASC_DLLSPEC(void) integrator_set_stepzero(IntegratorSystem *blsys, double);
235 ASC_DLLSPEC(double) integrator_get_stepzero(IntegratorSystem *blsys);
236 /**<
237 Returns the length of the initial step user specified,
238 or 0.0 if none was set.
239 */
240
241 ASC_DLLSPEC(void) integrator_set_minstep(IntegratorSystem *blsys, double);
242 ASC_DLLSPEC(double) integrator_get_minstep(IntegratorSystem *blsys);
243 /**<
244 Returns the length of the longest allowable step.
245 or 0.0 if none was set by user.
246 */
247
248 ASC_DLLSPEC(void) integrator_set_maxstep(IntegratorSystem *blsys, double);
249 ASC_DLLSPEC(double) integrator_get_maxstep(IntegratorSystem *blsys);
250 /**<
251 Returns the length of the shortest allowable step.
252 or 0.0 if none was set by user.
253 */
254
255 ASC_DLLSPEC(void) integrator_set_maxsubsteps(IntegratorSystem *blsys, int);
256 ASC_DLLSPEC(int) integrator_get_maxsubsteps(IntegratorSystem *blsys);
257 /**<
258 Returns the most internal steps allowed between
259 two time samples, or 0 if none was set by user.
260 */
261
262 ASC_DLLSPEC(long) integrator_getnsamples(IntegratorSystem *blsys);
263 /**<
264 Returns the number of values currently stored in xsamples.
265 */
266
267 ASC_DLLSPEC(long) integrator_getcurrentstep(IntegratorSystem *blsys);
268 /**<
269 Returns the current step number (blsys->currentstep). Should be reset to
270 zero inside your solver's integrator_*_solve method.
271 */
272
273 extern double integrator_getsample(IntegratorSystem *blsys, long i);
274 /**< The following functions fetch and set parts with names specific to
275 the type definitions in ivp.lib, the ASCEND initial value problem
276 model file. They are for use by any ivp solver interface.
277 All names are given at the scope of ivp.
278
279 Returns the value stored in xsamples[i]. Will whine if
280 if xsample[i] does not exist. No, there is no way to get
281 back the pointer to the xsamples vector.
282 */
283
284 extern void integrator_setsample(IntegratorSystem *blsys, long i, double val);
285 /**<
286 Sets the value stored in xsamples[i] to val. Will whine if
287 if xsample[i] does not exist. No, there is no way to get
288 back the pointer to the xsamples vector.
289 */
290
291 extern const dim_type *integrator_getsampledim(IntegratorSystem *blsys);
292 /**<
293 Returns a pointer to the dimensionality of the samples currently
294 stored, or NULL if none are stored. Do not free this pointer: we
295 own it.
296 */
297
298 /*------------------------------------------------------------------------------
299 BACKEND INTERFACE (for use by the integrator engine)
300 */
301
302 /* Problem size parameters. */
303
304 /* Parts of type definition derivatives refinements. */
305
306 ASC_DLLSPEC(double) integrator_get_t(IntegratorSystem *blsys);
307 /**<
308 Gets value of the independent variable value from the ASCEND model
309 (retrieves the value from the ASCEND compiler's instance hierarchy)
310 */
311
312 extern void integrator_set_t(IntegratorSystem *blsys, double value);
313 /**<
314 Sets value of the independent variable in the model (inserts the value in
315 the correct place in the compiler's instance hierarchy via the var_variable
316 API).
317 */
318
319 extern double *integrator_get_y(IntegratorSystem *blsys, double *vector);
320 /**<
321 Gets the value of vector 'y' from the model (what 'y' is depends on your
322 particular integrator).
323
324 If vector given is NULL, allocates vector, which the caller then owns.
325 Vector, if given, should be IntegGet_d_neq()+1 long.
326 */
327
328 extern void integrator_set_y(IntegratorSystem *blsys, double *vector);
329 /**<
330 Sets d.y[] to values in vector.
331 */
332
333 extern double *integrator_get_ydot(IntegratorSystem *blsys, double *vector);
334 /**<
335 Returns the vector ydot (derivatives of the 'states')
336
337 If vector given is NULL, allocates vector, which the caller then owns.
338 Vector, if given, should be IntegGet_d_neq()+1 long.
339 */
340
341 extern void integrator_set_ydot(IntegratorSystem *blsys, double *vector);
342 /**<
343 Sets d.dydx[] to values in vector.
344 */
345
346 ASC_DLLSPEC(double *) integrator_get_observations(IntegratorSystem *blsys, double *vector);
347 /**<
348 Returns the vector d.obs.
349 Vector should be of sufficient length (g_intginst_d_n_obs+1).
350 If NULL is given a vector is allocated and is the caller's
351 responsibility to deallocate.
352 */
353
354 ASC_DLLSPEC(struct var_variable *) integrator_get_observed_var(IntegratorSystem *blsys, const long i);
355 /**<
356 Returns the var_variable contained in the ith position in the observed variable list.
357 */
358
359 ASC_DLLSPEC(struct var_variable *) integrator_get_independent_var(IntegratorSystem *blsys);
360 /**<
361 Return a pointer to the variable identified as the independent variable.
362 */
363
364 /*-------------------------------
365 Stuff to facilitate output to the interface
366 */
367
368 /**
369 This call should be used to get the file streams ready, output column
370 headings etc.
371 */
372 extern int integrator_output_init(IntegratorSystem *blsys);
373
374 /**
375 This call should be used to output the immediate integration results from
376 a single timestep. For an ODE solver, this means just the 'y' values but
377 perhaps not the values of the algebraic varaibles, which must be calculated
378 separately. They'll be stored in the Integ_system_t somehow (not yet
379 known how)
380 */
381 extern int integrator_output_write(IntegratorSystem *blsys);
382
383 /**
384 Write out the 'observed values' for the integration. In the case of ODE
385 integration, we assume that the values of all the algabraic variables are
386 also now calculated.
387 */
388 extern int integrator_output_write_obs(IntegratorSystem *blsys);
389
390 /**
391 This call will close file stream and perhaps perform some kind of
392 user notification or screen update, etc.
393 */
394 extern int integrator_output_close(IntegratorSystem *blsys);
395
396 #endif

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