Parent Directory | Revision Log

Revision **126** -
(**show annotations**)
(**download**)
(**as text**)

*Tue Dec 20 13:27:11 2005 UTC*
(18 years, 5 months ago)
by *johnpye*

File MIME type: text/x-chdr

File size: 49987 byte(s)

File MIME type: text/x-chdr

File size: 49987 byte(s)

Reformating comments in the SLV files

1 | /* |

2 | SLV: Ascend Nonlinear Solver |

3 | Copyright (C) 1990 Karl Michael Westerberg |

4 | Copyright (C) 1993 Joseph Zaher |

5 | Copyright (C) 1994 Joseph Zaher, Benjamin Andrew Allan |

6 | Copyright (C) 1996 Benjamin Andrew Allan |

7 | Copyright (C) 2005 The ASCEND developers |

8 | |

9 | This program is free software; you can redistribute it and/or modify |

10 | it under the terms of the GNU General Public License as published by |

11 | the Free Software Foundation; either version 2 of the License, or |

12 | (at your option) any later version. |

13 | |

14 | This program is distributed in the hope that it will be useful, |

15 | but WITHOUT ANY WARRANTY; without even the implied warranty of |

16 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the |

17 | GNU General Public License for more details. |

18 | |

19 | You should have received a copy of the GNU General Public License |

20 | along with this program; if not, write to the Free Software |

21 | Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA |

22 | This file is part of the SLV solver. |

23 | */ |

24 | |

25 | #ifndef ASC_SLV_CLIENT_H |

26 | #define ASC_SLV_CLIENT_H |

27 | |

28 | /** @file |

29 | @see slv |

30 | |

31 | Requires: |

32 | #include "utilities/ascConfig.h" |

33 | #include "compiler/instance_enum.h" |

34 | #include "var.h" |

35 | #include "rel.h" |

36 | #include "discrete.h" |

37 | #include "conditional.h" |

38 | #include "logrel.h" |

39 | #include "bnd.h" |

40 | #include "linsol.h" |

41 | #include "linsolqr.h" |

42 | #include "slv_common.h" |

43 | #include "slv_types.h" |

44 | |

45 | */ |

46 | |

47 | /** @page slv SLV Solver Interface |

48 | |

49 | ASCEND (the language) exists to separate, when desirable, the |

50 | formulation of a mathematical problem (numeric) from the solution of |

51 | the that problem. ASCEND (the interface) exists to give the user as |

52 | much (or as little) control over the compilation and solution of their |

53 | problem as they want. @par |

54 | |

55 | The problems expressible in the language cannot (and indeed should not) |

56 | be reduced to a single formulation if the solutions are to be |

57 | implemented in a robust, efficient, and user controllable manner. |

58 | All but one of the solving engines attached to ASCEND must inevitably |

59 | be hamstrung if we insist that they all fit in the same interface shoebox. |

60 | Witness the minos/lsode implementations in the Pascal-version. The |

61 | alternative is to make all engines talk through an interface defined |

62 | by the intersection of the engines' individual interfaces. This |

63 | alternative is unacceptable from a software engineering point of view. @par |

64 | |

65 | This portion of the interface, then, has the task of making every |

66 | engine conform to a minimum set of semantics (thus enabling the GUI/ |

67 | CLUI to support the user wanting very little control over a host of |

68 | powerful solving engines) while giving the power hungry user access |

69 | to those parameters specific to a given engine. |

70 | The minimum semantics chosen, due mostly to convenience and the biases |

71 | of the developers, are those of slv0 with the provision of a set of |

72 | arrays for the passing of auxillary, or 'sub', parameters to each |

73 | solver. @par |

74 | |

75 | @see slv_common.h for the data structures we desire to have common to all the solvers. |

76 | |

77 | <pre> |

78 | Dates: 06/90 - original version KMW |

79 | 01/94 - modified tolerances, eliminated var_to_name |

80 | and rel_to_name function pointers, and |

81 | expanded status report |

82 | 04/94 - expanded scope of slv0 to perform optimization |

83 | 05/94 - added counting routines to count variables, |

84 | boundaries, and relations which pass some |

85 | specified filter |

86 | 10/94 - added stubs for OPT and QRSlv |

87 | 1/95 - moved status and parameters definitions to |

88 | slv_common.h. BAA |

89 | 02/96 - added stubs for NGSlv. KTH |

90 | 06/96 - split into client and server headers. |

91 | 0/97 - added stubs for CONOPT. KTH |

92 | </pre> |

93 | |

94 | @section desc Description |

95 | |

96 | The inputs to any solver consist of a formulation of |

97 | the problem to solve along with a set of parameters to |

98 | allow user control of the solution process. The |

99 | general formulation is given below (for non-discrete |

100 | problems only): |

101 | |

102 | @code |

103 | min F(x,u,c) |

104 | |

105 | s.t. h(x,u,c) = 0 |

106 | r(x,u,c) = 0 |

107 | g(x,u,c) >= 0 |

108 | b(x,u,c) >= 0 |

109 | @endcode |

110 | |

111 | A variable list consists of fixed (c), independent (u), |

112 | dependent variables (x), and unattached variables (q). |

113 | A relation list consists of unconditional (or global) |

114 | equality constraints (h), conditional equality |

115 | constraints (r), and inequality constraints (g), each of |

116 | type struct rel_relation *. The conditional equalities are |

117 | isolated from the global equalities because they are only |

118 | defined for certain ranges in values of the variables, |

119 | expressed through a set of inequality boundary relations |

120 | (b), each of type bnd_boundary_t which may or may not |

121 | be satisfied at any given point. An objective function |

122 | (F) is used to provide a criteria with which to |

123 | optimize the values of the independent variables. @par |

124 | |

125 | The objective function is a relation (LHS only) |

126 | struct rel_relation * and may be set (its default is NULL) |

127 | using slv_set_obj_relation. The variable, boundary, and |

128 | relation lists are pointer lists of |

129 | struct var_variable * and struct rel_relation * and |

130 | are expected to be NULL terminated. This means that for |

131 | 10 variables to be placed in a list, for example, 11 |

132 | elements must exist in order to reserve the last pointer |

133 | to be NULL. These lists ARE REQUIRED to be set. @par |

134 | |

135 | The additional set of inputs are the slv_parameters. |

136 | These can specify stopping conditions or the amount of |

137 | information displayed during solving, for example. |

138 | Monitoring of the solution process is done using the |

139 | status report for solvers that iterate. |

140 | More details are given with the |

141 | respective declarations below. @par |

142 | |

143 | @section arch Architecture |

144 | |

145 | Right, so we're going to have a client-server, object-oriented, |

146 | open-architecture system designed to handle multiple clients in a |

147 | single-thread process. Furthermore, the clients will NOT have to |

148 | know anything at all about the ASCEND IV compiler hidden out back |

149 | some place -- in fact our compiler may not BE out back, it may be |

150 | on another machine or swapped to disk or whatever. |

151 | |

152 | That's the ideal. In most applications of ASCEND, particularly the |

153 | interactive one, the compiler is never very far away. Isolating the |

154 | compiler data completely (meaning no looking back at it for anything) |

155 | would mean recreating all the relations (be they tokens, calls to |

156 | C code, or any kind) in a separate process. This is unacceptable from |

157 | a memory conservation point of view until RAM comes down to ~$1/MByte, |

158 | especially if ASCEND is to run on PCs any time soon. |

159 | |

160 | What we really have then is a slv_system_t made up of variables and |

161 | relations and hiding all the compiler details from the clients. |

162 | Clients will operate directly on the slv_system_t only through real |

163 | C functions and not through macros so we can hide all the nasty |

164 | details about the compiler. Variables and relations only make |

165 | sense in the context of a slv_system_t, so the var_variable type |

166 | and the rel_relation type in this C code sometimes require that |

167 | the system pointer be provided when asking for certain properties |

168 | or services. |

169 | |

170 | @section faq FAQ |

171 | |

172 | @subsection whatisvar What is a variable? |

173 | The question is ambiguous. In ASCEND we have the notion of a |

174 | solver_var ATOM type that includes bounding values, a scaling |

175 | value, and other properties. These are not the only real-number |

176 | based items that can occur, however. For purposes of the CLIENT |

177 | application programming interface (API) we collect all the real- |

178 | based objects we can find and map them all to struct var_variable. |

179 | See var.h for details. We sort them into lists as follows: |

180 | - vars. These are solver_var that are in an objective or relation. |

181 | - pars. These are solver_par appearing parametrically. |

182 | - unattached. These don't appear in relation or objective, and |

183 | they may be solver_var or solver_par or neither. |

184 | We keep 2 versions of each list: one for ourselves which is READ- |

185 | ONLY for clients and allows us to do many things efficiently, and |

186 | another for clients that clients may rearrange (or even delete) |

187 | as suits their needs. The former version is called a master list, |

188 | and the latter version is called a solvers list. |

189 | |

190 | @subsection whatisrel What is a relation? |

191 | At present a relation in ASCEND is either an objective function |

192 | (a one-sided relation) or a constraining equation. We have a |

193 | variety of relation implementations within ASCEND, but all any |

194 | client needs to know about relations can be found in the rel.h |

195 | file. We keep master and client lists of relations as well. |

196 | We provide a variety of interesting services with relations: |

197 | residual and gradient calculations |

198 | symbolic inversion (where possible) |

199 | numeric root finding |

200 | scaling based on symbolic arguments |

201 | symbolic determination of linearity |

202 | and we expect to add others as they occur to us or you suggest |

203 | them. |

204 | |

205 | @subsection whatisslvsys What else is a slv_system_t? |

206 | It's has a host of interesting properties. |

207 | @li One slv_system_t (system, hereafter) can only be used by one |

208 | *registered* client at a time, but if your client is an unregistered manager |

209 | of several subclients (for example an NLP code and and MILP code) |

210 | then you can pass it back and forth to those registered clients to solve |

211 | an MINLP. (Note: we haven't done this ourselves yet.) |

212 | Any number of unregistered clients may share a system, but they |

213 | must take responsibility for not stepping on each other or the |

214 | registered client. Registration will be explained further below. |

215 | @li From any given ASCEND type definitions, the master lists in the |

216 | system will be ordered identically across all invocations of |

217 | ASCEND on any hardware that we are aware of. This property is |

218 | derived from the way we compile instances and create systems. |

219 | This is helpful in benchmarking and other applications. |

220 | @li We have a number of standard clients (registered and not) |

221 | you can use on a the system to precondition it in some way for |

222 | your client: |

223 | - Degrees of freedom analysis. |

224 | - Problem decomposition. |

225 | - Reordering of vars and rels for good factorization. |

226 | - Solution of square nonlinear systems. |

227 | - Generation of MPS code for popular MILP solvers. |

228 | - Generation of GAMS code for an old, slow compiler of an |

229 | extremely awkward modeling language that does happen to |

230 | have a lot of really good optimizers connected. |

231 | |

232 | @TODO Short term, we expect to construct a client that takes the partitioned |

233 | problem and hands off the blocks in sequence to one or more |

234 | solvers designed to handle only 1 block. |

235 | |

236 | @TODO Long term, we anticipate that the structure laid out so far is capable of |

237 | expansion (probably by intermediate clients which add additional |

238 | semantic content) to provide standardized (mtx and harwellian) |

239 | sparse matrix support and memory management for codes that don't |

240 | care to think about such things directly. |

241 | |

242 | @NOTE |

243 | We are going through a solver API definition restructuring. |

244 | The appearance of NOTEs in the header means the code in question |

245 | has, or is about to have, a change in its meaning or is code that |

246 | is new and replaces some or all the functionality of an old |

247 | function definition. Basically, expect to have to read NOTE sections |

248 | carefully and maybe patch calls dependent on them. |

249 | */ |

