Parent Directory | Revision Log

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

*Thu Dec 22 09:24:56 2005 UTC*
(16 years, 9 months ago)
by *johnpye*

File MIME type: text/x-chdr

File size: 50211 byte(s)

File MIME type: text/x-chdr

File size: 50211 byte(s)

Committed changes to C++ solver class to accommodate new slv_lookup_client. Still seeing bug #178 though.

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_lookup_client( const char *solverName ); |

379 | /**< |

380 | *** Examples: @code |

381 | *** if (slv_lookup_client("QRSlv") < 0) { |

382 | *** slv_register_client(...) |

383 | *** } |

384 | *** @endcode |

385 | *** @return the number of the named client, or -1 if unknown. |

386 | **/ |

387 | |

388 | extern int slv_register_client(SlvRegistration slv0_register |

389 | ,CONST char *yourregisterfuncname |

390 | ,CONST char *yourbinaryname |

391 | ,int *new_client_id); |

392 | /**< |

393 | Examples: @code |

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

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

396 | @endcode |

397 | |

398 | Call this function with the SlvRegistration function |

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

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

401 | a solver. @par |

402 | |

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

404 | |

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

406 | */ |

407 | |

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

409 | /**< |

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

411 | @return name of the solver |

412 | |

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

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

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

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

417 | |

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

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

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

421 | of name-number pair. |

422 | */ |

423 | |

424 | extern int Solv_C_CheckHalt_Flag; |

425 | /**< |

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

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

428 | |

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

430 | */ |

431 | |

432 | extern int Solv_C_CheckHalt(void); |

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

434 | |

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

436 | |

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

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

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

440 | |

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

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

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

444 | */ |

445 | |

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

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

448 | |

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

450 | |

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

452 | */ |

453 | |

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

455 | /**< |

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

457 | |

458 | @see slv_get_log_dofdata(). |

459 | **/ |

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

461 | /**< |

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

463 | Data in the structure should be consistent with |

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

465 | The pointer this returns cannot be freed. |

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

467 | |

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

469 | */ |

470 | |

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

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

473 | |

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

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

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

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

478 | |

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

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

481 | order given in the list. @par |

482 | |

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

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

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

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

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

488 | rectangular. |

489 | |

490 | @see slv_get_solvers_log_blocks() |

491 | */ |

492 | |

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

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

495 | |

496 | @param sys system being analysed. |

497 | |

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

499 | |

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

501 | our equation gradients to suit any factorization method |

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

503 | |

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

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

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

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

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

509 | |

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

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

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

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

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

515 | block structure completely. @par |

516 | |

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

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

519 | be NULL. |

520 | */ |

521 | |

522 | extern void slv_set_solvers_blocks(slv_system_t sys, |

523 | int32 len, |

524 | mtx_region_t *data); |

525 | /**< |

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

527 | given which should be of length len. |

528 | |

529 | @see slv_set_solvers_log_blocks() |

530 | */ |

531 | extern void slv_set_solvers_log_blocks(slv_system_t sys, |

532 | int32 len, |

533 | mtx_region_t *data); |

534 | /**< |

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

536 | given which should be of length len. |

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

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

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

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

541 | */ |

542 | |

543 | extern void slv_check_var_initialization(slv_system_t sys); |

544 | /**< |

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

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

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

548 | much better starting value than 0.0. |

549 | */ |

550 | extern void slv_check_dvar_initialization(slv_system_t sys); |

551 | /**< |

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

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

554 | a value of TRUE. |

555 | */ |

556 | |

557 | extern void slv_bnd_initialization(slv_system_t sys); |

558 | /**< |

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

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

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

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

563 | is initialized to FALSE. |

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

565 | function provided in bndman. |

566 | */ |

567 | |

568 | extern void slv_set_solvers_var_list(slv_system_t sys, |

569 | struct var_variable **vlist, |

570 | int size); |

571 | /**< |

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

573 | |

574 | @see slv_set_solvers_bnd_list() |

575 | **/ |

576 | extern void slv_set_solvers_par_list(slv_system_t sys, |

577 | struct var_variable **vlist, |

578 | int size); |

