Parent Directory | Revision Log

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

*Fri Jan 27 04:23:20 2006 UTC*
(14 years, 10 months ago)
by *johnpye*

File MIME type: text/x-chdr

File size: 50345 byte(s)

File MIME type: text/x-chdr

File size: 50345 byte(s)

Updating for Jerry's new error_reporter syntax, bug #179

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-2006 Carnegie Mellon University |

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 | Haha :-) $1/MB! Jan 2006: 118 AUD = 512 MB = ~ 0.15 USD/MB -- johnpye |

161 | |

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

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

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

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

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

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

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

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

170 | or services. |

171 | |

172 | @section faq FAQ |

173 | |

174 | @subsection whatisvar What is a variable? |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

191 | |

192 | @subsection whatisrel What is a relation? |

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

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

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

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

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

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

199 | - residual and gradient calculations |

200 | - symbolic inversion (where possible) |

201 | - numeric root finding |

202 | - scaling based on symbolic arguments |

203 | - symbolic determination of linearity |

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

205 | them. |

206 | |

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

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

209 | - One slv_system_t (system, hereafter) can only be used by one |

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

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

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

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

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

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

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

217 | - From any given ASCEND type definitions, the master lists in the |

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

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

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

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

222 | - We have a number of standard clients (registered and not) |

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

224 | your client: |

225 | - Degrees of freedom analysis. |

226 | - Problem decomposition. |

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

228 | - Solution of square nonlinear systems. |

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

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

231 | extremely awkward modeling language that does happen to |

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

233 | |

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

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

236 | solvers designed to handle only 1 block. |

237 | |

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

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

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

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

242 | care to think about such things directly. |

243 | |

244 | @NOTE |

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

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

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

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

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

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

251 | */ |

252 | |

253 | typedef void *SlvClientToken; |

254 | /**< |

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

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

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

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

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

260 | should put such info with their token. |

261 | |

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

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

264 | */ |

265 | |

266 | struct slv_reorder_data { |

267 | int partition; |

268 | int basis_selection; |

269 | int block_reordering; |

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

271 | }; |

272 | |

273 | /** dof data structure */ |

274 | typedef struct dof_data_structure { |

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

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

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

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

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

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

281 | struct slv_reorder_data reorder; |

282 | } dof_t; |

283 | /**< dof data type */ |

284 | |

285 | #define slv_number_of_solvers g_SlvNumberOfRegisteredClients |

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

287 | |

288 | extern int g_SlvNumberOfRegisteredClients; |

289 | /**< |

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

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

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

293 | the functions it defines. |

294 | */ |

295 | |

296 | #define SLVMAXCLIENTS 100 |

297 | /**< |

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

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

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

301 | and the like. |

302 | */ |

303 | |

304 | /*----------------------------------------------------------------------- |

305 | Type declarations for registered client functions |

306 | */ |

307 | |

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

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

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

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

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

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

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

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

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

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

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

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

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

321 | |

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

323 | @TODO Complete documentation of slv_registration_data members. |

324 | */ |

325 | typedef struct slv_registration_data { |

326 | int number; |

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

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

329 | |

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

331 | /* |

332 | Required functions |

333 | */ |

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

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

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

337 | SlvGetDefParamsF *getdefparam; /**< Function that will create default solver-parameter structure (required) */ |

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

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

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

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

342 | /* |

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

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

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

346 | Redesign your bloody batch code. |

347 | */ |

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

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

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

351 | /** |

352 | Strictly Optional Functions |

353 | */ |

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

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

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

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

358 | } SlvFunctionsT; |

359 | |

360 | |

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

362 | /**< |

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

364 | |

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

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

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

368 | |

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

370 | |

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

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

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

374 | |

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

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

377 | incompetent solver was registered. |

378 | */ |

379 | |

380 | extern int slv_lookup_client( const char *solverName ); |

381 | /**< |

382 | *** Examples: @code |

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

384 | *** slv_register_client(...) |

385 | *** } |

386 | *** @endcode |

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

388 | **/ |

