1 /* Siconos is a program dedicated to modeling, simulation and 2 * of non smooth dynamical systems. 3 * 4 * Copyright 2021 INRIA. 5 * 6 * Licensed under the Apache License, Version 2.0 (the "License"); 7 * you may not use this file except in compliance with the License. 8 * You may obtain a copy of the License at 9 * 10 * http://www.apache.org/licenses/LICENSE-2.0 11 * 12 * Unless required by applicable law or agreed to in writing, software 13 * distributed under the License is distributed on an "AS IS" BASIS, 14 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 15 * See the License for the specific language governing permissions and 16 * limitations under the License. 17 */ 18 #ifndef SolverOptions_H 19 #define SolverOptions_H 20 21 /*!\file SolverOptions.h 22 Structure used to send options (name, parameters and so on) to a specific solver-driver (mainly from Kernel to Numerics). 23 */ 24 #include <stdio.h> // for size_t 25 #include <stdbool.h> // for boolean type 26 #include "SiconosConfig.h" // for BUILD_AS_CPP // IWYU pragma: keep 27 #include "NumericsFwd.h" // for SolverOptions 28 29 /** \struct Callback SolverOptions.h 30 Structure used to store user callbacks inside solvers 31 */ 32 typedef struct 33 { 34 void *env; /**< general user environment */ 35 void (*collectStatsIteration)(void *env, int size, double*reaction, 36 double*velocity, double error, void* extra_data);/**< pointer on a function 37 * Its signature is: user env, problem size, reaction, 38 * velocity, error at end of solver iteration (when this makes sense) and an 39 * extra data structure */ 40 } Callback; 41 42 43 // length of iparam/dparam arrays in solver options. 44 #define OPTIONS_PARAM_SIZE 20 45 46 /** \struct SolverOptions_ SolverOptions.h 47 Structure used to send options (name, parameters and so on) to a specific solver (mainly from Kernel to Numerics). 48 49 \rst 50 Creation, update and destruction: 51 52 :func:`solver_options_create` 53 54 :func:`solver_options_update_internal` 55 56 :func:`solver_options_delete` 57 58 Details: :ref:`solver_options` 59 \endrst 60 61 */ 62 struct SolverOptions 63 { 64 int solverId; /**< id number of the solver. */ 65 bool isSet; /**< true(1) if the structure is ready to be used by a numerics driver. */ 66 int iSize; /**< iSize size of vector iparam */ 67 int * iparam; /**< list of solver parameters (integer type); Check solvers doc for details. */ 68 int dSize; /**< size of vector dparam */ 69 double * dparam; /**< list of solver parameters (double type); Check solvers doc for details. */ 70 bool filterOn; /**< if true (1), check solution validity after the driver call. Default = 1. 71 For example if filterOn = 1 for a LCP, lcp_compute_error() 72 will be called at the end of the process). */ 73 size_t dWorkSize; /**< size of double type internal work array.*/ 74 double * dWork; /**< internal (double type) work array.*/ 75 size_t iWorkSize; /**< size of integer type internal work array.*/ 76 int * iWork; /**< internal (integer type) work array.*/ 77 size_t numberOfInternalSolvers; /**< the number of internal or local 'sub-solvers' used by the solver 78 (size of internalSolvers) .*/ 79 struct SolverOptions ** internalSolvers; /**< list of internal solver options*/ 80 Callback * callback; /**< pointer to user-defined callback*/ 81 void * solverParameters; /**< additional parameters specific to the solver (GAMS and NewtonMethod only) */ 82 void * solverData; /**< additional data specific to the solver */ 83 } ; 84 85 86 /** Some value for iparam index */ 87 enum SICONOS_IPARAM 88 { 89 SICONOS_IPARAM_MAX_ITER = 0, 90 SICONOS_IPARAM_ITER_DONE = 1, 91 SICONOS_IPARAM_PREALLOC = 2, 92 SICONOS_IPARAM_NSGS_SHUFFLE = 5, 93 SICONOS_IPARAM_ERROR_EVALUATION = 3, // CHECK IF THERE ARE NO CONFLICT WITH THIS !! 94 SICONOS_IPARAM_PATHSEARCH_STACKSIZE = 19 95 }; 96 97 /** allowed values for iparam[SICONOS_IPARAM_ERROR_EVALUATION */ 98 enum SICONOS_IPARAM_ERROR_EVALUATION_ENUM 99 { 100 /** Complete error computation, including v computation*/ 101 SICONOS_ERROR_FULL_EVALUATION = 0, 102 /** Light error computation with incremental values on r verification of absolute error at the end */ 103 SICONOS_ERROR_LIGHT_EVALUATION = 1, 104 /** only light error computation, do not update v unknown) */ 105 SICONOS_ERROR_LIGHT_EVALUATION_NO_UPDATE = 2 106 }; 107 108 109 /** Some values for dparam index */ 110 enum SICONOS_DPARAM 111 { 112 SICONOS_DPARAM_TOL = 0, 113 SICONOS_DPARAM_RESIDU = 1, 114 }; 115 116 #if defined(__cplusplus) && !defined(BUILD_AS_CPP) 117 extern "C" 118 { 119 #endif 120 121 /** screen display of solver parameters 122 \param options the structure to be displayed 123 */ 124 void solver_options_print(SolverOptions* options); 125 126 /** Clear and free all pointer members of the structure, then 127 release memory 128 \param options the structure to be cleared. 129 */ 130 void solver_options_delete(SolverOptions * options); 131 132 /** Create and initialize a SolverOptions struct: 133 allocate internal memories, set default values 134 depending on the id. 135 \param id solver id number 136 \rst 137 It must belong to one of the available ids defined for each formulation, 138 see :ref:`problems_and_solvers` for details. 139 \endrst 140 \return a pointer to options set, ready to use by a driver. 141 */ 142 SolverOptions * solver_options_create(int solverId); 143 144 /** Copy an existing set of options, to create a new one. 145 146 Warning : callback, solverData and solverParameters of 147 the new structure are pointer links to those of the original one! 148 149 \param source an existing solver options structure 150 \return a pointer to options set, ready to use by a driver. 151 */ 152 SolverOptions * solver_options_copy(SolverOptions* source); 153 154 /** Change one of the internal solver of a previously defined SolverOptions set. 155 156 Allocate internal memories and set default values for the internal solver. 157 158 Warning : the actual internal solver in position internal_solver_number and all its content will be destroyed 159 and replaced by a new one. 160 161 \param parent the top-level SolverOptions which contains the internal solver to be updated 162 \param internal_solver_number number of the internal solver to be update (warning : this is the position 163 in the list of internal solvers, not the id!) 164 \param solver_id id number of the new internal solver to be created/updated 165 */ 166 void solver_options_update_internal(SolverOptions* parent, size_t internal_solver_number, int solver_id); 167 168 /** return the id of a solver based on its name 169 * \param pName the name of the solver 170 * \return the id of the solver or 0 if it failed 171 */ 172 int solver_options_name_to_id(const char * pName); 173 174 /** return the name of a solver given its id 175 * \param Id the id of the solver 176 * \return the name of the solver 177 */ 178 const char * solver_options_id_to_name(int Id); 179 180 /** return the an internal solver options set 181 \param options parent options 182 \param number of the targeted solver 183 \return a pointer to the internal solver options set 184 */ 185 SolverOptions * solver_options_get_internal_solver(SolverOptions * options, size_t n); 186 187 /** set internal solver 188 \param options parent options 189 \param number of the targeted solver 190 \param the solver options to be used as internal solver number n 191 */ 192 void solver_options_set_internal_solver(SolverOptions * options, size_t n, SolverOptions* NSO); 193 194 #if defined(__cplusplus) && !defined(BUILD_AS_CPP) 195 } 196 #endif 197 198 199 200 #endif 201