250 | |

251 | typedef void *SlvClientToken; |

252 | /**< |

253 | A pointer that is meaningful to a registered client. |

254 | Each call that requires a client response will include this |

255 | token so that we can have multiple copies of a particular |

256 | client simultaneously. Clients shouldn't have to use any |

257 | global variables to save their state information -- they |

258 | should put such info with their token. |

259 | |

260 | @NOTE to present (6/96) developers: SlvClientToken is an alias for |

261 | all the old slv*_system_t pointers. cast it to be the type you want. |

262 | */ |

263 | |

264 | struct slv_reorder_data { |

265 | int partition; |

266 | int basis_selection; |

267 | int block_reordering; |

268 | /* other parameters here. convert to enums. */ |

269 | }; |

270 | |

271 | /** dof data structure */ |

272 | typedef struct dof_data_structure { |

273 | mtx_block_t blocks; /**< block structure determined by analyze */ |

274 | int32 structural_rank; /**< length of output assignment */ |

275 | int32 n_rows; /**< total included equations */ |

276 | int32 n_cols; /**< total free and incident solver variables */ |

277 | int32 n_fixed; /**< total fixed solver variables */ |

278 | int32 n_unincluded; /**< total unincluded equations */ |

279 | struct slv_reorder_data reorder; |

280 | } dof_t; |

281 | /**< dof data type */ |

282 | |

283 | #define slv_number_of_solvers g_SlvNumberOfRegisteredClients |

284 | /**< Alias for the number of solver's that have ever registered. */ |

285 | |

286 | extern int g_SlvNumberOfRegisteredClients; |

287 | /**< |

288 | The number of solver's that have ever registered. |

289 | Once a solver is registered, we keep track of its name, |

290 | a number which is the order it was registered in, and |

291 | the functions it defines. |

292 | */ |

293 | |

294 | #define SLVMAXCLIENTS 100 |

295 | /**< |

296 | The maximum number of clients that ever can be registered. |

297 | Limit is arbitrary. Note that not all clients of slv_system_t |

298 | should register, just those that purport to be solve engines |

299 | and the like. |

300 | */ |

301 | |

302 | /*----------------------------------------------------------------------- |

303 | Type declarations for registered client functions |

304 | */ |

305 | |

306 | /** @todo We will explain all these later in this file someday soon. */ |

307 | typedef SlvClientToken (SlvClientCreateF) (slv_system_t,int *); |

308 | typedef int (SlvClientDestroyF) (slv_system_t,SlvClientToken); |