579 | /**< |

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

581 | |

582 | @see slv_set_solvers_bnd_list() |

583 | */ |

584 | extern void slv_set_solvers_unattached_list(slv_system_t sys, |

585 | struct var_variable **vlist, |

586 | int size); |

587 | /**< |

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

589 | |

590 | @see slv_set_solvers_bnd_list() |

591 | */ |

592 | |

593 | extern void slv_set_solvers_dvar_list(slv_system_t sys, |

594 | struct dis_discrete **dvlist, |

595 | int size); |

596 | /**< |

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

598 | |

599 | @see slv_set_solvers_bnd_list() |

600 | */ |

601 | |

602 | extern void slv_set_solvers_disunatt_list(slv_system_t sys, |

603 | struct dis_discrete **dvlist, |

604 | int size); |

605 | /**< |

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

607 | |

608 | @see slv_set_solvers_bnd_list() |

609 | */ |

610 | |

611 | extern void slv_set_solvers_rel_list(slv_system_t sys, |

612 | struct rel_relation **rlist, |

613 | int size); |

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

615 | |

616 | @see slv_set_solvers_bnd_list() |

617 | */ |

618 | |

619 | extern void slv_set_solvers_condrel_list(slv_system_t sys, |

620 | struct rel_relation **clist, |

621 | int size); |

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

623 | @see slv_set_solvers_bnd_list() |

624 | */ |

625 | |

626 | extern void slv_set_solvers_obj_list(slv_system_t sys, |

627 | struct rel_relation **rlist, |

628 | int size); |

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

630 | @see slv_set_solvers_bnd_list() |

631 | */ |

632 | |

633 | extern void slv_set_solvers_logrel_list(slv_system_t sys, |

634 | struct logrel_relation **lrlist, |

635 | int size); |

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

637 | @see slv_set_solvers_bnd_list() |

638 | */ |

639 | |

640 | extern void slv_set_solvers_condlogrel_list(slv_system_t sys, |

641 | struct logrel_relation **lrlist, |

642 | int size); |

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

644 | @see slv_set_solvers_bnd_list() |

645 | */ |

646 | |

647 | extern void slv_set_solvers_when_list(slv_system_t sys, |

648 | struct w_when **wlist, |

649 | int size); |

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

651 | @see slv_set_solvers_bnd_list() |

652 | */ |

653 | |

654 | extern void slv_set_solvers_bnd_list(slv_system_t sys, |

655 | struct bnd_boundary **blist, |

656 | int size); |

657 | /**< |

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

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

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

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

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

663 | |

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

665 | of the list EXCLUDING the terminal NULL. |

666 | |

667 | @NOTE |

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

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

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

671 | solver needs to know about. |

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

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

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

675 | */ |

676 | |

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

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

679 | @see slv_get_master_disunatt_list() |

680 | */ |

681 | |

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

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

684 | @see slv_get_master_disunatt_list() |

685 | */ |

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

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

688 | @see slv_get_master_disunatt_list() |

689 | */ |

690 | |

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

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

693 | @see slv_get_master_disunatt_list() |

694 | */ |

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

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

697 | @see slv_get_master_disunatt_list() |

698 | */ |

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

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

701 | @see slv_get_master_disunatt_list() |

702 | */ |

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

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

705 | @see slv_get_master_disunatt_list() |

706 | */ |

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

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

709 | @see slv_get_master_disunatt_list() |

710 | */ |

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

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

713 | @see slv_get_master_disunatt_list() |

714 | */ |

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

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

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

718 | |

719 | @NOTE |

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

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

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

723 | solver needs to know about. |

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

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

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

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

728 | |

729 | Parameters are problem invariant constants that the GUI |

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

731 | same MODEL. |

732 | */ |

733 | |

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

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

736 | |

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

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

739 | |

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

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

742 | |

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

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

745 | |

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

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

748 | |

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

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

751 | |

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

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

754 | |

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

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

757 | |

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

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

760 | |

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

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

763 | |

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

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

766 | |

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

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

769 | |

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

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

772 | |

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

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

775 | |

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

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

778 | |

779 | extern int32 slv_need_consistency(slv_system_t sys); |

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

