ascend4/solver/slvDOF.h

/*
 *  SlvDOF: Ascend Degrees of Freedom module
 *  by Benjamin A Allan and Vicente Rico-Ramirez
 *  Created: 7/11/94
 *  Version: $Revision: 1.10 $
 *  Version control file: $RCSfile: slvDOF.h,v $
 *  Date last modified: $Date: 1998/03/30 22:07:03 $
 *  Last modified by: $Author: rv2a $
 *
 *  This file is part of the ASCEND solver interface.
 *
 *  Copyright (C) 1994 Benjamin Andrew Allan
 *  Copyright (C) 1998 Vicente Rico-Ramirez
 *
 *  The SLV solver is free software; you can redistribute
 *  it and/or modify it under the terms of the GNU General Public License as
 *  published by the Free Software Foundation; either version 2 of the
 *  License, or (at your option) any later version.
 *
 *  The SLV solver is distributed in hope that it will be
 *  useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
 *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 *  General Public License for more details.
 *
 *  You should have received a copy of the GNU General Public License 
 *  along with the program; if not, write to the Free Software Foundation,
 *  Inc., 675 Mass Ave, Cambridge, MA 02139 USA.  Check the file named
 *  COPYING.
 *  COPYING is found in ../compiler.
 */

/*
 *  Contents:     DOF module
 *
 *  Authors:      Ben Allan
 *
 *  Dates:        07/94 - original version
 *                06/96 - reimplementation
 *                03/98 - Added the consistency analysis for conditional
 *                        models
 *
 *  Description:  This file contains routines for managing degrees
 *                of freedom through the user interface. It uses
 *                its own incidence matrix separate from the mtx of
 *                any given solver.
 */
#ifndef slvdof_already_included
#define slvdof_already_included

/* requires #include <stdio.h> */
/* requires #include "slv_client.h" */

/*
 * The following functions are for use in running DOF analysis and dialog
 * through the interface. The tcl callbacks for them will be coded in 
 * DebugProc.c probably.
 * Partitioning is assumed to be in effect.
 * In general, the lists returned will be longer than number of degrees of
 * freedom which can be changed. DOF dialogs should be done 1 var/rel at a
 * time.
 */

extern int slvDOF_eligible(slv_system_t, int32**);
/*
 * Returns 1 if able to determine lists, 0 otherwise.
 * usage: if(slvDOF_eligible(server,&vil))
 * int32 *vil;
 * That is you send us the address of a pointer to an int32 array
 * and we will fill in the pointer.
 * If return is 1, user should free vil when done with it. Return 0
 * -> vil will be null.
 * The index list is terminated with a -1 but may be of any length.
 * The indices are var_sindex of vars on solvers_var_list.
 * vil is incident vars eligible to be fixed.
 * This routine does not sort out which vars are in a particular part of
 * the MODEL represented by the system -- that is a UI job.
 * Vars that do not appear in equations will not be listed as eligible
 * since they cannot help the DOF state of the system.
 */

extern int slvDOF_structsing(slv_system_t, int32, int32**, int32**,int32**);
/*
 * if(slvDOF_structsing(server,relindex,&vil,&ril,&fil)) {.... }
 * int32 *vil, *ril, fil.
 * Returns 1 if able to determine lists, 0 otherwise.
 * relindex should be the sindex of an unassigned, included equation
 * from the solvers_rel_list.
 * If relindex is mtx_FIRST, the list returned will be the intersection of
 * all singularity lists for any unassignable included equations in 
 * the system.
 * If return is 1, user should free r/v/fil when done with
 * them. Return 0 -> lists will be null.
 * The index lists are terminated with a -1.
 * The indices are *_sindex of vars/rels on solvers_*_list.
 * vil is the vars involved in a structural singularity.
 * ril is the rels involved in a structural singularity.
 * fil is the vars which reduce the structural singularity if freed.
 */