309 | typedef int (SlvClientEligibleF) (slv_system_t); |

310 | typedef int32 (SlvGetDefParamsF) (slv_system_t,SlvClientToken,slv_parameters_t *); |

311 | typedef void (SlvGetParamsF) (slv_system_t, SlvClientToken, slv_parameters_t *); |

312 | typedef void (SlvSetParamsF) (slv_system_t, SlvClientToken, slv_parameters_t *); |

313 | typedef void (SlvGetStatusF) (slv_system_t, SlvClientToken, slv_status_t *); |

314 | typedef linsol_system_t (SlvGetLinsolF)(slv_system_t, SlvClientToken); |

315 | typedef linsolqr_system_t (SlvGetLinSysF)(slv_system_t, SlvClientToken); |

316 | typedef mtx_matrix_t (SlvGetSysMtxF)(slv_system_t, SlvClientToken); |

317 | typedef void (SlvDumpInfoF)(slv_system_t, SlvClientToken,int); |

318 | typedef void (SlvSolveF)(slv_system_t, SlvClientToken); |

319 | |

320 | /** Registration information for a solver. |

321 | @TODO Complete documentation of slv_registration_data members. |

322 | */ |

323 | typedef struct slv_registration_data { |

324 | int number; |

325 | /**< we set number AFTER the client registration returns 0. |

326 | client sets all the rest, starting with a symbolic name */ |

327 | |

328 | const char *name; /**< symbolic name for solver (required). */ |

329 | /* |

330 | Required functions |

331 | */ |

332 | SlvClientCreateF *ccreate; /**< (required) */ |

333 | SlvClientDestroyF *cdestroy; /**< (required) */ |

334 | SlvClientEligibleF *celigible; /**< (required) */ |

335 | SlvGetDefParamsF *getdefparam; /**< (required) */ |

336 | SlvGetParamsF *getparam; /**< (required) */ |

337 | SlvSetParamsF *setparam; /**< (required) */ |

338 | SlvGetStatusF *getstatus; /**< (required) */ |

339 | SlvSolveF *solve; /**< (required) */ |

340 | /* |

341 | Functions we really want, but can live without if your solver is old |

342 | and klunky. Your solver may not 'look good' in an interactive environment, |

343 | but then those nasty batch codes seldom do anyway. |

344 | Redesign your bloody batch code. |

345 | */ |

346 | SlvSolveF *presolve; /**< (desired) */ |

347 | SlvSolveF *iterate; /**< (desired) */ |

348 | SlvSolveF *resolve; /**< (desired) */ |

349 | /** |

350 | Strictly Optional Functions |

351 | */ |

352 | SlvGetLinsolF *getlinsol; /**< (optional) */ |

353 | SlvGetLinSysF *getlinsys; /**< (optional) */ |

354 | SlvGetSysMtxF *getsysmtx; /**< (optional) */ |

355 | SlvDumpInfoF *dumpinternals; /**< (optional) */ |

356 | } SlvFunctionsT; |

357 | |

358 | |

359 | typedef int (SlvRegistration)(SlvFunctionsT *our_sft); |

360 | /**< |

361 | This defines the required form of a function to register a new solver. |

362 | |

363 | We assume a nonzero return value means you don't register successfully. |

364 | Your function is probably part of an entire file that bridges |

365 | between our headers and your solve engine back end. |

366 | |

367 | You must provide a function in your solver bridge which to this typedef. |

368 | |

369 | Your function should fill in all the required and as many of the |

370 | optional slots in the SlvFunctions pointer you are passed as it can. |

371 | (note: do not fill in number -- that is ours.) |

372 | |

373 | If you register, but do not fill in a slot we will not accidently |

374 | call a bogus function. We will instead tell the user that an |

375 | incompetent solver was registered. |

376 | */ |

377 | |

378 | extern int slv_register_client(SlvRegistration slv0_register, |

379 | char *yourregisterfuncname, |

380 | char *yourbinaryname); |

381 | /**< |

382 | Examples: @code |

383 | slv_register_client(slv0_register,NULL,NULL); |

384 | slv_register_client(NULL,"yourregisterfuncname","yourbinaryname"); |

385 | @endcode |

386 | |

387 | Call this function with the SlvRegistration function |

388 | from your solver or with 2 strings, but not both. |

389 | The 2 char strings will be used in dynamically loading |

390 | a solver. @par |

391 | |

392 | @return 0 if registration succeeds, nonzero OTHERWISE. |

393 | |

394 | @todo Note: the second syntax is NOT YET IMPLEMENTED. |

395 | */ |

396 | |

397 | extern const char *slv_solver_name(int index); |

398 | /**< |

399 | @param index index of the solver in question (the index depends on the order in which the solvers have been registered) |

400 | @return name of the solver |

401 | |

402 | There may in general be more than one solver. The solvers will be |

403 | numbered [0..slv_number_of_solvers). Not all the solvers may |

404 | be present in a given installation of ASCEND as some are proprietary |

405 | (MINOS, for example). @par |

406 | |

407 | Solvers not yet registered will not have names. Each registered |

408 | client must have a unique name if user interfaces are to be happy, |

409 | though we suppose an interface could make a unique identifier out |

410 | of name-number pair. |

411 | */ |

412 | |

413 | extern int Solv_C_CheckHalt_Flag; |

414 | /**< |

415 | Global variable used to communicate information between solvers and |

416 | an interface, whether a calculation should be halted or not. |

417 | |

418 | @TODO Should Solc_C_CheckHalt_Flag be in the public interface? |

419 | */ |

420 | |

421 | extern int Solv_C_CheckHalt(void); |

422 | /**< Function to check for variable ascSolvStatVect(menubreak) ="1" |

423 | |

424 | @return 1 if true or if variable not found in global context, else returns 0. |

425 | |

426 | Solvers which do not have a real slv_iterate function should |

427 | use this in the functions that call on the ASCEND data structure |

428 | and should stop and restart their time clocks around the call. @par |

429 | |

430 | This is the present hack to deal with signals, particularly |

431 | SIGINT. It needs to be changed along with the front end |

432 | signal handling in the solver and scripting codes. |

433 | */ |

434 | |

435 | extern unsigned int slv_serial_id(slv_system_t sys); |

436 | /**< Return the system serial number. |

437 | |

438 | @return serial id number of given system. |

439 | |

440 | The id is unique within the life of the program. |

441 | */ |

442 | |

443 | extern dof_t *slv_get_dofdata(slv_system_t server); |

444 | /**< |

445 | @return pointer to the system's dof structure for a nonlinear solver. |

446 | |

447 | @see slv_get_log_dofdata(). |

448 | **/ |

449 | extern dof_t *slv_get_log_dofdata(slv_system_t server); |

450 | /**< |

451 | @return pointer to the system's dof structure for a logical solver. |

452 | Data in the structure should be consistent with |

453 | some interpretation of the solvers_var/rel lists. |

454 | The pointer this returns cannot be freed. |

455 | If server is not NULL, the return value will not be NULL. |

456 | |

457 | @TODO The DEFAULT interpretation has not yet been established. |

458 | */ |

459 | |

460 | extern const mtx_block_t *slv_get_solvers_blocks(slv_system_t sys); |