781 | |

782 | extern int32 slv_get_num_solvers_vars(slv_system_t sys); |

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

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

785 | */ |

786 | |

787 | extern int32 slv_get_num_solvers_pars(slv_system_t sys); |

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

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

790 | */ |

791 | |

792 | extern int32 slv_get_num_solvers_unattached(slv_system_t sys); |

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

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

795 | */ |

796 | |

797 | extern int32 slv_get_num_solvers_dvars(slv_system_t sys); |

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

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

800 | */ |

801 | |

802 | extern int32 slv_get_num_solvers_disunatt(slv_system_t sys); |

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

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

805 | */ |

806 | |

807 | extern int32 slv_get_num_solvers_rels(slv_system_t sys); |

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

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

810 | */ |

811 | |

812 | extern int32 slv_get_num_solvers_condrels(slv_system_t sys); |

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

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

815 | */ |

816 | |

817 | extern int32 slv_get_num_solvers_objs(slv_system_t sys); |

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

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

820 | */ |

821 | |

822 | extern int32 slv_get_num_solvers_logrels(slv_system_t sys); |

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

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

825 | */ |

826 | |

827 | extern int32 slv_get_num_solvers_condlogrels(slv_system_t sys); |

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

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

830 | */ |

831 | |

832 | extern int32 slv_get_num_solvers_whens(slv_system_t sys); |

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

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

835 | */ |

836 | |

837 | extern int32 slv_get_num_solvers_bnds(slv_system_t sys); |

838 | /**< |

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

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

841 | **/ |

842 | extern int32 slv_get_num_master_vars(slv_system_t sys); |

843 | /**< |

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

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

846 | **/ |

847 | extern int32 slv_get_num_master_pars(slv_system_t sys); |

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

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

850 | */ |

851 | |

852 | extern int32 slv_get_num_master_unattached(slv_system_t sys); |

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

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

855 | */ |

856 | |

857 | extern int32 slv_get_num_master_dvars(slv_system_t sys); |

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

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

860 | */ |

861 | |

862 | extern int32 slv_get_num_master_disunatt(slv_system_t sys); |

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

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

865 | */ |

866 | |

867 | extern int32 slv_get_num_master_rels(slv_system_t sys); |

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

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

870 | */ |

871 | |

872 | extern int32 slv_get_num_master_condrels(slv_system_t sys); |

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

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

875 | */ |

876 | |

877 | extern int32 slv_get_num_master_objs(slv_system_t sys); |

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

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

880 | */ |

881 | |

882 | extern int32 slv_get_num_master_logrels(slv_system_t sys); |

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

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

885 | */ |

886 | |

887 | extern int32 slv_get_num_master_condlogrels(slv_system_t sys); |

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

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

890 | */ |

891 | |

892 | extern int32 slv_get_num_master_whens(slv_system_t sys); |

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

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

895 | */ |

896 | |

897 | extern int32 slv_get_num_master_bnds(slv_system_t sys); |

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

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

900 | */ |

901 | |

902 | extern int32 slv_get_num_models(slv_system_t sys); |

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

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

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

906 | */ |

907 | |

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

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

910 | |

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

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

913 | |

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

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

916 | |

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

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

919 | |

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

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

922 | |

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

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

925 | |

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

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

928 | |

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

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

931 | |

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

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

934 | |

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

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

937 | |

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

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

940 | |

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

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

943 | |

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

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

946 | |

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

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

949 | |

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

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

952 | |

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

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

955 | |

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

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

958 | |

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

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

961 | |

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

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

964 | |

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

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

967 | |

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

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

970 | |

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

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

973 | |

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

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

976 | |

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

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

979 | |

980 | /** @file slv_client.h |

981 | @NOTE |

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

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

984 | function for the list in question. |

985 | */ |

986 | |

987 | |

988 | /*----------------------------------------------------------------------- |

989 | Registered client queries. |

990 | */ |

991 | |

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

993 | /**< |

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

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

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

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

998 | */ |

999 | |

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

1001 | /**< |

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

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

1004 | |

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

1006 | */ |

1007 | |