extern int32 slvDOF_status(slv_system_t, int32 *, int32 *);
/*
 * Return the status of the current problem.
 *
 * status = 1  ==> underspecified
 * status = 2  ==> square
 * status = 3  ==> structurally singular
 * status = 4  ==> overspecifed
 * status = 5  ==> Error !! ( insufficient memory, NULL argument,
 *                            failed to presolve)
 *
 * If the system is underspecified, we will also get the number of the
 * degrees of freedom for the problem.
 *
 */

extern int32 get_globally_consistent_eligible(slv_system_t,int32 **);
/*
 * Returns 1 if able to determine list, 0 otherwise.
 * usage: get_globally_consistent_eligible(server,&(eliset))
 * int32 *eliset
 * That is you send us the address of a pointer to an int32 array
 * and we will fill in the pointer.
 * If return is 1, user should free eliset when done with it. Return 0
 * -> eliset will be null.
 * The index list is terminated with a -1 but may be of any length.
 * The indices are var_mindex of vars on master_var_list.
 * elist is incident vars eligible to be fixed.
 */

extern int32 consistency_analysis(slv_system_t,int32 **);
/*
 * Returns 1 if system is structurally consistent, 0 otherwise.
 * usage: consistency_analysis(server,&(fixed))
 * int32 *fixed
 * That is you send us the address of a pointer to an int32 array
 * and we will fill in the pointer.
 * The function
 * performs an automatized combinatorial consitency analysis to find
 * a partition which causes all the alernatives in the system to be
 * consitent. If the system is consistent, the array 'fixed' will contain
 * the solver var indices of a set of  variables which, if fixed, will
 * result in a consistent partition for all the alternatives in the
 * system.
 * If return is 1, user should free 'fixed' when done with it. Return 0
 * -> fixed will be null.
 * The index list is terminated with a -1 but may be of any length.
 * The indices are var_mindex of vars on master_var_list.
 * 
 */
