Home

SimEnv User Guide - Potsdam Institute for Climate Impact Research

Contents

1. Tab 8 1 Classified argument restriction s result description for the different levels of checking a coordinate description see below Argument restriction s Argument restriction s Result description result cf Section 8 1 2 for syntax description dimensionality extents and coordinates of the same dimensionality extents and only non character non constant argument arg coordinates as the only non character 1 can be arbitrary non constant argument dim res dim arg ext res j ext arg j for all j coord res j coord arg j for allj all non character non constant arguments arg same dimensionality extents and with same dimensionality extents and coordi coordinates as all the non character 2 1 nates non constant arguments i dim res dim arg ext res j ext arg j for all j coord res j coord arg j for allj some non character non constant arguments same dimensionality extents and 2 arg with same non zero dimensionality extents coordinates as all the non character and coordinates all the other non character non constant arguments with non arguments with dimensionality 0 zero dimensionality 2 2 dim res dim arg ext res j ext arg j for allj coord res j coord arg j for allj The 0 dimensional argument is ap plied to each element of the non zero dimensional argument 3 dimensionality extents and coordinates of the d
2. tt ico _nrl 2 ico_beg_posl 2 j valuel iretv2 simenv get co val f it ico nr2 1 ico_ beg pos2 1 j value2 c iret 33 differing coordinate values ra a Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 o HN uw lt 211 if valuel ne value2 iret 33 enddo endif endif ierror 0 if ichk_modus eq 2 then LE alias GCL aleuercoies3 elseif ichk_modus eq 1 then if iret gt 32 ierror 3 endif endif endif if ierror eq 0 then iextl 2 iext2 2 TCO imei 2 ica mic2 2 Teo eg posi 2s nk Ome cmos A 2 iok simenv_put_struct_res f 0 idimens1 iextl ico_nrl ico_beg_posl endif return error code Simenv check user def operator ierror PSEA end integer 4 function simenv_compute_user_def_operator res len_res SimEnv operator results are always of type real 4 reals resllen res integer len res declare SimEnv interface functions compile with IS SE_HOME inc Tiel uCkS Sasi oor 38 5 alae auxiliary variables integer 4 iext1 9 iext2 9 Taala welllureys re racl renra get dimensionality idimens and extents iext for both arguments idimens simenv get dim arg f 1 iext1 idimens simenv get dim arg f 2 iext2 perform matrix multiplication m 0 do k 1 iext2 2 Lene orrs i l alesse 1 do i 1 iextl1 1 iargl offs 1i res i k sum argl i 1l arg2 1
3. Tab 8 11 Experiment specific operators for DFD Argument Argument value Name Meaning restriction s g ae vas restriction result description dfd navigation and aggregation in the char_arg1 selection char_arg1 factor space for arg2 according aggregation filter arg2 to char_arg1 according to Tab 8 15 dim res dim arg2 appended dimensions according to char_arg1 same as for see Section 8 4 5 see Section 8 4 5 see Section 8 4 5 UNC_MC Tab 8 12 Syntax of the filter argument 1 for operator dfd Placeholder Explanation lt filter gt lt operator gt lt operator gt lt operator gt lt operator gt lt select_operator gt lt aggreg_operator gt lt select_operator gt sel lt factor_val_type gt lt factor_name gt lt factor_val_range gt lt aggreg_operator gt lt aggreg_type gt _ lt factor_val_type gt lt factor_name gt lt factor_val_range gt lt factor_name gt name of the experiment factor according to the experiment description file lt factor_val_type gt specification how to interpret lt factor_val_range gt i as a range of position indices of factor values always count from 1 S as a range of sampled factor values lt factor_smp_val gt a as a range of adjusted factor values lt factor_adj_val gt lt factor_val_range gt lt val gt lt val gt for lt val gt lt nil gt lt va
4. 0 cccccccececcnececeeeeeeeeeaeee cece seeeneaeeeeeeeeeseeaeeeeeeseaeea 64 Additional elements of lt model gt edf for experiment types with probabilistic sampling ceeeeeeeee 65 Probability density functions and their parameters c cccccceeeeceeceeeeeeeeeeeaeceeeeeseeeceaeaeeeeeseseecaeeeeeeeeaees 67 Experiment specific elements of an edf file for GSA _EE Lecce ee eeneeeeeenaeeeeeneeeeeeaeeeeeenaeeeenneeeeneaa 69 Experiment specific elements of an edf file for GSA_VB eee cece eeeeeeeeenneeeeeenaeeeseneeeeesaeeeeeenaeeeenneeeeneaa 71 Experiment specific elements of an edf file for a DFD experiment ccceceeeeeeeceeeeeeeeeeeeeeeaeeeeeeeeeeeees T3 Experiment specific elements of an edf file for UNC_MC eee cece ee sent ee eeeaeeeenneeeeeeaeeeeeeaeeeenneeeenaa 76 Experiment specific elements of an edf file for LSA cccccecececcececeeeeeeeeeeeeaeceeeeeseceneaeaeeeeeseseeesaeeeeeeneeea 79 Experiment specific elements of an edf file for BAY BC ooo ieee eeeeeeeeeeneeeeeeaeeeeeneeeeesaeeeseeaeeeenneeeenea 80 Elements of a BAY_BC bdf file eee ee eeteee ee eene ee eeee ee ee eae eee eeeaaeeeseneeeeeeaeeeeeeaaeeeenneeeesenaeeeenaeeeenneeeeneaa 81 Experiment specific elements of an edf file for OPT_SA Qo ceeeeeeeeeeeeeeneeeeeeeaeeeeeneeeeesaeeeeeenateeenneeeeneaa 87 Experiment related user shell scripts and files 00 00 0222 cccceccececeeeeeeeceae cece ee eeceeaeceeeeeseenaaeaeeeeeses
5. gsa_vb_run_mask mask runs to use for subse 7 samplet tresample char_arg1 quent UNC_MC experiment sample specific operators resample all resample_but_ this is NOT a lt factor_name gt multi run operator resample_but_all same as for see Section 8 4 5 see Section 8 4 5 see Section 8 4 5 UNC_MC The following explanations hold for the operators in Tab 8 10 For operators effects_1st and effects_tot first order and total effects indices are derived for reasons of numerical stability from the standardized variable arg1 avg_e arg1 sqrt var_e arg1 instead of arg1 This normalization does not change the indices Both operators append an additional dimensions to the dimensionality of its argument It corresponds to the factors Their sequence corresponds to the sequence of the factors in lt model gt edf As the run ensemble is composed from the sample S the re sample R and the resulting samples RS check Section 4 3 the operator gsa_vb_run_mask allows for selection of those sub samples out of the run ensemble that are to be included into the performance of subsequent UNC_MC operators If the character argument of the operator gsa_vb_run_mask is sample resample sample resample all resample_but_all resample_but_ lt factor_name gt all runs from the sample and the re sample all runs from the sample all runs from the re sample all runs all runs where all factors but
6. 0 an error occurred Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 F F Function Arguments Argument function value unction name Stee f Aare description function value description simenv_ announce to out string name of the variable in lt model gt mdf to be sliced slice_ put at the next var_name py ja m corresponding input simenv_put_ int dimension to be sliced var_name call only a slice of idim idim variable var_name input ifrom This announce int slice to start at position ifrom ito ment becomes ifrom ifrom corresponds to an index from index_extents inactive after per input in lt model gt mdf formance of the int slice to end at position ito corresponding ito ito corresponds to an index from index_extents in simenv_put_ input lt model gt mdf int return code simenv_slice_ 0 ok function value 0 an error occurred simenv_ close model string py return code end_ coupling interface int ja m 0 ok py ja m simenv_end_ Perform always function value as the last SimEnv function in the model 44 Make sure consistency of type and dimension declarations between the model output variables in model source code and the corresponding variable declarations in the model output description file lt model gt mdf Model output variables that are not output completely or only partially within the user m
7. Example 8 13 Experiment post processing operators for BAY_BC na aa S 136 y H Es f J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 8 4 8 Optimization Simulated Annealing OPT_SA The goal of an optimization experiment is to minimize a cost function by determining the corresponding op timal point in the factor space Nevertheless the specified model output from all single runs is stored during the experiment Tab 8 17 Experiment specific operators for OPT_SA Argument Argument value Name Meaning restriction s g ase Ane restriction result description same as for see Section 8 4 5 see Section 8 4 5 see Section 8 4 5 UNC_MC While the single run that corresponds to the optimal cost function can be post processed in the single run modus the whole experiment can be post processed as an UNC_MC experiment Keep in mind that the factors generally do not follow a pre defined distribution Having a model output variable definition as in Example 5 1 on page 40 and assuming address_default coordinate in lt model gt cfg Assume the experiment description file LSA from Example 6 12 on page 88 then in result processing minprop_e sum bios run number with the minimal cost function Dimensionality 0 Coordinates without Extents without ens Ssum bios run xxx sum bios run ensemble of the bias of cost function from its optimal valu
8. o gt y H i j ji S Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 3 Version 3 01 This chapter summarizes differences between the current and the previous SimEnv release limita tions and bugs and their workarounds 3 1 What is New Tab 3 1 SimEnv changes in Version 3 01 Type Check see on Description page update Tab 4 1 15 Experiment description file lt model gt edf Experiment types renamed new Section 4 3 4 3 New experiment type Section 6 3 6 3 Variance based global sensitivity analysis GSA_VB Section 8 4 3 8 4 3 Decompose variance at model output into linear or total effects of individual factors by applying Sobol method new Section 4 7 28 New experiment type Section 6 7 80 Bayesian calibration BAY_BC Section 8 4 7 135 Reduce uncertainty about factor values by deriving a representative sample from factor prior distributions by taking into account meas urement values from the system available for model system inter comparison new Sections 4 2 6 2 16 69 Experiment type GSA_EE formerly global sensitivity The p level grid is now constructed from equidistant quantiles of assigned distributions for each factor Non dimensionality of sensitivity measures allows for comparison across different output functions new Section 5 7 2 48 GAMS model interface New sub keyword script in lt model gt gdf for performing a shell s
9. Fax 49 331 288 2640 P IK WWW http www pik potsdam de Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 JH ahs lt ji That is what we meant by science That both question and answer are tied up with uncertainty and that they are painful But that there is no way around them And that you hide nothing instead everything is brought out into the open Peter H eg Borderliners McClelland Bantam Toronto 1995 p 19 z o a93 IV j ae ulti Run Simulation Environment SimEnv ser Guide for Version 3 uly 10 IV SHEN Multi Run Simulation Envi SimE User Guide for Version 3 01 July 10 2012 Contents EXECUTIVE SUMMARY craen eieiei eaa NER Ei Eea EAE EA a cvvee cen EA AIARRA 1 1 ABOUT THIS DOCUMEN T rT ig ee ee ce ge ed Ae 5 1 1 Document CONVENTIONS sisine nienie eai rie ariar egiara ara betastdenc tdeusbecusbesaseehe lt dosves 5 1 2 Example Layo t conr ernier e e aaeei EE Tes eaae aaa Oaea aa aa aaea iiaiai 6 2 GEM TING STARTED iuter a ar a a O r r O a 7 3 VERSION 3 O ccir aaa cede eas gic EN E Oa E E La E AE EREE EEA 9 3 1 WVU NS NEW ra oa a E E 9 3 2 Limitations Problems and Their Workarounds cceecceeeeeeeeeeneeeeeeeeeeeeeeaeeeeeeeaeeeseneeeeeenaeeeeeenaeeeenneeenenea 11 3 3 Known Bugs and Their Workarounds sisrate egean ereas ta aaeoa iia paaa Ea eea radka itant 12 4 EXPERIMENT TYPES anria aana e iaa eaa Eia aR AAEE EEA EEA EREE 13 4 1 Gene
10. bin_mid number of bins 4 lt int_arg3 lt number_of_values_of_arg6 or 0 automatic determination max 4 number_of_values_of_arg6 10 left bin bound for bin number 1 right bin bound for bin number int_arg3 determine bounds by min arg6 and max arg6 min arg6 max arg6 all result values are undefined The loop character argument char_arg1 is characterised as follows e The length of the string is equal to the dimensionality of the non character non constant argument e The string consists of 0 and 1 JHN av Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 e Oat position n means aggregate over the corresponding dimension n of the argument e 1 at position n means do not aggregate over the corresponding dimension n of the argument e Loop character arguments formed only of O 0 0 or 1 1 1 are forbidden 8 3 4 Advanced Operators Tab 8 8 Built in advanced operators Argument restriction s Argument Name Meaning result description value Example Tab 8 1 page restriction 106 classify classify arg4 into int_arg1 1 classify int_arg1 classes dim arg4 gt 0 10 real_arg2 potentially restrict classi int_arg1 number of classes 0 real_arg3 fication to interval 2 lt int_arg1 lt Osy arg4 real_arg2 real_arg3 number of values of arg4 atmo 0 automatic determination number of classes max 2 nmb
11. 84 yi HN iat I i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 6 7 4 Examples general descr Experiment description for the examples general descr in the SimEnv User Guide general type BAY BC PEO OIE pl type set factor jo default ir factor pl sample Gals tram U02 RACOR p2 type set IEGIO CONE p2 default ox factor p2 sample cisti NG 270304 factor p2 sample include 1 4 2 6 sample only within the 30 interval BACELOR p3 type set factor jos default ahs factor p3 sample distr U 8 10 factor p4 type set IE EKO CONC p4 default 4 factor p4 sample dassie W 6 2 specific runs 10000 chain length Example file world edf_BAY_BC Example 6 8 Experiment description file lt model gt edf for BAY_BC general descr settings 1 multiple case general descr else multiple setting case general settings i or 3 general method metropolis reflected likelihood LEN model_output vl i 1 10 10 values in total likelihood ERZI data el Cleve likelihood ise model _ output v2 i 1 5 5 values in total likelihood LEZ data Iie dat Example 6 9 Bayesian calibration description file lt model gt bdf for BAY_BC lt model gt run pin sh SSE_HOME bin simenv_ini_sh my patch_model is a patch model that is initialized calibrated for a partea a setting oy chs Tile patchy lt parcheno gt arms only for the multiple case running the model only at patch 1
12. eeeeeeieerrerrirerrnre 217 15 5 List of Experiment Post Processor Built In Operators and Operator Argument cecceeeestteeeeereeees 218 15 5 1 Experiment Post Processor Built In Operators in Thematic Order 218 15 5 2 Experiment Post Processor Built In Operators in Alphabetic Order 222 15 5 3 Character Arguments of Experiment Post Processor Built In Operators esenee 226 15 5 4 Constant Arguments of Experiment Post Processor Built In Operators 228 15 6 Additionally Used Symbols for the Model and Operator Interface ee eecceeeeeseeeeeeeeeeeeneeeeeeenaeeeeeeeaees 229 15 7 GIOSS ANY sascast cs an these sarin resstenan A E tort aaahst R E peastenaaarteben 231 3 m Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 3 3 I WINS lt Vii Tables Tab 1 1 Tab 1 2 Tab 3 1 Tab 3 2 Tab 3 3 Tab 3 4 Tab 3 5 Tab 4 1 Tab 4 2 Tab 4 3 Tab 4 4 Tab 4 5 Tab 5 1 Tab 5 2 Tab 5 3 Tab 5 4 Tab 5 5 Tab 5 6 Tab 5 7 Tab 5 8 Tab 5 9 Tab 5 10 Tab 6 1 Tab 6 2 Tab 6 3 Tab 6 4 Tab 6 5 Tab 6 6 Tab 6 7 Tab 6 8 Tab 6 9 Tab 6 10 Tab 6 11 Tab 6 12 Tab 7 1 Tab 7 2 Tab 8 1 Tab 8 2 Tab 8 3 Tab 8 4 Tab 8 5 Tab 8 6 Tab 8 7 Tab 8 8 Tab 8 9 Tab 8 10 Tab 8 11 Tab 8 12 Tab 8 13 Tab 8 14 Tab 8 15 Tab 8 16 Tab 8 17 Tab 8 18 Tab 8 19 Tab 8 20 Tab 8 21 Tab 8 22 Tab 10 1 Tab 10 2 Tab 10 3 Tab 10 4 Tab 10 5 Tab
13. factor def val p4 SSE_HOME bin simenv_get_sh create temporary direc and model output transformation from native to SimEnv structure there mkdir run simenv_run_char cd run simenv_run_char run the model cp land_sea_mask coarsed world_sh pl p2 p3 p4 read model results and output them to SimEnv world shput clear and remove directory Gel sx rm fR run simenv_run_char perform always and as the last SE_HOM SSE_HOME bin simenv_end_sh Example file world_sh run Example 15 10 Model interface at shell script level model shell script world_sh run 208 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 2 12 Model Interface for ASCII Files Assume any experiment Assume model executable world_as example file world_as f e to take factor names and resulting adjusted values p1 to p4 from the file generated by simenv_get_as e to output model variables to ASCII files e atmo_bios ascii lt simenv_run_char gt e atmo_g ascii lt simenv_run_char gt e __ bios_g ascii lt simenv_run_char gt with the same file structure as in Example 5 6 The current run number in 6 character notation is ap pended to the file names to distinguish files for parallel experiment performance The shell script world_as run with an ASCII interface to run the model world_as and to transfer model out put to SimEnv could look like SS SS Ss bin perform always an
14. simenv_ initialize model integer 4 return code ini_ f c coupling interface simenv_ini_ 0 ok fic 2_ IO error for experiment output file function value 3 error memory allocation Perform always 4 I O error for simenv_edf_bin tmp as the first as the structured representation of SimEnv function lt model gt edf in the model 5 I O error for simenv_mdf_bin tmp Check the semi as the structured representation of automated model lt model gt mdf interface for al 6 I O error for lt model gt smp ternatives 7 wrong single run number simenv_ get the resulting character name of the factor in lt model gt edf get_ f c adjusted value for factor_name the factor to be input factor_name experimented with real 4 default nominal factor value as specified in factor_def_val factor_adj_val in the current single run factor_def_val input lt model gt edf If factor_name is not defined in lt model gt edf then factor_adj_val is set to factor_def_val real 4 adjusted factor value factor_adj_val output integer 4 return code simenv_get_ 0 ok fic 1 factor_name undefined function value factor_adj_val factor_def_val simenv_ get run number of integer 4 current run number get_run_ f c the currentrunas simenv_run_int an integer value output simenv_run_int and a character character 6 current run number with leading zeros simenv_ string simenv_ run_char run_cha
15. amp idim amp levell amp levell idim 4 idecadel idecade 1 simenv_sts simenv_slice_c atmo amp idim amp idecadel amp idecadel simenv_sts simenv_put_c atmo char amp atmo idim 3 idecadel idecade 1 simenv_sts simenv_slice_c bios amp idim amp idecadel amp idecadel1 simenv_sts simenv_put_c bios char amp bios Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 compute dynamics of bios g simenv_sts simenv_end_c Pacu O simenv_sts simenv_put_c atmo_g char amp atmo_g simenv_sts simenv_put_c bios_g char amp bios_g Example file world_c c Example 15 3 Model interface for C models model world_c c Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 2 5 C Model With respect to Example 5 1 the following C code world_cpp cpp could be used to describe the model interfaced to SimEnv SimEnv modifications are marked in bold include lt stdio h gt include lt stdlib h gt declare SimEnv interface functions compile with ISSE_HOME inc include simenv_mod_c inc class World declare atmo without dimensions level and time and bios without time because they are computed in place and simenyv slice is used publics Float acme l4S 90 publics leat lonlios S3G YO
16. my_ patch model lt patch _1 ini only for the multiple setting case running the model for all patches SE_HOME bin simenv_bay bc sh my patch model setting _run sh SSE_HOME bin simenv_end_sh Q Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Ly H ar lt 85 User shell script my_patch_model_setting_run sh running one patch for the multiple setting case ip esl BAY BO SETEING 1S lake Current eeEtinNg MUNDET file patch _ lt patch_no gt ini holds the patch setting specific information my_patch_model lt patch SSE BAY BC SETTING ini Excerpt from lt model gt cfg model out_directory Experiment output is stored for the multiple case and for other experiments with a single likelihood case to multiple setting case for setting 1 to multiple setting case for setting 2 to multiple setting case for setting 3 to scratch modout scratch modout scratch modout s_1 scratch modout s_2 scratch modout s_3 Example 6 10 lt model gt run for BAY_BC Multiple case settings 1 data files for the likelihood function file If1 dat 10 values in total and data values for v1 3 v1 4 v1 5 v1 9 2 nodata HEES OLS ASA OA 155 OILS 3 nodata TORO Os 1 nodata file If2 dat 5 values in total and data values for v2 1 v2 5 TARONA 2 nodata 3 4E 38 3 4E
17. name bin_mid values equidist_end 1 bin mid bin width nmb of bins char_arg1 bin_no bin_mid int_arg2 number of bins 4 lt int_arg2 lt number_of_values or 0 automatic determination number of bins max 4 number_of_values_of_arg5 10 real_arg3 left bin bound for bin number 1 real_arg4 right bin bound for bin number int_arg2 real_arg3 real_arg4 0 determine bounds by min arg5 and max arg5 min arg5 max arg5 all result values are undefined Tab 8 6 Built in standard aggregation moment operators with suffix _n Aggregation and moment operator Argument restriction s result description Tab 8 1 page 106 max_n arg1 arg2 arg3 argn min_n arg1 arg2 arg3 argn 4 maxprop_n arg1 arg2 arg3 argn minprop_n arg1 arg2 arg3 argn 4 return per result element the argument position 1 n where the extreme is reached the first time Processing sequence starts with arg1 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Tab 8 7 Built in standard aggregation moment operators with suffix _I Aggregation and moment operator Argument restriction s result description min_I char_arg1 arg2 max_l char_arg1 arg2 sum_l char_arg1 arg2 avg_l char_arg1 arg2 var_l char_arg1 arg2 avgg
18. The Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 by M Flechsig U Bohm T Nocke amp C Rachimow Disclaimer of Warranty The authors make no warranties expressed or implied that the programs and data contained in the software package and the formulas given in this document are free of error or are consistent with any particular standard of merchantability or that they will meet the requirements for any particular application They should not be relied for solving a problem whose incorrect solution could result in injury to a person or loss of property Applying the programs or data or formulas in such a manner is on the user s own risk The authors disclaim all liability for direct or consequential damages from the use of the programs and data m n A N A I FIANS ulti Run Simulation Environment SimEnv ser Guide for Version 3 uly 10 I Deny Multi Run Simulation Envi SimE User Guide for Version 3 01 July 10 2012 The Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 by Michael Flechsig flechsig pik potsdam de Uwe B hm uwe boehm dwd de Thomas Nocke nocke pik potsdam de Claus Rachimow rachimow pik potsdam de SimEnv on the Internet http www pik potsdam de software simenv Potsdam Institute for Climate Impact Research Telegrafenberg 14473 Potsdam Germany D D D e lil Phone 49 331 288 2604
19. boundary value name corresponding to factors of the investigated model Correspondence is achieved by applying the SimEnv model interface function simenv_get_ in the model Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Factor names must differ from model output variables and coordinate names in the model output de scription file cf Section 5 1 and from built in and user defined operator names for experiment post processing cf Section 8 5 4 To derive the adjusted value of a factor its default nominal value as specified in lt model gt edf and not its default nominal value as specified in the model code is used in the model interface function simenv_get_ The file lt model gt smp always contains the sampled values according to the experiment and fac tor specific sampling scheme as defined by the sub keyword sample without applying the ad justment Consequently in general the factor values in lt model gt smp differ from the factor values as stored in the SimEnv experiment output In particular this is the case for factor adjustment type add and lt factor_def_val gt 0 factor adjustment type multiply and lt factor_def_val gt 1 factor adjustment type relative and any lt factor_def_val gt For the factor adjustment types multiply and relative a default nominal value lt real_val gt 0 is forbid den All experiment specific information is explained in t
20. ja m 0 ok 1 error additional user model specific commands can be implemented up from here if test rc_simenv_ini_ py ja m 0 then fi return always with the return code rc_simenv_ini_ py ja m exit rc_simenv_ini_ py ja m For an experiment restart with a Python Java or Matlab model cf Section 7 4 on page 95 lt model gt ini has to be performed again To force this specify in lt model gt cfg cf Section 10 1 on page 151 for the sub keyword restart_ini the value yes 5 6 Model Interface for Mathematica Models For Mathematica models a simple interface to SimEnv is implemented It is based on e generating automatically per single run a temporary Mathematica model by prefixing the original model with a piece of Mathematica model code that is generated automatically by SimEnv e performing this temporary model e transferring the model output from external files to SimEnv model output structures Set in the file HOME profile the Mathematica environment include the path to MathKernel in the PATH environment variable For more information check Section 10 9 simenv_get function The generic simenv_get function for a Mathematica model and running the model is performed by the SimEnv dot script SE_HOME bin simenv_run_mathematica This dot script has to be called in lt model gt run It expects that the Mathematica model has the name lt model gt m where lt model gt
21. 1 1 move_avg moving average of arg4 1 move avg char_arg1 dim arg4 gt 0 001 char_arg2 char_arg1 moving average lin int_arg3 sequence per dimension 0 arg4 char_arg2 average type atmo lin linear exp exponential running length for average int_arg3 gt 1 int_arg3 0 automatic determination max 3 ext arg4 i 20 int_arg3 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Argument restriction s Argument Name Meaning result description value Example Tab 8 1 page restriction 106 rank assign rank numbers to 1 rank char_arg1 arg2 according to ranking dim arg2 gt 0 tie avg arg2 type argument char_arg1 arg1 ranking type atmo tie_plain tie_min tie_avg regrid assign completely or par 1 regrid char_arg1 tially new coordinates to but coordinates according to mod ctf arg2 arg2 char_arg1 atmo _g 13 char_arg1 file how to transform coordinates of arg2 arg2 result to transform coordinates run values of arg 2 for the 1 run char_arg1 selected single run char_arg1 run number selection O arg2 number explicitly or implic for all experiment atmo itly coded in char_arg1 types run lt run_number gt sel _t pl1 4 0 lt char_arg1 lt atmo number_of_runs addit for DFD and LSA lt filter argument gt same as filter argument of operators dfd and sens lin
22. Determination of the i th element of multidimensional results follows the Fortran storage model see Glossary in Section 15 7 Individual likelihoods are multiplied afterwards to form the final likelinood function and consequently the posterior probability as described in Section 4 7 The number of average variance data pairs and the number of values product of the extents of the result must be identical For the structure of the data file check below Besides this single likelihood function case check Section 4 7 the user can specify in lt model gt bdf for the multiple likelihood function case several likelihood functions with different lt likelinood_ name gt Gen na o gt 82 y HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 erally the likelihood functions differ in their data and result parts from each other and each likelihood function follows the rules for the single likelihood function case Again the single case likelihoods are multiplied to determine the multiple case likelihood The file for the data part of the likelihood function has to follow the syntax rules of ASCII data files in Section 11 3 Per data record two values are allowed The first value is the average of the measurement value and the second value is the assigned variance As the number of average variance data pairs in the table and the number of values of the result must be identical nodata pairs
23. M 1990 One Decade of SONCHES Syst Anal Mod amp Sim 7 411 428 Wierzbicki A P 1984 Models and Sensitivity of Control Systems Studies in Automation and Control Vol 5 Elsevier Amsterdam a a 186 Ay HN r iwi lt Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 Appendices The appendices summarize the current version implementation list the examples for model inter faces user defined operators and result import interfaces and they compile all experiment post processor built in operators Finally a glossary of the main terms as used in this User Guide is supplied gt OF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 ky HN a J ji lt 187 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 1 Version Implementation Currently SimEnv is running under Unix and Linux For all installations only the latest version is supported and bug fixes are installed on demand Tab 15 1 lists the directory structure of SimEnv For SimEnv home directories at PIK check Tab 3 3 Tab 15 1 SimEnv installation directory structure Sub directory of SE_HOME Contents Latest version of SimEnv bin SimEnv scripts binaries and auxiliary files lib SimEnv libraries and scripts to link models and operators inc SimEnv include files for models and operators doc
24. Potsdam http www pik potsdam de research publications pikreports files pr47 pdf Flechsig M Bohm U Nocke T Rachimow C 2005 Techniques for Quality Assurance of Models in a Multi Run Simulation Environment In Hanson K M Hemez F M eds Sensitivity Analysis of Model Output Proceedings of the 4th International Conference on Sensitivity Analysis of Model Output SAMO 2004 Los Alamos National Laboratory Los Alamos U S A 297 306 http library lanl gov cgi bin getdoc event SAMO2004 amp document samo04 22 pdf Gray P Hart W Painton L Phillips C Trahan M Wagner J 1997 A Survey of Global Optimization Methods Sandia National Laboratories Albuquerque U S A http www cs sandia gov opt survey Helton J C Davis F J 2000 Sampling Based Methods In Saltelli et al 2000 Iman R L Helton J C 1998 An Investigation of Uncertainty and Sensitivity Analysis Techniques for Com puter Models Risk Anal 8 1 71 90 Ingber L 1989 Very fast simulated re annealing Math Comput Modelling 12 8 967 973 http www ingber com asa89_vfsr pdf Ingber L 1996 Adaptive simulated annealing ASA Lessons learned Control and Cybernetics 25 1 33 54 http www ingber com asaQ96_lessons pdf Ingber L 2004 ASA Readme http www ingber com ASA README pdf McKay M D Conover W J Beckman R J 1979 A Comparison of Three Methods for Selecting values of Input Variables in the Analysis
25. Remark number pre defined values are case insensitive avg_l sequence of digits 0 and 1 avgg_ sequence of digits 0 and 1 avgh_ sequence of digits 0 and 1 avgw_ sequence of digits 0 and 1 clip not pre defined case insensitive count all def undef count_e all def undef count sequence of digits 0 and 1 count_ all def undef cumul sequence of digits 0 and 1 dfd not pre defined case insensitive distr_par factor name case insensitive flip sequence of digits 0 and 1 get_data ascii netcdf get_data lt directory gt lt file_name gt get_data lt directory gt lt file_name gt get_experiment lt directory gt get_experiment lt model gt get_experiment lt directory gt lt file_name gt get_table_fct lt directory gt lt file_name gt hgr bin_no bin_mid hgr_e bin_no bin_mid hgr_ sequence of digits 0 and 1 hgr_ bin_no bin_mid if lt lt gt gt def undef lin_abs not pre defined case insensitive lin_rel not pre defined case insensitive mask lt lt gt gt un mask_file lt directory gt lt file_name gt max_ sequence of digits 0 and 1 I N INi 1 00 INi elv INi IN S po maxprop_l seque
26. are specified for one coordinate firstly position shift is applied to the coordinate and then the additional coordinate values from values_shift are added the the coordi nate without applying the position_shift value e Coordinate numbers lt coordinate_nmb gt are integers counting from 1 e For the sub keyword coord_extent the same rules apply as for the sub keyword coord_extents from the model output description file lt model gt mdf e For the keyword coordinate the same rules apply as for the keyword coordinate from the model out put description file lt model gt mdf e Coordinates are incorporated additionally into the original coordinate set only for the current result OAN general general modify modify modify modify modify assign assign assign assign ahWNDN dimension dimension coordinate coordinate name newl dim2 dim3 lat new2 coordinate name dim1 dim2 dims dim4 dim5 dim dim dim dim dim dim dim U aAa BD PRR EB dim dim ol new2 new2 coordinate Further assume the coordinate transformation file model ctf as descr descr rename position shift values shift values add voles io ntsiate coord coord extent coord coord _extent descr values In experiment post processing the result of the expression is a 5 dimensional data structure with coordinate definition Mist 1037 10037 L006 1009 Scuicisic Smell 2
27. are used in SimEnv as an element for the specification of value lists see below optionally in experiment description files to get sampling information and in post processing operators The following rules and restrictions are valid for lt directory gt lt file_name gt e The lt directory gt path can contain operating system environment variables e If lt directory gt is specified in a relative manner it relates to the current workspace e lt file_name gt must not be one of the SimEnv file names according to Tab 10 7 and Tab 10 8 e For the file Has to be an ASCII file Can be a multi record file Max record length is 1000 characters Values in a record are separated from each other by white spaces or comma A series of connected running separators is treated as a single separator Record end is handled as a separator Records formed only from white spaces or records starting with the first non white space character are handled as comments For variables coordinates and experiment factors value lists are supplied by the value item in user defined files Value lists describe a sequence of values together with an order The number of described values has to be greater than 1 Value lists may be restricted to strictly monotonic sequences They follow the syntax rules in Tab 11 6 Tab 11 6 Syntax rules for value lists Value list type Syntax Explanation explicit list lt real_val gt lt
28. e pupie ainhe atmo_g 20 publics Imt bios_g private int level idecade simenv_sts levell idecadel idim public void computeAtmo float pl float p2 float p3 float p4 compute dynamics of atmo over space and time and of atmo g over time all dependent on pl p2 p pi for idecade 0 idecade lt 19 idecade Taes for level 0 level lt 3 level Tea idim 3 level1l level1 1 simenv_sts simenv_slice _c atmo amp idim amp level amp level idim 4 idecadel idecadel1 1 simenv_sts simenv_slice _c atmo amp idim amp idecade amp idecade simenv_sts simenv_put_c atmo char amp atmo public void computeBios float pl float p2 float p3 float p4 compute dynamics of bios over space and time and of bios g all dependent on pl p2 p2 pi int simenv_sts for idecade 0 idecade lt 19 idecade diss idim 3 idecadel idecadel1 1 simenv_sts simenv_slice _c bios amp idim amp idecadel amp idecadel1 simenv_sts simenv_put_c bios char amp bios compute dynamics of bios g ARA 200 y H Es j i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 main void int simenv_sts simenv_run_int char simenv_run_char 6 loa joll i cILOEiE joz 2 7 loa jos 358 idkoeic jo 49 simenv_sts simenv_ini_c check
29. e Dimensionality dim operand and Extents ext operand i with i 1 dim operand Coordinates coord operand i with i 1 dim operand are assigned to The dimensionality is the number of dimensions an extent is related to each dimension and represents the number of elements in that dimension Extents are always greater than 1 To each dimension a coordinate is assigned to Coordinates have a name and from all coordinate values the co ordinate is defined for a subset is assigned to the extent of the dimension of the operand Coordinate specification for operands follows that for model output variables For more information see Section 5 1 Operators transform dimensionality dimensions and coordinates of the their non character operator arguments into unique dimensionality dimensions and coordinates of the operator result cf Section 8 1 4 Consequently the output of an operator and finally a post processor result as a sequence of operators applied to operands also has unique dimensionality extents and coordinates Experiment factors and constants always have a dimensionality of 0 Operands of dimensionality 0 and character string operands do not have a coordinate assignment 8 1 3 Model Output Variables A variable of dimensionality n corresponds to an n dimensional array and is defined at an n dimensional grid spanned up from the coordinate values of the assigned coordinates The complete data field of a model output variable or p
30. exit rc_land_sea_mask Example files world_ f c cpp py ja m sh as ini Example 7 2 Shell script lt model gt ini for user model specific experiment preparation For the shell script world_f end the following contents could be defined remove the file of the coarsed land sea mask rm f land_sea_mask coarsed Example file world_ f c cpp py ja m sh as end Example 7 3 Shell script lt model gt end for user model specific experiment wrap up gt Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN a J lt 91 For the shell script world_f run the following contents could be defined l fotas perform always and as the first SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_ini_sh enable to kill the process associated with the model SE _WS world f after 100 seconds of CPU time consumption SE_HOME bin simenv_kill process SE WS world_f 100 amp run the model SSE_WS world_f take some actions when the model was killed SE_HOME bin simenv_get_run_sh if test SSE _WS world_ f killed simenv_run_char then rm f SE_WS world f killed simenv_run_char ea perform always and as the last SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_end_sh Example file world_f run Example 7 4 Shell script lt model
31. face In this user interface a help services is implemented that should be used to gather additional informa tion on how to select post processed results for visualization and on visualization techniques provided by SimEnvVis Additionally a SimEnvVis user documentation is available from the SimEnv website Visualization of post processed experiment output is started by the SimEnv service simenv vis check Sec tion 10 2 and directly during experiment post processing by the service simenv res if in the file lt model gt cfg check Section 10 1 this feature is enabled by postproc visualization yes At PIK the SimEnvVis framework is installed at vissO1 pik potsdam de Access to viss01 is requested by the SimEnv service simenv key Check Section 10 2 for more information To apply SimEnvVis an X11 server must run on the client machine On Windows systems this may be Hummingbird or Cygwin X on Mac machines an XTerm a Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f i _ 149 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 10 General Control Services User Files and Settings In the control file simenv_settings txt general SimEnv settings are defined while lt model gt cfg is a model and workspace related general configuration file to control preparation performance and analysis of an experiment Besides simulation performance and exp
32. is the model name the service is started with e Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji 45 To enable the adjustment of a factor lt factor_name gt in the model during the performance of any single run it is necessary to modify the model source code with respect to the initial settings of the factors Let depend the assignment of the default nominal value lt factor_def_val gt to the factor variable lt factor_name gt in the model source code whether this variable was already set to its adjusted value by if ValueQ lt factor name gt False lt factor name gt lt factor def val gt lt factor name gt lt factor name gt J For an experiment with k factors the temporary Mathematica model for single run number lt simenv_run_int gt has the following structure lt factor_name gt lt factor_valUe lt simenv_run_int gt gt lt factor_name gt lt factor_valU lt simenv_run_int gt gt lt model gt This file is generated in a temporary sub directory run lt simenv_run_char gt of the current workspace The sub directory itself is created automatically when performing the single run lt simenv_run_int gt Store the Mathematica model in the current workspace the SimEnv simulation service simenv run rst is started from Since the original model is prefixed by the above piece of code that defines the adjustments of the factors
33. result number 01 record no 1 10 float in records of 10 values last record may have less values result_value 1 result_value length_result dim with length_result ext for dim gt 0 i 1 1 else result number 02 The vector result_value is stored in the Fortran storage model cf Section 15 7 Glossary The nodata ele ment for undefined result values is set to 3 4E38 The Fortran code in Example _15 15 reads experiment post processing ASCII output files lt model gt res lt simenv_res_char gt ascii and lt model gt inf lt simenv_res_char gt ascii in their general structure In the examples directory SE_HOME exa of SimEnv it is accompanied by the corresponding version for IEEE result output PTFE Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 ay Ji ua f _ 181 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 13 SimEnv Prospects SimEnv development and improvement is user driven Here one can find a list of the main develop ment pathways in future General e Graphical user interface e Portability to Windows based systems e Unique number representations for binary IEEE output of distributed models big endians vs small endi ans Model interface e for R models Experiment preparation e Experiment type stochastic analysis e UNC_MC sampling of correlated factors Experiment performance e Experiment perform
34. rst Check the semi automated model interface for alter natives for lt model gt run experiment factor_name lt factor_name gt factor_def_val lt factor_def_val gt SE_HOME bin simenv_ get the resulting adjusted value for the factor to be experimented with in the current sin gle run script variable factor_name input name of the factor in lt model gt edf script variable factor_def_val input default nominal factor value If factor_name is not defined in lt model gt edf then factor_adj_val is set to lt factor_def_val gt script variable factor_name shell script variable with the same name as the value of factor_name Script variable value is the a character script variable get_sh output adjusted factor value lt factor_adj_val gt SE_HOME bin get the run number simenv_ shell script variable with the current run number simenv_ of the current run run_char with leading zeros get_run_sh as aninteger and output simenv_run_int output shell script variable type integer with the current run number SE_HOME bin simenv_ put_sh Not available at shell script level Write a your own model related simenv_put_sh at the language level using the SimEnv model interface functions SE_HOME bin simenv_ slice_sh Not available at shell script level SE_HOME bin simenv_ end_sh wrap up current single run Perform always
35. sa pub are really a key pair It is recommended to keep the directories ssh and ssh2 disjunct 7 4 Experiment Restart When an experiment was interrupted has failed due to any reason or in the case of partial experiment per formance cf Section 7 5 below it can be restarted e Simply restart the experiment by simenv rst without changing any of the SimEnv files describing the experiment and or the model The only exception may be the values for the sub keywords of the key word experiment in the general model configuration file lt model gt cfg e simenv rst has the same usage as simenv run e Restart can be launched in a different mode on the login machine or under job management system control the latter also in other in an other job class and sub mode and or on an other machine than that of the interrupted experiment e Dependent on the experiment log file lt model gt elog written by the interrupted previous new start ex periment a single model run from the complete run ensemble in the restart experiment will be e Performed if this run has neither a start nor a finish information in the elog file e Not performed if this run has a start and a finish information in the elog file e Performed anew if the run has a start information but no finish information in the elog file e For the latter case a model restart shell script lt model gt rst can be provided by the user optionally to prepare restart of this single model
36. simenv_ini_py simenv_get_run_py only if necessary simenv_run_int int simenv_get_run_py pl float simenv_get_py pl pl1 p2 float simenv_get_py p2 p2 p3 float simenv_get_py p3 p3 p4 float simenv_get_py p4 p4 compute dynamics of atmo and bios over space and time of atmo_g over time all dependent on pl p2 p3 p4 for idecade in range 20 for level in range 4 atmo reshape atmo 45 90 4 20 simenv_put_py atmo atmo bios reshape atmo 45 90 20 simenv_put_py bios bios simenv_put_py atmo_g atmo_g compute dynamics of bios g i eae simenv_put_py bios_g bios_g simenv_end_py Example file world_py py Example 15 5 Model interface for Python models model world_py py ae 202 J HN 1a J i lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 2 7 Java Model With respect to Example 5 1 the following Java code world_ja java could be used to describe the model interfaced to SimEnv SimEnv modifications are marked in bold import java io public class world ja static float atmo new float 45 90 4 20 ll static float bios new float 36 90 20 static int atmo g new int 20 static int bios g public static void main String args int simenv sts simenv run int int idecade level float phi _lat 1 F Eloat
37. the more the factor x can be fixed at any value over its range of uncertainty without significantly modifying the output uncertainty expressed by V Z The following properties apply for 1 order sensitivity indices S and total effect indices Sx 0 lt Si lt 1 numerical irregularities may occur orthogonality zs lt 1 ditto S 1 for additive models without interaction effects and orthogonal uncorrelated factors S7 20 numerical irregularities may occur orthogonality XS7 z 1 ditto US 1 for additive models without interaction effects and orthogonal uncorrelated factors Si 2 Si Si Si if xi is not involved in interactions with other factors To determine the 1 order sensitivity indices S and total effect indices S Saltelli Saltelli 2002 Saltelli et al 2008 proposed the following cost efficient method For k factors x Xx draw two samples of size n according to the marginal distributions of the factors a sample S and a resample R Construct for each factor x i 1 k a resulting sample RS by copying all values from the resample R but for factor x For factor x take the values from the sample S In other words do not re sample for RS the factor x that first order and or total effect index is to be estimated ae ee ws 0 Sii Sik hoo Ng Ny Fia Su fin hy Psy PS S we S r e r r r S r eat r i or i nl nk nl nk nl ni 1 ni nit nk rS ni rS nk Sample S Resample R Resulting s
38. tween existing standards and the metadata requirements for a flexible and expressive visualization that is adapted to the requirements of the specific data sets of concern SimEnv follows the NetCDF Climate and Forecast NetCDF CF metadata convention 1 0 Currently SimEnv supports only up to 4 dimensional NetCDF output during experiment and post processor performance In principle any NetCDF file can be viewed by the NetCDF service program ncdump lt NetCDF_file gt Model output data types as declared in the model output description file lt model gt mdf are transferred into NetCDF data types automatically cf the Table below By default post processor output data is of type float Tab 12 1 NetCDF data types SimEnv data type cf Tab 5 4 NetCDF data type byte NF_BYTE short NF_SHORT int NF_INT float NF_FLOAT double NF_DOUBLE lt AFF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji ba f _ 177 12 1 1 Global Attributes The global attributes used in SimEnv from the CF standard are institution and Conventions In addition the following global attributes are defined for model and post processor output Tab 12 2 Additional global NetCDF attributes Name Value Data type creation_time lt YYYY MM DD HH MM SS gt char model_name lt model gt char model_ description model output description according to lt mode
39. vi Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 8 Experiment Post Processing Goal of experiment post processing is to navigate within the model experiment output space by de riving interactively output functions data that are to be visualized in experiment evaluation afterwards Therefor SimEnv supplies operators that can be applied to experiment output and reference data There are built in basic and advanced operators and built in experiment specific operators The user can define its own private operators and easily couple them to the post processor Additionally composed operators can be derived from both built in and user defined operators Operator chains and recursions are possible Macros can be defined as abbreviations for operator chains 8 1 General Approach 8 1 1 Post Processor Results In SimEnv experiment post processing post processor results synonym output functions are derived from experiment output of the experiment and from reference data A post processor result is specified by a post processor expression optionally prefixed by a result description and a result unit string lt result gt lt result_description gt lt result_unit gt lt result_expression gt lt result gt by the string Enter a result the user is asked to enter a result Input lines with a character as the first non white space character are treated as comments The e
40. 0 only for performing experi http Awww mpi forum org ments in compute cluster mode see Section 7 3 For running the corresponding interfaced models GAMS Distribution 20 http www gams com Java Version 1 4 http Awww java com Matlab Version 7 7 http www mathworks com Mathematica Version 4 1 http Awwwwolfram com For the visualization framework SimEnvVis OpenDX Version 4 4 4 http Awww opendx org Qt Version 3 3 5 http www trolltech com products qt Ferret Version 4 4 http ferret wrc noaa gov Ferret OpenGL Version 1 4 http Awww opengl orgq The version number of the software products in the above Tab 15 2 represent those version SimEnv was developed with Higher versions should also be applicable For setting up SimEnv gunzip tar configure make a Fortran compiler and the C C compiler have to be installed After installing SimEnv the file SE_HOME bin simenv_settings txt has to be adapted to the local settings check Tab 10 1 15 1 2 Technical Limitations Tab 15 3 Current SimEnv technical limitations Sampled factor values defined with equidist_ end nmb ivl see Tab 11 6 allocate only 6 storage places Maximum Entity entity value Directory strings SE_HOME bin current workspace in user defined files and operators resolved length relative to absolute paths environ variables resolved characters 109 Use
41. 1 k for k factors of the file has to have i values where value j j 1 i 1 is the covari ance between factor i and factor j and the i th value is the variance of factor i For reflected Metropolis MCMC covariances have to be zero In case the sub keyword is not used factor covariances are set to zero and factor variances are derived from the corresponding distributions as defined by the sub keyword sample in lt model gt edf For the file syntax check Section 11 3 on page 174 e Sub keyword jump_length From the last accepted point of the chain of visited points a new candidate point is constructed by a mul tivariate normal jump The length of the jump can be modified by the specified multiplier value while the direction of the jump will not be changed There are two major reasons for changing the jump length 1 jump_length lt 1 to reduce the number of candidates that are located outside the definition range of any individual factor and 2 jump_length gt 1 to speed up the convergence of the experiment i e explore the factor space adequately In case jump_length is not specified a default value 1 is assumed resulting in no modification of the jump length e Sub keyword settings SimEnv allows for composing the likelihood function from performing a single model run for a number of different model settings where all settings consistently follow the single or multiple likelinood function case check Section 4 7 This approach is
42. 1 Multi run Operators Experiment specific operators are to navigate and process in the factor space according to the layout of the individual experiment type A multi run operator operates on one or more operands for all runs of the whole run ensemble or parts of it The multi run operator gets its result from the all single runs of the experiment that have to be taken into account By contrast a non multi run single run operator gets its results individually from each sin gle run and assigns this result also to that single run Addressing an operand within a multi run operator normally results in application of the operator on the operand values from the whole run ensemble or parts of it and in aggregating across the run ensemble according to the operator Addressing an operand outside a multi run operator results in using the operand for the default run num ber 0 of the experiment The majority of the built in experiment specific operators are multi run operators Exceptions are refer enced explicitly Experiment specific operators for UNC_MC can be applied for all other experiment types Keep in mind that for the other experiment types generally the factors do not follow a pre defined distribution Multi run operators must not be applied recursively For experiment type UNC_MC one of the multi run operators is avg_e arg that computes the run ensemble average for the operand arg The corresponding single run operator is avg arg
43. 10 6 viii 4a Document CONVENTIONS cccccececeecee cece ee ttrt tetett ee eee ee ae ae ee eeeeeeceaeaeeeeeeeeeeeecaaeaeeeeeeeseceeaeseeeeeeeqesaeeeeeeeeeeeeea 5 Main placeholders in this document 4 6 cse eceecececeesdedendeesecnededeceedendecssdecdedensecceenedecdedendeeseddeceedessidaedenneee 5 simEny changes in Version 3 Ofte lee eae A chee ieee ee eee 9 User actions to upgrade to Version 3 01 0 eee eesneeeeeeeeeeeneeeeeeaeeeeeneeeeeeaeeeeeeaeeeenneeeeesnaeeeseeaeeenneeeeneaa 10 SimEnv availability at PIK MACHINES 0 eee cece erect eter ee aeeeeeeaaeeeseeeaeeesaaeeeeeeaaeeeseneaeeeseeeeenenaeeeeeenaeees 10 Limitations problems and their workarounds in Version 3 01 00 eecceeeeeeeeeeeneeeeeneeeeeeeaeeeseenaeeeenneeeeneas 11 Known bugs and their workarounds in Version 3 01 00 eeeeeee este ee cence eeeeneeeeeeaeeeseneeeeesaeeeeeenaeeeenneeeeneaa 12 DIMENV EXPErIMENt LYPES naniii dace rebsdare debdccsnduceceendansneescoweey AA ALE EEE aE EAEE a TERN 15 Experiment type CharacteniStiCs sero aara ea aa araea an E aAa eaaa eaa eaa rT I 16 Statistical measures for an UNC_MC experiment eee eeeeeeeenne ee eeeeeeeeeeaeeeseeaaeeeeneeeeesaeeeeeeaeeeeeneeeee 25 Probability density functions 200 0 eee cece cece cece ee eeene cece ee ee eee ae ce ee cece ceaaaeaeeeeeeeeseceeaaeeeeeeeseseeaaeeeeeseeceaaeeeeeeeeeeeeea 26 Local sensitivity linearity and symmetry MEASUFES 2 00 eee c cence cena eter eae eeeeeaaeee tees ee
44. 109 abs arg1 absolute value dim arg1 arg2 positive difference exp arg1 exponential function int arg1 integer truncation value log arg1 natural logarithm log10 arg1 decade logarithm mod arg1 arg2 remainder nint arg1 nearest integer value sign arg1 sign of value round int_arg1 int_arg2 round value arg2 to int_arg1 decimal places sqrt arg1 square root Trigonometric operators Tab 8 4 on page 109 sin arg1 sine cos arg1 cosine tan arg1 tangent cot arg1 cotangent asin arg1 arc sine acos arg1 arc cosine atan arg1 arc tangent acot arg1 arc cotangent sinh arg1 hyperbolic sine cosh arg1 hyperbolic cosine tanh arg1 hyperbolic tangent coth arg1 hyperbolic cotangent rn m 218 y H Es f Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Name See Meaning Advanced operators Tab 8 8 on page 113 classify int_arg1 real_arg2 real_arg3 arg4 classification of arg4 into int_arg1 classes clip char_arg1 arg2 clip arg2 according to char_arg1 cumul char_arg1 arg2 cumulates arg2 according to char_arg1 distr_par char_arg1 int_arg2 get distribution parameter int_arg2 of factor char_arg1 flip char_arg1 arg2 flip arg2 according to char_arg1 get_data char_arg1 char_arg2 char_arg3 arg4 get data from an external file get_experiment char_arg1 char_arg
45. 38 125 8 0 125 Multiple setting case settings 3 data files for the likelihood function for setting 1 file If1 dat_s_1 same as If1 dat see lt model gt run for setting 2 file If1 dat_s 2 10 values in total and no data values likelihood function If1 is not used for setting 2 10 nodata for setting 3 file If1 dat_s_3 10 values in total and values for v1 1 Silt oil Osaka 9 nodata file If2 dat_s_ 1 same as If2 dat see lt model gt run file If2 dat_s 2 5 values in total and data values for v2 3 2 nodata 223 3 03223 2 nodata file If2 dat_s_3 5 values in total and data values for v2 5 4 nodata 5292 9 05325 Example 6 11 Data files for the likelihood function of a BAY_BC experiment Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 6 8 Optimization Simulated Annealing OPT_SA The experiment specific information for experiment description files in Tab 6 1 on page 63 is defined for a LSA experiment as follows Tab 6 12 Experiment specific elements of an edf file for OPT_SA Max Keyword Name k Sub Line ine Value Explanation eyword type nmb factor lt factor_ sample m 1 lt real_val gt lower bound lt real_val gt and name gt lt real_val2 gt upper bound lt real_valz gt to define the factor range where the cost function is to be mini mized on lt real_val gt lt lt real_val gt Values
46. 6 1 1 on page 65 6 7 1 Bayesian Calibration Description File lt model gt bdf Tab 6 11 Elements of a BAY_BC bdf file Max Keyword Name k Sub Line Tine Value Explanation eyword type nmb general lt nil gt descr 0 any lt string gt overall likelihood descriptions method m 1 metropolis_ Markov chain Monte Carlo standard MCMC method to use metropolis _ reflected cov_matrix o 1 file lt directory gt lower triangular matrix includ lt file_name gt ing diagonal of factor covari ances jump_length o 1 lt real_val gt modifier for the length of the multivariate normal jump lt real_val gt gt 0 settings m 1 lt int_val gt number of settings for a multi ple setting BAY_BC experi ment lt int_val gt 2 1 likelihood lt symbolic_ descr 0 1 lt string gt likelihood descriptions likelihood_ model_output m 21 lt result gt likelihood function model out name gt put part A result of any dimensionality formed according to the rules of the SimEnv post processor Result definition can be ar ranged at a series of function lines in analogy to the rules for result expressions cf Section 8 1 1 data m 1 file lt directory gt likelihood function data part lt file_name gt The name of an ASCII file that holds the measurement val ues averages and the corre sponding errors variances S oa Multi Run Simulation Environment
47. 6 EXPERIMENT PREPARATION 2 cicsoccsecticcshesacestnecsidecnacdveeshpeaues iani aA E EEEE EEEE ET aE 6 1 General Approach Experiment Description File lt model gt edf 0 ccc ceeeseeeeeeeeeceenneeeeeeeeeeseeeeeeenaeeeeeneaees 63 6 1 1 Elements of lt model gt edf for Experiment Types with Probabilistic Sampling ceceeeeeeeeeeeeeeeeee 65 6 2 Global Sensitivity Analysis Elementary Effects Method GSA_EE ooo ecceeeeneeeeeeeeeeeeneeeeeenaeeeeeeaeees 69 6 2 1 Special Features in GSA_EE Run Sequence eee eeeeeeeeceenneeeeeeeeeeeeeaeeeeeeaeeeeseneeeeesneeeeeenaeeeeeenaees 70 6 2 2 Exam ples o cc5eche5 iene E EE E iors shops ie ibaa be aes Se A EA EE 70 6 3 Global Sensitivity Analysis Variance Based Method GSA_VB eccsceeeeeeeeenneeeeeeeeeeenneeeeeenaeeeeeneeees 71 6 3 1 RUM SEQUOMCE E sate cteshene dts acres adugstuesducavaadcicstarseecssesntue ausceeenabseeessenseatealbecesensaneteseubeasenecdusabenetssee T1 6 3 2 sb 100 9 lt Ree ere ee or enis e rere ES E A EEE e A epee emer rte ee rer EE eA E T2 6 4 Deterministic Factorial Design DFD 00 0 2 cece cece ceeeeeeeeene cece ee ee ceca eens ee eeeeeeceeeaeeeeeeeseseneaeaeeeeeseseeeeeeeeeeeeeeea T3 6 4 1 Formalisation of the Inspection Strategy Run Sequence 00 eee ee eeneeeeeereeeteneeeeeeaeeeeeeaeeeenneeeeneas 73 6 4 2 Example aac acct aep cata cdeuiete O r a a A N 75 6 5 Uncertainty Analysis Monte Carlo Method UNC_MC ssessssssiesiiiissirssrirssiinres
48. 7 1 lt model gt cfg will be checked anew for experiment restart Do not change for a restart any of the infor mation related to the keyword model in lt model gt cfg Minutes of the restarted experiment will be appended to the log files lt model gt mlog lt model gt nlog and lt model gt elog respectively from the interrupted experiment Restart can be applied to an experiment several times successively Experiment restart can be performed also as a partial experiment independently on the partial status of the original model Experiment re start is not possible for the experiment types UNC_MC with stopping rule BAY_BC and OPT_SA For the model world_sh cf Example 15 10 on page 208 the following contents could be defined for the restart shell script world_sh rst bin sh perform always and as the first SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_ini_sh get run number SE_HOME bin simenv_get_run_sh remove all files from the temporary directory and the directory itself if test d run simenv_run_char then ie ielx run simenv_run_char fa perform always and as the last SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_end_sh Example file world_sh rst Example 7 6 Shell script lt model gt rst to prepare model performance during experiment restart 7 5 Experiment Partial Performance SimEnv enables to perform
49. Definition File lt model gt mac e In experiment post processing a macro is an abbreviation for a result expression consisting of an opera tor chain applied on operands Generally they are model related and they are defined by the user Macros are identified in experiment post processing expressions by the suffix _m e A macro is plugged into a result expression by putting it into parentheses during parsing Example equ_100yrs_m test_mac m from Example 8 17 below is identical to avg atmo c 20 20 c 1 c 11 20 400 1 2 3 4 e Macros must not contain macros e Use simenv chk to check macros During the macro check validity of the following information is not checked e Un pre defined character arguments of built in operators cf Tab 15 10 e Integer or real constant arguments of built in operators cf Tab 15 11 e Character arguments of user defined operators e Operators with respect to dimensionality and dimensions of its operands In SimEnv macros are defined in the file lt model gt mac lt model gt mac is an ASCII file that follows the coding rules in Section 11 1 on page 169 with the keywords names sub keywords and values as in Tab 8 22 lt model gt mac describes the user defined macros SAA 146 3 HN aP yh lt Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Tab 8 22 Elements of a macro description file lt model gt mac Sub Line Max Keyword Name k
50. I 209 15 2 13 Semi Automated Model Interface at Shell Script Level Assume any experiment Assume model executable world_sh to take factor values p1 to p4 as arguments from the command line The shell script world_sh_auto run with a semi automated interface at shell script level to run the model world_sh and to transform model output to SimEnv could look like bin sh pl 1 p2 2 POSF p4 4 perform dot script EVO aaO SE for semi automated model interface at shell script level alternatively perform dot script SE_HOME bin simenv_ini_sh SSE _WS world_sh_auto_sh inc create temporary directory run lt simenv_run_char gt to perform the model and model output transformation from native to SimEnv structure there mkdir run simenv_run_char cd run simenv_run_char run the model cp land_sea_mask coarsed world_sh pl p2 p3 p4 read model results and output them to SimEnv world shput clear and remove directory Gel 5 5 rm fR run simenv_run_char perform always and as the last SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_end_sh Example file world_sh_auto run Example 15 12 Semi automated model interface at shell script level model shell script world_sh_auto run aA 3 210 v HN ia ii lt Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 3 Example Implementation for t
51. Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 4 Example for an Experiment Post Processor Result Import Interface In Example 15 15 an implementation of an interface to import ASCII post processor output from SimEnv can be found A corresponding interface to import IEEE compliant post processor output is documented subroutine read_result_file_ascii model_name res_nmb character model _name 20 res_ nmb 2 real 4 pointer dimension 83 coomd values real 4 pointer dimenston 42 result values integer 4 idim iext 9 Chicwecrcie wesc Geo Gilt iwesulle Cosel iaSswilic woe sz character coord name 20 open unit l file trim model iene inf res nmb ascii torm Srormattcedi sratus voldi open unit 2 file trim model_name res res_nmb ascii form formatted status old iostat 0 do while iostat eq 0 reedy asiz sO Sic ate io siecle result Sgor if iostat eq 0 then readh a126 p LOsicelie alosicenel rset cese reedi a32 l06tat icstatl resule wine read 1 1018 iostat iostatl idim iext i i 1 9 length_result 1 do i 1 idim length eres the Vengthgerestmilbt e read 1 a2 0 7 tostat lositatl coord mame allocate coord values iext i ibeg 1 do whil ibeg le iext i iend min0 ibeg 9 iext i reeC L a GRO Gallary Ma uO Sitcate sO s tales mn COomC eR alaTesa aE
52. SimEnv User Guide in pdf exa SimEnv examples as used in the User Guide Version repository of SimEnv at PIK version_archive SimEnv version archive Version lt x yz gt is located in a sub folder lt x yz gt and structured in this sub folder in the same manner as the latest version 15 1 1 System Requirements Tab 15 2 System requirements for running SimEnv Specification Component Unix Linux hardware IBM RS6000 and compatibles Intel based systems and compati bles with regular 32 bit or 64 bit processors i386 operating system AIX Version 4 3 any distribution with the Linux http Awww 03 ibm com servers aix kernel shell Bourne shell sh Python Version 2 3 http Awww python org NetCDF Version 3 6 0 http www unidata ucar edu packages netcdf Fortran compiler xlf Version 8 0 Intel ifort Version 10 0 IBM Fortran compiler http www intel com cd software pr http Awww 306 ibm com oducts asmo na eng 282048 htm software awdtools fortran xifortran or gfortran Version 4 2 GNU Fortran 95 compiler http gcc gnu org C C compiler xlc Version 7 0 gcc Version 3 3 IBM C C compiler GNU C C compiler http www 306 ibm com http gcc gnu org software awdtools xlcpp For the compiler the symbolic link cc is used i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H i 189 Specification Component Unix Linux MPI Version 1
53. Version 3 01 July 10 2012 10 3 Experiment Performance Tuning SimEnv allows for a bunch of settings that influence in terms of CPU time the performance of the single simulation runs and their communication with the simulation environment In particular these are The model output format as specified in the general configuration file lt model gt cfg by model out_format netcdf ieee Model output to compliant IEEE format is faster than to NetCDF format Nevertheless NetCDF comes with all the advantages of a self describing data format A lumped experiment output into a common file or into an individual model output file for each single run as specified in the general configuration file lt model gt cfg by model out_separation yes no Experiment output to individual model output files is faster than to a lumped file Nevertheless for a moderate model output size per single run a compact output into a lumped file is more convenient Using slices as specified in the general configuration file lt model gt cfg by model slices no f_c py_ja_m and in the interfaced model source code by the SimEnv interface function simenv_slice_ Not applying slices is faster than applying them for Fortran or C C models Compared to Fortran or C C models applying slices for Python Java or Matlab models increases model run time significantly Nevertheless for models that store a multi dimensional model output field in a lower dimensional array t
54. all optional GAMS sub models are stored in the current workspace the SimEnv services simenv chk run rst are started from Therefore two additional include statements have to be inserted into those GAMS model source code files where experiment factors are to be adjusted or model variables are to be output to SimEnv GAMS model source code files to be interfaced to SimEnv are one GAMS main model and optionally a number of GAMS sub models that are called directly from the GAMS main model Additional GAMS sub programs included files are not affected by SimEnv but one should keep in mind that the GAMS code within SimEnv will be TVR 46 J HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 executed in a sub directory of the current workspace see below and so the include statements have to be changed if the files are addressed in a relative manner see below The include files are lt model gt _simenv_get inc lt model gt _simenv_put inc During experiment preparation the file lt model gt _simenv_put inc and during experiment performance files lt model gt _simenv_get inc are generated automatically to forward GAMS model output to SimEnv data structures and to adjust investigated experiment factors respectively These include files correspond to the simenv_put and simenv_get model interface functions at the lan guage level cf Sections 5 4 and 5 5 The GAMS include statem
55. all statements e g clearall that clear the model variables have to be deleted from the original model source code simenv_put function For the Mathematica model interface a dedicated simenv_put function does not exist SimEnv expects the Mathematica model to write model output to external files These files can be transferred into SimEnv model output by writing a specific simenv_put_sh executable cf Section 5 8 or for ASCII model output files by applying simenv_put_as _simple cf Section 5 9 Both interfaces have to be incorporated into lt model gt run lt model gt edf While normally for the model interface the names of corresponding factors in the model description file lt model gt edf and the model source code can differ and are associated by the first argument of the interface function simenv_put_ cf Fig 5 1 the names have to coincide for the Mathematica model interface Since in Mathematica variables are case sensitive they have to be declared in the experiment description file lt model gt edf also in a case sensitive manner An example for lt model gt run can be found in Example 15 8 5 7 Model Interface for GAMS Models SimEnv allows to interface GAMS models to the experiment shell A GAMS main model interfaced to SimEnv can call GAMS sub models SimEnv expects that the GAMS main model e is located in the file lt model gt gms where lt model gt is the model name a SimEnv service is started with e and
56. an experiment partially by performing only a run slice out of the whole run ensemble Therefor assign appropriate run numbers to the corresponding sub keywords begin_run end_run include_runs exclude_runs in lt model gt cfg check Section 10 1 A partial experiment performance is also possible for an experiment restart Experiment partial performance is not possible for the experiment types UNC_MC with a stopping func tion BAY_BC and OPT_SA For more information check Fig 7 1 Oe 96 y HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 7 6 Experiment Related User Shell Scripts and Files Tab 7 1 Experiment related user shell scripts and files Shell script file Explanation Used for Exist status Shell scripts terminal output is re directed to lt model gt nlog lt model gt run model shell script to wrap the model executable Model interface dot scripts at shell script level simenv_ sh can have to be applied in lt model gt run e SE_HOME bin simenv_ini_sh has to be performed al ways and as the first SimEnv dot script simenv_ _sh e SE_HOME bin simenv_end_sh has to be performed always and as the last SimEnv dot script simenv_ _sh mandatory lt model gt rst model shell script to prepare single model run restart for such single runs that were started but not finished during
57. and stat_red have the postfix _e e All UNC_MC operators are also available for all other experiment types Keep in mind that in general the samples from these experiment types do not follow any distribution e The operators stat_full and stat_red supply basic statistical measures for their last argument Both operators are stand alone operators They must not be operands of any other operator Contrary their last argument can be composed from other non multi run operators To store the statistical measures dimensionality of both operators is that of their last argument appended by an additional dimension with an extent of 10 and or 7 Appended coordinate description is pre defined by SimEnv cf Tab 10 11 These ten data fields for operator stat_full and or seven data fields operator stat_red correspond to the following statistical measures Deterministic run run number 0 Run ensemble minimum Run ensemble maximum Run ensemble mean Run ensemble variance Run ensemble positive distance of confidence measure from run ensemble mean for a probability of error real_arg1 7 Run ensemble positive distance of confidence measure from run ensemble mean for a probability of error real_arg2 Only for operator stat_full 8 Run ensemble median 9 Run ensemble quantile for quantile value real_arg3 10 Run ensemble quantile for quantile value real_arg4 OuRWN gt Both operators were designed for application of an appropriate visualizatio
58. argument arg2 from the first addressed index position up to the current index position With the character argument char_arg1 those dimensions are identified that are to be cumulated Character 1 at position i means cumulation across dimension i while a 0 stands for no accumulation cumul 0 0 arg2 results in the identity to arg2 The operator distr_par is applicable for all experiment types that demand explicitly a probabilistic sam pling scheme experiment types GSA_EE GSA_VB UNC_MC and BAY_BC The operator provides the value of a distribution parameter of a factor as specified in the experiment description file lt model gt edf The operator is not applicable to factors where the sample is imported from a file The operator flip enables flipping of variable fields For a one dimensional field a vector flip changes the value of the first index position with the value of the last position the value of the second position with that of the last but one position etc With the character argument char_arg1 these dimensions are identified that are due to flip Character 1 at position i means flipping also for dimension i while a O stands for no flipping at this dimension Flipping includes adaptation of coordinates and the assigned grid flip 0 0 arg2 results in the identity to arg2 With the operator get_data data from external files can be included in post processing Character ar gument char_arg1 specifies the data file format
59. arguments lt model gt odf is evaluated to check a user defined and or composed operator syntactically when performing it during experiment post processing Tab 8 21 Elements of an operator description file lt model gt odf Max Keyword Name aup Line iine Values Explanation keyword type nmb general lt nil gt descr o any lt string gt general operator descriptions opr_ lt user_ descr 0 1 lt string gt operator description defined defined_ arguments m 1 lt int_val gt number of arguments defined operator_ lt int_val gt for the operator name gt lt int_val3 gt lt int_val gt 2 0 lt int_val gt character arguments lt int_val gt 2 0 integer constant arguments lt int_val3 gt 2 0 real constant arguments lt int_val gt gt 0 normal arguments opr_ lt composed_ descr o 1 lt string gt operator description composed operator_ arguments m 1 lt int_val gt number of arguments defined name gt lt int_valo gt for the operator lt int_val gt Explanations and restrictions lt int_val gt are the same as for a user defined operator define m 21 lt string gt operator definition string Operator definition can be arranged at a series of define lines in analogy to the rules for result expressions cf Section 8 1 1 To Tab 8 21 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e
60. assumed that the variance of the stopping function does not change anymore significantly after the point of change The first half of the simulation runs of the experiment is performed without applying the test in order to generate a stabilized stopping function sample res z The whole experiment is stopped if e the level of significance of the Pettitt test is below 0 05 for the already performed run ensemble and e there were at least lt int_val gt 5 single runs after that single run that represents the point of change lt int_val gt is the number of declared runs in lt model gt edf see above The latter condition is introduced to avoid to run into a local point of change UNC_MC experiments with a stopping function cannot be re started Partial experiment performance is not supported Consequently in the configuration file lt model gt cfg sub keywords begin_run end_run in clude_runs exclude_runs are not allowed for an experiment with a stopping function The stopping condi tion is reported to the experiment log file lt model gt elog 5a Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji _ ff 6 5 2 Example general descr Experiment description for the examples general descr in the SimEnv User Guide general type UNC_MC factor pl descr parameter pl factor pl unit without factor pl type add factor pl d
61. char_arg1 arg2 absolute sensitivity measure sens_rel char_arg1 arg2 relative sensitivity measure sym_abs char_arg1 arg2 absolute symmetry measure sym_rel char_arg1 arg2 relative symmetry measure Multi run operators UNC_MC also applicable for all other experiment types Tab 8 13 on page 130 avg_e arg1 run ensemble mean avgg_e arg1 run ensemble geometric mean avgh_e arg1 run ensemble harmonic mean avgw_e arg1 arg2 run ensemble weighted mean cnf_e real_arg1 arg2 positive distance of confidence line from run ensemble mean avg_e arg2 cor_e arg1 arg2 run ensemble correlation coefficient between arg1 and arg2 count_e char_arg1 arg2 run ensemble count number of values cov_e arg1 arg2 run ensemble covariance between arg1 and arg2 ens arg1 whole run ensemble hgr_e char_arg1 int_arg2 real_arg3 real_arg4 arg5 heuristic probability density function Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Name Meaning See krt_e arg1 max_e arg1 run ensemble kurtosis 4 moment run ensemble maximum maxprop_e arg1 run number where the maximum is reached the first time med_e arg1 run ensemble median min_e arg1 run ensemble minimum minprop_e arg1 run number where the minimum is reached the first time qnt_e real_arg1 arg2 r
62. codes are 0 For Matlab models Replace in the model source code the Matlab function names simenv_ ini get_run get slice put end _m by simenvdummy_ ini get_run get slice put end _m From these functions e simenvdummy_get_py forwards factor_def_val to factor_adj_val e simenvdummy_get_run_py returns run 000000 e all other SimEnv model interface function values return codes are 0 For Mathematica models No changes required For GAMS models Handle in the model source code the include statements e include lt model gt _simenv_get inc e include lt model gt _simenv_put inc as a comment T AAR Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN aP J 61 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 6 Experiment Preparation Experiment preparation is the first step in experiment performance of a model interfaced to the envi ronment In an experiment description file lt model gt edf all information to the selected experiment type and its numerical equipment is gathered in a structured way 6 1 Pre formed experiment types are the backbone of the SimEnv approach how to use models They represent in a generic way experiment tasks that have to be equipped with structural in formation from the model and numerical information cf Chapter 4 An equipped experiment type is represented by an experiment de scriptio
63. consisting only of nodata elements for those settings where an individual likeli hood is not be applied To interface the model to SimEnv for the multiple setting case the model wrap shell script lt model gt run is used that represents a single model run Since a single run for the multiple setting case is a sequence of individual single runs over all settings SimEnv provides a method how to deal with this feature instead of Instead of directly calling the model within lt model gt run the shell script SE_HOME bin simenv_bay_bc_sh lt adapt_and_perform_setting_script gt is called It has one argument lt adapt_and_perform_setting_script gt The argument is the name of a shell script where the adaptation of the model to one individual setting and afterwards the performance of the adapted model for this individual setting have to be implemented Within the shell script the operating system environment variable SE_BAY_BC_SETTING is defined Its value is the number of the current setting It has to be used for the adaptation As usual the dot scripts SE_HOME bin simenv_ini_sh and SE_HOME bin simenv_end_sh have to be applied in lt model gt run Dot scripts SE_HOME bin simenv_get_sh and SE_HOME bin simenv_get_run_sh can be applied in lt adapt_and_perform_setting_script gt If so take care to _ perform SE_HOME bin simenv_ini_sh before SE_HOME bin simenv_end_sh must not be applied in lt adapt_and_perform_setting_script gt OAL
64. coordinate values the coordinate is de fined for a subset is assigned to the extent of the dimension of the variable Variables of dimensionality 0 do not have a coordinate assignment A variable of dimensionality n corresponds to an n dimensional array a variable of dimensionality 0 is a sca lar coord coord coord Rectilinear grid supported by SimEnv Curvilinear grid not supported by SimEnv Fig 5 2 Grid types Additionally coordinate axes are defined Each coordinate axis a strictly monotonic sequence of coordinate values a description and a unit is assigned to For reasons of simplification in experiment post processing coordinate axes are assumed as curvilinear Each dimension of a variable with a dimensionality gt 0 a complete coordinate axis or a part of a coordinate axis is assigned to Consequently each variable with a dimensionality gt 0 is defined on a coordinate system formed from the assigned coordinates For reasons of simplification in result evaluation with visualization techniques coordinate systems are assumed as rectilinear orthogonal with variable distances between ad jacent coordinate values The model output variable values then exist on the grid spanned up from the co ordinate values of the coordinate axes cf Fig 5 2 Since coordinate axes can be assigned to model output variable dimensions in a flexible manner model output variables can exist on the same coordinate system or comple
65. de scribed by the names of the involved factors their numerical sampling values and their combination scan ning method Experiment post processing can resolve the scanning method again and output results as projections on multi dimensional factor subspaces Fig 4 6 describes the regular scanning technique by an example In the left scheme a the two dimensional factor space X2 p1 p2 is scanned combinatorially resulting in 4 4 16 model runs while the middle scheme b represents a parallel scanning of these two factors at the diagonal by 1 1 1 1 4 model runs The scheme c at the right side shows a complex scanning strategy of the 3 dimensional factor space X3 P1 P2 p3 with 1 1 1 1 3 12 model runs Each filled cross x in Fig 4 6 represents a sample point in the factor space and finally a single model run of the experiment X 2 E x 1 ot 1 ot x I ot 1 ot I l p b Fig 4 6 Deterministic Factorial Design DFD Scanning multi dimensional factor spaces AS Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji 23 4 5 Uncertainty Analysis Monte Carlo Method UNC_MC Monte Carlo analysis UNC_MC uses a non deterministic strategy to sample Xn An UNC_MC experiment in SimEnv is a perturbation analysis with pre experiment factor perturbations x X212 sub sample of size 12 in the 2 dimensional factor
66. default nominal numerical factor constellation of model M x4 Fig 4 1 Factor space SimEnv supports different sampling strategies and the performance of multi run experiments where k factors are adjusted numerically for each of n single simulation runs according the generated sample and the default nominal values of the factors Central goal is to study the dependency of the model dynamics in the factor space For simulation purposes in SimEnv experimentation with the model M over X is based on the as sumption that dynamics of M for each representative from the sample is independent from all other repre sentatives which is fulfilled in general This results in the possibility to form a run ensemble for performing the model M with n single model runs from the sample Xx n gt a 14 y HN E i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 SimEnv experiment types differ in the way the sample space X is sampled to get X There are determinis tic and probabilistic sampling strategies that offer a broad range of techniques for e Experimentation with models e Post processing experiment output e Interpreting results with respect to uncertainty and sensitivity matters of models The experiment types are described in detail in the following Sections Tab 4 1 provides an overview on the experiment types Is is ordered in a sequence which may for many cases is well suited for a
67. dim res name bin_mid values equidist_end 1 bin mid bin width number of bins char_arg1 bin_no bin_mid int_arg2 number of bins 4 lt int_arg2 lt number_of_runs or 0 automatic determination max 4 number_of_runs 10 real_arg3 left bin bound for bin number 1 real_arg4 right bin bound for bin number arg2 real_arg3 real_arg4 0 determine bounds by min_e arg5 and max_e arg5 min_e arg5 max_e arg5 all result values are undefined count_e run ensemble number of values 1 char_arg1 arg1 all def arg2 undef maxprop_e return the run number where the 1 arg1 maximum is reached the first processing sequence time starts with run number 1 rn m 130 y H Es j J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Argument restriction s Argument value ama meaning result description restriction Tab 8 1 page 106 minprop_e return the run number where the 1 arg1 minimum is reached the first time processing sequence starts with run number 1 cnf_e run ensemble positive distance of 1 arg1 0 001 0 01 real_arg1 confidence measure from real_arg1 probability of 0 05 0 1 arg2 avg_e arg2 error core run ensemble correlation coeffi arg1 f 2 1 cient between arg1 and arg2 arg2 cov_e run ensemble covariance be arg1 tween arg1 and arg2 21 arg2 ens run ensemble values 6 arg1 dim res dim arg1 1 e
68. dimensional DFD yes levels global yes design depend multi dimensional ent UNC_MC yes distributions global yes Nuct1 multi dimensional LSA yes levels local no 2 k 1 BAY_BC yes distributions global yes Nuct1 N gt gt 0 multi dimensional OPT_SA yes distributions global yes unpredictable multi dimensional 4 2 Global Sensitivity Analysis Elementary Effects Method GSA_EE The guiding philosophy of a GSA_EE experiment is to determine those factors that influence a model state z the most and to distinguish them from factors that are negligible Contrary to a local sensitivity analysis LSA during this experiment type the entire space where the factors may vary is considered The GSA_EE experiment in SimEnv applies the method of Morris 1991 in its modifications by Campolongo et al 2005 Saltelli et al 2008 and Sin amp Gernaey 2009 Its main approach is to derive qualitative global sensitivity measures for all factors by computing a statistics on a set of local sensitivity measures the so called elementary effects The result of this analysis is a ranking of the factors in terms of their importance with respect to the model state z The modified Morris method is as follows cf also Fig 4 2 e Specify for each factor x i 1 k a distribution with its distribution parameters e Span up in the factor space X a k dimensional p level grid by determining for each factor x p equidistan
69. e f character and integer real constant arguments are defined for an operator then there is always the following sequence of the operator arguments char_arg int_arg real_arg arg Example hgr_1 1000 bin mid 20 0 0 atmo Operators are generic with respect to the data types of their operands Each non character and non constant argument can be used with operands of all defined data types cf Section 5 1 Internally ar guments of any type are converted to a float representation This may lead to undefined arguments of type double in float representation Results of SimEnv experiment post processing operators are always of the type float SimEnv post processing follows the standard approach for description of operators for basic as well as advanced built in or user defined operators Advanced built in or user defined operators e Have a unique name and a number of operands e The sequence of operands is enclosed in parentheses directly after the operator name e Operands are separated from each other by a comma e Recursions of the same operator also for user defined operators are possible Example log10 min_n 3 min_n logl0 atmo 1 c 20 400 10 bios_g Elemental operators use the common form of notation Example atmo_g 345 lt IAE Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f ii _ 105 8 1 5 Operator Classification Flexible Coordinate Checking
70. ee eeeeeeae cece ee seecaaeaeeeeesesecaeaeeeeeeeseecueaeeeeeeeeeea 127 Syntax of the filter argument 1 for Operator dfd oe eeeeeeeeeneeeeeeeaeeeeeneeeeesaeeeseeaeeeseneeeeneneeeesenaes 127 Experiment specific operators for UNC_MC ee eeceeeeeeeeeneeeeeeenaeeeeeeeeeeeenaeeeeeesaaeeeeseeaeeesnaeeeseenaeeeseaeees 130 Experiment specific Operators for LSA soc seis ccvneatn cet ecccpecracseeessasespcceusenunsanecegecaneeeescoeeesesteewncuecteeneedechvareeae 133 Syntax of the filter argument 1 for LSA eee ee eeeeeeeeeee ee eeneeeeeeaaeeeeeeaaeeeseneeeeeeaeeeseeaeeeeeneeeeniaeeeseeaaes 134 Experiment specific operators for BAY BC ee eeccceeecneeeeeeeeeeeeneeeeeeeaeeeeaeeeeeeaaeeeseeeaeeesneeeesenaeeeeeeeaeegs 136 Experiment specific operators for OPT _SA uu eeeesccceeseeeeeeeeeeeeeaeeeseeeaeeesaeeeeesaaeeeseeeeeeeseeeeeseaaeeeseaeess 137 Operator interface functions for the declarative and computational part ce eeceeeeeseeeeeeeeeeenteeeeeenaes 138 Operator interface functions to get and put structural information ee eeeeeeeeeeeeeeeeeeeseeeeeeeeneeeeeenaes 139 Operator interface functions to get check put arguments and results 142 Elements of an operator description file lt MOdel gt OCF 0 0 eeceeeeneeeeereeeeeeneeeeeeaeeeseeeeeeeeeeeeenenaeeeeeeeaeees 145 Elements of a macro description file lt moOdel gt MaC ccccceceeeeceeeceeeeeeeeeeeaeaeeeeeeeeeceeeaeeeeeeeseeensaeeeeeenes 147 Elements of the file simen
71. exclude intervals with the definition domain of the distribution for probabili ties gt 0 can be several non connected intervals to sample from Sample_include and sample_exclude can nor be used for distributions imported from files Keep in mind that the generated sample of factor values normally does no longer follow the statistical properties of the specified distribution when applying sample_include and or sample_exclude In particu lar moments will differ from those specified explicitly by the distribution parameters Re 66 J HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Sub keyword seed This sub keyword controls the seed of the used random number generator for implicitly specified distri butions distr lt distribution gt A random seed will result in different generated samples for repetitive per formance of the same experiment while with a fixed seed the generated samples will be identical also across different machines without taking into account numerical inconsistencies e g rounding errors If the sub keyword is not stated initial seed is set to random Tab 6 4 Probability density functions and their parameters Distribution distr_ aula function shortcut distr_param_1 distr_param_2 Restriction uniform U lower boundary upper boundary lower boundary lt upper boundary normal N mean value variance variance gt 0 lognormal L mean value
72. experiment post processing cf Section 8 5 4 e Assignment of coordinate axes to variable dimensions and consequently of a grid to a variable is only valid for experiment post processing Normally the simulation model itself will also exploit the same grid structure Nevertheless the grid structures of the model are defined autonomously in the model in an explicit or implicit manner and do only correspond to the grid structure in the model output description file symbolically e Model output variables with dimensionality 0 are not assigned to a coordinate axis e The values of a coordinate have to be ordered in a strictly monotonic sequence They may be non equidistant and may be ordered in a decreasing sequence e With the sub keyword coord_extents only a portion of coordinate values of a coordinate axis can be assigned to a dimension of a variable This portion is addressed by its begin and end value lt co_valj gt and or lt co_valiz gt The number of coordinates values of the portion has to be greater than 1 na 38 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 D1 AY lt co_val gt gt lt co_vali gt for strictly increasing values of coordinates lt co_val4 gt lt lt co_vali2 gt for strictly decreasing values of coordinates e With the sub keyword index_extents portions of variables are made addressable during SimEnv ex periment post processing In the same way multi dimen
73. fic current operator get_nr_arg_ flc function value Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Inputs Function Function toits Inputs outputs function value name description f SS PUS description unction value simenv_ iarg gt 0 integer 4 argument number 0 for result get_type_arg__ get data type of an iarg fic argument input iarg 0 integer 4 type of argument result iarg get data type of simenv_ 1 byte 4 float the result get_type_arg_ f 2 short 8 double function value 4 int simenv_ get level of coordi integer 4 level of coordinate check for arguments get_co_chk_ nate check for simenv_ 0 without modus _ arguments get_co_chk_ 1 weak fic according to modus_ 2 strong lt model gt cfg flc function value simenv_ get formal coordi integer 4 argument number get_co_arg_ nate numbers and iarg fic formal coordinate input begin value posi integer 4 formal numbers of the coordinates iarg tions of an argu ico_nr 9 ico_nr 1 ico_nr simenv_get_dim_ ico_nr ment output arg f c ico_beg_pos integer 4 formal begin value positions of the coordinates co_name ico_beg_pos 9 ico_beg_pos 1 ico_beg_pos simenv_get_dim_ output arg f c character 20 coordinate names co_name 9 co_name 1 co_name simenv_get_dim_ output arg f c i
74. for Version 3 01 July 10 2012 e A method supports the factor range of each factor globally if the method takes into account the whole range of the factor variation and for probabilistic methods where samples are taken from distributions the whole probability density function is explored e A method supports multi factor variation if it investigates into all factors rather than focusing on for instance turn on single factors The latter approach disregards interaction effects between factors on the model output and finally on the derived measures e Often modelers and or analysts are confronted with correlated factors Even if specification of an ex periment in SimEnv does not explicitly support correlated samples for example method UNC_MC it al lows to import such samples e The computational costs of a an experiment type is the number of single model runs necessary to perform the method Computational costs may limit applicability of an individual experiment type if the computational costs in terms of CPU or wall clock time consumption of a single simulation run are high Tab 4 2 Experiment type characteristics N denotes the number of Monte Carlo runs Experi Model Sampletaken Factorranges Copewi Computational ment type free from multi factor variation factors for k factors GSA_EE yes levels global no 10 k 1 1 multi dimensional GSA_VB yes distributions global no Nuc k 2 1 multi
75. for a parallel model Set the model sub keyword structure also to parallel if the model is to be started in the background e g by my_model amp within lt model gt run na En 60 v HN e J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 5 12 Using Interfaced Models outside SimEnv To run a model interfaced to SimEnv outside the simulation environment in its native mode as before code adaptation the following simple changes have to be applied to the model For Fortran and C C models Link the model with the object library SE_HOME lib libsimenvdummy a instead of SE_HOME lib libsimenv a For this library e SimEnv model interface function values return codes are 0 e simenv_get_ forwards factor_def_val to factor_adj_val e simenv_get_run_ returns integer run number 0 and character run string six spaces For Python models Replace in the model source code from simenv import by from simenvdummy import For this modules e simenv_get_py forwards factor_def_val to factor_adj_val e simenv_get_run_py returns run 000000 e all other SimEnv model interface function values return codes are 0 For Java models Replace in the model source code the class Simenv by the class Simenvdummy From this class e simenv_get_py forwards factor_def_val to factor_adj_val e simenv_get_run_py returns run 000000 e all other SimEnv model interface function values return
76. from its resulting ad justed value by at least one character space simenv_put_as and simenv_put_as_simple can be used to transfer ASCII model output to SimEnv model output data structures These are the only SimEnv scripts that can be used in lt model gt run that are shell scripts and not dot scripts Both they have two arguments The first argument specifies the ASCII file name that is to be transferred The second argument is the name of a coordinate as specified in lt model gt mdf Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Having a model output variable definition as in Example 5 1 on page 40 SE_HOME bin simenv_put_as atmo_g ascii time Since atmo_g is the only variable with time as the first coordinate the file atmo_g ascii can only hold this variable The 1 record of the file with data corresponds with time 1 the 20 record with data with time 20 There is only one column SE_HOME bin simenv_put_as bios ascii lat Assuming that variable atmo is not defined Since bios is the only variable with lat as the first coordinate the file bios ascii can only hold this variable The 1 record of the file with data corresponds with lat 84 the 36 record with data with lat 56 There are 90 20 1800 columns The file has to hold bios lat lon time in the following structure shown are the indices of bios co
77. fulfilled or the explicitly stated end run number from the sub keyword runs in lt model gt edf is reached e As results of an OPT_SA experiment the optimization return code the optimal factors the corresponding value of the cost function and the number of the corresponding single run are documented at the end of the file lt model gt fct e A protocol from the optimization procedure is made available by SimEnv in the ASCII file lt model gt olog 6 8 2 Example general descr Experiment description for the examples general descr in the SimEnv User Guide general type OPT_SA LEIC TOL pl descr parameter pl FECTOR pl unit without PEO CONE pl type set PACE ON pl default ig factor pl sample 12 12 minimize cost function for p1e lt 12 12 gt RACOR p2 type set factor p2 default 2 alee One p2 sample LLO factor Po type set IE EKO CONE pS default SS IEGYGIE OIE js sample A eZ factor p4 type set factor p4 default 4 bac BO p4 sample Le ile specific function sum bios maximize sum bios over land masses specific runs 500 Example file world edf_OPT_SA Example 6 12 Experiment description file lt model gt edf for OPT_SA e0 88 yi HN iat I i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 7 Experiment Performance After experiment preparation experiment performance is the second step in running a model inter faced to SimEnv Each multi run experim
78. gt nf_ lt string gt f2c_ lt string gt c2f_dimids cdf_routine_name read_numrecs write_numrecs Tab 15 13 lists these symbols subroutine function and common block names that are linked in addition to the SimEnv operator interface functions in Tab 8 19 and Tab 8 20 from the object library SE_HOME lib libsimenv a to a user defined experiment post processing operator Tab 15 13 Additionally used symbols for the operator interface Used symbols csimenv_ lt string gt isimenv_ lt string gt jsimenv_ lt string gt AAA Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i J _ 229 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 7 Glossary The glossary defines and or explains terms in that sense they are used in this User Guide An arrow gt refers to another term in the glossary Adjustment Numerical modification of a gt factor by one of its gt sampled values and its gt default value during an gt experiment The resulting adjusted value is used instead of the default value of the factor when running the model ASCII The American Standard Code for Information and Interchange developed by the American Na tional Standards Institute http Avww ansi org is used in SimEnv to store information in gt user defined files and on request in post processing output file
79. have to be specified in the table for result elements where no data values are associ ated with Use the float real 4 nodata value 3 4E 38 For data that are scarcely available compared to the number of result elements instead of specifying n succeeding nodata pairs 3 4E 38 3 4E 38 3 4E 38 3 4E 38 where 3 4E 38 is the float real 4 nodata undefined value representation see Tab 10 13 the shortcut n nodata with n 2 1 can be used Keep in mind that the prior distribution is only determined by the marginal factor distributions as defined in lt model gt edf If for a factor sample_include or sample_exclude intervals are defined that alter the definition domain of the probability they are used to check whether a candidate point is outranged In contrast the prior distribution of the factor is not changed by defining such intervals for a factor distribution 6 7 2 Bayesian Calibration log Files lt model gt blog and lt model gt bmlog During the random walk by the Metropolis Hastings algorithm a new candidate point in the factor space can be e outrange as it is outside the definition domain of the distribution of any factor and will be discarded afterwards For an outranged point a single simulation run will not be performed e rejected for a Metropolis ratio MR lt 1 a candidate is rejected with a probability of 1 MR For a rejected candidate point a single run was performed e accepted always for MR gt 1 or for MR lt 1 a candi
80. in result processing dfd sin amp v amp results in GEGA V Simler chel een eee CEOL E es iG heel Salina S61 dfd amp v amp amp amp results in ci Gea ceo oils GEES u No sE SiON CEC CA emo Gros eke 7 bios gol CHECI EOD CEES 7 losiosjo2 CEEA EM OMG SO elTe 7 bios goZ Example 8 18 Experiment post processing with wildcard operands 8 8 Undefined Results By performing operator chains and due to possibly unwritten model output during simulation parts of the intermediate and or final result values can be undefined within the float data representation If an operand is completely undefined the computation of the result is stopped without evaluating the follow ing operands and operators For undefined nodata value representation check Tab 10 13 8 9 Saving Results The result files lt model gt res lt simenv_res_char gt nc ieee ascii and lt model gt inf lt simenv_res_char gt ieee ascii contain all the model and experiment information for further processing of results Ae 148 y H Es f i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 9 Visual Experiment Evaluation Experiment evaluation in SimEnv is based on its visualization framework SimEnvVis The SimEnvVis approach is to apply visualization techniques to the output data derived during experiment post processing and stored in NetCDF fo
81. int_arg lt 6 round 1 2 34 arg2 decimal places 2 3 round 1 2 36 2 4 sign arg1 sign of value 1 sign 3 1 sign 0 O sign 3 1 sqrt arg1 square root 1 arg 20 sqrt 4 2 Trigonometric operators sin arg1 sine 1 sin 0 0 cos arg1 cosine 1 cos 0 1 tan arg1 tangent 1 arg TI 2tn T tan 0 0 cot arg1 cotangent 1 arg n Tr cot 1 5708 0 asin arg1 arc sine 1 abs arg1 lt 1 asin 0 0 acos arg1 arc cosine 1 abs arg1 lt 1 acos 1 0 atan arg1 arc tangent 1 atan 0 0 acot arg1 arc cotangent 1 acot 0 1 5708 sinh arg1 hyperbolic sine 1 sinh 0 0 cosh arg1 hyperbolic cosine 1 cosh 0 1 tanh arg1 hyperbolic tangent 1 tanh 0 0 coth arg1 hyperbolic cotangent 1 arg1 0 coth 3 1416 1 F m Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H i f V 109 The following explanations hold for the operators in Tab 8 4 e All operators are applied to each element of the argument s These operators deal with an unfulfilled argument value restriction for an operand element in a way that the corresponding element of the opera tor result will be undefined e For examples check Section 8 3 5 8 3 3 Standard Aggregation Moment Operators The generic standard aggregation moment operators in Tab 8 2 can be applied during experiment post processing to derive aggregations and moments from operands in different ways by ap
82. k value8 0 indi _defined 0 do 1 1 iextl1 2 ral iargl ortar iL walesxie ll 1 ia2 iarg2_offs l facl simenv_get_arg_ f 1 ial1 fac2 simenv_get_arg f 2 1a2 if simenv_chk_undef f facl simenv_chk_ undef f fac2 eq 0 then gt By H S iy v Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 indi _defined 1 r8facl facl r8fac2 fac2 value8 value8t r8facl r8fac2 endif enddo m m 1 alae alae cerime ec 0 rhen res m simenv_put_undef f else res m Ssimenv clip undef f values endif enddo enddo CG rerum error Goce simenv_compute_user def operator 0 ISELIN end Example file usr_opr_matmul_f f Example 15 13 Experiment post processor user defined operator module operator matmul_f amp ora Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 JHN a J ji lt 213 15 3 2 C Implementation Implementation of the user defined operator matmul_c in the file usr_opr_matmul_c c include lt strings h gt include lt stdio h gt rioclade eimen opr cino 1e compile wito S S HH OMB Toe 29 int simenv_check_user_def_operator int iext1 9 iext2 9 ime Leo mrig ieo mie galC beg posle 1e beg joosZ S 7 char co_namel 180 co_name2 180 int idimensl idimens2 int ichk_modus int iret iretvl iretv2 j iok ierror 0 float valuel value2 get dimensionality i
83. lensedeauessvelancbedesaeuaniersevscgenn geese 102 8 1 3 Modell Output Variables aaier enr acces sh cvece ett dane era aai a a E N 103 8 1 4 OPGRALONS A E E E A E E redbesesnuseensuanasstetaceermdeers 105 8 1 5 Operator Classification Flexible Coordinate Checking eeeessesrissrsiiesriireerrssrrirssrirreerinnssinnnrrenns 106 8 2 Built In Generic Standard Aggregation Moment Operators 2 00 0 eeeseeeeeeeeeeeenneeeeeeeeeeeseeeeeeeaeeeeeeaeees 108 8 3 Built In Elemental Basic and Advanced Operators ccccccccccecesceeeeeeeeeeneeeeeeeeeseeaeeeeeeeeeeenceaeeeeeeeeeea 108 8 3 1 Elemental Operators abies case hag dae a specs ve eee eaten ev ecg cade eee ct a eae tacad 108 8 3 2 Basic and Trigonometric Operators eee eeeneeee cence eeeeneeeeeeaaeeeceneeeeeeaeeeeesaaeeeseeeeeeesnaeeeesenaeeeeeaeees 109 8 3 3 Standard Aggregation Moment Operators 0 00 0 eeeeeeee sence ee enneeeeeeeaeeeeeeeeeeeaeeesesaeeeenneeeeeenaeeeeneaas 110 8 3 4 Advanced Operators acciri poses edewnsecsseesloenaredeteeadegstes dence crsectebetinend eevedgeeke aveNeeeeste 113 8 3 5 EEX IM PICS iaancssoxecesnecstencncisceantecctenas sapeqtcain te A tended eanedaeteadsarteate 4121 8 4 Built In Experiment Specific Operators eee eeeeeeeeeeeeeeeeeneeeeeeaeeeseeeaeeeeeaeeeeesaaeeeseeeaeeeseeeeeneeeseeeaeens 123 8 4 1 Multi ruin Op rators z cacnciceccessieececesectessceascneeesentaasseenstensnertesedexsnnsecnennuas de EEN Eet SEEE aaa rdar pA Eraird Eate i 123 8 4 2 Glob
84. level 4x4 4 1 7 11 16 20 world_as ASCII 4x4 4 1 7 11 16 20 world_f_auto Fortran 4x4 4 1 7 11 16 20 world _sh_auto Shell script level 4x4 4 1 7 11 16 20 world f 1x1 Fortran 1x1 16 1 16 20 world f 05x05 Fortran 0 5 x 0 5 16 1 16 20 gridcell_f Fortran without implicitly by 4 1 7 11 16 20 experiment as 4 x 4 Examples in this document are generally placed in grey shaded boxes Examples that are available from the example directory SE_HOME exa of SimEnv are marked as such in the lower right corner of an example box To copy files from this directory use the SimEnv ser vice simenv cpy cf Tab 10 4 Example 1 1 General example layout in the User Guide For Mathematica and GAMS models see Sections 5 6 and 5 7 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 2 Getting Started In this chapter a quick start tour is described Without going into details the user can get an impres sion how to apply SimEnv and which files are essential to use the simulation environment e SimEnv is implemented under AlX Unix at IBM s RS6000 and compatibles and SUSE Linux at Intel based platforms and compatibles For detailed system requirements check Tab 15 2 on page 189 e Set the SimEnv home directory SE_HOME and expand the PATH environment variable in the file HOME profile by SE_HOME bin export SE_HOME lt se_home_path gt export PATH SE_HOME bin P
85. lt factor_name gt are from the re sample all runs but the sample and the re sample Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 are taken into account The selected case is active until a new selection is made The default value when starting the post processor is set to sample resample Keep in mind that only the resulting runs of the first three cases follow the distributions as specified in lt model gt edf by the sub keywords sample Generally for the remaining cases the statistical measures of the factors e g var_e show a bias and this may be for measures of model output variables as well The operator gsa_vb_run_mask is a stand alone operator Having a model output variable definition as in Example 5 1 on page 40 Assume the experiment description file GSA_VB from Example 6 4 on page 72 then in result processing gsa_vb_run sample resample setruns to use from the sample S and the re sample R for following post processing with UNC_MC operators effects tot atmo _g get total sensitivity indices for atmo_g for the four defined factors Dimensionality 2 Coordinates time factor_sequ Extents 20 4 max _e atmo_g run ensemble maximum of atmo from the sample S and the re sample R Dimensionality 1 Coordinates time Extents 20 sum effects 1st max atmo sum up linear sensitivity indices of max atmo for a linearity test of this model output Dimensionality 0 Coordinat
86. macro m1 define avg atmo_g c 11 20 Example 11 1 Structure of a user defined file 11 2 Coordinate Transformation File Some post processing operators currently get_data and get_experiment enable access to external data They derive from an operator argument a multi dimensional result that has to be equipped as usual in SimEnv experiment post processing with a coordinate assignment By applying these operators it can be necessary to define or transform a coordinate description for the operator result that fits the result to the current model and or experiment under consideration The same is true for the operator regrid which is used to assign new coordinates to a result The following cases can be distinguished e A dimension of the result does not have a coordinate assignment A coordinate has to be assigned to this dimension e A coordinate description of the result has to be modified in a way that it matches with a defined coordi nate of the model experiment under consideration Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 e A coordinate description of the result has to be incorporated with and or without modifications into the coordinate set of the model experiment under consideration Coordinate transformations for results in the course of the operator s performance are supported in SimEnv by a coordinate transformation file that is assigned to the operator result as an ar
87. main model is called with 11 0 lo 2 lf main_model lt simenv_run_char gt nlog Optdir All files with the extension nlog in the sub directory run lt simenv_run_char gt are copied to the SimEnv log file lt model gt nlog For both main model and sub models Optdir implies that all GAMS solver option files have to be located in the current working directory gt 52 y HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 5 8 Model Interface at Shell Script Level For models that do not allow to implement the model coupling interface at programming language level e g because source code is not available SimEnv supplies a coupling interface at shell script level by a set of dot scripts The shell script lt model gt run cf Section 7 1 on page 89 is used to wrap the model and option ally to have at disposal corresponding functionality of the SimEnv model interface functions of Tab 5 5 For additional interfaces at the shell script level using ASCII files see Section 5 9 Tab 5 8 Model interface functions at shell script level Dot script name Command Inputs Input output description outputs description SE_HOME bin initialize current SE_RUN operating system environment variable SE_RUN is simenv_ single run output set to the current run number of the simulation ini_sh Perform always and as the first SimEnv dot script in lt model gt run and lt model gt
88. method with factors that significantly differ in their value ranges i e for factors with large values together with factors with small values Additionally the scaling allows for comparing the sensitivity measures between different state variables z and or output functions g E Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 iit a i j _ 17 Fig 4 2 x1 x X212 sample of size 12 representing 4 trajectories at a 6 level grid assuming a normal distribution for x anda uniform distribution for x2 o X21 default nominal numerical factor constellation of model M upper figure sample for A 1 5 in the 2 dimensional factor space X2 X1 X2 middle figure sample for A 1 5 in the factor quantile space QX2 q x q x2 lower figure sample for optimal A 3 5 in the factor quantile space QX2 q x q x2 numbers indicate individual trajectories The arrows indicate the se quence how each trajectory was generated from sampling points Sample for GSA_EE Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 gt Interaction with other factors Nonlinear effect on model output Sensitivity w r t model output gt Fig 4 3 Result plot for GSA_EE of 21 factors Factors bounded by the dotted line were identified as sensitive factors bounded by the dashed li
89. model gt end lt model gt gdf Model description Model Interface Supported formats NetCDF CF IEEE binary ASCII ASCII mandatory file lt model gt edf lt model gt bdf lt model gt cfg General configuration Experiment description Experiment Preparation Experiment Performance lt model gt out Experiment outputs lt model gt smp lt model gt elog lt model gt mlog lt model gt nlog lt model gt blog lt model gt bmlog lt model gt olog lt operator gt opr lt model gt mac lt model gt odf User macros and operators Experiment Post processing lt model gt res lt model gt inf Post processor output Experiment Evaluation Visualize results model lt model gt fct experiment type output format Sample and dependent Experiment logs Fig 10 1 SimEnv user shell scripts and files 10 6 Built In Names SimEnv has a number of built in model output variable shell script variable and coordinate names that can not be used for corresponding user defined names Tab 10 9 lists the built in pre defined model variables that are output during experiment performance to SimEnv model output structures and are available in experiment post processing without defining them in the model output description file lt model gt mdf and without using the cor
90. model gt run is redirected to the log file lt model gt nlog e For GAMS models lt model gt run has a pre defined structure Check Section 5 7 1 for more informa tion e To cancel the whole experiment after the performance of the current single run lt simenv_run_int gt due to any condition of this run make sure a file SE_WS lt model gt err lt simenv_run_char gt exists as an indicator to stop Create this file in the model or in lt model gt run For the latter e Perform SE_HOME bin simenv_get_run_sh to get the current run number lt simenv_run_int gt and lt simenv_run_char gt e Touch the file SE_WS lt model gt err lt simenv_run_char gt e Cf Tab 5 8 on page 53 and Example 7 1 below From the cancelled experiment only those single runs are available for experiment post processing that were finished before the cancelled single run Check lt model gt elog to identify these single runs e SimEnv supplies a shell script simenv_kill_ process to kill models programs that were started within lt model gt run and that consumed more than a given threshold of CPU time For example with this script models can be killed that do not converge and would run infinitely Start this script in background directly before the process is started that is to be monitored SE_HOME bin simenv_kill_process lt program_to_monitor gt lt CPU_time_threshold_in sec gt When the program is killed a file SE_WS lt model gt killed lt simenv_run_char gt e
91. nodata gt 45 88 178 1 1 88 178 16 20 _ lt nodata gt lt nodata gt SE_HOME bin simenv_put_as bios g ascii Since there is no second argument to simenv_put_as all variables without coordinate assignment zero dimensional variables are output This is only bios_g The file has to have only one record with data and it must hold one data value The example model world_as f writes the model output files atmo_bios ascii atmo_g ascii and bios_g ascii in the structures as explained above Example 5 6 E SHAY ASCII file structure for the ASCII model interface Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Both shell scripts transfer the ASCII file data to SimEnv model output file as follows e A SimEnv model output variable is defined on a rectilinear grid that is composed from coordinates cf Section 5 2 By specifying a coordinate name as the second argument all these model variable values are expected in the ASCII file that have this coordinate as their first coordinate cf Section 5 3 e The lines in the ASCII file correspond to the coordinate axis values in that sequence as defined in lt model gt mdf e The columns in the ASCII file correspond to the variables with the first coordinate as specified in the second argument in that sequence of the variables as defined in lt model gt mdf A multi dimensional vari able occupies a block of contiguous columns The seq
92. of lt co_name gt the variable Determines in this way implicitly the dimen sionality n of the variable coord_extents c2 1 lt co_val14 gt assigns start and end coordi lt co_valj2 gt nate real values from each sats coordinate axis to the vari lt co_valn1 gt able If missing all coordinate lt co_valno gt values will be used from all assigned coordinates index_extents c1 1 lt in_val44 gt assigns integer value start lt in_val 2 gt and end indices for each er dimension to the variable lt in_val 4 gt Indices can be used to ad lt in_val 2 gt dress the variable during ex periment post processing Each model output variable has a name a dimensionality and assigned extents a data type a description and a unit The name should correspond to the name of the variable in the simulation model code Associa tion between these two names is achieved by the SimEnv model interface function simenv_put_ see be low lt model gt mdf is an ASCII file that holds this information It follows the coding rules in Section 11 1 on page 169 with the keywords names sub keywords and values as in Tab 5 3 To Tab 5 3 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e Coordinate and variable names must differ from factor names in experiment description cf Section 6 1 and from built in and user defined operator names for
93. of the whole run ensemble Alterna tively a list of non negative integer run number values can be defined by using a value list for the sub keyword include_runs The include set as defined by the sub keywords begin_run end_run in clude_runs can be reduced by specification of a list of non negative integer run number values defined by the sub keyword exclude_runs using again a value list Specification of exclude_runs demands an explicit specification of either begin_run and end_run or of include_runs The runs the experiment will be performed for are defined as follows i get the intersection of the runs as specified by the experiment definition in lt model gt edf and the include set ii form the relative complement of this set with respect to the exclude set For keyword experiment sub keyword email After performing an experiment an email is sent to the email address specified in lt string gt Specify al ways a complete address lt IES Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f i _ 153 For keyword postproc sub keyword address_default During experiment post processing portions of multi dimensional model output variables can be ad dressed by coordinate c or index i reference A default is established here For keyword postproc sub keyword coord_check D
94. only For the axis attribute of a coordinate variable exist defaults For each post processor result the first coordinate is assumed to be the X axis the second and third coordinate are assumed to represent the Y and Z axis and the fourth dimension is time T For model results these attribute values are assigned to coordinate variables describing geographical longitude geographical latitude level or height and time In case other coordinate names are used these are simply also used for the axis attribute The units attribute for model output is actually derived from the description of the corresponding sub keywords for the keyword variable in the lt model gt mdf file For post processing output it is only used as a placeholder and not derived from the applied operator sequence so far The coordinates attribute serves to define coordinates depending on other ones and so to allow coor dinate transformations Actually this attribute is not used Actually the _Fillvalue attribute is not applied to coordinate variables It is identically to the missing_value attribute but open for other definitions For visualization requirements the following additional variable attributes have been defined for SimEnv Tab 12 4 Variable NetCDF attributes for visualization Name Value Data type lt variable_name gt monotony increasing decreasing none char coordinate variables only lt vari
95. only if necessary simenv run int str2num simenv get run m phi lat simenv get m pl phi lat omega lat simenv_ get m p2 omega lat phi lon simenv get m p3 phi lon omega lon simenv get m p4 omega lon compute dynamics of atmo and bios over space and time of atmo_g over time all dependent on pl p2 p3 p4 for idecade 0 19 for level 0 3 end end simenv sts simenv sts simenv_sts simenv sts simenv put m atmo single atmo simenv put m bios single bios simenv put m atmo g int32 atmo g simenv put m bios g int32 bios g simenv end m Example file world_m m Example 15 7 Model interface for Matlab models model world_m m J Iii i j ji S Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 2 9 Mathematica Model Example 15 8 describes the model interface for a Mathematica model The model itself is not provided get cur E oan sia perform always and as the first SE_HOME bin simenv_ sh dot script rent run number lt simenv_run_char gt and lt simenv_run_int gt SSE_HOM E bin simenv_get_run_sh get run fac the tor names and adjusted values and Mathematica model lt model gt m CER SE_HOM E bin simenv_run mathematica transfer ASCII model output files to SimEnv model output Example 15 10 an
96. or simenv res or if the access does not work properly An email will be sent from SimEnv when the access is enabled simenv sta lt user_name gt lt begin_date gt lt end_date gt generate general log file statistics All SimEnv services are logged during their performance into log files The log file directory is specified in SE_HOME bin simenv_settings txt simenv sta evaluates these log files statistically and generates a report w r t SimEnv accesses experi lt repetition_time gt lt sort gt ments experiment post processing and visualization simenv sts get the current status of an active simulation experiment lt model gt Start this service from the workspace the active simulation experiment was started from This is the only service that can be started from a workspace where another service is active simenv srv lt user_name gt serve a request for password free access to the SimEnv visualization server only for systems where the SimEnvVis visualization server is not hosted on the local machine and only for the SimEnv administrator check SE_HOME bin simenv_settings txt e All but services simenv cpy simenv hlp simenv key simenv sta and simenv srv Start a service only from the current workspace e All but service simenv sts A SimEnv service cannot be started from a workspace where an other SimEnv service is active Multi Run Simulation Environment SimEnv User Guide for
97. or in one file per experiment slices o 1 no f_c indicates whether py_ja_m simenv_slice_ is not used used for Fortran C or Python Java Matlab models auto_interface o 1 no all f c indicates to generate include py sh source code files for the semi automated model interface for the corresponding languages structure o 1 standard indicates model structure with distributed respect to experiment per parallel formance experiment lt nil gt restart_ini o 1 no yes perform lt model gt ini for ex periment re start begin_run 0 1 lt int_val gt begin single run number end_run oO 1 last lt int_val gt end single run number include_runs o 1 lt val_list gt single run numbers to include in the experiment exclude_runs o 1 lt val_list gt single run numbers to exclude from the experiment email 0 1 lt string gt email notification address postproc lt nil gt out_directory 0 1 lt directory gt experiment post processing output directory out_format 0 1 netcdf ieee experiment post processing ascii output format address _default o 1 coordinate experiment post processing index address default for model output variables coord_check 0 1 strong weak post processing coordinate without check by operators opr_directory 0 1 lt directory gt directory the post processors expects user defined operator executables factors_in_output o 1 yes no determine whether factor val ues ar
98. return code of model interface functions at least here if simenv_sts 0 return 1 fe enmeny ger amn emily aie insosssecye simenv_sts simenv_get_run_c amp simenv_run_int simenv_run_char simenv_sts simenv_get_c p1 amp pl1 amp pl simenv_sts simenv_get_c p2 amp p2 amp p2 simenv_sts simenv_get_c p3 amp p3 amp p3 simenv_sts simenv_get_c p4 amp p4 amp p4 World world world computeAtmo p1 p2 p3 p4 simenv_sts simenv_put_c atmo_g char amp world atmo_g world computeBios p1 p2 p3 p4 simenv_sts simenv_put_c bios_g char amp world bios_g simenv_sts simenv_end_c return 0 Example file world_cpp cpp Example 15 4 Model interface for C models model world_cpp cpp ria aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN a J 201 15 2 6 Python Model With respect to Example 5 1 the following Python code world_py py could be used to describe the model interfaced to SimEnv SimEnv modifications are marked in bold usr local bin python import string import os from simenv import this model needs the math and the Numeric package set the PYTHONPATH environment variable accordingly from math import from Numeric import atmo zeros 45 90 4 20 Float bios zeros 36 90 20 Float atmo _g zeros 20 Float pl 1 p2 2 DSSS p4 4
99. sensitivity measure for dim res dim arg2 char_arg1 arg2 according to char_arg1 appended arg2 dimensions lin_abs absolute linearity measure for according to char_arg1 arg2 according to char_arg1 char_arg1 arg2 lin_rel relative linearity measure for arg2 char_arg1 according to char_arg1 arg2 i aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H i J ji 133 Argumen Argument value Name Meaning restriction s g ae ee restriction result description sym_abs absolute symmetry measure for char_arg1 arg2 according to char_arg1 arg2 sym_rel relative symmetry measure for char_arg1 arg2 according to char_arg1 arg2 same as for see Section 8 4 5 see Section 8 4 5 see Section 8 4 5 UNC_MC This experiment type allows to post process the whole run ensemble as an UNC_MC experiment Keep in mind that generally the factors do not follow a pre defined distribution Tab 8 15 Syntax of the filter argument 1 for LSA Placeholder Explanation lt filter gt lt select_operator gt lt select_operators gt lt select_operators gt lt select_operator gt self seli sels _ lt factor_val_type gt lt factor_val_range gt with self select factor range seli select increment range sels select sign range only for sens_abs and sens_rel lt factor_val_type gt specification how to inte
100. sim_time 1 float 4 8 atmo 45 x 90 x 4 x 20 float 1 296 000 1 296 000 bios 36 x 90 x 20 float 259 200 259 200 atmo g 20 int 80 80 bios g 1 int 4 8 1 555 312 One single run needs 1 555 312 512 000 3 1 records with a fixed length of 512 000 Bytes Remaining bytes in the last record are undefined Example 12 1 IEEE compliant model output data structure Storage demand for each model output variable factor is according to its dimensionality extents and data type Storage demand in bytes for each model output variable factor is re adjusted to the smallest number na a S 180 y H Es f J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 of bytes divisible by 8 where the data can be stored Multi dimensional data fields are organized in the For tran storage model cf Section 15 7 Glossary Data is stored in records with a fixed record length of minimum 512000 Bytes re adjusted storage demand in Bytes In lt model gt outall ieee each single run starts with a new record Sequence of the single runs corresponds to the sequence of the single run numbers lt simenv_run_int gt Consequently data from default nominal single run 0 is stored in the first and potentially the following records 12 3 IEEE Compliant Binary and ASCII Experiment Post Processor Output For IEEE and ASCII experiment post processor output result information is stored in two files e lt model gt res lt
101. simenv_res_char gt ieee ascii holds the result dynamics e lt model gt inf lt simenv_res_char gt ieee ascii holds structure and coordinate information The IEEE post processor output files lt model gt res lt simenv_res_char gt ieee and lt model gt inf lt simenv_res_char gt ieee are unformatted binary files with IEEE float int number representation while for the ASCII post processor version lt model gt res lt simenv_res_char gt ascii and lt model gt inf lt simenv_res_char gt ascii formatted ASCII files are used Files for both output file formats have for each result subsequently the following structure Record structure of lt model gt inf lt simenv_res_char gt ieee ascii for each result result number 01 record no 1 max 512 chars result expression string record no 2 max 128 chars result description string record no 3 max 32 chars result unit string or 1 space if unit is undefined record no 4 10 int dim ext 1 ext dim 0 O record no 4 max 20 chars coordinate name of dimension 1 record no 5 10 float coordinate values of dimension 1 in records of 10 values last record may have less values record no XXX max 20 chars coordinate name of dimension dim record no xxx 1 10 float coordinate values of dimension dim in records of 10 values last record may have less values result number 02 Record structure of lt model gt res lt simenv_res_char gt ieee ascii for each result
102. source code file names Element Constraints line length max 160 characters lt name gt max 20 characters first character has to be a letter must not end on _m must not contain elemental operators and characters and cf Tab 8 3 on page 108 lt value gt for sub keyword descr without lt name gt max 512 characters total sum over all lines for sub keyword descr with lt name gt max 128 characters for sub keyword lt string gt _directory max 116 characters for the resulting resolved directory string directory can contain operating system environment variables for sub keyword unit max 32 characters Tab 11 3 lists the reserved forbidden names and file names that cannot be declared in user defined files Tab 11 3 Reserved names and file names in user defined files Element Reserved forbidden names lt name gt built in model output variables according to Tab 10 9 with the exception of GAMS built in coordinates model source code file names according to Tab 10 11 special keywords in lt model gt edf for DFD default file lt file_ name gt see Section 11 3 The line type in the description table for a user defined file specifies whether a keyword sub keyword com bination can be omitted Sa S 170 y H Es f Multi Run Simulation Environment SimEnv User Guide for Version 3 01
103. space X2 X1 X2 o X21 default nominal numerical factor constellation of model M Fig 4 7 Sample for a Monte Carlo analysis UNC_MC Theoretically with a Monte Carlo analysis moments of a state variable z can be computed as Mz J 2X9 pat X dX Xk with 2 Xx state variable z as a function of X Pat Xx probability density function of X mM z m th moment of the state variable z with respect to the probability density function pdf By interpreting the probability density function pdf X as the error distribution in the factor space X it is pos sible to study error propagation in the model On the other hand Monte Carlo analysis can be interpreted as a stochastic error analysis if there are measurements of the real system for z For a numerical experiment in SimEnv it is assumed that the probability density function pdf X can be de composed into marginal independent probability density functions pdf for all factors x of X k pdf Xx II pdfi x i 1 and the k dimensional integral is approximated by a sequence of N single simulation runs of the model Monte Carlo runs where the numerical factor values all of k factors xj of xi 1 lt i lt k 1 lt j lt N are sam pled according to the marginal probability density function pdfi On the basis of these assumptions the statistical measures in Tab 4 3 can be computed during perform ance of a post processing session from an UNC_MC expe
104. specific lt nil gt seed o 1 random fixed method how to initialize the random number generator runs m 1 lt int_val gt chain length number of runs to be per formed for the experiment will be smaller Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Due to the sequential construction of the MCMC chain during the experiment a BAY_BC experiment can not be performed in parallel and can not be restarted To Tab 6 10 the following additional rules and explanations apply For the description of line type check Tab 11 4 on page 171 Sub keyword sample Each factor in a BAY_BC experiment comes with its own marginal prior distribution which will be quali fied in the course of experiment by generating a representative sample by taking into account measure ment values and measurement errors from the real system Sub keyword runs Specify here the length of the chain of visited points in the factor space The number of single simulation runs performed during the experiment is smaller than this length since simulation runs are not performed for candidate points that are outside the definition range of any individual factor according to its prior dis tribution and optional sample_include sample_exclude intervals Sub keyword type Section 6 1 1 on page 65 For BAY_BC only the factor adjustment type set is allowed For all the other sub keywords check Section
105. sym _ abs rel cf Sections 8 4 3 and 8 4 5 run_info number of the current 7 run_info char_arg1 single run char_arg1 run information type run nr and or run_nr total number of runs of the for current run number experiment nr_of_runs for number of runs of the experiment transpose transpose arg2 according dim arg2 gt 1 transpose char_arg1 to sequence in char_arg1 dim res dim arg2 3142 arg2 ext res i ext arg2 j re sorted atmo char_arg1 transpose sequence undef undefined value 7 undef usage get usage of a post 7 usage run info char_arg1 processing operator char_arg1 operator name or usage advanced all basic trigonometric aggr moment advanced multi run user defined for the corresponding operator classes S aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN i f ji 115 The following explanations hold for the operators in Tab 8 8 All operators but experiment and matmul are applied to each element of the argument s These operators deal with an unfulfilled argument value restriction for an operand element in a way that the cor responding element of the operator result will be undefined The operator classify transforms the values of an operand arg4 that has dimensionality gt O into the class numbers 1 int_arg1 of int_arg1 classes Classes are assumed to be
106. that compute the average from all values of the multi dimensional operand arg avg arg simply computes the average of arg for the default run number O of the experiment as it is applied outside a multi run operator Dimensionality 0 Coordinates without Extents without avg_e avg arg at first computes for all single run individually from all values of arg their average 1 value per single run and thereof the average over the whole run ensemble Dimensionality 0 Coordinates without Extents without avg avg_e arg at first computes the run ensemble average of arg that has the same dimensionality and extents as the operand arg itself and afterwards computes the average from all values of the previous multi run intermediate result Dimensionality 0 Coordinates without Extents without avg _e avg arg avg avg e arg avg arg is allowed and is the sum of the three summands as described above Dimensionality 0 Coordinates without Extents without Example 8 7 Multi and single run experiment post processing operators aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 3 HN aP I 123 8 4 2 Global Sensitivity Analysis Elementary Effects Method GSA_EE Tab 8 9 Experiment specific operators for GSA_EE Argument Name Meanin restriction s Argument value g result description restriction Tab 8 1 page 106 morris global sensi
107. the results are appended or the result files are replaced by new ones lt simenv_res_int gt simenv rst restart an experiment lt model gt cf Section 7 4 simenv run prepare and run an experiment lt model gt cf Section 7 1 simenv vis perform visual post processor output visualization with SimEnvVis for that NetCDF lt model gt post processor output file with the highest two digit number lt simenv_res_char gt latest lt simenv_res_char gt latest default or with the file number lt simenv_res_char gt At PIK visualization runs on a remote server Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 SimEnv lt simenv_run_int gt lt file gt Use to service Auxiliary Services simenv chk check on model script files lt model gt run lt model gt rst lt model gt ini lt model gt end lt model gt check lt model gt cfg lt model gt edf lt model gt odf lt model gt gdf lt model gt mdf lt model gt mac existing model and post processor output files generate pre experiment output statistics simenv cin clean up model and experiment post processor output files lt model gt Deletes all model output files post processor output files experiment log files and auxiliary files of a model according to the settings in lt model gt cfg simenv cpl complete sequence of SimEnv services lt model gt simenv chk simenv ru
108. to the current workspace can be modified and will then be used in stead of the default job control files to start an experiment with one of those parallelization strategies that use the load leveler and POE If necessary copy the ASCII job control files simenv_ dis par seq _ aix linux jcf from the sub directory bin of the SimEnv home directory to lt model gt _ dis par seq _ aix linux jcf in the current work space modify the file s according to the needs of the model one wants to perform and or the machine one wants to use and start afterwards simenv run and or simenv rst anew If available in the current workspace these modified job control files are used instead of the original files in the sub directory bin of the SimEnv home directory simenv_ dis par seq _ aix linux jcf and or lt model gt _ dis par seq _ aix linux jcf submit a job in distributed parallel sequential sub mode under LoadL control The default job control files and SimEnv log files enable automatic restart of the experiment by the load lev eler after an interrupt of the job caused by the operating system the load leveler or POE The user does not need to restart the experiment manually after such an event For performing a parallel model itself see Section 5 11 Peculiarities of multi run experiment performance Contrary to a single model run a native model source code has to be analysed at least with respect to its output
109. value is et set to the adjusted factor value lt factor_adj_val gt lt factor_smp_val gt add added to the factor default value lt factor_adj_val gt lt factor_smp_val gt lt factor_def_val gt multiply Multiplied by the factor default value lt factor_adj_val gt lt factor_smp_val gt lt factor_def_val gt relative increased by 1 and afterwards multiplied by the factor default value lt factor_adj_val gt 1 lt factor_smp_val gt lt factor_def_val gt 64 y H el yk Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 general descr Experiment description file general descr examples general type DFD LACTOL pl descr parameter pl acts ons pl tme without factor pl type set factor pl default ills LACTCOL pl sample lt DFD specific gt factor p2 type set LECTOR p2 default 2 TACTOL p2 sample lt DFD specific gt specific lt DFD specific gt Example 6 1 General layout of an experiment description file lt model gt edf 6 1 1 Elements of lt model gt edf for Experiment Types with Probabilistic Sampling For experiments with probabilistic sampling GSA_EE GSA_VB UNC_MC and BAY_BC but not OPT_SA the additional sub keywords are available as defined in Tab 6 3 Tab 6 3 Additional elements of lt model gt edf for experiment types with probabilistic sampling 3 Max Keyword Name k ah
110. var_name undefined function value 3 inconsistency between variable and idim ifrom ito 4 slice storage exceeded 5 warning slice overwritten or slice represents the total dimension simenv_ close model integer 4 return code end_ f c coupling interface simenv_end_ 0 ok flc 2_ VO error for experiment output file Perform always function value the last SimEnv function in the model 42 Make sure consistency of type and dimension declarations between the model output variables in model source code and the corresponding variable declarations in the model output description file lt model gt mdf Model output variables that are not output completely or only partially within the user model are handled in experiment post processing as their corresponding nodata values cf Tab 10 13 Application of simenv_slice_ f c demands a corresponding slice entry in the configuration file lt model gt cfg For more information check Section 10 1 Application of simenv_slice_ f c for NetCDF model output may result in a higher consumption of com puting time for each single run of the experiment compared with NetCDF model output without simenv_slice_ For this case keep in mind the trade off between the demand for computing time and the demand for main memory The include file simenv_mod_ f c inc from the sub directory inc of the SimEnv home directory can be used in a model to declare the SimEnv model interface funct
111. variable char_arg2 data file name char_arg3 coordinate specification transformation file name variable to get from the data file arg4 get_experiment include an other 1 char_arg1 post processed experi but coordinates according to mod_res char_arg2 ment output char_arg3 mod char_arg3 char_arg1 experiment directory mod ctf arg4 char_arg2 model experimented with avg atmo 400 char_arg3 coordinate transfor mation file arg4 result from the other experiment get_experiment get_table_fct apply table function with 1 get_table fct char_arg1 linear interpolation of table char_arg1 file name table usr arg2 char_arg1 to arg2 atmo if conditional if construct 5 if char_arg1 char_arg1 comparison operator lt arg2 arg2 comparator atmo arg3 arg3 arg4 new assignments 400 arg4 atmo mask mask values of arg2 5 mask char_arg1 set them undefined by char_arg1 comparison operator lt arg2 comparing arg2 and arg3 atmo arg3 using operator char_arg1 400 un mask_file mask values of arg2 1 mask char_arg1 set them undefined as__ char_arg1 mask file name mask dat arg2 specified in the file atmo char_arg1 matmul matrix multiplication dim arg1 dim arg2 dim res matmul arg1 2 atmo 1 1 arg2 ext res i according to matrix transpose 21 multiplication rules atmo
112. workspace by lt model gt ini and are deleted after the whole experiment where lt gams_model gt is a placeholder for the model of type main and all models of type sub in the gdf file During experiment performance of a GAMS model each single run lt simenv_run_int gt from the experiment is performed individually in a sub directory run lt simenv_run_char gt of the current workspace Each directory is generated automatically before performing the corresponding single run and removed after performance of this single run With the sub keyword keep_runs the user can force to keep sub directories for later check of the transformed model code and its performance GAMS main model terminal output is redirected to the log file main _model lt simenv_run_char gt nlog in the corresponding sub directory run lt simenv_run_char gt For re direction of the terminal output from sub models and from solvers the modeler is responsible for It is recommended to call all GAMS sub models with the GAMS command line option string 11 0 lo 2 lf lt any_name gt nlog dp 0 Optdir that re directs GAMS submodel and solver terminal output to the file lt any_name gt nlog in the sub directory run lt simenv_run_char gt of the current workspace cf Example 15 9 The main model is called with the options lt values from_subkeyword_ options gt lf main_model lt simenv_run_char gt nlog Optdir In case the sub keyword options is not specified the
113. y ICO bG posl return ierror return error code SimEnv operator results are always of type real 4 int simenv_compute_user_def_operator float res int len_res int iext1 9 iext2 9 double value8 r8facl r8fac2 int idimens Woe sy kp Ai Led eZ Pp iat dergl oiis ierg Ofte imei cerinecy iboart taci EVO ZS get dimensionality idimens and dimensions idim for both arguments idimens simenv get dim arg c 1 iextl idimens simenv get dim arg c 2 iext2 perform matrix multiplication m 0 for k 1 k lt iext2 1 k alence 2 Orte a1 ese 2 0 7 oie aii pissis eaLshe aleucel ortesi fe Sees Gly k srmlergl at i arg2 rk 7 value8 0 indi_defined 0 for 1 1 1 lt iext1 1 1 ialk iargil ofrer l iL areca O te2 lergA Orrel facl simenv_get_arg_c 1 ial fac2 simenv_get_arg_c 2 1a2 aie Salinsinwy Cak vcler Crac r simenv_ chk undef _ c fac2 indi defined ibe r8facl facil r8fac2 fac2 value8 value8 r8facl r8fac2 m m 1 a VI 54k Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 SHEN lt 215 iMSiewicin if indi_defined 0 resime Sse jowle ende i 7 else res m 1 simenv clip undef c value8 Example file usr_opr_matmul_c c Example 15 14 Experiment post processor user defined operator module operator matmul_c
114. 1 4 A user defined operator itself is a stand alone executable that is executed during the check and the compu tation of the operator chain While the main program of this executable is made available by SimEnv the user has to supply two functions with pre defined names in C C or Fortran that represent the check and the computational part of the user defined operator For declaration of both functions SimEnv comes with a set of operator interface functions They can be used among others to get dimensionality length extents and coordinates of an argument and to get and check argument values and to put operator results For a composed operator the operator description file lt model gt odf simply holds the definition of the corre sponding operator chain composed from built in and user defined operators and using formal arguments User defined operators must not be multi run operators Consequently such operators can not process the whole run ensemble according to any processing strategy for the individual experiment type For example for experiment type UNC_MC it is impossible to declare a user defined operator that derives any measure from the whole run ensemble However the concept of composed operators allows for such an approach by applying built in multi run operators 8 5 1 Declaration of User Defined Operator Dynamics User defined operators consist of a declarative and a computational part that are described in one source file in
115. 1 put xoliy e105 model sub_ml put an Gil ew O RES y ith Es j ji S Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 model sub m2 type sub model sub _m2 get dem_ch model sub m2 put Zial or model gams_model type main model sub ml type sub model sub_ml get dem_ny model sub m1 put Mod Gi 3 l ss model sub m1 put an Gi pLO ES model sub m2 type sub model sub _m2 get dem_ch model sub m2 put Zad model sub m2 put modstat Example 5 3 GAMS description file for coupled GAMS models lt model gt edf While for the C C Fortran Python Java Matlab model interface the names of corresponding factors in the model description file lt model gt edf and the model source code can differ and are associated by the first ar gument of the interface function simenv_put_ cf Fig 5 1 the names have to coincide for the GAMS model interface In the GAMS model code the factors specified in the experiment description file have to be of type PARAMETER and have be defined before the include statement include lt model gt _simenv_get inc lt model gt mdf Corresponding variables in the model output description file and in the GAMS model source code must have same names Variables have to be always of type float in the model output description file In GAMS model code the model output variables declared in the model output description file can be of the numeric type
116. 10 2012 Tab 5 7 Elements of a GAMS description file lt model gt gdf Sub Line Ma Keyword Name k line Value Explanation eyword type nmb general lt nil gt descr o any lt string gt GAMS coupling description keep_runs 0 1 lt val_list gt value list of run numbers where single GAMS model runs are to be stored by keep ing their corresponding sub directories for syntax see Tab 11 6 time_limit 0 1 lt int_val gt wall clock limit in seconds for each GAMS model single run options o 1 lt string gt string of options GAMS main model is started with from command line script o 1 lt directory gt shell script to be performed lt file_name gt before each single GAMS model run model lt model_ descr 0 1 lt string gt sub model output descrip name gt tion type m 1 main sub identifies GAMS main or sub without model extension get m exactly lt factor_name gt get resulting adjustment for gms number lt factor_name gt to this model of factors put m jexactly lt var_name gt put values of SimEnv model number lt suffix_set gt output variable lt var_name gt of lt index_set gt from this model to SimEnv model lt format gt output output GAMS variable lt var_name gt vari has the specified suffix and ables index sets and is interfaced from GAMS to SimEnv ac cording to lt format gt To Tab 5 7 the following addition
117. 2 There are e Single argument operators that replicate dimensionality dimensions and coordinates from the only argument to the operator result Example sin atmo e Multi argument operators that demand a certain relation between dimensionalities dimensions and coordinates of their arguments Example mod atmo c 84 56 c 1 bios e Operators that increase the dimensionality of the operator result and assign new coordinates to the additional dimensions cf Tab 10 11 or form new coordinates from resulting factor adjustments If the dimensionality of an operator result is higher than that of one of its operands the additional di mensions of the result are appended to the dimensions of the operand Example ens atmo SimEnv experiment post processing operators may have two special types of arguments e Character arguments char_arg Only character strings enclosed in are valid as arguments Some built in operators e g count have a pre defined set of valid character argument strings e g for operator count strings all def and undef Some built in operators allow an empty string e g dfd Example count undef atmo dfd atmo e Integer or real float constant arguments int_arg or real_arg Only constants in appropriate format are valid as arguments Model output variables of dimensional ity 0 or general operands with dimensionality 0 are invalid Example move_avg 0001 lin 3 atmo qnt 33 333 atmo
118. 2 20 Seuaichisic Simic 6 3 2il equidist_end 88 4 88 equidist_end 5 1 50 Having a model output variable definition as in Example 5 1 on page 40 and assuming address_default coordinate in lt model gt cfg Assume the experiment layout in Fig 4 6 c on page 23 and the corresponding experiment description file from Example 6 5 DFD_c on page 75 Additionally assume another experiment with a model named model and its model output variables modvar1 and modvar2 that are defined for the following coordinates coordinate definition lise 1 10 100 L000 equidist_end 2 2 20 ScquEichesieemcmsi S sO equidist_end 4 1 43 equidist_end 5 1 50 example of a coordinate transformation file newl Bis 2 list 1006 1009 3 lat Be 5 SG new2 50 85 new coordinate Scqunichisememc eo OK Sie iS get_experiment mydir model model ctf modvarl modvar2 coordinate use coordinate definition coordinate definition coordinate definition equidist_end 88 4 68 coordinate definition Example 11 2 Coordinate transformations by a transformation file Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Unlike all other user defined files coordinate transformation files cannot be checked by the SimEnv service simenv chk or when starting the service simenv res 11 3 ASCII Data Files and Value Lists ASCII data files lt directory gt lt file_name gt
119. 2 char_arg3 arg4 include an other experiment get_table_fct char_arg1 arg2 table function with linear interpolation of table char_arg1 for position arg2 if char_arg1 arg2 arg3 arg4 general purpose conditional if construct mask char_arg1 arg2 arg3 mask elements of argument arg2 set them undefined un mask_file char_arg1 arg2 mask elements of arg2 set them undefined according to information from file char_arg1 matmul arg1 arg2 matrix multiplication move_avg char_arg1 char_arg2 int_arg3 arg4 moving average of running length int_arg3 for arg4 rank char_arg1 arg2 rank of arg2 according to char_arg1 regrid char_arg1 arg2 assign new coordinates to arg2 run char_arg1 arg2 values of arg2 for a single run selected by char_arg1 run_info char_arg1 current run number and or number of single runs of the current experiment transpose char_arg1 arg2 transpose arg2 according to char_arg1 undef undefined element usage char_arg1 get usage of post proc operator char_arg1 Aggregation and mom ent operators for arguments Tab 8 5 on page 110 avg arg1 argument arithmetic mean of values avgg arg1 argument geometric mean of values avgh arg1 argument harmonic mean of values avgw arg1 arg2 argument weighted mean of values count char_arg1 arg2 count number of values according to char_arg1 hgr char_arg1 i
120. 2 gt It uses the syntax for model output variables as described in Section 8 1 3 on page 103 In particular i stands for local index addressing c for local coordinate addressing and if they are missing the global default as defined in the general SimEnv configuration file lt model gt cfg cf Section 10 1 on page 151 for index and or coordinate addressing is used Additionally a local file default can be set by lines a 118 X HN i f i lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 or c indicating that all addresses in the following records without a local setting are interpreted in the appro priate manner n corresponds with the dimensionality of arg2 lt valuei gt lt value gt if lt value gt is missing and instead of lt value gt lt valuej2 gt is allowed i 1 n Comment lines starting with the first non white space character are allowed as for each ASCII data file cf Section 11 3 on page 174 Each line defines for the argument arg2 a block of values that are masked for operator mask_file or not masked for operator unmask_file The line lt sep gt lt sep gt in the mask file char_arg1 results for operator mask_file that all values of arg2 are masked and for the operator unmask_file in the identity of argument arg2 For restrictions in the path to the directory of the character argument char_arg1 see Tab 11 3 Having a model outp
121. 3 sample include 0 680 6 factor p4 descr as p2 but exclude additionally 10 15 factor p4 sample dirst EN OFA OmO14 PEC OIe p4 sample exclude Hinite 0 6 OOo 10s 15 BACT ONS pS descr equivalent to p4 raCtor po sample distr N 0 0 04 ACE Ons po sample include O 2680 6 factor po sample exclude 5 108 5 ILS Bale ons p6 descr sample from 5 inf IEGYCNE OIE p6 sample distr L 0 0 04 factor p6 sample exclude SOR S S XXX any value S 0 Example 6 2 Include exclude for probabilistic sampling in an experiment description file lt model gt edf Alf 5 amp 68 S HHI z J IA Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 6 2 Global Sensitivity Analysis Elementary Effects Method GSA_EE The experiment specific information for experiment description files in Tab 6 1 on page 63 is defined for GSA_EE experiments as follows Tab 6 5 Experiment specific elements of an edf file for GSA_EE Max Keyword Name k oun ine line Value Explanation eyword type nmb factor lt factor_ sample m 1 distr distribution and distribution name gt lt distribution gt parameters to grid the factor for equidistant quantiles sample _ 0 1 lt real_val 41 gt lower bounds lt real_val gt and include lt real_valj gt upper bounds lt real_valj2 gt of ee intervals to include for sam lt real_valn1 gt pling according to distribution lt real_val 2 gt lt distribution g
122. 33 lin_rel char_arg1 arg2 relative linearity measure loc sens Tab 8 14 133 log arg1 natural logarithm basic Tab 8 4 109 log10 arg1 decade logarithm basic Tab 8 4 109 mask char_arg1 arg2 arg3 mask elements of argument arg2 set them advanced Tab 8 8 113 undefined un mask_file char_arg1 mask elements of argument arg2 set them advanced Tab 8 8 113 arg2 undefined according to information in file char_arg1 matmul arg1 arg2 matrix multiplication advanced Tab 8 8 113 max arg1 argument maximum of values aggr mom Tab 8 5 110 max_e arg1 run ensemble maximum UNC_MC max_lI char_arg1 arg2 dimension related argument maxima of values aggr mom Tab 8 7 112 of arg2 max_n arg1 argn maximum per element aggr mom Tab 8 5 111 maxprop arg1 index of the element where the maximum is aggr mom Tab 8 5 110 reached the first time maxprop_e arg1 run number where the maximum is reached UNC_MC Tab 8 13 130 the first time ri m Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H i f ji 223 arg2 Name Meaning Type See page maxprop_l char_arg1 arg2 dimension related argument position 1 n aggr mom Tab 8 7 112 where the maximum is reached the first time of arg2 maxprop_n arg1 argn argument position 1 n where th
123. 4 3 Example file world post_DFD_c Example 8 10 Experiment post processing operator dfd for DFD AA Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 iy HN aP I 129 8 4 5 Uncertainty Analysis Monte Carlo Method UNC_MC Tab 8 13 shows experiment specific operators for an UNC_MC experiment that can be used in post processing Tab 8 13 Experiment specific operators for UNC_MC without standard aggregation moment operators Argument N restriction s Argument value ame Meaning wae ae result description restriction Tab 8 1 page 106 min_e run ensemble minimum 1 arg1 max_e run ensemble maximum 1 arg1 sum_e run ensemble sum 1 arg1 avg_e run ensemble average 1 arg1 var_e run ensemble variance 1 arg1 avgg_ run ensemble geometric mean 1 arg1 avgh_e run ensemble harmonic mean 1 arg1 avgw_e run ensemble weighted mean of 2 1 arg1 arg1 arg2 weight arg2 hgr_e run ensemble dim res dim arg5 1 char_arg1 heuristic ext res ext arg5 for j 1 dim arg5 int_arg2 pdfs sepa ext res dim res number of bins real_arg3 rately calcu for char_arg1 bin_no bin number real_arg4 lated for each coord res dim res name bin_no arg5 index of arg5 values equidist_end 1 1 number of bins for char_arg1 bin_mid bin mid coord res
124. 8 Experiment post processor built in operators in alphabetical Order ecceeeeseeeeeeeeeeeeeeeeeeesateeeeeeeens 222 Character arguments of experiment post processor built in operators eeeeeeeresreieerrieerenrerenns 226 Constant arguments of experiment post processor built in Operators 2 eee eeeeeeeeneeeeeeeeeeeeeneeeeeenaes 228 Additionally used symbols for the model interface ccccccccceeceeceeeeeeeeeeeaeceeeeeeeceeeaeeeeeeeseseeceeeeeesenaeea 229 Additionally used symbols for the operator interface 0 eee eceeeneee sence eeeeneeeseeaaeeeseeeeeeeeeaeeeenenaeeeeneeeees 229 DIMENV SYStEMPGESION ereraa diaa aaa aa E DE aE E sagaeae bes bteebspapencatancbes 2 Factor Spacen eie fess areae raean r eae rA EEr EEF EAR EATE AEE diae EES AEE EEF sclasshss cdsabssasees shes favashevadedsledssadsacasmecicodee 14 sample for GSA_IEE E A T 18 Result plot for GSA EE csccssscectosceck cistentecnces cosvaundes ssacuiies shacensbaeqeuntysensnde ainidi aiiai inio nesiete 19 Sample TOMGSA VB spisana aai aer Eers Aie Raa a eE aA r E Eaa E ERSA 22 Sample for a Deterministic Factorial Design DFD eee cece ee enneeeeeeeeeeeeeeeeeeaaeeeeeeeaeeesnaeeeensaeeeeeenaeees 23 Deterministic Factorial Design DFD Scanning multi dimensional factor Spaces 23 Sample for a Monte Carlo analysis UNC_MC eee eeeeeeee eee eeeeenaeeeeeeeeeeeeaeeeeeeaaeeeseneaeeesnaeeeeeeaeeeeneaeees 24 Sample for a local sensitivity analysis LSA ooo eee ee
125. ATH lt se_home_path gt is the directory SimEnv is available from For SE_HOME at PIK check Tab 3 3 on page 10 for the complete environment check Tab 10 15 on page 168 Then apply the above setting by HOME profile e Change to a directory with full access permissions This is the SimEnv current workspace e Start simenv hlp to acquire basic information on how to use SimEnv e Select a model implementation language lt Ing gt to check SimEnv with the model world_ lt Ing gt from Example 1 1 on page 6 lt Ing gt f for Fortran Cc for C cpp for C py for Python ja for Java m for Matlab sh for shell script level as for ASCII file For Mathematica models check Section 5 6 on page 45 fora GAMS model example check Section 5 7 on page 46 e Start simenv cpy world_ lt Ing gt to copy the model world_ lt Ing gt model and experiment related files to the current workspace e Copy the file world edf_DFD_c to world_ lt Ing gt edf e Check for e The SimEnv configuration file world_ lt Ing gt cfg general SimEnv configurations e The model output description file world_ lt Ing gt mdf available model output variables e The model world_ lt Ing gt lt Ing gt implementation of the model e The model wrap shell script world_ lt Ing gt run wrapping the model executable e The experiment description file world_ lt Ing gt edf experiment definition e The post processing input file world post_D
126. B ooo eee cceeeeeeeeeeeeeeeeeeneeeeeeaaeeeeeeeeeeeseaeeeenenaeeeeeneaeees 126 Example 8 10 Experiment post processing operator dfd for DFD 0 cccceceeceeceeeeeeeeeeeaeeeeeeeseceaeeeeeeeseeeenaeaeeeeeees 129 Example 8 11 Experiment post processing operators for UNC_MC uo eee eeeeeceeeeeeeeeneeeeeeaeeeeeneaeeetaeeeeeeaeeeeneaaees 133 Example 8 12 Experiment post processing operators for LSA eeecceeeeeeeeeeeeeeeeeeneeeeeeeaeeeenaeeeeesaeeeeeeaeeeenneeeenes 135 Example 8 13 Experiment post processing operators for BAY_BC o0 ci ee eceeeeeeeeeeenneeeeeeeaeeeeeneeeeeeaeeesesaeeeenneeeene 136 Example 8 14 Experiment post processing operators for OPT_SA ou eeeeseeeeeeeeeeeenneee setae ee eeeeeeeeaeeeeeeiaeeeenieeeeneaa 137 Example 8 15 Composed operator S si niise atine aa eai aai abada teats oeteuaa fase in EREDE dslantyeeatn 144 Example 8 16 Operator description file lt model gt odf seeeeeesieseiresiireriisrsirnsitinsiiinttiinnitnnntittntiinnetknnnnnnnne nna 146 Example 8 17 User defined macro definition file lt model gt mac ssssesssriesriisssiissrriiesrirreriinntrnnntirtnniinneeerinnnnnnntnn 147 Example 8 18 Experiment post processing with wildcard operands eeeccceeeceeeeeneeeeeeneeeeeeneeeeeenaeeeseenaeeesnneeeeneas 148 Example 10 1 User defined general configuration file lt MmOdel gt CfQ eee eeeeeeeeeeeeeeeeeeeeeeeeaeeeeeeeeeeesnaeeeeeenaeeeeeenaeees 155 Example 11 1 Structure of a serdefined TINS miis
127. Character argument char_arg2 addresses the data file Character argument char_arg3 is used to define or transform structure information and coordinates from the data file Argument arg4 holds the variable that is to be extracted from the data file For restrictions in the path to the directory of the character arguments char_arg2 and char_arg3 check Tab 11 3 Cur rently ASCII and NetCDF files are supported char_arg1 ascii netcdf For ASCII data files the file syntax rules from Section 11 3 are valid Since the ASCII data file itself does not come with any structure and coordinate information a coordinate specification transformation file can be specified by the character argument char_arg3 For ASCII data files this argument is a manda tory one It follows the same rules as for any coordinate transformation file cf Section 11 2 Keywords general assign and coordinate and the appropriate sub keywords from Tab 11 5 can be used to structure the data file and to assign coordinates and coordinate values Consequently the keyword modify is not allowed See Example 8 4 for more information For ASCII files it is assumed that the file holds only the values for one variable in a sequence according to the Fortran storage model cf Section 15 7 Glossary For ASCII files argument arg4 is only a dummy placeholder For NetCDF files argument 4 addresses the variable name to extract from the data file The chara
128. E_HOME bin simenv_ dis par seq _ aix linux jcf if required optional lt model gt _opt_ options txt model specific control and option file for experiment type OPT_SA e Copy from SE_HOME bin simenv_opt_sa_options txt if required optional shell script applied for R Restart of an experiment by simenv rst lt model gt Ss Start of an experiment by simenv run lt model gt file applied for A All experiment performance on the login machine or by submission to a job management system J Job management experiment submission O OPT_SA experiment performance C make sure by the Unix Linux command chmod u x lt model gt lt ext gt that the shell script lt model gt lt ext gt has execute permission Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 simenv rst lt model gt simenv run lt model gt restart_ini yes in lt model gt cfg lt model gt ini return code 0 from lt model gt ini return code 0 from lt model gt ini lt run gt first single run lt run gt first single run Single run completed in previous experiments single run unfinished in previous experiments yes lt model gt run lt model gt run exists exists lt model gt lt run_char gt err lt model gt lt run_char gt err g lt run gt last single run lt run gt last single run Fig 7 1 Flowchart
129. Eine iiine Value Explanation eyword type nmb factor lt factor_ sample m 1 distr distr distribution and distribu name gt lt distribution gt tion parameters to derive file lt directory gt a sample of values lt file_name gt lt factor_smp_val gt file file name to import an external sample of val ues lt factor_smp_val gt sample _ c4 1 pseudo random sampling method method stratified only for distr lt distribution gt quasi sample _ 0 1 lt real_val 1 gt lower bounds lt real_val gt and include lt real_valj gt upper bounds lt real_valj2 gt of aig intervals to include for sam lt real_val 1 gt pling according to distribution lt real_val 2 gt lt distribution gt lt real_valj gt lt lt real_valj2 gt sample __ 0 1 lt real_val 41 gt lower bounds lt real_val gt and exclude lt real_valj2 gt upper bounds lt real_vali2 gt of s intervals to exclude from sam lt real_valm gt pling according to distribution lt real_valm2 gt lt distribution gt lt real_vali gt lt lt real_vali2 gt specific lt nil gt seed o 1 random fixed method how to initialize the random number generator Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Be careful when specifying for an experiment with probabilistic sampling a factor adjustment type cf Tab 6 2 that differs from set Values are sampled accord
130. Environment SimEnv User Guide for Version 3 01 July 10 2012 run lt simenv_run_char gt where the GAMS model is called from Make sure by the Unix Linux command chmod u x lt directory gt lt file_name gt that the shell script has execute permission e There has to be exactly one main GAMS model identified by the sub keyword type value main All other models have to be of sub keyword type value sub e To each GAMS model lt model_name gt an arbitrary number of factors and model output variables can be assigned to by the corresponding sub keyword get and or put To each sub model type sub at least one get or one put sub keyword must be assigned to The main model type main can be configured without any sub keyword get and put This is useful when the main model simply calls sub models Each factor and each model output variable as declared in lt model gt edf and lt model gt mdf respec tively has to be used in the value field of lt model gt gdf exactly one time Each model lt model_name gt in lt model gt gdf with at least one sub keyword get has to have an in clude lt model_name gt _simenv_get inc statement in the corresponding GAMS model file lt model_name gt gms Each model lt model_name gt in lt model gt gdf with at least one sub keyword put has to have an in clude lt model_name gt _simenv_put inc statement in the corre
131. Example 7 4 Shell script lt model gt run with shell script simenv_kill_PrOCeSS oe eee cece ee eeeeeeeeeneeeeeenaeeeeeeeeeees 92 Example 7 5 Handling model input and output files in multi run experiments eee cece ee eee ee erect eeeeenaeeeeeneeeenead 95 Example 7 6 Shell script lt model gt rst to prepare model performance during experiment restart 96 Example 8 1 Addressing results in experiment post proCeSSing ccccceeeeeeceeceeeeeeeeeeaeeeeeeeseseecaeaeeeeeeeeeesanaeees 102 Example 8 2 Addressing model output variables in experiment post processing ceecesceeeeeeeeeeeetteeeeeneeeeeeeeens 104 Example 8 3 Checking rules for COOrdINAtES ee cece ceeeeeeeeeee ee eeeeaeeeteeeeeeeeaaeeeeeeeaaeeeseeeeeesaeeeseeaeeesneeeeeneneeeeseaaes 107 Example 8 4 Experiment post processing operator get_data and coordinate transformation file 0 0 0 0 117 Example 8 5 Experiment post processing operators un mask_file nnnsneesnnnnenesseenr eeeeeeeeeeeeeeseseneaeeeeeeeeeteenaees 119 Example 8 6 Experiment post processing with advanced OperatOrs eeccceeeeeeeeeseeeeeeeeeneeeseeeeeesneeeseeaeeeeneaaees 122 Example 8 7 Multi and single run experiment post processing Operators sssssssssserrrtsssstrrrrsnserttnnnnnesrrrnn nennen 123 Example 8 8 Experiment post processing operators for GSA_EE sssesreerisesiissreiieeriireeiinstirnsriitesiinneernnnrnnnt 124 Example 8 9 Experiment post processing operators for GSA_V
132. FD_c post processor result sequence Either e Start simenv cpl world_ lt Ing gt 1 world post_DFD_c to run a complete SimEnv session e Model and experiment related files will be checked e The experiment will be prepared e The experiment will be performed select the login machine on request g Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji 7 e Experiment output post processing will be started for this experiment e With the post processing input file world_post_DFD_c and following e Interactively Enter any result and finish post processing by entering a single lt return gt e Visualization of post processed results will be started e Model or result output files will be dumped or e Start simenv chk world_ lt Ing gt to check model and experiment relate files e Start simenv run world_ lt Ing gt to prepare and perform a simulation experiment select the login machine on request e Start simenv res world_ lt Ing gt new lt simenv_run_int gt to post process the last simulation experiment for the whole run ensemble or for run number lt simenv_run_int gt and to create a new result file world_ lt Ing gt res lt simenv_res_char gt nc ieee as cii with the highest two digit number lt simenv_res_char gt lt simenv_res_char gt can range from 01 to 99 e Start simenv vis world _ lt Ing g
133. HOME bin simenv_ini_sh SE_HOME bin simenv_run_gams SE_HOME bin simenv_end_sh lt model gt end lt model gt end cf Section 7 1 on page 89 is for GAMS models a mandatory shell script and has to have the contents for all GAMS models SE_HOME bin simenv_end_gams additional user model specific commands can follow Python programming language is used to prepare run and to end an experiment with a GAMS model 5 7 2 GAMS Description File lt model gt gdf lt model gt edf lt model gt mdf e AnASCII GAMS description file lt model gt gdf see below has to be supplied The ASCII GAMS description file lt model gt gdf is intended to specify the GAMS sub models and assigned factors and model output variables in detail Derived from this information a block of lines for each GAMS sub model with a simenv_get inc file and or a simenv_put inc file is created The file lt model gt gdf holds the specific characteristics of GAMS model input and output needed by SimEnv to generate GAMS put statements All model output variables from the model output description file and all factors from the factor description file have to be used in this file again lt model gt gdf is an ASCII file that follows the coding rules in Section 11 1 on page 169 with the keywords names sub keywords and values as in Tab 5 3 io 48 y H an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July
134. July 10 2012 Tab 11 4 Line types in user defined files ede User defined file Explanation viation m all files mandatory 0 all files optional c1 lt model gt mdf conditional 1 keyword variable forbidden for variables with dimensionality 0 sub keyword _ coords mandatory for variables with dimensionality gt 0 index_extents c2 lt model gt mdf conditional 2 keyword variable forbidden for variables with dimensionality 0 sub keyword coord_extents optional for variables with dimensionality gt 0 c3 lt model gt edf conditional 3 keyword factor mandatory for experiment type UNC_MC sub keyword sample forbidden for experiment type LSA conditional for experiment type DFD c4 lt model gt edf conditional 4 for probabilistic sampling mandatory for sample distr keyword factor forbidden for sample file sub keyword sample_method a lt model gt edf alternatively for DFD either mandatory for all experiment factors keyword factor or forbidden for all experiment factors sub keyword sample f lt model gt edf forbidden for LSA keyword factor sub keyword sample mac descr This is a macro description file mac descr for the SimEnv User Guide macro pol _ atmo descr atmo outside polar reg final time level 1 macro pol atmo unit without macro pol _ atmo define atmo c 84 56 c 1 c 20
135. Matlab model in lt model gt run by matlab nojvm nosplash lt model_name Contrary to general Matlab syntax variable and factor names as the first argument in simenv_get_m simenv_slice_m and simenv_put_m are not case sensitive and are transformed to lower cases in the appropriate Matlab interface function See also Section 10 7 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 e Errors that occur during performance of one of the above Python Java or Matlab interface modules methods are directly reported to the log file lt model gt nlog Set in HOME profile the Python Java and or Matlab environment include the path to python Java and or Matlab in the PATH environment variable and specify for Python the PYTHONPATH environment variable accordingly to the need of the Python model For more information check Section 10 9 In Example 15 5 on page 202 the Python model world_py py is described in detail in Example 15 6 on page 203 the Java model world_ja java and in Example 15 7 on page 204 the Matlab model world_m m 5 5 1 Standard Dot Scripts for Python Java and Matlab Models lt model gt ini lt model gt ini cf Section 7 1 on page 89 is for Python Java and Matlab models a mandatory shell script and has to have the same contents for all Python Java and or Matlab models SE_HOME bin simenv_ini_ py ja m return code from simenv_ini_ py ja m is rc_simenv_ini_ py
136. N DIEGO dem ch D I J distance in thousands of miles NEW YORK CHICAGO TOPEKA SEATTLE 208 Lod Lasts SCALAR F SAN DIEGO a sts 1 4 r freight in dollars per case per thousand miles 90 get the model status as a model output modstat is set to transport modelstat PARAMETER C I J transport cost in thousands of dollars per case Chipo F DJ LOOM 2 VARIABLES X I J shipment quantities in cases Z EOE tiEcinispOmeciaVOnCOst oN eholcancd smote olMansie POSITIVE VARIABLE X EQUATIONS COS define objective function SURETA observe supply limit at plant i DEMAND J satisfy demand at market j COSTER A a SN y Cr apa zg SURREY SUMO Cle rrels ip AGL 2 DEMAND J SUM 24 CE J G B J MODEL TRANSPORT ALL SOLVE TRANSPORT USING LP MINIMIZING Z a f yy 206 iis iy lt Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 After solving the equations include simenv_put inc has to be inserted simenv_put inc is generated automatically by SimEnv based on lt model gt edf and lt model gt gdf Additional GAMS statements are possible after the Sinclude statement modstat transport modelstat include gams_model_simenv_put inc t 4 Only if submodels etio mi and sub m2 are coupled cf Example 5 3 call gams sub_ml gms 11 lo 2 1f sub_m1 nlog dp 0 Optdi
137. NV service uu eee cece eeeneeeeeeenaeeeteeeeeeeteeeeeeeaeeeenenaeees 159 Files generated during performance of SIMENV Services 0 0 eee ceeeeeeeeeeeeeteeaeeeseeeeeeeenaeeeseeaaeeeeeenaeees 160 Built in model output variables saissetiae aTa EASE 164 Built in shell script variables in lt model gt run cececeeece cece ce eeeeee ee cece ee eeceaeaeeeeeeeseeacaeeeeeeeeeeseeseeaeeeeeeeeeea 164 Built in coordinates for experiment POSt PrOCeSSING eee ceeeeeee eset eeeeereeeeeeeeeeeeaeeeseeeaeeesnneeeenenaeeeeeeaeees 164 Case sensitivity of SimEnv entities Data type related nodata values ENvirOnment Variables wc s c ccccsduedeasneceecday ie ea aE r E a E E E E Ee a eaa r aaa AE 167 Programs to include in the environment variable PATH c ccccceeeeeeeeaeceeeeeeeeeneaeeeeeeeseeenaeeeeeeeeeeeeea 168 User defined files with general StruCturre cci c eccececeiecceesseeceeeseceeenecseceensceseste sooeessdeceseaeneedenssnenbvnatnetse 170 Constraints in user defined files ccccccceeeeeeceeceeeeeeeeeenae cece ees eaaeaeceeeeeeeeeaaeaeeeeeeeseeaaeaeeeeeeeeneaneeeeeeees 170 Reserved names and file names in user defined files Line types in user defined files ccccccccecccecce cece eeeeee aces ce eeeeeeeaaeaeceeeeeseaaeaaaeceeeeeeneceeaeeeeeeeseceeaeeeeeeeeneeaea Elements of a coordinate transformation file 0 eee ce cece eeeeneeeeeeeeeeseeeeeeesaeeeeeeaaeeeeeeeaeeeseeeeeneaeaee
138. On Name Meaning Type See page sym_abs char_arg1 arg2 absolute symmetry measure loc sens Tab 8 14 133 sym_rel char_arg1 arg2 relative symmetry measure loc sens Tab 8 14 133 tan arg1 tangent trigonom Tab 8 4 109 tanh arg1 hyperbolic tangent trigonom Tab 8 4 109 transpose char_argi arg2 _ transpose arg2 according to char_arg1 advanced Tab 8 8 113 undef undefined element advanced Tab 8 8 113 usage char_arg1 get usage of post proc operator char_arg1 advanced Tab 8 8 113 var arg1 argument variance of values aggr mom Tab 8 5 110 var_e arg1 run ensemble variance UNC_MC Tab 8 13 130 var_I char_arg1 arg2 dimension related argument variances of val aggr mom Tab 8 7 112 ues of arg2 3 m Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H i J i 225 15 5 3 Character Arguments of Experiment Post Processor Built In Operators Tab 15 10 summarises for built in operators character argument values User defined operators cannot have pre defined character argument values Tab 15 10 Character arguments of experiment post processor built in operators Character argument can be empty gt The length of the character argument from a sequence of digits corresponds to the dimensionality of the non character and non constant argument under investigation Argument value Operator Argument without quotation marks
139. Post processing operators for experiment type UNC_MC are now also available for all the other experiment types new Section 10 3 157 New Section on experiment performance tuning update Tab 15 2 189 Atthe compute cluster at PIK the NetCDF library libnetcdf a used for SimEnv is now located in iplex 01 sys libraries netcdf3 lib This library is used to link interfaced models and user defined operators Update link files accordingly Bug fixes Tab 3 2 User actions to upgrade to Version 3 01 Upgrade type Upgrade action mandatory Re link interfaced models and user defined operators mandatory Update in experiment description files lt model gt edf the name of the experiment type Tab 3 3 SimEnv availability at PIK machines Machine Login node SE_HOME Iplex compute cluster login01 login02 iplex 01 sys applications simenv visualization cluster vissO1 vissO2 iplex 01 sys applications simenv bs08 usr local simenv a m 10 y H ya J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 3 2 Limitations Problems and Their Workarounds Tab 3 4 Limitations problems and their workarounds in Version 3 01 Where Limitation gi Problem Description Workaround Where Overall Limitation Current SimEnv technical limitations as specified in Tab 15 3 on page 190 Workaround None Where Overall but visual result evaluation Limitation Without graphical user interface Workaround None Wh
140. SimEnv User Guide for Version 3 01 July 10 2012 y HN ua f ji 81 Bayesian calibration is the only experiment type that comes with a mandatory SimEnv file which supple ments the experiment definition file lt model gt edf This supplementary file is the Bayesian calibration descrip tion file lt model gt bdf where the applied MCMC method the covariance matrix for the normal multivariate jump and the likelihood function s are defined To Tab 6 11 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e Sub keyword method The method metropolis_standard corresponds to the regular Metropolis Hastings algorithm while for me tropolis_reflected the so called Metropolis with Reflection algorithm check Section 4 7 is used The lat ter method demands per factor only one resulting interval as the intersection from the definition domain of the distribution and sample_include sample_exclude intervals specified in lt model gt edf e Sub keyword cov_matrix Specify here the name of a file that holds the covariance matrix of all factors The covariance matrix is used for the normal multivariate jump from an accepted point in the factor space to a candidate point Only the lower triangular matrix including the diagonal with the factor variances has to be provided Se quence of rows and columns of the matrix is determined by the sequence of factors in lt model gt edf Line number i i
141. The sequence of the four integer values lt int_val gt built in user defined and composed operators e The sum lt int_val gt lt int_val gt has to be less equal 9 e Use the SimEnv service simenv chk to check user defined and composed operators lt int_val gt follows the sequence of arguments in Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 general descr Operator description for the general descr examples in the SimEnv User Guide opr defined matmul_f descr meacriz m ilciplicacironm in Torrtren opr defined matmul_f arguments OF OF Ore opr defined matmul_c descr matrix multiplication in C opr defined matmul_c arguments 0002 opr defined Corr COS descr Correlation Coetiiciemwt ic opr defined COrrECOCH E arguments 0 002 opr defined div descr arithmetic division opr defined div arguments OOF One opr defined simple div descr division without undefined check opr defined simple div arguments OF OF OFZ opr defined Cham eSsic descr test character arguments opr defined Chicka Sie arguments 27 07 Oy Al opr composed rel count descr relative count opr composed rel count arguments 7 O 0 al opr_ composed rel count define MOr ecounearo Marg 2 Gor composed rel count define Count allie p arez Example files world_ f c cpp py ja m sh odf Example 8 16 Operator description file lt model gt odf 8 6 Macros and Macro
142. _ lat lon phi_ lat lon n 12 value_ lat lon last sin nm omega_ lat lon phi_ lat lon n 12 Finally atmo lat lon level time value _lat lat value_lon lon 100 time level 1 bios lat lon time value_lat lat value_lon lon 100 time and notated in the syntax of the SimEnv post processor atmo_g time avg_1 001 abs atmo lat lon 1 time bios g avg abs bios lat lon time Means avg and avg_ are calculated in a box with the extent Alat x Alon 10 x 10 and lat lon 0 0 in the mid of the box lt ane Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 SHL _ 195 15 2 2 Fortran Model With respect to Example 5 1 the following Fortran code world_f f could be used to describe the model inter faced to SimEnv SimEnv modifications are marked in bold program world f c declare SimE nv interface functions compile with IPSE HOME inc include simenv_mod_f inc integer 4 simenv_sts simenv_run_int character 6 simenv_run_char c declare atmo without dimensions level and time and bios without time real 4 real 4 integer 4 integer 4 CLORO e WN Io WW DWN simenv_sts simenv_sts simenv_sts simenv_sts simenv_sts simenv_sts enddo enddo simenv_sts simenv_sts simenv_sts end do level simenv_sts simenv_sts simenv_sts c because they are computed in place and simenv_s
143. _get_run_sh for sequential experiment performance my_model mv my model out my _model out simenv_run_char sequential end for parallel and distributed experiment performance mkdir run simenv_run_char cd run simenv_run_char GO sa uhy model in my_model mv my model out my_model out simenv_run_char AA 94 y HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Gish ae rmdir run simenv_run_char parallel and distributed end perform always and as the last SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_end_sh Example 7 5 Handling model input and output files in multi run experiments Inter node communication for parallel sub mode at compute clusters The Message Passing Interface MPI is used for this sub mode To start the simenv binary SE_HOME bin simenv_run_par MPI needs ssh connections between the nodes blades of the compute cluster The ssh connections need public and private keys and appropriate authorization entries At the PIK compute clusters openssh is used openssh uses the directory ssh for key files A minimal di rectory contents of ssh looks like this login02 gt 1s id d r sa private key id d sa pub public key authorized keys file of accepted public keys id_ d r sa pub must be authorised_keys Pay attention that id_ d r sa and id_ d r
144. _l char_arg1 arg2 avgh_l char_arg1 arg2 avgw_ char_arg1 arg2 arg3 count_l char_arg1 char_arg2 arg3 dim argi gt 1 ext argi arbitrary dim res ext res i according to char_arg1 and argi dim arg2 dim arg3 ext arg2 i ext arg3 i arg3 weight char_arg2 all def undef minprop_ char_arg1 arg2 maxprop_ char_arg1 arg2 as above but dim res is increased by 1 ext res dim res dim arg2 coord res dim res equidist_end 1 1 n return the indices of those elements of arg2 where the extreme is reached the first time according to char_arg1 and to a For tran like processing sequence storage model cf Section 15 7 Glossary of the argument field arg2 name index values hgr_l char_arg1 char_arg2 int_arg3 real_arg4 real_arg5 arg6 heuristic pdf s separately calculated for each index of the those dimensions of arg5 that remain according to char_arg1 dim res ext res dim res for char_arg2 bin_no 1 dim res of all other operators of this Tab number of bins bin number coord res dim res name bin_no values equidist_end 1 1 number of bins for char_arg2 bin_mid bin mid coord res dim res name bin_mid char_arg2 int_arg3 real_arg4 real_arg5 real_arg4 real_arg5 0 values equidist_end 1 bin mid bin width number of bins bin_no
145. _value gt is missing c stands for coordinate addressing e Index and coordinate ranges are separated from each other by a comma the sequence of ranges for all dimensions is enclosed in brackets and is appended after the variable name e For one variable c and i can be used in mixed mode for different dimensions denotes the complete range of a dimension c isidenticalto i is identicalto aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i _ 103 e In the general SimEnv configuration file lt model gt cfg cf Section 10 1 on page 151 a global default for index and or coordinate addressing is established for the whole experiment post processing ses sion This global default can be overwritten locally by using c and or i cm cm cm cm cm cm cm ooonoopoaga ow cm atmo atmo atmo atmo atmo atmo atmo Having a model output variable definition as in Example 5 1 on page 40 then in experiment post processing result expressions can be and P 7 and C pile and c 88 88 c 178 178 c 1 16 c 1 20 and 1145 i l OO deal sti 920 E 1 1e4S cS 17ss le and 1s45 1390 134 1320 and with address_ default index in model cfg 1 45 c 178 178 1 4 1 20 and with address_default index in model cfg all address all 45 90 4 20 values and the following holds for this addressed variable Dimensionality 4 Coor
146. _working_directory SimEnvVis working directory on the visualization server server_SimEnv_home_directory SE_HOME directory on the visualization server ssh_local ssh implementation of the client com puter scp_local scp implementation of the client com puter ssh keygen_local ssh keygen implementation of the client computer nc_libpath directory the NetCDF shared object libraries are located for Linux S AEA Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN i f ji 151 In the ASCII file lt model gt cfg general SimEnv control variables can be declared lt model gt cfg is workspace and model related and is an ASCII file that follows the coding rules in Section 11 1 on page 169 with the keywords names sub keywords and info as in Tab 10 2 Tab 10 2 Elements of a general model related configuration file lt model gt cfg Max Keyword Name k aun rine iiine Value Explanation eyword type nmb general lt nil gt descr o any lt string gt general configuration description message_level o 1 info warning specifies which message types error to show model lt nil gt out_directory 0 1 lt directory gt model output directory out_format 0 1 netcdf ieee model output format out_separation o 1 yes no indicates whether to store model output in a single file per single run
147. a distance measure in a specific metric between selected model state variables and reference data measurement values of the real system or simulation results from an other model Conse quently optimization can be used for model validation and control design to find optimal values of model factors in such a way that model state variables are close to reference data In SimEnv the cost function is specified in experiment preparation as a single run result formed from model output and reference data where an operator chain is applied on cf Section 6 7 and Chapter 8 The value of the cost function is cal culated directly after the current single run has been performed SimEnv uses a gradient free optimization approach that is called Simulated Annealing and is a generali zation of a Monte Carlo method for examining the state equations of n body systems The concept is based on the manner in which metals recrystalise in the process of annealing In an annealing process a melt ini tially at high temperature Temp and disordered is slowly cooled so that the system at any time is approxi mately in thermodynamic equilibrium As cooling proceeds the system becomes more ordered and ap proaches a frozen ground state at Temp 0 Hence the process can be thought of as an adiabatic ap proach to the lowest energy state E If the initial temperature of the system is too low or cooling is done in sufficiently slowly the system may become quenched formi
148. a factor value as script variable 58 S IEF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H ua f 157 See Dot script Use status Used for Section simenv_get_as optional get all factor names and adj values to an ASCII file 59 simenv_run_gams mandatory run a GAMS model Mi simenv_run_mathematica mandatory run a Mathematica model 5 6 simenv_put_as optional put ASCII file to SimEnv model output 5 9 simenv_put_as_ simple optional put ASCII file to SimEnv model output simple mode 5 9 simenv_bay_bc_sh optional control multiple setting case fora BAY_BC experim 2 simenv_kill_ process optional kill a program model after reaching a CPU time limit 6 7 3 lt model gt _ sh as inc optional semi automated model interface at shell script 510 ASCII level cf also Tab 10 6 a lt model gt end simenv_end_gams mandatory experiment end for GAMS models S In Tab 10 6 all that include files and link scripts are compiled that are provided by the simulation environ ment or generated by the user and or automatically during performing a SimEnv service Tab 10 6 SimEnv include files and link scripts File Used in Explanation location generated during simenv_mod_ used in shell script to compile and link an interfaced model f c cpp Ink stand alone source code for experiment performance If
149. a model by the shell script file lt model gt run as for standard and distributed models Instead performing the model within lt model gt run submit it there to the load leveler LoadL by using the Ilsubmit command Start an experiment from a login node of the compute cluster and run the experiment at the login machine in foreground SimEnv submits from the login machine all single runs to LoadL and directly finishes afterwards The load leveler LoadL and the parallel operating environment POE then take responsibility for performing the single model runs For the parallel modus the temporary SimEnv files simenv_ tmp are not deleted at experiment end i e after all single model runs are submitted These files can be removed manually after finishing the last single run Check the LoadL services for the end of the last parallel single model run To support bookkeeping of SimEnv applications on PIK s compute cluster machines insert into the job con trol file to submit a single model run file my_parallel_model jcf in the example below the line comment SimEnv Application To perform a parallel model in SimEnv the corresponding shell script lt model gt run cf Section 7 1 for more information could have the following contents bin sh SSE _HOME bin simenv_ini_sh run a single run of the model llsubmit my parallel model jcf SSE_HOME bin simenv_end_sh Example 5 7 Shell script lt model gt run
150. able_name gt coo_type 1 2 integer lt variable_name gt data_range lt min gt lt max gt char lt variable_name gt index_range_ lt coordinate gt lt min_index gt lt max_index gt int lt variable_name gt simenv_data_kind predefined model output variable _ char model factor model output variable postproc_result lt variable_name gt var_representation positions connections or both char lt variable_name gt grid_shift lt shift_x gt lt shift_y gt real dimension 2 lt variable_name gt north_pole lt lon_pole gt lt lat_pole gt real dimension 2 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 JHN Pny 179 e The monotony attribute is applied to coordinate variables only and estimated from the coordinate val ues as defined in the lt model gt mdf file During post processing additional coordinates can be generated for which no monotony may be estimated In such cases the attribute is set to none e The coo_type attribute describes the grid representation of a given coordinate A value of 1 indicates that all coordinate values are provided explicitly suitable e g for irregular grids A value of 2 indicates a regular grid and a coordinate representation by its start value increment and end value e The data_range attribute provides the real range that is covered by the related variable in the recent NetCDF file e The in
151. aeeseecceeesssedeeeedecdeesscendesseceesetenseetee 166 10 9 Operating System Environment Variables eccceceeeeeee cence eeeeneeeeeeeaeeeseneeeeeeaeeeeeeaeeeenneeeeeenaeaeeaaes 167 11 STRUCTURE OF USER DEFINED FILES COORDINATE TRANSFORMATION FILES VALUE LISTS 169 11 1 General Structure of User Defined Fil S 2 00 ccccsccccecceneceecceeeesnateecaenceeensuecenewudneeeesccnesesdercennecdereeesiedendectee 169 11 2 Coordinate Transformation File cc ec eeseeceeeeeeeeeneeeceeaeeeeeneeeeeeeaeeeeeeaaeeeeeeeeeeesnaeeeeseaeeeenneeeennaeeeseeaes 171 11 3 ASCIL Data Files and Value Lists airis rarene aeeai a iaee raa AE a e EA E EA EEE 174 a m F J VI e fisi pl 21S A y ulti Run Simulation Environment SimEnv ser Guide for Version 3 uly 10 VI DENY Multi Run Simulation Envi SimE User Guide for Version 3 01 July 10 2012 12 MODEL AND EXPERIMENT POST PROCESSOR OUTPUT DATA STRUCTURES ecce 127 12 1 NetCDF Model and Experiment Post Processor Output 0 0 eee eeeeeeeeeeneeeeeeaeeeseeeaeeeseaeeeeeeaeeeeeeaeees 177 12 1 1 GloBal Attributes isco cass eetteeiiics rere a ea aeaa eaaa aa a r aha ine A AEEA E eis AEE 178 12 1 2 Variable Labeling and Variable Attributes cccccecececcce cece eeeeeeeeaeceeeeeseceeeaeeeeeeesesneaeaeeeeeeeseesenaeees 178 12 2 IEEE Compliant Binary Model Output 0 0 eee eee eeneeeceeeeeeeeeneeeeeeaaeeeseeeeeeesaeeeeeeaaeeeseeeaeeeseeeeeeeaeeseeaaeess 180 12 3 IEEE Compliant Binary and ASCII Experiment Pos
152. al Features in OPT_SA Qo ceecceeeeeneeeeeenneeeeeeeeeeeeaeeeseeaaeeeeeeneeeeseaeeeeseaeeeeeeeeeeesneeeeesnaeeeeeeaeees 87 6 8 2 EXAM Pl Gigaset E Paes Sede E E vocnennsfoepeea A reseee cea peoaeenvayiee anes 88 7 EXPERIMENT PERFORMANCE visesti a iraa Ea aAa EAEE ERACE 89 7 1 Generali APPFOACH issaeiwcdsccedeesshevntuaele eeseclhewiehees bedi rea a aie A E a ewes aE Ee E a a aaea aaa a anaa aaa 89 7 2 Model Wrap Shell Script lt model gt run Experiment Specific Preparation and Wrap Up Shell Scripts 90 7 3 Experiment Parallelization ccc ceceecceeeeeneeeeeneeeeeeneeeeeeeeeeeeeaeeeseeeaeeeeeneeeeeeaeeeeeeaeeeenneeeeseaeeseenaeeeenneeeeneaa 7 4 Experiment Restart eee 7 5 Experiment Partial Performance 96 7 6 Experiment Related User Shell Scripts and Files cccceceeeeeeeeeeeeeeeeeneeeeeeeaeeeseneeeeesnaeeeeeenaeeeenneeeeneaa 97 7 7 Saving EXP SMIMEMNS esis eases eth ar a ee a O Er A a nrcdsue esuccetssreestesvedeadlvasareeucecesi everson ticenks 99 EXPERIMENT POST PROCESSING ictisscesctitecetweduareenatcecs te ais ovteutage cntunepenseace gees a iito naiaiae naise ireas inarin 101 8 1 General ApproaCh rrian cenieni rande eireas eerren ere e eaa ede daer adaa aeaee e Eaa EE eiaa aiarad aa E iaa EEE ERE 101 8 1 1 P st Processor RESUILS cria eirn dacechcweaelas bvadeenpetac cueantidcentecs stia dae deddandecveabea Ceaametenetacees 101 8 1 2 OPPS iss edie sc cde shed buted iedcag bis bot decda Lecapeedcandavaseenapeds bes asudness devcageny sa
153. al Sensitivity Analysis Elementary Effects Method GSA_EE seeieesrerreerrerinrrn 124 8 4 3 Global Sensitivity Analysis Variance Based Method GSA_VB sesieerissrrisrrrireerrrrserrsnrenss 125 8 4 4 Deterministic Factorial Design DFD cc c ccctecnesinccsescenecetecenecnecteceessceceenssotendessneseaenersenseceesnnnetense 126 8 4 5 Uncertainty Analysis Monte Carlo Method UNC_MC ceeeccceeeceeeeeeeeeeeneeeeeeeeeeesneeeseenaeeeenenaees 130 8 4 6 Local Sensitivity Analysis LSA ie ieicstes aids vesecatateadecetecescegecdes ateigada aiina Raa cdanueenatan ste 133 8 4 7 Bayesian Technique Bayesian Calibration BAY _BC o eeecceecseeeeneeeeeeneeeeeeeeeeesnaeeeeeenaeereeeeaeees 135 8 4 8 Optimization Simulated Annealing OPT_SA Wu eeceeeeceeeeenneeeeeeeeeeeeneeeeeeaeeeeeeaeeeenneeeeeenaeeeeeeaas 137 8 5 User Defined and Composed Operators Operator Interface 0 eee eee eeeeeeeeenneeeeeeeeeeenneeeeeeaeeeeeenaeens 137 8 5 1 Declaration of User Defined Operator DynaMmics c ccccceeeceeceeceeeeeeeeeeeaeeeeeeeeeseceeaeeeeeeeeeeeeaaees 138 8 5 2 Undefined Results in User Defined Operators eeececeenneeeeeeeeeeeeeeeeeeeaeeeeeeeeeeeeneeeeseenaeeeenenaees 143 8 5 3 Composed Operators oncicjsacci siscaees igs ainn ea na Eaa EE AEE E TE i EEEa aia 143 8 5 4 Operator Description File lt model gt Of is aia arnari nauraa 145 8 6 Macros and Macro Definition File lt model gt mac cccceceeeeeeceeeeeeeeeece
154. al integration For quasi random sampling the first values of the sequence are skipped 1500 values for a fixed seed for a ran dom seed the number of values is randomly selected within the interval lt 1000 2000 gt Check also the Figures below Pseudo and stratified random sampling at first generate a factor sample uniformly or stratified uniformly distributed on lt 0 1 gt For quasi random sampling a Sobol sequence is taken Afterwards these values Xi lt o 1 gt are transformed to the target distribution as specified by lt distribution gt The definition domain of the distribution according to sample_include and sample_exclude sub keywords is taken into account and random numbers of the target distribution are identified as the quantiles of Xi lt o 1 gt A sample method can not be specified for experiment types GSA_EE and BAY_BC e Sub keywords sample_include and sample_exclude With the sub keywords sample_include and sample_exclude intervals to sample from can be specified explicitly when the distribution is defined by sample distr lt distribution gt A typical example for applica tion of these two sub keywords is to exclude values from the distribution tails If include or exclude inter vals are not specified the corresponding overall defaults from the distribution are applied Use inf to de clare a positive infinite interval boundary and inf for a negative infinite interval boundary The result from the overlay of all include and
155. al rules and explanations apply e For the description of line type check Tab 11 4 on page 171 The sub keyword time_limit enables limitation of each GAMS model single run in the run ensemble to a maximum wall clock time consumption If this threshold is reached the single run is aborted and the fol lowing single run started In general SimEnv nodata values will be assigned to the results of the aborted single runs The sub keyword time_limit can be necessary since each GAMS model single run itself is an optimization procedure which could result in an unfeasible wall clock time consumption If the sub keyword is not used in the gdf file wall clock time consumption per single run is unlimited If the sub keyword options is not specified the GAMS main model is started with the default options 11 0 lo 2 dp 0 complemented by lf main_model lt simenv_run_char gt nlog Optdir Check also Section 5 7 3 By the sub keyword script a shell script can be specified that will be performed before each single GAMS model run By default the shell script is expected to be located in the current workspace The shell script is performed from the sub directory run lt simenv_run_char gt of the current workspace cf Section 5 7 3 The shell script has one argument the current run number lt simenv_run_char gt formed from six characters For example the script can be used to copy some files into the sub directory Multi Run Simulation
156. alue of argument iarg at index index simenv_ get_arg_ Operands of any type are transferred by fic simenv_get_arg_ f c to a real 4 float repre function value sentation Operands of a dimensionality gt 1 are forwarded to user defined operators as one dimensional vectors using the Fortran storage model cf Section 15 7 Glossary Adjust the second argument of simenv_get_arg_ f c index accordingly simenv_ overflow real 8 value to be checked clip_undef_ set areal 8 value value fic to an undefined input real 4 result z value if appropriate real j Example simenv res i simenv clip undef f c underflow clip_undef_ value set a real 8 value flc to real 4 0 d f y function value if appropriate simenv_ check whether real 4 argument value to be checked chk_undef_ value is undefined value fic before processing input it integer 4 0 value is defined value simenv_ 1 value is undefined is_undef_ fic function value simenv_ set a result value real 4 Example put_undef_ as undefined simenv_ res i simenv_put_undef f c f c put_undef_ fic function value e In SimEnv the declarative and computational part of a user defined operator lt opr gt is hosted in a source file usr_opr_ lt opr gt f c cpp The assigned executable has the name usr_opr_ lt opr gt and has to be lo cated in that directory that is stated in lt model gt cfg as the hosting directory opr_dire
157. ample RS Run model for the sample S the re sample R and the k resulting samples RS to get 2 S 248 2 5 Z Z S44 Stk sees Z Snt se Z Snk z R z TEET Za Z r41 iaa rak ia 2 tn1 pin Z rnk ZSR SE ia za Y sr sa Sk Jra AlS aa ZS 9 gt FAA Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN ua i lt 21 2 S z RS n 7 S To estimate S use model output from S and RS S E y S o y S n z S R oz RS n z R To estimate S use model output from R and RS Sr ARISES AE z R o z R n z R with o scalar product Fig z A oz B 9 2 zP i l n 2A gt lt i l x X212 sub sample and sub re sample of size 12 each in the 2 dimensional factor space X2 X1 X2 o X21 default nominal numerical factor constellation of model M 4 4 Sample for GSA_VB 4 4 Deterministic Factorial Design DFD Deterministic Factorial Design DFD uses a deterministic strategy to sample X It is the inspection of the model in the factor space X where inspection points are set in a regular and well structured manner A DFD experiment can be interpreted and used in different ways For scenario analysis to show how model behaviour changes with changes of factor values For numerical validation purposes to determine factor values in such a way that the output vector matches with measurement re
158. ance for distributed models across networks e Multi file model output storage Experiment post processing e Additional advanced operators coarse sort categorical operators e Advanced uncertainty operators e Flexible assignment of data types to operator results currently only float e Shared memory access for user defined operators to avoid data exchange by external files Visual experiment evaluation e Advanced techniques for graphical representation of experiment post processor output especially for multi run operators aes Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN a J lt 183 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 14 References and Further Readings Campolongo F Cariboni J Saltelli A Schoutens W 2005 Enhancing the Morris Method In Hanson K M Hemez F M eds Sensitivity Analysis of Model Output Proceedings of the 4th International Conference on Sensitivity Analysis of Model Output SAMO 2004 Los Alamos National Laboratory Los Alamos U S A 369 379 http library lanl gov cgi bin getdoc event SAMO2004 amp document samo04 52 pdf European Commission Joint Research Centre IPSC 2006 SimLab 3 Website http simlab jrc ec europa eu Flechsig M 1998 SPRINT S A Parallelization Tool for Experiments with Simulation Models PIK Report No 47 Potsdam Institute for Climate Impact Research
159. and as the last SimEnv dot script in lt model gt run and lt model gt rst Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 e For the model interface at the shell script level i e within the shell script lt model gt run the adjusted ex periment factors for the current single run from the whole run ensemble can be made available to for ward them to the model under investigation by any means the modeller is responsible for One common way to forward experiment factors to the model is to place current numerical factor values as arguments to the model executable at the model command line in Unix or Linux Another way could be to read the factors from a special file in a special file format e While for the C C Fortran Python Java Matlab model interface the names of corresponding factors in the model description file lt model gt edf and the model source code can differ and are associated by the first argument of the interface function simenv_put_ cf Fig 5 1 the names have to coincide for the model interface at the shell script level e Directly before performing the dot script SE_HOME bin simenv_get_sh make sure that the shell script variables factor_name and factor_def_val have been specified At the end of the dot script simenv_get_sh the values of these variables are set again to empty strings e After running the dot script SE_HOME bin simenv_get_sh the name of an experiment fact
160. arency reasons Description entity name should be the same as source code entity name unlike this example Fortran model source cade program model integer 4 simenv_in f simenv_get_f sime real 4 model_factd source code e dimension model_var source code efti model factor is the default factor value oa as specified in the previous statement simenv_sts simenv_ini_f to be used as the adjusted value if ete edf_factor is undefined in lt model gt edf model_ factor simenv_sts simenv_get_f model_var simenv_sts simenv_put_f simenv_sts simenv_end_f model_ factor is e the adjusted end field model_var is factor value output as mdf_var for C C Python in a likewise manner Fig 5 1 Conceptual scheme of the model interface for C C Fortran Python Java and Matlab p 36 y HN ia ii Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 5 2 Coordinate and Grid Assignments to Variables To each variable e Dimensionality dim variable e Extents ext variable i with i 1 dim variable e Coordinates coord variable i with i 1 dim variable are assigned to The dimensionality is the number of dimensions an extent is related to each dimension and represents the number of elements in that dimension Extents are always greater than 1 To each dimension a coordinate is assigned to Coordinates have a name and from all
161. arg1 effects_1st arg1 linear effects of all factors for arg1 Tab 8 10 125 effects_tot arg1 total effects of all factors for arg1 Tab 8 10 125 ens arg1 whole run ensemble UNC_MC Tab 8 13 130 exp arg1 exponential function basic Tab 8 4 109 flip char_arg1 arg2 flip arg2 according to char_arg1 advanced Tab 8 8 113 get_data char_arg1 get data from an external file advanced Tab 8 8 113 char_arg2 char_arg3 arg4 get_experiment char_arg1 include an other experiment advanced Tab 8 8 113 char_arg2 char_arg3 arg4 get_table_fct char_arg1 table function with linear interpolation of table advanced Tab 8 8 113 arg2 char_arg1 for position arg2 gsa_vb_run_mask select sub sample to apply to subsequent GSA_VB Tab 8 10 125 char_arg1 UNC_MC operators hgr char_arg1 int_arg2 argument histogram of values aggr mom Tab 8 5 110 real_arg3 real_arg4 arg5 hgr_e char_arg1 int_arg2 run ensemble heuristic probability density UNC_MC Tab 8 13 130 real_arg3 real_arg4 arg5 function hgr_I char_argi char_arg2 dimension related argument histograms of aggr mom Tab 8 7 112 int_arg3 real_arg4 values of arg6 real_arg5 arg6 if char_arg1 arg2 arg3 arg4 general purpose conditional if construct advanced Tab 8 8 113 int arg1 integer truncation value basic Tab 8 4 109 krt_e arg1 run ensemble kurtosis 4 moment UNC_MC Tab 8 13 130 lin_abs char_arg1 arg2 absolute linearity measure loc sens Tab 8 14 1
162. ariable NetCDF Network Common Data Form is an interface for array oriented data access and a library that pro vides an implementation of the interface The NetCDF library also defines a machine independent format for representing scientific data Together the interface library and format support the crea tion access and sharing of scientific data The NetCDF software was developed at the Unidata Program Center in Boulder Colorado NetCDF is freely available SimEnv follows for model and gt experiment post processing output storage the NetCDF Climate and Forecast CF metadata con vention 1 0 http www cgd ucar edu cms eaton cf metadata index html and extends it To dump NetCDF files ncdump is used by SimEnv OpenDxX The Open Data Explorer OpenDX http Awww opendx org is a uniquely full featured open source project and software package for the visualization of scientific engineering and analytical data Its open system design is built on a standard interface environment The data model provides users with great flexibility in creating visualizations OpenDX is based on IBM s Visualization Data Ex plorer aaa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f _ 233 Operand Argument of an gt operator in SimEnv gt experiment post processing An operand can be a model gt variable an experiment gt factor a constant a character string gt a macro and an op era
163. arts of it can be addressed in experiment post processing see below Di mensionality dimensions and coordinate description of this data field is derived from the model output variable description in lt model gt mdf Model output variables are specified in the ASCII model output description file lt model gt madf cf Tab 5 3 on page 38 by their Name Dimensionality Extents Coordinate assignment to each dimension Data type cf Tab 5 4 on page 39 Use the service simenv chk to check variables description in model output description file lt model gt mdf Addressing of model output data fields or parts of it is done in experiment post processing by corre sponding model output variables names For variables with a dimensionality greater than 0 it is possible to address only a part of the whole vari able field by e Specifying for a dimension an index range i by i lt index_value gt lt index_value gt lt index_value gt lt lt index_value gt lt index_value2 gt lt index_value gt if lt index_valuez gt is missing i stands for index addressing e Specifying for a dimension a coordinate range c by c lt coordinate_value gt lt coordinate_valuez gt lt coordinate_value gt lt lt coordinate_value2 gt for strictly increasing coordinate values lt coordinate_value gt 2 lt coordinate_value2z gt for strictly decreasing coordinate values lt coordinate_value gt lt coordinate_value2 gt __if lt coordinate
164. ated by SimEnv that represents the simulation experiment as a whole This shell script is submitted as a cron job to the na ABS 92 yi HN ia I i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 cron daemon for one time execution starting at a time specified during experiment preparation The cron job is removed from the cron job list directly after the start of the corresponding experiment After ex periment preparation the login session can be closed For background performance make sure to have rights to manage cron jobs on the machine the experiment is started from e distributed on a multicore processor machine mcore multi core sub mode For a multi core processor login machine the single runs of the experiment can be distributed across a selected number of cores The experiment can be started at once or at a specified time For the latter a cron job is generated which is removed from the cron job list directly after the start of the corresponding experiment For cron job submission make sure to have rights to manage cron jobs on the machine the experiment is started from As for background sub mode in multi core sub mode the login session can be closed after experiment preparation Experiment performance controlled by the job management system SimEnv enables the parallelization of the experiment in the sense that several single runs can be performed in parallel without influencing ea
165. ation file in the case of absence of the appropriate sub keyword Tab 10 3 Default values for the general configuration file in the case of absence of the appropriate sub keyword Default value For more Keyword Sun keyword information see general descr lt nil gt above message_level info above model out_directory d above out_format NetCDF Chapter 12 out_separation yes above slices no above auto_interface no Section 5 10 structure standard Section 5 11 and above experiment restart_ini no Section 7 4 begin_run 0 Section 7 1 7 5 and above end_run last Section 7 1 7 5 and above include_runs lt nil gt above exclude_runs lt nil gt above email lt nil gt Section 7 1 postproc out_directory J above out_format NetCDF Chapter 12 address_default coordinate Section 8 1 3 and above coord_check strong Section 8 1 5 and above opr_directory d Section 8 5 factors _in_output yes above display _values 0 above visualization yes above rn m 154 z H Es f J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 general general general model model model model model experiment experiment experiment postproc postproc postproc postproc postproc postproc descr descr General configuration file for the examples in the SimEnv User Guide message level info out_directory mod_out out_for
166. ber of values for a dimension from the gt dimensionality of a model gt variable or of an gt operator result in gt experiment post processing Extents are always greater than 1 Model output variables and operator results of dimensionality 0 do not have an extent Expression gt result expression Factor Element of the input set of a gt model Factors are manipulated numerically during an gt experi ment by sampling them Factors can be addressed in gt experiment post processing and they have there a gt dimensionality of 0 Factor adjustment gt adjustment Fortran storage model A rule how to map the elements of a multi dimensional data field to a 1 dimensional vector and vice versa A multi dimensional data field field 1 ext 1 extz 1 Xtaim 1 1 Xtaim Of gt dimensionality dim and gt extents ext ext2 eXtgim eXtgm is mapped in Fortran on a 1 dimensional data field vector 1 ext extz eXtgim 1 Xtuim in the following way ipointer 0 do dim 1 Xtgim dO igim 1 1 Xtgim 1 do i2 1 ext2 do i4 1 ext ipointer ipointer 1 vector ipointer field i4 i2 5 igim 1 dim enddo enddo enddo enddo For a two dimensional matrix this storage model corresponds to a column by column storage of the matrix to the vector starting with the first column and for each column starting with the first row GAMS The General Algebraic Modeling System http Awww gams co
167. called the multiple setting likelinood function case Model set tings in such a case may differ in model calibration or site conditions While the result part of the likeli hood function s is are unique for all settings the data part differ s among the settings Settings always count from 1 Please check Section 6 7 3 below for more information how to set up such an experiment e Sub keywords result and data For the Metropolis Hastings algorithm applied in a BAY_BC experiment the posterior probability is the product of the prior probability and the likelihood function The latter follows a normal distribution where the mean is the average measurement value and the variance is derived form the measurement error check Section 4 7 The keyword data supplies the data part of the likelihood function Specify here the name of a file where the measurement data averages and variances are defined With the keyword re sult the model output part of the likelinood function is supplied A model output variables and or result of any dimensionality has to be specified here Both parts are combined during performance of the experi ment to compute successively an individual likelihood from a data pair with average and variance of the table and its corresponding element from the model output part Correspondence is achieved by a se quential approach The i th individual likelihood is computed form the i th data pair the i th record and the i th element of the result
168. case a forest growth model is applied for one patch and likelihood functions for tree diameter and tree height are used multiple setting likelihood function case a forest growth model is applied for several patches and one or several likelihood functions are used The resulting likelihood function is always the product of the individual likelihood functions The measure ment error expressed as the variance determines the influence of the individual likelihood functions The smaller the measurement error the more influential the individual likelihood function and finally the individual posterior probability Settings for the multiple setting likelihood function case may differ e g in model calibrations or site condi tions Such an experiment design is useful for identifying an overall posterior sample rather than individual setting related samples 4 8 Optimization Simulated Annealing OPT_SA The optimization experiment OPT_SA in SimEnv uses a stochastic strategy to sample X It is an experiment type where the sample is generated during experiment performance and not at experiment preparation The general approach of any optimization method is to find the global minimum of a cost function synonym ob jective function F Z F ST Xx that depends on model s state variables Z and consequently on the experiment factors X X1 Xk minimize F Z X Xk subject to Xj min Xi Ximax fori 1 k Often F represents
169. ce for Python Java and Matlab Models ccccccecceceeeeeeeeeeceeeeeeeeeeceeaeeeeeeeseceaeaeeeeeeeeeeeeea 43 5 5 1 Standard Dot Scripts for Python Java and Matlab Models ecceeeeeeceeeenneeeeeeeeeeeseneeeeeeaeeeeneeeeees 45 5 6 Model Interface for Mathematica Models cccccccceeecceeeeeeeeeeneeeeeeeeeeseeeaeaeeeeeeeeeceeeaeeeeeeeseeeueaeeeeeeeeeeeeea 45 5 7 Model Interface for GAMS Models 4 2 cccissc caceeceeccesoesnen ia arae aar riar aeriana Nai 46 5 7 1 Standard Dot Scripts for GAMS Models 00 0 ce eeseeeeeeeceeeeeeeeeceeaeeeeeeeeeeeeaeeeeeeaaeeeseeeeeeeseaeeeeeenaeeeseeaeees 47 5 7 2 GAMS Description File lt model gt gdf lt model gt edf lt model gt Mdf oo eecceeeeneeeeeeeeeeeseeeeeeenaeeeeeeeaeees 48 5 7 3 Files Created during GAMS Model Performance eeccceeseeeeeeeeeeee settee seeaeeeenneeeeeeaeeeseeaeeeenneeeenees 52 5 8 Model Interface at Shell Script Level sriid ae ceeddugnresesbaceesdeeedevaneeeeete 53 5 9 Model Interface for ASCII Files c ccccceccceceecneceeeeeseceaeaeeeeeeeeeceaeaeeeeeeeseceaeaeceeeeesececeaeeeeeeeseseeaeeeeeeeeeeeeea 55 5 10 Semi Automated Model Interface ccccceceeeccececeeeeeeeeeaeeeeeeeeeeceeeeaaeeeeeeesesaaeaeeeeeseseeceaeeeeeeseenaeaeeeeeees 57 5 11 Supported Model Str ctUresS 5 scbiccadicesccnenetaccecswescchapeacceusieds coaasets ceguseeeaeas ches eunceteysgcdeentetacceeanuaeseuacentants tace8 60 5 12 Using Interfaced Models outside SimEnv
170. ch other This opens an approach for a computer network or a compute clus ter of connected machines e to distribute the single runs of an experiment across the network on the cluster e to perform the single runs there and e to collect after the end of a single model run its model output data and related information SimEnv supports distribution of single runs from an experiment for compute cluster architectures Currently IBM s Job management system load leveler LoadL and the parallel operating environment POE are sup ported by SimEnv The processors of a compute cluster are assigned to job classes where jobs can be sub mitted to Two different distribution strategies are offered by the simulation environment Perform the single runs of an experiment e onall the available processor cores of a job class dis distributed sub mode The single runs are submitted to the job class as single jobs in a way that all available processor cores of the class can be used Due to controlling the submit process dynamically by SimEnv the job class will not be overloaded by the single run jobs of the experiment Instead the submit process will wait if nec essary The submit process itself is started in the background The experiment performance will start with the first submitted single run when a processor core of the selected job class is free Use this sub mode for best utilization of all job class processor cores e on pre allocated pr
171. cript before running each GAMS model single run new Section 6 1 1 65 Experiment description file lt model gt edf for experiment types with probabilistic random sampling GSA_EE GSA_VB UNC_MC and BAY_BC e New sub keywords sample_exclude and sample_include for defining intervals to use for probabilistic factor sampling GSA_VB UNC_MC and BAY_BC e New probabilistic random sampling method quasi based on Sobol low discrepancy sequences e Sampling method random renamed to pseudo sampling method Latin hypercube renamed to stratified e New sub keyword seed with values fixed random to initialize the random number generator also for experiment type OPT_SA new Section 10 1 151 Post processor General configuration file lt mode gt cfg New sub keyword display_values for displaying additionally the first values of each result during experiment post processing new Section 8 3 4 113 Post processor New advanced operators distr_par mask_file unmask_file and usage pn Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji 9 Type Check see on Description page update Section 8 4 4 126 Post processor Experiment type DFD formerly behaviour Experiment specific operator behav renamed to dfd new Tab 8 13 130 Post processor
172. ct operator can also be applied to force a certain experiment factor to be used as a coordinate in the result of the operator dfd if this factor is combined in parallel with other factors By default the first factor of a parallel factor sub space as declared in the normalized see Section 6 4 1 comb line of the experiment description file is used in the dfd result Aggregation operators reduce dimensionality of the covered experiment factor space in the dfd result The sequence of aggregation operators in the first argument of the operator dfd influences the result Computation starts with the first aggregation operator and ends with the last avg pl min p2 normally differs from min p2 avg p1 An unused experiment factor in the selection and aggregation filter contributes with an additional dimen sion to arg2 to the result of the operator dfd The extent of this additional dimension corresponds to the number of sampled values of this factor in the experiment description file A factor that is restricted by any of the select operators also contributes with an additional dimension to the result of the operator dfd if the number of selected values is greater than 1 The extent of the addi tional dimension corresponds to the number of selected values of this factor by the select operator Consequently an empty character string arg1 forces to output the operand arg2 over the whole factor space of the experiment The name of the coordinate that is a
173. cter argument char_arg3 is an optional argument Unlike for ASCII data files the keyword modify is allowed m aa 116 y HN 1a f J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Having a model output variable definition as in Example 5 1 on page 40 and assuming a data file data asc as data file with 6 values WO 20 3 40 50 60 and a file data def to define data structure and coordinates as general descr structure for data asc assign as second dimension coordinate time already defined in world_ mdf assign 2 coord time assign 2 coord extent ii eis assign as first dimension a new coordinate new coord assign il coord new_coord assign 1 coord extent ROOF ILLO coordinate new _coord values list 100 110 then get _data ascii data asc data def dummy has Dimensionality 2 Coordinates new_coord time Extents 2 3 and the result of this operator is a 2 x 3 matrix 10 30 50 20 40 60 To get same dimensionality coordinates and extents but result values as the original matrix in data asc exchange coordinate numbers in data def 1 by 2 and 2 by 1 and apply transpose 21 get_data ascii data asc data def dummy Ithas Dimensionality 2 Coordinates new_coord time Extents 2 3 and the result of this operator chain is a 2 x 3 matrix 10 20 30 40 50 60 Example 8 4 Experiment post proce
174. ctor values by a simulated annealing method for a cost function derived from Z For model validation system model comparison control design decision making SimEnv makes use of modern IT concepts Model preparation for interfacing it to SimEnv is based on mini mal source code manipulations by implementing interface function calls into Fortran C C Python Java Matlab Mathematica and GAMS model source code for the addressed factors and model output Addition ally interfaces are available at shell script level and for supporting ASCII files In experiment preparation an experiment type is selected and equipped numerically by sampling the factor space Experiment performance supports local remote and parallel distributed hardware architectures to distribute work load of the single runs of the experiment Experiment specific experiment output post processing enables navigation in the complex factor experi ment output space and interactive filtering of experiment output and reference data by application of operator chains SimEnv supplies built in operators and enables specification of user defined and composed opera tors Result evaluation is dominated by application of pre formed visualization modules using the visualization framework SimEnvVis of SimEnv SimEnv model output as well as experiment post processing offer data interfaces for NetCDF IEEE compli ant binary and ASCII format for a more detailed post processing outside Si
175. ctory for user defined operators e The include file simenv_opr_f inc and simenv_opr_c inc from the inc subdirectory of the SimEnv home directory can be used in user defined operators to declare the SimEnv operator interface functions for Fortran and or C C cf also Tab 10 6 e Apply the shell script simenv_opr_ f c cpp Ink lt opr gt rn m 142 y H Es f J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 from the SimEnv library directory SE_HOME lib to compile and link from usr_opr_ lt opr gt f c cpp an executable usr_opr_ lt opr gt that represents the user defined operator lt opr gt Like the main program for the operator also the object SE_HOME bin simenv_opr o is supplied by SimEnv This object file has to be linked with usr_opr_ lt opr gt o and the object library SE_HOME lib libsimenv a e Tab 15 13 lists the additionally used symbols when linking a user defined operator e In Section 15 3 on page 213 implementation of the user defined operator matmul_ f c is described in detail It corresponds to the built in operator matmul Additionally check the user defined operators from Tab 15 6 and apply them during experiment post processing 8 5 2 Undefined Results in User Defined Operators Check always by the SimEnv operator interface function simenv_chk_undef val cf Tab 8 20 whether an argument value val is undefined before it is processed Set a result to be unde
176. d lt xx gt lt yy gt hgr_e 999999 hgr_ with lt xx gt first bin mid lt yy gt bin width bin_no hgr bin numbers equidist_end 1 1 999999 hgr_e hgr_ incr lin_abs increment values dependent on experiment lin_rel description and operator sens_abs arguments sens_rel sym_abs sym_rel index maxprop index number equidist_end 1 1 999999 maxprop_ minprop minprop run ens run numbers equidist_end 1 1 999999 rn m 164 y H Es f Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Built in coordinate name Generated by operator Meaning Definition cf Tab 11 6 sign sens_abs signs of incremental change equidist_end 1 2 1 sens_rel 1 1 e stat_measure stat_full basic statistical measures equidist_end 1 1 10 stat_red 1 deterministic case 2 minimum 3 maximum 4 mean 5 variance positive distance from mean of confidence meas ure 6 1 7 nna 2 8 median 9 quantile of quantile value 1 10 quantile of quantile value 2 factor_sequ morris sequence of factors equidist_end 1 1 999999 lin_abs 1 1 factor in edf file lin_rel 2 2 factor in edf file sens_abs sens_rel sym_abs sym_rel lt factor_name gt _ dfd factor values dependent on experiment description and operator arguments 10 7 Case Sensitivity As stated in Tab 10 12 all names used in SimEnv are case insensitive Internally they are mapped on a lowe
177. d Electronics Engineers http www ieee org standard number 754 for binary storage of numbers in floating point representation Linux Linux is a free gt Unix type operating system http www linux org originally created by Linus Tor valds with the assistance of developers around the world SimEnv runs under any Linux implemen tation for Intel based hardware and compatibles Load Leveler The load leveler is a network job management system from IBM that handles compute re sources It schedules jobs and provides functions for building submitting and processing them LSA Local sensitivity analysis gt Experiment type with an incremental gt sample of gt factors in the neighbourhood of the gt default values of the factors A local sensitivity analysis in SimEnv is al ways performed independently for all factors involved During gt experiment post processing sensi tivity linearity and symmetry measures can be determined Macro An abbreviation for a unique gt result expression to apply during gt experiment post processing Macros can be embedded into result expressions and are plugged into the expression during its evaluation and computation Macros are described in the macro description gt user defined file Mathematica Mathematica http www wolfram com products mathematica introduction html seamlessly integrates a numeric and symbolic computational engine graphics system programming lan guage documentation syste
178. d Example 15 11 remove temporary sub directory run simenv_run_char rmdir run simenv_run_char perform always and as the last SE_HOME bin simenv_ sh dot script SSE_HOM E bin simenv_end_sh Example 15 8 Model interface for Mathematica model shell script lt model gt run m Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 SHIP 205 15 2 10 GAMS Model SimEnv comes with an interfaced GAMS model gams_model gms and all associated files that fully corre spond to the GAMS example model at http www gams com docs gams Tutorial pdf Modifications for SimEnv are marked in bold with Miam t F OF TABLI IEA canning plants markets SEATTLE SAN DIEGO NEW YORK CHICAGO TOPEKA Ss PARAMETERS capacity of plant i in cases SEATTLE 350 SAN DIEGO 600 demand at market j in cases NEW YORK 325 CHICAGO 300 TOPEKA 215 ff 8B Before using parameters here dem_ny and dem_ch as SimEnv experiment factors they have to be declared as GAMS model parameters default values from above insert Sinclude lt model gt _simenv_get inc sSimenv_get inc is generated automatically based on lt model gt edf And assign adjusted factors to model variables PARAMETERS dem_ny 325 0 dem_ch 300 0 include gams_model_simenv_get inc A SEATTLE dem_ny A SA
179. d as the first SE_HOME bin simenv_ sh dot script altern perform SSK WS lt model sh inc for semi autom model interface sh SSE_HOME bin simenv_ini_sh ge t current run number lt simenv_run_char gt and lt simenv_run_int gt SE_HOME bin simenv_get_run_sh get factor names and adjusted values to ASCII file world_as as lt simenv_run_char gt SSE_HOME bin simenv_get_as run the model read world_as as simenv_run_char store world_as use sS transfer ASCII model output files to SimEnv model output model output to ASCII files imenv_put_as_ simple since the ASCII file has 9000 columns E HOM E bin simenv_put_as_ simple atmo bios ascii simenv_run_char lat use sS imenv_put_as since the ASCII files have 1 column E HOM E bin simenv_put_as atmo_g ascii simenv_run_char time E HOM remove ASCII files f world_as as simenv_run_char f atmo_bios ascii simenv_run_char f atmo_g asciiSsimenv_run_char ERD perfo E bin simenv_put_as bios _g ascii simenv_run_char ios_g asciiS simenv_run_char rm always and as the last SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_end_sh Example file world_as run Example 15 11 Model interface for ASCII files model shell script world_as run Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 J fh ALT
180. date is accepted with a probability of MR For a accepted candidate point a single run was performed e reflected for an accepted candidate that was reflected before only for the Metropolis_reflected method For a reflected candidate point a single run was performed The log file lt model gt blog records information how a candidate point was classified according to the above four categories Additionally the likelinood function value the prior probability and the sampled values and not the adjusted values by simenv_get_ of the point are reported to this file For outranged and rejected points the information from the previously accepted point is listed instead from the point itself At the end of the file a statistical summary is attached The sequence of the records in the file relates to the sequence of generated candidate points in the chain The point with the default nominal factor values that correspond to the run number 0 is assumed as an accepted point The number of points records in lt model gt blog is larger than the number of sample points in lt model gt smp as for outranged candidates the model is not performed lt model gt smp is generated during performance of the experiment lt model gt blog is also exploited by the BAY _BC specific post processing operators bay_bc_run_mask and bay_bc_run_weight see Section 8 4 7 For the multiple likelihood function case and the multiple setting likelihood function case another file l
181. der consideration coordinate lt new_ coordinate __ name gt descr lt string gt coordinate axis description unit oO lt string gt coordinate axis unit values lt val_list gt strictly monotonic sequence of coordinate values for syntax see Tab 11 6 To Tab 11 5 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e With the sub keyword values_shift result values can be shifted on the corresponding coordinate by lt values_shift_val gt coordinate values Consequently lt values_shift_val gt coordinate values have to be appended at the end of the coordinate for a positive value of lt values_shift_val gt and or have to be in serted at the begin of the coordinate for a negative value of lt values_shift_val gt Coordinate values that are obsolete because of this shift are removed from the coordinate definition For a coordinate that is defined with equidistant coordinate values the extent of the coordinate is speci fied automatically by simply applying the equidistant rule for this coordinate For a coordinate with non equidistant coordinate values the coordinate values necessary for the coordi nate extension are defined by the sub keyword values_add 172 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 If both position_shift and values_shift
182. dex_range attribute is used only in case a NetCDF variable does not cover the complete range of a coordinate and an additional coordinate was defined and assigned to this NetCDF variable The in dex_range attribute describes that sub space for which the NetCDF variable is defined Range indices count from 1 e The var_representation attribute is introduced to specify what operations are allowed on the data e The grid_shift attribute is actually still a placeholder for variables that are not defined in the centre of a grid box when quasi regular grids are used e The north_pole attribute can be used if rotated grids are applied 12 2 IEEE Compliant Binary Model Output IEEE compliant binary model output is written in records of fixed length to lt model gt out lt simenv_run_char gt ieee and or lt model gt outall ieee For the determination of the record length see below Sequence of data for each single run is as follows e Experiment factors as specified in lt model gt edf Sequence as in lt model gt edf e Built in pre defined model output variables Sequence as in Tab 10 9 e Model output variables Sequence as in lt model gt mdf Having a model output description file as in Example 5 1 and an experiment description file DFD_a as in Example 6 5 each single run is stored in the following way Factor Extents Data type Storage demand Storage demand model variable Byte re adjusted Byte pl 1 float 4 8 p2 1 float 4 8
183. dify and the corresponding sub keywords are not allowed For syntax of coordinate transformation files check Section 11 2 For restrictions in the path to the directory of the character arguments char_arg1 check Tab 11 3 The operator run selects a single run from the run ensemble The operator run must not contain ex periment specific multi run operators as operands since these operators may refer to the operator run Additionally run must not contain itself as an argument m ETH 120 X HN e f J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 The character argument char_arg1 can hold the run number string explicitly An explicit run number string in character argument char_arg1 is allowed for all experiment types Additionally for DFD and LSA a run number unequal 0 can be selected implicitly by applying a filter of the corresponding opera tors cf Sections 8 4 3 and 8 4 5 as char_arg1 of the operator run The file lt model gt smp holds the sampled factor values to be adjusted by the default nominal values for the current experiment Run number n corresponds to record number n 1 of this file Single run number 0 corresponds to the default single run 0 For more information on lt model gt smp check Section 6 1 on page 63 For examples see Example 8 10 and Example 8 11 The operator run_info returns for the character argument run_nr the run number of the current single run
184. dimens extents iext formal coordinate number ico nr and formal coordinate begin position ico beg pos a idimensl simenv get dim arg c 1 iext1 idimens2 simenv get dim arg c 2 iext2 TOk oimmeny Ger CO arg Cl ieg nri 100 e0 POSI CO nemel y TOk elmenyv Ger CO arg C2 10 nr 100 9S0 DOSZ CO Mem y ichk_modus simenv_get_co_chk_ modus_c if idimens1 2 idimens2 2 ierror 1 wrong dimensionalities else if iext1 1 iext2 0 ierror 2 wrong dimensions else alae CO nri ij 1c0 nro ir CO beg jos 1 alee beg jeesZ O iret 31 else iret 33 coordinates identical else i sliie3 2 differing coordinates if ichk_modus 1 kor Gj Op ext Pasa 7s oly tor weak Co Chock get coordinate values iretvl simenv get co val c ico nrili ieo beg posili venlie y iretv2 simenv get co val c 1co_nr2 0 ico_beg_ pos2 0 j amp value2 jiret 33 differing coordinate values if valuel value2 iret 33 a r 93 214 w HN S iy Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 lerror 0 if ichk_modus 2 if iret gt 31 ierror 3 else if ichk_modus 1 Iie aS SD aleueweoie 3 9 if lerror 0 iextl 1 iext2 1 100 mer see ise LL 2 t00 e0 mPOA Pa icon begmpos7 Pale MOS SHMeOn Ves Micm Ss SUC tape Sw ei O sie Ceimemoie sik xedly kG Omnia
185. dinates lat lon level time Extents 45 90 4 20 2 C 111820 addresses all values of last 10 decades Dimensionality 4 Coordinates lat lon level time Extents 45 90 4 10 y pel el addresses all values of the first decade for level 1 Dimensionality 2 Coordinates lat lon Extents 45 90 c p lp i20 addresses all values of level 1for the last decade at equator Dimensionality 1 Coordinates lon Extents 90 1 23 1 1 20 addresses all values of level 1for the last decade at equator Dimensionality 1 Coordinates lon Extents 90 C O nC ee 2 0 addresses the value for the last decade at lat lon level time 0 2 1 20 Dimensionality 0 Coordinates without Extents without C O nC Ih 0 e e20 addresses the values for the last decade at lat lon level time 0 2 1 20 and 0 6 1 20 Dimensionality 1 Coordinates lon Extents 2 c 0 c 1 c 1 c 20 error in addressing c 1 for lon does not exist Example file world post_bas Example 8 2 Addressing model output variables in experiment post processing 8 104 Qs AY Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 8 1 4 Operators Operators transform dimensionality dimensions and coordinates of the their non character operator arguments into unique dimensionality dimensions and coordinates of the operator result cf Section 8 1
186. ding to Tab 5 1 model interface functions are generic The function simenv_slice_ lt Ing gt announces output of a slice of the data of a defined model output variable This is good for models with multi dimensional variables where at least one dimension is omitted in the state variable declaration in the model the source code because the dynamics for this dimension is calculated in place e g time The assigned variable then has a lower dimensionality than the corresponding variable in the model output description file Nevertheless the simenv_slice_ lt Ing gt function ensures that model output over the omitted dimension can be handled in experiment post processing in common Fig 5 1 shows the conceptual scheme for the SimEnv interface for a Fortran model Ap Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y ff ua J ji 33 Tab 5 1 Generic SimEnv interface functions for language lt Ing gt cf Tab 5 2 Function name Description simenv_ini_ lt Ing gt open model coupling interface simenv_get_ lt Ing gt associate a model source code entity parameter initial value boundary value driver with an experiment factor from lt model gt edf and assign the adjusted factor value to the entity simenv_get_run_ lt Ing gt __ get the current single run number of the run ensemble simenv_put_ lt Ing gt associate a model source code entity with a model output variable from
187. ditionally the following files are available from the example directory SE_HOME exa Tab 15 5 Implemented model and operator related user files for the current version For lt opr gt see Tab 15 6 below File Explanation lt model gt f c cpp py ja m model source code cf also example files in Section 15 2 gms lt model gt model executable compiled and linked from lt model gt f c cpp world edf_ GSA_EE experiment description files corresponding to the individual experiment GSA_VB types to be copied to world_ f c cpp py ja m sh edf and or DFD_ a b c dJ world_f_1x1 edf and world_f_05x05 edf LSA UNC_MC BAY_BC OPT_SA world post_ GSA_EE Experiment specific post processor input file complete experiment GSA_VB for the corresponding description files world edf_ lt exp_type gt DFD_c simenv res_ world_ f c cpp py ja m sh LSA new append replace UNC_MC lt world post_ lt exp_type gt BAY_BC OPT_SA world post_ bas adv Experiment type unspecific post processor input file for single run post processing of a selected single run lt simenv_run_int gt simenv res world_ f c cpp py ja m sh new append replace lt simenv_run_int gt lt world post_ bas adv world dat_ DFD_d UNC_MC adv data files used in world edf_ DFD_d UNC_MC and or world post_adv usr_opr_ lt opr gt f c source code for user defined
188. e Replace xxx by the result of the previous operator Dimensionality 1 Coordinates run Extents 500 rank tie min ene sum bios run ensemble of the ranks of the cost function Dimensionality 1 Coordinates run Extents 500 Example file world post_OPT_SA Example 8 14 Experiment post processing operators for OPT_SA 8 5 User Defined and Composed Operators Operator Interface Besides application of built in operators during experiment post processing SimEnv enables construction and application of user defined and composed post processing operators A user defined operator is sup plied by the user in the form of a stand alone executable that is to perform the operator Contrarily a com posed operator can be derived from both built in and user defined operators to generate more complex op erators User defined and composed operators are announced to the simulation environment in a user defined operator description file lt model gt odf by their names and the number of character integer constant real constant and normal arguments This information is used to check user defined and composed opera S JAF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H i f ji 137 tors syntactically during experiment post processing and by the SimEnv service simenv chk Sequence of the operator arguments types follows the same rule as for built in operator cf Section 8
189. e nmb factor lt factor_ sample m 1 distr distr distribution and distribu name gt lt distribution gt tion parameters to derive file lt directory gt a sample of values lt file_name gt lt factor_smp_val gt file file name to import an external sample of val ues lt factor_smp_val gt sample _ c4 1 pseudo quasi sampling strategy method stratified only for sample distr lt distribution gt sample _ 0 1 lt real_val 41 gt lower bounds lt real_val gt and include lt real_val 2 gt upper bounds lt real_vali2 gt of Gases intervals to include for sam lt real_val 1 gt pling according to distribution lt real_valn2 gt lt distribution gt lt real_valj gt lt lt real_vali2 gt sample _ 0 1 lt real_val 41 gt lower bounds lt real_val gt and exclude lt real_valj2 gt upper bounds lt real_vali2 gt of ipso intervals to exclude from sam lt real_valm1 gt pling according to distribution lt real_valm2 gt lt distribution gt lt real_valj gt lt lt real_valj gt rn m 76 y H Es f Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Max keyword Name Ta d oa line Value Explanation nmb specific lt nil gt seed 0 1 random fixed method how to initialize the random number generator runs m 1 lt int_val gt number of runs to be per formed for the experiment function o 20 lt result gt stopping function to use b
190. e 40 and assuming address_default coordinate in world_ cfg then in experiment post processing atmo g 2 atmo g value of result 3 atmo_g Dimensionality 1 Coordinates time Extents 20 sqrt atmo_g square root of atmo_g Dimensionality 1 Coordinates time Extents 20 clip i 23 1 19 20 atmo last two decades for level 1 at equator equivalent with atmo i 23 1 19 20 Dimensionality 2 Coordinates lon time Extents 90 2 atmo get experiment ielaese dir other model T atmo Difference for atmo between the current experiment and another model other _model located in directory other_dir PFE Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji ba f j _ 121 without application of a coordinate transformation file Dimensionality 4 Coordinates lat lon level time Extents according to definition of atmo in other_model get_table fct world dat_adv atmo aie YK pave OC Oa EnO ene eiiomion in 7 7 LSS 20 maxprop atmo Operator table_fct with table world dat_adv applied to each element of atmo Dimensionality 4 Coordinates lat lon level time Extents 45 90 4 20 maximum from atmo and 10 for each element of atmo equivalent with max_n atmo 10 Dimensionality 4 Coordinates lat lon level time Extents 45 90 4 20 global all level mean over the last two decades Dimensional
191. e different names of corresponding factors in the model description file lt model gt edf and in the model source code that are associated by the first argument of the interface function simenv_put_ cf Fig 5 1 When using the semi automated model interface the SimEnv factor names and the corresponding source code variable names have to coincide Automatically generated source code sequences are stored in files lt model gt _ f c sh as inc and lt model gt _py py in the current workspace SE_WS Note the file name exception for Python When using k factors x Xk in the experiment description file lt model gt edf the source code sequences have the following contents for Fortran file lt model gt _f inc simenv_sts simenv_ini_f simenv_sts simenv_get_run_f simenv_run_int simenv_run_char simenv_sts simenv_get_f x1 0 X simenv_sts simenv_get_f XK 0 XK for C C file lt model gt _c inc simenv_sts simenv_ini_c simenv_sts simenv_get_run_c amp simenv_run_int simenv_run_char simenv_sts simenv_get_c x amp Simenv_zero amp x simenv_sts simenv_get_c Xk amp Simenv_zero amp X for Python file lt model gt _py py from simenv import simenv_ini_py simenv_run_int int simenv_get_run_py x float simenv_get_py x 0 x float simenv_get_py Xk 0 a 58 Y HN an J J Multi Run Simulation Environmen
192. e eee ee eeeeeeeeeeneeeeeeeeeeeeaeeeeeeeaeeeeeneeeeeeaeeeseeaeeeenneeeeeaaa 40 Example 5 2 GAMS description Tile lt model gt Qdt scii i cesssess dai Rico hd ae edie each beep eels 50 Example 5 3 GAMS description file for coupled GAMS Models 00 cc eecceeeeeeeeeeeereeeeeeneeeeeeaeeeseeeaeeeeeneeeenenaeeeeeenaees ot Example 5 4 Model output description file for a GAMS model 0 0 ee eeeeee ce eeeeeeeeeeeeeeeeneeeeeeeaeeeseneeeeeeaeeeeeeaeeeenneeeenaa 52 Example 5 5 Addressing factor names and values for the model interface at shell script level c ceeeeeees 54 Example 5 6 ASCII file structure for the ASCII model interface 2 0 eee eeeeeeeeeeeeeeeeneeeeeeeeeeeeneeeeeenaeeeeeenaeeeeeneeeeee 56 Example 5 7 Shell script lt model gt run for a parallel model 0 0 eee eeeeeeeeeeneeeeeeeeeeeeeeeeeeeaaeeeseeeaeeeseaeeeeeenaeeeeeeeaeees 60 Example 6 1 General layout of an experiment description file lt model gt edf eee eeeeeeeeeeteeeceeneeeeenneeeeeenaeeeeeeeeeees 65 Example 6 2 Include exclude for probabilistic sampling in an experiment description file lt model gt edf 68 Example 6 3 Experiment description file lt model gt edf for GSA_EE 0 ee eecceeceeeeeeneee erent eeeeeeeeeeeaeeeeeenaeeeenneeeeneaa 70 Example 6 4 Experiment description file lt model gt edf for GSA_VB ec eeeeseeeeeeeeeeeeeeeeeeeaeeeseneeeeeeaeeeeeenaeeesnneeeeneaa T2 Example 6 5 Experiment description files lt model gt ed
193. e functions for C C is based on a call by reference for the function arguments Tab 8 19 Operator interface functions to get and put structural information Function Function iia Inputs outputs function value name description f P description unction value Functions to get and put structure information in the declarative and computational part simenv_ get string and integer 4 argument number get_char_arg_ string length of a iarg fle character argu input ment character string of the character argument iarg char Declare char with a sufficient length char output integer 4 length of character argument simenv_ get_char_arg_ flc function value simenv_ iarg gt 0 integer 4 argument number 0 for result get_dim_arg_ get dimensionality iarg fic and extents ofan input argument integer 4 extents of argument result iarg iarg 0 iext 9 iext 1 iext simenv_get_dim_arg_ f c iext get dimensionality output and extents of the integer 4 dimensionality of argument result result simenv_ get_dim_arg_ fic function value simenv_ iarg gt 0 integer 4 argument number 0 for result get_len_arg_ get length of an iarg fic argument input iarg 0 integer 4 length of argument result iarg get length of the simenv_ result get_len_arg_f function value simenv_ get number of integer 4 number of arguments get_nr_arg_ arguments of the simenv_
194. e maxi aggr mom Tab 8 5 111 mum is reached the first time med_e arg1 run ensemble median UNC_MC Tab 8 13 130 min arg1 argument minimum of values aggr mom Tab 8 5 110 min_e arg1 run ensemble minimum UNC_MC min_I char_arg1 arg2 dimension related argument minima of values aggr mom Tab 8 7 112 of arg2 min_n arg1 argn minimum per element aggr mom Tab 8 5 111 minprop arg1 index of the element where the minimum is aggr mom Tab 8 5 110 reached the first time minprop_e arg1 run number where the minimum is reached UNC_MC Tab 8 13 130 the first time minprop_I char_arg1 arg2 dimension related argument position 1 n aggr mom Tab 8 7 112 where the minimum is reached the first time of arg2 minprop_n arg1 argn argument position 1 n where the minimum aggr mom Tab 8 5 111 is reached the first time mod arg1 arg2 remainder basic Tab 8 4 109 morris arg1 get global sensitivity measures for arg1 glob sens Tab 8 9 124 move_avg char_arg1 moving average of running length int_arg3 for advanced Tab 8 8 113 char_arg2 int_arg3 arg4 arg4 nint arg1 nearest integer value basic Tab 8 4 109 qnt_e real_arg1 arg2 run ensemble quantile of arg2 UNC_MC Tab 8 13 130 rank char_arg1 arg2 rank of arg2 according to char_arg1 advanced Tab 8 8 113 reg_e arg1 arg2 run ensemble linear regression coefficient to UNC_MC Tab 8 13 130 forecast arg2 from arg1 regrid char_a
195. e stored in SimEnv model output aF m 2 4 E AN 152 y H a f Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Sub Line EES Keyword Name keyword type line Value Explanation nmb display_values o 1 lt int_val gt specify number of values per result that are displayed addi tionally visualization o yes no determine whether to directly visualize an entered result during experiment post processing To Tab 10 2 the following additional rules and explanations apply For the description of line type check Tab 11 4 on page 171 For keyword general sub keyword message_level Message output is controlled by this information Specify info to output errors and warnings and additional information warning to output errors and warnings error to output errors during any SimEnv service During running an experiment the values info and warning imply that the model output is checked on undefined values This may result in a noticeable increase of CPU time con sumption see Section 10 3 For keyword model sub keyword out_separation Specify here whether SimEnv model output data for the whole run ensemble is stored into one file lt model gt outall nc ieee or in single output files lt model gt out lt simenv_run_char gt nc ieee For keyword model sub keyword slices If the model interface function simenv_slice_ are
196. eaeees 172 Syntax rules for value liSts ee ee ceeee cece ee eeee ee eeeeaeeeseeaaaeeesaeeeeesaaeeeeeeeaeeeseeeeeseaeeeeseaaeseneeeeeeenaeeeseeaes 174 NetCDF data Ype Srii eraon ai e ees ee E a Eee eas TE Oa EA AAEE Ea EENE EE REAT Additional global NetCDF attributes ooo eee ee eene cece eater eeeeaeeeeaeeeeeeaaeeeseeeaeeeseeeeeeesaeeeeesnaeeeeeenaeess 178 Variable NetCDF attributes s icini e aerae araa a a E NE TEE EA AERE REEE A ESE 178 Variable NetCDF attributes for visualization 2 0 0 2 ccccecceceeeeeeeeeee cece ee eeeeeeaeae tees ee seeeaeaeeeeeeesecensaeeeeeeeeeeeees 179 SimEnv installation directory structure oe ee eee eeeeeeceeeee ee eeeeeeeeeaeeeeeeaaeeeseneeeeeeaeeeeeeaeeesneeeeensaeeeeeeaaes 189 System requirements for running SIMENV c2 c ccceeccee cess ceeedeeeceeescoeeeeedeeeedesdeneesendeseeseeteesadendeesscendenseees Current SimEnv technical limitations 0 eee ee eeeeeeeeeeeeeeeneeeeeeeees Implemented example models for the current version 192 Implemented model and operator related user files for the Current VerSiON 0000csseeeeseeeeeseseeeeeeees 193 Available user defined operators c c c cccsteceecaseteeeceseteesdaustdesdeceedesdadeedasdecstsesdeddadedeededvadesdagensaedetecdedendeedae 194 Factors or the generice model Won issiria a aaa aa aE Ea aAA aaaea Ea aaia 195 Experiment post processor built in operators in thematic Order ssssssssssssssssirensnessrrnrnnnsssersnrnrsnssrnne 21
197. ecified in the experiment description gt user defined file and for gt the model interface at the language level also in the model code DFD Deterministic Factorial Design gt Experiment type to inspect behaviour of a gt model in a space spanned up by gt factors The factor space is scanned in a deterministic manner applying deter ministically gt sampled values of the factors with a flexible scanning strategy for factor sub spaces Dimension gt dimensionality Dimensionality dim The number of dimensions of a model gt variable or of an gt operator result in gt ex periment post processing In the model output description gt user defined file each variable a di mensionality is assigned to that corresponds to the dimensionality of the related model output field in the model source code Dimensionality 0 corresponds to a scalar dimensionality 1 to a vector dimensionality 2 to a matrix Dot script A sequence of gt Unix gt Linux operating system commands stored in an gt ASCII file The sequence of operating system commands is directly interpreted and executed by the gt shell Con trary to gt shell scripts a child shell is not spawned A dot script is preceded by a dot and a space when calling it All SimEnv scripts but those marked with in Tab 10 5 at page 157 that can be used in SimEnv within lt model gt ini run end are dot scripts Environment variable At gt Unix gt Linux operating system
198. eeaeeeeeeeeecaeaeeeeeeeseeeeeceeaeeeeeeeseea 146 8 7 Wildcard Operands amp V amp and Si8ticis sccesiesteesicetetectevs cheagucc ateraia eea peida aaa aaa EEE Eain a EEEa 147 8 8 Undefined RESUNS enicsiirieieiiie esien iea A ER EA EAEE EAE aN REELE 148 8 9 Saving RESUIES sairip ee a a a E OEA ETa ENEE OEE AAT EEEE NAE 148 9 VISUAL EXPERIMENT EVALUATION 0 ee ecceeeeeeeeeenneeeeeeeeeeeeaeeeeeeaaeeeceeeeeesaeeeeeeaaeeeseeeaeeesnaeeeeeeaeeeeeeaeess 149 10 GENERAL CONTROL SERVICES USER FILES AND SETTINGS 0 0 eeeseeeesneeeeeneeeeeeeeeeenaeeeeeeaaes 151 10 1 General Configuration Files simenv_settings txt and lt MOdel gt CfQ eecceeeseeeeeeeeeeeeneeeseeeeeeeenaeeeenenaes 151 10 2 Main and Auxiliary Services eee ceeeeeee cnet cece eaeeeeeeeaeeeeaeeeeeeaaeeeseeeaeeesaeeeeeeaaeeeeeeeeeeesneeeeenaeeeeeenaeens 10 3 Experiment Performance Tuning 157 10 4 Model Interface Scripts Include Files Link Scripts ce eecceeeeeeeeeeeeneeeeeeneeeeeeaaeeeseeeaeeeseaeeeseeaeeeenaeeess 157 10 5 User Defined Files and Shell Scripts Temporary Files ceeeseceeeeseeeeeeeeeeeeeeaeeeseeeeeeseaeeeeeeenaeeeeennaees 159 10 6 B lt Fe i os eraer tener rere tte ernest rere errr errr eres ere erry ey reer mmerrye erence err erence errr ree 163 10 7 CASE SONSIIVILY 22 255 ieee a ee a a e eaea aa Eaa e a aE ae E EAOa oS EEEE a Eea oe Eda aia 165 10 8 Numerical Nodata Representation 2 2 c cccescseecesseeeeseesceeedenneeeeseeneesed
199. eecaeaeeeeeeeeeea 97 SimEnv files to store for later experiment POSt PrOCeSSING ee eeeceeceeeteeeeeeeeeeeenaeeeseeeeeeseeeeeeenaeeeeennaeees 99 Classified argument restriction s result description 0 eee eee ee eeeee cece enter eeeeeeeeeaeeeeeeaaeeeeeneeeeeeneeeeeaaes 106 Built in generic standard aggregation Moment Operators eee cece eeeeeeeeeeeneeeseeeeeeeseeeeeeeaeeeeeeaaeees 108 Built in elemental Operators cierno aeea e ee eaaa a a das aaa eaa eaa DEAA ete aa EEE EENE see 108 Built in basic and trigonometric operators ccccceeeceecee cece ee eeeeeeaeeeeeeeseceeaeeeeeeeseeeeeaeeeeeeeeeeseegeaeeeeeeneeea 109 Built in standard aggregation moment operators without SUFFIX 2 eee eee enneeeeeeeeeeeeeneeeeeeaeeeenenaeees 110 Built in standard aggregation moment operators with suffix _N eessssssssriesrriesriisrsiresrriresrinreerresrsenns 111 Built in standard aggregation moment operators with suffix _ sesssessseiesrsiiesrisserirssririresrinresrrnnrsenns 112 Built in advanced Operators isciissec coe ehh raang eee ened a Eaa ur cee Eea a EEA E A Daa a AEE AAAA ERE 113 Experiment specific operators for GSA_EE Lo eeeecccceeeseee cence eeeeaeeeseeeaeeeeaeeeeeeaaeeeseeeaeeeeneeeenenaeeeeeaeees 124 Experiment specific operators for GSA_VB 2 cceceececssecceeeseeccessecceeeeneeceessenseesesneneesneneeesenensesseneenmeneeense 125 Experiment specific operators for DFD ccccccccceeeceecee cece
200. eeneeeenee ee eeeaaeeeceeeaeeeeeaeeeeeeaaeeeseneaeeeseaeeeesenaeeeeeeaeees 2r Trace plots of a MCMC chain for one factor and 100000 run sesssssiesseiiesriiresirssrrirssriiresrinreerinnreresens 29 Part of a sample for OPT_SA generated during the experiment essriesreierriirrsrissrrireeriireeriesreresr 31 Conceptual scheme of the model interface for C C Fortran Python Java and Matlab 0 36 GI EY POS E E E ebeneedbelieelddvaaeds denen dusebedece gens faeces ds teveadacaesdaesaeebee tines on Model output variable definition Grid ASSIQNMENL ee eee ee enee ee eeee ee ee eee ee eeeeaeeeeeeeeeeeaeeeeeeaeeeenneeeeneaa 40 Probabilistic sampling Pseudo and quasi SAMPIing ccccccceecceceeeeeeeeeeeeeeeeeeeseceeeaeeeeeeeseeecesaeaeeeereneeea 67 Probabilistic sampling Latin hypercube sampling 0 00 2 eee ee cnet ee teeeeeeeeeneeeeeeeaeeeeeneeeeesaeeeseenaeeeenneeeenea 68 Flowcharts for performing Simenv run and SIMENV ISt ccccceceeeeeee cece ee eeeeeeaeceeeeeseeeaeaeeeeeeeseseeaeeeeeenenaees 98 SIMENV user shell Scripts ANd Me Sss soiien enoda arai aeda eaae ipinia 163 3 m Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 J els lt X Examples Example 1 1 General example layout in the User Guide eee eee ceeeneeeeeeeeeeeeeaeeeeeeeaeeeeaeeeeesaeeeeeeeaeeeesneeeeseeeseeeaeees 6 Example 5 1 Model output description file lt MOdel gt MdF ee
201. efault alin factor pl sample method stratified factor pl sample distr U 6 6 p1is sampled from a uniform distribution between 6 and 6 In simenv_get_ each value is increased by 1 factor p2 type multiply EAaCOr p2 default 2 factor p2 sample method pseudo ACTOL p2 sample distr N 2 04 p1is sampled from a normal distribution with mean 1 and variance 0 4 In simenv_get_ each sampled value is multiplied by 2 factor pl sample include 1 6 2 4 sample only within the 20 interval factor PS type SGT factor DS default Sio factor p3 sample file world dat_UNC_MC sample for p3 is read from file world dat_UNC_MC specific runs 250 specific function avg atmo _g apply avg atmo_g as stopping function Example file world edf_UNC_MC Example 6 6 Experiment description file lt model gt edf for UNC_MC Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 6 6 Local Sensitivity Analysis LSA The experiment specific information for experiment description files in Tab 6 1 on page 63 is defined for a LSA experiment as follows Tab 6 9 Experiment specific elements of an edf file for LSA Max Keyword Name aub nine line Value Explanation keyword type nmb factor lt factor_ sample f 0 sub keyword is forbidden name gt for this experiment type specific lt nil gt incrs m 1 lt val_list gt increments that form a sample of factor values lt factor_smp_val gt Resulting lt factor_sm
202. el 5 1 General Approach SimEnv model interface has to supply a link between the simulation environment and the model and has to address two aspects For each single run from the run ensemble e All experiment factors as defined in the experiment description file lt model gt edf cf Section 6 1 have to be associated to the corresponding model code entities parameters initial or boundary values drivers These entities are modified numerically in the model by the sampled values and the default nominal values of the factors according to the specified factor adjustment types The process of such a modifica tion is call an adjustment The factor adjustment type specifies how to interfere the current sampled value with the default nominal value of the entity cf Section 6 1 e All model output variables as defined in the model output description file lt model gt mdf cf Section 5 3 have to be associated to the corresponding model entities in general model state variables and these entities have to be output to SimEnv data structures during the performance of the model Implementation of this general approach is based on minimal source code manipulation of the model SimEnv supplies a library with a set of simple functions to interface the model to the simulation environment Generally speaking e Every experiment factor and e Every model output variable demand one additional SimEnv function call in the model source code Accor
203. el gt rUN 0 0 eee eeeeeeeeeneeeeeeeneeeeenneeeenees 205 Example 15 9 Model interface for GAMS models model gamMs_MOdel QMS eececeesseeeeeeeeeeeeteeeteenaeeeenneeeeneas 207 Example 15 10 Model interface at shell script level model shell script World_SH PUN occ eeeeeeeeeeeeeeeeneeeenneeeeneee 208 Example 15 11 Model interface for ASCII files model shell script world_as run 00 eee eee eeeeeeeeeeeeeenteeeeeeneeeeenneeeeeeas 209 Example 15 12 Semi automated model interface at shell script level model shell script world_sh_auto run 210 Example 15 13 Experiment post processor user defined operator module operator MatMUl_f eee eee 213 Example 15 14 Experiment post processor user defined operator module operator matMUl_C eeeeeeeeeees 216 Example 15 15 ASCII compliant experiment post processor result import interface ee eeeeeeeeeeeeeeeeeteeeenteeeeeeee 217 X 2 Bs I j J hyhy oS Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Executive Summary SimEnv is a multi run simulation environment that focuses on evaluation and usage of models with large and multi dimensional output mainly for quality assurance matters and scenario analyses using sam pling techniques Interfacing models to the simulation environment is supported for a numb
204. ent include lt model gt _simenv_get inc has to be placed in the GAMS model source code at such a position where all the GAMS variables are declared Directly before the include statement the factor default nominal values have to be assigned to factor variables that are introduced additionally in the model Directly after the include statement the factor variables with the adjusted factor values have to be assigned to the model variables The GAMS include statement include lt model gt _simenv_put inc has to be placed in the GAMS model source code at such a position where all the variables from the model output description file can be out put by GAMS put statements In the course of experiment preparation the GAMS model and all sub models that are specified in lt model gt gdf see below are transformed automatically Each GAMS model single run from the run en semble is performed in a separate sub directory run lt simenv_run_char gt of the current workspace The sub directories are created automatically Transformed GAMS models and sub models are copied to this sub directory and are performed from there Keep this in mind when specifying in any GAMS model in clude statements with relative or absolute paths In Example 15 9 on page 207 the model gams_model gms is described in detail Note the following information To output the GAMS model status to SimEnv a PARAMETER modstat has to be declared and the statement modstat lt model_name
205. ent can be performed sequentially or in a multi processor hardware environment Besides experiment performance from scratch a restart after an experiment interrupt or only for an experiment slice can be handled by SimEnv 7 1 General Approach SimEnv enables performance of an experiment in different modes on the login machine in foreground or in background and in a job class controlled by the load leveler LoadL and the parallel operating environment POE Experiment performance on the login machine is organized in a way that the single runs of the ex periment are performed sequentially Experiment control by LoadL and POE enables assignment of the simulation load of the single runs of the experiment to a number of processors in distributed parallel or se quential mode Experiments may be performed partially only for a slice out of the run ensemble Experiment slices are con trolled by the general configuration file lt model gt cfg by a range of single run numbers Experiments can be re started for successive performance of experiment slices and or after abnormal ex periment interrupt The experiment log file lt model gt elog is analyzed to identify these single runs out of the run ensemble that have to be performed the first time and or anew and the corresponding model output data is appended to the output data that already exists for this experiment For all experiment settings the user model has to be wrapped in a shell script lt model
206. equidistant If both arguments real_arg2 and real_arg3 are equal zero then min arg4 forms the lower boundary of class number 1 and max arg4 forms the upper boundary of class number int_arg1 For min arg4 max arg4 all result values of the operator classify are undefined For real_arg2 0 or real_arg3 0 real_arg2 and real_arg3 are used as boundaries for the classification and all of those result values are undefined where values of argument arg4 are outside the specified boundary range The operator clip clips an operand arg2 that has dimensionality gt 0 The portion to clip from the oper and arg2 is described by the argument char_arg1 The argument char_arg1 uses syntax for model out put variable addressing cf Section 8 1 3 on page 103 Note that for all dimensions of argument arg2 lower bound index is 1 This applies also to model output variables where the lower bound index is un equal 1 in the model output description file In general extents differ between the result of the operator clip and the argument arg2 Clip reduces the dimensionality of the result with respect to the argument arg2 to clip if the portion to be clipped is limited to one value for at least one dimension A character argument char_arg1 results for operator clip in the identity of argument arg2 The operator cumul cumulates computes partial sums of an operand arg2 that has dimensionality gt 0 Cumulation is performed for all values of the
207. er argument e For lt val_type gt i i e if a factor value range is specified by position indices those factors are selected for self and or those increments are selected for seli that correspond to the specified position indices Position indices are assigned from index 1 to the factors and or increments according to their specifica tion sequence in the corresponding experiment description file lt model gt edf e f more than one factor increment value and or sign was selected by the filter argument arg1 it contrib utes with an additional dimension to the result of the LSA operator e For factors an additional dimension factor_sequ 9 134 SHEL Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 e For increments an additional dimension incr e For signs an additional dimension sign is appended to the dimensions of the argument arg2 to form the result of the LSA operator The extent of this additional dimension corresponds to the defined and or selected number of factors increment val ues and or signs For a definition of the additional dimensions check Tab 10 11 Firstly dimension factor_sequ is appended on demand secondly dimension incr and thirdly dimension sign Having a model output variable definition as in Example 5 1 on page 40 and assuming address_default coordinate in lt model gt cfg Assume the experiment description file LSA from Example 6 7 on page 80 then in result
208. er of model programming lan guages by minimal source code modifications and in general at the shell script level Pre defined experiment types are the backbone of SimEnv applying standardised numerical sampling schemes for model parame ters initial or boundary values or driving forces spaces The resulting multi run experiment can be per formed sequentially or in parallel Interactive experiment post processing makes use of built in operators optionally supplemented by user defined and composed operators Operator chains are applied on experi ment output and reference data to navigate and post process in the combined sample and experiment out put space Resulting post processor output data can be evaluated within SimEnv by advanced visualization techniques Simulation is one of the cornerstones in scientific research The aim of the SimEnv project is to develop a toolbox oriented simulation environment that allows the modeller to handle model related quality assurance matters Saltelli et a 2000 amp 2004 and scenario analyses Both research foci require complex simulation experiments for model inspection validation and control design without changing the model in general SimEnv Flechsig et al 2005 aims at model evaluation by performing simulation runs with a model in a co ordinated manner and running the model several times Co ordination is achieved by pre defined experiment types representing multi run simulations According to
209. er performing moving averages for those dimensions that correspond to digits smaller than the current one If the n th digit of arg1 is O then the moving average for the dimension n of arg4 will not be performed Keep in mind that the sequence of moving averages for single coordinates influences the result of the operator The operator rank transforms all values of the operand arg2 that has dimensionality gt 0 into their ranks Small values get low ranks large values get high ranks The smallest rank is 1 Character argument char_arg1 determines how to rank ties i e values arg 21 and arg22 of arg2 that are identical or have a maximum relative difference of abs arg21 arg22 arg21 lt 10 Example Assume an argument arg2 with 6 values 4 2 4 4 4 8 Then char_arg1 tie_plain returns ranks 2 1 2 2 2 3 four times rank 2 next rank is 3 does not take into account the number of identical values char_arg1 tie_min returns ranks 2 1 2 2 2 6 four times rank 2 next rank is 6 takes into account the number of identical values char_arg1 tie_avg _ returns ranks 3 5 1 3 5 3 5 3 5 6 four times mean rank 3 5 2 3 4 5 4 next rank is 6 takes into account number of identical values The operator regrid can be used to assign new coordinates to argument arg2 Character argument char_arg1 is the name of the coordinate transformation file that holds the information how to transform the coordinates The keyword mo
210. ere Experiment performance Experiment output to NetCDF Problem Check on undefined experiment output results in noticeably additional CPU time consump tion Example Per single run a check of 8 Mill of real 8 values takes additionally 80 sec for single nc file experiment output and additionally 200 sec for common nc file output Workaround Specify in lt model gt cfg for the sub keyword message_level the value error see also Section 10 3 Where Experiment performance Under load leveler LoadL control in distributed sub mode dis and on PIK machine bs08 Limitation Model output is not checked on undefined values on machine bs08 in general and on the Iplex compute cluster under load leveler control in in sub mode dis even when specified by the sub keyword message_level in lt model gt cfg Workaround Perform experiment at login node or under load leveler LoadL control in an other sub mode Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 3 3 Known Bugs and Their Workarounds Tab 3 5 Known bugs and their workarounds in Version 3 01 Where Bug Description Workaround Where Experiment performance Distributed models structure distributed in lt model gt cfg Model output to NetCDF Bug May not store all model output Workaround Specify IEEE model output in lt model gt cfg Where Experiment post processing Operators clip mask mask_file un
211. eriment description file and conse quently the current experiment factors for the Fortran C C Python shell script and ASCII file model inter face For GAMS and Mathematica SimEnv offers such a simple model interface that a semi automated inter face is needless For Java and Matlab there is no semi automated SimEnv model interface as these two languages do not support include files Z EFJ Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji _ 57 These source code sequences can be used e for Fortran C C Python model source codes as include files in the model source code and or e forthe model interface at the shell script level and ASCII level as a dot script in lt model gt run to interface the model and consequently to run the experiment with an up to date part for initialization and factor adjustment For e Fortran C C models The model has to be compiled and linked anew with a new include file This is supported by SimEnv in the course of experiment preparation e Python models and the model interface at shell script level and ASCII level The include file and or dot script can be used directly Generating source code sequences for the semi automated model interface is invoked by the sub keyword auto_interface of the keyword model in the model configuration file lt model gt cfg cf Section 10 1 The Fortan C C Python model interfaces offer to us
212. eriment post processing SimEnv supplies a set of auxiliary services to check status of the model to dump model and post processor output and files and to clean a model from output files General built in settings reflect case sensitivity nodata values and other information related to SimEnv 10 1 General Configuration Files simenv_settings txt and lt model gt cfg SE_HOME bin simenv_settings txt is the general SimEnv settings file It is a case sensitive ASCII file with the structure lt keyword gt lt sep gt lt value gt Tab 10 1 lists the keywords and their values Unless marked by each of the keywords has to be used exactly one time even it is not necessary for the current SimEnv installation Keywords marked by can be multiple specified Tab 10 1 Elements of the file simenv_settings txt Keyword Description SimEnv_admin email address of the SimEnv administra tor logfile_directory directory to store SimEnv log files which services were used SimEnv_home_directory2log SE_HOME directory to store log files from jms_login_node login node for a compute cluster to ac cess the job management system JMS SimEnvVis_server_hostname name of the visualization server that hosts the visualization component SimEnvVis SimEnvVis_server_account account on the visualization server for accessing SimEnvVis SimEnvVis_home_directory SimEnvVis home directory SimEnvVis
213. ero covariances as normally they contradict the requirement in the Metropolis Hastings algorithm that a jump in the factor space from a point p to a point pz has the same probability as from pz to p4 Furthermore SimEnv enables to compute the likelihood function and finally the posterior probability for dif ferent levels of complexity from data files df composed from a number of data points avgy and vary that cor respond to individual elements of model state variables output variables results y Compose the posterior probability with a likelinood function e forthe single likelihood function case from one data file and its corresponding result df with y e forthe multiple likelihood function case from I gt 1 data files each corresponding to its result df withy dfi with y sequence of single likelihood functions e forthe multiple setting likelihood function case S An Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H i f ji 29 from performing each single run for m settings and for each setting from 2 1 setting specific data files each corresponding to its setting independent result df with y4 df with y df4 with V4 gees df with y sequence of multiple likelihood functions Example single likelihood function case a forest growth model is applied for one patch and one likelihood function for the tree diameter is used multiple likelihood function
214. es without Extents without Example file world post_GSA_VB Example 8 9 Experiment post processing operators for GSA_VB 8 4 4 Deterministic Factorial Design DFD There is only one experiment specific operator for DFD experiment post processing With this operator dfd e A single run can be selected from the run ensemble e The complete run ensemble can be addressed e Sub spaces from the factor space can be addressed and e Sub spaces can be projected by aggregation and moment operators dependent on the way the experiment factor space was to be scanned according to the sub keyword comb in the experiment description file To show the power of the operator dfd the simple experiment layouts as described in Fig 4 6 on page 23 are used as examples e With the operator dfd it is possible to address for any operand a single run out of the run ensemble by fixing values of experiment factors p1 and p2 for Fig 4 6 a a value of the parallel factors p1 or p2 for Fig 4 6 b and values of factors p3 and p1 or p2 for Fig 4 6 c Dimensionality and extents of the operator result is the same as that of the operand e Without any selection in the factor space p1 p2 and or p1 p2 p3 the dimensionality of the operator result is formed from the dimensionality of the operand enlarged by the dimensionality of the factor space Two additional dimensions are appended to the operand for Fig 4 6 a one additional dimen sion for F
215. esponding information for the sub keyword descr in lt model gt mdf for a model output variable as an operand of this operator and or from lt model gt edf for an experiment factor as an operand of this operator The only operator used in this expression must not transform the contents of the operand in general must be invariant with respect to description and unit For all other cases lt result_description gt is set to the string res_ lt xy gt and lt result_unit gt is undefined aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f i _ 101 Having a model output variable definition as in Example 5 1 on page 40 then in experiment post processing abs atmo 3 applies operator abs to atmo and adds 3 multi operator result expression lt result_description gt res_ lt xy gt lt result_unit gt undefined Energy MWh abs atmo 3 as above but lt result_description gt Energy lt result_unit gt MWh Energy MWh as above abs atmo 3 MWh abs atmo 3 as above but lt result_description gt res_ lt xy gt lt result_unit gt MWh sign atmo applies operator sign to atmo operator sign is not invariant w r t the contents of its operand lt result_description gt res lt xy gt lt result_unit gt undefined abs atmo applies operator abs to atmo operator abs is invariant w r t the contents
216. experiment factors by operators and e The operator combines sampled values of different factors and so their resulting adjusted values combinatorially the Cartesian product of the sampled values of all factors For example compare with the experiment description file DFD_a from Example 6 5 below e The operator combines sampled values of different factors and so their resulting adjusted values in parallel on the diagonal in the space spanned up from all factors For the operator the factors must have the same number of sampled values For example compare with the experiment description file DFD_b from Example 6 5 below e The operators and can be multiple used in lt combination gt The operator has a higher priority than the operator Parentheses are not allowed For example x X2 X3 X4 always combines factors x2 and x in parallel and this combinatorially with factors x and x4 A parallel combination of x X2 with x3 X4 by X1 X2 X3 X4 is not possible For example compare with the experiment description file DFD_c from Example 6 5 below e In lt combination gt each factor has to be used exactly once By the default combination default all experiment factors are combined combinatorially in the sequence of their declaration in the experiment description file e For example comb default of the experiment description file DFD_a from Example 6 5 below
217. experiment is determined in the following manner loop over the number of runs per factor as specified by the sub keyword runs in lt model gt edf sample point from S re sample point from R loop over resulting sample RS for factor i i 1 K resulting sample point from RS endloop endloop S SAL Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H ba f j 71 For S R and RS check Section 4 3 6 3 2 Example general descr Experiment description for the examples general descr in the SimEnv User Guide general type GSA_VB factor pl type set factor pl default Ty aCe Os pi sample_method pseudo TECTO pl sample dissi i w i2 2 factor p2 type set factor p2 default 2 factor p2 sample method stratified factor p2 sample cirst Or TACTCOR p2 sample include 0 inf factor p3 type Ser LECTOR p3 default So ACOs jos sample method pseudo IPEICICONE jos sample ciste W 12 12 factor p4 type set BACOOR p4 default ar EGCTOL p4 sample method stratified factor p4 sample distr N 4 0 4 PACE Ons p4 sample include 0 inf specific runs 250 in total 250 4 2 1 runs Example file world edf_GSA_VB Example 6 4 Experiment description file lt model gt edf for GSA_VB Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 6 4 Deterministic Factorial Design DFD The experiment specific information for experiment desc
218. eyword type line Value Explanation nmb general lt nil gt descr 0 any lt string gt general macro descriptions macro lt macro_ descr 0 1 lt string gt macro description name gt unit m 1 lt string gt unit of the value of the macro define m 21 lt string gt macro definition string macro definition can be ar ranged at a series of define lines in analogy to the rules for result expressions cf Section 8 1 1 To Tab 8 22 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e Values for sub keywords descr and unit are not evaluated during parsing a result expression general descr Macro definitions for the general descr examples in the SimEnv User Guide macro equ _100yrs descr 2 century tropical level 1 average macro equ 100yrs Umie without macro equ _100yrs define avigi aiemon e 2 0 OF p C LEZO IMEYEIES IESE descr test macro Ma CraO mes e define ilar 2sr3 A macro ESE define 4 Example files world_ f c cpp py ja m sh mac Example 8 17 User defined macro definition file lt model gt mac 8 7 Wildcard Operands amp v amp and amp f amp In SimEnv wildcard operands offer a convenient approach to compute a result expression successively for all defined model output variables and experiment factors Wildcard operands are used in the same manner as normal operands when defining a
219. f c 2 differing extents simenv_check_ function value 3 differing coordinates according to the sub user_def_ keyword coord_check in lt model gt cfg operator 4 iarg1 iarg2 simenv_ put integer 4 potential in place indicator for result put_struct_res_ potential in inplace result can be computed in place with the following fic place storage input non character arguments dimensionality 1 all inplace extents 0 none idimens formal coordi gt 0 e g 135 with arguments 1 3 and 5 nate number integer 4 dimensionality of the result iext formal coordi idimens ico_nr nate value begin input ico_beg_pos number integer 4 only for idimens gt 0 of the result iext 9 extents of the result input iext 1 iext idimens integer 4 only for idimens gt 0 Currently only ico_nr 9 formal coordinate numbers of the result coordinates from input ico_nr 1 ico_nr idimens the arguments can integer 4 only for idimens gt 0 be assigned to the ico_beg_pos 9 formal coordinate begin position for formal coordi result input nate number ico_nr of the result ico_beg_pos 1 ico_beg_pos idimens integer 4 return code Must be applied simenv 0 ok in the declarative put_dim_res_ 0 inconsistency between operands part and only fic there function value All of these operator interface functions return 999 as an error indicator if an argument iarg is invalid Output a
220. f for DFD experiment cece eeeseeeeeereeeeeeneeeeeenaeeeenneeeeneaa 76 Example 6 6 Experiment description file lt model gt edf for UNC_MC ee eececceeeeeeeeeneeeeeeaeeeeeneeeeeeaeeeeeeaeeeenneeeene 78 Example 6 7 Experiment description file lt model gt edf for LSA 0 0 eeccceeeeeeeeeeeeeeeeeneeeeeeaaeeeeeneeeeeeaeeeeeenaeeeenneeeenea 80 Example 6 8 Experiment description file lt model gt edf for BAY BC eeeeseeeeeeeeeeeeneeeeeeaeeeeeneeeeeeaeeeeeeaeeeenneeeene 85 Example 6 9 Bayesian calibration description file lt model gt bdf for BAY_BC ooo eee eeeneeeeeeeeeeeeneeeeeenaeeeenneeeeneaa 85 Example 6 10 lt model gt r n for BAY BC ii scecociesazcctacah nccatceesecssinegecacendpesdscnnnen tine teadnets acdhcoesdeaanscteauefecatesepessuane reecenert steeds 86 Example 6 11 Data files for the likelihood function of a BAY_BC experiment eee eee eeneee eee eeeeeeeeeeeeaeeeenneeeeeeaa 86 Example 6 12 Experiment description file lt model gt edf for OPT_SA Qu eeeceeeeeeceeeenneeeeeeeeeeeeeaeeeeeenaeeeseneeeeeeneeeeeeaaes 88 Example 7 1 Shell script lt model gt run to wrap the user model eee eee ce eeneeeceeeeeeeeeeeeeeeaaeeeeeeeaeeeseaeeeenenaeeeeneaaeees 91 Example 7 2 Shell script lt model gt ini for user model specific experiment preparation ee ee ee eeeeeeeeenteeeeeeeeees 91 Example 7 3 Shell script lt model gt end for user model specific experiment Wrap UP ee eeeeeeeeeteeeeeeeeeeeeneeeeeeeeeees 91
221. factor from this parallel sub space in the normal ized see Section 6 4 1 comb line is used in the result For experiments that use a sample file lt model gt edf specific comb file instead of explicit sample definitions lt model edf gt specific comb default lt combination gt all experiment factors are assumed to be combined in parallel Additionally this experiment type allows to post process the whole run ensemble as an UNC_MC ex periment Keep in mind that generally the factors do not follow a pre defined distribution Having a model output variable definition as in Example 5 1 on page 40 and assuming address_default coordinate in world_ cfg Assume the experiment layout in Fig 4 6 c on page 23 and the corresponding experiment description file from Example 6 5 DFD_c on page 75 then in result processing m ETH 128 y HN 1a f J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 dfd Chre dfd Ghre CEEL N chren drd dfd dfd A oios pn a20 last time step of bios dependent on p2 p1 and p3 Dimensionality 4 Coordinates lat lon p2 p3 Extents 36 90 4 3 SSL jaz oros a ay ZO last time step of bios dependent on p1 p2 and p3 Dimensionality 4 Coordinates lat lon p2 p3 Extents 36 90 4 3 sel aoz 4 Sel toS aL 7 hemi C2 pk select the single run out of the run ensemble for leve
222. factor pl sample distr U 12 12 use factor values 9 3 3 9 EGO CONE p2 type set PEO OIE p2 default 2 factor p2 sample cise WL L0 use factor values 2 25 4 75 7 25 8 75 factor PS type Sew factor PS default SE BICER PO sample cisti V 12 L2 factor p4 type set factor p4 default 4 factor p4 sample disti Ui il 10 specific levels 4 use quantiles 125 375 625 875 specific trajectories 10 Example file world edf_ GSA_EE Example 6 3 Experiment description file lt model gt edf for GSA_EE 70 y H a i ji Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 6 3 Global Sensitivity Analysis Variance Based Method GSA_VB The experiment specific information for experiment description files in Tab 6 1 on page 63 is defined for GSA_VB experiments as follows Tab 6 6 Experiment specific elements of an edf file for GSA_VB z Max Keyword Name Taea d Bae line Value Explanation nmb factor lt factor_ sample m 1 distr distr distribution and distribu name gt lt distribution gt tion parameters to derive file lt directory gt a sample of values lt file_name gt lt factor_smp_val gt file file name to import an external sample of val ues lt factor_smp_val gt sample _ c4 1 pseudo quasi sampling strategy method stratified only for sample distr lt distribution gt sample _ 0 1 lt real_val 4 gt lo
223. files before setting up a multi run simulation experiment Often models write output to files with fixed file names and these files must not exist before running the model Such assumptions conflict with running the model in a loop sequentially or in parallel distributed sub mode Pragmatic workarounds for such conditions without changing the model source code are as follows e For sequential experiment performance on the login machine and or on a compute cluster rename in the model wrap shell script lt model gt run after running the model its outputs to run number re lated file names This solves most of the problems since always only one model run is active e For parallel and distributed experiments on the login machine and or on a compute cluster this solution fails since more than one model run is active and output files are opened Here the best choice is to perform each single model run in its own temporary subdirectory of the current workspace e g identified by the number of the single run Keep in mind that input files also have to be copied to this directory Check Example 7 5 for more information For a model my_model with an input file my_model in and an output file my_model out the following contents could be defined for the model wrap shell script my_model run 1 Aoa sh perform always and as the first SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_ini_sh get run number SE_HOME bin simenv
224. fined by the SimEnv operator interface function simenv_put_undef_ f c cf Tab 8 20 Check usr_opr_matmul_ f c f c in Section 15 3 or usr_opr_div f in the example directory SE_HOME exa of SimEnv for more detailed examples If things go so wrong that computation of the whole result expression has to be stopped it is possible to al ternatively e Set all elements of the results to be undefined e Set simenv_compute_user_def_operator 0 otherwise set it always 0 e In both cases application of the following operators in the operator chain of the result expression will be suppressed and consequently computation of the result expression will be stopped e Check usr_opr_char_test f for a detailed example 8 5 3 Composed Operators A composed operator is an operator chain composed from built in and user defined operators The concept of composed operators enables construction of more complex operators from built in and user defined ones A composed operator is defined with formal arguments that are used in the operator chain as arguments Formal arguments are replaced by current arguments when applying a composed operator during experi ment post processing In this sense the definition of a composed operator in SimEnv corresponds to the definition of a function in a programming language When calling the function formal arguments are replaced by current arguments Consequently composed operators offer the same flexibility as buil
225. g experiment post processing to derive aggregations and moments from operands in different ways by appending suffixes _n _l periment type DFD Tab 8 2 Built in generic standard aggregation moment operators e without suffix to the generic operator name or by incorporating them into the filter argument for experiment specific operator dfd of ex Generic aggregation and moment operator Meaning max maximum of values min minimum of values sum sum of values avg arithmetic mean of values var variance of values avgg geometric mean of values avgh harmonic mean of values avgw weighted mean of values count number of all all defined or all undefined values maxprop maximal suffix related property of values minprop minimal suffix related property of values hgr histogram heuristic probability density function of values For more information check Sections 8 3 3 8 3 Built In Elemental Basic and Advanced Operators 8 3 1 Elemental Operators Tab 8 3 Built in elemental operators Argument restriction s Argument Name Meaning result description value Precedence Tab 8 1 page restriction 106 left parenthesis first right parenthesis first arg1 arg2 exponentiation 2 arg1 gt 0 second arg1 arg2 multiplication 2 third arg1 arg2 division 2 arg2 0 third arg1 arg2 addition dyadic 2 fourth ar
226. g1 arg2 subtraction dyadic 2 fourth arg identity monadic 1 fourth arg1 negation monadic 1 fourth ri m 108 y H Es f Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 e n dimensional matrix algebra of built in elemental operators is performed element by element Example atmo 1 bios atmo i j 1 k bios i j k for all addressed i j k e If an argument value restriction is not fulfilled for an operand element the corresponding element of the operator result is undefined e For examples check Section 8 3 5 8 3 2 Basic and Trigonometric Operators Tab 8 4 Built in basic and trigonometric operators Argument restriction s Argument Name Meaning result description value Example Tab 8 1 page restriction 106 Basic operators abs arg1 absolute value 1 abs 3 3 dim arg1 arg2 positive difference 2 dim 10 5 5 dim 5 10 0 exp arg1 exponential function 1 exp 1 2 7183 int arg1 integer truncation value 1 int 7 6 7 int 7 6 7 log arg1 natural logarithm 1 arg gt 0 log 2 7183 1 log10 arg1 decade logarithm 1 arg gt 0 log10 10 1 mod arg1 arg2 remainder 2 arg2 0 mod 10 4 2 nint arg1 nearest integer value 1 nint 7 6 8 nint 7 6 8 round int_arg1 round arg2 to int_arg1 1 1 lt
227. g3 hgr_I char_arg1 char_arg2 int_arg3 real_arg4 real_arg5 arg6 dimension related argument histograms of values of arg6 max_I char_arg1 arg2 dimension related argument maxima of values of arg2 maxprop_ I char_arg1 arg2 dimension related argument position 1 n where the maximum of arg2 is reached the first time min_I char_arg1 arg2 dimension related argument minima of values of arg2 minprop_I char_arg1 arg2 dimension related argument position 1 n where the minimum of arg2 is reached the first time sum_I char_arg1 arg2 var_I char_arg1 arg2 dimension related argument sums of values of arg2 dimension related argument variances of values of arg2 Multi run operators GSA_EE Tab 8 9 on page 124 morris arg1 get global sensitivity measures for arg1 Multi run operators GSA_VB Tab 8 10 on page 125 effects_1st arg1 linear effects of all factors for arg1 effects_tot arg1 total effects of all factors for arg1 gsa_vb_run_mask char_arg1 select sub sample to apply to subsequent UNC_MC operators Multi run operators DFD Tab 8 11 on page 127 dfd char_arg1 arg2 general purpose operator for navigating and aggregating arg2 in the factor space Multi run operators LSA Tab 8 14 on page 133 lin_abs char_arg1 arg2 absolute linearity measure lin_rel char_arg1 arg2 relative linearity measure sens_abs
228. gin_value end_value 1 lise 3 S FT Sh iil describes the five values 3 5 7 9 and 11 2 equidist_end 3 2 11 is equivalent to 1 3 equidist_end 3 2 11 9 is equivalent to 1 4 equidist_nmb 3 2 5 is equivalent to 1 5 ecmichet ivl gt 5 1 is equivalent to 1 6 file my _values dat is equivalent to 1 with my values dat 3 5 7 oF qwl 7 equidist_end 11 2 3 differs from 1 6 values are identical ordering sequence differs Example 11 3 Examples of value lists SESE Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN a J 175 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 12 Model and Experiment Post Processor Output Data Structures This chapter summarizes information on available data structures for model and experiment post processor output SimEnv supports several output formats from the experiment and the post processor NetCDF is a self describing data format and can be used for model and post processor output Another for mat specifications for both outputs is IEEE compliant binary format and ASCII for post processor output This chapter describes all the used data structures Dependent on the specification of the supported experiment post processor output formats in lt model gt cfg model output can be stored in NetCDF format and post processor output in NetCDF IEEE or ASCII format During experiment perfor
229. gt modelstat has to be incorporated in the GAMS model source code above the include lt model gt _simenv_put inc line The variable modstat has to be stated in the model output description file lt model gt mdf and the GAMS description file lt model gt gdf Set in the file HOME profile the GAMS environment include the path to gams in the PATH environment variable For more information check Section 10 9 5 7 1 Standard Dot Scripts for GAMS Models lt model gt ini lt model gt ini cf Section 7 1 on page 89 is for GAMS models a mandatory shell script and has to have the contents for all GAMS models SE_HOME bin simenv_ini_gams return code from simenv_ini_gams is rc_simenv_ini_gams 0 ok 1 error additional user model specific commands can be implemented up from here if test rc_simenv_ini_gams 0 then fi return always with the return code rc_simenv_ini_gams exit rc_simenv_ini_gams 5 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y ff ua J ji _ 47 For an experiment restart with a GAMS model cf Section 7 4 on page 95 lt model gt ini has to be performed again To force this specify in lt model gt cfg cf Section 10 1 on page 151 for the sub keyword restart_ini the value yes lt model gt run lt model gt run cf Section 7 1 on page 89 has for each GAMS model the same contents bin sh SE_
230. gt run cf also Fig 5 1 Moreover the following conditions are valid when running an experiment For more details check the corre sponding Sections e The model variables to be output during experiment performance are declared in the model output de scription file lt model gt mdf e The type and the factors of the experiment to be performed are declared in the experiment description file lt model gt edf e Mapping between experiment factors and factors in the model source code is achieved by application of the generic SimEnv model interface function simenv_get_ in the model code or at shell script level e Output of model variables declared in lt model gt mdf into SimEnv structures is achieved by the application of the generic SimEnv model interface function simenv_put_ and simenv_slice_ in the model source code e Model output from run number lt simenv_run_int gt is stored in the file lt model gt out lt simenv_run_char gt nc ieee if the value if the out_separation sub keyword in lt model gt cfg is set to yes Otherwise model output from the complete experiment is stored in lt model gt outall nc ieee e For all experiment types a run number O with the default nominal values of all experiment factors will is declared additionally to the runs declared in the experiment description file lt model gt edf e During experiment performance a model interface log file lt model gt mlog is written where the adj
231. gt run with shell script simenv_kill_process 7 3 Experiment Parallelization According to the general SimEnv approach how to design an experiment the single runs of an experiment are independent from each other The only exceptions are the experiment types OPT_SA and BAY_BC where the sample values for the current single run are determined on the outcomes of previous single runs Keeping this in mind SimEnv offers different modes how to disseminate the single runs of an experiment during its performance Experiments can run e locally on the login machine in foreground and background mode and distributed on a multicore processor machine e under control of the load leveler LoadL job management system in parallel distributed and sequential mode For an experiment performance controlled by the job management system or on the login machine in back ground make sure that the environment variable SE_HOME is set correctly in the file HOME profile Local experiment performance on the login machine Two different distribution strategies are offered by the simulation environment for running an experiment on the login machine Perform the single runs of an experiment e sequentially on the login machine foreg foreground sub mode backg background sub mode For an experiment in foreground sub mode the login session must be active during the whole experi ment Choosing experiment performance in the background a temporary shell script is gener
232. gument of the operator Coordinate transformation files follow the same syntax rules as all other user defined files cf Section 10 1 Tab 11 5 Elements of a coordinate transformation file Keyword Name Sub keyword Line type Max line nmb Value Explanation general lt nil gt descr 0 any lt string gt general transformation de scription modify lt original_ coordinate _ name gt rename 0 1 lt new_name gt renames original coordinate position_shift 0 1 lt real_val gt shifts all values of the original coordinate by the specified value lt position_shift_val gt values_shift lt int_val gt shifts the result values on the original coordinate by the specified positions lt values_shift_val gt values_add lt val_list gt defines lt values_shift_val gt values to add to the coordi nate values for syntax see Tab 11 6 assign lt original_ coordinate _ name gt lt coordinate_ nmb gt coord lt co_name gt assign to the dimension with coordinate number lt coordi nate_nmb gt only for operator get_data ascii and or lt original_coordinate_name gt else an already defined co ordinate or a coordinate de fined by the keyword coordi nate coord_extent lt co_val gt lt co_val2 gt assigns start and end coordi nate value to the dimension of the result un
233. h setting from unique result parts and setting specific data parts Overall likelihood function is the product of all individual setting related likelihood functions The Bayesian calibration description file lt model gt bdf for the multiple setting case differs only in the value of the sub keyword method from that for the other two cases However instead of checking and using the tables as specified by the sub keyword data setting specific data files are checked and used They are ex pected with names as declared in the data sub keyword and appended by _s_ lt setting_number gt Setting numbers count from 1 For each setting a single model run is performed To distinguish between the model outputs of the individual settings experiment output is stored for each setting to an individual subdirectory Subdirectories are cre ated in the model output directory as specified in lt model gt cfg Subdirectory names are s_ lt setting_number gt As usual experiment related output files are stored in the current workspace Multi ple setting experiments can not be post processed in a common post processing session Instead modify temporarily the model output directory in lt model gt cfg to a setting subdirectory and post process a single setting experiment output individually In the very artificial case the likelihood functions differ between settings specify in lt model gt bdf all likelihood functions and assign a table
234. he Experiment Post Processor User Defined Operator matmul_ f c 15 3 1 Fortran Implementation Implementation of the user defined operator matmul_f in the file usr_opr_matmul_Tf f integer 4 function simenv_check_user_def_operator ce declare SimEnv interface functions compile with IS SE_HOME inc include simenv_opr f inc c declare fields to hold extents and coordinates dimension iextl1 9 iext2 9 dimen Moni coun s 6D Fee Om mmvre 2 2 dimension ico_beg posl1 9 ico_beg pos2 9 character 20 co_namel 9 co_name2 9 c get dimensionality idimens extents iext c formal coordinate number ico _nr and c formal coordinate begin position ico beg pos idimensl simenv get dim arg f 1 iextl idimens2 simenv get dim arg f 2 iext2 TOk otneny Get CO co like Omnraly eO Sg POSL Co namel iok simenv_get_co_arg_f 2 ico_nr2 ico_ beg pos2 co_name2 c get check modus for coordinates ichk_modus simenv_get_co_chk_modus_f if idimens1l ne 2 or idimens2 ne 2 then c wrong dimensionalities ierror else if iextl1 2 ne iext2 1 then Cc wrong extents ierror 2 else LELEO mri 2 eG ico ar21 tnen c coordinates identical Le eCO beg POEL ceceo Deg PoS2 1 Taen iret 31 else iret 33 endif else c differing coordinates iret 32 if ichk_modus eq 1 then c check only for weak coordinate do j 0 iext1 2 1 c get coordinate values iretvl simenv get co val f
235. he appropriate Sections Specify at least one experiment factor When preparing an experiment an experiment input file lt model gt smp is generated with the sampled values lt factor_smp_val gt according to the information in the sub keyword sample These values are applied within the interface function simenv_get_ to the default nominal values of the factors according to the specified factor adjustment type cf Tab 6 2 below before finally influencing the dynamics of the model The sequence of elements columns of each record of lt model gt smp corresponds to the sequence of factors in the factor name space cf Section 11 1 on page 169 the sequence of records corresponds to the sequence of single model runs of the experiment For each experiment a single model run with run number O lt simenv_run_int gt 0 and lt simenv_run_char gt 000000 is generated automatically as the default nominal run of the model without any factor adjustments This run does not have an assigned record in lt model gt smp Tab 6 2 Factor adjustment types in experiment preparation Factor adjustment type Meaning To derive the final adjusted factor value lt factor_adj_val gt to use in the model from the sampled value lt factor_smp_val gt from lt model gt smp and the factor default nominal value lt factor_def_val gt as defined in lt model gt edf within the SimEnv model interface function simenv_get_ the sampled
236. he normalized lt combination gt lt x gt lt X2 gt lt x gt and lt X gt Xin Xiz Xie Xi j 1 loop over all factor sample values Xnj j 1 fori 1 n n fOr lt X gt PAnR S eeaay 2 1 for lt x4 gt endloop endloop endloop e For comb default Is put down to comb lt combination gt see above y H i j ji S Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 6 4 2 Example Experiment description file DFD_a represents an experiment description according to Fig 4 6 a on page 23 DFD_b and DFD_d according to Fig 4 6 b and DFD_c according to Fig 4 6 c world edf_DFD_a general general general ACE ONe pl AC EONS pl factor pl factor pl ACOs pl factor p2 PICEO p2 factor p2 factor p2 factor p2 specific world edf_DFD_b general general factor pl LECTOR pl factor pl LAC TOT D2 factor p2 factor p2 specific world edf_DFD_c general general factor pi LECTOT pl LAC TOT pii PAC EONS p2 LECTOR p2 factor p2 Pactor p3 ACTON p3 factor p3 descr descr type descr vae type default sample descr unaLe type default sample comb descr type type default sample type default sample comb descr type type default sample type default sample type default sample Results in adjusted factor values Experiment description for the examples in the SimE
237. his is the only approach to allow for addressing the field by one output variable in SimEnv post processing Checking model output on undefined values As specified in the general configuration file lt model gt cfg by general message_level info warning error Not checking model output on undefined values by setting the message level to error is faster than checking it In particular checking NetCDF model output results in a noticeable CPU time consumption Nevertheless checking on undefined values can support model debugging 10 4 Model Interface Scripts Include Files Link Scripts Tab 10 5 lists all these dot scripts and shell scripts that can must be used in lt model gt ini run end J Tab 10 5 Shell scripts and dot scripts that can be used in lt model gt ini run end For built in shell script variables in lt model gt run see Tab 10 10 this is not a dot script but a normal shell script with two arguments See Dot script Use status Used for Section lt model gt ini simenv_ini_gams mandatory experiment init for GAMS models uk simenv_ini_ja mandatory experiment init for Java models 5 5 simenv_ini_m mandatory experiment init for Matlab models 55 simenv_ini_py mandatory experiment init for Python models 5 5 lt model gt run simenv_ini_sh mandatory _ init for any model 5 8 simenv_end_sh mandatory end for any model 5 8 simenv_get_sh optional get
238. ibeg iend 1 j ibeg iend enddo c further processing of coordinate values ers deallocate coord values enddo allocate result _values length_ result ibeg 1 do whil ibeg le length_result iend min0 ibeg 9 length_result ueseicl 2 LOGS 7 dostee losicac reewlt welues 3 ibeg iend 1 j ibeg iend enddo c further processing of result values TE deallocate result values endif enddo close unit 1 close unit 2 return end Example file read_result_file f together with subroutine read_result_file_ieee Example 15 15 ASCII compliant experiment post processor result import interface ra S PAF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Jl Ji io Ni lt 217 15 5 List of Experiment Post Processor Built In Operators and Operator Arguments 15 5 1 Experiment Post Processor Built In Operators in Thematic Order arg general numerical argument int_arg integer constant argument 2 0 real_arg real float constant argument char_arg character argument Tab 15 8 Experiment post processor built in operators in thematic order Name Meaning See Elemental operators Tab 8 3 on page 108 arg1 arg2 addition arg1 arg2 subtraction arg1 arg2 multiplication arg1 arg2 division arg1 arg2 exponentiation arg identity arg1 negation arg parentheses Basic operators Tab 8 4 on page
239. ig 4 6 b and two additional dimensions for Fig 4 6 c For the latter two cases it is important which of the axis p1 and p2 is used for further processing and or output of the operator result The ex tents of the appended dimensions are determined by the number of sampled values Ane S 126 z H Es f J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 As a third option it is possible to select only a sub space out of the factor space to append to the oper and For Fig 4 6 a this could be the sub space formed from the first until the third sampled value of p1 and all adjusted values of p2 between 3 and 7 Dimensionality of the operator result increases by 2 and extents of these additional dimensions are 3 and 2 with respect to the corresponding experiment de scription file DFD_a in Example 6 5 in Section 6 4 2 on page 75 The operator dfd also enables to aggregate operands in the factor space In correspondence with the example in the last bullet point for Fig 4 6 a the operand could be aggregated e g averaged over the first until the third sampled value of p1 autonomously for all runs with different values of p2 and after wards this intermediate result that now depends only on p2 could be summed up for all adjusted values of p2 between 3 and 7 Consequently the result has the same dimensionality as the operand of dfd Se quence of performing aggregations is important
240. iinnriinnsriiteniinneernnnrrrnent 76 6 5 1 StOppINg RUIE ieee aae eaa ag eee a A E E Aa EA E rhe EE TAE EEA Aa A Egi 6 5 2 EA le E P E EE ET AE A A E A E ETE 78 6 6 Local Sensitivity Analysis LSAs sssi au stcccateshes teaceencesvcacgeesadeds ceeeeh gu iateadaurseesndsactondy stages iaiia reoriad 79 6 6 1 Sensitivity Functions RUN Sequence ee c ee eeeeee cence eeeeeeeceeaaeeeteeeeeeesaeeeeeeaaeeeseneeeeeenaeeeesenaeeeeeeeaeees 79 6 6 2 Example iss seas ceed ives seen sea eek eee venue ce Cedi Dee ean dhs EEEE dedi getiieen Neeved trees cient ade 80 6 7 Bayesian Technique Bayesian Calibration BAY _BC 0 eee cence eeeeee erent teense eeeeneeeeeeaeeeeeeaeeeenneeeene 80 6 7 1 Bayesian Calibration Description File lt model gt bdf 0 00 eeeeeeeeeeeee erent ee eeeeeeeeneeeeeeeaeeeseeaeeeenneeeenes 81 6 7 2 Bayesian Calibration log Files lt model gt blog and lt model gt bmlog 0 ccceeeseeeeeeteeeeeeteeeeeeneeeeeeneeeeneas 83 6 7 3 Multiple Setting Likelihood Function Case ooo ee ee ennt eee erte eterna ee ee taeeeseeeaeeeeeaeeeeneaeeeseeaeeeeneeeneas 84 6 7 4 Example Seriene iea ereere a R treme rereerer rere fre rerer A E tert rere rere err err A ESA 85 3 m Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 J PATI S V 6 8 Optimization Simulated Annealing OPT_SA ce eecccceeeceeeeeneeeeeenneeeeeeeeeeenaeeeeeeaeeeseeeaeeesneeesesnaeeeeneeeees 87 6 8 1 Speci
241. ility distribution in terms of integrals A probability distribution assigns to every interval of real numbers a probabil ity Python Python htto Awww python org is a portable interpreted interactive object oriented programming language It incorporates modules exceptions dynamic typing very high level dynamic data types and classes Result In SimEnv gt experiment post processing a result synonym output function is derived from model output of the gt experiment and from reference data A result is specified by a result expression optionally prefixed by a result description and a result unit string Result expression A chain of gt operators from built in or user defined operators applied to model output gt variables and or reference data A result expression is a part of an gt experiment post processing gt result Sample A set of numerical gt factor values created during experiment preparation Shell A shell is the command interpreter for the operating systems gt Unix and gt Linux Shell script A sequence of gt Unix gt Linux operating system commands stored in an gt ASCII file A shell script is interpreted and executed by a gt shell Contrary to gt dot scripts a child shell is spawned when calling a shell script that inherits the gt environment variables of the father calling shell After returning to the father shell it does not transfer the environment variables and other variables of the chi
242. im res 0 only non character argument can be arbitrary all non character non constant arguments with dim res 0 4 1 same dimensionality extents and coordinates 4 some non character non constant arguments dim res 0 4 2 with same non zero dimensionality extents and the 0 dimensional argument is applied coordinates all the other non character to each element of the non zero di non constant arguments with dimensionality 0 mensional argument dimensionality extents and coordinates of the same dimensionality extents and first non character non constant argument arg coordinates as the first non character 5 can be arbitrary all the other following argu non constant argument ments have to have dimensionalities extents dim res dim arg and coordinates of this argument or have to ext res j ext arg j for all j have dimensionality 0 coord res j coord arg j for allj dimensionality extents and coordinates of the dimensionality is higher than that of only non character non constant argument arg the only non character non constant can be arbitrary argument Extents and coordinates of this argument are copied to the result 6 appended dimensions are explained individually dim res gt dim arg ext res j ext arg j for allj coord res j coord arg j for alll j 7 only character arguments constant arguments dim res 0 or without arguments ri m 106 z H Es j J Multi Run Simu
243. imenv_res_char gt 2 character experiment post processor output file number 01 02 99 lt simenv_res_int gt integer post processor output file number 1 2 99 lt simenv_run_char gt 6 character single run number 000000 000001 of an experiment lt simenv_run_int gt integer single run number 0 1 of an experiment lt sep gt sequence of white spaces as item separators in user defined and related files lt string gt any string lt val_list gt list of values in explicit or implicit notation according to Tab 11 6 For post processor operator descriptions only arg general numerical argument operand char_arg character argument operand enclosed in single quotation marks int_arg integer constant argument operand 2 0 real_arg real float constant argument operand Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 1 2 Example Layout All examples in this document but for GAMS refer to a hypothetical global simulation model world It describes dynamics of atmosphere and biosphere at the global scale over 200 years Lateral latitudinal and longitudinal model resolution differs for different model imple mentations temporal resolution is at decadal time steps Additionally atmosphere is struc tured vertically into levels For more information on this generic model check Section 15 2 1 The model world is assumed to map la
244. in grey boxes 1 1 Document Conventions Tab 1 1 Document conventions Character Meani eaning string Ki angle brackets enclose a placeholder for a string braces enclose an optional element lele la square brackets enclose a list of choices separated by a vertical bar er single quotation marks enclose a keyword or sub keyword from user defined files Er double quotation marks enclose the string value of a sub keyword from user defined files lt nil gt stands for the empty string nothing monospace indicates SimEnv example code blue underlined hyperlink in the document Tab 1 2 Main placeholders in this document Placeholder Description lt directory gt path to a directory lt factor_adj_val gt resulting adjusted value of a factor by lt factor_smp_val gt and lt factor_def_val gt lt factor_def_val gt default nominal value of a factor as defined in lt model gt edf lt factor_name gt name of a factor to experiment with as defined in lt model gt edf lt factor_smp_val gt sampled value of a factor from lt model gt smp lt file_ name gt name of a ASCII data file lt int_val gt integer value e g 1234 lt model gt model name to start a SimEnv service with lt real_val gt real float value in integer e g 1234 fixed point e g 1234 or floating point scientific e g 0 1234e 4 notation lt s
245. ing to the specified distribution and its declared distri bution parameters and or are used from the input files Nevertheless each value of the sample is modified according to the factor adjustment type in simenv_get_ So for the factor adjustment type add normally the mean value of the sample will be shifted by the specified factor default nominal value lt factor_def_val gt For the factor adjustment types multiply and relative the specified distribution will be adulterated normally by the factor default nominal value lt factor_def_val gt To Tab 6 3 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e Sub keyword sample e distr lt distribution gt For implicitly specified distributions according to Tab 6 4 sample values lt factor_smp_val gt are gen erated from the distribution with the assigned distribution parameters For lt distribution gt lt distr_shortcut gt lt distr_param_1 gt lt distr_param_2 gt check Tab 6 4 e file lt directory gt lt file_name gt For explicitly specified samples by an ASCII file lt directory gt lt file_name gt the sample values of any distribution are taken directly from this file Each record of the ASCII file can hold only one sample value with an exception for experiment type GSA_VB For GSA_VB two values are expected the first for the sample and second for the re sample For the other sy
246. ion is unique provided that the factors x X are orthogonal A necessary condition for orthogonality of the factors x Xk is that they are uncorrelated With this it holds the following ANOVA HDMR V Z EV DEV D LVin is Viz and it can be shown that Vi V E Z Xi Vy V EZIKX Vit V Vms V E Z Xm s gt 2 Vrea of lower order Vik V E Z X1__ FS Vi ker lower order Dividing the ANOVA HDMR by V Z 1 S 22S D Sm s S42 it holds Si V E Z X V Z 1 order sensitivity index V E Z X X V Z Si S 2 order sensitivity index Si Sms V E Z Xm s V Z z Sm s of lower order S4 V E Z X1 k V Z s ZS iicker ower onder m gt n 20 y H a i i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Sm s indicates by how much V Z would be reduced on average if Xm Xs could be fixed The number of model evaluations model runs necessary to compute the complete set of sensitivity indices is C Nwc Nuc 2 1 where Nme is the Monte Carlo sample size Saltelli defined another sensitivity index the total sensitivity index as St sum of all terms in that include factor X total effect index and showed that it can be computed by Sr 1 V E ZIX V Z E V Z X V Z Sxi is a measure for the total contribution to the output variation due to factor xi The smaller Sz Sx 0
247. ion problem Furthermore avoidance of entrainment in local minima quenching is dependent on the annealing schedule that is the choice of initial temperature how many iterations are performed at each temperature and how much the temperature is decremented at each step as cooling proceeds after Gray et al 1997 Ideally when local optimization methods are trapped in a poor local minimum simulated annealing can climb out The algorithm applied in SimEnv is a very fast simulated re annealing method named Adaptive Simulated Annealing ASA Ingber 2004 Ingber 1989 and Ingber 1996 For the above stated probability p the term kg Temp is chosen as ks Temp Tempo exp c ta where t is the annealing time The ASA schedule is much faster than Boltzmann annealing where kg Temp Tempo In ta and faster than fast Cauchy annealing where kg Temp Tempo ta For the ASA method the cost function F over the bounded factor space X has to be non convex x X212 sub sample of size 31 from a sample in the 2 dimensional factor space X2 X1 X2 o X21 default nominal numerical factor constellation of model M Fig 4 10 Part of a sample for OPT_SA generated during the experiment Aue Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN a J i 31 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 5 M
248. ions as integer 4 int for Fortran and or C C Apply the shell script simenv_mod_ f c cpp Ink lt model_name gt from the SimEnv library directory SE_HOME lib to compile and link an interfaced model User models implemented in C C or Fortran have to be linked with the following libraries to interface them to the simulation environment e SE_HOME lib libsimenv a e libnetcdf a from usr local lib or usr lib Tab 15 12 lists the additionally used symbols when interfacing a Fortran or C C model to SimEnv In e Example 15 1 on page 196 the model world_f f e Example 15 3 on page 199 the model world_c c e Example 15 4 on page 201 the model world_cpp cpp are explained Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 5 5 Model Interface for Python Java and Matlab Models Due to the special features of Python Java and Matlab the model interface components for simenv_get und simenv_get_run differs from that for Fortran and C C in Section 5 4 Additionally the model interface for Python and Java does not support all data types cf Tab 5 4 Tab 5 6 summarizes the model interface modules for a Python and Java models Tab 5 6 Model interface modules methods functions for Python Java and Matlab models addressed as functions factor_def_val in the current single run Function name Function Arguments Argument function value description function value de
249. is equivalent to comb p1 p2 zA Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji 73 e Specification of file in the comb is only allowed if sub keywords sample were not specified for all factors in the edf file All factors are assumed to be combined in parallel The sampled values are read from the sample data file lt directory gt lt file_name gt Each record of the sampled values data file represents one simulation run The sequence of the sam ple sequence of columns in each record corresponds to the sequence of the factors in the factor name space cf Section 11 1 on page 169 Consequently the file has to have per record as much values as factors defined in lt model gt edf All the other syntax rules for ASCII data files from Section 11 3 hold When specifying lt directory gt lt file_name gt strict or lt directory gt lt file_name gt identical sample values for a factor are not allowed to enable after the experiment SimEnv post processing with the experiment specific multi run operator dfd When specifying lt directory gt lt file_name gt nonstrict identical sample values for a factor are al lowed Experiment specific multi run operator dfd can not be applied in post processing Use UNC_MC operator ens instead During experiment post processing restricted capabilities for the operator dfd apply for this experi ment layout For e
250. ity 0 Coordinates without Extents without indices of this element of atmo where the maximum of atmo is reached the first time Dimensionality 1 Coordinates index Extents 4 maa a enewley isk VG np AL ILS 210 pli minimum per grid cell for level 1 without polar regions for the last two decades from atmo and 10 Dimensionality 3 Coordinates lat lon time Extents 36 90 2 mia LANL patno 203 20 Sp 1 20 zonal tropical minima of atmo for the last decade and level 1 Dimensionality 1 Coordinates lat Extents 11 minpropi sO omamno AO i 2A hgr 1 10 zonal tropical indices of those elements of atmo for the last decade and level 1 where the minimum is reached the first time Dimensionality 2 Coordinates lat index Extents 11 2 vora imo per Oop Oo premio 20 20 5 i 20 zonal tropical histograms with 8 bins of atmo for the last decade and level 1 Bin bound extremes are deviated from the values of atmo Dimensionality 2 Coordinates lat bin_no Extents 11 8 Evag IL YLOO mia ATOL atmo ZO S 20 7 temporally averaged all level zonal tropical minima Dimensionality 1 Coordinates lat Extents 11 Example file world post_adv Example 8 6 Experiment post processing with advanced operators Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 8 4 Built In Experiment Specific Operators 8 4
251. iv arg1 division without consideration of simple div 2 4 arg2 overflow underflow and division 0 5 by 0 a m 194 yi HN et Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 2 Examples for Model Interfaces 15 2 1 Example Implementation of the Generic Model world According to Example 1 1 on page 6 dynamics of the model world depend on four model parameters p1 p2 p3 and p4 Tab 15 7 Factors of the generic model world Mapping between model factors and internal model parameters is performed by the model coupling interface functions simenv_get_ Factor Model default Internal model Factor Fact factor nominal parameter name unit pec atc as value p1 1 phi_lat 7 12 latitudinal phase shift p2 2 omega _lat 2 TT latitudinal frequency p3 3 phi_lon 7 12 longitudinal phase shift p4 4 omega_lon 2 11 longitudinal frequency For reasons of simplification these factors parameters influence state variables atmo and bios by the prod uct of two trigonometric terms value_lat and value_lon in the following manner value_lat lat sin 2 n omega lat f lat phi_lat n 12 value_lon lon sin 2 n omega_lon f lon phi_lon n 12 The function f norms value_lat and value_lon by lat and or lon in a way that it holds value_ lat lon 1 sin n omega_ lat lon phi_ lat lon n 12 value _ lat lon last 2 sin 0 omega
252. ization algorithm Consequently only the header of the file lt model gt smp is created during experiment preparation The records belonging to the performed single runs are written during experiment performance e In parallel to the file lt model gt smp an ASCII file lt model gt fct is written during experiment performance with the value of the cost function for each of the single runs e The optimization algorithm itself is controlled by additional technical parameters and options that are normally fixed by SimEnv To modify these settings copy the ASCII file simenv_opt_sa_options txt m S oF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN ua f I 87 from the sub directory bin of the SimEnv home directory to lt model gt _opt_sa_options txt in the current workspace and edit this file During the experiment the edited file is used instead of the file with the de fault constellation in the SimEnv home directory The description of the options and parameters of this file can be found in Ingber 2004 e OPT_SA experiments cannot be restarted by the SimEnv service simenv rst e In the configuration file lt model gt cfg sub keywords begin_run end_run include_runs ex clude_runs are not allowed for an OPT_SA experiment The experiment always starts with run number 0 and ends if one of the criteria in the file lt model gt simenv _opt_sa_options txt see above is
253. k elementary effects dj x z i 1 k one for each factor can be deter mined by two consecutive points x and x i 0 k e Determine randomly r trajectories in this way finally resulting in r elementary effects dj x z for each fac tor Xj e With 0 run ensemble variance of factor values x run ensemble variance of variable z consider the distributions FeS d x Z 0x 0 and compute mean pi di x z r OPET aak Fi d x z 0 o and compute variance of d x z di x z r r 1 fori 1 k e Consider in the u o plane the points u 0 i 1 K a high value of gt with respect to the other p indicates an important overall influence of the factor x on the model state z a high value ofo with respect to the other oj indicates that the factor x is involved in interactions with other factors or indicates that the effect of x on the model state z is non linear Saltelli et al 2004 See also Fig 4 3 Note the following remarks e According to Saltelli et a 2004 and as a rule of thumb e The number of levels p of the grid should by even and should be 4 or 6 e The optimal unique jump width A in the factor quantile space is p 2 p 1 e The number of trajectories r should range around 10 e According to Sin and Gernaey 2009 e The sensitivity measures p and of are non dimensional as they are scaled by o and oz This al lows for applying the Morris
254. l Tab 8 3 108 arg1 negation elemental Tab 8 3 108 arg1 parentheses elemental Tab 8 3 108 abs arg1 absolute value basic Tab 8 4 109 acos arg1 arc cosine trigonom Tab 8 4 109 acot arg1 arc cotangent trigonom Tab 8 4 109 asin arg1 arc sine trigonom Tab 8 4 109 atan arg1 arc tangent trigonom Tab 8 4 109 avg arg1 argument arithmetic mean of values aggr mom Tab 8 5 110 avg_e arg1 run ensemble mean UNC_MC Tab 8 13 130 avg_ char_arg1 arg2 dimension related argument arithmetic means aggr mom Tab 8 7 112 of values of arg2 avgg arg1 argument geometric mean of values aggr mom Tab 8 5 110 avgg_e arg1 run ensemble geometric mean UNC_MC Tab 8 13 130 avgg_l char_arg1 arg2 dimension related argument geometric means aggr mom Tab 8 7 112 of values of arg2 avgh arg1 argument harmonic mean of values aggr mom Tab 8 5 110 avgh_e arg1 run ensemble harmonic mean UNC_MC avgh_I char_arg1 arg2 dimension related argument harmonic means aggr mom Tab 8 7 112 of values of arg2 avgw arg1 arg2 argument weighted mean of values aggr mom Tab 8 5 110 avgw_e arg1 arg2 run ensemble weighted mean UNC_MC Tab 8 13 130 avgw_I char_arg1 arg2 dimension related argument weighted means _ aggr mom Tab 8 7 112 arg3 of values of arg3 classify int_arg1 real_arg2 classification of arg4 into int_arg1 classes advanced Tab 8 8 113 real_arg3 arg4 clip char_arg1 arg2 c
255. l 1 p2 4 and p3 3 3 Dimensionality 3 Coordinates lat lon time Extents 45 90 20 Sel a ozs Sel SGI patno y 7 1 20 last time step of atmo for level 1 depend on p2 p1 and p3 use only runs for p2 1 2 3 and for p3 6 0 8 4 Dimensionality 4 Coordinates lat lon p2 p3 Extents 45 90 3 2 awe a e2 Les Sel a os 2 s ratno g y Lp mean of atmo for level 1 and for runs with p2 1 2 3 for each value of p3 8 4 9 9 Dimensionality 4 Coordinates lat lon time p3 Extents 45 90 20 2 MEEA joy eb TOS e ava Ene E y dk IL S 8 2 determine single minima of avg atmo for level 1 and the last two decades for each value of p2 afterwards determine from that the maximum over all p3 Dimensionality 0 Coordinates without Extents without me FOS mdslian Ge2 7 peavey eucuio 5 Il ILS 204 Y Result differs normally from min p2 max p3 previous result expression count def p3 sel_i p2 1 bios 20 3 determine single numbers of defined values of bios for last decade for runs with p2 1 Result consists of values 0 for water and 1 for land Dimensionality 2 Coordinates lat lon Extents 36 90 parma ggl ZO rta O Ser ah oil I Ser m GOSS y atmo 1 20 deviation of the last time step of atmo for level 1 from the run with p1 1 p2 1 p3 6 dependent on p1 p2 and p3 Dimensionality 4 Coordinates lat lon p1 p3 Extents 45 90
256. l gt lt val gt m use all values from lt factor_name gt lt val gt lt int_val gt for lt factor_val_type gt i lt val gt lt real_val gt else lt aggreg_type gt an aggregation moment operator from Tab 8 5 on page 110 The following restrictions apply aggregations avgw and hgr cannot be used e aggregation count has a differing syntax count_ lt factor_value_type gt all def undef lt factor_name gt lt factor_value_range gt multiple application of minprop and or maxprop causes senseless results an Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H ba f i 127 The following rules hold for the operator dfd Generally by the filter argument arg1 those runs from the run ensemble are selected and or aggregated here interpreted as filtered that are used for the formation of the result Consequently if no filter is specified all runs are used dfd atmo_g The select operator has to be specified only if values are to be restricted by a corresponding factor value range For the aggregation and the select operator the factor value type is redundant if the value range repre sents the full range of values by lt factor_name gt or lt factor_name gt sel pl sel pl1 sel i pl sel _s pl sel _a pl sel i pl sel_s pl sel_a pl and all these select operators are redundant The sele
257. l gt mdf char model_description_file lt directory gt lt model gt mdf char experiment_type experiment type according to Tab 6 1 char experiment_description experiment description according to lt model gt edf char experiment_description_file lt directory gt lt model gt edf char number_of_runs lt number of runs gt int 12 1 2 Variable Labeling and Variable Attributes For NetCDF variables two cases of labeling are distinguished If e during experiment performance for a SimEnv model output variable or e during post processing for a SimEnv result one of its coordinates spans the entire range of definition the already defined coordinate definition is used Otherwise an additional coordinate lt variable_name gt lt coordinate_name gt is defined where the NetCDF variable depends on The additional variable is described in the dimension and data part of the NetCDF file Additionally the SimEnv specific attribute index_range_ lt original_coordinate_name gt see Tab 12 4 is assigned to such a NetCDF variable The following variable attributes are used according to the CF 1 0 standard Tab 12 3 Variable NetCDF attributes Name Value Data type lt variable_name gt standard_name lt coordinate_name gt char lt predef_coordinate_name gt lt predef_var_name gt lt factor_name gt lt variable_name gt lt result_name gt lt variable_name gt long_name lt coordinate_description g
258. l interfaced to SimEnv SimEnv modifications are marked in bold include lt stdio h gt include lt stdlib h gt include lt string h gt declare SimEnv interface functions include simenv_mod_c inc compile with ISS E HOM E inc declare atmo without dimensions level and time and bios without time J because they are computed in place and simeny slice is used Srat lOc atmo 45 90 Sicaicake Lloar bioslsel LLON pratic imt atmo_g 20 statie imt Droe G main void fs woe OL 92799794F int level idecade simenv_sts simenv_run_int levell idecadel idim char simenv_run_char 6 pl 1 7 De 2of pS Bee p4 4 simenv_sts simenv_ini_c check return code of model interface functions at least here if simenv_sts 0 return 1 simenv get run _c only if necessary simenv_sts simenv_get_run_c amp simenv_run_int simenv_run_char simenv_sts simenv_get_c p1 amp p1 amp p1 simenv_sts simenv_get_c p2 amp p2 amp p2 simenv_sts simenv_get_c p3 amp p3 amp p3 simenv_sts simenv_get_c p4 amp p4 amp p4 compute dynamics of atmo and bios over space and time y of atmo g over time all dependent on pl p2 p3 pt for idecade 0 idecade lt 19 idecade ETA for level 0 level lt 3 level idim 3 levell level 1 simenv_sts simenv_slice_c atmo
259. l z te sens_abs z X measure E Z x linearity lin abs z z x ate z x Z x z x lin rel z lin abs z X measure z x symmetry gym_abs ze Z amp 8 z amp x e sym_rel z e sym_abs z e measure e z x Accordingly local measures of the model with respect to a factor are always expressed as a measure of a model s state variable z usually at a selected time step within a surrounding neighbourhood e of a factor value t That is why the conclusions drawn from a LSA experiment are only valid locally at X 7 with respect to the whole factor space X Additionally local measures only describe the influence of one factor x from the whole vector X on the model s dynamics As stated above the sensitivity measures reflect the classical sensitivity functions in a neighbourhood of X 7 The larger the absolute value of the measure the higher is the influence of an incremental change of the factor x on the model output z The linearity measures map the linear behaviour of z nearby X 7 If the linear measure is zero z shows a linear behaviour with respect to x The symmetry measures map the symmetric behaviour of the z nearby X If the symmetry measure is zero z shows a symmetric behaviour with respect to x The larger the absolute values of the latter two measures the higher is the nonlinear non symmetric behaviour of z with respect to x The absolute measures are best suited
260. l_arg 0 001 0 01 0 05 0 1 distr_par 2 int_arg 22 hgr 2 int_arg 0 24 hgr 3 real_arg arg3 arg4 0 hgr 4 real_arg arg3 lt arg4 hgr_e 2 int_arg 0 24 hgr_e 3 real_arg arg3 arg4 0 hgr_e 4 real_arg arg3 lt arg4 hgr_ 3 int_arg 0 24 hgr_ 4 real_arg arg4 arg5 0 hgr_ 5 real_arg arg4 lt arg5 move_avg 3 int_arg 0 23 qnt 1 real_arg 0 lt arg1 lt 100 round 1 int_arg 1 lt arg1 lt 5 stat_full 1 real_arg 0 001 0 01 0 05 0 1 J stat_full 2 real_arg arg1 lt arg2 stat_full 3 real_arg 0 lt arg3 lt arg 4 lt 100 stat_full 4 real_arg stat_red 1 real_arg 0 001 0 01 0 05 0 1 stat_red 2 real_arg arg1 lt arg2 SAAG S 228 y H a J i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 6 Additionally Used Symbols for the Model and Operator Interface Tab 15 12 lists these symbols subroutine function and common block names that are linked in addition to the SimEnv model interface functions in Tab 5 5 from the object libraries SE_HOME lib libsimenv a and usr local lib lionetcdf a to a Fortran and C C user model when interfacing it to SimEnv Additionally the logical unit numbers luns 997 998 and 999 are used Tab 15 12 Additionally used symbols for the model interface Used symbols csimenv_ lt string gt isimenv_ lt string gt jsimenv_ lt string gt lt string gt _nc_ lt string gt nc lt string
261. lation Environment SimEnv User Guide for Version 3 01 July 10 2012 Tab 8 1 lists for all built in operators a classification of argument restrictions and result description that are used in the following for the explanation of built in operators The requirement for a lot of operators to have same coordinates for same dimensions may restrict applica tion of experiment post processing especially for hypothesis checking heavily To enable a broader flexibility with respect to this situation a general solution is provided by SimEnv post processing With the sub keyword coord_check in the general configuration file lt model gt cfg three different modi can be assigned globally to the SimEnv complete post processing session e coord_check strong To ensure for two arguments with same dimensionalities and extents to have same coordinates it is necessary that e Assigned coordinate values for corresponding dimensions are unique e Assigned coordinate names for corresponding dimensions are unique coord_check strong is the default e coord_check weak To ensure for two arguments with same dimensionalities and extents to have same coordinates it is necessary that e Assigned coordinate values for corresponding dimensions are unique e Assigned coordinate names may differ Coordinate description of the appropriate operator result is delivered from its first non character non constant operand e coord_check without To ensure for two arguments wi
262. ld shell to the father shell SimEnv demands the Bourne shell sh SimEnvVis The visualization framework of SimEnv It does not belong to the standard distribution of SimEnv Contact the SimEnv developers to get SimEnvvVis Simulation Performing gt experiments with gt models UNC_MC Uncertainty analysis Monte Carlo method gt Experiment type with pre single run perturba tions of experiment gt factors For each perturbed factor a gt probability density function pdf with function parameters is assigned to During the gt experiment gt adjustments of the factors are re alizations from the pdf s using random number techniques In gt experiment post processing statis tical measures can be derived from experiment output of the run ensemble A prominent statistical measure is the heuristic pdf histogram of a model gt variable and its relation to the pdf s of the factors Unix A computer operating system htto Awww unix org originally developed at AT amp T USL SimEnv runs under the AIX Unix implementation for RS6000 hardware and compatibles from IBM m ERANS 234 y HN 1a f i lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 User defined files A set of gt ASCII files to describe gt model gt experiment gt operator and gt macro specific information and to determine general SimEnv settings All user defined files follow the same syntax rules Variable Element
263. le lt model gt mdf time 10 years 36 1 20 model variable bios lat lon time lat deg gt 90 20 Definition of model output variable bios refers to Example 5 1 above The triples at the edges of the grid are the indices of model output variable bios lat lon time for the appropriate grid cells 36 90 1 lon deg Fig 5 3 Model output variable definition Grid assignment 5 4 Model Interface for Fortran and C C Models Tab 5 5 describes the model interface functions that can be used in user models written in Fortran or C C postfix f for Fortran c for C C e to get sampled values of the experiment factors and to adjust them numerically by the factor default nominal value for the current single run of the run ensemble and e to output model results from the current single run In this table the input and output data types are documented for functions used in Fortran For C C the corresponding data types are valid All functions have a 4 byte integer function value integer 4 and or int Implementation of the functions for C C is based on a call by reference for the function arguments S 40 v HN e J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Tab 5 5 Model interface functions for Fortran and C C models Function name Function description Arguments function value Argument function value description
264. level the so called environment is set up as an array of operating system and user defined environment variables that have the form Name Value The Value of a Name can be addressed by Name In SimEnv use of environment variables in directory strings lt direct gt is allowed aaa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f _ 231 Experiment Performing simulation runs with a gt model in a co ordinated manner by applying gt experi ment types and running the model in a run ensemble i e a series of single simulation runs Experiment post processing The work step of processing model output data from the whole run ensemble after performing a simulation gt experiment SimEnv post processing enables navigation in the gt factor space that is gt sampled by an experiment as well as construction of additional output func tions by declaration and computation of gt results Experiment post processing operator gt operator Experiment factor gt factor Experiment type Pre defined multi run simulation experiment In the process of experiment preparation defining an experiment by describing it in the experiment description gt user defined file gt fac tors are assigned to an experiment type and are gt sampled in an experiment specific manner Currently available experiment types are gt GSA_EE gt DFD gt UNC_MC gt LSA and gt OPT_SA Extent ext The num
265. lice f is used atmo 0 44 0 89 IoaL Os 10 S OORS S atmo_g 0 19 bios g simenv_ini_f c check return code for the model interface functions at least here if simenv_sts ne 0 stop 1 oime nvy get runm i emily ir mecesseicys simenv_get_run_f simenv_run_int simenv_run_char simenv_get_f pl pl1 p1 simenv_get_f p2 p2 p2 simenv_get_f p3 p3 p3 simenv_get_f p4 p4 p4 c compute dynamics of atmo and bios over space and time or Taiemong over ieme alll dependent fon pisip2 02 4 do idecade 0 19 Op 3 simenv_slice_f atmo 3 levelt 1 level 1 simenv_slice f atmo 4 idecade 1 idecade 1 simenv_put_f atmo atmo simenv_sts simenv_slice f bios 3 idecadet 1 idecade 1 simenv_sts simenv_put_f bios bios simenv_put_f atmo_g atmo_g c compute dynamics of bios g simenv_put_f bios_g bios_g simenv_end_f Example file world _f f Example 15 1 Model interface for Fortran models model world_f f Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 2 3 Fortran Model with Semi Automated Model Interface With respect to Example 5 1 the following Fortran code world_f_auto f could be used to describe the semi automated model interface to SimEnv SimEnv modifications are marked in bold program world f auto ce declare SimEnv interface functions compile with IS SE_HOME inc c elmen
266. lip arg2 according to char_arg1 advanced Tab 8 8 113 cnf_e real_arg1 arg2 positive distance of confidence line from run UNC_MC Tab 8 13 ensemble mean avg_e arg2 cor_e arg1 arg2 run ensemble correlation coefficient between UNC_MC Tab 8 13 130 arg1 and arg2 cos arg1 cosine trigonom Tab 8 4 109 cosh arg1 hyperbolic cosine trigonom Tab 8 4 109 cot arg1 cotangent trigonom Tab 8 4 109 coth arg1 hyperbolic cotangent trigonom Tab 8 4 109 ri m 222 y H Es f Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 On Name Meaning Type See page count char_arg1 arg2 count number of values aggr mom Tab 8 5 110 count_e char_arg1 arg2 run ensemble count UNC_MC Tab 8 13 130 count_I char_arg1 dimension related count numbers of values of aggr mom Tab 8 7 112 char_arg2 arg3 arg3 cov_e arg1 arg2 run ensemble covariance between arg1 and UNC_MC Tab 8 13 130 arg2 cumul char_arg1 arg2 cumulates arg2 according to char_arg1 advanced Tab 8 8 113 dfd char_arg1 arg2 general purpose operator for navigating and DFD Tab 8 11 127 aggregating of arg2 in the factor space dim arg1 arg2 positive difference basic Tab 8 4 109 distr char_arg1 int_arg2 get distribution parameter int_arg2 of factor basic Tab 8 4 109 char_
267. lon time Extents 45 90 2 Wee elaro s pl Is 20 rebia OY enemies 7 7 Lp L820 global run ensemble variance of the anomaly of atmo for level 1 and the last two decades Differs normally from the previous result expression Dimensionality 4 Coordinates lat lon time Extents 45 90 4 20 haz eCbin no 00s 0min 1O10 atmo 20 20 1 20 histogram with 25 bins for the zonal tropical minima for level 1 and the last decade Bin bound extremes are derived from the values of the last argument of the operator hgr_e Dimensionality 2 Coordinates lat bin_no Extents 11 25 etar rull 001 0057 25 75 mim 1 10 atmo 208 20 1 20 full basic statistical measures for the zonal tropical minima of atmo for level 1 and the last decade Dimensionality 2 Coordinates lat stat_measure Extents 11 10 Example file world post_UNC_MC Example 8 11 Experiment post processing operators for UNC_MC 8 4 6 Local Sensitivity Analysis LSA Tab 8 14 shows the experiment specific operators for LSA that can be used in post processing For a defini tion of these operators check Tab 4 5 on page 27 Tab 8 14 Experiment specific operators for LSA Argument Argument value Name Meaning restriction s gumon Ses restriction result description sens_abs absolute sensitivity measure for char_arg1 char_arg1 arg2 according to char_arg1 selection arg2 aggregation filter sens_rel relative
268. lt factor_smp_val gt are sampled in this factor range specific lt nil gt seed o 1 random fixed method how to initialize the random number generator function m 21 lt result gt cost function to minimize A 0 dimensional result formed according to the rules of the SimEnv post processor Do not apply multi run operators Result definition can be ar ranged at a series of function lines in analogy to the rules for result expressions cf Section 8 1 1 runs m 1 lt int_val gt number of single runs to end the experiment without check ing the other optimization method related stopping crite ria To Tab 6 12 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e Sub keyword seed This sub keyword controls the seed of the used random number generator for implicitly specified distri butions A random seed will result in different generated samples for repetitive performance of the same experiment while with a fixed seed the generated samples will be identical also across different ma chines without taking into account numerical inconsistencies e g rounding errors If the sub keyword is not stated initial seed is set to random 6 8 1 Special Features in OPT_SA e This is an experiment type where the sample for the factors of the single runs are not determined before the experiment but in the course of the experiment by the optim
269. lt model gt mdf and output the entity to SimEnv data structures simenv_slice_ lt lIng gt enable slicing i e a repetitively partial output of model output variables simenv_end_ lt Ing gt close model coupling interface The alignment of the contents of the SimEnv description files and the used SimEnv model interface functions in the model source code is dominated by the description files These files determine the experiment and the model source code is expected to be well adapted Nevertheless this approach is implemented in a flexible manner e Entry in SimEnv description file missed and corresponding function call in model source code available A function call in the source code where an experiment factor from lt model gt edf and or a model output variable from lt model gt mdf is not associated with is handled during the model performance in such a way that the factor is unadjusted and or the model output variable is not output In particular a factor remains the value it had in the model source code before calling the simenv_get_ function call The factor and or model output variable is not stored in SimEnv experiment output and can not ad dressed in SimEnv experiment post processing This approach enables adaption of the model source code for a number of potential experiment factors and model outputs where only a subset of these factors is under consideration in special experiments and or requested for model o
270. lti run operator multi run operators In fact both operators do not make sense when apply ing outside a multi run operators This is not checked when analysing a result expression Operator bay_bc_run_weight The weight that is assigned to a single run of type accepted or reflected is the number of all subse quent records in the file lt model gt blog of types outrange or rejected until the next entry of type ac cepted or reflected is reached The single run under consideration also contributes with a summand 1 to the weight The resulting weight is multiplied with arg1 Single runs of type rejected get an undefined weight This experiment type allows to post process the whole run ensemble as an UNC_MC experiment Mask rejected runs of the whole run ensemble ens bay bc_run mask arg returns for rejected runs the undefined value otherwise arg run 1 bay_bc_run_mask arg returns for run no 1 the undefined value if it was rejected otherwise arg bay_bc_run_ mask ens arg returns a meaningless result Mask rejected runs and weight runs of type accepted or reflected of the whole run ensemble ens bay bc run weight arg rejected runs get undefined weights accepted and reflected runs get a weigth which is the number of assigned subsequent runs of type outrange or rejected Weight is multiplied with arg sum e bay bc run weight 1 the result returns the chain length
271. lumn line 1 2 90 91 90 20 1 84 178 1 84 174 1 84 178 1 84 178 2 84 178 20 36 56 178 1 56 174 1 56 178 1 56 178 2 56 178 20 SE_HOME bin simenv_put_as_ simple atmo _bios ascii lat atmo and bios are the variable with lat as the first coordinate According to the sequence in world_as mdf the file atmo_bios ascii has to hold in its first columns the variable atmo followed by the variable bios Since bios is defined for the coordinate lat only on the subrange 2 37 of the complete range 1 45 for atmo values with numerical nodata placeholder lt nodata gt e g 0 0 have to be set for all values of bios in file records 1 and 38 to 45 The first record of the file corresponds for atmo with lat 88 for bios lt nodata gt has to be assigned The 45 record corresponds for atmo with lat 88 for bios lt nodata gt has to be assigned There are 90 4 20 90 20 9000 columns that s why simenv_put_as_ simple is used instead of simenv_put_as The file has to hold atmo lat lon level time and bios lat lon time in the following structure shown are the indices atmo bios column line 1 90 4 20 90 4 20 1 9000 1 88 178 1 1 88 178 16 20 lt nodata gt lt nodata gt 2 84 178 1 1 84 178 16 20 _ 84 178 1 84 178 20 37 56 178 1 1 56 178 16 20 _ 56 178 1 56 178 20 38 60 178 1 1 60 178 16 20 _ lt nodata gt lt
272. m and advanced connectivity to other applications Matlab MATLAB http Awww mathworks de products matlab is a high level language for computations and interactive environment for developing algorithms analysis and visualization of data It allows to perform computationally intensive tasks faster than with traditional programming languages Model A model is a deterministic or stochastic algorithm implemented in one or a number of computer programs that transforms a sequence of input values gt factors into a sequence of output values gt variables Normally inputs are parameters driving forces initial values or boundary values to the model outputs are state variables of the model For many cases the model will be state de terministic time and space dependent For SimEnv the model its factors and variables are cou pled in the process of gt interfacing the model to SimEnv Model coupling gt model interface Model interface Interfacing a gt model to SimEnv means coupling it to SimEnv and enabling finally experi menting with the model within SimEnv There are coupling interfaces at programming language level for C C Fortran gt Python Java gt GAMS gt Matlab and gt Mathematica Additionally models can be interfaced at the gt shell script level by using shell script syntax elements For all in terface techniques the interfaced model itself has to be wrapped into a shell script Model output variable gt v
273. m is a high level modeling system for mathematical programming problems It consists of a language compiler and a number of inte grated high performance solvers GAMS is tailored for complex large scale modeling applications and allows to build large maintainable models that can be adapted quickly to new situations GSA_EE Global sensitivity analysis elementary effects method gt Experiment type to determine qualitatively a ranking of the gt factors during gt experiment post processing with respect to the factors sensitivity to a model output Sensitivity is assessed globally i e for the complete feasibil ity range of each factor based on a statistics from local effects on randomly selected trajectories in the factor space GSA_VB Global sensitivity analysis variance based gt Experiment type to determine how the vari ance of model output depends on the variability of the model gt factors and how the output vari ance can be apportioned accordingly E aa 232 y HN 1a J J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Grid Regular topological structure for a model gt variable or an gt operator result in gt experiment post processing spanned up as the Cartesian product of the assigned gt coordinates to the variable or the operator result IEEE SimEnv can use on demand for storage of model and post processor output the Institute of Electri cal an
274. mEnv Original Model Model Experiment f Experiment l gamonia N Experiment Interface Preparation Performance os 7 Evaluation processing 4 S ia I d Model o i V Update Si J Fig 0 1 SimEnv system design E 2 Y H iat fy Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 SimEnv key features e Available for Unix and Linux platforms e Support of key working techniques in experimenting with models SimEnv enables model evaluation uncertainty and scenario analyses in a structured methodologically sound and pre formed manner applying sampling techniques e Run ensembles instead of single model runs Model evaluation by multi run simulation experiments e Availability of pre defined multi run simulation experiment types To perform an experiment only the factors parameters initial values drivers to experiment with and a strategy how to sample the factor space have to be specified e Simple model interface to the simulation environment Model interface functions allow mainly to adjust an experiment factor numerically and to output model results for later experiment post processing Model interfacing and finally communication between the model and SimEnv can be done at the model language level by incorporating interface function calls into model source code C C Fortran Python Java and Matlab include per experime
275. mance model output is written either to single output files lt model gt out lt simenv_run_char gt nc ascii per experiment single run or to a common output file lt model gt outall nc ieee for all single runs from the experiment run ensemble Output to single files or a common file depends on specification of the value for the sub keyword out_separation in lt model gt cfg lt simenv_run_char gt is a six digit placeholder for the corresponding single run number During experiment post processing output and structure of results is written to lt model gt res lt simenv_res_char gt nc ieee ascii and lt model gt res lt simenv_res_char gt ieee ascii lt simenv_res_char gt is a two digit placeholder for the number of the result file It ranges from 01 to 99 For IEEE and ASCII model output and experiment post processor output formats multi dimensional data is organized in the Fortran storage model cf Section 15 7 Glossary Use the SimEnv service command simenv dmp for browsing model and result output files See Tab 10 4 for more information 12 1 NetCDF Model and Experiment Post Processor Output The intention for supplying NetCDF format for model and experiment post processor output is to provide the possibility to generate self describing platform independent data files with metadata that can be interpreted by subsequent visualization techniques The conventions applied for SimEnv represent a compromise be
276. mask_file Bug Do not work with the coordinate range c lt coordinate_value gt lt coordinate_valuez gt Workaround Use index range i lt index_value gt lt index_value2 gt instead aa gt 12 y HN E Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 4 Experiment Types SimEnv supplies a set of pre defined multi run experiment types Each experiment type addresses a special experiment method for performing a simulation model several times in a co ordinated manner In this chapter an overview on the available experiment types is given from the viewpoint of system s theory 4 1 General Approach SimEnv supplies a set of pre defined multi run experiment types where each type addresses a special multi run experiment method for performing a simulation model or any algorithm with an input output transition behaviour In the following the general SimEnv approach will be described for time dynamic simulation models be cause this class forms the majority of SimEnv applications All information can be transformed easily to any other algorithm Based on systems theory each time dynamic model M can be formulated without limitation of generality for the time dependent time discrete and state deterministic case as M Z t ST Z t At Z t k At P IX t Zo B with ST state transition description Z state variables vector P parameter vector IX in
277. mat netcdf out_separation yes auto_interface if structure standard begin run 45 end_run 300 exclude_runs file runs2exclude dat out_directory Ge SOULE out_format netcdf address default index coord check strong opr directory a visualization no Example 10 1 User defined general configuration file lt model gt cfg 10 2 Main and Auxiliary Services The following SimEnv service commands are available from the sub directory bin of the SimEnv home direc tory SE_HOME Besides experiment performance experiment post processing and visualization there are additional auxiliary SimEnv services to check input information consistency to monitor the status of a run ning simulation experiment to dump files of model and experiment post processor output to monitor general SimEnv log files and to wrap up a SimEnv workspace Tab 10 4 SimEnv services 2imEny Use to service Main Services simenv res perform experiment result post processing for run number lt simenv_run_int gt or for lt model gt the whole run ensemble lt simenv_run_int gt 1 default new append Before entering experiment post processing those output files replace lt model gt res lt simenv_res_char gt nc ieee ascii and lt simenv_run_int gt lt model gt inf lt simenv_res_char gt ieee ascii with the highest two digit number lt simenv_res_char gt are identified and new result files for lt res 1 gt are written
278. modified version The so called Metropolis with Reflection algorithm van Oijen 2008 can reduce drastically the number of outranged candidates that are not subject to the Metropolis ratio MR The algorithm tries to reflect back a jump outside the definition domain again within the distribution bounds The chain can be stopped when it has converged i e it has explored the parameter space adequately Visual analysis of convergence can be assisted by trace plots where the value of a sampled factor is plotted versus the run number see Fig 4 9 Nevertheless in SimEnv the chain length has to be specified as a fixed value before the experiment and is not subject to any stopping criterion For more information on MCMC trace plots check for example SAS 2012 factor value factor value T T T T T T T T T T 0 20000 40000 60000 80000 i 20000 40000 60000 s0000 run number run number Fig 4 9 Trace plots of a MCMC chain for one factor and 100000 run left chain does not converge right chain converges As for the experiment type UNC_MC the prior distribution is assumed to be decomposed into marginal distri butions for k all individual factors k pdfa Xk II pafi x i 1 Covariances between the individual factors can be specified to determine the direction of the multivariate normal jump The Metropolis with Reflection algorithm does not allow for inter factor nonz
279. mon assumptions are made that the measurement errors are nor mally distributed uncorrelated and additive Consequently the likelinood function follows a normal distribu tion L N avgg vara The Metropolis ratio MR post_prob candidate point post_prob prev accepted point with the posterior probability post_prob pdf L avga vara is used to decide whether a proposed candidate point in the factor space is accepted or not MR gt 1 if and only if the candidate point has a higher posterior probability than the previously accepted point candidate point is accepted MR lt 1 else candidate point is accepted with probability MR The multivariate normal jump can result in a candidate point that is located outside the domain of definition of the prior distribution pdfp X and consequently has a prior probability of zero This may be the case for distributions with hard coded lower and or upper bounds e g the uniform distribution While for an out ranged candidate point a single simulation run will not be performed such a candidate does not contribute to Do 28 y HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 the inspection of the factor space for a given chain length N but reduces the efficiency of the algorithm in terms of the ratio between outranged candidates and N That s why SimEnv offers beside the standard Me tropolis Hastings algorithm a
280. mulation experiment optional for GAMS models manda 7 6 tory and stan dardized lt model gt lnk model shell script to link an interfaced C C Fortran optional model Used in the course of experiment preparation for experiment run not re start if a semi automated model interface auto_interface no was declared in 510 lt model gt cfg for the appropriate programming lan n guages Can also be used stand alone for non semi automated model interface Is normally based on SE_HOME lib simenv_mod_ f c cpp Ink lt model gt _ user specific job control file to submit a job by the load optional dis par seq _ leveler in distributed parallel sequential mode 7 6 aix linux jcf lt model gt _opt_sa_ user specific control and option file for experiment type optional 68 1 options txt OPT_SA o lt model gt err touch create this file in the model or in lt model gt run as optional lt simenv_ an indicator to stop the complete experiment after 76 run_char gt lt model gt run has been finished for the single model run lt simenv_run_int gt m4 m Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H i f ji 159 Shell script file Perens infor in the current F Explanation Exist status mation workspace see AIM Section usr_opr_ lt opr gt executable for user defined operator lt opr gt optional in the opr_directory 8 5 according to lt model g
281. n simenv res simenv vis simenv dmp simenv res is performed with input file lt file gt if available and interactively for both optionally only for single run lt simenv_run_int gt lt dmp_modus gt simenv cpy copy all SimEnv example files lt model gt from the example directory lt model gt SE_HOME exa to the current directory Additionally example files of user defined operators and for models world _ f c cpp py ja m sh common user defined files are copied All files are only copied if they do not already exist in the current workspace simenv dmp dump SimEnv model output or experiment post processor output files lt model gt Files to dump have to match the SimEnv file name convention for model and or post processor output and are expected to be in the directories as stated in lt model gt cfg Model output variables and post processor results in IEEE and or ASCII format with a dimensionality greater than 1 are listed according to Fortran storage model for multi dimensional fields cf Section 15 7 Glossary lt user_name gt simenv hlp acquire basic SimEnv help information for the specified topics lt topics gt simenv key get password free access to the SimEnv visualization server Only for systems where the SimEnvVis visualization server is not hosted on the local machine check SE_HOME bin simenv_settings txt Start this service only one time before the first access to simenv vis and
282. n 3 01 July 10 2012 11 Structure of User Defined Files Coordinate Transformation Files Value Lists Basic information to describe general control settings of SimEnv model output variables the ex periment itself macros and user defined operators as well as GAMS model specific information is stored in user defined files They are ASCII files and have a common structure that is described in this chapter Addi tionally coordinate transformation files are described and value lists are defined in general 11 1 General Structure of User Defined Files All user defined files listed in Tab 11 1 have the same structure They are ASCIl files with the following re cord structure lt sep gt lt keyword gt lt sep gt lt name gt lt sep gt lt sub keyword gt lt sep gt lt value gt lt sep gt with e lt name gt is the name of a model output variable GAMS model source file experiment factor coordinate user defined operator or macro Declaration of lt name gt depends on the related keyword lt keyword gt e lt keyword gt is a string Normally more than one lines with differing sub keywords belong to one keyword block e lt sub keyword gt is a string Sub keywords are defined only in relation to the user file and the keyword under consideration e lt value gt lt substring gt lt sep gt lt substring gt is a string with user file keyword and sub keyword related information e lt sep gt i
283. n file lt model gt edf General Approach Experiment Description File lt model gt edf lt model gt edf is an ASCII file that follows the coding rules in Section 11 1 on page 169 with the keywords names sub keywords and value as in Tab 6 1 Tab 6 1 Elements of an experiment description file lt model gt edf for all experiment types Max Keyword Name k Sub Line line Value Explanation eyword type nmb general lt nil gt descr 0 any lt string gt experiment description type m 1 GSA_EE experiment type DFD LSA UNC_MC OPT_SA factor lt factor_ descr 0 1 lt string gt factor description name gt unit o 1 lt string gt factor unit type m 1 see Tab 6 2 factor adjustment type specifies how to adjust the sampled values by the factor default nominal value in simenv_get_ to get the re sulting adjusted factor value default m 1 lt real_val gt factor default nominal value lt factor_def_val gt sample c3 1 lt experiment specifies how to sample the specific gt factor to get sampled values lt factor_smp_val gt specific lt nil gt lt experiment m lt ex lt experiment experiment specific informa specific gt peri specific gt tion ment spe cific gt To Tab 6 1 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e A factor name is the symbolic parameter driver initial value
284. n technique in result evalua tion in future The operator stat_red was introduced because since of the median and quantiles con sumes a lot of auxiliary storage space Having a model output variable definition as in Example 5 1 on page 40 and assuming address_default coordinate in world_ cfg Assume the UNC_MC experiment with the experiment description file UNC_MC from Example 6 6 on page 78 then in experiment post processing avg_e pl atmo 1 19 20 global run ensemble mean of p1 atmo for level 1 and the last two decades Dimensionality 3 Coordinates lat lon time Extents 45 90 2 avg atmo 1 1 s20 global mean of atmo for level 1 and the last two decades for run number 0 Dimensionality 0 Coordinates without Extents without ens atmo 1 20 run ensemble values of atmo for level 1 and the last decade Dimensionality 3 Coordinates lat lon run Extents 45 90 250 minprop_e atmo 1 19 20 run ensemble run number for level 1 and the last two decades where the minimum of atmo is reached the first time Dimensionality 3 Coordinates lat lon time Extents 45 90 2 m e 132 y H Es f J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Wale S aicmo i 19320 eee dl L320 anomaly for run ensemble variance from the default nominal run for level 1 the last two decades Dimensionality 3 Coordinates lat
285. n the file corresponds the current single to the sequence of the factors in the experiment run description file lt model gt edf SE_HOME bin transfer ASCII file lt file_ name gt Name of an ASCII file that is transferred to SimEnv simenv_ to SimEnv model input model output according to model output variable put_as output coordinate lt coord gt lt file_name gt in safe mode lt coord gt lt coord gt Name of a model output variable coordinate simenv_put_as is input Lines in lt file_name gt correspond to coordinate a normal shell values If lt coord gt is not specified lt file_name gt has script and NOT a to be a one record file dot script SE_HOME bin transfer ASCII file lt file_name gt Name of an ASCII file that is transferred to SimEnv simenv_ to SimEnv model input model output according to model output variable put_as_ simple output coordinate lt coord gt lt file_name gt in simple mode lt coord gt lt coord gt Name of a model output variable coordinate simenv_put_as___ input Lines in lt file_name gt correspond to coordinate simple is a values If lt coord gt is not specified lt file_name gt has normal shell to be a one record file script and NOT a dot script After performing the dot script simenv_get_as an ASCII file lt model gt as lt simenv_run_char gt holds lines with a factor name and its resulting adjusted value per line Each factor name is separated
286. n_res simenv_ 0 ok compute_user_ 0 user defined interrupt of calculation def_operator function value Operator results of a dimensionality gt 1 have to be stored to the field res using the Fortran storage model cf Section 15 7 Glossary noe S 138 y H Es f J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 A function value 0 of simenv_check_user_def_operator should be set according to the following rules e f appropriate forward function value from the operator interface function simenv_chk_2args_ f c see below to the function value of simenv_check_user_def_operator The corresponding error message is reported automatically by the experiment post processor Return code 4 from simenv_chk_2args_ f c is only an information and no warning and is not reported e Other detected inconsistencies between operands have to be reported to the user by a simple print statement within simenv_check_user_def_operator The corresponding return code has to be greather than 5 Tab 8 19 summarizes these SimEnv operator interface functions that can be applied in the declarative and computational part written in Fortran or C C postfix f for Fortran c for C C to get and put structure information In this table the input and output data types are documented for functions used in Fortran For C C the corresponding data types are valid Implementation of th
287. nation of model state variable s local sensitivity to factors Is performed Local sensitivity by finite difference derivative approximations from the model analysis For numerical validation purposes model analysis sub model sensitivity BAY_BC Reduce uncertainty about factor values by deriving a representative sample from Bayesian factor prior distributions while having measurement values from the system avail technique able for model measurement comparison Bayesian For uncertainty analysis and reduction with a Bayesian technique calibration OPT_SA Determination of optimal factor values by a simulated annealing method for a cost Optimization function derived from state variables Sate ans For model validation system model comparison control design decision mak nealing i ing The experiment types come with special properties e A model free method is model independent It can cope with non linear non additive and non monotonic models Each of these three properties holds for the relation between each factor x i 1 K and the state variable and or output function under consideration e Some methods take the sample from pre defined factor levels rather than from pre defined factor distri butions The former approach allows for performing an analysis without knowledge about factor distribu tions and the accompanying distribution parameters Multi Run Simulation Environment SimEnv User Guide
288. nce of digits 0 and 1 min_ sequence of digits 0 and 1 minprop_ sequence of digits 0 and 1 move_avg sequence of digits 0 to 9 move_avg lin exp rank tie_plain tie_min tie_avg regrid lt directory gt lt file_name gt run not pre defined case insensitive run_info run_nr nr_of_runs sens_abs not pre defined case insensitive Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Argument value Operator Argument without quotation marks Remark number pre defined values are case insensitive sens_rel 1 not pre defined case insensitive sum_ 1 sequence of digits 0 and 1 sym_abs 1 not pre defined case insensitive sym_rel 1 not pre defined case insensitive transpose 1 sequence of digits 1 to 9 var_ 1 sequence of digits 0 and 1 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 5 4 Constant Arguments of Experiment Post Processor Built In Operators Tab 15 11 summarises for built in operators constant argument values Tab 15 11 Constant arguments of experiment post processor built in operators Operator Argument Argument Argument value number type restriction classify 1 int_arg 0 22 classify 2 real_arg arg2 arg3 0 classify 3 real_arg arg2 lt arg3 cnf 1 rea
289. ndition char_arg1 arg2 then res arg3 else res arg4 endif with condition char_arg1 arg2 arg2 lt 0 char_arg1 lt arg2 lt 0 char_arg1 lt arg2 gt 0 char_arg1 gt arg2 2 0 char_arg1 gt arg2 0 char_arg1 arg2 0 char_arg1 arg2 defined char_arg1 def arg2 undefined char_arg1 undef The operator mask supplies a method to mask to set undefined elements based on their values It operates for each element of the operand arg2 in the following way if condition char_arg1 arg2 arg3 then res undef else res arg2 endif with condition char_arg1 arg2 arg3 arg2 lt arg3 char_arg1 lt arg2 lt arg3 char_arg1 lt arg2 gt arg3 char_arg1 gt arg2 2 arg3 char_arg1 gt arg2 arg3 char_arg1 arg2 arg3 char_arg1 The operators mask_file and unmask_file mask the elements of arg2 set them undefined according to their position the latter stored in the ASCII file char_arg1 For operator mask_file all those values of arg2 are masked that are specified in the mask file char_arg1 while for operator unmask_file all values of arg2 are masked that are not specified in the file char_arg1 Each line of the mask file char_arg1 has to follow the subsequent syntax i c lt value gt lt value 2 gt lt sep gt lt sep gt i c lt value gt lt valuen
290. ne show interactions with other factors and or a nonlinear effect on model output 4 3 Global Sensitivity Analysis Variance Based Method GSA_VB The guiding question of variance based methods for sensitivity analysis of model output is how the variance of model output depends on the variability of the model factors and how the output variance can be appor tioned accordingly With respect to this approach variance based methods have a connection to analysis of variance ANOVA studies and the design of experiments DOE For variance based methods it is assumed that all what is known about the sensitivity of the model output to the factors and consequently can be ex ploited is captured by the variance of the model output For variance decomposition the method of Sobol Sobol 1993 and a cost efficient implementation by Sal telli Saltelli 2002 Saltelli et al 2008 have been implemented Related to the decomposition of the variance the overall goal is to decompose the variance V z on model output z into a sum of 2 1 terms V z Vi LIV L to Viz 1si lt j lt lt m lt s sk k number of factors with Vi fraction caused by factor x Vi fraction caused by interaction of factors x and x Vm s fraction caused by interaction of factors Xm Xs Vi2 k fraction caused by interaction of all k factors Theoretically the unconditional variance V Z of Z can be reduced by fixing X to its
291. necessary copy it to SE_WS and modify it SE_HOME lib simenv_opr_ used in shell script to compile and link a user defined op f c cpp Ink stand alone erator source code for experiment post processing If necessary copy it to SE_WS and modify it SE_HOME lib simenv_mod_ used in ASCII include file for an interfaced model source f c inc interfaced Fortran C C code to define SimEnv interface functions SE_HOME inc models simenv_mod_auto_ f c inc SE_HOME inc used in interfaced Fortran C C models ASCII include file for an interfaced model source code to define SimEnv interface functions and to declare auxiliary variables for the semi automated model interface simenv_opr_ f c inc SE_HOME inc used in user defined Fortran C C operators ASCII include file for a user defined operator source code to define SimEnv interface functions lt model gt _ f c py sh as inc SE_WS generated during experiment preparation only for service run not for service re start only for auto_interface no in lt model gt cfg ASCII include file for semi automated model inter face The files can be used directly in the interfaced model source code for Fortran C C and Py thon or as a dot script in lt model gt run for the shell script and ASCII interface Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 10 5 User Defi
292. ned Files and Shell Scripts Temporary Files Tab 10 7 lists the mandatory or optional shell scripts and files the user has to provide for running SimEnv services Tab 10 7 User files and shell scripts to perform any SimEnv service make sure by the Unix Linux command chmod u x lt file gt that a file lt file gt has execute permission Shell script file e in the current E wks xplanation Exist status mation workspace ee IE Section lt model gt cfg ASCII user defined general configuration file optional 10 1 lt model gt mdf ASCII user defined model variables description file mandatory 5 1 lt model gt edf ASCII user defined experiment description file mandatory 6 1 lt model gt mac ASCII user defined macro description file optional 8 6 lt model gt odf ASCII user defined operator description file optional 8 5 4 lt model gt gdf ASCII user defined GAMS model output description file for GAMS mod 57 2 els mandatory Z lt model gt run model shell script to wrap the model executable mandatory 7 6 lt model gt rst model shell script to prepare single model run restart optional 7 6 lt model gt ini model shell script to prepare simulation experiment optional additionally to standard SimEnv preparation for Python Java Matlab and GAMS 7 6 models manda tory and stan dardized lt model gt end model shell script to wrap up si
293. ng defects or freezing out in metastable states i e trapped in a local minimum energy state The annealing scheme is that an initial state of a thermodynamic system is chosen at energy E and tempera ture Temp holding Temp constant the initial configuration is perturbed and the change in energy dE is com An 30 Y HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 puted If the change in energy is negative or zero the new configuration is accepted If the change in energy is positive it is accepted with a probability given by p exp dE ks Temp where kg denotes the Boltzmann constant This process is then repeated sufficient times to give good sam pling statistics for the current temperature and then the temperature is decremented and the entire process repeated until a frozen state is achieved at Temp 0 By analogy the generalization of this Monte Carlo approach to optimization problems is straight forward e The current state of the thermodynamic system is analogous to the current solution to the optimization problem e The energy equation for the thermodynamic system is analogous to the objective function F and e The ground state at Temp 0 is analogous to the global minimum of F The major difficulty art in implementation of a simulated annealing algorithm is that there is no obvious analogy for the temperature Temp with respect to a free parameter in the optimizat
294. not applied set the value to no If it is applied in For tran or C C models set the values to f_c and for Python Java or Matlab model to py_ja_m If in the overall model slices are used in Python Java or Matlab and as well as in Fortran or C C set the value to py_ja_m Running a model with slices py_ja_m results in a significant increase of CPU time con sumption per call of simenv_slice_ and simenv_put_ since slice information is then stored in external files rather than internally as for slices f_c For keyword model sub keyword auto_interface Check Section 5 10 For keyword model sub keyword structure Check Section 5 11 For keyword experiment sub keyword begin_run end_run include_runs exclude_runs With the exception of experiment types UNC_MC with a stopping function BAY_BC and OPT_SA SimEnv enables to perform an experiment partially by performing only a subset of all defined single simulation runs from the whole run ensemble cf Section 7 5 on page 96 To declare runs for including into a SimEnv experiment use either sub keywords begin_run and end_run or sub keyword in clude_runs For begin_run and end_run assign appropriate run numbers Make sure that begin and end run represent integer run number including run number 0 and that begin run lt end run The value string last for end_run always represents the last simulation run
295. nt factor and per model output variable one additional SimEnv function call into the source code or can be done at the shell script level Additionally there are special interfaces for Mathematica and GAMS models e Support of distributed models Independently on the kind distributed model components are interfaced to SimEnv and among each other the total model can be run within SimEnv e Parallelization of the experiment This is a prerequisite for a lot of simulation tasks e Operator based experiment post processing Chains of built in user defined and composed operators enable interactive experiment post processing based on experiment model output and reference data including general purpose and experiment spe cific operators There is a simple interface to write user defined and to derive composed operators e Visual experiment evaluation For post processed experiment output e Support of standard data formats Output from the model as well from the post processor can be stored in NetCDF or IEEE compliant bi nary format Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN iat J 3 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 1 About this Document In this chapter document conventions are explained Within the whole document one generic refer ence example model is used to explain application of SimEnv Examples are always located
296. nt performance simenv run and all successive simenv rst lt model gt mlog SE_WS experiment performance ASCII minutes file of model interface functions performance simenv run and all successive simenv rst lt model gt mlog is organized single run by single run lt model gt nlog SE_WS experiment performance ASCII minutes file of native model specific experim prepar by lt model gt ini single runs model output by lt model gt run single run restart preparation by lt model gt rst model specific experim wrap up by lt model gt end performances redirected from terminal simenv run and all successive simenv rst lt model gt nlog is organized single run by single run Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 File location Generated in Explanation run lt simenv_run_char gt SE_WS experiment performance only for GAMS models sub directory for GAMS model performance that are kept according to the sub keyword keep_runs in lt model gt gdf lt model gt blog SE_WS experiment performance only for experiment type BAY_BC ASCII minutes file of Bayesian calibration lt model gt bmlog SE_WS experiment performance only for experiment type BAY_BC ASCII minutes file of Bayesian calibration for the multiple setting case lt model gt olog experiment performance
297. nt_arg2 real_arg3 real_arg4 argument histogram of values argo max arg1 argument maximum of values maxprop arg1 index of the element where the maximum is reached the first time min arg1 argument minimum of values minprop arg1 index of the element where the minimum is reached the first time sum arg1 argument sum of values var arg1 argument variance of values Multiple aggregation a nd moment operators for arguments Tab 8 6 on page 111 max_n arg1 argn maximum per element maxprop_n arg1 argn argument position 1 n where the maximum is reached the first time min_n arg1 argn minimum per element minprop_n arg argn argument position 1 n where the minimum is reached the first time Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Name Meaning See Dimension related aggregation and moment operators for arguments Tab 8 7 on page 112 avg_ char_arg1 arg2 dimension related argument arithmetic means of values of arg2 avgg_l char_arg1 arg2 dimension related argument geometric means of values of arg2 avgh_lI char_arg1 arg2 dimension related argument harmonic means of values of arg2 avgw_I char_arg1 arg2 arg3 dimension related argument weighted means of values of arg2 count_I char_arg1 char_arg2 arg3 dimension related count numbers of values of ar
298. ntax rules for ASCII data files check Section 11 3 Sample size has to be identical to lt int_val gt from the sub keyword runs Explic itly specified samples can not be applied for experiment types GSA_EE and BAY_BC e Sub keyword sample_method The sub keyword sample_method allows to select the random sampling method to be applied individu ally for each factor For pseudo random numbers a deterministic algorithm is used that approximates the properties of the given factor s distribution by a sequence of generated numbers The sequence de pends on an initial values that is controlled by the sub keyword seed For stratified random sampling the Latin Hypercube approach e g McKay et al 1979 Iman amp Helton 1998 Helton amp Davis 2000 is used The sampling range of the factor as determined by the distribution is divided into lt int_val gt from the sub keyword runs intervals of equal probability according to the given distribution and from each in terval exactly one sampling point is drawn The sampling point within each interval is drawn with a pseudo random number approach Quasi random sampling is based on the usage of pre defined Sobol sequences Sobol 1967 amp 1976 for the interval lt 0 1 gt Sobol quasi random sampling is also known as LP sampling In general quasi random sampling results in a low discrepancy sequence which show a regular distribution pattern in the factor space and hence qualify it for numeric
299. nteger 4 return code simenv_ 0 ok get_co_arg_ flc function value simenv_ get for a coordi integer 4 formal number of the coordinate get_co_val_ nate a coordinate ico_nr from simenv_get_co_arg f c flc value at a speci input fied position integer 4 formal position within all coordinate values of the ico_nr ico_pos value to get ico_pos input The smallest ico_pos to use corresponds to the co_val value ico_beg_pos from the function simenv_get_co_arg f c real 4 coordinate value co_val For non monotonic coordinate values output Do not get value number ico_pos but the Application of this ico_pos th smallest value sort values in increas function in ing manner simenv_check__ integer 4 return code user_def_operator simenv_ 0 ok for coordinate get_co_arg_ 1 ico_pos out of range bin_mid results in f c 2_ storage exceeded an error function value a m 140 y HN ia ii Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Function Function ieee Inputs outputs function value name description PP value description simenv_ check two argu integer 4 argument number chk_2args_ ments on same iarg1 fic dimensionality input extents and coor integer 4 argument number iarg1 dinates iarg2 iarg2 input If appropriate integer 4 return code forward return simenv_ 0 ok code 0 to the chk_2args_ 1 differing dimensionalities function value of
300. nv User Guide Fig 4 6 a DFD parameter p1 without add i list i 3 77 amp 2 4 8 9 for p1 parameter p2 without multiply 2E list i 2 5p 4 2 4 6 8 for p2 default Fig 4 6 b DFD multiply Le lage lp Sp Wy amp 1 3 7 8 for p1 multiply Zs 6 equidist_end 1 0 5 2 5 2 3 4 5 for p2 pl p2 iv es Ue DFD set is Lise i 3 F amp 1 3 7 8 for p1 Ser Dee equidist_end 1 1 4 1 2 3 4 for p2 multiply 3o ligt 2 0 2 8 3 38 6 0 8 4 9 9 for p3 Multi Run Simulation Environment SimEnv m User Guide for Version 3 01 July 10 2012 SHEN MZ 75 specific comb PIPE PS world edf_DFD_d general descr Eig 4 6 p general type DFD file world dat DFD d LaCTOL pl type multiply iL 0 ACE ONe foul default ee 3 1 factor p2 type add 7 2 factor p2 default One 8 3 specific comb file world dat_DFD_d strict 1 2 3 3 7 4 8 5 for p1 p2 Example files world edf_ DFD_ a b c d Example 6 5 Experiment description files lt model gt edf for DFD experiments 6 5 Uncertainty Analysis Monte Carlo Method UNC_MC The experiment specific information for experiment description files in Tab 6 1 on page 63 is defined for an UNC_MC experiment as describes in Tab 6 8 Tab 6 8 Experiment specific elements of an edf file for UNC_MC Max keyword Name k ale eine ine Value Explanation eyword typ
301. ocessor cores of a class par parallel sub mode A number of processor cores are assigned to the experiment during experiment preparation and one parallel job is submitted to the job class During the experiment one communication processor node is responsible for experiment management while the other processors serve as simulation processor cores for the single runs The experiment performance will start when the assigned number of processor cores are free in this class This sub mode makes use of the Message Passing Interface MPI Use this sub mode to make sure to run an experiment in a certain time For inter node communication check the remark below e on one pre allocated processor core of a class seq sequential sub mode Additionally to the above distributed and parallel sub modes SimEnv also offers a sequential sub mode under control of the job management system One processor core of a job class is assigned to the whole experiment and the experiment is performed sequentially on this processor core The experiment per formance will start when one processor core of this job class is free After an experiment is submitted to the load leveler the current login session can be closed xno Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN aP I 93 Default job control files are supplied by SimEnv to ensure communication with the load leveler and POE These job control files may be copied
302. odel Interface To use any model within SimEnv it has to be interfaced to the simulation environment SimEnv offers easy coupling techniques at programming language and shell script level While at language level SimEnv func tion calls have to be implemented into model source code to address and modify numerically experiment factors i e model parameters initial or boundary values or drivers of the current single run out of the run ensemble and to output simulation results at the shell script level communication between the simulation environment and the model can be based on operating system information exchange methods To plug the model into the simulation environment the variables of the model to be output during experiment perform ance and to be potentially processed during experiment post processing have to be declared in the model output description file lt model gt mdf Additionally the model itself has to be wrapped into a shell script lt model gt run Model interfacing is related to transferring sampled numerical values of model factors under investigation from the simulation environment to the model and to transferring model output variables under investigation from the model to the simulation environment for later experiment post processing Interfacing is supported at the programming language level for C C Fortran Python Java Matlab Mathematica and GAMS pro gramming languages the model is implemented in and at shell script lev
303. odel are handled in experiment post processing as their corresponding nodata values cf Tab 10 13 Application of simenv_slice_ py ja m demands a corresponding slice entry in the configuration file lt model gt cfg For more information check Section 10 1 Application of simenv_slice_ py ja m results in a higher consumption of computing time for each single run of the experiment compared without simenv_slice_ For this case keep in mind the trade off between the demand for computing time and the demand for main memory SimEnv Python model interface modules are declared in the file simenv py in the sub directory bin of the SimEnv home directory To use these modules in a Python model import it by from simenv import and refer to them for example by simenv_get_py SimEnv Java model interface methods are declared in the file Simenv java in the sub directory bin of the SimEnv home directory The corresponding class file Simenv class is also located there Specify in lt model gt run or in the profile file the CLASSPATH by export CLASSPATH SE_HOME bin CLASSPATH before calling java to run the model To use an interface method in a Java model refer it for example by Simenv simenv_get_ja SimEnv Matlab model interface functions are in the sub directory bin of the SimEnv home directory Insert into the file HOME matlab startup m addpath getenv SE_HOME bin before performing an experiment with a Matlab model Start a
304. odel enlargements or re formulations It is a linear approximations of the classical model sensitivity measure Wierzbicki 1984 Contrary to a global sensitivity analysis a local one covers the model s sensitivity in the neighbourhood of the default nominal factor con stellation Local sensitivity measures as well as measures which reflect model output linearity and or symmetry nearby Xx can be used for localizing modification relevant model parts as well as control sensitive factors in control problems On the other hand identification of robust parts of a model or even complete robust models aa 26 y HN a i i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 makes it possible to run a model under internal or external disturbances Sensitivity analysis in SimEnv ex periment post processing is based on finite sensitivity linearity and symmetry measures which are defined as in Tab 4 5 x X212 sample of size 12 in the 2 dimensional factor space X2 X1 X2 o X21 default nominal numerical factor constellation of model M X1 Fig 4 8 Sample for a local sensitivity analysis LSA Tab 4 5 Local sensitivity linearity and symmetry measures for a state variable z a selected factor x from X and a selected value from 1 Em Local Definition measure Absolute measure Relative measure sensitivity sens_abs z te z x z x sens_re
305. of Output from a Computer Code Technometrics 221 239 245 Morris M D 1991 Factorial plans for preliminary computational experiments Technometrics 33 2 161 174 Pettitt A N 1979 A non parametric Approach to the Change point Problem Applied Statistics 28 126 135 Rabitz H Alis O F 1999 General foundations of high dimensional model representations Journal of Mathematical Chemistry 95 197 233 Saltelli A Chan K Scott E M eds 2000 Sensitivity Analysis J Wiley amp Sons Chichester Saltelli A 2002 Making best use of model valuations to compute sensitivity indices Computer Physics Communications 145 280 297 Saltelli A Ratto M Andres T Campolongo F Cariboni J Gatelli D Saisana M Tarantola S 2008 Global Sensitivity Analysis The Primer J Wiley amp Sons Chichester Saltelli A Tarantola S Campolongo F Ratto M 2004 Sensitivity Analysis in Practice A Guide to As sessing Scientific Models J Wiley amp Sons Chichester SAS STAT R 9 2 User s Guide http support sas com documentation cdl en statug 63033 HTML default viewer htm statug introbayes s ect008 htm Accessed Feb 14 2012 Schulzweida U Kornblueh L Quast R 2004 Climate Data Operators Max Planck Institute for Meteor ology http www mpimet mpg de fileadmin software cdo Sin G Gernaey K V 2009 Improving the Morris method for sensitivity analysis by scaling the elementary effect
306. of a variance of a nor variance gt 0 normally distributed mally distributed factor factor exponential E mean value mean value gt 0 For more information on the distribution functions see Section 4 5 and Tab 4 4 f 10000 2 1 10000 2 x 1 1000 2 0 2 04 0 6 0 8 1 0 00 az os 03 oe 1s co az a as 08 10 0 0 02 04 0 8 0 8 13 341 10000 1 21 1800 1 x 1 10C0 1 Fig 6 1 Probabilistic sampling Pseudo and quasi sampling left pseudo sampling sample size N 10000 mid quasi sampling N 10000 right quasi sampling N 1000 Factors on abscissa and ordinate U 0 1 From http en wikipedia org GNU Free Publication License Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 67 X2 Sample size N 12 single simulation runs Factor x is normally distributed Factor x2 is uniformly distributed x4 Fig 6 2 Probabilistic sampling Latin hypercube sampling only sampling relevant sub keywords without sample method are shown factor pl descr sample without restrictions in int inf LACTOL pl sample distr N 0 0 04 factor p2 descr as pl but sample only within the 3 sigma range factor p2 sample distr N 0 0 04 LECTOR p2 sample exclude ines 0 6 y OoSorriimi ACE Ons p3 descr equivalent to p2 factor p3 sample distr N 0 0 04 factor p
307. of its operand lt result_description gt aggregated atmospheric state according to lt model gt mdf lt result_unit gt without according to lt model gt mdf Energy abs atmo applies operator abs to atmo lt result_description gt Energy according to lt model gt mdf lt result_unit gt without according to lt model gt mdf Example 8 1 Addressing results in experiment post processing 8 1 2 Operands Operands in result expressions can be Model output variables as defined in lt model gt mdf In the following abbreviated by arg Example atmo Experiment factors as defined in lt model gt edf In the following abbreviated by arg Example p1 Constants lt int_val gt or lt real_val gt In the following abbreviated by int_arg and or real_arg Example 12 and 12 and 12 34 and 1 234e 1 Character strings lt string gt enclosed in single quotation marks In the following abbreviated by char_arg Example tie avg Operator results In the following abbreviated by arg Example abs atmo and atmo 3 Macros as defined in lt model gt mac cf Section 8 6 Example equ 100yrs_m m r 102 y H Es f J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Wildcard operands cf Section 8 7 Example amp v amp As for model output variables cf Section 5 1 also to each operand with the exception of character string operands
308. of the experiment For the character argument nr_of_runs the number of performed single runs of the current post processed experiment without the run number 0 is returned The operator transpose enables to transpose an operand that has a dimensionality gt 1 Sequence of extents of the transposed result is described by character argument char_arg1 It consists of digits 1 dim arg2 where the digit sequence corresponds to the re ordered sequence of the operator result ex tents A character argument char_arg1 123 results for the operator transpose in the identity of argument arg2 The operator undef supplies a 0 dimensional result as undefined Among others this operator can be used as an argument for the if operator The operator usage prints a short usage for the post processing operator name char_arg1 Additionally operator class names can be used instead of an operator name all for all operators basic for basic operators Section 8 3 2 trigonometric for trigonometric operators Section 8 3 2 aggr moment aggregation moment operators Section 8 3 3 advanced advanced operators Section 8 3 4 multi run multi run operators Section 8 4 user defined user defined operators 8 5 The operator is a stand alone operator It must not be operands of any other operator For examples of the described operators check Section 8 3 5 8 3 5 Examples Having a model output variable definition as in Example 5 1 on pag
309. of the output set of a gt model that is stored during a SimEnv experiment in SimEnv model output Variables are defined in the model output description gt user file Each variable has a unique gt data type a gt dimensionality gt extents and an assigned gt grid Normally a variable consists of a series of values forming a field White spaces gt also known as blanks ASCII characters space and horizontal tabulator used in gt user defined files or within result expressions in gt experiment post processing Workspace The directory a SimEnv service was started from Sno Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN a J i lt 235 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012
310. of values 10 real_arg2 minimum bound for values in class 1 real_arg3 maximum bound for values in class int_arg1 arg2 0 and arg3 0 automatic bound determination clip clip arg2 according to dim arg2 gt 0 clip char_arg1 char_arg1 dim res ext res i depend on YO 1 10 4 arg2 char_arg1 and arg2 atmo char_arg1 clip range cumul cumulate compute par 1 cumul char_arg1 tial sums of arg2 dim arg2 gt 0 0001 arg2 according to char_arg1 char_arg1 cumulation indicator atmo per dimension distr_par get for experiment types 7 distr par char_arg1 with probabilistic sam char_arg1 factor name pl 2 int_arg2 pling the value of a fac int_arg2 number of the distribu tor s distribution parame tion parameter lt 2 ter flip flip arg2 according to 1 but coordinates are also flipped flip char_arg1 char_arg1 dim arg2 gt 0 0001 arg2 char_arg1 flip indicator per atmo dimension 3 m Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f i 113 Argument restriction s Argument Name Meaning result description value Example Tab 8 1 page restriction 106 get_data get data from an external dimensionality extents and coordi get _data char_arg1 file nates according to char_arg3 and ne char_arg2 char_arg4 data ne char_arg3 char_arg1 data file format data def arg4 netcdf ascii
311. omega lat 2 by float phi_lon 3 F float omega lon 4 F simenv sts Simenv simenv ini ja simenv_ get run ja only if necessary phi lat Simenv simenv get ja pl1 phi lat omega lat Simenv simenv get ja p2 omega lat phi lon Simenv simenv get ja p3 phi lon omega lon Simenv simenv get ja p4 omega lon compute dynamics of atmo and bios over space and time of atmo_g over time all dependent on pl p2 p3 p4 for idecade 0 idecade lt 20 idecade for level 0 level lt 4 level simenv sts simenv sts simenv sts simenv sts Simenv simenv put ja atmo atmo Simenv simenv put ja bios bios Simenv simenv put ja atmo g atmo g Simenv simenv put ja bios g bios g simenv sts Simenv simenv end ja System exit 0 simenv run int Integer parseInt Simenv simenv get run ja Example file world_ja java Example 15 6 Model interface for Java models model world_ja java ra Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN ai I 42 203 15 2 8 Matlab Model With respect to Example 5 1 the following Matlab code world_m m could be used to describe the model interfaced to SimEnv SimEnv modifications are marked in bold atmo zeros 45 90 4 20 bios zeros 36 90 20 atmo_g zeros 20 pantelar 1Pi omega_lat 2 plawelon sry omega _lon 4 simenv sts simenv ini m o simenv get_run m
312. only for experiment type ASCII minutes file of optimization experiment per formance SE_WS OPT_SA lt model gt fct experiment performance ASCII file of function values Record no n 1 corresponds to single run no n only for experiment types UNC_MC with stopping rule SE_WS BAY_BC and OPT_SA lt model gt experiment performance indicator file that in lt model gt run a process was killed lt simenv_run_char gt SE_WS killed by the shell script simenv_kill_ process due to CPU time exceeding lt model gt res lt simenv_res_char gt nc ieee ascii postproc out_directory experiment post processing output file of an experiment post processing ses sion lt model gt inf lt simenv_res_char gt ieee ascii postproc out_directory experiment post processing output structure description file of an experiment post processing session Temporary files do not delete during performing the corresponding service lt model gt out lt simenv_run_char gt nc ieee model out_directory experiment performance if out_separation no in lt model gt cfg if the experiment is performed by the load leveler in distributed or parallel mode lt model gt as lt simenv_run_char gt experiment performance ASCII file with all factor names and their adjusted values SE_WS only for simenv_get_as asa_opt experiment performance auxiliary files for e
313. operator lt opr gt usr_opr_ lt opr gt executable for user defined operator lt opr gt land_sea_mask lt nil gt f executable and source code to derive a coarsed land sea mask from the file land_sea_mask 05x05 land_sea_mask 05x05 global ASCII land sea mask file with a resolution of 0 5 lat x 0 5 lon read_result_file lt nil gt f executable and source code for the result file import interface of ASCII and IEEE compliant result output Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 1 5 Example User Defined Operators The following user defined operators are available from the example directory SE_HOME exa as source code and executables usr_opr_ lt opr gt All but operator matmul_c source file usr_opr_ lt opr gt c are imple mented in Fortran and available as source files usr_opr_ lt opr gt f Tab 15 6 Available user defined operators sis neme Operator arguments Explanation Example opr gt char_test char_arg1 character test char_test arg11 char_arg2 check usr_opr_char_test f arg22 bios arg corr_coeff arg1 correlation coefficient R corr coeff bios arg2 bios 1 div arg1 division as an example how the div 2 4 0 5 arg2 corresponding built in basic opera tor works matmul_ f c arg1 matrix multiplication of 2 matmul f c arg2 dimensional operands mat1 mat2 simple_d
314. or lt fac tor_name gt from the experiment description file lt model gt edf is available in lt model gt run as a shell script variable lt factor_name gt and the resulting adjusted value of the factor is available as lt factor_name gt e After running the model model output has to be identified and potentially transformed within lt model gt run for SimEnv output To do this simply write a model related simenv_put_sh as a transformation program that reads in all the native model output and outputs it to SimEnv by applying the model interface func tions simenv_ _ from the SimEnv model interfaces at language level e Tab 10 10 lists the built in pre defined shell script variables that are defined and or used by the dot scripts SE_HOME bin simenv_ _sh and are directly available in lt model gt run e Notice To perform a dot script cf Section 15 7 Glossary it has to be preceded by a dot and a space In Example 15 10 on page 208 the model shell script world_sh run is described in detail SSE_HOME bin simenv_ini_sh o get adjusted value tor the a tractor o Cert Corinei in the Gcli rile factor name p def CaCO Cer val z SSE_HOME bin simenv_get_sh now shell script variable p def is available iG valus ot shell geript variable jo cer is according to edf file p get adjusted valve for a tactor p undei not Ceftined in eck factor name p undef Ibe ene Oie Clie inval ooo SSE_HOME bin simen
315. or the meaning of pdf X and z check Section 4 5 Bayes theorem Pdfpo prior avga vara pdf prior L avga vara prior pdf avga vara is applied with Pdfpo prior avga vara posterior distribution given data avga vara pdf prior prior distribution L avga vara prior likelihood function of the data avga vara given model output z X pdf avga Vary normalization constant If the data avga have a low measurement error vary then the posterior distribution is expected to represent less uncertainty than the prior distribution Since Bayes theorem in general can not be solved analytically for a simulation model a representative sample for the posterior distribution is generated by a Markov chain Monte Carlo method MCMC In SimEnv the Metropolis Hastings algorithm is used for MCMC and the argu mentation and implementation in van Oijen 2008 is followed The Metropolis Hastings algorithm itself per forms a random walk through the factor space A chain of visited points is generated where a candidate for the posterior distribution for the chain is generated randomly and is accepted or rejected dependent on the Metropolis ratio The candidate point in the factor space is found by a multivariate normal jump from the pre viously accepted point in the chain The individual probability density function used for the likelihood function is determined by the distribution of the measurement errors Here the com
316. out pre defined values get_experiment Model f atmo Exceptions information e lt directory gt and sensitive model out directory MyDir lt value gt in lt file_ name gt factor pl sample file MyF user defined files for lt sub keyword gt factor pl unit kWh lt string gt _directory and in lt val_list gt e lt value gt for lt sub keyword gt descr unit lt model gt edf e lt factor_name gt sensitive factor pl sample list for Mathematica as in the 1 2 3 models Mathematica factor P1 sample list model 345 lt model gt gdf e GAMS model file name sensitive model sub ml type sub for GAMS model sub M1 type sub models 10 8 Numerical Nodata Representation For model output with the SimEnv model coupling interface functions and for experiment post processor output the following data type specific nodata values are used to represent undefined unwritten model out put and undefined post processor output Tab 10 13 Data type related nodata values SimEnv data type cf also Tab 5 4 NERS IS byte int 1 127 short int 2 32767 int int 4 2147483648 float real 4 2 3 4E 38 double real 8 2 1 79D 308 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 10 9 Operating System Environment Variables The following operating system environment variables are used by SimEnv Additionally make sure that in
317. p_val gt from lt val_list gt have to be ordered in a strictly monotonic increasing manner for syntax see Tab 11 6 To Tab 6 9 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e For a LSA experiment only the factor adjustment types add and relative are allowed e Values from the value list must be positive and unique 6 6 1 Sensitivity Functions Run Sequence As an example the absolute sensitivity function cf Tab 4 5 on page 27 is as follows for adjustment type Add sens_abs lt factor_def_val gt lt factor_smp_val gt z lt factor_def_val gt lt factor_smp_val gt z lt factor_def_val gt lt factor_smp_val gt for adjustment type Relative sens_abs lt factor_def_val gt lt factor_smp_val gt z lt factor_def_val gt 1 lt factor_smp_val gt z lt factor_def_val gt lt factor_def_val gt lt factor_smp_val gt The sequence of the single simulation runs in the experiment is determined in the following manner loop over increment sequence loop over experiment factors sample point endloop endloop loop over negative increment sequence loop over experiment factors sample point endloop endloop A Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji _ 79 6 6 2 Example general desc
318. pending suffixes to the generic operator name e Appending no suffix Aggregate the only non character non constant argument Result is a scalar an operator result of dimensionality 0 e Appending suffix _n for n arguments Aggregate an arbitrary number of non character non constant arguments element by element Currently only operators min_n max_n minprop_n and maxprop_n are implemented Result has same dimensionality extents and coordinates as the arguments e Appending suffix _I for loop Aggregate the only non character non constant argument separately for selected dimensions Dimen sions to select are described by an additional loop character argument These operators correspond to the group by clause of the standard query language SQL of relational database management systems Result has a lower dimensionality as the only non character argument according to the loop character argument e Appending suffix _e for run ensemble Aggregate separately for each index of the only non character non constant argument over the ensem ble of all single simulation runs but single run 0 Consequently the operators are applied as multi run operators check Section 8 4 1 Result has same dimensionality extents and coordinates as the arguments e Exceptions to the above rules hold for operators minprop maxprop and hgr e Additionally the operators can be used in the selection aggregation filter argument char_arg1 of the multi run o
319. perator dfd for the experiment type DFD For details check Section 8 4 3 e For examples without suffix and with suffix _n _ check Section 8 3 5 with suffix _e check Section 8 4 5 Tab 8 5 Built in standard aggregation moment operators without suffix Aggregation and Argument restriction s moment operator result description Tab 8 1 page 106 max arg1 min arg1 sum arg1 avg arg1 3 var arg1 avgg arg1 avgh arg1 avgw 4 1 arg1 arg2 weight arg2 m EETA 110 Y HN 1a f i lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Aggregation and moment operator Argument restriction s result description Tab 8 1 page 106 one heuristic pdf from all values of arg5 count 3 char_arg1 char_arg1 all def undef arg2 maxprop for dim arg1 gt 1 dim res 1 arg1 ext res 1 dim arg1 else dim res 0 minprop return the index of that element of arg1 where the extreme is reached the first arg1 time according to the processing sequence of the argument field arg by the Fortran storage model cf Section 15 7 Glossary hgr dim res 1 char_arg1 ext res 1 number of bins int_arg2 for char_arg1 bin_no bin number real_arg3 coord res 1 name bin_no real_arg4 values equidist_end 1 1 number of bins arg5 for char_arg1 bin_mid bin mid coord res 1
320. processing sens_abs atmo_g absolute sensitivity measure for atmo_g for all factors increments and signs Dimensionality 4 Coordinates time factor_sequ incr sign Extents 20 3 4 2 cene well seis in sr selt i i atmo G relative sensitivity measure for atmo_g for factor p1 and all positive increments Dimensionality 2 Coordinates time incr Extents 20 4 cene abel eeli e 0 0010 05 etme C absolute sensitivity measure for atmo_g for all factors increment values 1 to 3 and all signs Dimensionality 4 Coordinates time factor _sequ incr sign Extents 20 3 3 2 lin abs sella s OF 001 005 atmo c absolute linearity measure for atmo_g for all factors and increment values 1 to 3 Dimensionality 3 Coordinates time factor_sequ incr sign Extents 20 3 3 Example file world post_LSA Example 8 12 Experiment post processing operators for LSA 8 4 7 Bayesian Technique Bayesian Calibration BAY_BC Tab 8 16 shows experiment specific operators for a BAY_BC experiment that can be used in post processing S aS Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN i f ji 135 Tab 8 16 Experiment specific operators for BAY_BC Argument N z restriction s Argument value ame Meaning ae foot result description restriction Tab 8 1 page 106 bay_bc_run_mask _ mask all values of arg set 1 argumen
321. ps general descr Data centred per lat lon cell general descr This file is valid for all models general descr vorid e cae py Ja my Sioa asi coordinate leg descr geographic latitude coordinate lat unit deg coordinate leit values equidist_end 88 4 88 coordinate lon descr geographic longitude coordinate lon unit deg coordinate lon values equidist_end 178 4 178 coordinate level descr atmospheric vertical level coordinate level uae level no coordinate level values asic ip dv ili le coordinate time descr time in decades coordinate time vinie 10 years coordinate time values equidist_nmb 1 1 20 m S Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y ff ua f ji _ 39 variable atmo descr aggregated atmospheric state variable atmo unit without variable atmo type Eloet variable atmo coords lat lon level time variable atmo almilep epics Ig4is ies eH 5 Ls2e variable bios descr aggregated biospheric state variable bios unit g m variable bios type float variable bios coords lat 5 ALi time variable bios coord Gucemes SHos b6 Lvsoblvs LeZe variable bios alimiclep lt Gexiccincs ILE SiG de MIC z Le2e variable atmo_g type TINE variable atmo g coords time variable atmo g index extents 1 20 variable bios g type HNE Example file world_ f c cpp py ja m sh as maf Example 5 1 Model output description fi
322. put driving forces vector Zo initial value vector B boundary value vector t time At time increment k time delay The output vector Y is a function of the state vector Z parameters P drivers IX and initial values Zo Y t OU Z t P IX Zo Model behaviour Z is determined for fixed k and At by state transition description ST parameters P driving forces IX initial values Zo and boundary values B Manipulating and exploring model behaviour in any sense means changing these four model components While state transition description ST reflects mainly model structure and is quite complex to change each component of the driving forces vector IX normally is a time dependent vector Introduction of additional technical parameters triggers Ptecon can reduce the complexity of handling a model with respect to the five model components described above Changes in state transition description ST can be pre determined in the model by assigning values of a technical trigger parameter Prtecn to apply for ex ample alternative model structures sub structures processes formulations resolutions which are triggered by these values Additionally each component of the driving forces vector IX can be combined with technical parameters in different ways e By selecting special driving forces dependent on the technical value e By manipulating the driving forces with the parameter value e g as an additive or multiplicative increment e B
323. r call gams sub_m2 gms 11 lo 2 1f sub_m2 nlog dp 0 Optdir Example file gams_model gms Example 15 9 Model interface for GAMS models model gams_model gms ria lt RAAF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Jl Ji ic awe lt 207 15 2 11 Model Interface at Shell Script Level Assume any experiment Assume model executable world_sh to take factor values p1 to p4 as arguments from the command line The shell script world_sh run with an interface at shell script level to run the model world_sh and to trans form model output to SimEnv could look like E bin simenv_ sh dot script SE_WS lt model gt _sh inc for semi autom model interface tory run lt simenv_run_char gt to perform the model E bin simenv_ sh dot script bin sh pl 1 p2 2 POSF p4 4 perform always and as the first SE HOM altern perform SSE_HOME bin simenv_ini_sh get current run number lt simenv_run_char gt and lt simenv_run_int gt SE_HOME bin simenv_get_run_sh get adjusted values for factors pl p4 factor name pl factor def _val p1 SE_HOME bin simenv_get_sh Fackorenane p24 factor def val p2 SSE _HOME bin simenv_get_sh factor name p3 factor def val p3 SSE_HOME bin simenv_get_sh factor name p4
324. r output integer 4 return code simenv_get_run 0 ok fic function value simenv_ output model re character name of the variable in lt model gt mdf to be output put_ f c sults to native var_name SimEnv output input var_name file s dimension data of variable var_name to be stored as simula field field tion results type according to lt model gt mdf input integer 4 return code simenv_put_ 0 ok fic 1 var_name undefined function value 2__ I O error for experiment output file Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Functionname Function Arguments Argument function value description function value description simenv_ announce to out character name of the variable in lt model gt mdf to be sliced slice_ f c put at the next var_name corresponding input var_name simenv_put_ f c integer 4 dimension to be sliced idim call only a slice of idim ifrom variable var_name input ito This announce integer 4 slice to start at position ifrom ment becomes ifrom ifrom corresponds to an index from index_extents inactive after per input in lt model gt mdf formance of the integer 4 slice to end at position ito corresponding ito ito corresponds to an index from index_extents in simenv_put_ f c input lt model gt mdf integer 4 return code simenv_slice_ 0 ok fic 1
325. r 4 int single run number simenv_run_char character 6 char 6 6 digit single run number string simenv_zero real 4 float auxiliary variable set to 0 The source code sequences are included in the model source code for Fortran by include lt model gt _f inc for C C by include lt model gt _c inc for Python by from lt model gt _py import for the model interface at shell script level by SE_WS lt model gt _sh inc for the model interface at ASCII level by SE_WS lt model gt _as inc Examples can be found in Example 15 2 and Example 15 12 Saat Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y ff ua J ji _ 59 5 11 Supported Model Structures SimEnv supports performance of lumped distributed and parallel models Information about model structure is specified in the model configuration file lt model gt cfg cf Section 10 1 by the sub keyword structure Lumped standard models are normally represented by one stand alone executable A distributed model in SimEnv consists from a web of stand alone sub models i e the model dynamics are computed by perform ing a set of stand alone sub models that normally interact with each other and exchange information For a parallel model each single run of an experiment needs a set of assign processors Lumped standard models use in the common sense SimEnv model interface functionality For dist
326. r Experiment description for the examples general descr in the SimEnv User Guide general type LSA factor Toul descr parameter pl factor pl unit without factor pi type add factor pl default il EEO CONIC p2 type relative PACE Ons p2 default 2 TECTO L PS type relative TECTO p3 default SS specific incrs lret 001 0 01 005 01 Example file world edf_LSA Example 6 7 Experiment description file lt model gt edf for LSA 6 7 Bayesian Technique Bayesian Calibration BAY_BC Tab 6 10 Experiment specific elements of an edf file for BAY_BC z Max Keyword Name k er Mie line Value Explanation eyword type nmb factor lt factor_ sample m 1 distr prior distribution to generate a name gt lt distribution gt representative sample of val ues lt factor_smp_val gt given the information defined in lt model gt bdf sample _ 0 1 lt real_val 41 gt lower bounds lt real_val gt and include lt real_val 2 gt upper bounds lt real_val i gt of eer intervals to include for sam lt real_valn1 gt pling according to distribution lt real_val 2 gt lt distribution gt lt real_valj gt lt lt real_valj2 gt sample _ o 1 lt real_val gt lower bounds lt real_val gt and exclude lt real_val 2 gt upper bounds lt real_vali2 gt of Patas intervals to exclude from sam lt real_valm gt pling according to distribution lt real_valm2 gt lt distribution gt lt real_valj gt lt lt real_val gt
327. r defined files entities cf also Section 11 1 length of a record in a user defined file characters 160 length of all general descriptions descr characters 512 length of a local description descr characters 128 length of a unit characters 32 length of aname characters 20 user defined and composed operators in lt model gt odf number 27 TAR l 190 y H Es f Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 F Maximum amy entity value length of all define strings for a macro or a composed operator characters 512 values in a value list number 5000 length of a record of a referred ASCII data file characters 1 024 Model interface and experiment preparation entities single model runs in an experiment number 999 999 experiment factors number 100 model output variables number 100 dimensionality of a model output variable for all but Java models g dimensionality of a model output variable for Java models 4 coordinates number 100 coordinate values and sampled factor values number 200 000 active slices during performance of a model number 30 storage size of a float real 4 model output variable for GAMS models Mbytes 64 Experiment post processing entities length of the optional result description string characters 128 length of the optional re
328. r of columns per line is checked and missing columns are added as nodata values In contrast simenv_put_as_simple just applies a simple Fortran read statement per expected line without any checking routines Due to its extensive in terpretation efforts simenv_put_as is rather slow As a rule of thumb simenv_put_as_simple should be used for file with more than 2000 columns where one can trust in the file structure An example can be found in Section 15 2 12 5 10 Semi Automated Model Interface Source code manipulations of a model for interfacing it to SimEnv can be classified into four parts e Initialization apply simenv_ini_ and simenv_get_run_ e Factor adjustments apply simenv_get_ e Model output apply simenv_slice_ and simenv_put_ e End apply simenv_end_ Often Initialization and Factor adjustments can be lumped together in a source code sequence where the factor adjustment part has to be updated when new factors are defined in an experiment description file and have to be mapped to model internal factors the first time Contrarily Model output and End are often distributed in the model source code but do not change so often Recognising this situation SimEnv offers beside the standard hand coded model interface a semi automated model interface Initialization and Factor adjustments are generated automatically during experiment preparation as sequences of source code based on the current exp
329. ral APPrOaCH eissor e a ei EV eria Eaa E Ea Pes E N AEAT 13 4 2 Global Sensitivity Analysis Elementary Effects Method GSA_EE ssesreieerirsrsirssrriresrirrrerrsnrsenns 16 4 3 Global Sensitivity Analysis Variance Based Method GSA_VB ceccsceeeseeeeeeeenteeeeeneeeetneeeenenaeeeeeenaeees 19 4 4 Deterministic Factorial Design DFD 00 0 2 cece cceccecc cece ceeeee ce eect ee cece aeae ee eeeeeeceeeaeceeeeeseceneaeeeeeeeseseeeeeeeeeeeeeeea 22 4 5 Uncertainty Analysis Monte Carlo Method UNC_MC ssesissssiiesiiiissrissriiiesiinresrinnriirnsinitenrinneernnnenrnnnt 24 4 6 Local Sensitivity Analysis LSA ciesccccoscicecceecteeesseneuesvocnaae steed oveusdensdoscseassenteesaeeedvees cecnseancesteceeeedeneeedeuaneesnare 26 4 7 Bayesian Technique Bayesian Calibration BAY _BC 0 ec eeeeeeeeeeeeeeeeeneeeeeeaeeeeeneeeeesaeeeseeaeeeenneeeene 28 4 8 Optimization Simulated Annealing OPT_SA eee eeesseeeeteeeeeenneeeeeeeeeeeeaeeeeeeaeeeeneeaeeesneeeesenaeeeeneeeees 30 5 MODEL INTERFACE 5 1 General Approach 5 2 Coordinate and Grid Assignments to Variables eee ccceeeeeeceeeeeneeeeeeeeeeeeeaeeeeeeaaeeeeeeeaeeesneeeenenaeeeennaeees or 5 3 Model Output Description File lt model gt Mdf 0 00 eecceceecceeeeeeeeeeeeneeeeeeeeeeeeaeeeeeeaeeeseneeeeeesaeeeeeeaeeeeneeeeneaa of 5 4 Model Interface for Fortran and C C Models 0 2ceccecececeeeeeeeeeaeeeeeeeeeeneaeceeeeeeeceneaeeeeeeeseseeeaeaeeeseeeeea 40 5 5 Model Interfa
330. rcase representation and this lowercase representation is used also for model and or experiment post processor output files in NetCDF IEEE and or ASCII format Tab 10 12 Case sensitivity of SimEnv entities Where Entity E Example sensitivity overall e model name sensitive simenv chk World f user defined files e keyword insensitive experiment END RUN last cf Section 11 1 e name e sub keyword e information lt value gt insensitive xperiment nd_run LAST general descr This is model interface e variable and factor name insensitive iok simenv_put_f ATMO atmo atmo factor name P1 factor value 1 SSE _HOME bin simenv_get_sh Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Where Entity ea Example sensitivity experiment e optional result description sensitive Energy kW my_opr atmo post processing and unit e character arguments sensitive char _test argll Arg21 of user defined operators atmo e variable and factor name __ insensitive 3e 6 exp atmo e operator name 3E 6 EXP ATMO e number e macro name e macro identifier _m e character arguments insensitive count ALL atmo of built in operators with pre defined values cf Tab 15 10 e character arguments check get _ table fct MyFile dat of built in operators Tab 15 10 atmo with
331. real value x V xi Z Xi x conditional residual variance of Z when fixing X to any x where uppercase X and Z indicate random variables lowercase x and z values of a random variable and the subscript X stands for all but X An Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y ff ua J ji 19 As the real value x of factor X is unknown consider instead the average residual variance Exi V xi Z Xi x average residual variance of Z that can be obtained when fixing X The smaller this value the more influential is factor X It always holds Exi V xi Z X x lt V Z Taking into account the variance decomposition rule for conditional distributions V Z Vxi E xi Z X x Exi V_xi Z X Xx fabbr V E Z Xi E V ZIX main effect of XonZ residual Dividing the above equation by V Z results in Si 1 E V ZIX V Z 1st order sensitivity index V E Z X V Z e 0 1 S indicates by how much V Z would be reduced on average if factor X could be fixed The larger S the more influential is factor X In parallel 2 x Xk can be developed in a high dimensional model representation HDMR Rabitz et al 1999 of 2 terms as 2 X4 eee Xk Zo z DLZt 0 De LZmigt i tZik 1Si lt j lt lt m lt S Sk with Zo constant Zi zi Xi Zij Zi Xi X Zm s Zm s Xms Xs Z4 k Z4 k X1 pees Xk This decomposit
332. real_val gt explicit list of values same syntax rules as for one record of a file with a value list see above by reference file lt directory gt lt file_name gt file lt directory gt lt file_name gt contains the explicit value list implicit equidist_end lt real_val gt lt real_val2 gt lt real_vals gt description of an equidistant list with of values with begin element begin value lt real_val gt increment increment lt real_val gt end element end value lt real_val3 gt lt real_val gt lt real_val3 gt lt real_val gt 0 Number of resulting values have to be gt 1 implicit equidist_nmb lt real_val gt lt real_val2 gt lt int_val gt description of an equidistant list with of values with begin element begin value lt real_val gt increment increment lt real_val gt number of values number of values lt int_val gt lt real_valo gt 0 lt int_val gt gt 1 PETH 174 y HN an J i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Value list type Syntax Explanation implicit equidist_ivl lt real_val gt lt int_val gt lt real_val gt description of an equidistant list with of values with begin element begin value lt real_val gt number of values number of values lt int_val gt end element end value lt real_ val a gt lt int_val gt gt 1 lt int_val gt 2 values are placed within the interval be
333. responding model interface coupling functions simenv_put_ in the model Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Tab 10 9 Built in model output variables Built in Dimen model output _ Extents Data type Meaning f sionality variable name sim_time 0 float elapsed user time in seconds when perform ing usr bin time p lt model gt run Tab 10 10 lists the built in pre defined shell script variables that are defined used by the model coupling interface dot scripts SE_HOME bin simenv_ _sh and simenv_run_ mathematica gams and that are fi nally available in lt model gt run Tab 10 10 Tab 10 11 lists the built in pre defined coordinates that are used in experiment post processing when addi Built in shell script variables in lt model gt run Built in shell script variable name Meaning simenv_run_int current run number as integer simenv_run_char current run number as 6 character string with leading zeros factor_name factor name for simenv_get_sh factor_def_val default nominal factor value for simenv_get_sh simenv_hlp auxiliary variables tional dimensions are generated by an operator Tab 10 11 Built in coordinates for experiment post processing peers tae Generated Dy operator meamng A ak 1 16 bin_mid hgr bin mid values equidist_en
334. result expression There are two wildcard operands at disposal amp v amp wildcard operand for any model output variable amp f amp wildcard operand for any experiment factor When applying in a result expression only one wildcard type i e either amp v amp or amp f amp the result expression is performed repetitively where the wildcard is replaced successively by all model output variables and experi ment factors respectively When applying both amp v amp and amp f amp in a result expression the result expression is performed for the Cartesian product of all model output variables and experiment factors Wildcard operands must not be used in macro definitions cf Section 8 6 The wildcard operand amp v amp for model output variables cannot be restricted to a portion of the variable by appending a sub specification in brackets as explained in Section 8 1 3 e g amp v amp i 3 10 is not allowed S aA Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H ba f j 147 Note that the strings amp v amp and amp f amp are only substituted in the result string by model variables and or model factors if they are e prefixed b b begin of result string and e postfixed l 1 end of result string Having a model output variable definition as in Example 5 1 on page 40 and assuming the experiment description file DFD_b from Example 6 5 on page 75 then
335. rg1 arg2 assign new coordinates to arg2 advanced Tab 8 8 113 rng_e arg1 run ensemble range UNC_MC Tab 8 13 130 max_e arg1 min_e arg1 round int_arg1 arg2 round value arg2 to int_arg1 decimal places basic Tab 8 4 109 run char_arg1 arg2 values of arg2 for a single run selected by advanced Tab 8 8 113 char_arg1 run_info char_arg1 current run number and or number of single advanced Tab 8 8 113 runs of the current experiment sens_abs char_arg1 arg2 absolute sensitivity measure loc sens Tab 8 14 133 sens_rel char_arg1 arg2 relative sensitivity measure loc sens Tab 8 14 133 sign arg1 sign of value basic Tab 8 4 109 sin arg1 sine basic Tab 8 4 109 sinh arg1 hyperbolic sine trigonom Tab 8 4 109 skw_e arg1 run ensemble skewness 3 moment UNC_MC Tab 8 13 130 sqrt arg1 square root trigonom Tab 8 4 109 stat_full real_arg1 full basic statistical measures UNC_MC Tab 8 13 130 real_arg2 real_arg3 real_arg4 arg5 stat_red real_arg1 reduced basic statistical measures UNC_MC Tab 8 13 130 real_arg2 arg3 sum arg1 argument sum of values aggr mom Tab 8 5 110 sum_e arg1 run ensemble sum UNC_MC sum_lI char_arg1 arg2 dimension related argument sums of values of aggr mom Tab 8 7 112 na oa SI Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012
336. rguments are set to 999 as well Tab 8 20 summarizes these SimEnv operator interface functions that can be applied in the computational part written in Fortran or C C postfix f for Fortran c for C C to get and check argument values and put results In this table the input and output data types are documented for functions used in Fortran For C C the corresponding data types are valid Implementation of the functions for C C is based on a call by ref erence for the function arguments To handle real 4 underflow and overflow during computation of the operator results with real 4 argument values it is advisable to compute operator results temporarily as real 8 values and afterwards to transform these values back to the final real 4 operator result by the function simenv_clip_undef_ f c ar ea Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H ba f j 141 Tab 8 20 Operator interface functions to get check put arguments and results Function Function ee Inputs outputs function value name description f SB description unction value Functions to get and check argument values and to put results in the computational part simenv_ get value of a non integer 4 argument number get_arg_ character argu iarg fic ment with index input index integer 4 vector index of an argument iarg index index input real 4 v
337. ributed models each of the sub models can use SimEnv model interface functionality i e simenv_get_ simenv_get_run_ simenv_put_ or simenv_slice_ In each sub model with SimEnv model interface functionality simenv_ini_ and simenv_end_ calls have to be incorporated in Sub models can be implemented in different programming languages Additionally the corresponding SimEnv model interface functionality at shell script level simenv_ _sh dot scripts can be applied As usual the overall model is wrapped into a shell script lt model gt run cf Chapter 7 The model output description file lt model gt mdf collects all the model output variables from all sub models and the experiment description file lt model gt edf collects all the factors from all sub models Announce a distributed model to the simulation environment if e More than one sub model uses SimEnv model interface functionality by the simenv_ _ functions and e Sub models get factor data from and put model output data to SimEnv data files in parallel A distributed model where the sub models are performed sequentially one by one in a cascade like manner can run in standard mode SimEnv interfaced sub models of a distributed model can reside on different machines The only prerequisite is that the current workspace and the model output directory can be mapped to each of these machines k To perform a parallel model within SimEnv simply use the same approach for wrapping
338. riment gt a 24 y H an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Tab 4 3 Statistical measures for an UNC_MC experiment N number of Monte Carlo runs Z1 Zn Z17 Z1y Z27 Z2y are realizations of state variables z z1 and z2 resp N N indices for sums amp products and extremes run from 1toN X IT min max function i 1 f i 1 N i 1 N Statistical measure Definition minimum min z min zi maximum max Z max zi sum sum z z arithmetic mean avg z z N variance var z z avg z N 1 skewness skw z z avg z N var z kurtosis krt z z avg z f N var z 3 range rng z max z min z geometric mean avgg z Iliz ye harmonic mean agvh z N X 1 Izi weighted mean avgw z Lz w lw w weight cor z1 z2 z1 avg z1 z2 avg z2 correlation V z1 avg z1 z2 avg z2 covariance cov z1 z2 z1 avg z1 z2i avg z2 N 1 linear regression coefficient E 4 2 z1 avg z1 i z r avga ji to forecast z2 from z1 z1i avg z1 It is Z2 reg z1 Z2 z1 avg z2 reg z1 z2 avg z1 error median med z middle value from increasingly ordered z N odd mean of the two middle values from z N even qnt z that
339. ription files in Tab 6 1 on page 63 is defined for a DFD experiment as follows Tab 6 7 Experiment specific elements of an edf file for a DFD experiment Max Sub Line Keyword Name keyword type line Value Explanation nmb factor lt factor_ sample a 1 lt val_list gt value list of factor samples name gt lt factor_smp_val gt for syntax see Tab 11 6 specific lt nil gt comb m 21 default information how to scan the lt combination gt spanned factor space file lt directory gt lt file_name gt strict nonstrict To Tab 6 7 the following additional rules and explanations apply For the description of line type check Tab 11 4 on page 171 For sub keyword comb the following rule holds value default lt combination gt for used sub keyword sample value file lt directory gt lt file_name gt for unused sub keyword sample Values of a value list have to be unique for used sub keyword sample and each factor Assigned values from file lt directory gt lt file_name gt can be multiple defined for each factor The sequence of the single runs is determined by the sub keyword comb 6 4 1 Formalisation of the Inspection Strategy Run Sequence The combination lt combination gt defines the way in which the space spanned by the experiment factors will be inspected by SimEnv This is done by concatenating all stated
340. rmat SimEnvVis does not belong to the standard SimEnv distribution It can be obtained from the SimEnv developers on request Analysis and evaluation of post processed data selected and derived from large amount of relevant experi ment output benefits from visualization techniques Based on metadata information of the post processed experiment type the applied operator chain and the dimensionalities of the post processor output pre formed visualization modules are evaluated by a suitability coefficient how they can map the data in an ap propriate manner The visualization modules offer a high degree of user support and interactivity to cope with multi dimensional data structures They cover among others standard techniques such as isolines isosurfaces direct volume rendering and a 3D difference visualization techniques for spatial and temporal data visualization These techniques are accompanied by parallel coordinates graphical table and scatterplot matrixes techniques Furthermore approaches to navigate intuitively through large multi dimensional data sets have been ap plied including details on demand interactive filtering and animation Using the OpenDX platform OpenGL and Ferret visualization techniques have been designed and imple mented suited in the context of analysis and evaluation of derived multi run output functions Currently visual experiment evaluation is the only SimEnv service that comes with a graphical user inter
341. rpret lt val_range gt i as a range of position indices always count from 1 for self and seli S as a range of sampled increment values for seli n as a range of factor names sequ as in lt model gt edf for self as a range of signs for sels lt factor_val_range gt lt val gt lt val2 gt for lt val gt lt nil gt lt val gt lt valy gt use all values from lt factor_name gt lt val gt lt int_val gt for lt val_type gt i lt val gt lt real_val gt for lt val_type gt s lt val gt lt factor_name gt for lt val_type gt n self lt val gt and lt val gt lt nil gt for lt val_type gt n sels The following rules hold for the filter argument in the LSA operators e Generally by the filter argument char_arg1 those runs from the run ensemble are selected here inter preted as filtered that are used for the formation of the result Consequently if no filter is specified all runs are used sens_abs atmo_g The filter operator has to be specified only if values are to be restricted by corresponding factor values increment values and or sign ranges e For the above three select operators self seli and sels the factor value type is redundant if the factor value range represents the full range of values by self seli sels self self_n self i and all are redundant e Each select operator can be applied only once within the filt
342. run e g by deleting non SimEnv temporary or output files Make sure that in lt model gt rst e 6 bin sh is the first line e SE_HOME bin simenv_ini_sh is performed always and as the first SimEnv dot script e SE_HOME bin simenv_end_sh is performed always and as the last SimEnv dot script cf Tab 5 8 on page 53 and Example 7 6 below Make sure that lt model gt rst has execute permission by the Unix Linux command chmod u x lt model gt rst After running SE_HOME bin simenv_get_run_sh the shell script variables simenv_run_int and simenv_run_char are available in lt model gt rst cf Tab 10 10 Terminal output from lt model gt rst is re directed to the log file lt model gt nlog RE Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji 95 Experiment restart works without standard SimEnv experiment preparation Instead experiment prepa ration files and other information from the interrupted experiment will be used For a restart the optional experiment preparation shell script lt model gt ini will be performed only on demand This request is specified in the configuration file lt model gt cfg with the sub keyword restart_ini and its value yes For Python Java Matlab and GAMS models interfaced to SimEnv lt model gt ini has to be performed mandatorily Consequently the value of restart_ini has to be set to yes cf Sections 5 5 1 and 5
343. run number for lt model gt run rst of a single run Value lt simenv_run_int gt SE_RUN1 first single run for lt model gt run rst of an experiment Value yes no To perform SimEnv make sure that paths to the directories of the programs as specified in Tab 10 15 below are included in the environment variable PATH Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Tab 10 15 Programs to include in the environment variable PATH Program Usage Include in PATH python python interpreter mandatory ncdump dump NetCDF files mandatory gams GAMS modelling system optional only for running GAMS models java Java optional only for running Java models matlab Matlab interpreter optional only for running Matlab models MathKernel Mathematica interpreter optional only for running Mathematica models Additionally PATH is prefixed by SE_WS see Tab 10 14 above internally by all SimEnv services Keep in mind to specify a PYTHONPATH environment variable dependent on interfaced Python models PY THOMPATH is prefixed by SE_WS and SE_HOME bin is appended to PYTHONPATH internally by all SimEnv services For linking and running Fortran and C C models and operators the environment variables PATH and LIBRARY_PATH have to be defined accordingly Aa 168 y H a J en Multi Run Simulation Environment SimEnv User Guide for Versio
344. s BAY_BC Bayesian calibration gt Experiment type to reduce uncertainty about gt factor values by deriv ing a representative gt sample from factor prior distributions while having measurement values from the system available for gt model measurement comparison For uncertainty analysis and reduction with a Bayesian technique Coordinate coord Each gt dimension of a gt variable and each gt operand of an gt operator in a gt result with a gt dimensionality greater than 0 a coordinate is assigned to A coordinate has a unique name and strictly monotonic ordered coordinate values The number of coordinate values corre sponds to the gt extent for this dimension Consequently each model output variable with a di mensionality greater than 0 resides at an assigned multi dimensional gt grid Assignments for variables is done in the model output description gt user defined file Coupling gt model interface Cron daemon The cron daemon runs gt shell commands at specified dates and times Crontab The gt Unix gt Linux crontab command submits edits lists or removes jobs for the gt cron dae mon Data type The type of a gt variable as declared in the gt model and the corresponding model output de scription gt user defined file SimEnv data types are byte short int float and double Default value The nominal standard numerical value of an gt experiment gt factor The default value is sp
345. s In Jezowski J Thullie J eds 19 European Symposium on Computer Aided Process Engi neering ESCAPE19 June 14 17 2009 Cracow Poland Elsevier lt IOE Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f i _ 185 Sobol I M 1967 Distribution of points in a cube and approximate evaluation of integrals U S S R Comput Maths Math Phys 7 86 112 Sobol I M 1976 Uniformly distributed sequences with an additional uniform property U S S R Comput Maths Math Phys 16 236 242 Sobol I M 1993 Sensitivity analysis for non linear mathematical models Mathematical Modelling and Computational Experiment 1 407 414 van Oijen M 2008 Bayesian calibration BC and Bayesian model comparison BMC of process based models Theory implementation and guidelines NERC Centre for Ecology and Hydrology http nora nerc ac uk 6087 1 BC 26BMC_ Guidance 2008 12 18 Final pdf Waszkewitz J Lenzen P Gillet N 2001 The PINGO package Procedural interface for Grib formatted objects Max Planck Institute for Meteorology Hamburg and http www mad zmaw de Pingo pingohome html Wenzel V Kucken M Flechsig M 1995 MOSES Modellierung und Simulation kologischer Systeme PIK Report No 13 Potsdam Institute for Climate Impact Research Potsdam http www pik potsdam de research publications pikreports summary report no 13 Wenzel V Matthaus E Flechsig
346. s VARIABLES or PARAMETER The maximum dimensionality of a SimEnv model output variable used in a GAMS model is restricted to 4 Additionally each model output variable must not exceed a size of 64 MByte With respect to Example 15 9 the model output description file could look like coordinate plant descr canning plants coordinate plant uale plant number coordinate plant values couniiaiis tiendi i 1 2 coordinate market descr canning markets coordinate market unit market number coordinate market values Scmaichisic Gime dl al s variable a descr plant capacity variable a unit cases variable a type float variable a coords plant variable a index extents 1 2 _ Ea Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji _ 51 variable x descr shipment quantities variable x unit cases variable x type float variable x coords plant market variable x index extents 1 2 7 Les variable Z descr total transportation costs variable Zz unit MOLO RUSS variable Z type float variable modstat descr model status variable modstat type FILO Example file gams_model mdf Example 5 4 Model output description file fora GAMS model 5 7 3 Files Created during GAMS Model Performance Additionally to the files listed in Tab 10 8 during the performance of a GAMS model the files lt gams_model gt _ pre main post inc are created temporarily in the current
347. s a sequence of white spaces Sequence of keyword and sub keyword lines can be arbitrary For reasons of readability it is recommended to use a block structure like in the Example 11 2 below Sequence of names in the separated name spaces name spaces of coordinates model output variables experiment factors user defined operators macros during processing is determined by the sequence the name occur the first time in the appropriate user file Lines consisting only from separator characters as well as lines starting with a as the first non separator character are handled as comment lines For case sensitivity of the contents of user defined files check Tab 10 12 on page 165 aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f i _ 169 Tab 11 1 User defined files with general structure File Contents Reece as cripion in Section on page lt model gt cfg general configuration file 10 1 451 lt model gt mdf model output description file 51 33 lt model gt edf experiment description file 6 1 63 lt model gt odf operator description file 8 5 4 145 lt model gt mac macro description file 8 6 146 lt model gt gdf GAMS description file Drz 48 arbitrary file name coordinate transformation file 112 171 The following restrictions hold for user defined files Tab 11 2 Constraints in user defined files with the exception for GAMS model
348. s for performing simenv run and simenv rst First and last single run always refer to the corresponding settings in lt model gt cfg eA TAG S 98 J HN ia i i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 7 7 Saving Experiments To save experiments for later use e g by SimEnv experiment post processing make sure to store the files listed in Tab 7 2 Tab 7 2 SimEnv files to store for later experiment post processing File name Remark Mandatory from the model output directory lt model gt out all lt simenv_run_char gt nc ieee Mandatory from the current workspace lt model gt cfg do not modify the information as signed to the keyword model lt model gt mdf do not modify all information including lt model gt edf the sequence of the model output variables and or experiment factors lt model gt smp lt model gt fct for UNC_MC with stopping rule BAY_BC and OPT_SA lt model gt blog for BAY_BC Optional from the curren t workspace lt model gt elog lt model gt mlog lt model gt nlog lt model gt _ dis par seq aix linux jcf lt model gt bmlog for BAY_BC lt model gt olog for OPT_SA lt model gt opt_sa_options txt for OPT_SA Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN ua J
349. saaeeeseeaeeeenneeeneaa ZL Generic SimEnv interface functions cccccececcece cece eeecee ance cnet eeeeaaaeaeceeeesaaaeaeeeeeeesecaeaeeeeeeesasenaeeaeeeeeees 34 Language suffices for SimEnv interface FUNCTIONS eee ee enee ee eeee eter states eeeeaeeeseneeeeeeaeeeseeaeeeenneeeeneaa 35 Elements of a model output description file lt model gt mdf ccccececeeeececceceeeeeeeeeeeeeeeeseseeeaeaeeeeeeeseeaaes 38 SimEnv data types eccere e ea E ea ee tesa cb e oa een Aa aaa E Ea AAA a E EAT 39 Model interface functions for Fortran and C C Models c cc eeeeeeeeeeeeeeeeeneeeeeenaeeeeeneeeeesaeeeeeenaeeeennneeeenaa 41 Model interface modules methods functions for Python Java and Matlab models s e 43 Elements of a GAMS description file lt model gt gdf eee ee eee eeenee erent ee eeenaeeeeetaeeeseneeeeesaeeeeeenaeeeenneeeeneaa 49 Model interface functions at shell script level cccecceceeeeeeeeeee cece ee eeseeeaeeeeeeeeeeseceneaeaeeeeeseseeceeeeeeeeeeees 53 Model interface functions at ASCII level ccccceceeeceee cence cece ee eeee eases seen seceaeaeeeeeeeeeceneaeeeeeeeseeeneeeeeeneeeeeea 55 Built in variables by simenv_mod_auto_ f C J iNC c cece cececeecee cece ee ee cece ae ee ee esse seceaeaeeeeeeeseceesaeeeeeeseeeeeea 59 Elements of an experiment description file lt model gt edf for all experiment types eeeeeeeteeeeereeeeees 63 Factor adjustment types in experiment preparation
350. scription simenv_ initialize model string py return code ini_ py ja m coupling interface int ja m 0 ok simenv_ini_ Perform always function value as the first SimEnv function in the model Check the semi automated model interface for al ternatives simenv_ get the resulting string name of the factor in lt model gt edf get_ py ja m adjusted value for factor_name the factor to be input factor_name experimented with float default nominal factor value as specified in factor_def_val input lt model gt edf If factor_name is not defined in lt model gt edf then factor_adj_val is set to factor_def_val float simenv_get_ function value adjusted factor value factor_adj_val If an error occurred then function value 999 99 simenv_ get the run number string current run number as string of the length 6 with get_run_ of the current run simenv_get_run leading zeros py ja m as a string Ba If an error occurred then function value function value simenv_ output model string name of the variable in lt model gt mdf to be output put_ py ja m results to native var_name SimEnv output input var_name file s declaration of data of variable var_name to be stored as simula field field tion results according to lt model gt mdf input string py return code int ja m 0 ok simenv_put_ function value
351. sen tu sis ootenah fa setecgenn vues Shes deeds vebench su iateedgesteeemsciadseeieoes 171 Example 11 2 Coordinate transformations by a transformation fil eee eeeeeeeeeeneeeeeeeeeeenneeeeeeaeeeeeeeaaeeeeneeeene 173 Example 11 3 Examples of Value lists scania ainaiset aaia aaite E faai 175 Example 12 1 IEEE compliant model output data structure ccccccccecececcee cece ee eeceeeaeeeeeeeeeseeaaeaeeeeeeeseeeeeaeeeeeeeentaes 180 Example 15 1 Model interface for Fortran models model world_f f c ec eeeseceeeeeeeeeeeeeeeeeeeaeeeeeeeeeeeseeeeseenaeeeeeeeaeess 196 Example 15 2 Semi automated model interface for Fortran models model world_f_ uto f ee eeeeeeeeeeeeeeeee 197 Example 15 3 Model interface for C models model WOrld_C C eeeeceeeeeeeeee eee eeeeeeeeeeeeaeeeenteeeeeeaeeeeeeneeeeenneeeeneaa 199 Example 15 4 Model interface for C models model world _Cpp Cpp ceeeecceeeeeneeeeeeeeeeeeeneeeeeenaeeeseenaeeeenneeeeneaa 201 Example 15 5 Model interface for Python models model world_pPy py ccccceceeeeeeceeceeeeeeeeeeeaeeeeeeeseseesaeeeeeeeees 202 Example 15 6 Model interface for Java models model World_ja jaVa eee eeeseeeeeeeeeeeeenneeeeeeeeeeseenaeeeenneeeeee 203 Example 15 7 Model interface for Matlab models model World_1 M c ccecceceeeeeeeeeeeeeeeeeseeeeeaeceeeeeseseesaeaeeeeeees 204 Example 15 8 Model interface for Mathematica model shell script lt MOd
352. sional variables are equipped with indices in the simulation model they also have an index description in the model output description file for purposes of experiment post processing It is advisable that these two descriptions coincide The index range is de scribed by a start and an end integer value index lt in_valj gt and or lt in_val_extj2 gt The index set is a strictly increasing equidistant set of integer values with an index increment of 1 lt in_valj gt lt lt in_valio gt lt in_val gt lt 0 is possible e Coordinate values lt co_val gt and index values lt in_val gt are assigned in a one to one manner e For multi dimensional variables that do not exist on an assigned grid completely or partially simply as sign formal coordinate axes to e Specify at least one model output variable in lt model gt mdf Tab 5 4 SimEnv data types Sime ny data type Description Restriction synonyms byte int 1 1 byte integer not for Python and Java models short int 2 2 bytes integer not for Python and Java models int int 4 4 bytes integer float real 4 4 bytes real double real 8 8 bytes real not for Python and Java models For the following Example 5 1 of a model output description file and the assigned grids for model output vari ables check Example 1 1 on page 6 general descr World with a resolution of general descr 4 lat z AD lon z general descr 4 levels x 20 time ste
353. sponding GAMS model file lt model_name gt gms The value field for the sub keyword put is adapted to GAMS syntax to output GAMS model output variables Afterwards this output is used to generate the appropriate SimEnv output lt index_set gt is mandatory for variables with a dimensionality gt 0 Otherwise specification of lt in dex_set gt is forbidden Indices as used in the GAMS model are separated from each other by comma With respect to Example 15 9 the GAMS description file could look like general descr GAMS model output description general descr for the examples in the SimEnv general descr User Guide general keep runs list Op i model gams_model descr this is the only GAMS model to use model gams_model type main model gams_model get dem_ny model gams_model get dem_ch model gams_model put eI aL 3 1055 model gams_model put ai al SOs model gams_model put BIL model gams model put modstat Example file gams_model gadf Example 5 2 GAMS description file lt model gt gdf If the model gams_model from the above Example 5 2 would be coupled with two additional GAMS sub models sub_m1 and sub_m2 where both sub models interact with SimEnv the GAMS description file could look like without taking into consideration plausibility with respect to model contents model gams_model type main model gams_model put modstat model sub_ml type sub model submi get dem _ ny model sub m
354. ssessing any model Tab 4 1 SimEnv experiment types Expenmeni Description type GSA_EE Qualitative ranking of a large number of factors with respect to their sensitivity on Global sensitivity model output derived from statistical measures of local elementary effects at ran analysis domly selected trajectories in the factor space elementary For determination of the most important factors effects method GSA_VB Identify contribution of each factor to the variance of the model output Global sensitivity For determination of most important factors and those factors that can be fixed at analysis any value over the range of uncertainty without significantly modifying the output DFD Inspection of the model s behaviour in the factor space by a discrete numerical Deterministic factorial design sampling with a flexible inspection strategy for sub spaces For model verification numerical validation deterministic error analysis determi nistic control design scenario analysis and spatial patch model applications UNC_MC Factor space sampling by perturbations according to probability density functions Uncertainty Determination of moments confidence intervals and heuristic probability density analysis functions for state variables in the course of experiment post processing Monte Carlo For error analysis uncertainty analysis verification and validation of deterministic method models LSA Determi
355. ssigned to an additional dimension is the name of the corresponding factor Coordinate description and coordinate unit cf Section 5 1 on page 33 are associated with the corresponding information for the factor from the experiment description file Coordinate values are formed from adjusted factor values For strictly ordered factor sampled values in the experiment description file and finally for strictly ordered factor adjusted values the coordinate values are ordered accordingly in an increasing or decreasing manner Unordered factor sampled values and finally unordered factor adjusted values are ordered in an increasing manner for coordinate usage The result of the operator dfd is always arranged according to ascending coordinate values for all addi tional dimensions Independently from the declared sequence of the applied aggregation and select operators in argument 1 of the operator dfd the factors that contribute to additional dimensions of the result of the operator dfd are appended to the dimensions of the operand arg2 of dfd according to the sequence they are used in the normalized see Section 6 4 1 comb line of the experiment description file From parallel changing factors that factor is used in this sequence that is addressed explicitly or implicitly by the select operator For experiment factors that are changed in the experiment in parallel that increase dimensionality of the result and where a select operator is missing the first
356. ssing operator get_data and coordinate transformation file e The operator get_experiment is to access to external SimEnv experiment output from the same or an other model performed with the same or another experiment type and stored in the same or in an other model output format Model output variables can differ from that used for the current model Use for the experiment directory char_arg1 always that workspace the external experiment was started from The external experiment is always post processed completely over all single runs Argument char_arg3 is the coordinate transformation file It can be used to transform coordinates from the external result for usage in the current result of the current experiment If no coordinate transformation file is to be used argument char_arg3 is empty If after potential application of a coordinate transformation file the imported re sult has same coordinate names as defined in the original experiment coordinate descriptions are checked against each other otherwise coordinate descriptions are imported from the external into the original experiment For syntax of coordinate transformation files check Section 11 2 For restrictions in the path to the directory of the character arguments char_arg1 and char_arg3 check Tab 11 3 Attention Make sure e that no SimEnv service is running from the directory char_arg1 of the external experiment before applying this operator e to have full access permissions to
357. sult unit string characters 32 arguments of an operator number 9 dimensionality of a result 9 length of a complete result string with optional description and unit characters 1024 all operands and operators of a result number 200 length of a character argument of an operator characters 124 length of a string for a constant characters 20 constants of a result number 30 user defined and composed operators number 35 allocatable main memory segments for computing a result number 10 total allocatable main memory MBytes 2 048 results in a NetCDF post processor output file number 99 post processor output files number 99 15 1 3 Linking User Models and User Defined Operators e User models implemented in C C or Fortran have to be linked with the following libraries to interface them to the simulation environment e SE_ HOME lib libsimenv a e libnetcdf a from usr local lib or usr lib e User defined operators to be used in experiment post processing have to be linked with the following library to interface them to the simulation environment e SE_HOME lib libsimenv a For running interfaced models outside SimEnv check Section 5 12 i a Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H i f ji 191 15 1 4 Example Models and User Files For the following models corresponding files of Tab 10 7 of can be copied from the corresponding exam ples directory SE_HOME exa to
358. sults of the real system For deterministic error analysis to analyse how the model error is dependent on factor errors For a simulation based control design to determine factor values in such a way that a goal function becomes an extreme aaa S 22 y HN E i Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 x X212 sample of size 12 in the 2 dimensional factor space X2 X1 X2 o X21 default nominal numerical factor constellation of model M x4 Fig 4 5 Sample for a Deterministic Factorial Design DFD SimEnv sampling strategy for DFD is a generalization of the one dimensional case for X4 where the model behaviour is scanned in dependence on deterministic sample of one factor x4 The general case for X de mands a strategy for scanning m dimensional spaces in a flexible manner Based on the predecessors of SimEnv Wenzel et al 1990 Wenzel et al 1995 Flechsig 1998 subspaces of the m dimensional factor space can be scanned on the subspace diagonal parallel in a one dimensional hyperspace or completely for all dimensions combinatorially on a grid and both techniques can be combined Besides this regular scanning method an irregular technique is possible The resulting number of single simulation runs for the experiment depends on the number of factor samples per dimension of the scanned factor space and from the selected scanning method An experiment is
359. t latest lt simenv_res_char gt to visualize output from the latest post processing session world_ lt Ing gt res lt simenv_res_char gt nc or that with number lt simenv_res_char gt with the highest two digit number lt simenv_res_char gt e Start simenv dmp world_ lt Ing gt mod more simenv dmp world_ lt Ing gt res more to dump a SimEnv model or post processor output file Check in the current workspace the model interface log file world_ lt Ing gt mlog native model terminal output log file world_ lt lIng gt nlog experiment performance log file world_ lt Ing gt elog Start simenv cin world_ lt Ing gt to wrap up a simulation experiment Get the usage of any SimEnv service by entering the service command without arguments To run other simulation experiments and or output in other data formats modify world_ lt Ing gt cfg world_ lt Ing gt edf world_ lt Ing gt mdf world_ lt Ing gt run and or world_ lt Ing gt lt Ing gt To experiment with other models replace world_ lt lng gt by lt model gt as a placeholder for the name of any other model The visualization framework SimEnvVis of SimEnv does not belong to the standard SimEnv distribution At PIK for visualization set the DISPLAY environment variable accordingly To get access permission for the PIK visualization server check in Section 10 2 on page 155 the SimEnv service simenv key lt user_name gt
360. t lt real_valj gt lt lt real_vali2 gt sample _ 0 1 lt real_val 41 gt lower bounds lt real_val gt and exclude lt real_valj2 gt upper bounds lt real_vali2 gt of TETE intervals to exclude from sam lt real_valm gt pling according to distribution lt real_valm2 gt lt distribution gt lt real_val gt lt lt real_val gt specific lt nil gt levels m 1 lt int_val gt number of levels to span up a p level grid in the factor cube that is composed from equi distant quantiles for each factor p 2 4 even trajectories m 1 lt int_val gt number of trajectories r to position randomly at the p level grid r25 seed o 1 random fixed method how to initialize the random number generator To Tab 6 5 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e The jump width A in the corresponding quantile space is optimally selected as A p 2 p 1 check Section 4 2 e Fora grid with p levels the i th level i 1 p corresponds to the 1 2 i 1 2 p quantile Consequently level 1 is the 1 2 p quantile and level p is the 1 1 2 p quantile For p 4 the quantiles are 1 8 3 8 5 8 7 8 For p 6 the quantiles are 1 12 3 12 5 12 7 12 9 12 11 12 Keep in mind that distribution tails are cut by this approach In particular for a factor with a uniform dis tribution the upper bound and the lower bound
361. t char lt predef_coordinate_description gt lt predef_variable_description gt lt factor_description gt lt variable_description gt lt result_applied_operator_sequence gt Snr S 178 y H Es J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Name Value Data type lt variable_name gt units lt coordinate_unit gt char lt predef_coordinate_unit gt lt predef_variable_unit gt lt factor_unit gt lt variable_unit gt lt result_unit gt lt variable_name gt missing value lt variable type depending missing value gt type dep lt variable_name gt axis X Y Z T bin_no run char single coordinate variables only lt variable_name gt coordinates lt par1_lon gt lt par1_lat gt char multi dimensional coordinate variables only lt variable_name gt _Fillvalue lt variable type depending fill value gt type dep For experiment post processor output the standard_name attribute simply counts the number of ap plied operations because the result name of an arbitrary operation is not Known in general For that rea son the long_name attribute would re sample the standard_name attribute and it is used instead to provide the complete description of the applied operator sequence without defining an additional attrib ute If macros are included these are resolved and elementary operations are included
362. t cfg Tab 10 8 lists the temporary or permanent files that are created during a SimEnv service Tab 10 8 Files generated during performance of SimEnv services For the current workspace SE_WS see Tab 10 14 mua Generated in Explanation location Permanent files lt model gt smp SE_WS experiment preparation all but OPT_SA BAY_BC experiment performance OPT_SA BAY_BC ASCII sample input file for the run ensemble de rived from lt model gt edf Record no n 1 corresponds to single run no n Column no m of each record is the sampled value for experiment factor no m in the edf file lt model gt _ f c sh as inc and lt model gt _py py SE_WS experiment preparation if auto_interface no in lt model gt cfg ASCII include files dot scripts for semi automated model interface lt model gt out lt simenv_run_char gt nc ieee model out_directory experiment performance if out_separation yes in lt model gt cfg model output of run number lt simenv_run_int gt of the experiment to be processed by the experiment post processor lt model gt outall nc ieee model out_directory experiment performance if out_separation no in lt model gt cfg model output of all runs of the experiment to be processed by the experiment post processor lt model gt elog SE_WS experiment performance ASCII minutes file of experime
363. t quantiles q Gp These quantiles vary in 0 1 and the corresponding individual factor values in the factor space follow their own distributions In the corresponding k dimensional factor quantile space QXx this results in a regular equidistant grid e Specify in the factor quantile space QX a unique jump width A as a value from 1 p 1 2 p 1 p 2 p 1 The jump width specifies how far away in terms of equidistant quantiles another point is se lected from an existing grid point to compute an elementary effect as described below In the factor 16 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 space X the unique jump width A transforms for each factor x to values Aim where m corresponds to the value of x of the existing grid point e Select at the p level grid in the factor space randomly a starting grid point x X1 Xk and randomly another grid point x X1 p Xi 1 XitAim Xiet a Xk that differs from x in exactly one factor x by Aim i 1 K e Compute from these two grid points the elementary effect of the factor x for the model state variable z by d x Z 2 X4 jen LA 4 Xi Aim 5 Xie gey Xx E 2 X4 peed Xx Aim e Proceed by randomly selecting a new grid point x to the previous grid point x for another elementary effect dj x z i4j until k 1 points xX a X are sampled Such a series of k 1 points is called a trajectory For one trajectory
364. t Processor Output 00 ees eeeeseeeeeteeeeenneeeeeeneeees 181 13 SIMENV PROSPECTS igs since iiaeie castactnrssacegssisbccdedsade eceascte rO A POEP I ONE COMAE Shi aea A aE S EEan Naaa ane SEEEN iaga 183 14 REFERENCES AND FURTHER READINGS 0 00 eeccceeeeeneeeeeeeeee ee eaeeeseeeaeeeeaeeeeesaeeeseeaaeeesneeesesaeeeseenaees 185 15 APPENDICE Sisaria tsoro nA rr E a OE aE Oa sentences Ore aO O E AE N 187 15 1 Version Implementation ccccccecceceeeeeeeeeee cece ee ceeeeaeceeeeee ee ceaaaeaeceeeeesaaaaeaeceseeeseeneaeeeseeeeeaaeaeeeeeeeeeeeaes 189 15 1 1 SYSTEM REQUIFCMOMS sesini a eaaa Gagees E aA EA EATE E EAA E EE aaaea 189 15 1 2 Technical Limitations a a a a a E a A E aN E e 190 15 1 3 Linking User Models and User Defined Operators seesseeeriissssiissrriiesiiireeirsntrirnsiirnsiinneerrnnnrnnnnt 191 15 1 4 Example Models and User Files 00 ccceeescceceesneeeeeeeeeeeeaeeeeeeaaeeeceeeaeeesaeeeeesaaeeeseeeeeeeesneeeesenaeeeeeaeees 192 15 1 5 Example User Defined Operator c ccci ceeseessceecoceeeescees evendees eveeteesedeedeenseensedseccecesseneeeeenenseeeenidendeteedee 194 15 2 Examples for Model Interfaces cccccccccceecceceeeeeeeeeaeeeceee eee eaaeaeceeeeesqaaeaeceeeeeseeeaeaeeeeeeeseeceeaeeeeeeeeeeeaes 195 15 2 1 Example Implementation of the Generic Model World eeescceeeesceeeeeeeeeeeeneeeseeeeeeeeneeeensaeeeseeaeees 195 15 2 2 Fonran Model aa sate acres Sacra cca ca secant chess anaes Adie seca a
365. t Sade teueavaynsdstoea testes emia aeetsarentresntadee 196 15 2 3 Fortran Model with Semi Automated Model Interface ee eeseceeeeeeeeeceeeeeeeneeeceeeeeesneeessenaeeeeeeeaees 197 15 2 4 oTo e A A E A E A E deeaded peucdeentracdeehue ne peeaedaapeeg eee 198 15 2 5 CHE MOC a a E A E E E T 200 15 2 6 Python Modeli ser csper iian aE aae eaS a bear it e a EA aaea 202 15 2 7 Java Model creeren toane en rera EEE r EEEE raaa ra E 203 15 2 8 Matlab Modelinin aaa ea cia oea aa sates CE aA S Ea R eE 204 15 2 9 Mathematica Model rrisin n AEE EENE EE 205 15 2 10 GAMS M gd l iaiiaeeeai ani ai e iiri iaeiaiai 206 15 2 11 Model Interface at Shell Script Level 2 c cc eccesecceseseceneeseseeeneseeceesseeneeesseeeseasiceeessnersesseeeeeteertense 208 15 2 12 Model Interface for ASCII Files ccccccceceeececene cece ee eeeeeaaeaeeeeeeesceaeaeeeeeeeeecaeaeeeeeeeseeensaeaeeeeeeesanaeees 209 15 2 13 Semi Automated Model Interface at Shell Script LeVel oo eee eeeeeeeeeeeeeeeneeeeeetaeeeeeneeeeeenaeeeeseaas 210 15 3 Example Implementation for the Experiment Post Processor User Defined Operator matmul_ f c 211 15 3 1 Fortran lim Plememtarth Oi sae sasesea ceices seticacsiee ca ie of araea eaae a e Era ye sscenea sate o a chinese 21i 15 3 2 C lmplO mentation isere iascwaceedseceasatss cacpedecctasaneeessascccenacaschesuot PE a Ea a oa EEE CEO aaa PAES eO reh Iia 214 15 4 Example for an Experiment Post Processor Result Import Interface
366. t SimEnv User Guide for Version 3 01 July 10 2012 for the model interface at shell script level file lt model gt _sh inc SE_HOME bin simenv_ini_sh SE_HOME bin simenv_get_run_sh factor_name x factor_def_val 0 SE_HOME bin simenv_get_sh factor_name x factor_def_val 0 SE_HOME bin simenv_get_sh for the model interface at ASCII level file lt model gt _as inc SE_HOME bin simenv_ini_sh SE_HOME bin simenv_get_run_sh SE_HOME bin simenv_get_as The sequence of factors in the code sequences corresponds to the sequence of factors in the experiment description file lt model gt edf For the Fortran C C model interface e a model link file lt model gt Ink can be declared in the current workspace to link the model anew using the generated code sequences in the course of experiment preparation only for service simenv run not for service simenv rst e the variables simenv_sts simenv_run_int simenv_run_char and simenv_zero are defined in the model source code include file simenv_mod_auto_ f c inc cf Tab 5 10 Additionally the functions simenv_ ini get get_run put slice end _ f c are declared by simenv_ mod_auto_ f c inc as integer 4 int functions Tab 5 10 Built in variables by simenv_mod_auto_ f c inc without declaration of interface functions Variable Data type Used for simenv_sts integer 4 int SimEnv interface function value simenv_run_int intege
367. t in or user defined operators Like built in and user defined operators a composed operator can have nine formal arguments at maximum Sequence of these arguments is also the same as for the other operators Character arguments followed by integer constant arguments real constant arguments and normal arguments For composed operators the operand set cf Section 8 1 2 to form the operator by a chain of operators is restricted to e Constants in integer and real float notation e Character strings e Operator results from built in and user defined operators Not allowed as operands are e Model output variables e Experiment factors e Composed operators e Macros Additionally have to be used e Formal arguments arg1 arg9 aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f i _ 143 Check the following example how to specify composed operators composed operator name rel_count error_1 error 2 composed operator definition KO OMENS ountanrg Panoz Coume alli area countekarnrg Paor is honar mMOoOron ONAR arog iik aaa oin wiel y 10 0r Oa yergi Having a model output variable definition as in Example 5 1 on page 40 then for example the operator rel_count can be applied by Tel conne Cder boros rel counti der biog c 20 20 7 1 rel_ count undef 100 bios Example 8 15 Composed operators Composed opera
368. t model gt bmlog is generated during experiment performance It lists individual likelihood functions for each setting and or each likelihood function Likelihood function numbers correspond to the sequence of the likeli hood functions as defined in lt model gt bdf Compared to lt model gt blog this file lists also the candidate point likelihoods for rejected points As the model is not run for outranged candidates the file can not supply infor mation for such candidates m pa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji ua _ 83 6 7 3 Multiple Setting Likelihood Function Case The general idea behind this case is to derive the posterior distribution as a representative sample by taking into account several settings of a unique model rather than run the model only for a single setting The latter is the standard case of SimEnv in terms of the model calls per SimEnv single run for each single SimEnv run the model is performed once only In contrast for the multiple setting case each single SimEnv run cov ers all model runs of the individual settings Model settings may differ in their calibration e g for site condi tions if a model is considered to run at a local regional scale While the result part of the likelinood func tion s is are unique for all settings the data part differ s among the settings In other words setting related likelihood functions are composed for eac
369. t must not be a arg1 them undefined that belong multi run operator to single runs of type this is NOT a rejected multi run operator bay_bc_run_weight mask all values of arg1 set 1 argument must not be a arg1 them undefined that belong multi run operator to single runs of type rejected and weight arg1 of unmasked values values that this is NOT a belong to single runs of type multi run operator accepted or reflected same as for see Section 8 4 5 see Section 8 4 5 see Section 8 4 5 UNC_MC The following explanations hold for the operators in Tab 8 16 As discussed in Section 6 7 2 for points in the MCMC chain that are marked as outranged in the file lt model gt blog a single simulation run is not performed Consequently they are not available from ex periment output For the multiple likelinood function case check Section 6 7 3 only the run ensemble from an individual setting can be post processed Individual setting experiment outputs are stored in subdirectories s_ lt setting number gt of the model output directory as specified in lt model gt cfg Please adapt lt model gt cfg accordingly Operators bay_bc_run_weight and bay_bc_run_weight Both operators are not multi run post processing operators By definition such operators can be applied outside a multi run operator is an argument to the operator as well as inside the operator is an argu ment of a mu
370. t processing morris max atmo importance measures p and o for max atmo for the four defined factors Dimensionality 2 Coordinates factor_sequ stat_measure Extents 4 2 geile eig plain Gllsiio Yr i l morris maz latmne ranks the importance measure p rank 1 for the most important factor for max atmo for the four defined factors Dimensionality 1 Coordinates factor _sequ Extents 4 bs Example file world post_GSA_EE Example 8 8 Experiment post processing operators for GSA_EE na 9 124 SHEL Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 8 4 3 Global Sensitivity Analysis Variance Based Method GSA_VB Tab 8 10 Experiment specific operators for GSA_VB Name Meaning Argument restriction s result description Tab 8 1 page 106 Argument value restriction effects_ st arg1 first order sensitivity indices of arg1 6 dim res dim arg1 1 ext res dim res number_of_factors coord res dim res name factor_sequ values equidist_end 1 1 number_of_factors arg1 must not contain strings enclosed in effects_tot arg1 total effect sensitivity indices of arg1 6 dim res dim arg1 1 ext res dim res number_of_factors coord res dim res name factor_sequ values equidist_end 1 1 number_of_factors arg1 must not contain strings enclosed in
371. tely or partially disjoint coordinate sys tems 5 3 Model Output Description File lt model gt mdf In the model output description file lt model gt mdf the model output variables are declared that are to be out put by a SimEnv model coupling interface function in the model code and are to be post processed after experiment performance Additionally coordinate axes are defined and flexibly assigned to model output variables Consequently a model output variable always is defined on a coordinate system formed from the assigned coordinates to the variable AF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y ff ua J i _ 37 Tab 5 3 Elements of a model output description file lt model gt mdf Sub Line Ma Keyword Name k line Value Explanation eyword type nmb general lt nil gt descr 0 any lt string gt model output description coordinate lt co_name gt descr o 1 lt string gt coordinate axis description unit 0 1 lt string gt coordinate axis unit values m 1 lt val_list gt strictly monotonic sequence of coordinate values lt co_vals gt for syntax see Tab 11 6 variable lt variable_ descr oO 1 lt string gt variable description name gt unit 0 1 lt string gt variable unit type m 1 see Tab 5 4 variable type in the simulation model coords c1 1 lt co_name gt assigns a coordinate axis by ses its name to each dimension
372. teral and vertical level fluxes and demands that s why for computing state variables for all grid cells However in the model gridcell_f state variables are calculated for each grid cell without consideration of lateral fluxes Model implementation in a programming language lt Ing gt results in a model world_ lt Ing gt puesto Description Defined on DEEN state variable type atmo aggregated atmospheric state lat x lon x level x time float bios aggregated biospheric state at lat x lon x time float land masses defined between 84 N and 60 S latitude at land masses i e without Antarctic atmo_ aggregated global state time int not for model gridcell_f derived from atmo for level 1 bios_g aggregated global state int not for model gridcell_f derived from bios Dynamics of all model variables depend on model parameters p1 p2 p3 and p4 With this SimEnv release the following model implementations are distributed Model Model Resolution auto in name interface 3 Ss example for lateral vertical temporal semi automated ana ani clings lat x lon number of number of modelinterrace guay g deg x deg levels time steps world_f Fortran 4x4 4 1 7 11 16 20 world_c C 4x4 4 1 7 11 16 20 world_cpp C 4x4 4 1 7 11 16 20 world_py Python 4x4 4 1 7 11 16 20 world ja Java 4x4 4 1 7 11 16 20 world_m Matlab 4x4 4 1 7 11 16 20 world_sh Shell script
373. th same dimensionalities and extents to have same coordinates e Neither coordinate names nor coordinate values for corresponding dimensions are checked Coordinate description of the appropriate operator result is delivered from its first non character non constant operand Check Example 8 3 for examples Having a model output variable definition as in Example 5 1 on page 40 then the checking rules for coordinates are applied in the following manner to operands with dimensionality 1 Same coordinates for Result expression coord_check strong weak without bios atmo c 84 56 c l same coordinate names same coordinate values yes Jes yee armo Gl nge Moan mo 20 0 0 aime differing coordinate names same coordinate values no yes YES atmo g c 6 16 atmo g c 8 18 same coordinate names differing coordinate values us he big atmo g c 20 atmo c 0 c 2 c 1 c 1 two operands with dimensionality 0 us es ye While determination of coordinate information is unique for coord_check strong coordinate information is determined by the first summand for coord_check weak without Example 8 3 Checking rules for coordinates S IAF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN i f ji 107 8 2 Built In Generic Standard Aggregation Moment Operators The generic operators in Tab 8 2 can be applied durin
374. the experiment directory char_arg1 S aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H ba f j 117 e the experiment directory char_arg1 differs from the current workspace In the experiment directory a file simenv_get_experiment exc is used to exchange information be tween the external and the current experiment With the operator get_table_fct a table function is applied to each element of the operand arg2 If nec essary table values are interpolated linearly Outside the definition range of the table function the first and or the last table value is used File char_arg1 has to hold the name of the table function file It must be an ASCII file with two columns The first column is the argument value x associated with the elements of the operand arg2 the second column is the function value f x of the table associated with the ele ments of the operator result Argument values x have to be ordered in a strictly increasing manner Syn tax rules for comments and separators in the table function file are the same as for user defined files cf Section 11 3 For restrictions in the path to the directory of the character argument char_arg1 see Tab 11 3 Check the table function world dat_adv in the example directory SE_HOME exa of SimEnv for more information The operator if supplies a general conditional if construct It operates for each element of the operand arg2 in the following way if co
375. the log file lt model gt nlog For running an interfaced model outside SimEnv there are dummy SimEnv libraries to link run the model with They ensure the same model dynamics as before interfacing the model to SimEnv cf Section 5 12 zA 34 y HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Currently there are SimEnv interfaces for Fortran C C Python Java Matlab Mathematica and GAMS models Additionally there is an interface implementation at shell script level and for ASCII files Mixed lan guage models as well as distributed models cf Section 5 11 can be run with SimEnv Tab 5 2 Language suffices for SimEnv interface functions for the Mathematica interface check Section 5 6 for the GAMS interface check Section 5 7 lt Ing gt For model source code c C C f Fortran py Python ja Java m Matlab as ASCII file m g AE Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y ff ua J ji 35 Description Files Experiment description file lt model gt edf Model output description file lt model gt mdf factor edf_factor type Las variable mdf_var type factor Q default sis variable coords ii factor specific info variable index_extents Model Model wrapper shell script lt model gt run associate description file entity with source code entity For transp
376. the previ ous experiment start restart e SE_HOME bin simenv_ini_sh has to be performed al ways and as the first SimEnv dot script simenv_ _sh e SE_HOME bin simenv_end_sh has to be performed always and as the last SimEnv dot script simenv_ sh e SE HOME bin simenv_get_run_sh can be used optional lt model gt ini model shell script to prepare simulation experiment addition ally to standard SimEnv preparation e Experiment will be not performed if return code from this shell script is unequal 0 e For experiment re start lt model gt ini will be performed only on request optional for Python Java Mat lab and GAMS models mandatory lt model gt end model shell script to clean up simulation experiment from non SimEnv files optional Files lt model gt err lt simenv_run_char gt touch such a file in lt model gt run and or in lt model gt rst as an indicator to stop the complete experiment after single run lt simenv_run_int gt has been finished optional lt model gt killed lt simenv_run_char gt generated from SE_HOME bin simenv_kill_process in lt model gt run as an indicator that a process exceeded the specified CPU time limit and was killed optional lt model gt _ dis par seq _ aix linux jcf model specific job control file to submit an experiment in dis tributed parallel and or sequential sub mode by the load lev eler LoadL e Copy from S
377. the shell the noclobber option is not set Tab 10 14 Environment variables Environment z Definition Meaning Explanation variable status SimEnv access settings Set by the user Used within all SimEnv services SE_HOME SimEnv home direc mandatory Value has to be defined by the user tory For values check Tab 3 3 and Tab 15 1 Optionally include SE_HOME bin into the PATH environment variable to access to a SimEnv ser vice without prefixing it by SE_HOME bin DISPLAY machine screen optional Value machine dependent that the X11 system has to be defined at PIK by the user only for visu uses for displaying alization matters in SimEnv services simenv res windows and simenv vis Internal settings Set automatically by SimEnv Set within all SimEnv services SE_BAY_BC__ setting number of provided by SE_HOME bin simenv_bay_bc_sh SETTING the multiple setting within lt model gt run for experiment type BAY_BC case Value lt int_val gt gt 0 SE_GUI identifier for GUI for all SimEnv services non GUI version Value yes lt nil gt SE_HN generic hostname for all SimEnv services Value hostname without domain SE_MOD model name for all SimEnv services Value lt model gt SE_OS operating system for all SimEnv services specification Value AIX LINUX SE_WS current SimEnv for all SimEnv services workspace Value lt directory gt SE_RUN
378. the strategy of a selected experiment type for a set of so called factors x which represent pa rameters initial or boundary values or drivers of a model Ma numerical sample is generated before simula tion This sample corresponds to a multi run experiment with the model During the experiment for each sin gle simulation run the factors x are adjusted numerically according to the sample and the factors default nominal values Each experiment results in a sequence of model outputs for selected state variables z of the model M in the space of all addressed factors X Experiment output as the set of all model outputs can be processed and evaluated after simulation generally on the state space and experiment type specifically on the factor space The following experiment types form the base of the SimEnv multi run facility e Global sensitivity analysis elementary effect method Qualitative ranking of a large number of factors x with respect to their sensitivity on model output at ran dom trajectories in the factor space X For determination of the most important factors e Global sensitivity analysis variance based method Identify contribution of each factor to the variance of the model output For determination of most important factors and those factors that can be fixed at any value over the range of uncertainty without significantly modifying the output uncertainty e Deterministic factorial design Inspection of the model s beha
379. the user s current workspace by running the SimEnv service command simenv cpy lt model gt from this workspace Tab 15 4 Implemented example models for the current version For the generic model world check Example 1 1 model Pete PE Ted Explanation source code world_f Fortran world_f f world_c C world_c c world_cpp C world_cpp cpp world_py Python world_py py world_ja Java world_ja java world in Matlab global atmosphere biosphere model wont nt at resolution of lat x lon x level x time 45 x 90 x 4 x 20 world_sh Shell script level world_sh f world_shput f world_as ASCII interface world_as f world_f auto Fortran semi automated model interface world_f_auto f world_sh_auto Shell script level world _f 05x05 f semi automated world_sh f model interface world_shput f world_f_1x1 Fortran global atmosphere biosphere model world_f_1x1 f at a resolution of lat x lon x level x time 180 x 360 x 16 x 20 world_f 05x05 Fortran global atmosphere biosphere model at a resolution of lat x lon x level x time 360 x 720 x 16 x 20 gridcell_f Fortran atmosphere biosphere model for one lat lon grid cell gridcell_f f at a resolution of level x time 4 x 20 gams_model GAMS GAMS example model gams_model gms rn m 192 y H Es f J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Ad
380. tivity measures for 6 arg1 argument arg dim res dim arg1 2 ext res dim res 1 number_of_factors coord res dim res 1 name factor_sequ values equidist_end 1 1 number_of_factors ext res dim res 2 coord res dim res name stat_measure values equidist_end 4 1 5 same as for see Section 8 4 5 see Section 8 4 5 see Section 8 4 5 UNC_MC The following explanations hold for the operators in Tab 8 10 e The operator morris appends two additional dimensions to the dimensionality of its argument The first corresponds to the factors and the second to the derived statistical measures According to the coordi nate values as described above the second additional dimension has the extent 2 and according to Tab 10 11 the first index of this dimension holds the averages yu and the second index the variances o to describe the importance of the corresponding factors The sequence of the factors in the appended fac tor dimension corresponds to the sequence of the factors in lt model gt edf e This experiment type allows to post process the whole run ensemble as an UNC_MC experiment Keep in mind that generally the sampled factor points do not follow a pre defined distribution as they form spe cial designed trajectories in the factor space Having a model output variable definition as in Example 5 1 on page 40 Assume the experiment description file GSA_EE from Example 6 3 on page 70 then in resul
381. to be specified An experiment is described by the factors involved in the analysis their distribution and the appropriate distribution parame ters Optionally a stopping rule is helpful to limit the number of simulation runs in an experiment In a stopping rule statistical measures from model output z of all performed single runs are calculated during the experi ment after each single model run to decide whether to stop the whole experiment SimEnv supplies a simple rule of thumb stopping rule from Schuyler 1997 using the standard error of mean statistic y var z N with N number of already performed single runs and checks it against the mean avg z 4 6 Local Sensitivity Analysis LSA Local sensitivity analysis LSA uses a deterministic sampling strategy in e neighbourhoods of the numerical default constellation X of the model M For each value x from the default nominal factor constellation X and each sj from the e neighbourhoods 4 Em two members X1 Xi 1 XitEj Xi 1 Xk Of the resulting sample are generated The sample size n is given by 2 m k Running the model for this sampling set serves to determine sensitivity functions In classical systems theory model sensitivity of a model state variable z with respect to a factor x is the partial derivative of z after x z x In the numerical simulation of complex systems a finite sensitivity func tion is preferred because it can be obtained without m
382. to compare the influence of different factors x on the same state variable z while due to their normalization factor the relative measures enable comparison of the influence of one factor x on different state variables z m A Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji ua _ 27 From the local measures of table Tab 4 5 additional measures can be derived on demand e g abs sym_abs z A LSA experiment is described by the names of the factors x to be involved and the increments The num ber of runs for the experiment results from the number of factors and increments two runs per factor for each increment plus one run with the default nominal values of the factors Local sensitivity functions are calculated during experiment post processing 4 7 Bayesian Technique Bayesian Calibration BAY_BC Bayesian calibration is a method to reduce uncertainty about model factors using Bayesian techniques The basic approach is to qualify given marginal prior probability density function pdf X of the factors X by deriv ing a representative sample This is achieved by taking into account a vector of individual measurement values represented by their averages avg and their accompanied measurement errors expressed as vari ances vary They are measured from the real system that correspond to individual elements of state vari ables model output z X results from the model F
383. tor Operator Computational algorithm how to transform the values of a sequence of gt operands into the val ues of the operator result during gt experiment post processing An operator transforms gt dimen sionality gt extents and gt coordinates from the operands into the corresponding information for the operator result There are built in elemental basic and advanced operators as well as built in operators related to specific gt experiment types Additionally SimEnv offers specification of user defined operators according to an operator interface User defined operators are announced to the system in the operator description gt user defined file OPT_SA Optimization Simulated Annealing gt Experiment type to minimize a cost function objective function over a bounded gt factor space In SimEnv a simulated annealing strategy cf Section 4 7 for explanation is used to optimize the cost function that is formed from model gt variables Of ten the cost function represents a distance between model output and reference data to find an op timal point in the factor space that fits best the model behaviour with respect to the reference data Parallel Operating Environment gt POE POE The Parallel Operating Environment POE from IBM supplies services to allocate nodes assign jobs to nodes and launch jobs on a compute cluster Probability density function pdf A probability density function serves to represent a probab
384. tors are checked syntactically by the SimEnv service simenv chk When performing simenv chk validity of the following information is not cross checked between formal arguments e Character arguments of operators Example The composed operator error_1 is considered by simenv chk to be valid though argument 1 of operator count is limited to values all def undef and argument 1 of operator hgr is limited to values bin_no bin_mid e Use of normal formal arguments in the operator chain with respect to their dimensionality extents and coordinates Example The composed operator error_2 is considered by simenv chk to be valid though the dimensionality of the operator hgr in this constellation is always higher than that of the argument arg1 and consequently multiplication between arg1 and hgr is impossible Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 8 5 4 Operator Description File lt model gt odf lt model gt odf is an ASCII file that follows the coding rules in Section 11 1 on page 169 with the keywords names sub keywords and values as in Tab 8 21 lt model gt odf announces the user defined and composed operators by their names and the number of character integer constant real constant and normal argu ments that belong to an operator Additionally lt model gt odf hosts for composed operators the corresponding operator chain using formal
385. two C C or Fortran functions cf Tab 8 18 e Function simenv_check_user_def_operator This is the declarative part of the operator The consistency of the non character operands can be checked with respect to dimensionality dimensions and coordinates as well as the values of character arguments can be checked Dimensionality extents and coordinates of the result have to be defined normally in dependence on the argument information e Function simenv_compute_user_defined_operator This is the computational part of the operator In the computational part the result of the operator in de pendency of its operands is computed Tab 8 18 Operator interface functions for the declarative and computational part Inputs outputs function value Function Function name description Inputs outputs function value description Functions to host the declarative and computational part in usr_opr_ lt opr gt f c cpp simenv_ check consistency integer 4 return code check_user_ of operator argu simenv_ 0 ok def_operator ments and defines check_user_ 0 inconsistency between operands dimensionality and def_operator dimensions of function value result simenv_ compute result of real 4 output compute_user_ the operator in res len_res result vector of the operator def_operator dependency on integer 4 input operands len_res length of the result vector of the operator res integer 4 return code le
386. uence of all columns of all lines of this variable is according to the Fortran storage model cf Section 15 7 Glossary e Variables with the same first coordinate but with different coordinate extents variable sub keyword co ord_extents in lt model gt mdf have to be harmonised line by line The set of all lines is the union of all de fined coordinate axis values from all variables To ensure synchronisation across columns variable val ues for undefined coordinate values of a variable have to be output to the file as any real 4 float nodata placeholder lt nodata gt e The values of the ASCII file are interpreted as of type real 4 float They are transferred to SimEnv model output according to their defined data type If a real 4 float value is outside the definition range of the data type it is set to the SimEnv nodata element of this data type cf Tab 10 13 e f no coordinate is defined as the second argument the values of all zero dimensional variables are ex pected to be in the ASCII file Consequently the file can have only one record with data values e The shell scripts simenv_put_as and simenv_put_as_ simple differ in how to read each line of the ASCII file simenv_put_as handles the file as an ASCII data file defined in Section 11 3 with the exception that data files are not limited to 1000 characters Consequently a file can have comment and blank lines when transferring by simenv_get_as to SimEnv Additionally the numbe
387. un ensemble quantile of arg2 reg_e arg1 arg2 run ensemble linear regression coefficient to forecast arg2 from arg1 rng_e arg1 run ensemble range max_e arg1 min_e arg1 skw_e arg1 run ensemble skewness 3 moment stat_full real_arg1 real_arg2 real_arg3 real_arg4 arg5 run ensemble full basic statistical measures stat_red real_arg1 real_arg2 arg3 run ensemble reduced basic statistical measures sum_e arg1 run ensemble sum var_e arg1 run ensemble variance Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 15 5 2 Experiment Post Processor Built In Operators in Alphabetic Order arg general numerical argument int_arg integer constant argument 2 0 real_arg real float constant argument char_arg character argument Tab 15 9 Experiment post processor built in operators in alphabetical order UNC_MC operators are also applicable for all other experiment types Name Meaning Type See on page arg1 arg2 addition elemental Tab 8 3 108 arg1 arg2 subtraction elemental Tab 8 3 108 arg1 arg2 multiplication elemental Tab 8 3 108 arg1 arg2 division elemental Tab 8 3 108 arg1 arg2 exponentiation elemental Tab 8 3 108 arg1 identity elementa
388. uring experiment post processing feasibility of application of an operator on its operands is checked with respect to the coordinate description of the operands Different levels of this check are possible A default is established here For keyword postproc sub keyword factors_in_output Special model interface constellations may lead to a situation that all factor values are not stored in SimEnv model output This could happen when simenv_get_ was not used but another technique for getting factor values within the model If specifying factors_in_output as no adjusted factor values are derived from lt model gt smp and lt model gt edf For keyword postproc sub keyword display_values Enables display of a number of result values per result during experiment post processing For multidi mensional result output the first values according to the Fortran storage model cf Section 15 7 Glos sary are shown Set display_values to 0 to suppress this output For keyword postproc sub keyword visualization Specifies whether to directly visualize an entered result during experiment post processing Keep in mind to ensure consistency of control settings in lt model gt cfg across different SimEnv services As an example one has to run experimentation experiment post processing and dump with the same value for out_separation in lt model gt cfg Tab 10 3 lists the default values in the general configur
389. usted experiment factor values are logged All model output to the terminal is re directed within SimEnv to the experiment model native output log file lt model gt nlog e During experiment performance an experiment log file lt model gt elog is written with the minutes of the experiment e After the experiment has been finished an email is sent on demand cf Section 10 1 to the address as specified in lt model gt cfg e The status of any running experiment can be acquired by the SimEnv service simenv sts For more in formation check Tab 10 4 e Do not start restart submit another experiment from a workspace where an experiment is still running e For more information check Section 5 1 Fig 5 1 and Fig 7 1 aA Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y J ua J ji _ 89 7 2 Model Wrap Shell Script lt model gt run Experiment Specific Preparation and Wrap Up Shell Scripts e The model to be applied within the SimEnv experiment has to be wrapped in the shell script lt model gt run lt model gt run is performed for each single run within the run ensemble e Make sure that in lt model gt run e 6 bin sh is the first line e SE_HOME bin simenv_ini_sh is performed always and as the first SimEnv dot script e SE_HOME bin simenv_end_sh is performed always and as the last SimEnv dot script cf Tab 5 8 on page 53 and Example 7 1 below e Terminal output from lt
390. ut variable definition as in Example 5 1 on page 40 and assuming a data file mask dat as this file masks the variable atmo tropical Africa and Arabia level 2 last two decades 202 20 20560 7 19320 this is equivalent to Iys27 41esQ 2 1920 this is equivalent to C 208 20 c 203860 2 19320 Antarctica all levels and decades C G0s 8 a w amp this is equivalent to i Bsa a amp this is equivalent to C G02 88 1390 ised T820 then mask file mask dat atmo masks for atmo the above two regions with the declared levels and decades and unmask file mask dat atmo masks for atmo all but the two regions with the declared levels and decades Example 8 5 Experiment post processing operators un mask_file The operator matmul performs a simple matrix multiplication for 2 dimensional arguments arg1 and arg2 The operator move_avg performs a moving average operation successively for selected dimensions of the argument arg4 For a vector a a2 Alen the moving average of running length rl is a vector ma Maz Maen with elements 1 i marce a gt i aj gt wj j max 1 i rl 1 j max 1 i rl 1 Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y Ji i f i _ 119 where w are weights Value ma is averaged from the rl values a a ai n 1 Accordingly the first rl 1 values maj Maz Ma
391. utput e Entry in SimEnv description file available and corresponding function call in model source code missed and or unperformed A model entity that is defined in the corresponding experiment description file lt model gt edf as a factor and or in the model output description file lt model gt mdf as an output variable and where the correspond ing SimEnv functions in the model source code are missing can be addressed during experiment post processing They are completely undefined For IEEE SimEnv model output such a factor and or model output variable is set to its corresponding nodata value For NetCDF output the factor and or model output variable is not available from unde fined in the NetCDF file s A regular matching between the model output description file and the used SimEnv interface functions in the model source code as well as the above exceptions are reported to the interface log file lt model gt mlog cf Tab 10 8 Native model output does not influence performance of the model in SimEnv and there is no necessity to disable this output when the model is interfaced to SimEnv The user only has to ensure that for an experi ment control by the load leveler LoadL the outputs of different single runs do not conflict with each other Normally this can be ensured by performing each single run in a special run related sub directory cf Example 15 10 Native user model output to the terminal is redirected during the experiment to
392. v_SettingS txt cc ccceceeeeessecceeeseecceeeeeeeeeeneeeeensenseeensneneesnsneeesecensesseedensenseeese 151 Elements of a general model related configuration file lt model gt cfg eeeecsieerireriesrrireerrireerrenreren 152 Default values for the general configuration file ccccceeececeeeee cece ee eeeeeeaeeeeeeeseeeneaeeeeeeeeeeeneaeeeeeeeeeeeeea 154 SIMENV SOMVICES arnee aa aaa a Gob E a E aaa aa aa Eea aE a AER E EE AAA EERE ees 155 Shell scripts and dot scripts that can be used in lt model gt ini run end J ossee 157 SimEnv include files and link SCIiIPtS eee ee eeeeeeeeene eect teeter eeeeeeeeeaaeeeeeeaaeeeseeeeeeesaeeeeeeaeeeeeeeeeeenaeeeeseaaes 158 F o j j HN hyhy y Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab 10 7 10 8 10 9 10 10 10 11 10 12 10 13 10 14 10 15 11 1 11 2 11 3 11 4 11 5 11 6 12 1 12 2 12 3 12 4 15 1 15 2 15 3 15 4 15 5 15 6 15 7 15 8 15 9 15 10 15 11 15 12 15 13 Figures Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig 0 1 4 1 4 2 4 3 4 4 4 5 4 6 4 7 4 8 4 9 4 10 5 1 5 2 5 3 6 1 6 2 7 1 10 1 User files and shell scripts to perform any SIME
393. v_get_sh now shell script variable p_undef is available value of shell script variable p_undef is 9 9 9 SSE_HOME bin simenv_end_sh Example file world_sh run Example 5 5 Addressing factor names and values for the model interface at shell script level a 54 y HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 5 9 Model Interface for ASCII Files The SimEnv ASCII interface addresses constellations where e amodel expects factor names and their adjusted values in an ASCII file e model output is stored to ASCII files Tab 5 9 lists those SimEnv dot scripts and shell scripts that represent the ASCII interface They have to be applied in the model wrap shell script lt model gt run They can be used together with the interface at the shell script level cf Section 5 8 Tab 5 9 Model interface functions at ASCII level Dot shell Command Inputs Input output script name description outputs description SE_HOME bin get the names and ASCII file After performing simenv_get_sh the ASCII file simenv_ the resulting ad lt model gt as lt model gt as lt simenv_run_char gt contains all factor get_as justed values of all lt simenv_run_ names and resulting adjusted values in the form factors to be ex char gt lt factor_name gt lt factor_adj_val gt perimented with in output Sequence of the factor lines i
394. value from increasingly ordered zi quantile which corresponds to a cumulative frequency of N p 100 qnt z med z confidence interval enf z avg z tuna V var z N boundaries a probability of error tan significance boundaries of Student distribution heuristic probability density hgr z number of z with clasSmin lt Zi lt ClaSSmax ClaSSmin ClASSmax boundaries of equidistant classes Tab 4 4 summarizes those probability density functions that are pre defined in SimEnv for factors to be per turbed Additionally SimEnv offers to import random number samples in the course of experiment prepara tion Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 Tab 4 4 Probability density functions Distribution EAS Probability density function pdf Distribution parameters uniform U a b 1 a lower boundary pdf x bza if x e a b p upper boundary gt a pdf x 0 otherwise it is mean atb 2 standard deviation y b a 12 normal N u 0 2 u mean pdf x 1 exp oy o standard deviation gt 0 oV2n 20 lognormal L u 0 2 4 i 1 l pdf x exp Ine u ifx gt 0 o gt 0 XoN2m 202 pdf x 0 otherwise it is In x N u 0 exponential E mean gt 0 w odis Lo x ifx gt o H H pdf x 0 otherwise it is standard deviation xu The number of runs to be performed during an UNC_MC experiment has
395. viour in the factor space X by a discrete numerical sampling with a flexi ble inspection strategy for sub spaces For model verification numerical validation deterministic error analysis deterministic control design scenario analysis and spatial patch model applications e Uncertainty analysis Monte Carlo analysis Factor space X sampling by perturbations according to probability density functions Determination of moments confidence intervals and heuristic probability density functions for state variables in the course of experiment post processing For error analysis uncertainty analysis verification and validation of deterministic models e Local sensitivity analysis Determination of model state variable s z local sensitivity to factors x Is performed by finite difference derivative approximations from M For numerical validation purposes model analysis sub model sensitivity gt ulti Run Simulation Environment SimEnv ser Guide for Version 3 uly 10 e Multi Run Simulation Envi SimE U Guide for Version 3 01 July 10 2012 bey 1 e Bayesian technique Bayesian calibration Reduce uncertainty about factor values by deriving a representative sample from factor prior distribu tions while having measurement values from the system available for model measurement compari son For uncertainty analysis and reduction with a Bayesian technique e Optimization Simulated Annealing Determination of optimal fa
396. wer bounds lt real_val gt and include lt real_val12 gt upper bounds lt real_vali2 gt of eee intervals to include for sam lt real_valn 1 gt pling according to distribution lt real_valn2 gt lt distribution gt lt real_valj gt lt lt real_valj2 gt sample _ 0 1 lt real_val 41 gt lower bounds lt real_val gt and exclude lt real_val 2 gt upper bounds lt real_vali2 gt of CERF intervals to exclude from sam lt real_valm gt pling according to distribution lt real_valm2 gt lt distribution gt lt real_val gt lt lt real_vali2 gt specific lt nil gt seed o 1 random fixed method how to initialize the random number generator runs m 1 lt int_val gt number of runs per factor To Tab 6 7 the following additional rules and explanations apply For the description of line type check Tab 11 4 on page 171 For the sub keyword sample and reading the sample and the sub sample from a file sample file each record of the ASCII file must hold exactly two sample values where the first value is for the sample and second for the re sample For the other syntax rules for ASCII data files check Section 11 3 For the sub keyword run The number of resulting runs for experiment type GSA_VB is lt int_val gt k 2 where k is the number of factors to be investigated For all the other sub keywords check Section 6 1 1 on page 65 6 3 1 Run Sequence The sequence of the single simulation runs in the
397. will not be used as factor values for the resulting grid in the factor space e To ensure that trajectories do not have to share grid points the ratio between the number of available grid points p in a k dimensional p level factor cube and the r k 1 points of r trajectories has to be greater or equal than 3 p k 1 2 3 e For all the other sub keywords check Section 6 1 1 on page 65 S an Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y HN i J ji 69 6 2 1 Special Features in GSA_EE Run Sequence To ensure that the r trajectories optimally scan the gridded factor space the following approach is used for generating them e Select the first trajectory randomly e Assuming to have already determined raet trajectories e Then generate randomly 10 5 r rdet 1 potential trajectories and select from them as the trajectory gett 1 that one which has to the existing raet trajectories the maximum distance in the quantile space The sequence of the single simulation runs in the experiment is determined in the following manner loop over trajectories loop over successive sampling points of the trajectory trajectory point endloop endloop 6 2 2 Example general descr Experiment description for the examples general descr in the SimEnv User Guide general type GSA_EE IEGNO EOE pl descr parameter pl Factor pl unit without factor pl type set factor pl default i
398. x Linux com mand chmod u x lt model gt run ini end On 90 y HN an J J Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 For the shell script world_f run the following contents could be defined l bamni sihh perform always and as the first SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_ini_sh run the model world_f assuming a model return code 0 as an indicator to stop the whol xperiment for any reason Touch the file below in the current workspace SE_WS as an indicator to SimEnv for this if test ne 0 then SE_HOME bin simenv_get_run_sh touch SSE WS world_f err simenv_run_char fi perform always and as the last SE_HOME bin simenv_ sh dot script SSE_HOME bin simenv_end_sh Example file world_f run Example 7 1 Shell script lt model gt run to wrap the user model For the shell script world_ ini the following contents could be defined for Matlab the coarsed land sea mask is restructured additionally coarse 0 5 x 0 5 land sea mask from file land_sea_mask 05x05 in the current directory to a 4 x 4 resoluted land sea mask in file land_sea_mask coarsed in the current directory to use for all single runs land_sea_mask 4 4 rc_land_sea_mask Gae eow WOLE S saga yea Terion CoE 0 as an indicator not to start the experiment
399. xample compare with the experiment description file DFD_d from Example 6 5 below Combi nation is implicitly as comb p1 p2 Experiment description files DFD_b and DFD_d in Example 6 5 below describe the same experiment e To continue a combination lt combination gt at a following comb line end the current comb line by one of the operators kn o or e An explicit stated combination lt combination gt is normalized before running the experiment in the follow ing sense Segments of lt combination gt that are separated by the operator can be re arranged in an arbitrary order For example p2 p1 is equivalent to p1 p2 Factors that are scanned in parallel can be re arranged in an arbitrary order For example p4 p3 p2 p1 is equivalent to p3 p4 p2 p1 lt combination gt is rearranged in a way that factors are used in the sequence they are declared in the experiment description file For example if four factors are declared in the sequence p1 p2 p3 p4 then the explicitly stated lt combination gt p4 p2 p3 p1 is normalized to p1 p3 p2 p4 Normalisation does not influence the layout of the experiment The sequence of the single simulation runs in the experiment is determined in the following manner e For comb file lt directory gt lt file_name gt The sequence corresponds to the sequence of the sampled factor values in the file lt file_name gt e For comb lt combination gt with t
400. xists as an indica tor Keep in mind that for killed models normally the status of model output to SimEnv data struc tures may be undefined Sub processes of the killed model are not killed by the shell script simenv_kill_ process Check Example 7 4 e The user can define an optional model specific experiment preparation shell script lt model gt ini that is performed additionally after standard experiment preparation and before setting up a new experiment For experiment restart lt model gt ini is performed only on request cf Section 7 4 below e In lt model gt ini additional settings checks can be performed For return codes unless 0 from lt model gt ini the experiment will not be started e Terminal output from lt model gt ini is re directed to the log file lt model gt nlog e For Python Java Matlab and GAMS models lt model gt ini is a mandatory shell script with standard ized contents Check Sections 5 5 1 and 5 7 1 for more information e After the experiment has been finished the native model specific output from the experiment can be wrapped up with the optional model specific shell script lt model gt end e Terminal output from lt model gt end is re directed to the log file lt model gt nlog e For GAMS models lt model gt end is a mandatory shell script with standardized contents Check Sec tion 5 7 1 for more information e All of these three shell scripts have to have execute permission Ensure this by the Uni
401. xperiment post processing session is finished by entering lt ret gt or a sequence of white spaces instead of a result For case sensitivity of lt result gt check Tab 10 12 on page 165 lt result_description gt must not contain an apostrophe character lt result_unit gt characters and f belong to the syntax and are not part of the this document convention as defined in Tab 1 1 Result description and or unit together with the separator have to be specified in the first input line The result expression itself may follow at the following input line lt result_expression gt is a chain of SimEnv operators applied to model output variables and or reference data Can be continued on a new input line continue expression if the current input line ends on one of the operators P or or on the operand separator in operators White spaces are filtered out from the result expression string also from character arguments lt result_description gt or lt result_unit gt are used to describe the result in the corresponding result output file cf Chapter 12 For the case one of these entities is not specified SimEnv analyses the result expression For a result expression formed without any operator or only from one operator and using exactly one model output variable and or one experiment factor lt result_description gt and or lt result_unit gt is copied from the corr
402. xperiment type OPT_SA asa_out asa_usr_out only for experiment type SE_WS OPT_SA run lt simenv_run_char gt sub direct of SE_WS experiment performance only for Mathematica and GAMS models sub directory for Mathematica and GAMS model performance Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 File location Generated in Explanation lt model gt _ SE_WS pre main post inc experiment performance only for GAMS models auxiliary files lt model gt GAMS main and all interfaced sub models SE_WS lt model gt resO0 nc experiment post processing NetCDF representation of the current result for visualization during experiment post processing only for value yes of sub keyword visualization in lt model gt cfg EXC SE_WS simenv_get_experiment experiment post processing auxiliary file for operator get_experiment simenv_ tmp SE_WS all services auxiliary files Fig 10 1 sketches usage of main SimEnv user shell scripts and files in the course of model interfacing ex periment preparation and performance experiment post processing and visual evaluation of post processed results Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 lt model gt mdf lt model gt run lt model gt rst lt model gt ini lt
403. xt res dim res number_of_runs coord res dim res name run values equidist_end 1 1 number_of_runs krt_e run ensemble kurtosis 1 arg1 4 moment med_e run ensemble median 1 arg1 qnt_e run ensemble quantile of arg2 1 0 lt arg1 lt 100 real_arg1 real_arg1 quantile value arg2 reg _e run ensemble linear regression arg1 coefficient to forecast arg2 from 2 1 arg2 arg1 rng_e run ensemble range 1 arg1 max_e arg1 min_e arg1 skw_e run ensemble skewness 1 arg1 3 moment stat_full run ensemble full basic statistical 6 arg1 arg2 0 001 real_arg1 measures of arg5 dim res dim arg5 1 0 01 0 05 0 1 real_arg2 ext res dim res 10 arg1 lt arg2 real_arg3 coord res dim res probability of error for real_arg4 name confidence distance arg5 stat_measure measure values 0 lt arg3 lt arg4 lt 100 equidist_end 1 1 10 quantile values stat_red run ensemble reduced basic 6 arg1 arg2 0 001 real_arg1 statistical measures of arg3 dim res dim arg5 1 0 01 0 05 0 1 real_arg2 ext res dim res 7 arg1 lt arg2 arg3 coord res dim res probability of error for name stat_measure values equidist_end 1 1 7 confidence distance measure Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 The following explanations hold for the operators in Tab 8 13 e All UNC_MC operators but ens stat_full
404. y are averaged from less than rl values i 1 and yw j max 1 i rl 1 For the linear moving average the weights are Wj ij min rl i i j for the exponential moving average the weights are Wi e While the moving average is normally applied to time dependent one dimensional data vectors the op erator move_avg allows processing of multi dimensional data fields in a general and successive manner Example If arg4 is the three dimensional variable bios 1 lat 1 lon 1 time then the linear moving average could be applied to the dimension time successively for all combinations of lat and lon This means that lat1 1 lat lon1 1 lon lat lon moving averages will be performed for the vector bios lat1 lon1 1 bios lat1 lon1 2 bios lat1 lon1 time Afterwards this moving averaged temporary result tmp could be moving averaged for all values of lat loni 1 lon time1 1 time lon time moving averages will be performed for the vector tmp 1 lon1 time1 tmp 2 lon1 time1 tmp lat lon1 time The operator that allows for this double averaging would have the arguments move_arg 201 lin 0 bios The character argument char_arg1 supplies those dimensions that are to be involved in the moving av erage operation If the n th digit of char_arg1 is a digit gt 0 then the moving average for dimension n of argument arg4 is performed at position number digit i e aft
405. y the stopping rule for the ex periment A 0 dimensional result formed according to the rules of the SimEnv post processor Do not apply multi run operators Result definition can be ar ranged at a series of function lines in analogy to the rules for result expressions cf Section 8 1 1 To Tab 6 8 the following additional rules and explanations apply e For the description of line type check Tab 11 4 on page 171 e Sub keyword runs Specify here the number of runs to be performed e For all the other sub keywords check Section 6 1 1 on page 65 6 5 1 Stopping Rule Optionally SimEnv enables definition of a stopping rule that can be helpful to limit the number of simulation runs in an experiment In a stopping rule statistical measures from all already performed single model runs of the run ensemble are calculated after each single run to decide whether to stop the whole experiment Sta tistical measures are computed from a 0 dimensional result res z the stopping function formed according to the rules of the SimEnv post processor The stopping function is used as an indicator to stop the experi ment In SimEnv the point of change for the variance of the stopping function res z over the already performed single runs is determined after each single run using the Pettitt test Pettitt 1979 If a point of change in the sequence of the single runs over the already performed run ensemble is detected it is
406. y parametrising the shape of a driving force g aa Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 y H a ik 1 3 When this has been done the model behaviour finally depends only on the parameters P the initial values Zo and the boundary values B From the methodical point of view there is no difference between parame ters initial values and boundary values because all are considered as constant during one model run That is why in SimEnv all the four model components parameters drivers initial values and boundary values are lumped together and the term factor stands as a placeholder for them An often used synonym for factor is input All factors form the factor space X X P IX Z B and Z ST X In the following Xk X1 Xk k gt 0 stands for a subset of the factor space X that spans up a k dimensional sub space of X by selected model factors x1 Xk from X and Xkn vee wie 4X rede M k gt 0 n gt 0 stands for a numerical sample for X of size n and finally for k n values representing in any sense the sample space Xx In the set of all samples X 1 X 7 is the default nominal numerical factor constellation for the model M as normally defined in the model source code If denotes the dynamics of the model M over a sample of size n then it holds Z 2Z 1 20 SH AX n STC AX Y X2 Factor space X2 X1 X2 o o X21
407. y sts simenv_run_int and simenv_run_char are also declared include simenv_mod_auto_f inc c declare atmo without dimensions level and time and bios without time c because they are computed in place and simenv_slice f is used real 4 atmo 0 44 0 89 real 4 bitos 0 35 0839 integer 4 atmo lg 0 19 integer 4 bios g pl 1 p2 2 jos Be p4 4 c include source code sequence for the semi automated model interfac include world_f _auto_f inc c compute dynamics of atmo and bios over space and time Of atmo g over time alll dependent on pl p2 p3 p4 do idecade 0 19 do level 0 3 simenv_sts simenv_sts simenv_sts enddo simenv_sts simenv_slice f bios 3 idecadet 1 idecade 1 simenv_sts simenv_put_f bios bios enddo simenv_slice_f atmo 3 levelt 1 level 1 simenv_slice f atmo 4 idecade 1 idecade 1 simenv_put_f atmo atmo simenv_sts simenv_put_f atmo_g atmo_g c compute dynamics of bios g simenv_sts simenv_put_f bios_g bios_g simenv_sts simenv_end_f end Example file world_f_auto f Example 15 2 Semi automated model interface for Fortran models model world_f_auto f lt IAF Multi Run Simulation Environment SimEnv User Guide for Version 3 01 July 10 2012 SHL _ 197 15 2 4 C Model With respect to Example 5 1 the following C code world_c c could be used to describe the mode

Download Pdf Manuals

Related Search

Related Contents

R330 R430Z/R530Z/R630Z  LIVRO DO ALUNO NEONATOLOGIA DE RISCO  USER MANUAL Controller Belt Station U9911-BSC (P/N: 41033G-01)  Syntactica - MIT Press  ETP1010  Advantech POC-S157 User Manual  World Marketing of America QDE1425 space heater  Cliquez ici pour téléchargez le livre  V7 Nano Wifi DVB-T Tuner  Russell Hobbs Illumina  

Copyright © All rights reserved. Failed to retrieve file