1008 | extern void slv_set_obj_variable(slv_system_t sys, |

1009 | struct var_variable *objvar, |

1010 | unsigned maximize); |

1011 | /**< |

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

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

1014 | complete insanity may result. |

1015 | |

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

1017 | Client solvers should minimize this variable. |

1018 | |

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

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

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

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

1023 | relation if the var is defined. |

1024 | */ |

1025 | |

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

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

1028 | |

1029 | extern real64 slv_get_obj_variable_gradient(slv_system_t sys); |

1030 | /**< |

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

1032 | if no var is set. |

1033 | */ |

1034 | |

1035 | extern int slv_eligible_solver(slv_system_t sys); |

1036 | /**< |

1037 | Determines whether or not the current solver. |

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

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

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

1041 | return value may be misleading. @par |

1042 | |

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

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

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

1046 | */ |

1047 | |

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

1049 | /**< |

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

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

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

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

1054 | will be blown away. |

1055 | |

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

1057 | */ |

1058 | |

1059 | extern int slv_get_selected_solver(slv_system_t sys); |

1060 | /**< |

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

1062 | */ |

1063 | |

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

1065 | /**< |

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

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

1068 | If failure, return is -1; |

1069 | */ |

1070 | |

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

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

1073 | |

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

1075 | /**< |

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

1077 | |

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

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

1080 | */ |

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

1082 | /**< |

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

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

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

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

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

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

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

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

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

1092 | |

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

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

1095 | */ |

1096 | |

1097 | extern SlvClientToken slv_get_client_token(slv_system_t sys); |

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

1099 | |

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

1101 | /**< |

1102 | Sets the client token of the system_t. |

1103 | */ |

1104 | |

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

1106 | /**< |

1107 | Sets the solver index of the slv_system_t. |

1108 | */ |

1109 | |

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

1111 | /**< |

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

1113 | */ |

1114 | |

1115 | extern linsolqr_system_t slv_get_linsolqr_sys(slv_system_t sys); |

1116 | /**< |

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

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

1119 | */ |

1120 | |

1121 | extern linsol_system_t slv_get_linsol_sys(slv_system_t sys); |

1122 | /**< |

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

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

1125 | */ |

1126 | |

1127 | extern mtx_matrix_t slv_get_sys_mtx(slv_system_t sys); |

1128 | /**< |

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

1130 | |

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

1132 | **/ |

1133 | |

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

1135 | /**< |

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

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

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

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

1140 | principally to facilitate debugging a little. |

1141 | |

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

1143 | */ |

1144 | |

1145 | extern void slv_presolve(slv_system_t sys); |

1146 | /**< |

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

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

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

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

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

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

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

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

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

1156 | |

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

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

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

1160 | it is received. @par |

1161 | |

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

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

1164 | */ |

1165 | |

1166 | extern void slv_resolve(slv_system_t sys); |

1167 | /**< |

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

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

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

1171 | since are as follows: |

1172 | |

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

1174 | @li variable values. |

1175 | @li variable nominal values. |

1176 | @li variable bounds. |

1177 | |

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

1179 | |

1180 | @li variable fixed flag. |

1181 | @li relation included flag. |

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

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

1184 | the list. |

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

1186 | including structural rearrangement on relations, although any |

1187 | expression may be simplified. |

1188 | |

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

1190 | */ |

1191 | |

1192 | extern void slv_iterate(slv_system_t sys); |

1193 | /**< |

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

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

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

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

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

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

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

1201 | */ |

1202 | |

1203 | extern void slv_solve(slv_system_t sys); |

1204 | /**< |

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

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

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

1208 | */ |

1209 | |

1210 | extern void slv_destroy_client(slv_system_t sys); |

1211 | /**< |

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

1213 | the allocated data space of sys |

1214 | */ |

1215 | |

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

1217 | /**< |

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

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

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

1221 | won't do it. |

1222 | |

1223 | @deprecated THIS CALL SHOULD GO AWAY |

1224 | */ |

1225 | |

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

1227 | /**< |

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

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

1230 | |

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

1232 | */ |

1233 | |

1234 | #endif /* ASC_SLV_CLIENT_H */ |

1235 |

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

Powered by ViewVC 1.1.22 |