1 //-------------------------------------------------------------------------- 2 // 3 // QUESO - a library to support the Quantification of Uncertainty 4 // for Estimation, Simulation and Optimization 5 // 6 // Copyright (C) 2008,2009,2010,2011,2012,2013 The PECOS Development Team 7 // 8 // This library is free software; you can redistribute it and/or 9 // modify it under the terms of the Version 2.1 GNU Lesser General 10 // Public License as published by the Free Software Foundation. 11 // 12 // This library is distributed in the hope that it will be useful, 13 // but WITHOUT ANY WARRANTY; without even the implied warranty of 14 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 15 // Lesser General Public License for more details. 16 // 17 // You should have received a copy of the GNU Lesser General Public 18 // License along with this library; if not, write to the Free Software 19 // Foundation, Inc. 51 Franklin Street, Fifth Floor, 20 // Boston, MA 02110-1301 USA 21 // 22 //-----------------------------------------------------------------------el- 23 24 #include <queso/Environment.h> 25 #include <queso/SharedPtr.h> 26 27 #ifndef QUESO_DISABLE_BOOST_PROGRAM_OPTIONS 28 #include <queso/BoostInputOptionsParser.h> 29 #include <queso/ScopedPtr.h> 30 #endif // QUESO_DISABLE_BOOST_PROGRAM_OPTIONS 31 32 #ifndef UQ_GPMSA_OPTIONS_H 33 #define UQ_GPMSA_OPTIONS_H 34 35 namespace QUESO { 36 37 template <typename V> 38 class SimulationOutputMesh; 39 40 /*! 41 * \file GPMSAOptions.h 42 * \brief This class defines the options that specify the behaviour of the Gaussian process emulator 43 * 44 * \class GPMSAOptions 45 * \brief This class defines the options that specify the behaviour of the Gaussian process emulator 46 */ 47 48 class GPMSAOptions 49 { 50 public: 51 //! Given prefix, read the input file for parameters named "prefix"+* 52 GPMSAOptions(const BaseEnvironment& env, const char* prefix); 53 54 //! Construct with default parameters 55 GPMSAOptions(); 56 57 //! Set parameter option names to begin with prefix 58 void set_prefix(const char* prefix); 59 60 //! Set default values for parameter options 61 void set_defaults(); 62 63 //! Given prefix, read the input file for parameters named "prefix"+* 64 void parse(const BaseEnvironment& env, const char* prefix); 65 66 //! Destructor 67 virtual ~GPMSAOptions(); 68 69 //! Prints \c this to \c os 70 void print(std::ostream& os) const; 71 72 //! The prefix to look for in the input file 73 std::string m_prefix; 74 75 //! If this string is non-empty, print the options object to the output file 76 std::string m_help; 77 78 //! The maximum number of basis vectors to use for approximating 79 // emulator output. If this number is set to be zero (as it is by 80 // default), then the number of basis vectors will be determined at 81 // run time to preserve some minimum fraction of the variance in 82 // simulation output. 83 int m_maxEmulatorBasisVectors; 84 85 //! The minimum fraction of the variance in simulation output to 86 // capture with the emulator basis. By default this is 1.0, i.e. 87 // 100%, in which case there will be one basis vector for each 88 // dimension in the simulation output space. 89 // 90 // Currently the only supported value is 1.0 91 double m_emulatorBasisVarianceToCapture; 92 93 //! Do automatic normalization, using minimum and maximum values in 94 // the supplied simulator data, for uncertain parameter i. 95 // 96 // Normalized values will range from 0 to 1. 97 void set_autoscale_minmax_uncertain_parameter(unsigned int i); 98 99 //! Do automatic normalization, using minimum and maximum values in 100 // the supplied simulator data, for scenario parameter i. 101 // 102 // Normalized values will range from 0 to 1. 103 void set_autoscale_minmax_scenario_parameter(unsigned int i); 104 105 //! Do automatic normalization, using minimum and maximum values in 106 // the supplied simulator data, for output variable i. Note that, 107 // if functional data exists, variable i will *not* be the same as 108 // index i. 109 // 110 // Normalized values will range from 0 to 1. 111 void set_autoscale_minmax_output(unsigned int i); 112 113 //! Do automatic normalization, using minimum and maximum values in 114 // the supplied simulator data, for all input uncertain parameters, 115 // all input scenario parameters, and all output values. 116 // 117 // Normalized values will range from 0 to 1. 118 void set_autoscale_minmax(); 119 120 //! Do automatic normalization, using mean and variance of the 121 // supplied simulator data, for uncertain parameter i. 122 // 123 // Normalized values will have mean 0 and standard deviation 1. 124 void set_autoscale_meanvar_uncertain_parameter(unsigned int i); 125 126 //! Do automatic normalization, using mean and variance of the 127 // supplied simulator data, for scenario parameter i. 128 // 129 // Normalized values will have mean 0 and standard deviation 1. 130 void set_autoscale_meanvar_scenario_parameter(unsigned int i); 131 132 //! Do automatic normalization, using mean and variance of the 133 // supplied simulator data, for output variable i. Note that, when 134 // functional data exists, variable i will *not* be the same as 135 // index i. 136 // 137 // Normalized values will have mean 0 and standard deviation 1. 138 void set_autoscale_meanvar_output(unsigned int i); 139 140 //! Do automatic normalization, using mean and variance of the 141 // supplied simulator data, for all input uncertain parameters, all 142 // input scenario parameters, and all output values. 143 // 144 // Normalized values will have mean 0 and standard deviation 1. 145 void set_autoscale_meanvar(); 146 147 //! Set a value, for uncertain parameter i in simulation inputs, of 148 // the physical parameter range (range_min, range_max) which should 149 // be rescaled to (0,1) 150 // 151 // If no value is set and no automatic normalization is specified, 152 // a default of (0,1) will be used; i.e. no normalization. 153 // 154 // This option is mutually exclusive with the above automatic 155 // scaling options; trying to use both is a runtime error. 156 void set_uncertain_parameter_scaling(unsigned int i, 157 double range_min, 158 double range_max); 159 160 //! Set a value, for scenario parameter i in simulation and 161 // experimental inputs, of the physical parameter range (range_min, 162 // range_max) which should be rescaled to (0,1) 163 // 164 // If no value is set and no automatic normalization is specified, 165 // a default of (0,1) will be used; i.e. no normalization. 166 // 167 // This option is mutually exclusive with the above automatic 168 // scaling options; trying to use both is a runtime error. 169 void set_scenario_parameter_scaling(unsigned int i, 170 double range_min, 171 double range_max); 172 173 //! Set a value, for output variable i in simulation and 174 // experimental outputs, of the physical output range (range_min, 175 // range_max) which should be rescaled to (0,1) 176 // 177 // Note that, when functional data exists, variable i will *not* be 178 // the same as output vector index i. 179 // 180 // If no value is set and no automatic normalization is specified, 181 // a default of (0,1) will be used; i.e. no normalization. 182 // 183 // This option is mutually exclusive with the above automatic 184 // scaling options; trying to use both is a runtime error. 185 void set_output_scaling(unsigned int i, 186 double range_min, 187 double range_max); 188 189 //! Determine the physical parameter ranges (range_min, range_max) 190 // which should be rescaled to (0,1), based on our autoscaling option 191 // settings. 192 template <typename V> 193 void set_final_scaling 194 (const std::vector<typename SharedPtr<V>::Type> & m_simulationScenarios, 195 const std::vector<typename SharedPtr<V>::Type> & m_simulationParameters, 196 const std::vector<typename SharedPtr<V>::Type> & m_simulationOutputs, 197 const std::vector<typename SharedPtr<V>::Type> & m_experimentScenarios, 198 const std::vector<typename SharedPtr<V>::Type> & m_experimentOutputs, 199 const std::vector<typename SharedPtr<SimulationOutputMesh<V> >::Type> & m_simulationMeshes); 200 201 //! Calculate a normalized value from a physical value for the 202 // specified scenario parameter. 203 double normalized_scenario_parameter(unsigned int i, 204 double physical_param) const; 205 206 //! Calculate a normalized value from a physical value for the 207 // specified uncertain parameter. 208 double normalized_uncertain_parameter(unsigned int i, 209 double physical_param) const; 210 211 //! Calculate a normalized value from a physical value for the 212 // output variable at vector index i. 213 double normalized_output(unsigned int i, 214 double output_data) const; 215 216 //! Calculate a normalized value from a physical value for the 217 // output variable i. 218 double normalized_output_variable(unsigned int i, 219 double output_data) const; 220 221 //! Returns the scale, in physical units, corresponding to a single 222 // nondimensionalized unit for the output at vector index i. 223 double output_scale(unsigned int i) const; 224 225 //! Returns the scale, in physical units, corresponding to a single 226 // nondimensionalized unit for output variable i. 227 double output_scale_variable(unsigned int i) const; 228 229 //! The shape parameter for the Gamma hyperprior for the truncation error precision 230 double m_truncationErrorPrecisionShape; 231 232 //! The scale parameter for the Gamma hyperprior for the truncation error precision 233 double m_truncationErrorPrecisionScale; 234 235 //! The shape parameter for the Gamma hyperprior for the emulator precision 236 double m_emulatorPrecisionShape; 237 238 //! The scale parameter for the Gamma hyperprior for the emulator precision 239 double m_emulatorPrecisionScale; 240 241 //! Whether to use an observational error precision hyperparameter 242 // lambda_y rather than a fixed multiplier of 1. 243 // 244 // False by default. 245 bool m_calibrateObservationalPrecision; 246 247 //! The shape parameter for the Gamma hyperprior for the observational precision 248 double m_observationalPrecisionShape; 249 250 //! The scale parameter for the Gamma hyperprior for the observational precision 251 double m_observationalPrecisionScale; 252 253 254 //! The alpha paramter for the Beta hyperprior for the emulator correlation strength 255 double m_emulatorCorrelationStrengthAlpha; 256 257 //! The beta paramter for the Beta hyperprior for the emulator correlation strength 258 double m_emulatorCorrelationStrengthBeta; 259 260 //! The shape parameter for the Gamma hyperprior for the discrepancy precision 261 double m_discrepancyPrecisionShape; 262 263 //! The scale parameter for the Gamma hyperprior for the discrepancy precision 264 double m_discrepancyPrecisionScale; 265 266 //! The alpha paramter for the Beta hyperprior for the discrepancy correlation strength 267 double m_discrepancyCorrelationStrengthAlpha; 268 269 //! The beta paramter for the Beta hyperprior for the discrepancy correlation strength 270 double m_discrepancyCorrelationStrengthBeta; 271 272 //! Returns the QUESO environment 273 const BaseEnvironment& env() const; 274 275 //! The shape parameter for the Gamma hyperprior for the emulator data precision 276 double m_emulatorDataPrecisionShape; 277 278 //! The scale parameter for the Gamma hyperprior for the emulator data precision 279 double m_emulatorDataPrecisionScale; 280 281 //! The ridge to add to B^T*W_y*B before inverting it 282 double m_observationalPrecisionRidge; 283 284 //! The ridge to add to (B^T*W_y*B)^-1 before using it 285 double m_observationalCovarianceRidge; 286 287 //! The distance between gaussian discrepancy kernels, on each 288 // provided simulation mesh, in each direction. 289 std::vector<double> m_gaussianDiscrepancyDistanceX, 290 m_gaussianDiscrepancyDistanceY, 291 m_gaussianDiscrepancyDistanceZ, 292 m_gaussianDiscrepancyDistanceT; 293 294 //! Whether or not gaussian discrepancy kernels should be periodic, 295 // on each simulation mesh, in each direction. 296 std::vector<bool> m_gaussianDiscrepancyPeriodicX, 297 m_gaussianDiscrepancyPeriodicY, 298 m_gaussianDiscrepancyPeriodicZ, 299 m_gaussianDiscrepancyPeriodicT; 300 301 //! Gaussian discrepancy kernels have infinite support, and we want 302 // to include some kernels which are not centered within a bounded 303 // domain, so we have a cutoff (default 5% == 0.05) for what the 304 // value of a gaussian at the domain boundary must be, relative to 305 // the value of its out-of-boundary peak, for us to include it. 306 // 307 // Currently this is a single scalar value, because I can't imagine 308 // users wanting it to differ from mesh to mesh (or from direction 309 // to direction) within a single problem. 310 double m_gaussianDiscrepancySupportThreshold; 311 312 friend std::ostream & operator<<(std::ostream& os, const GPMSAOptions & obj); 313 314 private: 315 const BaseEnvironment * m_env; 316 317 #ifndef QUESO_DISABLE_BOOST_PROGRAM_OPTIONS 318 QUESO::ScopedPtr<BoostInputOptionsParser>::Type m_parser; 319 #endif // QUESO_DISABLE_BOOST_PROGRAM_OPTIONS 320 321 // For fast lookups when doing normalization 322 std::vector<unsigned int> m_output_index_to_variable_index; 323 324 // True if the specified autoscaling should be done for all inputs 325 bool m_autoscaleMinMaxAll; 326 bool m_autoscaleMeanVarAll; 327 328 // True if the specified autoscaling should be done for the specific 329 // uncertain input parameter index 330 std::set<unsigned int> m_autoscaleMinMaxUncertain; 331 std::set<unsigned int> m_autoscaleMeanVarUncertain; 332 333 // True if the specified autoscaling should be done for the specific 334 // scenario input parameter index 335 std::set<unsigned int> m_autoscaleMinMaxScenario; 336 std::set<unsigned int> m_autoscaleMeanVarScenario; 337 338 // True if the specified autoscaling should be done for the specific 339 // output variable index; this index could apply to many vector 340 // indices in the case of functional output. 341 std::set<unsigned int> m_autoscaleMinMaxOutput; 342 std::set<unsigned int> m_autoscaleMeanVarOutput; 343 344 // The point in each uncertain input parameter range (typically min 345 // or mean) corresponding to a normalized parameter of 0 346 std::vector<double> m_uncertainScaleMin; 347 348 // The width of the physical uncertain input parameter range 349 // (typically max minus min or standard deviation) corresponding to 350 // a normalized width of 1 351 std::vector<double> m_uncertainScaleRange; 352 353 // The point in each input scenario parameter range (typically min 354 // or mean) corresponding to a normalized parameter of 0 355 std::vector<double> m_scenarioScaleMin; 356 357 // The width of the physical input scenario parameter range 358 // (typically max minus min or standard deviation) corresponding to 359 // a normalized width of 1 360 std::vector<double> m_scenarioScaleRange; 361 362 // The point in each output range (typically min 363 // or mean) corresponding to a normalized parameter of 0 364 std::vector<double> m_outputScaleMin; 365 366 // The width of the physical output range (typically max minus min 367 // or standard deviation) corresponding to a normalized width of 1 368 std::vector<double> m_outputScaleRange; 369 370 std::string m_option_help; 371 std::string m_option_maxEmulatorBasisVectors; 372 std::string m_option_truncationErrorPrecisionShape; 373 std::string m_option_truncationErrorPrecisionScale; 374 std::string m_option_emulatorBasisVarianceToCapture; 375 std::string m_option_emulatorPrecisionShape; 376 std::string m_option_emulatorPrecisionScale; 377 std::string m_option_calibrateObservationalPrecision; 378 std::string m_option_observationalPrecisionShape; 379 std::string m_option_observationalPrecisionScale; 380 std::string m_option_emulatorCorrelationStrengthAlpha; 381 std::string m_option_emulatorCorrelationStrengthBeta; 382 std::string m_option_discrepancyPrecisionShape; 383 std::string m_option_discrepancyPrecisionScale; 384 std::string m_option_discrepancyCorrelationStrengthAlpha; 385 std::string m_option_discrepancyCorrelationStrengthBeta; 386 std::string m_option_emulatorDataPrecisionShape; 387 std::string m_option_emulatorDataPrecisionScale; 388 std::string m_option_observationalPrecisionRidge; 389 std::string m_option_observationalCovarianceRidge; 390 391 std::string m_option_autoscaleMinMaxAll; 392 std::string m_option_autoscaleMeanVarAll; 393 394 std::string m_option_gaussianDiscrepancyDistanceX, 395 m_option_gaussianDiscrepancyDistanceY, 396 m_option_gaussianDiscrepancyDistanceZ, 397 m_option_gaussianDiscrepancyDistanceT; 398 399 std::string m_option_gaussianDiscrepancyPeriodicX, 400 m_option_gaussianDiscrepancyPeriodicY, 401 m_option_gaussianDiscrepancyPeriodicZ, 402 m_option_gaussianDiscrepancyPeriodicT; 403 404 std::string m_option_gaussianDiscrepancySupportThreshold; 405 406 bool options_have_been_used; 407 408 void checkOptions(); 409 }; 410 411 } // End namespace QUESO 412 413 #endif // UQ_GPMSA_OPTIONS_H 414