461 | /**< Decomposition information for the nonlinear solver. |

462 | |

463 | The blocks of the return value contain decomposition information |

464 | about the Jacobian of the equations(included) and variables(free |

465 | and incident) if it is constructed in the ordering of relations/ |

466 | variables in the solvers_rel/var_lists. @par |

467 | |

468 | That is, we have done the subproblem partitioning already. |

469 | Each region may be solved as a separate subproblem in the |

470 | order given in the list. @par |

471 | |

472 | We may have also done what we think is a good ordering |

473 | for row-wise lower-triangular linear factorization codes |

474 | within each of the blocks. We may have even arranged the |

475 | columns so that we believe we have made a 'good' set of |

476 | variables non-basic in the event that the last block is |

477 | rectangular. |

478 | |

479 | @see slv_get_solvers_log_blocks() |

480 | */ |

481 | |

482 | extern const mtx_block_t *slv_get_solvers_log_blocks(slv_system_t sys); |

483 | /**< Decomposition information for the logical solver. |

484 | |

485 | @param sys system being analysed. |

486 | |

487 | @return pointer to the block structure, or NULL if and only if sys is NULL. |

488 | |

489 | You are free to reorder any matrix you construct from |

490 | our equation gradients to suit any factorization method |

491 | you choose. We strongly recommend that you not do this. @par |

492 | |

493 | The return value is a pointer to the struct with the number of |

494 | blocks and the data for the blocks. Each block but the last |

495 | one will be square and will contain a set of rows/columns that |

496 | should be solved simultaneously. The last block may be |

497 | rectangular. Rectangular last blocks will be wider.<br><br> |

498 | |

499 | In the event that we have a structurally overspecified |

500 | problem, we will have excluded the redundant equations from |

501 | the region covered by the block list and partitioned those |

502 | equations remaining. If you are a solver client which solves |

503 | least squares problems, you should probably just ignore our |

504 | block structure completely. @par |

505 | |

506 | This will never return NULL unless sys is NULL, but if the |

507 | length of the block array is 0, then the region pointer will |

508 | be NULL. |

509 | */ |

510 | |

511 | extern void slv_set_solvers_blocks(slv_system_t sys, |

512 | int32 len, |

513 | mtx_region_t *data); |

514 | /**< |

515 | Set the block data for the nonlinear solver to the array |

516 | given which should be of length len. |

517 | |

518 | @see slv_set_solvers_log_blocks() |

519 | */ |

520 | extern void slv_set_solvers_log_blocks(slv_system_t sys, |

521 | int32 len, |

522 | mtx_region_t *data); |

523 | /**< |

524 | Set the block data for the logical solver to the array |

525 | given which should be of length len. |

526 | If the system in question already has a list of blocks, |

527 | it will be freed. This may have antisocial consequences |

528 | for registered clients if they have stored a copy of the pointer to the |

529 | old data. The should be told to reinitialize themselves. |

530 | */ |

531 | |

532 | extern void slv_check_var_initialization(slv_system_t sys); |

533 | /**< |

534 | Checks that all the variables on the solvers_var_list have |

535 | been assigned at least once. If any has not, it is assigned |

536 | its scaling value (var_nominal) since this is generally a |

537 | much better starting value than 0.0. |

538 | */ |

539 | extern void slv_check_dvar_initialization(slv_system_t sys); |

540 | /**< |

541 | Checks that all the boolean variables on the solvers_dvar_list have |

542 | been assigned at least once. If any has not, it is assigned |

543 | a value of TRUE. |

544 | */ |

545 | |

546 | extern void slv_bnd_initialization(slv_system_t sys); |

547 | /**< |

548 | Initializes the status of a boundary (satisfied ?). |

549 | At the initial point, it will be given the same value to |

550 | the current status and the previous status. Therefore, the bit |

551 | crossed (which can be modified during the iterative scheme) |

552 | is initialized to FALSE. |

553 | The evaluation of the status is performed with a call to the |

554 | function provided in bndman. |

555 | */ |

556 | |

557 | extern void slv_set_solvers_var_list(slv_system_t sys, |

558 | struct var_variable **vlist, |

559 | int size); |

560 | /**< |

561 | Sets the system's variable list to vlist. |

562 | |

563 | @see slv_set_solvers_bnd_list() |

564 | **/ |

565 | extern void slv_set_solvers_par_list(slv_system_t sys, |

566 | struct var_variable **vlist, |

567 | int size); |

568 | /**< |

569 | Sets the system's parameters list to vlist. |

570 | |

571 | @see slv_set_solvers_bnd_list() |

572 | */ |

573 | extern void slv_set_solvers_unattached_list(slv_system_t sys, |

574 | struct var_variable **vlist, |

575 | int size); |

576 | /**< |

577 | Sets the system's unattached variable list to vlist. |

578 | |

579 | @see slv_set_solvers_bnd_list() |

580 | */ |

581 | |

582 | extern void slv_set_solvers_dvar_list(slv_system_t sys, |

583 | struct dis_discrete **dvlist, |

584 | int size); |

585 | /**< |

586 | Sets the system's discrete varialbe list to dvlist. |

587 | |

588 | @see slv_set_solvers_bnd_list() |

589 | */ |

590 | |

591 | extern void slv_set_solvers_disunatt_list(slv_system_t sys, |

592 | struct dis_discrete **dvlist, |

593 | int size); |

594 | /**< |

595 | Sets the system's unattached discrete variable list to dvlist. |

596 | |

597 | @see slv_set_solvers_bnd_list() |

598 | */ |

599 | |

600 | extern void slv_set_solvers_rel_list(slv_system_t sys, |

601 | struct rel_relation **rlist, |

602 | int size); |

603 | /**< Sets the system's relation list to rlist. |

604 | |

605 | @see slv_set_solvers_bnd_list() |

606 | */ |

607 | @par |

608 | extern void slv_set_solvers_condrel_list(slv_system_t sys, |

609 | struct rel_relation **clist, |

610 | int size); |

611 | /**< Sets the system's conditional relation list to clist. |

612 | @see slv_set_solvers_bnd_list() |

613 | */ |

614 | |

615 | extern void slv_set_solvers_obj_list(slv_system_t sys, |

616 | struct rel_relation **rlist, |

617 | int size); |

618 | /**< Sets the system's objective relation list to rlist. |

619 | @see slv_set_solvers_bnd_list() |

620 | */ |

621 | |

622 | extern void slv_set_solvers_logrel_list(slv_system_t sys, |

623 | struct logrel_relation **lrlist, |

624 | int size); |

625 | /**< Sets the system's logical relation list to lrlist. |

626 | @see slv_set_solvers_bnd_list() |

627 | */ |

628 | |

629 | extern void slv_set_solvers_condlogrel_list(slv_system_t sys, |

630 | struct logrel_relation **lrlist, |

631 | int size); |

632 | /**< Sets the system's conditional relation list to lrlist. |

633 | @see slv_set_solvers_bnd_list() |

634 | */ |

635 | |

636 | extern void slv_set_solvers_when_list(slv_system_t sys, |

637 | struct w_when **wlist, |

638 | int size); |