389 | |

390 | extern int slv_register_client(SlvRegistration slv0_register |

391 | ,CONST char *yourregisterfuncname |

392 | ,CONST char *yourbinaryname |

393 | ,int *new_client_id); |

394 | /**< |

395 | Examples: @code |

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

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

398 | @endcode |

399 | |

400 | Call this function with the SlvRegistration function |

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

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

403 | a solver. @par |

404 | |

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

406 | |

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

408 | */ |

409 | |

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

411 | /**< |

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

413 | @return name of the solver |

414 | |

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

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

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

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

419 | |

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

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

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

423 | of name-number pair. |

424 | */ |

425 | |

426 | extern int Solv_C_CheckHalt_Flag; |

427 | /**< |

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

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

430 | |

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

432 | */ |

433 | |

434 | extern int Solv_C_CheckHalt(void); |

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

436 | |

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

438 | |

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

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

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

442 | |

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

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

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

446 | */ |

447 | |

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

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

450 | |

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

452 | |

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

454 | */ |

455 | |

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

457 | /**< |

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

459 | |

460 | @see slv_get_log_dofdata(). |

461 | **/ |

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

463 | /**< |

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

465 | Data in the structure should be consistent with |

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

467 | The pointer this returns cannot be freed. |

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

469 | |

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

471 | */ |

472 | |

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

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

475 | |

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

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

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

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

480 | |

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

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

483 | order given in the list. @par |

484 | |

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

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

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

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

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

490 | rectangular. |

491 | |

492 | @see slv_get_solvers_log_blocks() |

493 | */ |

494 | |

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

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

497 | |

498 | @param sys system being analysed. |

499 | |

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

501 | |

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

503 | our equation gradients to suit any factorization method |

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

505 | |

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

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

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

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

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

511 | |

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

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

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

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

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

517 | block structure completely. @par |

518 | |

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

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

521 | be NULL. |

522 | */ |

523 | |

524 | extern void slv_set_solvers_blocks(slv_system_t sys, |

525 | int32 len, |

526 | mtx_region_t *data); |

527 | /**< |

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

529 | given which should be of length len. |

530 | |

531 | @see slv_set_solvers_log_blocks() |

532 | */ |

533 | extern void slv_set_solvers_log_blocks(slv_system_t sys, |

534 | int32 len, |

535 | mtx_region_t *data); |

536 | /**< |

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

538 | given which should be of length len. |

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

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

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

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

543 | */ |

544 | |

545 | extern void slv_check_var_initialization(slv_system_t sys); |

546 | /**< |

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

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

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

550 | much better starting value than 0.0. |

551 | */ |

552 | extern void slv_check_dvar_initialization(slv_system_t sys); |

553 | /**< |

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

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

556 | a value of TRUE. |

557 | */ |

558 | |

559 | extern void slv_bnd_initialization(slv_system_t sys); |

560 | /**< |

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

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

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

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

565 | is initialized to FALSE. |

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

567 | function provided in bndman. |

568 | */ |

569 | |

570 | extern void slv_set_solvers_var_list(slv_system_t sys, |

571 | struct var_variable **vlist, |

572 | int size); |

573 | /**< |

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

575 | |

576 | @see slv_set_solvers_bnd_list() |

577 | **/ |

578 | extern void slv_set_solvers_par_list(slv_system_t sys, |

579 | struct var_variable **vlist, |

580 | int size); |

581 | /**< |

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

583 | |

584 | @see slv_set_solvers_bnd_list() |

585 | */ |

586 | extern void slv_set_solvers_unattached_list(slv_system_t sys, |

587 | struct var_variable **vlist, |

588 | int size); |

589 | /**< |

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

591 | |

592 | @see slv_set_solvers_bnd_list() |

593 | */ |

594 | |

595 | extern void slv_set_solvers_dvar_list(slv_system_t sys, |

596 | struct dis_discrete **dvlist, |

597 | int size); |

