Parent Directory | Revision Log

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

*Wed Apr 19 02:44:25 2006 UTC*
(13 years, 11 months ago)
by *johnpye*

File MIME type: text/x-chdr

File size: 50512 byte(s)

File MIME type: text/x-chdr

File size: 50512 byte(s)

Fixing for ubuntu GCC 4

1 | /* ASCEND modelling environment |

2 | Copyright (C) 1990 Karl Michael Westerberg |

3 | Copyright (C) 1993 Joseph Zaher |

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

5 | Copyright (C) 1996 Benjamin Andrew Allan |

6 | Copyright (C) 2005-2006 Carnegie Mellon University |

7 | Copyright (C) 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, or (at your option) |

12 | 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., 59 Temple Place - Suite 330, |

22 | Boston, MA 02111-1307, USA. |

23 | *//** |

24 | @file |

25 | @see slv |

26 | |

27 | Requires: |

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

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

30 | #include "solver/var.h" |

31 | #include "solver/rel.h" |

32 | #include "solver/discrete.h" |

33 | #include "solver/conditional.h" |

34 | #include "solver/logrel.h" |

35 | #include "solver/bnd.h" |

36 | #include "solver/linsol.h" |

37 | #include "solver/linsolqr.h" |

38 | #include "solver/slv_common.h" |

39 | #include "solver/slv_types.h" |

40 | ... some mtx.h files required as well? |

41 | *//** |

42 | @page slv SLV Solver Interface |

43 | |

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

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

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

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

48 | problem as they want. @par |

49 | |

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

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

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

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

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

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

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

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

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

59 | |

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

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

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

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

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

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

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

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

68 | solver. @par |

69 | |

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

71 | |

72 | <pre> |

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

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

75 | and rel_to_name function pointers, and |

76 | expanded status report |

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

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

79 | boundaries, and relations which pass some |

80 | specified filter |

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

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

83 | slv_common.h. BAA |

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

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

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

87 | </pre> |

88 | |

89 | @section desc Description |

90 | |

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

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

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

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

95 | problems only): |

96 | |

97 | @code |

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

99 | |

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

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

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

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

104 | @endcode |

105 | |

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

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

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

109 | equality constraints (h), conditional equality |

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

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

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

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

114 | expressed through a set of inequality boundary relations |

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

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

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

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

119 | |

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

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

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

123 | relation lists are pointer lists of |

124 | struct var_variable * and struct rel_relation * and |

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

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

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

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

129 | |

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

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

132 | information displayed during solving, for example. |

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

134 | status report for solvers that iterate. |

135 | More details are given with the |

136 | respective declarations below. @par |

137 | |

138 | @section arch Architecture |

139 | |

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

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

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

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

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

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

146 | |

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

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

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

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

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

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

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

154 | |

155 | Haha :-) $1/MB! Jan 2006: 118 AUD = 512 MB = ~ 0.15 USD/MB -- johnpye |

156 | |

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

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

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

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

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

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

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

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

165 | or services. |

166 | |

167 | @section faq FAQ |

168 | |

169 | @subsection whatisvar What is a variable? |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

186 | |

187 | @subsection whatisrel What is a relation? |

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

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

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

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

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

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

194 | - residual and gradient calculations |

195 | - symbolic inversion (where possible) |

196 | - numeric root finding |

197 | - scaling based on symbolic arguments |

198 | - symbolic determination of linearity |

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

200 | them. |

201 | |

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

219 | your client: |

220 | - Degrees of freedom analysis. |

221 | - Problem decomposition. |

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

223 | - Solution of square nonlinear systems. |

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

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

226 | extremely awkward modeling language that does happen to |

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

228 | |

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

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

231 | solvers designed to handle only 1 block. |

232 | |

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

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

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

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

237 | care to think about such things directly. |

238 | |

239 | @NOTE |

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

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

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

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

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

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

246 | */ |

247 | |

248 | #ifndef ASC_SLV_CLIENT_H |

249 | #define ASC_SLV_CLIENT_H |

250 | |

251 | #include <utilities/ascConfig.h> |

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 | ASC_DLLSPEC(int) g_SlvNumberOfRegisteredClients; |

289 | |

290 | /**< |

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

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

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

294 | the functions it defines. |

295 | */ |

296 | |

297 | #define SLVMAXCLIENTS 100 |

298 | /**< |

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

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

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

302 | and the like. |

303 | */ |

304 | |

305 | /*----------------------------------------------------------------------- |

306 | Type declarations for registered client functions |

307 | */ |