639 | /**< Sets the system's when list to wlist. |

640 | @see slv_set_solvers_bnd_list() |

641 | */ |

642 | |

643 | extern void slv_set_solvers_bnd_list(slv_system_t sys, |

644 | struct bnd_boundary **blist, |

645 | int size); |

646 | /**< |

647 | Sets the system's boundary list to blist. If the system already |

648 | has such a list, the old list will be freed unless the two lists are |

649 | in fact the same (in which case why are you calling this?). |

650 | Size is the length of the vlist (excluding the terminal NULL entry). |

651 | The sindex field of each var in the list should match it's list position. @par |

652 | |

653 | The list should be NULL terminated and the size should be the length |

654 | of the list EXCLUDING the terminal NULL. |

655 | |

656 | @NOTE |

657 | There are now 2 var lists: the master var list pulled of the instance |

658 | tree, and the solvers var list is to be fetched by the solvers. |

659 | Eventually the solvers_varlist will only include those vars the specific |

660 | solver needs to know about. |

661 | For the moment, the content of the two lists is the same, but the ordering |

662 | is not. The master list is in the order collected. The solvers list |

663 | is reordered in some useful fashion defined elsewhere. |

664 | */ |

665 | |

666 | extern struct var_variable **slv_get_solvers_var_list(slv_system_t sys); |

667 | /**< Returns the most recently set variable list (never NULL) from the system. |

668 | @see slv_get_master_disunatt_list() |

669 | */ |

670 | |

671 | extern struct var_variable **slv_get_solvers_par_list(slv_system_t sys); |

672 | /**< Returns the most recently set par list (never NULL) from the system. |

673 | @see slv_get_master_disunatt_list() |

674 | */ |

675 | extern struct var_variable **slv_get_solvers_unattached_list(slv_system_t sys); |

676 | /**< Returns the most recently set unattached variable list (never NULL) from the system. |

677 | @see slv_get_master_disunatt_list() |

678 | */ |

679 | |

680 | extern struct dis_discrete **slv_get_solvers_dvar_list(slv_system_t sys); |

681 | /**< Returns the most recently set discrete variable list (never NULL) from the system. |

682 | @see slv_get_master_disunatt_list() |

683 | */ |

684 | extern struct dis_discrete **slv_get_solvers_disunatt_list(slv_system_t sys); |

685 | /**< Returns the most recently set unattached discrete variable list (never NULL) from the system. |

686 | @see slv_get_master_disunatt_list() |

687 | */ |

688 | extern struct var_variable **slv_get_master_var_list(slv_system_t sys); |

689 | /**< Returns the most recently set master variable list (never NULL) from the system. |

690 | @see slv_get_master_disunatt_list() |

691 | */ |

692 | extern struct var_variable **slv_get_master_par_list(slv_system_t sys); |

693 | /**< Returns the most recently set master par list (never NULL) from the system. |

694 | @see slv_get_master_disunatt_list() |

695 | */ |

696 | extern struct var_variable **slv_get_master_unattached_list(slv_system_t sys); |

697 | /**< Returns the most recently set master unattached variable list (never NULL) from the system. |

698 | @see slv_get_master_disunatt_list() |

699 | */ |

700 | extern struct dis_discrete **slv_get_master_dvar_list(slv_system_t sys); |

701 | /**< Returns the most recently set master discrete variable list (never NULL) from the system. |

702 | @see slv_get_master_disunatt_list() |

703 | */ |

704 | extern struct dis_discrete **slv_get_master_disunatt_list(slv_system_t sys); |

705 | /** Returns the most recently set master unattached discrete variable list |

706 | (never NULL) for the convenience of those who need it.<br><br> |

707 | |

708 | @NOTE |

709 | There are now 2 var lists: the master var list pulled of the instance |

710 | tree, and the solvers var list to be handed to the solvers. |

711 | Eventually the solvers_varlist will only include those vars the specific |

712 | solver needs to know about. |

713 | For the moment, the content of the two lists is the same, but the ordering |

714 | is not. The master list is in the order collected. The solvers list |

715 | is reordered in some useful fashion defined by a client. |

716 | Solver clients don't need to know about the master list. UI clients may.<br><br> |

717 | |

718 | Parameters are problem invariant constants that the GUI |

719 | user might change before solving another problem using the |

720 | same MODEL. |

721 | */ |

722 | |

723 | extern struct rel_relation **slv_get_solvers_rel_list(slv_system_t sys); |

724 | /**< Returns the (NULL-terminated) list of solver relations. */ |

725 | |

726 | extern struct rel_relation **slv_get_solvers_condrel_list(slv_system_t sys); |

727 | /**< Returns the (NULL-terminated) list of solver conditional relations. */ |

728 | |

729 | extern struct rel_relation **slv_get_solvers_obj_list(slv_system_t sys); |

730 | /**< Returns the (NULL-terminated) list of solver objective relations. */ |

731 | |

732 | extern struct logrel_relation **slv_get_solvers_logrel_list(slv_system_t sys); |

733 | /**< Returns the (NULL-terminated) list of solver logical relations. */ |

734 | |

735 | extern struct logrel_relation **slv_get_solvers_condlogrel_list(slv_system_t sys); |

736 | /**< Returns the (NULL-terminated) list of solver conditional relations. */ |

737 | |

738 | extern struct w_when **slv_get_solvers_when_list(slv_system_t sys); |

739 | /**< Returns the (NULL-terminated) list of solver whens. */ |

740 | |

741 | extern struct bnd_boundary **slv_get_solvers_bnd_list(slv_system_t sys); |

742 | /**< Returns the (NULL-terminated) list of solver boundaries. */ |

743 | |

744 | extern struct rel_relation **slv_get_master_rel_list(slv_system_t sys); |

745 | /**< Returns the (NULL-terminated) list of master relations. */ |

746 | |

747 | extern struct rel_relation **slv_get_master_condrel_list(slv_system_t sys); |

748 | /**< Returns the (NULL-terminated) list of master conditional relations. */ |

749 | |

750 | extern struct rel_relation **slv_get_master_obj_list(slv_system_t sys); |

751 | /**< Returns the (NULL-terminated) list of master objective relations. */ |

752 | |

753 | extern struct logrel_relation **slv_get_master_logrel_list(slv_system_t sys); |

754 | /**< Returns the (NULL-terminated) list of master logical relations. */ |

755 | |

756 | extern struct logrel_relation **slv_get_master_condlogrel_list(slv_system_t sys); |

757 | /**< Returns the (NULL-terminated) list of master conditional relations. */ |

758 | |

759 | extern struct w_when **slv_get_master_when_list(slv_system_t sys); |

760 | /**< Returns the (NULL-terminated) list of master whens. */ |

761 | |

762 | extern struct bnd_boundary **slv_get_master_bnd_list(slv_system_t sys); |

763 | /**< Returns the (NULL-terminated) list of master boundaries. */ |

764 | |

765 | extern struct gl_list_t *slv_get_symbol_list(slv_system_t sys); |

766 | /**< Returns the list of SymbolValues struct of a solver system. */ |

767 | |

768 | extern int32 slv_need_consistency(slv_system_t sys); |

769 | /**< Gets the int need_consitency associated with the system. */ |