598 | /**< |

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

600 | |

601 | @see slv_set_solvers_bnd_list() |

602 | */ |

603 | |

604 | extern void slv_set_solvers_disunatt_list(slv_system_t sys, |

605 | struct dis_discrete **dvlist, |

606 | int size); |

607 | /**< |

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

609 | |

610 | @see slv_set_solvers_bnd_list() |

611 | */ |

612 | |

613 | extern void slv_set_solvers_rel_list(slv_system_t sys, |

614 | struct rel_relation **rlist, |

615 | int size); |

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

617 | |

618 | @see slv_set_solvers_bnd_list() |

619 | */ |

620 | |

621 | extern void slv_set_solvers_condrel_list(slv_system_t sys, |

622 | struct rel_relation **clist, |

623 | int size); |

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

625 | @see slv_set_solvers_bnd_list() |

626 | */ |

627 | |

628 | extern void slv_set_solvers_obj_list(slv_system_t sys, |

629 | struct rel_relation **rlist, |

630 | int size); |

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

632 | @see slv_set_solvers_bnd_list() |

633 | */ |

634 | |

635 | extern void slv_set_solvers_logrel_list(slv_system_t sys, |

636 | struct logrel_relation **lrlist, |

637 | int size); |

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

639 | @see slv_set_solvers_bnd_list() |

640 | */ |

641 | |

642 | extern void slv_set_solvers_condlogrel_list(slv_system_t sys, |

643 | struct logrel_relation **lrlist, |

644 | int size); |

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

646 | @see slv_set_solvers_bnd_list() |

647 | */ |

648 | |

649 | extern void slv_set_solvers_when_list(slv_system_t sys, |

650 | struct w_when **wlist, |

651 | int size); |

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

653 | @see slv_set_solvers_bnd_list() |

654 | */ |

655 | |

656 | extern void slv_set_solvers_bnd_list(slv_system_t sys, |

657 | struct bnd_boundary **blist, |

658 | int size); |

659 | /**< |

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

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

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

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

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

665 | |

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

667 | of the list EXCLUDING the terminal NULL. |

668 | |

669 | @NOTE |

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

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

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

673 | solver needs to know about. |

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

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

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

677 | */ |

678 | |

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

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

681 | @see slv_get_master_disunatt_list() |

682 | */ |

683 | |

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

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

686 | @see slv_get_master_disunatt_list() |

687 | */ |

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

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

690 | @see slv_get_master_disunatt_list() |

691 | */ |

692 | |

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

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

695 | @see slv_get_master_disunatt_list() |

696 | */ |

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

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

699 | @see slv_get_master_disunatt_list() |

700 | */ |

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

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

703 | @see slv_get_master_disunatt_list() |

704 | */ |

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

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

707 | @see slv_get_master_disunatt_list() |

708 | */ |

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

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

711 | @see slv_get_master_disunatt_list() |

712 | */ |

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

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

715 | @see slv_get_master_disunatt_list() |

716 | */ |

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

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

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

720 | |

721 | @NOTE |

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

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

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

725 | solver needs to know about. |

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

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

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

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

730 | |

731 | Parameters are problem invariant constants that the GUI |

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

733 | same MODEL. |

734 | */ |

735 | |

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

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

738 | |

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

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

741 | |

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

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

744 | |

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

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

747 | |

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

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

750 | |

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

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

753 | |

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

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

756 | |

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

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

759 | |

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

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

762 | |

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

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

765 | |

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

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

768 | |

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

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

771 | |

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

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

774 | |

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

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

777 | |

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

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

780 | |

781 | extern int32 slv_need_consistency(slv_system_t sys); |

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

783 | |

784 | extern int32 slv_get_num_solvers_vars(slv_system_t sys); |

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

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

787 | */ |

788 | |

789 | extern int32 slv_get_num_solvers_pars(slv_system_t sys); |

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

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

792 | */ |

793 | |

794 | extern int32 slv_get_num_solvers_unattached(slv_system_t sys); |

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

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