308 | |

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

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

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

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

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

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

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

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

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

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

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

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

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

322 | |

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

324 | @TODO Complete documentation of slv_registration_data members. |

325 | */ |

326 | typedef struct slv_registration_data { |

327 | int number; |

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

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

330 | |

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

332 | /* |

333 | Required functions |

334 | */ |

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

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

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

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

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

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

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

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

343 | /* |

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

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

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

347 | Redesign your bloody batch code. |

348 | */ |

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

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

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

352 | /** |

353 | Strictly Optional Functions |

354 | */ |

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

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

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

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

359 | } SlvFunctionsT; |

360 | |

361 | |

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

363 | /**< |

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

365 | |

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

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

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

369 | |

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

371 | |

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

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

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

375 | |

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

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

378 | incompetent solver was registered. |

379 | */ |

380 | |

381 | ASC_DLLSPEC(int) slv_lookup_client( const char *solverName ); |

382 | /**< |

383 | *** Examples: @code |

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

385 | *** slv_register_client(...) |

386 | *** } |

387 | *** @endcode |

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

389 | **/ |

390 | |

391 | ASC_DLLSPEC(int) slv_register_client(SlvRegistration slv0_register |

392 | ,CONST char *yourregisterfuncname |

393 | ,CONST char *yourbinaryname |

394 | ,int *new_client_id); |

395 | /**< |

396 | Examples: @code |

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

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

399 | @endcode |

400 | |

401 | Call this function with the SlvRegistration function |

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

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

404 | a solver. @par |

405 | |

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

407 | |

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

409 | */ |

410 | |

411 | ASC_DLLSPEC(const char*) slv_solver_name(int index); |

412 | /**< |

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

414 | @return name of the solver |

415 | |

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

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

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

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

420 | |

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

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

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

424 | of name-number pair. |

425 | */ |

426 | |

427 | extern int Solv_C_CheckHalt_Flag; |

428 | /**< |

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

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

431 | |

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

433 | */ |

434 | |

435 | extern int Solv_C_CheckHalt(void); |

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

437 | |

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

439 | |

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

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

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

443 | |

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

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

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

447 | */ |

448 | |

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

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

451 | |

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

453 | |

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

455 | */ |

456 | |

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

458 | /**< |

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

460 | |

461 | @see slv_get_log_dofdata(). |

462 | **/ |

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

464 | /**< |

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

466 | Data in the structure should be consistent with |

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

468 | The pointer this returns cannot be freed. |

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

470 | |

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

472 | */ |

473 | |

474 | ASC_DLLSPEC(const mtx_block_t*) slv_get_solvers_blocks(slv_system_t sys); |

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

476 | |

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

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

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

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

481 | |

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

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

484 | order given in the list. @par |

485 | |

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

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

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

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

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

491 | rectangular. |

492 | |

493 | @see slv_get_solvers_log_blocks() |

494 | */ |

495 | |

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

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

498 | |

499 | @param sys system being analysed. |

500 | |

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

502 | |

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

504 | our equation gradients to suit any factorization method |

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

506 | |

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

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

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

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

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

512 | |

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

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

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

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

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

518 | block structure completely. @par |

519 | |

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

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

522 | be NULL. |

523 | */ |

524 | |

525 | extern void slv_set_solvers_blocks(slv_system_t sys, |

526 | int32 len, |

527 | mtx_region_t *data); |

528 | /**< |

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

530 | given which should be of length len. |

531 | |

532 | @see slv_set_solvers_log_blocks() |

533 | */ |

534 | extern void slv_set_solvers_log_blocks(slv_system_t sys, |

535 | int32 len, |

536 | mtx_region_t *data); |

537 | /**< |

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

539 | given which should be of length len. |

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

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

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

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

544 | */ |

545 | |

546 | extern void slv_check_var_initialization(slv_system_t sys); |

547 | /**< |

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

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

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

551 | much better starting value than 0.0. |

552 | */ |

553 | extern void slv_check_dvar_initialization(slv_system_t sys); |

554 | /**< |

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

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

557 | a value of TRUE. |

558 | */ |

559 | |

560 | extern void slv_bnd_initialization(slv_system_t sys); |

561 | /**< |

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

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

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

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

566 | is initialized to FALSE. |

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

568 | function provided in bndman. |

569 | */ |

570 | |

571 | extern void slv_set_solvers_var_list(slv_system_t sys, |

572 | struct var_variable **vlist, |

573 | int size); |

574 | /**< |

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

576 | |

577 | @see slv_set_solvers_bnd_list() |

578 | **/ |