770 | |

771 | extern int32 slv_get_num_solvers_vars(slv_system_t sys); |

772 | /**< Returns the length of the solver variable list. |

773 | The length does NOT include the terminating NULL. |

774 | */ |

775 | |

776 | extern int32 slv_get_num_solvers_pars(slv_system_t sys); |

777 | /**< Returns the length of the solver parameters list. |

778 | The length does NOT include the terminating NULL. |

779 | */ |

780 | |

781 | extern int32 slv_get_num_solvers_unattached(slv_system_t sys); |

782 | /**< Returns the length of the solver unsattached variable list. |

783 | The length does NOT include the terminating NULL. |

784 | */ |

785 | |

786 | extern int32 slv_get_num_solvers_dvars(slv_system_t sys); |

787 | /**< Returns the length of the solver discrete variables list. |

788 | The length does NOT include the terminating NULL. |

789 | */ |

790 | |

791 | extern int32 slv_get_num_solvers_disunatt(slv_system_t sys); |

792 | /**< Returns the length of the solver unattached discrete variables list. |

793 | The length does NOT include the terminating NULL. |

794 | */ |

795 | |

796 | extern int32 slv_get_num_solvers_rels(slv_system_t sys); |

797 | /**< Returns the length of the solver relations list. |

798 | The length does NOT include the terminating NULL. |

799 | */ |

800 | |

801 | extern int32 slv_get_num_solvers_condrels(slv_system_t sys); |

802 | /**< Returns the length of the solver conditional relations list. |

803 | The length does NOT include the terminating NULL. |

804 | */ |

805 | |

806 | extern int32 slv_get_num_solvers_objs(slv_system_t sys); |

807 | /**< Returns the length of the solver objective relations list. |

808 | The length does NOT include the terminating NULL. |

809 | */ |

810 | |

811 | extern int32 slv_get_num_solvers_logrels(slv_system_t sys); |

812 | /**< Returns the length of the solver logical relations list. |

813 | The length does NOT include the terminating NULL. |

814 | */ |

815 | |

816 | extern int32 slv_get_num_solvers_condlogrels(slv_system_t sys); |

817 | /**< Returns the length of the solver conditional relations list. |

818 | The length does NOT include the terminating NULL. |

819 | */ |

820 | |

821 | extern int32 slv_get_num_solvers_whens(slv_system_t sys); |

822 | /**< Returns the length of the solver whens list. |

823 | The length does NOT include the terminating NULL. |

824 | */ |

825 | |

826 | extern int32 slv_get_num_solvers_bnds(slv_system_t sys); |

827 | /**< |

828 | *** Returns the length of the solver boundaries list. |

829 | *** The length does NOT include the terminating NULL. |

830 | **/ |

831 | extern int32 slv_get_num_master_vars(slv_system_t sys); |

832 | /**< |

833 | *** Returns the length of the master variables list. |

834 | *** The length does NOT include the terminating NULL. |

835 | **/ |

836 | extern int32 slv_get_num_master_pars(slv_system_t sys); |

837 | /**< Returns the length of the master parameters list. |

838 | The length does NOT include the terminating NULL. |

839 | */ |

840 | |

841 | extern int32 slv_get_num_master_unattached(slv_system_t sys); |

842 | /**< Returns the length of the master unattached variables list. |

843 | The length does NOT include the terminating NULL. |

844 | */ |

845 | |

846 | extern int32 slv_get_num_master_dvars(slv_system_t sys); |

847 | /**< Returns the length of the master discrete variables list. |

848 | The length does NOT include the terminating NULL. |

849 | */ |

850 | |

851 | extern int32 slv_get_num_master_disunatt(slv_system_t sys); |

852 | /**< Returns the length of the master unattached discrete variables list. |

853 | The length does NOT include the terminating NULL. |

854 | */ |

855 | |

856 | extern int32 slv_get_num_master_rels(slv_system_t sys); |

857 | /**< Returns the length of the master relations list. |

858 | The length does NOT include the terminating NULL. |

859 | */ |

860 | |

861 | extern int32 slv_get_num_master_condrels(slv_system_t sys); |

862 | /**< Returns the length of the master conditional relations list. |

863 | The length does NOT include the terminating NULL. |

864 | */ |

865 | |

866 | extern int32 slv_get_num_master_objs(slv_system_t sys); |

867 | /**< Returns the length of the master objective relations list. |

868 | The length does NOT include the terminating NULL. |

869 | */ |

870 | |

871 | extern int32 slv_get_num_master_logrels(slv_system_t sys); |

872 | /**< Returns the length of the master logical relations list. |

873 | The length does NOT include the terminating NULL. |

874 | */ |

875 | |

876 | extern int32 slv_get_num_master_condlogrels(slv_system_t sys); |

877 | /**< Returns the length of the master conditional relations list. |

878 | The length does NOT include the terminating NULL. |

879 | */ |

880 | |

881 | extern int32 slv_get_num_master_whens(slv_system_t sys); |

882 | /**< Returns the length of the master whens list. |

883 | The length does NOT include the terminating NULL. |

884 | */ |

885 | |

886 | extern int32 slv_get_num_master_bnds(slv_system_t sys); |

887 | /**< Returns the length of the master boundaries list. |

888 | The length does NOT include the terminating NULL. |

889 | */ |

890 | |

891 | extern int32 slv_get_num_models(slv_system_t sys); |

892 | /**< Returns the number of models found in the tree the |

893 | problem was constructed from. There is no corresponding list. |

894 | Rel_relations will know which of these models they came from. |

895 | */ |

896 | |

897 | extern int32 slv_count_solvers_vars(slv_system_t sys, var_filter_t *vfilter); |

898 | /**< Returns the number of solver variables matching the specified filter. */ |

899 | |

900 | extern int32 slv_count_solvers_pars(slv_system_t sys, var_filter_t *vfilter); |

901 | /**< Returns the number of solver parameters matching the specified filter. */ |

902 | |

903 | extern int32 slv_count_solvers_unattached(slv_system_t sys, var_filter_t *vfilter); |

904 | /**< Returns the number of solver unattached variables matching the specified filter. */ |

905 | |

906 | extern int32 slv_count_solvers_dvars(slv_system_t sys, dis_filter_t *dfilter); |

907 | /**< Returns the number of solver discrete variables matching the specified filter. */ |

908 | |

909 | extern int32 slv_count_solvers_disunatt(slv_system_t sys, dis_filter_t *dfilter); |

910 | /**< Returns the number of solver unattached discrete variables matching the specified filter. */ |

911 | |

912 | extern int32 slv_count_solvers_rels(slv_system_t sys, rel_filter_t *rfilter); |

913 | /**< Returns the number of solver relations matching the specified filter. */ |

914 | |

915 | extern int32 slv_count_solvers_condrels(slv_system_t sys, rel_filter_t *rfilter); |

916 | /**< Returns the number of solver conditional relations matching the specified filter. */ |

917 | |

918 | extern int32 slv_count_solvers_objs(slv_system_t sys, rel_filter_t *rfilter); |

919 | /**< Returns the number of solver objective relations matching the specified filter. */ |

920 | |

