ascend4/solver/slv_stdcalls.h

/*
 *  Standard Clients module of ASCEND environment
 *  by Benjamin Andrew Allan
 *  5/19/96
 *  Version: $Revision: 1.8 $
 *  Version control file: $RCSfile: slv_stdcalls.h,v $
 *  Date last modified: $Date: 1998/06/16 16:53:07 $
 *  Last modified by: $Author: mthomas $
 *
 *  Copyright(C) 1996 Benjamin Andrew Allan
 *  Copyright(C) 1998 Carnegie Mellon University
 *
 *  This file is part of the ASCEND IV math programming system.
 *  It registers our primary clients (solvers) and provides a home
 *  for several unregistered utility clients.
 *
 *  The Ascend Math Programming System 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 Ascend Math Programming System 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.
 */

#ifndef _slv_stdclients_h_seen_
#define _slv_stdclients_h_seen_
/* requires #include <stdio.h> */
/* requires #include "system.h" */
/* requires #include "slv_client.h" */
/* requires #include "mtx.h" */
/* requires #include "slvDOF.h" */

extern int slv_std_make_incidence_mtx(slv_system_t, mtx_matrix_t, 
                                      var_filter_t *,rel_filter_t *);
/*********************************************************************\
err = slv_std_make_incidence_mtx(sys,mtx,vf,rf);

Populates a matrix according to the sys solvers_vars, solvers_rels
lists and the filters given. The filter should have at least 
SVAR = 1 bit on. mtx given must be created (not null) and with
order >= max( slv_get_num_solvers_rels(sys),slv_get_num_solvers_vars(sys));
Vars and rels on solvers lists should be sindexed 0 -> len-1.
Returns 0 if went ok.
\*********************************************************************/

#define slv_block_partition(s) slv_block_partition_real((s),0)
/* do BLT permutation to system solvers lists */

#define slv_block_partition_upper(s) slv_block_partition_real((s),1)
/* do BUT permutation to system solvers lists */

extern int slv_block_partition_real(slv_system_t,int);
/*********************************************************************\
  status = slv_block_partition(sys);
  Takes a system and reorders its solvers_vars and solvers_rels
  list so that they fall into a block lower(upper) triangular form and
  the system's block list is set to match.
  Only included equality relations and free, incident solver_var
  are so ordered.
  The blocks derived are put in the slv_system_t block list.
  If this succeeds, return value is 0.
  If fail due to insufficient memory, return is 2.
  If fail for any other reason, return is 1.
  Produces whine about DOF analysis on file stderr.

  ASSUMPTION: We assume that the variable and relation bit flags
  are in sync with the flags on the atoms.  The need for this
  assumption and the associated bookkeeping should go away when
  we move to using only the bit flags.  Currently var_fixed and
  rel_included are in charge of the syncronization.
\*********************************************************************/

extern void slv_sort_rels_and_vars(slv_system_t,int32 *,int32 *);
/*********************************************************************\
  slv_sort_rels_and_vars(sys,rel_count,var_count);
  Reindexes systems rel and var lists such that rel list is in order:
  rel_list = |included and active rels|unincluded|inactive|
  and the var list is in the order:
  var_list = |incident free solver vars|unincluded|inactive|
  Upon return rel_count will be the number of included and active rels
  and var_count will be the number of incident free solver vars.
  If either rel_count or var_count is -1 then a memory allocation
  failed and this function bailed out without doing any work.
\*********************************************************************/
     
int slv_block_unify(slv_system_t);
/*********************************************************************\
  Takes a system that has been through slv_block_partition and combines
  the blocks that comprise rows 0 -> (structural_rank -1) and
  columns 0 to ncols-1 in the system's dof_t into one block.
  This may be useful for optimizers which want a whole rectangular
  block.
\*********************************************************************/