579 | extern void slv_set_solvers_par_list(slv_system_t sys, |

580 | struct var_variable **vlist, |

581 | int size); |

582 | /**< |

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

584 | |

585 | @see slv_set_solvers_bnd_list() |

586 | */ |

587 | extern void slv_set_solvers_unattached_list(slv_system_t sys, |

588 | struct var_variable **vlist, |

589 | int size); |

590 | /**< |

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

592 | |

593 | @see slv_set_solvers_bnd_list() |

594 | */ |

595 | |

596 | extern void slv_set_solvers_dvar_list(slv_system_t sys, |

597 | struct dis_discrete **dvlist, |

598 | int size); |

599 | /**< |

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

601 | |

602 | @see slv_set_solvers_bnd_list() |

603 | */ |

604 | |

605 | extern void slv_set_solvers_disunatt_list(slv_system_t sys, |

606 | struct dis_discrete **dvlist, |

607 | int size); |

608 | /**< |

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

610 | |

611 | @see slv_set_solvers_bnd_list() |

612 | */ |

613 | |

614 | extern void slv_set_solvers_rel_list(slv_system_t sys, |

615 | struct rel_relation **rlist, |

616 | int size); |

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

618 | |

619 | @see slv_set_solvers_bnd_list() |

620 | */ |

621 | |

622 | extern void slv_set_solvers_condrel_list(slv_system_t sys, |

623 | struct rel_relation **clist, |

624 | int size); |

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

626 | @see slv_set_solvers_bnd_list() |

627 | */ |

628 | |

629 | extern void slv_set_solvers_obj_list(slv_system_t sys, |

630 | struct rel_relation **rlist, |

631 | int size); |

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

633 | @see slv_set_solvers_bnd_list() |

634 | */ |

635 | |

636 | extern void slv_set_solvers_logrel_list(slv_system_t sys, |

637 | struct logrel_relation **lrlist, |

638 | int size); |

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

640 | @see slv_set_solvers_bnd_list() |

641 | */ |

642 | |

643 | extern void slv_set_solvers_condlogrel_list(slv_system_t sys, |

644 | struct logrel_relation **lrlist, |

645 | int size); |

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

647 | @see slv_set_solvers_bnd_list() |

648 | */ |

649 | |

650 | extern void slv_set_solvers_when_list(slv_system_t sys, |

651 | struct w_when **wlist, |

652 | int size); |

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

654 | @see slv_set_solvers_bnd_list() |

655 | */ |

656 | |

657 | extern void slv_set_solvers_bnd_list(slv_system_t sys, |

658 | struct bnd_boundary **blist, |

659 | int size); |

660 | /**< |

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

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

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

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

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

666 | |

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

668 | of the list EXCLUDING the terminal NULL. |

669 | |

670 | @NOTE |

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

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

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

674 | solver needs to know about. |

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

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

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

678 | */ |

679 | |

680 | ASC_DLLSPEC(struct var_variable**) slv_get_solvers_var_list(slv_system_t sys); |

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

682 | @see slv_get_master_disunatt_list() |

683 | */ |

684 | |

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

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

687 | @see slv_get_master_disunatt_list() |

688 | */ |

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

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

691 | @see slv_get_master_disunatt_list() |

692 | */ |

693 | |

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

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

696 | @see slv_get_master_disunatt_list() |

697 | */ |

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

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

700 | @see slv_get_master_disunatt_list() |

701 | */ |

702 | ASC_DLLSPEC(struct var_variable **) slv_get_master_var_list(slv_system_t sys); |

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

704 | @see slv_get_master_disunatt_list() |

705 | */ |

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

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

708 | @see slv_get_master_disunatt_list() |

709 | */ |

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

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

712 | @see slv_get_master_disunatt_list() |

713 | */ |

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

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

716 | @see slv_get_master_disunatt_list() |

717 | */ |

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

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

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

721 | |

722 | @NOTE |

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

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

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

726 | solver needs to know about. |

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

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

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

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

731 | |

732 | Parameters are problem invariant constants that the GUI |

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

734 | same MODEL. |

735 | */ |

736 | |

737 | ASC_DLLSPEC(struct rel_relation**) slv_get_solvers_rel_list(slv_system_t sys); |

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

739 | |

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

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

742 | |

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

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

745 | |

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

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

748 | |

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

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

751 | |

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

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

754 | |

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

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

757 | |

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

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

760 | |

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

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

763 | |

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

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

766 | |

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

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

769 | |

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

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