921 | extern int32 slv_count_solvers_logrels(slv_system_t sys, logrel_filter_t *lrfilter); |

922 | /**< Returns the number of solver logical relations matching the specified filter. */ |

923 | |

924 | extern int32 slv_count_solvers_condlogrels(slv_system_t sys, logrel_filter_t *lrfilter); |

925 | /**< Returns the number of solver conditional logical relations matching the specified filter. */ |

926 | |

927 | extern int32 slv_count_solvers_whens(slv_system_t sys, when_filter_t *wfilter); |

928 | /**< Returns the number of solver whens matching the specified filter. */ |

929 | |

930 | extern int32 slv_count_solvers_bnds(slv_system_t sys, bnd_filter_t *bfilter); |

931 | /**< Returns the number of solver boundaries matching the specified filter. */ |

932 | |

933 | extern int32 slv_count_master_vars(slv_system_t sys, var_filter_t *vfilter); |

934 | /**< Returns the number of master variables matching the specified filter. */ |

935 | |

936 | extern int32 slv_count_master_pars(slv_system_t sys, var_filter_t *vfilter); |

937 | /**< Returns the number of master parameters matching the specified filter. */ |

938 | |

939 | extern int32 slv_count_master_unattached(slv_system_t sys, var_filter_t *vfilter); |

940 | /**< Returns the number of master unattached variables matching the specified filter. */ |

941 | |

942 | extern int32 slv_count_master_dvars(slv_system_t sys, dis_filter_t *dfilter); |

943 | /**< Returns the number of master discrete variables matching the specified filter. */ |

944 | |

945 | extern int32 slv_count_master_disunatt(slv_system_t sys, dis_filter_t *dfilter); |

946 | /**< Returns the number of master unattached discrete variables matching the specified filter. */ |

947 | |

948 | extern int32 slv_count_master_rels(slv_system_t sys, rel_filter_t *rfilter); |

949 | /**< Returns the number of master relations matching the specified filter. */ |

950 | |

951 | extern int32 slv_count_master_condrels(slv_system_t sys, rel_filter_t *rfilter); |

952 | /**< Returns the number of master conditional relations matching the specified filter. */ |

953 | |

954 | extern int32 slv_count_master_objs(slv_system_t sys, rel_filter_t *rfilter); |

955 | /**< Returns the number of master objective relations matching the specified filter. */ |

956 | |

957 | extern int32 slv_count_master_logrels(slv_system_t sys, logrel_filter_t *lrfilter); |

958 | /**< Returns the number of master logical relations matching the specified filter. */ |

959 | |

960 | extern int32 slv_count_master_condlogrels(slv_system_t sys, logrel_filter_t *lrfilter); |

961 | /**< Returns the number of master conditional logical relations matching the specified filter. */ |

962 | |

963 | extern int32 slv_count_master_whens(slv_system_t sys, when_filter_t *wfilter); |

964 | /**< Returns the number of master whens matching the specified filter. */ |

965 | |

966 | extern int32 slv_count_master_bnds(slv_system_t sys, bnd_filter_t *bfilter); |

967 | /**< Returns the number of master boundaries matching the specified filter. */ |

968 | |

969 | /** @file slv_client.h |

970 | @NOTE |

971 | Efficiency note relating to slv_count_master_*: if you are using this with a match anything |

972 | filter, you would be better off just calling the slv_get_num_* |

973 | function for the list in question. |

974 | */ |

975 | |

976 | |

977 | /*----------------------------------------------------------------------- |

978 | Registered client queries. |

979 | */ |

980 | |

981 | extern void slv_set_obj_relation(slv_system_t sys, struct rel_relation *obj); |

982 | /**< |

983 | Sets the objective relation of the solver to the |

984 | given one which should come from the objective list. A special value |

985 | of NULL for the objective function indicates no objective function.<br><br> |

986 | Client solvers should minimize the residual of this equation. |

987 | */ |

988 | |

989 | extern struct rel_relation *slv_get_obj_relation(slv_system_t sys); |

990 | /**< |

991 | @return the internal copy of the objective function, or |

992 | NULL if none was specified.<br><br> |

993 | |

994 | Client solvers should minimize the residual of this equation. |

995 | */ |

996 | |

997 | extern void slv_set_obj_variable(slv_system_t sys, |

998 | struct var_variable *objvar, |

999 | unsigned maximize); |

1000 | /**< |

1001 | Specifies the var to use for an objective and whether it should |

1002 | be maximized or minimized. Var must be from the slv_system or |

1003 | complete insanity may result. |

1004 | |

1005 | There is no value function here. just use var_value |

1006 | Client solvers should minimize this variable. |

1007 | |

1008 | By default, the objective var is NULL, even if there is |

1009 | and objective relation (maximize,minimize) in the ASCEND MODEL. |

1010 | (ascend MODEL objectives are handled with obj_relation functions) |

1011 | Optimizers should use objective var in preference to the obj |

1012 | relation if the var is defined. |

1013 | */ |

1014 | |

1015 | extern struct var_variable *slv_get_obj_variable(slv_system_t sys); |

1016 | /**< Returns the var used for an objective or NULL if none set. */ |

1017 | |

1018 | extern real64 slv_get_obj_variable_gradient(slv_system_t sys); |

1019 | /**< |

1020 | Returns the unscaled gradient of the objective variable, or 0 |

1021 | if no var is set. |

1022 | */ |

1023 | |

1024 | extern int slv_eligible_solver(slv_system_t sys); |

1025 | /**< |

1026 | Determines whether or not the current solver. |

1027 | is capable of solving the given system as it is currently set up |

1028 | (e.g. some solvers cannot do optimization, or inequalities, etc.). |

1029 | The system must be set up first before calling this function, or the |

1030 | return value may be misleading. @par |

1031 | |

1032 | The solver in question will be asked to pass judgement on the |

1033 | data in the slv_system_t wrt the solver being useful. |

1034 | If no solver is registered, this returns FALSE. |

1035 | */ |

1036 | |

1037 | extern int slv_select_solver(slv_system_t sys, int solver); |

1038 | /**< |

1039 | Sets the given solver to be the current solver |

1040 | for the system. The intelligence or stupidity of this move is not |

1041 | investigated. If the system has already has a solver selected and |

1042 | it is not the same solver, the data structures of the old selection |

1043 | will be blown away. |

1044 | |

1045 | @return number of solver actually selected or -1 on failure |

1046 | */ |

1047 | |

1048 | extern int slv_get_selected_solver(slv_system_t sys); |

1049 | /**< |

1050 | Returns the current solver number for a system. |

1051 | */ |

1052 | |

1053 | extern int slv_switch_solver(slv_system_t sys, int solver); |

1054 | /**< |

1055 | Sets the given solver to be the current solver for the system. |

1056 | Return value is number of solver actually selected. |

1057 | If failure, return is -1; |

1058 | */ |

1059 | |

1060 | extern int32 slv_get_default_parameters(int32 index, slv_parameters_t *parameters); |

1061 | /**< @TODO needs commenting, KHACK */ |

1062 | |

1063 | extern void slv_get_parameters(slv_system_t sys, slv_parameters_t *parameters); |