#endif /* slvdof_already_included */
1	/*
2	* SlvDOF: Ascend Degrees of Freedom module
3	* by Benjamin A Allan and Vicente Rico-Ramirez
4	* Created: 7/11/94
5	* Version: $Revision: 1.10 $
6	* Version control file: $RCSfile: slvDOF.h,v $
7	* Date last modified: $Date: 1998/03/30 22:07:03 $
8	* Last modified by: $Author: rv2a $
9	*
10	* This file is part of the ASCEND solver interface.
11	*
12	* Copyright (C) 1994 Benjamin Andrew Allan
13	* Copyright (C) 1998 Vicente Rico-Ramirez
14	*
15	* The SLV solver is free software; you can redistribute
16	* it and/or modify it under the terms of the GNU General Public License as
17	* published by the Free Software Foundation; either version 2 of the
18	* License, or (at your option) any later version.
19	*
20	* The SLV solver is distributed in hope that it will be
21	* useful, but WITHOUT ANY WARRANTY; without even the implied warranty of
22	* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
23	* General Public License for more details.
24	*
25	* You should have received a copy of the GNU General Public License
26	* along with the program; if not, write to the Free Software Foundation,
27	* Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check the file named
28	* COPYING.
29	* COPYING is found in ../compiler.
30	*/
31
32	/*
33	* Contents: DOF module
34	*
35	* Authors: Ben Allan
36	*
37	* Dates: 07/94 - original version
38	* 06/96 - reimplementation
39	* 03/98 - Added the consistency analysis for conditional
40	* models
41	*
42	* Description: This file contains routines for managing degrees
43	* of freedom through the user interface. It uses
44	* its own incidence matrix separate from the mtx of
45	* any given solver.
46	*/
47	#ifndef slvdof_already_included
48	#define slvdof_already_included
49
50	/* requires #include <stdio.h> */
51	/* requires #include "slv_client.h" */
52
53	/*
54	* The following functions are for use in running DOF analysis and dialog
55	* through the interface. The tcl callbacks for them will be coded in
56	* DebugProc.c probably.
57	* Partitioning is assumed to be in effect.
58	* In general, the lists returned will be longer than number of degrees of
59	* freedom which can be changed. DOF dialogs should be done 1 var/rel at a
60	* time.
61	*/
62
63	extern int slvDOF_eligible(slv_system_t, int32**);
64	/*
65	* Returns 1 if able to determine lists, 0 otherwise.
66	* usage: if(slvDOF_eligible(server,&vil))
67	* int32 *vil;
68	* That is you send us the address of a pointer to an int32 array
69	* and we will fill in the pointer.
70	* If return is 1, user should free vil when done with it. Return 0
71	* -> vil will be null.
72	* The index list is terminated with a -1 but may be of any length.
73	* The indices are var_sindex of vars on solvers_var_list.
74	* vil is incident vars eligible to be fixed.
75	* This routine does not sort out which vars are in a particular part of
76	* the MODEL represented by the system -- that is a UI job.
77	* Vars that do not appear in equations will not be listed as eligible
78	* since they cannot help the DOF state of the system.
79	*/
80
81	extern int slvDOF_structsing(slv_system_t, int32, int32, int32,int32**);
82	/*
83	* if(slvDOF_structsing(server,relindex,&vil,&ril,&fil)) {.... }
84	* int32 vil, ril, fil.
85	* Returns 1 if able to determine lists, 0 otherwise.
86	* relindex should be the sindex of an unassigned, included equation
87	* from the solvers_rel_list.
88	* If relindex is mtx_FIRST, the list returned will be the intersection of
89	* all singularity lists for any unassignable included equations in
90	* the system.
91	* If return is 1, user should free r/v/fil when done with
92	* them. Return 0 -> lists will be null.
93	* The index lists are terminated with a -1.
94	* The indices are _sindex of vars/rels on solvers__list.
95	* vil is the vars involved in a structural singularity.
96	* ril is the rels involved in a structural singularity.
97	* fil is the vars which reduce the structural singularity if freed.
98	*/
99
100	extern int32 slvDOF_status(slv_system_t, int32 , int32 );
101	/*
102	* Return the status of the current problem.
103	*
104	* status = 1 ==> underspecified
105	* status = 2 ==> square
106	* status = 3 ==> structurally singular
107	* status = 4 ==> overspecifed
108	* status = 5 ==> Error !! ( insufficient memory, NULL argument,
109	* failed to presolve)
110	*
111	* If the system is underspecified, we will also get the number of the
112	* degrees of freedom for the problem.
113	*
114	*/
115
116	extern int32 get_globally_consistent_eligible(slv_system_t,int32 **);
117	/*
118	* Returns 1 if able to determine list, 0 otherwise.
119	* usage: get_globally_consistent_eligible(server,&(eliset))
120	* int32 *eliset
121	* That is you send us the address of a pointer to an int32 array
122	* and we will fill in the pointer.
123	* If return is 1, user should free eliset when done with it. Return 0
124	* -> eliset will be null.
125	* The index list is terminated with a -1 but may be of any length.
126	* The indices are var_mindex of vars on master_var_list.
127	* elist is incident vars eligible to be fixed.
128	*/
129
130	extern int32 consistency_analysis(slv_system_t,int32 **);
131	/*
132	* Returns 1 if system is structurally consistent, 0 otherwise.
133	* usage: consistency_analysis(server,&(fixed))
134	* int32 *fixed
135	* That is you send us the address of a pointer to an int32 array
136	* and we will fill in the pointer.
137	* The function
138	* performs an automatized combinatorial consitency analysis to find
139	* a partition which causes all the alernatives in the system to be
140	* consitent. If the system is consistent, the array 'fixed' will contain
141	* the solver var indices of a set of variables which, if fixed, will
142	* result in a consistent partition for all the alternatives in the
143	* system.
144	* If return is 1, user should free 'fixed' when done with it. Return 0
145	* -> fixed will be null.
146	* The index list is terminated with a -1 but may be of any length.
147	* The indices are var_mindex of vars on master_var_list.
148	*
149	*/
150	#endif /* slvdof_already_included */