extern int slv_set_up_block(slv_system_t,int32);
/*********************************************************************\
  status = slv_set_up_block(sys,block);
  This function should be called on blocks which have previously
  been reordered.  Variable and relation maintanence is performed
  so that the block will be ready for an interation.
  ***rest of this is cut from slv_spk1_reorder***
  System should have first been processed by slv_block_partition,
  so that all the current rows and columns within the block
  correspond to org rows and columns within the block.
  solvers_vars and solvers_rels lists are
  reordered and reindexed within that region to match.
  The block should contain only included equality relations and
  free, incident solver_vars.
  If we made a matrix out of the block, it should have a full
  diagonal.
  If this succeeds, return value is 0.
  If fail due to insufficient memory, return is 2.
  If fail for any other reason, return is 1.

  Preconditions of use:
    No vars outside the block in the solvers_var list should have
    VAR_INBLOCK set to TRUE.
  Sideeffects: 
  We will diddle with all the vars in the solvers_vars and solver_rels
  list so that all rel/vars inside the block respond TRUE to in_block.
  We will do this even if we decide to block is too small to be worth
  reordering or is the wrong shape.
  Bugs:
  This should optionally take a user supplied matrix so it doesn't
  allocate a big matrix header+perms every time. This needs some
  thought.
\*********************************************************************/

     
extern int slv_spk1_reorder_block(slv_system_t, int32, int32);
/*********************************************************************\
  status = slv_spk1_reorder_block(sys,block,transpose);
  System should have first been processed by slv_block_partition,
  so that all the current rows and columns within the block
  correspond to org rows and columns within the block.
  Within the diagonal block given (which must be square), an SPK1
  reordering is done. solvers_vars and solvers_rels lists are
  reordered and reindexed within that region to match.
  The block should contain only included equality relations and
  free, incident solver_vars.
  transpose determines if SPK1 is transposed.
  If we made a matrix out of the block, it should have a full
  diagonal.
  If this succeeds, return value is 0.
  If fail due to insufficient memory, return is 2.
  If fail for any other reason, return is 1.

  Preconditions of use:
    No vars outside the block in the solvers_var list should have
    VAR_INBLOCK set to TRUE.
  Sideeffects: 
  We will diddle with all the vars in the solvers_vars and solver_rels
  list so that all rel/vars inside the block respond TRUE to in_block.
  We will do this even if we decide to block is too small to be worth
  reordering or is the wrong shape.
  Bugs:
  This should optionally take a user supplied matrix so it doesn't
  allocate a big matrix header+perms every time. This needs some
  thought.
\*********************************************************************/

extern int slv_tear_drop_reorder_block(slv_system_t,int32,int32,
                                       int,enum mtx_reorder_method);
/*********************************************************************\
  slv_tear_drop_reorder_block(sys,blockindex,cutoff,two,blockmethod);
  System should have first been processed by slv_block_partition,
  so that all the current rows and columns within the block
  correspond to org rows and columns within the block.
  If you made a matrix out of the block, it should have a full
  diagonal.
  Given a system and the index of a block in that system,
  applies a variant of the reordering hinted at in [Abbott,1996].
  The implementation here is by Ben Allan, so any discrepancies
  (positive) in performance with respect to the Abbott
  thesis data are Ben's fault.
  If two != 0, applies an algorithm slightly more similar to that
  of Abbott, getting borders roughly twice as large.
  Preconditions of use: same as spk1_reorder_block.
  Sideeffects and bugs: same as spk1_reorder_block.
  Additional bugs: none known, but they're there.
\*********************************************************************/

extern int slv_insure_bounds(slv_system_t,int32,int32,FILE *);
/*********************************************************************\
  nchange = slv_insure_bounds(sys,lo,hi,fp);
  Takes a system and a range of vars (lo,hi) and makes sure all the
  variables are within bounds and bounds are reasonable. makes 
  repairs in all cases where they are not. Returns the number
  of repairs made or -1 if something weird found.
  If fp is not NULL, prints notices to the file given.
\*********************************************************************/

extern void slv_check_bounds(const slv_system_t,int32,int32, 
                             FILE *,const char *);
/*********************************************************************\
  slv_check_bounds(sys,lo,hi,fp,label);
  Takes a system and a range of vars (lo,hi) and makes sure all the
  variables are within bounds and bounds are reasonable. Whines
  to fp using the label in all cases where they are not.
  Does not change anything.
  If fp is NULL, does nothing.
\*********************************************************************/

extern int SlvRegisterStandardClients(void);
/*********************************************************************\
  Attempts to register solvers slv0 through (as of 6/96) slv7.
  Returns the number of these which register successfully.
  The solvers registered here are those linked at build time of the
  ascend binary. See slv_client.h for registering dynamically loaded
  solvers.
\*********************************************************************/