1064 | /**< |

1065 | Copies the current system parameters to the given structure. |

1066 | |

1067 | Do not confuse these parameters [algorithm control variables] |

1068 | with the parameter list which is a list of pointers to var_variable. |

1069 | */ |

1070 | extern void slv_set_parameters(slv_system_t sys, slv_parameters_t *parameters); |

1071 | /**< |

1072 | Sets the current system parameters to the values contained |

1073 | in the given structure. It is recommended that one |

1074 | gets the parameters first, before one modifies them and sets them, |

1075 | especially if not all of the parameters are to be modified (and you |

1076 | never know when that might suddenly become true because a new |

1077 | parameter was added to the structure). Parameters will only be |

1078 | accepted by an engine if they came from that engine, so fetching |

1079 | before setting is not only a good idea, it's the law (gas engines |

1080 | don't run on diesel very well...). @par |

1081 | |

1082 | Do not confuse these parameters [algorithm control variables] |

1083 | with the parameter list which is a list of pointers to var_variable. |

1084 | */ |

1085 | |

1086 | extern SlvClientToken slv_get_client_token(slv_system_t sys); |

1087 | /**< Returns the client token of the system_t. */ |

1088 | |

1089 | extern void slv_set_client_token(slv_system_t sys, SlvClientToken ct); |

1090 | /**< |

1091 | Sets the client token of the system_t. |

1092 | */ |

1093 | |

1094 | extern void slv_set_solver_index(slv_system_t sys, int index); |

1095 | /**< |

1096 | Sets the solver index of the slv_system_t. |

1097 | */ |

1098 | |

1099 | extern void slv_get_status(slv_system_t sys, slv_status_t *status); |

1100 | /**< |

1101 | Copies the current system status into the given structure. |

1102 | */ |

1103 | |

1104 | extern linsolqr_system_t slv_get_linsolqr_sys(slv_system_t sys); |

1105 | /**< |

1106 | Returns the linsolqr system used, or NULL if none. |

1107 | @deprecated { THIS CALL SHOULD GO AWAY } |

1108 | */ |

1109 | |

1110 | extern linsol_system_t slv_get_linsol_sys(slv_system_t sys); |

1111 | /**< |

1112 | Returns the linsol system used, or NULL if none. |

1113 | @deprecated { THIS CALL SHOULD GO AWAY } |

1114 | */ |

1115 | |

1116 | extern mtx_matrix_t slv_get_sys_mtx(slv_system_t sys); |

1117 | /**< |

1118 | Returns the mtx used, or NULL if none. The user should check. |

1119 | |

1120 | @deprecated {THIS CALL SHOULD GO AWAY} |

1121 | **/ |

1122 | |

1123 | extern void slv_dump_internals(slv_system_t sys, int level); |

1124 | /**< |

1125 | Will spew whatever the solver interface developer feels like to |

1126 | stderr. Larger values of level will give more detailed information, |

1127 | we hope. No specification is made with regard to what the |

1128 | information will be. returns -1 if solver gutless. This is provided |

1129 | principally to facilitate debugging a little. |

1130 | |

1131 | @TODO fix dubious documentation (return type is void...) |

1132 | */ |

1133 | |

1134 | extern void slv_presolve(slv_system_t sys); |

1135 | /**< |

1136 | Prepares the system for solving. This must be called before the |

1137 | system is solved, but after everything about the system is set up |

1138 | (i.e. variables and relations cannot be changed IN ANY WAY, objective |

1139 | function cannot be modified, boundaries cannot be modified, or even |

1140 | repermuted, and a new solver cannot be selected: some parameters may |

1141 | be modified, they will be marked as such). The system essentially |

1142 | becomes "read-only". If anything is modified after slv_presolve was |

1143 | called, slv_presolve must be called again before solving (EXCEPTIONS: |

1144 | slv_resolve may do for a certain restricted class of changes). @par |

1145 | |

1146 | It is at this point that the variable list is created if it does not |

1147 | already exist and the newly created variables are indexed in the |

1148 | order they end up. The relation list is indexed as well in the order |

1149 | it is received. @par |

1150 | |

1151 | Among other things, this function will perform structural analysis |

1152 | so that structural analysis flags in the status will be accurate. |

1153 | */ |

1154 | |

1155 | extern void slv_resolve(slv_system_t sys); |

1156 | /**< |

1157 | This function re-prepares the system for solving. This function may |

1158 | be used instead of slv_presolve, provided the system was partially |

1159 | or completely solved before, and then the only changes to the system |

1160 | since are as follows: |

1161 | |

1162 | @li any parameter except "partition". |

1163 | @li variable values. |

1164 | @li variable nominal values. |

1165 | @li variable bounds. |

1166 | |

1167 | In particular, the following changes are NOT allowed: |

1168 | |

1169 | @li variable fixed flag. |

1170 | @li relation included flag. |

1171 | @li variable/relation list contents, including order. Also, the |

1172 | variable/relation indices must continue to be consistent with |

1173 | the list. |

1174 | @li definition of relations, objective function, and boundaries: |

1175 | including structural rearrangement on relations, although any |

1176 | expression may be simplified. |

1177 | |

1178 | This function is considerably more efficient when it is usable. |

1179 | */ |

1180 | |

1181 | extern void slv_iterate(slv_system_t sys); |

1182 | /**< |

1183 | Performs one iteration toward the ultimate solution (or |

1184 | failure thereof) of the system. The user can obtain information |

1185 | from the status and from the variables and relations themselves |

1186 | (some care should be taken in examining the residuals of relations; |

1187 | they may not be up to date). The user may not modify the system in |

1188 | any way between iterations (i.e. you may look, but don't touch: see |

1189 | slv_presolve()). See also slv_solve(). |

1190 | */ |

1191 | |

1192 | extern void slv_solve(slv_system_t sys); |

1193 | /**< |

1194 | Attempts to solve the entire system in one shot (i.e. |

1195 | performs as many iterations as needed or allowed). For some solvers, |

1196 | slv_iterate() and slv_solve() may mean the same thing. |

1197 | */ |

1198 | |

1199 | extern void slv_destroy_client(slv_system_t sys); |

1200 | /**< |

1201 | Destroy the client token of slv_system_t. It does not deallocate |

1202 | the allocated data space of sys |

1203 | */ |

1204 | |

1205 | extern boolean slv_change_basis(slv_system_t,int32,mtx_range_t *); |

1206 | /**< |

1207 | Move var (given by index #) to the unassigned region (far right) |

1208 | of the solver matrix if possible. returns FALSE if impossible |

1209 | because structural infeasibility would occur or because solver selected |

1210 | won't do it. |

1211 | |

1212 | @deprecated THIS CALL SHOULD GO AWAY |

1213 | */ |

1214 | |

1215 | extern void slv_print_output(FILE *fp, slv_system_t sys); |

1216 | /**< |

1217 | Start of some report generation routines. For now just prints out |

1218 | the variable values and residuals at the moment. |

1219 | |

1220 | @TODO make more general in the future. |

1221 | */ |

1222 | |

1223 | #endif /* ASC_SLV_CLIENT_H */ |

1224 |

john.pye@anu.edu.au | ViewVC Help |

Powered by ViewVC 1.1.22 |