1 /* _______________________________________________________________________ 2 3 DAKOTA: Design Analysis Kit for Optimization and Terascale Applications 4 Copyright 2014-2020 National Technology & Engineering Solutions of Sandia, LLC (NTESS). 5 This software is distributed under the GNU Lesser General Public License. 6 For more information, see the README file in the top Dakota directory. 7 _______________________________________________________________________ */ 8 9 //- Class: NonDLHSSampling 10 //- Description: Wrapper class for Fortran 90 LHS library 11 //- Owner: Mike Eldred 12 //- Checked by: 13 //- Version: 14 15 #ifndef NOND_LHS_SAMPLING_H 16 #define NOND_LHS_SAMPLING_H 17 18 #include "NonDSampling.hpp" 19 #include "DataMethod.hpp" 20 21 22 namespace Dakota { 23 24 /// Performs LHS and Monte Carlo sampling for uncertainty quantification. 25 26 /** The Latin Hypercube Sampling (LHS) package from Sandia 27 Albuquerque's Risk and Reliability organization provides 28 comprehensive capabilities for Monte Carlo and Latin Hypercube 29 sampling within a broad array of user-specified probabilistic 30 parameter distributions. It enforces user-specified rank 31 correlations through use of a mixing routine. The NonDLHSSampling 32 class provides a C++ wrapper for the LHS library and is used for 33 performing forward propagations of parameter uncertainties into 34 response statistics. 35 36 Batch generation options, including D-Optimal and incremental LHS 37 are provided. 38 39 The incremental LHS sampling capability allows one to supplement 40 an initial sample of size n to size 2n while maintaining the 41 correct stratification of the 2n samples and also maintaining the 42 specified correlation structure. The incremental version of LHS 43 will return a sample of size n, which when combined with the 44 original sample of size n, allows one to double the size of the 45 sample. 46 */ 47 class NonDLHSSampling: public NonDSampling 48 { 49 public: 50 51 // 52 //- Heading: Constructors and destructor 53 // 54 55 /// standard constructor 56 NonDLHSSampling(ProblemDescDB& problem_db, Model& model); 57 /// alternate constructor for sample generation and evaluation "on the fly" 58 NonDLHSSampling(Model& model, unsigned short sample_type, 59 int samples, int seed, const String& rng, 60 bool vary_pattern = true, short sampling_vars_mode = ACTIVE); 61 /// alternate constructor for uniform sample generation "on the fly" 62 NonDLHSSampling(unsigned short sample_type, int samples, int seed, 63 const String& rng, const RealVector& lower_bnds, 64 const RealVector& upper_bnds); 65 /// alternate constructor for sample generation of correlated normals 66 /// "on the fly" 67 NonDLHSSampling(unsigned short sample_type, int samples, int seed, 68 const String& rng, const RealVector& means, 69 const RealVector& std_devs, const RealVector& lower_bnds, 70 const RealVector& upper_bnds, RealSymMatrix& correl); 71 /// destructor 72 ~NonDLHSSampling(); 73 74 protected: 75 76 // 77 //- Heading: Virtual function redefinitions 78 // 79 80 /// increment to next in sequence of refinement samples 81 void sampling_increment(); 82 83 // together the three run components perform a forward uncertainty 84 // propagation by using LHS to generate a set of parameter samples, 85 // performing function evaluations on these parameter samples, and 86 // computing statistics on the ensemble of results. 87 88 /// generate LHS samples in non-VBD cases 89 void pre_run(); 90 /// perform the evaluate parameter sets portion of run 91 void core_run(); 92 /// generate statistics for LHS runs in non-VBD cases 93 void post_run(std::ostream& s); 94 95 void post_input(); 96 97 /// update finalStatistics and (if MC sampling) finalStatErrors 98 void update_final_statistics(); 99 100 /// compute a principal components analysis on the sample set 101 void compute_pca(std::ostream& s); 102 103 /// print the final statistics 104 void print_results(std::ostream& s, short results_state = FINAL_RESULTS); 105 106 // 107 //- Heading: Member functions 108 // 109 110 /// generate a d-optimal parameter set, leaving the first 111 /// previous_samples columns intact and adding new_samples new 112 /// columns following them 113 void d_optimal_parameter_set(int previous_samples, int new_samples, 114 RealMatrix& full_samples); 115 116 /// Populate the first new_samples columns of allSamples with an LHS 117 /// design and update the stored ranks 118 void initial_increm_lhs_set(int new_samples, 119 RealMatrix& full_samples, IntMatrix& full_ranks); 120 121 /// generate a new batch that is Latin w.r.t. the previous samples 122 void increm_lhs_parameter_set(int previous_samples, int new_samples, 123 RealMatrix& full_samples, IntMatrix& all_ranks); 124 125 /// store the ranks of the last generated sample for continuous 126 /// (based on sampleRanks) and calculate/store discrete ranks 127 void store_ranks(const RealMatrix& sample_values, IntMatrix &sample_ranks); 128 129 /// store the combined ranks from sampleRanks to leading submatrix 130 /// local cached ranks matrix 131 void store_ranks(IntMatrix& full_ranks); 132 133 /// merge the discrete ranks into a submatrix of sampleRanks 134 void combine_discrete_ranks(const RealMatrix& initial_values, 135 const RealMatrix& increm_values); 136 137 /// sort algorithm to compute ranks for rank correlations 138 static bool rank_sort(const int& x, const int& y); 139 140 /// Print a header and summary statistics 141 void print_header_and_statistics(std::ostream& s, const int& num_samples); 142 143 /// Archive all results 144 void archive_results(int num_samples, size_t ind_inc = 0); 145 146 private: 147 148 // 149 //- Heading: Data 150 // 151 152 /// number of response functions; used to distinguish NonD from opt/NLS usage 153 size_t numResponseFunctions; 154 155 /// list of refinement sample batch sizes 156 IntVector refineSamples; 157 158 /// whether to generate d-optimal point sets 159 bool dOptimal; 160 161 /// number of candidate designs to generate for classical D-optimal designs 162 size_t numCandidateDesigns; 163 164 /// oversampling ratio for Leja D-optimal candidate set generation 165 Real oversampleRatio; 166 167 /// static data used by static rank_sort() fn 168 static RealArray rawData; 169 170 /// flags computation of variance-based decomposition indices 171 bool varBasedDecompFlag; 172 173 /// flag to specify the calculation of principal components 174 bool pcaFlag; 175 /// Threshold to keep number of principal components that explain 176 /// this much variance 177 Real percentVarianceExplained; 178 }; 179 180 } // namespace Dakota 181 182 #endif 183