797 | */ |

798 | |

799 | extern int32 slv_get_num_solvers_dvars(slv_system_t sys); |

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

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

802 | */ |

803 | |

804 | extern int32 slv_get_num_solvers_disunatt(slv_system_t sys); |

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

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

807 | */ |

808 | |

809 | extern int32 slv_get_num_solvers_rels(slv_system_t sys); |

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

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

812 | */ |

813 | |

814 | extern int32 slv_get_num_solvers_condrels(slv_system_t sys); |

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

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

817 | */ |

818 | |

819 | extern int32 slv_get_num_solvers_objs(slv_system_t sys); |

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

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

822 | */ |

823 | |

824 | extern int32 slv_get_num_solvers_logrels(slv_system_t sys); |

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

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

827 | */ |

828 | |

829 | extern int32 slv_get_num_solvers_condlogrels(slv_system_t sys); |

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

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

832 | */ |

833 | |

834 | extern int32 slv_get_num_solvers_whens(slv_system_t sys); |

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

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

837 | */ |

838 | |

839 | extern int32 slv_get_num_solvers_bnds(slv_system_t sys); |

840 | /**< |

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

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

843 | **/ |

844 | extern int32 slv_get_num_master_vars(slv_system_t sys); |

845 | /**< |

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

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

848 | **/ |

849 | extern int32 slv_get_num_master_pars(slv_system_t sys); |

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

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

852 | */ |

853 | |

854 | extern int32 slv_get_num_master_unattached(slv_system_t sys); |

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

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

857 | */ |

858 | |

859 | extern int32 slv_get_num_master_dvars(slv_system_t sys); |

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

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

862 | */ |

863 | |

864 | extern int32 slv_get_num_master_disunatt(slv_system_t sys); |

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

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

867 | */ |

868 | |

869 | extern int32 slv_get_num_master_rels(slv_system_t sys); |

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

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

872 | */ |

873 | |

874 | extern int32 slv_get_num_master_condrels(slv_system_t sys); |

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

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

877 | */ |

878 | |

879 | extern int32 slv_get_num_master_objs(slv_system_t sys); |

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

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

882 | */ |

883 | |

884 | extern int32 slv_get_num_master_logrels(slv_system_t sys); |

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

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

887 | */ |

888 | |

889 | extern int32 slv_get_num_master_condlogrels(slv_system_t sys); |

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

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

892 | */ |

893 | |

894 | extern int32 slv_get_num_master_whens(slv_system_t sys); |

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

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

897 | */ |

898 | |

899 | extern int32 slv_get_num_master_bnds(slv_system_t sys); |

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

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

902 | */ |

903 | |

904 | extern int32 slv_get_num_models(slv_system_t sys); |

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

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

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

908 | */ |

909 | |

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

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

912 | |

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

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

915 | |

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

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

918 | |

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

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

921 | |

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

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

924 | |

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

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

927 | |

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

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

930 | |

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

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

933 | |

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

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

936 | |

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

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

939 | |

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

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

942 | |

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

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

945 | |

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

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

948 | |

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

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

951 | |

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

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

954 | |

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

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

957 | |

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

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

960 | |

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

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

963 | |

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

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

966 | |

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

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

969 | |

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

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

972 | |

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

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

975 | |

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

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

978 | |

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

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

981 | |

982 | /** @file slv_client.h |

983 | @NOTE |

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

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

986 | function for the list in question. |

987 | */ |

988 | |

989 | |

990 | /*----------------------------------------------------------------------- |

991 | Registered client queries. |

992 | */ |

993 | |

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

995 | /**< |

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

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

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

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

1000 | */ |

1001 | |

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

1003 | /**< |

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

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

1006 | |

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

1008 | */ |

1009 | |

1010 | extern void slv_set_obj_variable(slv_system_t sys, |

1011 | struct var_variable *objvar, |

1012 | unsigned maximize); |