772 | |

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

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

775 | |

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

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

778 | |

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

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

781 | |

782 | extern int32 slv_need_consistency(slv_system_t sys); |

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

784 | |

785 | ASC_DLLSPEC(int32) slv_get_num_solvers_vars(slv_system_t sys); |

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

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

788 | */ |

789 | |

790 | extern int32 slv_get_num_solvers_pars(slv_system_t sys); |

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

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

793 | */ |

794 | |

795 | extern int32 slv_get_num_solvers_unattached(slv_system_t sys); |

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

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

798 | */ |

799 | |

800 | extern int32 slv_get_num_solvers_dvars(slv_system_t sys); |

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

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

803 | */ |

804 | |

805 | extern int32 slv_get_num_solvers_disunatt(slv_system_t sys); |

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

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

808 | */ |

809 | |

810 | extern int32 slv_get_num_solvers_rels(slv_system_t sys); |

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

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

813 | */ |

814 | |

815 | extern int32 slv_get_num_solvers_condrels(slv_system_t sys); |

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

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

818 | */ |

819 | |

820 | extern int32 slv_get_num_solvers_objs(slv_system_t sys); |

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

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

823 | */ |

824 | |

825 | extern int32 slv_get_num_solvers_logrels(slv_system_t sys); |

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

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

828 | */ |

829 | |

830 | extern int32 slv_get_num_solvers_condlogrels(slv_system_t sys); |

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

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

833 | */ |

834 | |

835 | extern int32 slv_get_num_solvers_whens(slv_system_t sys); |

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

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

838 | */ |

839 | |

840 | extern int32 slv_get_num_solvers_bnds(slv_system_t sys); |

841 | /**< |

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

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

844 | **/ |

845 | extern int32 slv_get_num_master_vars(slv_system_t sys); |

846 | /**< |

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

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

849 | **/ |

850 | extern int32 slv_get_num_master_pars(slv_system_t sys); |

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

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

853 | */ |

854 | |

855 | extern int32 slv_get_num_master_unattached(slv_system_t sys); |

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

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

858 | */ |

859 | |

860 | extern int32 slv_get_num_master_dvars(slv_system_t sys); |

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

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

863 | */ |

864 | |

865 | extern int32 slv_get_num_master_disunatt(slv_system_t sys); |

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

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

868 | */ |

869 | |

870 | extern int32 slv_get_num_master_rels(slv_system_t sys); |

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

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

873 | */ |

874 | |

875 | extern int32 slv_get_num_master_condrels(slv_system_t sys); |

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

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

878 | */ |

879 | |

880 | extern int32 slv_get_num_master_objs(slv_system_t sys); |

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

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

883 | */ |

884 | |

885 | extern int32 slv_get_num_master_logrels(slv_system_t sys); |

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

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

888 | */ |

889 | |

890 | extern int32 slv_get_num_master_condlogrels(slv_system_t sys); |

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

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

893 | */ |

894 | |

895 | extern int32 slv_get_num_master_whens(slv_system_t sys); |

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

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

898 | */ |

899 | |

900 | extern int32 slv_get_num_master_bnds(slv_system_t sys); |

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

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

903 | */ |

904 | |

905 | extern int32 slv_get_num_models(slv_system_t sys); |

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

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

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

909 | */ |

910 | |

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

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

913 | |

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

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

916 | |

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

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

919 | |

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

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

922 | |

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

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

925 | |

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

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

928 | |

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

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

931 | |

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

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

934 | |

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

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

937 | |

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

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

940 | |

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

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

943 | |

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

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

946 | |

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

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

949 | |

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

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

952 | |

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

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

955 | |

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

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

958 | |

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

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

961 | |

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

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

964 | |

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

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

967 | |

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

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

970 | |

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

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

973 | |

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

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

976 | |

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

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

979 | |

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

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

982 | |

983 | /** @file slv_client.h |

984 | @NOTE |

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

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

987 | function for the list in question. |

988 | */ |

989 | |

990 | |

991 | /*----------------------------------------------------------------------- |

992 | Registered client queries. |

993 | */ |

994 | |

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

996 | /**< |

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

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

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

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

1001 | */ |

1002 | |

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

1004 | /**< |

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

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

1007 | |

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

1009 | */ |

1010 | |

1011 | extern void slv_set_obj_variable(slv_system_t sys, |

1012 | struct var_variable *objvar, |

1013 | unsigned maximize); |

