/[ascend]/trunk/tcltk98/generic/interface/DebugProc.h
ViewVC logotype

Contents of /trunk/tcltk98/generic/interface/DebugProc.h

Parent Directory Parent Directory | Revision Log Revision Log


Revision 67 - (show annotations) (download) (as text)
Wed Nov 30 16:31:29 2005 UTC (16 years, 5 months ago) by johnpye
File MIME type: text/x-chdr
File size: 20603 byte(s)
Standardised the "if seen" #defines to [ASC|ASCTK|ASCPY|ASCXX]_FILENAME_H
Fixed compile on FC3
1 /*
2 * DebugProc.h
3 * by Kirk Abbott and Ben Allan
4 * Created: 1/94
5 * Version: $Revision: 1.14 $
6 * Version control file: $RCSfile: DebugProc.h,v $
7 * Date last modified: $Date: 2003/08/23 18:43:05 $
8 * Last modified by: $Author: ballan $
9 *
10 * This file is part of the ASCEND Tcl/Tk interface
11 *
12 * Copyright 1997, Carnegie Mellon University
13 *
14 * The ASCEND Tcl/Tk interface is free software; you can redistribute
15 * it and/or modify it under the terms of the GNU General Public License as
16 * published by the Free Software Foundation; either version 2 of the
17 * License, or (at your option) any later version.
18 *
19 * The ASCEND Tcl/Tk interface is distributed in hope that it will be
20 * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
21 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
22 * General Public License for more details.
23 *
24 * You should have received a copy of the GNU General Public License
25 * along with the program; if not, write to the Free Software Foundation,
26 * Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
27 * COPYING. COPYING is found in ../compiler.
28 */
29
30 /** @file
31 * Debugging Routines
32 * <pre>
33 * To include this header, you must include the following:
34 * #include "tcl.h"
35 * #include "utilities/ascConfig.h"
36 * #include "interface/DebugProc.h"
37 * </pre>
38 */
39
40 #ifndef ASCTK_DEBUGPROC_H
41 #define ASCTK_DEBUGPROC_H
42
43 extern int Asc_DebuGetBlkOfVar(ClientData cdata, Tcl_Interp *interp,
44 int argc, CONST84 char *argv[]);
45 /**<
46 * Get the block number for a variable.
47 * Returns "none" if var is not in a partition (not assigned included).
48 * Returns tclerror if var isn't in system.
49 * Returns block # that var is in from C structure.
50 * Assumes g_solvsys_cur exists.
51 * var_block wrapper <br><br>
52 *
53 * Registered as: dbg_get_blk_of_var varindex
54 */
55
56 extern int Asc_DebuGetBlkOfEqn(ClientData cdata, Tcl_Interp *interp,
57 int argc, CONST84 char *argv[]);
58 /**<
59 * Get the block number for an equation.
60 * Returns "none" if eqn is not in a partition (not assigned included).
61 * Returns tclerror if eqn isn't in system.
62 * Returns block # that eqn is in from C structure.
63 * Assumes g_solvsys_cur exists.
64 * rel_block wrapper <br><br>
65 *
66 * Registered as: dbg_get_blk_of_eqn eqnindex
67 */
68
69 extern int Asc_DebuGetBlkCoords(ClientData cdata, Tcl_Interp *interp,
70 int argc, CONST84 char *argv[]);
71 /**<
72 * Get the coordinates of a block.
73 * returns "none" if block is not a partition.
74 * Returns collo rowlo colhi rowhi from C structure.
75 * Assumes g_solvsys_cur exists.
76 * mtx_block wrapper <br><br>
77 *
78 * Registered as: dbg_get_blk_coords blocknumber
79 */
80
81 extern int Asc_DebuGetEqnOfVar(ClientData cdata, Tcl_Interp *interp,
82 int argc, CONST84 char *argv[]);
83 /**<
84 * Get the equation number for a variable.
85 * Returns "none" if var is not assigned (fixed or not incident).
86 * Returns tclerror if var isn't in system.
87 * Returns eqn # that var is assigned to from C structure.
88 * Assumes g_solvsys_cur. not yet working. needs some linsol. <br><br>
89 *
90 * Registered as: dbg_get_eqn_of_var varindex
91 */
92
93 extern int Asc_DebuGetVarPartition(ClientData cdata, Tcl_Interp *interp,
94 int argc, CONST84 char *argv[]);
95 /**<
96 * Return a / and space delimited list of the variables in the system.
97 * / separates partitions, space separates var #s. There's a trailing
98 * / at end.
99 * No args. <br><br>
100 *
101 * Registered as: dbg_get_varpartition
102 */
103
104 extern int Asc_DebuGetEqnPartition(ClientData cdata, Tcl_Interp *interp,
105 int argc, CONST84 char *argv[]);
106 /**<
107 * Return a / and space delimited list of the equations in the system.
108 * / separates partitions, space separates eqn #s. There's a trailing
109 * / at end.
110 * No args. <br><br>
111 *
112 * Registered as: dbg_get_eqnpartition
113 */
114
115 extern int Asc_DebuListRels(ClientData cdata, Tcl_Interp *interp,
116 int argc, CONST84 char *argv[]);
117 /**<
118 * Return the C index list of rels matching the simple filter specified.
119 * No filter --> usage message,error.
120 * Not all of filter.h is yet supported.
121 * Unrecognized filters return an error.
122 * Any argument in the anything position cause negation of the filter. <br><br>
123 *
124 * Registered as: dbg_list_rels <filtercode> [anything]
125 */
126
127 extern int Asc_DebuListVars(ClientData cdata, Tcl_Interp *interp,
128 int argc, CONST84 char *argv[]);
129 /**<
130 * Return the C index list of vars matching the simple filter specified.
131 * No filter --> usage message,error.
132 * Unrecognized filters return an error.
133 * An argument in the anything position cause negation of the filter.
134 * Note: solvers which do not partition do not assign, e.g. MINOS
135 * leaves all variables 'unassigned'.<br><br>
136 *
137 * Registered as: dbg_list_vars <filtercode> [anything]
138 */
139
140 extern int Asc_DebuWriteVar(ClientData cdata, Tcl_Interp *interp,
141 int argc, CONST84 char *argv[]);
142 /**<
143 * Writes a real variable. Conditions:
144 * -# output device; stderr stdout or interp (0,1,2)
145 * -# it's C index number
146 * -# with detail level: 0 name 1 val 2 dims 3 var# 4 fixedflag
147 * 5 lower_bound 6 nominal 7 upper_bound
148 * -# the selection of the master list or
149 * solvers list of variables. 0 is solver list, 1 is master.
150 * -# with optional string prepended to the qlfdid
151 *
152 * Name returned is qualified id from root instance g_solvinst_root.
153 * The string is not prepended to the interp qlfdid,
154 * an ampersand marks the root and should be edited in tcl before
155 * displaying the result. interp is returned as a list.
156 * If cdata 1,uses g_browsys_cur instead of g_solvsys_cur.<br><br>
157 *
158 * Registered as: dbg_write_var out# Cindex detail# [string]
159 */
160
161 extern int Asc_DebuWriteUnattachedVar(ClientData cdata, Tcl_Interp *interp,
162 int argc, CONST84 char *argv[]);
163 /**<
164 * Writes the list of unattached variables to stderr, stdout, or interp
165 * (0,1,2).
166 * Name returned is qualified id from root instance g_solvinst_root.
167 * The string is not prepended to the interp qlfdid,
168 * an ampersand marks the root and should be edited in tcl before
169 * displaying the result. interp is returned as a list.
170 * If cdata 1,uses g_browsys_cur instead of g_solvsys_cur.<br><br>
171 *
172 * It is not assumed anymore that the unattached variables are in the
173 * solver list of variables. There is a specific list now ofr this
174 * nonincident variables.<br><br>
175 *
176 * Registered as: dbg_write_unattvar out# [simname]
177 */
178
179 extern int Asc_DebuWriteRel(ClientData cdata, Tcl_Interp *interp,
180 int argc, CONST84 char *argv[]);
181 /**<
182 * Writes a relation to stderr stdout or interp (0,1,2).
183 * Conditions:
184 * -# it's a C index number
185 * -# with detail level 0 name 1 resid 2 rel# 3 include flag
186 * -# cumulative
187 *
188 * If detail level is 4, only the relation itself is written/returned.
189 * Name returned is qualified id from root instance g_solvinst_root.
190 * The string is not prepended to the interp qlfdid,
191 * an ampersand marks the root and should be edited in tcl before
192 * displaying the result. interp is returned as a list
193 * If cdata 1,uses g_browsys_cur instead of g_solvsys_cur.<br><br>
194 *
195 * SIDE EFFECTS: updates the residual of the relation examined.
196 * bugs: detail level is not exactly analogous to write_Var
197 * does not trap fp exceptions. <br><br>
198 *
199 * Registered as: dbg_write_rel <out> <Cindex> <detail> [string]
200 */
201
202 extern int Asc_DebuWriteObj(ClientData cdata, Tcl_Interp *interp,
203 int argc, CONST84 char *argv[]);
204 /**<
205 * Same as Asc_DebuWriteRel() except applies to objective relations. <br><br>
206 *
207 * Registered as: dbg_write_obj
208 */
209
210 extern int Asc_DebuWriteVarAttr(ClientData cdata, Tcl_Interp *interp,
211 int argc, CONST84 char *argv[]);
212 /**<
213 * Writes a solver_var instance including some ip properties.
214 * Conditions: it's a C index number in a list:
215 * atom type, dims, value, shortest qlfdid, ip data items
216 * atom children and values.
217 * Current ip data items are var.index, var.incident, and var.in_block.
218 *
219 * When called s dbg_write_qlfattr <qlfdid> (cdata==1), same as
220 * dbg_write_varattr except takes qlfdid and
221 * if ip is null (var has never been to solver) ip data will be -1<br><br>
222 *
223 * If something is amiss with the inst, returns nothing and TCL_ERROR. <br><br>
224 *
225 * Dual registered as:
226 * - dbg_write_varattr <Cindex> (cdata==0)
227 * - dbg_write_qlfattr <qlfdid> (cdata==1)
228 */
229
230 extern int Asc_DebuRelIncluded(ClientData cdata, Tcl_Interp *interp,
231 int argc, CONST84 char *argv[]);
232 /**<
233 * Returns 1 if rel included flag set true, 0 if not.
234 * This call, along with Asc_DebuVarFixed(), is used primarily
235 * for speed in the incidence matrix construction. The normal
236 * rel and var queries give more useful information in most cases. <br><br>
237 *
238 * Registered as: dbg_rel_included <index>
239 */
240 extern int Asc_DebuVarFixed(ClientData cdata, Tcl_Interp *interp,
241 int argc, CONST84 char *argv[]);
242 /**<
243 * Returns 1 if var fixed flag set true, 0 if not.
244 * This call, along with Asc_DebuRelIncluded(), is used primarily
245 * for speed in the incidence matrix construction. The normal
246 * rel and var queries give more useful information in most cases. <br><br>
247 *
248 * Registered as: dbg_var_fixed <index>
249 */
250
251 extern int Asc_DebuGetIncidence(ClientData cdata, Tcl_Interp *interp,
252 int argc, CONST84 char *argv[]);
253 /**<
254 * Returns the list of indexes of variables occuring in the relation
255 * index given. Uses NumberVaribles and RelationVariable routines to
256 * determine incidence, so it does not rely on a specific solver to set
257 * incidence flags. Uses the rel and var lists from g_solvsys_cur. <br><br>
258 *
259 * Registered as: dbg_get_incidence
260 */
261
262 extern int Asc_DebuGetOrder(ClientData cdata, Tcl_Interp *interp,
263 int argc, CONST84 char *argv[]);
264 /**<
265 * Returns the list of original indexes as found running
266 * along the mtx of the current system's linsol_sys. Will be
267 * relation indexes if arg is row. Will be var indexes if col <br><br>
268 *
269 * Registered as: dbg_get_order <row,col>
270 */
271
272 extern int Asc_DebuWriteIncidence(ClientData cdata, Tcl_Interp *interp,
273 int argc, CONST84 char *argv[]);
274 /**<
275 * Dumps the incidence matrix from slv. <br><br>
276 *
277 * Registered as: dbg_write_incidence <dest> 0= stdout 1 = stderr 2= list
278 */
279
280 extern int Asc_DebuFindEligible(ClientData cdata, Tcl_Interp *interp,
281 int argc, CONST84 char *argv[]);
282 /**<
283 * Output will be a list of indexes of the eligible variables
284 * that if fixed reduce the excess column count of the system.
285 * This list will be enclosed in {} so the output of the function is
286 * always a 1 item list whose first item is the list of indices.
287 * The DOF solver will do its own presolve, so our DOF analysis may
288 * not line up with an arbitrary clients.
289 * The list may come back empty if appropriate.
290 * Operates on g_solvsys_cur. <br><br>
291 *
292 * Registered as: dbg_find_eligible <dest> 0= stdout 1 = stderr 2= list
293 */
294
295 extern int Asc_DebuConsistencyAnalysis(ClientData cdata, Tcl_Interp *interp,
296 int argc, CONST84 char *argv[]);
297 /**<
298 * Operates on g_solvsys_cur.
299 * Output will a set of indices of the variables , which, if fixed, will
300 * result in all the alternatives of a conditional model being square and
301 * structurally consistent.
302 * This list will be enclosed in {} so the output of the function is
303 * always a 1 item list whose first item is the list of indices.
304 * The list may come back empty if appropriate. <br><br>
305 *
306 * Registered as: dbg_consistency_analysis <dest> 0= stdout 1 = stderr 2= list
307 */
308
309 extern int Asc_DebuFindGlobalEligible(ClientData cdata, Tcl_Interp *interp,
310 int argc, CONST84 char *argv[]);
311 /**<
312 * Operates on g_solvsys_cur.
313 * Output will be a list of indexes of the eligible variables
314 * that if fixed reduce the excess column count of the system. The
315 * resulting set is of eligible variables consistent will all the
316 * alternatives in a conditional model.
317 * This list will be enclosed in {} so the output of the function is
318 * always a 1 item list whose first item is the list of indices.
319 * The list may come back empty if appropriate. <br><br>
320 *
321 * Registered as: dbg_global_eligible <dest> 0= stdout 1 = stderr 2= list
322 */
323
324 extern int Asc_DebuInstEligible(ClientData cdata, Tcl_Interp *interp,
325 int argc, CONST84 char *argv[]);
326 /**<
327 * Operates on newly made g_browsys_cur made from curinst
328 * and destroys g_browsys_cur when done, leaving it NULL.
329 * Output will be a list of indexes of the eligible variables
330 * that if fixed reduce the excess column count of the system.
331 * This list will be enclosed in {} so the output of the function is
332 * always a 1 item list whose first item is the list of indices.
333 * The list may come back empty if appropriate.
334 * if dest is 0 or 1, output wil be names instead of indices. <br><br>
335 *
336 * Registered as: brow_find_eligible <dest> 0= stdout 1 = stderr 2= list
337 */
338
339 extern int Asc_DebuFindActive(ClientData cdata, Tcl_Interp *interp,
340 int argc, CONST84 char *argv[]);
341 /**<
342 * Operates on g_solvsys_cur.
343 * Output will be a list of indexes of the active relations in the
344 * system.
345 * This list will be enclosed in {} so the output of the function is
346 * always a 1 item list whose first item is the list of indices. <br><br>
347 *
348 * Registered as: dbg_find_activerels <dest> 0= stdout 1 = stderr 2= list
349 */
350
351 extern int Asc_DebuInstActive(ClientData cdata, Tcl_Interp *interp,
352 int argc, CONST84 char *argv[]);
353 /**<
354 * Operates on newly made g_browsys_cur made from curinst
355 * and destroys g_browsys_cur when done, leaving it NULL.
356 * Output will be a list of indexes of the active relations
357 * of the system.
358 * This list will be enclosed in {} so the output of the function is
359 * always a 1 item list whose first item is the list of indices.
360 * if dest is 0 or 1, output wil be names instead of indices. <br><br>
361 *
362 * Registered as: brow_find_activerels <dest> 0= stdout 1 = stderr 2= list
363 */
364
365 extern int Asc_DebuNumBlockSing(ClientData cdata, Tcl_Interp *interp,
366 int argc, CONST84 char *argv[]);
367 /**<
368 * output will be a list(or lists):
369 * {index {eqn coef} {eqn coef}}
370 * where index is the index of an unpivoted relation and the set of
371 * eqn coef pairs is the linear combination that contribute.
372 * Interpretation of the coefs (how small is zero?) is left to tcl.
373 * Dependency will be done with rows or colums as specified.
374 * The lists may come back empty if appropriate.
375 * Works only for Slv, since no other solver is currently blocking. <br><br>
376 *
377 * Registered as: dbg_num_block_singular <dest> 0= stdout 1 = stderr 2= interp
378 * <block #> <row,col>
379 */
380
381 extern int Asc_DebuStructSing(ClientData cdata, Tcl_Interp *interp,
382 int argc, CONST84 char *argv[]);
383 /**<
384 * Output will be a list of indexes of the responsible relations
385 * and a list of indexes of the vars in the singularity(s)
386 * and a list of vars that reduce singularity if freed.
387 * If dest is 0 or 1, list will be names instead of indices.
388 * relindex should be the index of an unassigned but included row, or
389 * -1 if you want the total cause of all singular rows.
390 * The lists may come back empty if appropriate. <br><br>
391 *
392 * Registered as: dbg_struct_singular <dest> 0= stdout 1 = stderr 2= list <relindex>
393 */
394
395 extern int Asc_DebuVarFree2Nom(ClientData cdata, Tcl_Interp *interp,
396 int argc, CONST84 char *argv[]);
397 /**<
398 * Moves all free vars in current solve system to their nominal values.
399 * This is basically a crash recovery call. Vars must also be incident. <br><br>
400 *
401 * Registered as: var_free2nom <no args>
402 */
403
404 extern int Asc_DebuVarNom2Free(ClientData cdata, Tcl_Interp *interp,
405 int argc, CONST84 char *argv[]);
406 /**<
407 * Moves all free vars nominals in current solve system to var values.
408 * Vars must also be incident. <br><br>
409 *
410 * Registered as: var_nom2free <no args>
411 */
412
413 extern int Asc_DebuCheckRelFp(ClientData cdata, Tcl_Interp *interp,
414 int argc, CONST84 char *argv[]);
415 /**<
416 * Returns a list which is
417 * {{index lstat rstat dlstat drstat} ...}.
418 * There is a quintuplet for each relation in the current solver list
419 * which produces a float or calc_ok error.
420 * lstat rstat reflect any problems evaluating the function l/rhs
421 * dl/rstat reflect any problems evaluating the derivatives of l/rhs
422 * A stat flag of 0 -> ok, 1 -> exception. <br><br>
423 *
424 * Registered as: dbg_check_rels
425 *
426 * @todo In Asc_DebuCheckRelFp(), dlstat, drstat are not
427 * currently implemented: always 0.
428 */
429
430 extern int Asc_DebuCalcRelNominals(ClientData cdata, Tcl_Interp *interp,
431 int argc, CONST84 char *argv[]);
432 /**<
433 * Returns a list which is
434 * {{index lstat rstat nom} ...}.
435 * There is a quintuplet for each relation in the current solver list
436 * which produces a float or calc_ok error.
437 * lstat rstat reflect any problems evaluating the function l/rhs
438 * A stat flag of 1 -> !calc_ok. 2 -> float error. 0->ok
439 * nom is the nominal the relation was left with after the error. <br><br>
440 *
441 * Registered as: dbg_calc_relnoms
442 */
443
444 extern int Asc_DebuWriteSystem(ClientData cdata, Tcl_Interp *interp,
445 int argc, CONST84 char *argv[]);
446 /**<
447 * Write a system description suitable for a standalone slv0 to the
448 * file given. destroys anything in the file if it already exists.
449 * All values will be in internal units (si) <br><br>
450 *
451 * Registered as: dbg_write_slv0_sys
452 *
453 * @todo Asc_DebuWriteSystem() doesn't deal with bnds.
454 */
455
456 extern int Asc_DebuWriteKirkSystem(ClientData cdata, Tcl_Interp *interp,
457 int argc, CONST84 char *argv[]);
458 /**<
459 * KAA_DEBUG.
460 * Registered as: dbg_write_kirk_xsys
461 */
462 extern int Asc_DebuWriteGAMSSystem(ClientData cdata, Tcl_Interp *interp,
463 int argc, CONST84 char *argv[]);
464 /**<
465 * KAA_DEBUG.
466 * Registered as: dbg_write_gams_xsys
467 */
468
469 extern int Asc_DebuMtxCalcJacobianCmd(ClientData cdata, Tcl_Interp *interp,
470 int argc, CONST84 char *argv[]);
471 /**<
472 * The jacobian is calculated at the current point.
473 * At the moment which solver must be an int which is the index of
474 * the solver. Only slv5 is now supported. <br><br>
475 *
476 * Registered as: dbg_calc_jacobian <whichsolver>
477 */
478
479 extern int Asc_DebuMtxWritePlotCmd(ClientData cdata, Tcl_Interp *interp,
480 int argc, CONST84 char *argv[]);
481 /**<
482 * Write a mtx to the named file.
483 * Arguments:
484 * - file is an openable file name or path/filename
485 * - type is 'coeff' (coefficient) or anything else (inverse)
486 * - fmt is the file format to use ('mtx','smms','plot','csr')
487 *
488 * Trashes the file if the name already exists.
489 * smms, plot, and csr uses the symbolic rank to determine the size
490 * of the region to write.
491 * mtx writes the entire matrix.
492 * A lot smarter.
493 * Deals only with solvers which can produce an mtx.<br><br>
494 *
495 * WARNINGS:
496 * This is not a command for use in a production interface -- in
497 * particular solvers are not and should not be in the habit of exposing
498 * their factorized matrices to casual users. <br><br>
499 *
500 * Registered as: debug_mtxwriteplot <file> <type> <fmt>
501 *
502 * @todo Asc_DebuMtxWritePlotCmd() does not accept a block no.
503 * @todo Asc_DebuMtxWritePlotCmd() does not accept a set of
504 * region coordinates.
505 */
506
507 extern int Asc_DebuHelpList(ClientData cdata, Tcl_Interp *interp,
508 int argc, CONST84 char *argv[]);
509 /**<
510 * Debug help command for tcl.
511 * No arg -> return tcl list.
512 * "s" -> list names only, "l" -> short explanations also, to stderr. <br><br>
513 *
514 * Registered as: dbghelp [s,l]
515 */
516
517 #endif /* DebugProc_module_loaded */
518

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