/*********************************************************************\
          Output Assignment and partitiong in Logical Relations    
\*********************************************************************/

extern int slv_std_make_log_incidence_mtx(slv_system_t, mtx_matrix_t, 
                                          dis_filter_t *,logrel_filter_t *);
/*********************************************************************\
err = slv_std_make_log_incidence_mtx(sys,mtx,dvf,lrf);

Populates a matrix according to the sys solvers_dvars, solvers_logrels
lists and the filters given. mtx given must be created (not null) and with
order >= max( slv_get_num_solvers_logrels(sys),
              slv_get_num_solvers_dvars(sys));
Dvars and logrels on solvers lists should be sindexed 0 -> len-1.
Returns 0 if went ok.
\*********************************************************************/

extern int slv_log_block_partition(slv_system_t);
/*********************************************************************\
  status = slv_log_block_partition(sys);
  Takes a system and reorders its solvers_dvars and solvers_logrels
  list so that they fall into a block lower triangular form and
  the system's block list is set to match.
  Only included and active logrelations and free, incident boolean_var
  are so ordered.
  The blocks derived are put in the slv_system_t block list.
  If this succeeds, return value is 0.
  If fail due to insufficient memory, return is 2.
  If fail for any other reason, return is 1.
\*********************************************************************/

#endif /*  _slv_stdclients_h_seen_ */
1	/*
2	* Standard Clients module of ASCEND environment
3	* by Benjamin Andrew Allan
4	* 5/19/96
5	* Version: $Revision: 1.8 $
6	* Version control file: $RCSfile: slv_stdcalls.h,v $
7	* Date last modified: $Date: 1998/06/16 16:53:07 $
8	* Last modified by: $Author: mthomas $
9	*
10	* Copyright(C) 1996 Benjamin Andrew Allan
11	* Copyright(C) 1998 Carnegie Mellon University
12	*
13	* This file is part of the ASCEND IV math programming system.
14	* It registers our primary clients (solvers) and provides a home
15	* for several unregistered utility clients.
16	*
17	* The Ascend Math Programming System is free software; you can
18	* redistribute it and/or modify it under the terms of the GNU
19	* General Public License as published by the Free Software
20	* Foundation; either version 2 of the License, or (at your option)
21	* any later version.
22	*
23	* The Ascend Math Programming System is distributed in hope that it
24	* will be useful, but WITHOUT ANY WARRANTY; without even the implied
25	* warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
26	* See the GNU General Public License for more details.
27	*
28	* You should have received a copy of the GNU General Public License
29	* along with the program; if not, write to the Free Software
30	* Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139 USA. Check
31	* the file named COPYING.
32	*/
33
34	#ifndef _slv_stdclients_h_seen_
35	#define _slv_stdclients_h_seen_
36	/* requires #include <stdio.h> */
37	/* requires #include "system.h" */
38	/* requires #include "slv_client.h" */
39	/* requires #include "mtx.h" */
40	/* requires #include "slvDOF.h" */
41
42	extern int slv_std_make_incidence_mtx(slv_system_t, mtx_matrix_t,
43	var_filter_t ,rel_filter_t );
44	/*********************************************************************\
45	err = slv_std_make_incidence_mtx(sys,mtx,vf,rf);
46
47	Populates a matrix according to the sys solvers_vars, solvers_rels
48	lists and the filters given. The filter should have at least
49	SVAR = 1 bit on. mtx given must be created (not null) and with
50	order >= max( slv_get_num_solvers_rels(sys),slv_get_num_solvers_vars(sys));
51	Vars and rels on solvers lists should be sindexed 0 -> len-1.
52	Returns 0 if went ok.
53	\*********************************************************************/
54
55	#define slv_block_partition(s) slv_block_partition_real((s),0)
56	/* do BLT permutation to system solvers lists */
57
58	#define slv_block_partition_upper(s) slv_block_partition_real((s),1)
59	/* do BUT permutation to system solvers lists */
60
61	extern int slv_block_partition_real(slv_system_t,int);
62	/*********************************************************************\
63	status = slv_block_partition(sys);
64	Takes a system and reorders its solvers_vars and solvers_rels
65	list so that they fall into a block lower(upper) triangular form and
66	the system's block list is set to match.
67	Only included equality relations and free, incident solver_var
68	are so ordered.
69	The blocks derived are put in the slv_system_t block list.
70	If this succeeds, return value is 0.
71	If fail due to insufficient memory, return is 2.
72	If fail for any other reason, return is 1.
73	Produces whine about DOF analysis on file stderr.
74
75	ASSUMPTION: We assume that the variable and relation bit flags
76	are in sync with the flags on the atoms. The need for this
77	assumption and the associated bookkeeping should go away when
78	we move to using only the bit flags. Currently var_fixed and
79	rel_included are in charge of the syncronization.
80	\*********************************************************************/
81
82	extern void slv_sort_rels_and_vars(slv_system_t,int32 ,int32 );
83	/*********************************************************************\
84	slv_sort_rels_and_vars(sys,rel_count,var_count);
85	Reindexes systems rel and var lists such that rel list is in order:
86	rel_list = \|included and active rels\|unincluded\|inactive\|
87	and the var list is in the order:
88	var_list = \|incident free solver vars\|unincluded\|inactive\|
89	Upon return rel_count will be the number of included and active rels
90	and var_count will be the number of incident free solver vars.
91	If either rel_count or var_count is -1 then a memory allocation
92	failed and this function bailed out without doing any work.
93	\*********************************************************************/
94
95	int slv_block_unify(slv_system_t);
96	/*********************************************************************\
97	Takes a system that has been through slv_block_partition and combines
98	the blocks that comprise rows 0 -> (structural_rank -1) and
99	columns 0 to ncols-1 in the system's dof_t into one block.
100	This may be useful for optimizers which want a whole rectangular
101	block.
102	\*********************************************************************/
103
104	extern int slv_set_up_block(slv_system_t,int32);
105	/*********************************************************************\
106	status = slv_set_up_block(sys,block);
107	This function should be called on blocks which have previously
108	been reordered. Variable and relation maintanence is performed
109	so that the block will be ready for an interation.
110	*rest of this is cut from slv_spk1_reorder*
111	System should have first been processed by slv_block_partition,
112	so that all the current rows and columns within the block
113	correspond to org rows and columns within the block.
114	solvers_vars and solvers_rels lists are
115	reordered and reindexed within that region to match.
116	The block should contain only included equality relations and
117	free, incident solver_vars.
118	If we made a matrix out of the block, it should have a full
119	diagonal.
120	If this succeeds, return value is 0.
121	If fail due to insufficient memory, return is 2.
122	If fail for any other reason, return is 1.
123
124	Preconditions of use:
125	No vars outside the block in the solvers_var list should have
126	VAR_INBLOCK set to TRUE.
127	Sideeffects:
128	We will diddle with all the vars in the solvers_vars and solver_rels
129	list so that all rel/vars inside the block respond TRUE to in_block.
130	We will do this even if we decide to block is too small to be worth
131	reordering or is the wrong shape.
132	Bugs:
133	This should optionally take a user supplied matrix so it doesn't
134	allocate a big matrix header+perms every time. This needs some
135	thought.
136	\*********************************************************************/
137
138
139	extern int slv_spk1_reorder_block(slv_system_t, int32, int32);
140	/*********************************************************************\
141	status = slv_spk1_reorder_block(sys,block,transpose);
142	System should have first been processed by slv_block_partition,
143	so that all the current rows and columns within the block
144	correspond to org rows and columns within the block.
145	Within the diagonal block given (which must be square), an SPK1
146	reordering is done. solvers_vars and solvers_rels lists are
147	reordered and reindexed within that region to match.
148	The block should contain only included equality relations and
149	free, incident solver_vars.
150	transpose determines if SPK1 is transposed.
151	If we made a matrix out of the block, it should have a full
152	diagonal.
153	If this succeeds, return value is 0.
154	If fail due to insufficient memory, return is 2.
155	If fail for any other reason, return is 1.
156
157	Preconditions of use:
158	No vars outside the block in the solvers_var list should have
159	VAR_INBLOCK set to TRUE.
160	Sideeffects:
161	We will diddle with all the vars in the solvers_vars and solver_rels
162	list so that all rel/vars inside the block respond TRUE to in_block.
163	We will do this even if we decide to block is too small to be worth
164	reordering or is the wrong shape.
165	Bugs:
166	This should optionally take a user supplied matrix so it doesn't
167	allocate a big matrix header+perms every time. This needs some
168	thought.
169	\*********************************************************************/
170
171	extern int slv_tear_drop_reorder_block(slv_system_t,int32,int32,
172	int,enum mtx_reorder_method);
173	/*********************************************************************\
174	slv_tear_drop_reorder_block(sys,blockindex,cutoff,two,blockmethod);
175	System should have first been processed by slv_block_partition,
176	so that all the current rows and columns within the block
177	correspond to org rows and columns within the block.
178	If you made a matrix out of the block, it should have a full
179	diagonal.
180	Given a system and the index of a block in that system,
181	applies a variant of the reordering hinted at in [Abbott,1996].
182	The implementation here is by Ben Allan, so any discrepancies
183	(positive) in performance with respect to the Abbott
184	thesis data are Ben's fault.
185	If two != 0, applies an algorithm slightly more similar to that
186	of Abbott, getting borders roughly twice as large.
187	Preconditions of use: same as spk1_reorder_block.
188	Sideeffects and bugs: same as spk1_reorder_block.
189	Additional bugs: none known, but they're there.
190	\*********************************************************************/
191
192	extern int slv_insure_bounds(slv_system_t,int32,int32,FILE *);
193	/*********************************************************************\
194	nchange = slv_insure_bounds(sys,lo,hi,fp);
195	Takes a system and a range of vars (lo,hi) and makes sure all the
196	variables are within bounds and bounds are reasonable. makes
197	repairs in all cases where they are not. Returns the number
198	of repairs made or -1 if something weird found.
199	If fp is not NULL, prints notices to the file given.
200	\*********************************************************************/
201
202	extern void slv_check_bounds(const slv_system_t,int32,int32,
203	FILE ,const char );
204	/*********************************************************************\
205	slv_check_bounds(sys,lo,hi,fp,label);
206	Takes a system and a range of vars (lo,hi) and makes sure all the
207	variables are within bounds and bounds are reasonable. Whines
208	to fp using the label in all cases where they are not.
209	Does not change anything.
210	If fp is NULL, does nothing.
211	\*********************************************************************/
212
213	extern int SlvRegisterStandardClients(void);
214	/*********************************************************************\
215	Attempts to register solvers slv0 through (as of 6/96) slv7.
216	Returns the number of these which register successfully.
217	The solvers registered here are those linked at build time of the
218	ascend binary. See slv_client.h for registering dynamically loaded
219	solvers.
220	\*********************************************************************/
221
222
223	/*********************************************************************\
224	Output Assignment and partitiong in Logical Relations
225	\*********************************************************************/
226
227	extern int slv_std_make_log_incidence_mtx(slv_system_t, mtx_matrix_t,
228	dis_filter_t ,logrel_filter_t );
229	/*********************************************************************\
230	err = slv_std_make_log_incidence_mtx(sys,mtx,dvf,lrf);
231
232	Populates a matrix according to the sys solvers_dvars, solvers_logrels
233	lists and the filters given. mtx given must be created (not null) and with
234	order >= max( slv_get_num_solvers_logrels(sys),
235	slv_get_num_solvers_dvars(sys));
236	Dvars and logrels on solvers lists should be sindexed 0 -> len-1.
237	Returns 0 if went ok.
238	\*********************************************************************/
239
240	extern int slv_log_block_partition(slv_system_t);
241	/*********************************************************************\
242	status = slv_log_block_partition(sys);
243	Takes a system and reorders its solvers_dvars and solvers_logrels
244	list so that they fall into a block lower triangular form and
245	the system's block list is set to match.
246	Only included and active logrelations and free, incident boolean_var
247	are so ordered.
248	The blocks derived are put in the slv_system_t block list.
249	If this succeeds, return value is 0.
250	If fail due to insufficient memory, return is 2.
251	If fail for any other reason, return is 1.
252	\*********************************************************************/
253
254	#endif /* _slv_stdclients_h_seen_ */