1013 | /**< |

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

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

1016 | complete insanity may result. |

1017 | |

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

1019 | Client solvers should minimize this variable. |

1020 | |

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

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

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

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

1025 | relation if the var is defined. |

1026 | */ |

1027 | |

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

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

1030 | |

1031 | extern real64 slv_get_obj_variable_gradient(slv_system_t sys); |

1032 | /**< |

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

1034 | if no var is set. |

1035 | */ |

1036 | |

1037 | extern int slv_eligible_solver(slv_system_t sys); |

1038 | /**< |

1039 | Determines whether or not the current solver. |

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

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

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

1043 | return value may be misleading. @par |

1044 | |

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

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

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

1048 | */ |

1049 | |

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

1051 | /**< |

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

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

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

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

1056 | will be blown away. |

1057 | |

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

1059 | */ |

1060 | |

1061 | extern int slv_get_selected_solver(slv_system_t sys); |

1062 | /**< |

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

1064 | */ |

1065 | |

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

1067 | /**< |

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

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

1070 | If failure, return is -1; |

1071 | */ |

1072 | |

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

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

1075 | |

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

1077 | /**< |

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

1079 | |

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

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

1082 | */ |

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

1084 | /**< |

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

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

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

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

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

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

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

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

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

1094 | |

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

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

1097 | */ |

1098 | |

1099 | extern SlvClientToken slv_get_client_token(slv_system_t sys); |

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

1101 | |

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

1103 | /**< |

1104 | Sets the client token of the system_t. |

1105 | */ |

1106 | |

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

1108 | /**< |

1109 | Sets the solver index of the slv_system_t. |

1110 | */ |

1111 | |

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

1113 | /**< |

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

1115 | */ |

1116 | |

1117 | extern linsolqr_system_t slv_get_linsolqr_sys(slv_system_t sys); |

1118 | /**< |

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

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

1121 | */ |

1122 | |

1123 | extern linsol_system_t slv_get_linsol_sys(slv_system_t sys); |

1124 | /**< |

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

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

1127 | */ |

1128 | |

1129 | extern mtx_matrix_t slv_get_sys_mtx(slv_system_t sys); |

1130 | /**< |

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

1132 | |

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

1134 | **/ |

1135 | |

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

1137 | /**< |

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

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

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

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

1142 | principally to facilitate debugging a little. |

1143 | |

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

1145 | */ |

1146 | |

1147 | extern void slv_presolve(slv_system_t sys); |

1148 | /**< |

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

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

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

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

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

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

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

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

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

1158 | |

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

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

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

1162 | it is received. @par |

1163 | |

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

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

1166 | */ |

1167 | |

1168 | extern void slv_resolve(slv_system_t sys); |

1169 | /**< |

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

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

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

1173 | since are as follows: |

1174 | |

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

1176 | @li variable values. |

1177 | @li variable nominal values. |

1178 | @li variable bounds. |

1179 | |

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

1181 | |

1182 | @li variable fixed flag. |

1183 | @li relation included flag. |

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

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

1186 | the list. |

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

1188 | including structural rearrangement on relations, although any |

1189 | expression may be simplified. |

1190 | |

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

1192 | */ |

1193 | |

1194 | extern void slv_iterate(slv_system_t sys); |

1195 | /**< |

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

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

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

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

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

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

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

1203 | */ |

1204 | |

1205 | extern void slv_solve(slv_system_t sys); |

1206 | /**< |

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

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

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

1210 | */ |

1211 | |

1212 | extern void slv_destroy_client(slv_system_t sys); |

1213 | /**< |

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

1215 | the allocated data space of sys |

1216 | */ |

1217 | |

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

1219 | /**< |

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

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

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

1223 | won't do it. |

1224 | |

1225 | @deprecated THIS CALL SHOULD GO AWAY |

1226 | */ |

1227 | |

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

1229 | /**< |

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

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

1232 | |

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

1234 | */ |

1235 | |

1236 | #endif /* ASC_SLV_CLIENT_H */ |

1237 |

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

Powered by ViewVC 1.1.22 |