1014 | /**< |

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

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

1017 | complete insanity may result. |

1018 | |

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

1020 | Client solvers should minimize this variable. |

1021 | |

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

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

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

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

1026 | relation if the var is defined. |

1027 | */ |

1028 | |

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

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

1031 | |

1032 | extern real64 slv_get_obj_variable_gradient(slv_system_t sys); |

1033 | /**< |

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

1035 | if no var is set. |

1036 | */ |

1037 | |

1038 | ASC_DLLSPEC(int) slv_eligible_solver(slv_system_t sys); |

1039 | /**< |

1040 | Determines whether or not the current solver. |

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

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

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

1044 | return value may be misleading. @par |

1045 | |

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

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

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

1049 | */ |

1050 | |

1051 | ASC_DLLSPEC(int) slv_select_solver(slv_system_t sys, int solver); |

1052 | /**< |

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

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

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

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

1057 | will be blown away. |

1058 | |

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

1060 | */ |

1061 | |

1062 | ASC_DLLSPEC(int) slv_get_selected_solver(slv_system_t sys); |

1063 | /**< |

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

1065 | */ |

1066 | |

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

1068 | /**< |

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

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

1071 | If failure, return is -1; |

1072 | */ |

1073 | |

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

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

1076 | |

1077 | ASC_DLLSPEC(void) slv_get_parameters(slv_system_t sys, slv_parameters_t *parameters); |

1078 | /**< |

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

1080 | |

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

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

1083 | */ |

1084 | ASC_DLLSPEC(void) slv_set_parameters(slv_system_t sys, slv_parameters_t *parameters); |

1085 | /**< |

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

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

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

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

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

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

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

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

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

1095 | |

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

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

1098 | */ |

1099 | |

1100 | extern SlvClientToken slv_get_client_token(slv_system_t sys); |

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

1102 | |

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

1104 | /**< |

1105 | Sets the client token of the system_t. |

1106 | */ |

1107 | |

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

1109 | /**< |

1110 | Sets the solver index of the slv_system_t. |

1111 | */ |

1112 | |

1113 | ASC_DLLSPEC(void) slv_get_status(slv_system_t sys, slv_status_t *status); |

1114 | /**< |

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

1116 | */ |

1117 | |

1118 | extern linsolqr_system_t slv_get_linsolqr_sys(slv_system_t sys); |

1119 | /**< |

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

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

1122 | */ |

1123 | |

1124 | extern linsol_system_t slv_get_linsol_sys(slv_system_t sys); |

1125 | /**< |

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

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

1128 | */ |

1129 | |

1130 | extern mtx_matrix_t slv_get_sys_mtx(slv_system_t sys); |

1131 | /**< |

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

1133 | |

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

1135 | **/ |

1136 | |

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

1138 | /**< |

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

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

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

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

1143 | principally to facilitate debugging a little. |

1144 | |

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

1146 | */ |

1147 | |

1148 | ASC_DLLSPEC(void) slv_presolve(slv_system_t sys); |

1149 | /**< |

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

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

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

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

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

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

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

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

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

1159 | |

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

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

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

1163 | it is received. @par |

1164 | |

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

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

1167 | */ |

1168 | |

1169 | extern void slv_resolve(slv_system_t sys); |

1170 | /**< |

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

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

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

1174 | since are as follows: |

1175 | |

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

1177 | @li variable values. |

1178 | @li variable nominal values. |

1179 | @li variable bounds. |

1180 | |

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

1182 | |

1183 | @li variable fixed flag. |

1184 | @li relation included flag. |

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

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

1187 | the list. |

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

1189 | including structural rearrangement on relations, although any |

1190 | expression may be simplified. |

1191 | |

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

1193 | */ |

1194 | |

1195 | ASC_DLLSPEC(void) slv_iterate(slv_system_t sys); |

1196 | /**< |

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

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

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

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

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

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

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

1204 | */ |

1205 | |

1206 | extern void slv_solve(slv_system_t sys); |

1207 | /**< |

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

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

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

1211 | */ |

1212 | |

1213 | extern void slv_destroy_client(slv_system_t sys); |

1214 | /**< |

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

1216 | the allocated data space of sys |

1217 | */ |

1218 | |

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

1220 | /**< |

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

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

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

1224 | won't do it. |

1225 | |

1226 | @deprecated THIS CALL SHOULD GO AWAY |

1227 | */ |

1228 | |

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

1230 | /**< |

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

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

1233 | |

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

1235 | */ |

1236 | |

1237 | #endif /* ASC_SLV_CLIENT_H */ |

1238 |

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

Powered by ViewVC 1.1.22 |