Home

SimEnv User Guide - Potsdam Institute for Climate Impact Research

1. All examples in this document but for GAMS refer to a hypothetical global atmosphere bio sphere simulation model world It describes dynamics of atmosphere and biosphere at the global scale over 200 years Global lateral latitudinal and longitudinal model resolution is 4 X 4 between 178 W and 178 E and or 88 N and 88 S exceptions see below temporal resolution is at decadal time steps Additionally atmosphere is structured vertically into lev els For more information on this generic model check Section 15 2 1 The model world is assumed to map lateral 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 Ing results in a model world Ing Lusso Description Defined on Pen 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 56 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 variab
2. 160 Operator Description File model odf ssses eene nennen nnne 162 Macros and Macro Definition File model maxc c cccccceeeeeecne cece eeeececeaeeeeeeeeeeeeaeeeeeeeseeseecieaeeeeeeeeea 163 Wildcard Operands amp v amp and amp f amp oo eee sse eene nnne enn nennen nenne enne 164 Undefined cm 165 Saving MIIUIEMERPE T 165 VISUAL EXPERIMENT EVALUATION sseeeeene nenne ene nnen nnne enhn enne nenne nnns entere 167 MODEL AND EXPERIMENT POST PROCESSOR OUTPUT DATA STRUCTURES eee 169 NetCDF Model and Experiment Post Processor Output sssssseeeeeeenemeene enn 169 Global ATIDHITOS s eem foco ccm p D ntu M LLLA LL ni AAT LEE 170 Variable Labeling and Variable Attributes sss nennen enne nennen 170 NetCDF Attribute Description File model ndf sseen een 175 IEEE Compliant Binary Model Output ssssssseeeneeene eene nennen enne ener tenere Ac IEEE Compliant Binary and ASCII Experiment Post Processor Output sesseeee 178 GENERAL CONTROL SERVICES USER FILES AND SETTINGS see emere 181 General Configuration Files simenv settings txt and model cfg ssseeeeee 181 Maincand Auxillary S rvices MM m 186 Experiment Perf
3. 170 Global NetCDF attributes c c cece cece cece cece ences ee ee cece eae ae ee seen se ceaeaaeceeeeeeeseaaaeaeeeeesesecsaeaeeeesetensaeeeeeeeess 170 Variable NetCDF att bute E Eat 173 Elements of a NetCDF attribute description file model ndf eee 175 Record structure of model inf simenv res char ieee ascii for each result 179 33 j j Hp hyhy oS Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 Tab Tab Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig Fig 11 1 11 2 11 3 11 4 11 5 11 6 11 7 11 8 11 9 11 10 11 11 11 12 11 13 11 14 11 15 12 1 12 2 12 3 12 4 12 5 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 15 14 ures 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 11 1 Elements of the file simenv settings txt sisirin deai aranera aariaa anaana 181 Elements of a general model related configuration file model cfg ssssssssssssss 182 Default values for the general co
4. seem 19 Global Sensitivity Analysis Variance Based Method GSA VB sss 22 Deterministic Factorial Design DFD sssssssssssssssssssseseeenen nennen nhe nn ente netr tnnt nnn trn tesis sensere 25 Uncertainty Analysis Monte Carlo Method UNC MC sssseeee emere nennen 27 Local Sensitivity Analysis LSA eee ecesee een ee center eeneeeeenaeeeeeeaaeeeeeneeeeeeaeeeeeeaeeeenneeeessnaeeseenaeeeenneeeeneaa 30 Bayesian Technique Bayesian Calibration BAY BO sese 31 Optimization Simulated Annealing OPT SA ssssssseeeeeeeeene nennen nennen enne 34 MODEL INTERFACE ss iiviceiigiccis E 37 General APPrOACH m M l Coordinate and Grid Assignments to Variables ssesseseeeeeeene emm ener 41 Model Output Description File model mdf sss eren nnne sinet nn 42 Model Interface for Fortran and C C Models sssssssssssssssssseseenee eene nennt nr nre 45 Model Interface for Python Java and Matlab Models sesee nemen enne 48 Standard Dot Scripts for Python Java and Matlab Models sse 50 Model Interface for Mathematica Models cccccccccceececeeeeeeeeeeeeeeeeeeceeeaeaeeeeeeeseceaeeeeeeeseeeesaeeeeeeteeeeeea 51 Model Interface for GAMS Models icti inside c
5. P or in operators White spaces are filtered out from the result expression string also from character arguments m S FEE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN ji lt 111 For a single operand single operator result expression and in absence of result_description and or re sult_unit in the result descriptor both properties may be substituted by defaults Here a single operand single operator result expression is defined as a result without any operator or only from one operator and using exactly one model output variable and or one experiment factor For such op erators that are invariant with respect to the unit of the operand result description and or result unit are copied from the corresponding 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 For all other cases lt result_description gt and lt result_unit gt are blank strings undefined For a list of invariant operators check Section 15 5 5 The default value for result_name is res_ lt digit gt lt digit gt where lt digit gt lt digit gt where the first result in an post processing output file with a default name is res_01 and lt digit gt lt digit gt can count up to 99 If the result expression is compo
6. m x UT Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y H 1 3 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 m At P IX t Zo with ST state transition description Z state variables vector P parameter vector IX input driving forces vector Zo initial value vector t time At time increment m time delay The output
7. It is always a good idea that the model output variable name correspond to the name of the variable in the simulation model code Association between the two names is achieved by the SimEnv model interface func tion simenv put see below model mdf is an ASCII file that holds this information It follows the coding rules in Section 12 1 on page 203 with the keywords names sub keywords and values as in Tab 5 3 m a Q 42 y HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 To Tab 5 3 the following additional rules and explanations apply e Coordinate names lt co_name gt and variable names lt var_name gt must differ from factor names lt fac tor_name gt in experiment description cf Section 6 1 and from built in and user defined operator names for 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 used in 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 out put description file symbolically Model output variables with dimensionality 0 are not assigned to a coordinate axis Consequently the sub keyword coords is mandatory for variables wi
8. Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Function Function sue Inputs outputs function value name description f description unction value 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 flc place storage input non character arguments dimensionality 1 all inplace extents 0 none idimens formal coordi 20 e g 135with arguments 1 3 and 5 i nate number integer 4 dimensionality of the result iext formal coordi idimens ico_nr nate value begin input ico_beg_pos number TF of the result integer 4 only for idimens gt 0 iext 9 extents of the result input iext 1 iext idimens Currently only integer 4 only for idimens gt 0 coordinates from ico nr 9 formal coordinate numbers of the result the arguments can input ico nr 1 ico nr idimens be assigned to the integer 4 only for idimens 0 result ico beg pos 9 formal coordinate begin position for formal coordi input nate number ico nr of the result ico beg pos 1 ico beg pos idimens sip T integer 4 return code in the a ini simenv 0 ok ek ony i ues 0 inconsistency between operands i flc function value All of these operator interface functions return 999 as an error indicator if an argument iarg is invalid Output arguments
9. get factor names and adjusted values to ASCII file world as as simenv run char SSE HOME bin simenv get as run the model read world as as simenv run char store model output to ASCII files world as transfer ASCII model output files to SimEnv model output use simenv put as simple since the ASCII file has 9000 columns SSE HOME bin simenv put as simple atmo bios ascii simenv run char lat use simenv put as since the ASCII files have 1 column SSE HOME bin simenv put as atmo g ascii simenv run char time SSE HOME bin simenv put as bios g ascii simenv run char remove ASCII files rm f world as as simenv run char rm f atmo bios ascii simenv run char rm f atmo g ascii simenv run char rm f bios g ascii 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 as run Example 15 11 Model interface for ASCII files model shell script world as run m s RAS Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 JHN a Vy Go 23T7 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 and to world_sh_auto run with a semi automated interface at shell script level to run the mode
10. get run number SSE 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 iain ER run simenv run char f perform always and as the last SE HOME bin simenv sh dot script SE HOME bin simenv end sh Example file world sh rst Example 7 6 Shell script model rst to prepare model performance during experiment restart 1 m HEN Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 SMAN 107 7 5 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 up model 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 the previ ous experiment start restart e SE HOME bin simenv i
11. simenv get run ja only if necessary phi lat Simenv simenv get ja pl 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 Q4 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 V HN fi d 231 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 2 0 paulo d omega lat 2 phoueMlon d a p omega lon 4 simenv sts simenv ini m 9 simenv get run m only if necessary simenv run int str2num simenv get run m phi lat simenv get m pl p
12. d 1 for x4 endloop endloop endloop For comb default Is put down to comb combination see above 6 4 2 Example Experiment description file DFD a represents an experiment description according to Fig 4 6 a on page 26 DFD b and DFD d according to Fig 4 6 b and DFD c according to Fig 4 6 c Results in adjusted factor values world edf DFD a general descr Experiment description for the examples general descr in the SimEnv User Guide Fig 4 6 a general type DFD factor pl descr latitudinal phase shift factor pl unit ous Le factor pl type add factor pl default il factor pi sample lige d 3 7 8 2 4 8 9 for p1 LECTOR i9 type multiply factor p2 default ZU factor 92 sample lise 1 2 3 4 2 4 6 8 for p2 Specific comb default 3 m 82 y HN T J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 world edf_DFD_b general descr mae b 9 general type DFD factor pi type multiply factor pi default I factor pl sample list d 35 7 8 1 3 7 8 for p1 factor p2 type multiply Hue D2 default do factor p2 sample equidist end 1 0 5 2 5 2 3 4 5 for p2 Specific comb joi world edf DFD c general descr makers 4 6 fe general type DFD PACE Ore pl type set ANC Ons pl default il factor oul sample lise 1 3 VT 8 1 3 7 8 for p1 factor p2 type set factor p2 default dio factor 98 sample equid
13. 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 argument of the operator Coordinate transformation files follow the same syntax rules as all other user defined files cf Section 11 1 Tab 12 4 Elements of a coordinate transformation file line type o optional Max Sub Line Keyword Name keyword type line Value Explanation nmb general nil descr o any lt string gt general transformation de scription modify lt original_ rename o 1 new name renames original coordinate coordinate position shift o 1 val float shifts all values of the original name coordinate by the specified value position shift val values shift 0 1 lt val_int gt shifts the result values on the original coordinate by the specified positions lt values_shift_val gt values_add 0 1 lt val_list gt defines lt values_shift_val gt values to add to the coordi nate values for syntax see Tab 12 5 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Sub Line Ma Keyword Name keyword type line Value Explanat
14. minprop e arg1 run number where the minimum is reached the first time qnt e real arg1 arg2 run ensemble quantile of arg2 reg e arg1 arg2 run ensemble linear regression coefficient to forecast arg2 from arg1 rng e arg 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 1 Jan 25 2013 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 oD page arg1 arg2 addition elemental Tab 8 3 120 arg1 arg2 subtraction elemental Tab 8 3 120 arg1 arg2 multiplication elemental Tab 8 3 120 arg1 arg2 division elemental Tab 8 3 120 arg1 arg2 exponentiation
15. 8 6 Macros and Macro Definition File lt model gt mac In experiment post processing a macro is an abbreviation for a result expression consisting of an operator chain applied on operands Generally they are model related and they are defined by the user e 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 19 below is identical to ewe exem 20 8 AO GdL z ced TE E 2 9 20 0 e lbs 2319 81 dy 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 model mac model mac is an ASCII file that follows the coding rules in Section 12 1 on page 203 with the keywords names sub keywords and values as in Tab 8 22 model mac describes the user defined macros m S 7 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN T J lt 163 Tab 8 22 Elements of a macro description file lt model gt
16. User Guide for Version 3 1 Jan 25 2013 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 AIX 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 217 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 PATH se home path is the directory SimEnv is available from For SE HOME at PIK check Tab 3 3 on page 11 for the complete environment check Tab 11 15 on page 201 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 Ing to check SimEnv with the model world Ing from Example 1 1 on page 7 Ing f for Fortran C 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 51 fora GAMS model example check Section 5 7 on page 52 e Start simenv cpy world
17. arg1 parentheses Basic operators Tab 8 4 on page 121 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 121 sin arg1 sine cos arg1 cosine tan arg1 tangent cot arg1 cotangent asin arg1 arc sine acos arg1 arc cosine atan arg1 arc tangent Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Name Meaning See acot arg1 arc cotangent sinh arg1 hyperbolic sine cosh arg1 hyperbolic cosine tanh arg1 hyperbolic tangent coth arg1 hyperbolic cotangent Advanced operators Tab 8 8 on page 126 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 arg char arg2 char arg3 arg4 get data
18. lt arg2 comparing arg2 and arg3 char_arg1 comparison operator atmo arg3 using operator char_arg1 400 un mask_file mask values of arg2 1 mask char_arg1 set them undefined as mask dat arg2 specified in the file char_arg1 mask file name atmo char_arg1 matmul matrix multiplication diMarg1 diMarg2 diMres 2 matmul arg1 atmo 1 1 arg2 eXtres i according to matrix transpose 21 multiplication rules atmo 1 1 move_avg moving average of arg4 1 move avg char_arg1 001r char_arg2 diMargs gt O lan int_arg3 char_arg1 moving average 0 arg4 sequence per dimension atmo char arg2 average type lin linear exp exponential int arg3 running length for average int arg3 1 int arg3 0 automatic determination max 3 extarga i 20 rank assign rank numbers to 1 rank char_arg1 arg2 according to ranking tie avg arg2 type argument char_arg1 dimag2 gt O atmo arg1 ranking type tie plain tie min tie avg Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 STOUT Argument Name Meaning ASSO MO d value Example result description restriction Tab 8 1 page 118 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 co
19. z 2 d 307 then bound 1 2 1 1 e 4 nodata val float bound 1 2 1 1 d 10 nodata val double else else bound 1 e 4 bound 1 d 10 endif endif m noe 198 z H T f l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Example For lt nodata_value float gt 99999 itis bound 100009 and bound 99989 Within SimEnv post processing all model and intermediate post processor output values lt val_float gt with bound lt val float lt bound are identified as nodata values That s why make sure that values of real model output variables are always outside the neighbourhood as defined above Important note The visualization system SimEnvVis see Chapter 9 that is coupled to SimEnv expects that the nodata val ue assigned to the variable data type is outside the value range of this variable The value range is bounded by the minimum and the maximum value of the variable Normally type dependent default nodata values are outside the value range This may be violated for user defined nodata values For NetCDF model output each model output variable and for post processor output each result comes with an attribute data range that describes the value range by its boundaries see explanations to Tab 10 3 In particular pay attention to a user defined float real 4 nodata type when post processor output is stored in NetCDF format as post processo
20. At PIK SimEnvVis runs on the server viss 186 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 SimEnv lt simenv_run_int gt lt file gt service viser Auxiliary Services simenv chk check on model script files model run model rst model ini model end model 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 cln clean up model and experiment post processor output files model Deletes all model output files post processor output files experiment log files and auxiliary files of a model according to the settings in model cfg simenv cpl complete sequence of SimEnv services model simenv chk simenv run simenv res simenv vis simenv dmp simenv res is performed with input file file if available and interactively for both optionally only for single run simenv run int dmp modus simenv cpy copy all SimEnv example files model from the example directory model 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
21. 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 O or general operands with dimensionality 0 are invalid Example move _avg 0001 lin 3 atmo qnt 33 333 atmo If 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 ngr 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 arg can be used with operands of all defined data types cf Section 5 1 Internally arguments 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 for built in or user defined operators the standard approach for description of variables Advanced built in or user defined operators Have a unique name and a number of operands The sequence of operands is enclosed in parentheses directly after the operator name Operands are separated from each other by a comma S J a j Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Elemen 8 1 5 Recursions of t
22. The Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 by M Flechsig U Bohm T Nocke amp C Rachimow I e f ren 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 zi ETE WE j i Edd A ulti Run Simulation Environment SimEnv ser Guide for Version 3 1 Jan 25 I SHEN Multi Run Simulation Envi SimE User Guide for Version 3 1 Jan 25 2013 The Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 M ee Phone
23. exit rc_simenv_ini_ py ja m For an experiment restart with a Python Java or Matlab model cf Section 7 4 on page 106 lt model gt ini has to be performed again To force this specify in lt model gt cfg cf Section 11 1 on page 181 for the sub keyword restart_ini the value yes n 50 Y HN T I J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 11 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 model run It expects that the Mathematica model has the name model m where model is the model name the service is started with To enable the adjustment of a factor factor name in the mode
24. par seq _ aix linux jcf pbs if required optional model opt options txt model specific control and option file for experiment type OPT SA e Copy from 8E HOME bin simenv opt sa options txt if required optional shell script applied for R Restart of an experiment by simenv rst model S Start of an experiment by simenv run model file applied for A All experiment performance on the login node or under Distributed Resource Manager control D experiment performance under Distributed Resource Manager control O OPT SA experiment performance 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 na 108 SIENY Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Fig 7 1 simenv run lt model gt lt model gt ini return code 0 from lt model gt ini lt run gt first single run lt model gt run exists lt model gt lt run_char gt err lt run gt last single run simenv rst lt model gt restart_ini yes in lt model gt cfg return code 0 from lt model gt ini lt run gt first single run Single run completed in previous experiments Single run unfinished in previous experiments yes lt model gt run exists lt model gt lt run_char gt err d run last s
25. 1 2 3 and for p3 6 0 8 4 Dimensionality 4 Coordinates lat lon p2 p3 Extents 45 90 3 2 ceel eweg o2 13 S Sel 3L Gs 285 retno 57 5 Lp J mean of atmo for level 1 and for runs with p2 71 2 3 for each value of p3 8 4 9 9 Dimensionality 4 Coordinates lat lon time p3 Extents 45 90 20 2 Gligel Sunstio 1922 p mes q9 9 7 iar suem o Fe 1L 1198 20 9 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 lel imer G95 p ueia 1992 V 7 eher Leben 5 57 dL Le 210 9 Result differs normally from min p2 max p3 previous result expression licel count def 195 pexell si 162 131 bios Corr te 20 S 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 J TT j l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 ShEel p atmo p dp 20 eum Sell x94 1 eel 1033 amoi 5 Lp ZO 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 4 3 Example file world post DFD c Ex
26. 4 68 coordinate definition Example 12 2 Coordinate transformations by a transformation file Q4 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 SRN 207 12 3 ASCII Data Files and Value Lists ASCII data files lt directory gt lt file_name gt 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 directory2 file name e The directory path can contain operating system environment variables e f lt directory gt is specified in a relative manner it relates to the current workspace e file name must not be one of the SimEnv file names according to Tab 11 7 and Tab 11 8 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 T
27. Ing to copy the model world Ing model and experiment related files to the current workspace e Copy the file world edf DFD c to world Ing 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_DFD_c post processor result sequence Either e Start simenv cpl world Ing 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 m S Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T l 9 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 nteractively Enter any result and finish post processing by entering a single return e Visualization of post processed results will be started e Model or result output files will be dumped or e Start simenv chk world Ing to check model and experime
28. Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab 8 10 8 11 8 12 8 13 8 14 8 15 8 16 8 17 8 18 8 19 8 20 8 21 8 22 10 1 10 2 10 3 10 4 10 5 viii 4a Document conventions ccccccccececeesesceeeceeeceeaseceeececeaueaseeeceeeseaueaseeeeeeeeeaseceeeeeeeaueaseeeeeeseauaeaseeeeeseeauenensss 5 Main placeholders in this doc rnent oia rece toe iene a iea vas fen EEEE EER ERA EA EOE 5 SimEnv changes ini Version 3 ci cuuleecbssd cnc es cones seaeede cael enge e De Lena senshuctescdbodatesesbeve 11 User actions to upgrade to Version 3 1 escossa oaa aada apa daiire aieiai anaki 11 SimEny installatlons tr Er t Er E In I REIR Li eR EPI USFIE IRIERERRO UNENE ET TENERI OEE EESE ENTE 13 Limitations problems and their workarounds in Version 3 1 sssssseee een 12 Known bugs and their workarounds in Version 3 1 eene 138 DIMENV experiment LY POS e Pm F Experiment do Nerei e ia i eiaha dace iaraa pa inier 18 Statistical measures for an UNC_MC experiment eene nennen nennen 28 Probability density functions icio renidet octaua co cp too tee Ea tee aao cad sage L Aa EEEE EEEE Ra Chaves 29 Local sensitivity linearity and symmetry measures sssssssssssssssseseeeeeeeeren eene rnnt 30 Generic SimEnv model interface functions ssssssssssssssssssssesee nennen nennen nnn 38 Language suffices and multi dimension
29. arg2 arg2 lt 10 Assume an argument arg2 with 6 values 4 2 4 4 4 8 char_arg1 tie_plain returns ranks 2 1525252 8 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 15 252528 four times rank 2 next rank is 6 takes into account the number of identical values char arg1 tie avg returns ranks 35 1 35 35 35 6 four times mean rank 3 5 2 3 4 5 4 next rank is 6 takes into account number of identical values Example 8 7 Operator rank e Operator regrid 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 modify and the corresponding sub keywords are not allowed For syntax of coordinate transformation files check Section 12 2 For restrictions in the path to the directory of the character arguments char_arg1 check Tab 12 3 e Operator run The operator run selects a single run from the run ensemble The operator run must not contain experi ment specific multi run operators as operands since these operators may refer to the operator run Additionally run must not contain itself as an argument The character argument char_arg1 can hold the run number string explicitly An explicit run number string in character argument char_arg1 is
30. cfg For more information check Section 11 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 e 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 e 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 Matlab model in model run by matlab nojvm nosplash model name Contrary to general Matlab syntax variable
31. eee ce cece ee ceeeae cece eene 109 simEnv user shell scripts and flles iiiter eret eeu tte tee Itu dana kDa coeur vp ador dai ERa 194 ra a ulti Run Simulation Environment SimEnv ser Guide for Version 3 an 25 c ire IX Multi Run Simulation Envi SimE U Guide for Version 3 1 Jan 25 2013 SHAY IX Examples Example 1 1 Example 4 1 Example 5 1 Example 5 2 Example 5 3 Example 5 4 Example 5 5 Example 5 6 Example 5 7 Example 6 1 Example 6 2 Example 6 3 Example 6 4 Example 6 5 Example 6 6 Example 6 7 Example 6 8 Example 6 9 Example 6 10 Example 6 11 Example 6 12 Example 7 1 Example 7 2 Example 7 3 Example 7 4 Example 7 5 Example 7 6 Example 8 1 Example 8 2 Example 8 3 Example 8 4 Example 8 5 Example 8 6 Example 8 7 Example 8 8 Example 8 9 Example 8 10 Example 8 11 Example 8 12 Example 8 13 Example 8 14 Example 8 15 Example 8 16 Example 8 17 Example 8 18 Example 8 19 Example 8 20 Example 10 1 Example 10 2 Example 10 3 Example 10 4 Example 10 5 Example 11 1 Example 12 1 Example 12 2 Example 12 3 Example 15 1 Example 15 2 Example 15 3 Example 15 4 Example 15 5 Example 15 6 Example 15 7 X 3 ji General example layout in the User Guide ssssssseee ene enne rennen ener nns 7 DFD examples for scanning multi dimensional factor spaces ssseeem 26 Model output description file lt model gt mdf 2 0 2 cece cece cece ee ceeeeeae cece e
32. is z sr z sr P To estimate S use model output from S and RS S z S o z RS n a S y S x S n z S R oz RS 722 R To estimate Sz use model output from R and RS Sn z R oz RS n 2 R z R o z R n Z R with o scalar product 2 A oz B V zi 2 i l 1 n z A 5 zi n j SEAT 24 J HN T J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 x t X212 sub sample and sub re sample of size 12 each in the 2 dimensional factor space X2 x j X2 o X21 default nominal numerical factor constellation of model M Fig 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 e For scenario analysis to show how model behaviour changes with changes of factor values e Fornumerical validation purposes to determine factor values in such a way that the output vector matches with measurement results of the real system e For deterministic error analysis to analyse how the model error is dependent on factor errors e Fora simulation based control design to determine factor values in such a way that a goal function becomes an extreme x X212 sample of
33. l 1 5 When this has been done the model behaviour finally depends only on the parameters P and the initial val ues Zo From the methodical point of view there is no difference between parameters and initial values be cause all are considered as constant during one model run That is why in SimEnv the three model compo nents parameters drivers and initial 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 7 P IX Zo and Z ST X In the following Xk X4 X 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 x Xk from X and Xkn wee X X 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 amp 4 X 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 Zia UZC X4 ZU X 2 CST X4 STC AX Y X2 Factor space X2 X1 X2 o o X21 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 adj
34. mac line type m mandatory o optional Sub Line Max Keyword Name line Value Explanation keyword type nmb general lt nil gt descr o any string general macro descriptions macro macro descr o 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 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 unit without macro equ 100yrs define AaviGi alemon e Z 01 20 exo ilm iiim MACHO Mas Si descr se SEIT GIO macro tst define ilar 2 393 5 Tn eai jte define 4 Example files world f c cpp py ja m sh mac Example 8 19 User defined macro definition file model 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 d
35. model name an arbitrary number of factors and model output variables can be assigned to by the corresponding sub keyword get and or put e 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 e Each factor and each model output variable as declared in lt model gt edf and lt model gt mdf re spectively has to be used in the value field of model gdf exactly one time e Each model model name in lt model gt gdf with at least one sub keyword get has to have an include lt model_name gt _simenv_get inc statement in the corresponding GAMS model file lt model_name gt gms e Each model lt model_name gt in lt model gt gdf with at least one sub keyword put has to have an include lt model_name gt _simenv_put inc statement in the corresponding GAMS model file lt model_name gt gms e 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 index set is mandatory for variables with a dimensionality gt 0 Otherwise specification of index set is forbidden Indices as used in the GAMS model are separated from each other by comma m s EE Multi Run Simulation Environment SimEnv User Guide for Version 3 1
36. preparation Instead experiment preparation files and other information from the interrupted experi ment will be used The configuration file model cfg will be checked anew for experiment restart e Dependent on the experiment log file lt model gt elog written by the previous interrupted experiment a single model run out of run ensemble as defined in model cfg for the experiment to restart will be e Performed if this run has neither a start nor a finish entry in the elog file e Not performed if this run has a start and a finish entry in the elog file e Performed anew if the run has a start entry but no finish entry in the elog file e For the latter case a model restart shell script lt model gt rst can be optionally provided by the user to prepare the restart of this single model run e g by deleting non SimEnv temporary or output files Make sure that in lt model gt rst e dHlbin 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 59 and Example 7 6 below Make sure that model 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 11 10 Terminal output from lt model gt rst
37. py py experiment preparation if auto interface no in lt model gt cfg ASCII include files dot scripts for semi automated model interface model out directory in lt model gt cfg SE WS lt model gt out experiment performance model output of run number lt simenv_run_int gt of lt simenv_run_char gt the experiment nc ieee if out_separation yes 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 experiment 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 File location Generated in Explanation 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
38. run see Tab 11 10 this is not a dot script but a normal shell script with two arguments Dot script Use status Used for S See ection model ini simenv ini gams mandatory experiment init for GAMS models S7 simenv_ini_ja mandatory experiment init for Java models 5 5 simenv_ini_m mandatory experiment init for Matlab models 25 simenv ini py mandatory experiment init for Python models 5 5 S y H a j Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Dot script Use status Used for S PES ection model 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 a factor value as script variable 5 8 simenv_get_as optional get all factor names and adj values to an ASCII file 59 simenv_run_gams mandatory run a GAMS model Sa 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 fu simenv kill process optional kill a program model after reaching a CPU time limit 6 7 2 model sh as inc optional semi automated model interface at shell script 5 10 ASCII level cf also Tab 11
39. 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 simenv run char nlog in the corresponding sub directory run simenv run char 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 any name 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 values from sub keyword options lf main model simenv run char nlog Optdir In case the sub keyword options is not specified the main model is called with 1120 lo 2 lf main model simenv run char nlog Optdir All files with the extension nlog in the sub directory runssimenv run char 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 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
40. 0 For more information on the distribution functions see Section 4 5 and Tab 4 4 z 241 10000 1 Fig 6 1 left mid right Q4 ES 74 DHE IY 41 10000 2 co az ou as 01800 1 1 0 x1 1000 2 0 6 0 8 04 0 2 Probabilistic sampling Pseudo and quasi sampling pseudo sampling sample size N 10000 quasi sampling N 10000 quasi sampling N 1000 Factors on abscissa and ordinate U 0 1 From http en wikipedia org GNU Free Publication License 02 04 05 11000 1 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 X2 Sample size N 12 single simulation runs Factor x is normally distributed X4 Factor x is uniformly distributed 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 inf inf IEEE jou sample distr N 0 0 04 factor p2 descr as pl but sample only within the 3 sigma range Bale ons p2 sample distr N 0 0 04 factor p2 sample exclude Hines 0 6 Wo Gne factor p3 descr equivalent to p2 factor p3 sample distr N 0 0 04 LECTOR i93 sample include 4 0 5 8 01 1 factor p4 descr as p2 but exclude additionally 10 15 factor p4 sample distr N 0 0 04 3E HE One p4 sample ex
41. 0 yes yS yes 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 8 2 Built In Generic Standard Aggregation Moment Operators The generic operators in Tab 8 2 can be applied during experiment post processing to derive aggregations and moments from operands in different ways by appending suffixes n l e without suffix to the generic operator name or by incorporating them into the filter argument for experiment specific operator dfd of ex periment type DFD Tab 8 2 Built in generic standard aggregation moment operators Generic aggregation and Meaning moment operator 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 m a Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T J 119 8 3 Built In Elemental Basic and Advanced Operator
42. 1 info warning specifies which message types error to show nodata_value_ o 1 lt byte_val gt nodata value for integer 1 byte byte data nodata_value_ o 1 lt short_val gt nodata value for integer 2 short short data nodata_value_ o 1 lt int_val gt nodata value for integer 4 int int data nodata_value_ o 1 lt float_val gt nodata value for real 4 float float data nodata_value_ 0 1 lt double_val gt nodata value for real 8 double double data 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 or in one file per experiment out builtin vars o 1 yes no indicates whether built in model variables check Tab 11 9 are stored to SimEnv model output files 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 structure o 1 standard indicates model structure with distributed respect to experiment per parallel formance m ae 182 y H T f J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Sub Line Max Keyword Name keyword type line Value Explanation nmb experiment lt nil gt restart_ini o 1 no yes perform lt mo
43. 4449 331 288 2604 Fax 49 331 288 2640 P IK WWW http www pik potsdam de DI i Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 SH it 3 E ri 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 zi 7 UL IV ca M ulti Run Simulation Environment SimEnv ser Guide for Version 3 an 25 IV SHEN Multi Run Simulation Envi SimE User Guide for Version 3 1 Jan 25 2013 Contents Nae A WWWW N gt gt gt ona EXECUTIVE SUMMARY em 1 zo ug Irdpiocs gr 5 Document Conventions siise earitana ior eaa aa cess cca Ea sisi eh nenne ness es disset nre neti si set nensis sisi sinn naa 5 Example zo LV ees x GETING STARTED eiii heiter tasti teens ade ba iem repas isti ce iiie b eese 9 VERSION 321 EE ceeds 11 Whats TEE 11 Limitations Problems and Their Workarounds sseseeeneeenn nennen nnne enne 12 Known Bugs and Their Workarounds essseseseeene nennen enne nemen enne en nennen nene 13 EXPERIMENT TYPES 5 efc RR Global Sensitivity Analysis Elementary Effects Method GSA EE
44. 6 cmd model end simenv end gams mandatory experiment end for GAMS models roma In Tab 11 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 11 6 SimEnv include files and link scripts File Used in Explanation location generated during P link simenv mod used in shell script to compile and link an interfaced model f c cpp sh stand alone source code for experiment performance If necessary copy it to SE WS and modify it SE_HOME lib link_simenv_opr_ used in shell script to compile and link a user defined op f c cpp sh 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
45. Basic and Trigonometric Operators ssssssseeene eene nennen enemies 121 Standard Aggregation Moment Operators eee nennen nennen nns 122 Advanced Operators iiss ie E 126 Scy e 135 Built In Experiment Specific Operators cc ccceceenecssecceceseecceesecceeeenseceensenseees scenes ni tnh reden head taeda intra eds 136 M lti R N Oper tor d 136 Global Sensitivity Analysis Elementary Effects Method GSA EE see 138 Global Sensitivity Analysis Variance Based Method GSA VB sse 139 Deterministic Factorial Design DFD cccecceeceeeeeeeeeee ates ee ee teeeeeaeaeeeeeeeeecaaeaeeeeeeeseceusaeeeeeeesesanaeees 141 Uncertainty Analysis Monte Carlo Method UNC MC sese emere 145 Local Sensitivity Analysis LSA ssssssssseeseeene enm nene ener en nemen ennemi enne 149 Bayesian Technique Bayesian Calibration BAY BO sssseeeeeememe enm 151 Optimization Simulated Annealing OPT_SA sssssseeeeene emm eene 153 User Defined and Composed Operators Operator Interface ssssssseeee em 154 Declaration of User Defined Operator Dynamics esee 154 Undefined Results in User Defined Operators sseeeeene enm eene 160 Gro socios lm
46. 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 26 are used in the examples below 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 Dimensionality and extents of the operator result is the same as that of the operand Example for Fig 4 6 a fix a value of factor p1 and of factor p2 for Fig 4 6 b fix a value of the parallel factors p1 or p2 for Fig 4 6 c fix values of factors p3 and p1 or p2 e Without any selection in the factor space the dimensionality of the operator result is formed from the dimensionality of the operand enlarged by the dimensionality of the factor space The extents of the appended dimensions are determined by the number of sampled values Example for Fig 4 6 a two additional dimensions are appended to the operand dimension for Fig 4 6 b one additional dimension is appended to the op
47. Design by an example In the left scheme a the two dimensional factor space X p1 p2 is scanned combinatorially resulting in 4 4 16 model runs The middle scheme b represents a parallel scanning of these two factors at the X diagonal resulting in 1 1 1 1 4 model runs The right scheme c shows a complex scanning strategy of the 3 dimensional factor space Xa P1 P2 P3 resulting in 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 Example 4 1 DFD examples for scanning multi dimensional factor spaces ps Cose 1 l X i i i F I Hi 1 J I ee oe xx 0d at 0g X ot ot X X ee f ool P1 pi b c Fig 4 6 DFD examples for scanning multi dimensional factor spaces m AE Q 26 y HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 space X2 X1 X2 o X21 default nominal numerical factor constellation of model M Fig 4 7 Sample for UNC_MC
48. Example compare with the experiment description file DFD a in Example 6 5 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 Example compare with the experiment description file DFD b in Example 6 5 m 5A 80 y H T f l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 e The operators and can be multiple used in combination The operator has a higher priority than the operator Parentheses are not allowed Example compare with the experiment description file DFD_c in Example 6 5 X1 X2 X3 x4 always combines factors x and x in parallel and this combinatorially with factors x and x4 A parallel combination of x4 x2 with x3 x4 by x4 X2 X3 X4 is not possible e n combination each factor has to be used exactly once By the default combination default all experiment factors are combined combinatorially in the se quence of their declaration in the experiment description file Example comb default ofthe experiment description file DFD a from Example 6 5 is equivalent to comb p1 p2 Specification of file in the comb is only allowed if sub keywords sample were not specified for all fac tors in the
49. Ferret visualization techniques have been adapted designed and implemented 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 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 11 2 and directly during experiment post processing by the service simenv res if in the file model cfg check Section 11 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 11 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 I A 167 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN MATE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 10 Model and Experiment Post Processor Output Data Structures
50. 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 variance based uncertainty DFD Inspection of the model s behaviour in the factor space by a discrete numerical 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 Determination 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
51. Jan 25 2013 Argument Name Meaning restriction s Argument value result description restriction Tab 8 1 page 118 krt e run ensemble kurtosis 1 arg 4 moment med e run ensemble median 1 arg1 qnt e run ensemble quantile of arg2 1 0 real arg1 s 100 real arg arg2 real arg1 quantile value reg e run ensemble linear regression arg1 coefficient to forecast arg2 from 2 1 arg2 arg1 mg 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 real arg1 real arg2 real arg measures of arg5 0 001 0 01 real arg2 dim es diMargs 1 0 05 0 1 real arg3 eXtres diMres 10 real_arg1 lt real_arg2 real_arg4 Coord res diMres probability of error for arg5 name confidence distance stat_measure measure values 0 real arg3 lt equidist end 1 1 10 real arg4 x 100 quantile values stat red run ensemble reduced basic 6 real arg1 real arg2 real arg statistical measures of arg3 0 001 0 01 real arg2 dimes diMargs 1 0 05 0 1 arg3 eXtres diMres 7 real_arg1 lt real_arg2 COOrdres diM es probability of error for name confidence distance stat_measure measure values equidist_end 1 1 7 The following explanations hold for the operators in Tab 8 13 e All UNC_MC operators but ens stat full and stat red have the postfix e e All UN
52. Jan 25 2013 SHH 55 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 liet 0 1 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 Sod 3 3 sl es model gams_model put adi s 1085 model gams model put gs model gams model put modstat Example file gams model gdf 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 mi type sub model sub mi get dem ny model sub m1 put 5l 3153 8110185 model sub mi pat e sis model sub m2 type sub model sub m2 get dem ch model sub m2 put s IL or model gams model type main model sub mi type sub model sub mi get dem ny model sub mi put oil 3153 8110185 model sub m1 put ea silos model sub m2 type sub model sub m2 get dem ch model sub m2 put 1l model sub m2 put modstat Example 5 3 GAMS description fi
53. Jan 25 2013 y Hi l 1 75 To Tab 10 4 the following additional rules and explanations apply Attribute names lt attr_name gt and character strings lt string gt are case sensitive Attribute names are not checked for NetCDF CF compliance The meaning of the wildcard amp amp are as follows e amp v amp all variables only active for model output e amp c amp all coordinates e amp r amp all results only active for post processor output e amp amp amp c amp and amp v amp model output and or amp c amp and amp r amp post processor output By the sub keyword replace the specified attribute is replaced and not appended if the attribute is already defined otherwise it is inserted If the sub keywords delete and replace are declared for the same attribute name attrib name and for a local attribute for the same var name or co name or wildcard amp amp then the attribute is deleted first by delete and afterwards inserted by replace Consequently for such constellations delete is a redundant entry If for a local attribute a coordinate co name is addressed then also all derived coordinates var name co name see Section 10 1 2 are handled by this entry For a local attribute attrib name and multiple declarations for var name co name and wild card amp amp the processing sequence is as follows independently on the declaration sequence in lt mod
54. PY THONPATH 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 12 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 12 1 General Structure of User Defined Files All user defined files listed in Tab 12 1 have the same structure They are ASCII files with the following re cord structure lt sep gt keyword sep lt name gt sep sub keyword sep value sep with e name 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 keyword e keyword is a string N
55. 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 Function name Function description Arguments function value Argument function value description factor def val in the current single run factor def val input 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 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 num
56. Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 model 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 model mdf A multi dimensional variable occupies a block of contiguous columns The sequence of all columns of all lines of this variable is according to the column major order model cf Section 15 7 Glossary e Variables with the same first coordinate but with different coordinate extents variable sub keyword coord extents in model mdf have to be harmonised line by line The set of all lines is the union of all defined coordinate axis values from all variables To ensure synchronisation across columns variable values 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 a
57. SimEnv model coupling interface functions and for experiment post processor output default or user defined data type specific nodata values are used to represent undefined unwritten model output and undefined post processor output For the latter check Section 8 8 Default nodata value representations are listed in Tab 11 13 User defined nodata values are specified in lt model gt cfg as de scribed in Section 11 1 Tab 11 13 Data type related default nodata values SimEnv data type cf also Tab 5 4 Default nodata value byte int 1 127 short int 2 32767 int int 4 2147483647 float real 4 3 40E 38 double real 8 1 79D 308 All post processor output is of type float real 4 Model output in terms of model variables can be of any of the above types in Tab 5 4 as defined in the file lt model gt mdf model output in terms of experiment factors is of type float real 4 An integer byte int 1 short int 2 int int 4 value is identified as nodata if the value exactly matches with the corresponding nodata value representation In contrast a real float real 4 double real 8 value is identified as nodata if the value is in the neighbourhood of the corresponding nodata value representation This neighbourhood is defined by its bounds bound as follows For a float real 4 data value val float For a double real 8 data value val double if abs val float 2 1 e 34 then if abs val double
58. SimEnv supplies a coupling interface at shell script level by a set of dot scripts The shell script model run cf Section 7 1 on page 99 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 CEQ 58 Y HN T I J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Tab 5 8 Model interface functions at shell script level ini_sh Perform always and as the first SimEnv dot script in lt model gt run and lt model gt rst Check the semi automated model interface for alter natives for lt model gt run Command Inputs Input output Dot script name PAR or 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 experiment factor_name lt factor_name gt factor_def_val lt factor_def_val gt SE_HOME bin simenv_ get_sh 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
59. 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 vara normalization constant If the data avga have a low measurement error var 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 common assumptions are made that the measurement errors are nor m x E UE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y Hi l 91 mally distributed u
60. _ 0 1 real val4 lower bounds real val and exclude real val47 upper bounds real vali of PUT intervals to exclude from sam lt real_Valm1 gt pling according to distribution lt real_valm2 gt lt distribution gt real vali lt real vali specific nil seed 0 1 random fixed method how to initialize the random number generator runs m 1 lt val_int gt number of runs per factor To Tab 6 7 the following additional rules and explanations apply e 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 12 3 e Forthe sub keyword run The number of resulting runs for experiment type GSA_VB is lt val_int gt k 2 where k is the num ber of factors to be investigated e For all the other sub keywords check Section 6 1 1 on page 72 m Nr E Q 78 y HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 6 3 1 Run Sequence The sequence of the single simulation runs in the 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 endloop endloop loop over resulting sample
61. a model output variable definition as in Example 5 1 on page 44 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 column 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 SSE 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
62. 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 processing operator get_data and coordinate transformation file e Operator get_experiment 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 m AAD 130 y H a J
63. 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Tab 8 20 Operator interface functions to get check put arguments and results Function name Function description Inputs outputs function value Inputs outputs function value description 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 C index integer 4 vector index of an argument iarg index index input real 4 value of argument iarg at index
64. 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 coordinates 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 arg avg e arg avg e avg arg avg avg e arg is allowed and is the sum of the four summands as described above Dimensionality dimensionality of arg Coordinates coordinates of arg Extents extents of arg Example 8 9 Multi and single run experiment post processing operators m AT Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN Tl 137 8 4 2 Global Sensitivity Analysis Elementary Effects Method GSA_EE Tab 8 9 Experiment specific operators for GSA EE Name Meaning Argument restriction s result description Tab 8 1 page 118 Argument value restriction arg1 argument arg morris global sensitivity measures for 6 dimres diMargi 2 eXtres diMres 1 no of factors Coordres diM es 1 name factor_sequ values equidist_end 1 1 no _of_factors Xtres diMres 2 coordres diM es name
65. below By default all post processor output data is of type float real 4 IL 169 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN MATE Tab 10 1 NetCDF data types BE Mis NetCDF data type byte int 1 NF BYTE short int 2 NF SHORT int int 4 NF INT float real 4 NF FLOAT double real 8 NF DOUBLE 10 1 1 Global Attributes The global attributes used in SimEnv from the NetCDF CF standard for model and post processor output are Conventions institution and title They are complemented by CF non compliant attributes that are all pre fixed by SimEnv Tab 10 2 Global NetCDF attributes Name Value naa type Conventions CF lt CF_version gt char institution as specified in SE_HOME bin simenv_settings txt char title SimEnv Vers lt SimEnv_version gt model post processor output char Workspace lt user_name gt lt hostname gt lt SimEnv_workspace gt Timestamp lt YYYY MM DD gt T lt hh mm ss gt Z SimEnv http www pik potsdam de software simenv SimEnv Conventions information on CF convention extensions char NetCDF CF non compliant SimEnv model model char model description from general descr of lt model gt mdf gt NetCDF CF non compliant SimEnv experiment xxx single runs char with experiment type acronym and long name see Tab 4 1 NetCDF CF non compliant experim
66. 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 m ET TM 160 X HN T J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 Check the following example how to specify composed operators composed character normal composed operator operator name argument argument definition rel count arg1 arg2 100 count argl arg2 Counti ase 2 error 1 arg1 arg2 count argl arg2 honar o 0 0 7 10 5 7 AROZ error 2 arg1 argl ines Moulin snake y 310 0 5 7 Oc rera Having a model output variable definition as in Example 5 1 on page 44 then for example the operator rel count can be applied by rel count Cder boros rel count der bilog 202 20 7 1 zel count under T00biros Example 8 17 Compo
67. by applying the model interface functions simenv_ _ from the SimEnv model interfaces at language level Tab 11 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 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 236 the model shell script world_sh run is described in detail SSE HOME bin simenv ini sh i gert adjusted value for the a tactor p cet Cerine in the edi tile factor name p def Ibe ene ie Cer well 2 SSE HOME bin simenv get sh now shell script variable p def is available value of shell script variable p def is according to edf file get adjusted value for a factor p undef not defined in edf file factor name p undef ipexeEue Clic suedb 99 5c SE HOME bin simenv get sh now shell script variable p undef is available value of shell script variable p undef is 999 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 2 20 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 5 9 Model Interface for ASCII Files The SimEnv ASCII interface addresses constellations where e a model expects fa
68. 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 model 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 dis tributed model where the sub models are performed sequentially one by one in a cascade like man ner 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 To perform a parallel model within SimEnv simply use the same approach for wrapping a model by the shell script file model run as for standard and distributed models Instead performing the model within model run submit it there to the Distributed Resource Manager DRM by using the Ilsubmit for LoadL or qsub for PBS Torque command Start an experiment from a login node of the compute cluster and run the experiment at the login node in foreground SimEnv submits from the login machine all single runs to The DRM and directly finishes afterwards DRM then takes responsibility for performing the single model runs For the
69. char arg1 arg2 arg3 char arg1 Q4 m S LAG Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Es HN T J lt 131 e Operators mask file and unmask file 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 values lt value12 gt lt sep gt lt sep gt i c values values It uses the syntax for model output variables as described in Section 8 1 3 on page 114 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 model cfg cf Section 11 1 on page 181 for index and or coordinate addressing is used Additionally a local file default can be set by lines 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 valuez value if valuez is missing and instead of values valuez
70. cistr U 12 12 factor p4 type set PACE One p4 default 4 ACOs p4 sample distr UW il 3500 specific levels 4 use quantiles 125 375 625 875 specific trajectories 10 Example file world edf GSA EE Example 6 3 Experiment description file model edf for GSA EE Multi Run Simulation Environment SimEnv E User Guide for Version 3 1 Jan 25 2013 3 Hn S p lt 1 TT 6 3 Global Sensitivity Analysis Variance Based Method GSA_VB The experiment specific information for experiment description files in Tab 6 1 on page 69 is defined for GSA_VB experiments as follows Tab 6 6 Experiment specific elements of an edf file for GSA_VB Max Sub Line Keyword Name keyword type line Value Explanation nmb factor factor sample m 1 distr distr distribution and distribu name distribution tion parameters to derive file lt directory gt a sample of values file name factor smp val file file name to import an external sample of val ues factor smp val sample __ see 1 pseudo quasi sampling strategy method ex stratified only for plan sample distr lt distribution gt sample __ 0 1 real val4 lower bounds real val and include real val427 upper bounds real vali of ae intervals to include for sam real valy pling according to distribution real vali distribution real vali lt real vali sample
71. co_name 1 co name simenv get dim output arg f c integer 4 return code simenv 0 ok get co arg fic 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 Application of this output Do not get value number ico_pos but the function in ico_pos th smallest value sort values in increas simenv_check_ ing manner user def operator integer 4 return code for coordinate simenv 0 ok bin mid results in get co arg 1 ico pos out of range an error flc 2 storage exceeded function value 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 E integer 4 return code code 0 to the SITIS a 0 ok a function value of chk 2args 1 differing dimensionalities simenv check flc 2 differing extents user def e function value 3 differing coordinates according to the sub op erat or keyword coord check in lt model gt cfg 4 iarg1 iarg2
72. edf file e All factors are assumed to be combined in parallel e The sampled values are read from the sample data file directory file name e Each record of the sampled values data file represents one simulation run The sequence of the sample sequence of columns in each record corresponds to the sequence of the factors in the factor name space cf Section 12 1 on page 203 e Consequently the file has to have per record as much values as factors defined in model edf All the other syntax rules for ASCII data files from Section 12 3 hold e When specifying directory file name strict or directory file name 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 e When specifying directory file name nonstrict identical sample values for a factor are allowed Experiment specific multi run operator dfd can not be applied in post processing Use UNC MC operator ens instead e During experiment post processing restricted capabilities for the operator dfd apply for this experiment layout Example compare with the experiment description file DFD_d from Example 6 5 Combination is implicitly as comb p1 p2 Experiment description files DFD b and DFD d in Example 6 5 describe the same experiment To continue a combination combination at a following comb line end the current comb lin
73. first values of the se quence are skipped 1500 values for a fixed seed for a random seed the number of values is ran domly 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 uni formly distributed on 0 1 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 distribution The defi nition 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 0 1 gt Sub keywords sample_include and sample_exclude With the sub keywords sample_include and sample_exclude intervals to sample from can be speci fied explicitly when the distribution is defined by sample distr lt distribution gt A typical example for application of these two sub keywords is to exclude values from the distribution tails If include or exclude intervals are not specified the corresponding overall defaults from the distribution are ap plied Use inf to declare a positive infinite interval bound and inf for a negative infinite interval bound The result from the overlay of all include and exclude intervals with the definition domain of the distribution for probabilities gt 0 can be several non connected intervals
74. for Version 3 1 Jan 25 2013 for setting 2 file world dat_BAY_BC1_s 2 16 data entries in total and no data pair likelihood function If atmo is not used for setting 2 file world dat BAY BC2 s 2 6 data entries in total and a data pair for time 4 16 nodata for setting 3 file world dat BAY BC1 s 3 16 data entries in total and a data pair for time 1 Sybil E Oe Sli 15 nodata 3 nodata 2 21 db 2 nodata Qs 22 file world dat BAY BC2 s 3 6 data entries in total and a data pair for time 6 5 nodata SAIL c lE Oo SZ Example files world dat_BAY_BC1 world dat BAY BC2 Example 6 11 Data files for the likelihood functions of a BAY BC experiment For syntax of data file records check sub keyword data in Section 6 7 1 6 8 Optimization Simulated Annealing OPT SA The experiment specific information for experiment description files in Tab 6 1 on page 69 is defined for an OPT_SA experiment as follows To Tab 6 12 the following additional rules and explanations apply e Sub keyword seed This sub keyword controls the seed of the used random number generator the simulated annealing algorithm 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 differ ent machines without taking into account numerical inconsistencies e g rounding errors If
75. for a slice out of the run ensemble Experiment slices are controlled by the general configuration file model cfg by a range of single run numbers Ex periments can be restarted for successive performance of experiment slices and or after abnormal experiment interrupt The experiment log file model 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 e For more information check Section 5 1 Fig 5 1 and Fig 7 1 m s AA Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs Ni a f l lt 99 7 2 Model Wrap Shell Script lt model gt run Experiment Specific Preparation and Wrap Up Shell Scripts 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 model run e 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 59 and Example 7 1 below e Terminal output from lt model gt run is redirected to the model native output log file lt model gt nlog e To cancel the whole experiment after the per
76. for an UNC_MC experiment N number of Monte Carlo runs Z1 Zu Zh4 Z1y Z2 Z2y are realizations of state variables z z1 and z2 resp N N indices for sums X products and extremes run from 1 to N X I1 min max function i 1 i91 i 14 N i 1 N Statistical measure Definition minimum min z min zi maximum max z max zi sum sum z 2 Zi arithmetic mean avg z z N variance var z z avg z N 1 skewness skw z X zi 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 IIz y harmonic mean agvh z 2 N X1 Izi weighted mean w avgw z Xz wiXw w weight f cor z1 z2 z1 avg z1 za avg z2 correlation V zi avg z1 Y z2 avg z2 Y covariance cov z1 z2 X zii avg z1 zz avg z2 N 1 linear regression coefficient regie tza 2 z1 avg z1 4 Zer avga to forecast z2 from z1 z1i avg z1 Y 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 zi N even qnt z that value from increasingly ordered zi quantile p which corresponds to a cumulative frequency of N p 100 qnt z med z confidence interval cnf z avg z tana V v
77. function arguments Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Tab 8 19 Operator interface functions to get and put structural information Function name Function description Inputs outputs function value Inputs outputs function value description 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 fic character argu input ment character string of the character argument larg char Declare char with a sufficient length char output integer 4 length of character argument simenv_ get_char_arg_ fic 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 larg iarg 0 iext 9 iext 1 iextsimenv get dim arg f c iext get dimensionality output and extents of the z result integer 4 dimensionality of argument 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
78. function simenv put undef f c cf Tab 8 20 Check usr opr matmul f c J 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 Setsimenv compute user def operator 7 0 otherwise set it always 0 e n 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 built in or user defined operators Like
79. 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 simenv_ announce to out character name of the variable in model 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 x UNE integer 4 slice to start at position ifrom ment becomes ifrom ifrom corresponds to an index from index extents inactive after per t n smodelscadt formance of the input HS HOSTE corresponding integer 4 slice to end at position ito simenv put f c ito ito corresponds to an index from index extents in input model mdf integer 4 return code simenv slice 0 ok fic 1 var name undefined 3 m 46 J H a l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Function name Function Arguments Argument function value description function value description 3 inconsistency between variable and idim ifrom
80. in the Metropolis Hastings algorithm that a jump in the factor space from a point p to a point p has the same probability as from p 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 avg and var that cor respond to individual elements of model state variables output variables results y Compose the posterior probability with a likelihood 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 gt 1 data files each corresponding to its result df with y4 df with y sequence of single likelihood functions e forthe multiple setting likelihood function case from performing each single run for m gt 1 settings and for each setting from 2 1 setting specific data files each corresponding to its setting independent result df with y df with y df with V4 s df with yi 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 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 for
81. is stated in lt model gt cfg as the hosting directory opr_directory for user defined operators e The include files 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 func tions for Fortran and or C C cf also Tab 11 6 e Apply the shell script link simenv opr f c cpp sh lt opr gt 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 pro gram for the operator also the object SE_HOME bin simenv_opr o is supplied by SimEnv This ob ject file has to be linked with usr_opr_ lt opr gt o and the object library SE_HOME lib libsimenv a e Tab 15 14 lists the additionally used symbols when linking a user defined operator e In Section 15 3 on page 241 implementation of the user defined operator matmul f c is de scribed 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 undefined by the SimEnv operator interface
82. lt 105 7 3 5 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 Is id d r sa private key id d r 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 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 3 3 it can be restarted Restart can be applied to an experiment several times suc cessively e Simply restart the experiment by simenv rst The SimEnv service simenv rst has the same usage as simenv run Do not change 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 keyword experiment in the general model configuration file model cfg Experiment restart works without standard SimEnv experiment
83. lt p p 1 un mask_file lt directory gt lt file_name gt max_l sequence of digits 0 and 1 maxprop sequence of digits O and 1 min sequence of digits 0 and 1 minprop_ sequence of digits 0 and 1 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Argu Argument value Operator ment pre defined values Remark number are case insensitive move_avg 1 sequence of digits 0 to 9 move_avg 2 lin exp rank 1 tie_plain tie_min tie_avg regrid 1 lt directory gt lt file_name gt run 1 not pre defined case insensitive run_info 1 run nr nr of runs sens abs 1 not pre defined 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 1 Jan 25 2013 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 Argument Arg
84. m jcf pbs PBS Torque model opt sa user specific control and option file for experiment type optional 6 8 1 options txt OPT SA m 190 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Shell script file Formers infor in the current Explanation Exist status mation workspace cag SSIES Section lt model gt err touch create this file in the model or in model run as optional lt simenv_ an indicator to stop the complete experiment after 75 run_char gt lt model gt run has been finished for the single model run s lt simenv_run_int gt usr_opr_ lt opr gt executable for user defined operator lt opr gt optional in the opr_directory 9 5 according to lt model gt cfg Tab 11 8 lists the temporary or permanent files that are created during a SimEnv service Tab 11 8 Files generated during performance of SimEnv services For the current workspace SE_WS see Tab 11 14 me 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 model
85. 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 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 is a series of the model runs of the individual settings Model settings may differ in their calibration e g for site conditions if a model is considered to run at a local regional scale While the result part of the likelihood function s is are unique for all settings the data part s differ s among the settings In other words setting related likelihood functions are composed for each 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 model bdf for the mult
86. method to use metropolis _ reflected cov matrix o 1 file lt directory gt lower triangular matrix includ file name ing diagonal of factor covari ances jump length o 1 val float modifier for the length of the multivariate normal jump val float gt 0 settings m 1 val int number of settings for a multi ple setting BAY BC experi ment val int 2 1 likelihood symbolic descr o 1 lt string gt likelinood descriptions likelihood model output m 21 result likelihood function model out namga 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 To Tab 6 11 the following additional rules and explanations apply e Sub keyword method The method metropolis standard corresponds to the regular Metropolis Hastings algorithm while for metropolis_reflected the so called Metropolis with Reflection algorithm check Section 4 7 is used The latter method demands per factor only one resulting interval that is the intersection from the definition domain of the distribution and sample_include sample
87. model gt smp as for outranged candidates the model is not performed model 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 model 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 Unlike lt model gt blog this file lists also the candidate point likeli hoods for rejected points As the model is not run for outranged candidates the file can not supply informa tion for such candidates oO 92 J T I J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 6 7 4 Examples general descr Experiment description for the examples general descr in the SimEnv User Guide general type BAY BC factor pl type set factor pl default ipe LECTOR pi sample Cibi SS NA OMON factor pl sample include 0 9 1 1 sample only within the 30 interval TACTO p2 type set factor p2 default 2 factor p2 sample disti Urbs 2 factor p3 type set factor p3 default So factor p3 sample chiste J8 55 0 0 ACOs p4 type set
88. multi run experiment can be performed sequen tially or in parallel Interactive experiment post processing makes use of built in operators optionally sup plemented by user defined and composed operators Operator chains are applied on experiment output and reference data to navigate and post process in the combined sample and experiment output space Result ing 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 al 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 the strategy of a selected experiment type for a set of so called factors x which represent pa rameters initial values or drivers of a model M a numerical sample is generated before simulation This sample corresponds to a multi run experiment with the model During the experiment for each single simula tion
89. of CE 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 real vali specific lt nil gt levels m 1 lt val_int 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 val_int 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 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 distribution U lower bound upper bound the two bounds will not be used as factor values for the resulting grid in the factor space Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 e To ensure that trajectories do not have to share grid points t
90. of the result vector of the operator ien jas integer 4 return code z simenv_ 0 ok compute user def operator function value 0 user defined interrupt of calculation Operator results of a dimensionality gt 1 have to be stored to the array res using the Fortran storage model cf Section 15 7 Glossary 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 the functions for C C is based on a call by reference for the
91. operators for BAY BC Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 drum Argument value Name Meaning restriction s g me EE 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 44 and assuming address default coordinate in model cfg Assume the experiment description file LSA from Example 6 12 on page 97 then in result processing Dimensionality 0 Coordinates without Extents without ens sum bios run xxx sum bios Dimensionality 1 Coordinates run Extents 500 rank tie min ens sum bios Dimensionality 1 Coordinates run Extents 500 minprop e sum bios run number with the minimal cost fu
92. 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 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 Fig 4 8 Sample for 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 meos Absolute measure Relative measure sensitivity sens abs z se Zi5 z 9 sens relz tt sens abs z tc X measure teg z x linearity lin abs z s 2 x 2 x 2 x Z lin rel z c lin abs zc X measure u B z x symmetry sym_abs
93. 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 lt simenv_run_int gt Tab 11 4 SimEnv services EUER Use to service Main Services simenv res perform experiment result post processing for run number simenv run int or for model the whole run ensemble simenv run int 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 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 the results are appended or the result files are replaced by new ones 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 lt simenv_res_int gt
94. respect to Example 5 1 the following C code world_c c 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 include lt string h gt include simenv_mod_c inc declare SimEnv interface functions compile with ISSE HOME inc declare atmo without dimensions level and time and bios without time because they are computed in place and simenv slice c is used starcie Float atmo 45 90 Stacie rloat bios 36 T90 tatic int atmo_g 20 pratic imr DAO SMG main void fs inde 19171921935 949 int level idecade simenv sts simenv run int levell idecadel idim char simenv run char 6 oll Lap DA Z p jos 347 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 pl 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 of atmo g over time all dependent on pl p2 p3 p4 for idecade 0 idecade lt 19 idecade leas for level 0 level lt 3 level sees idim
95. scale modeling applications and allows to build large maintainable models that can be adapted quickly to new situations 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 coordinates to the variable or the operator result m e 262 y HN T J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 IEEE SimEnv can use on demand for storage of model and post processor output the Institute of Electri cal and 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 origina
96. simenv_sts simenv_sts simenv_sts simenv_sts do idecade enddo enddo simenv_sts simenv_sts simenv_sts end do level simenv_sts simenv_sts simenv_sts atmo 0 44 0 89 loses OS SORS atmo_g 0 19 bios g simenv ini f heek recita Code oTi emoc cies edes aie C UTI esl om Se ase least here if simenv sts ne 0 stop 1 elmeny get run i only it necepsarys simenv get run f simenv run int simenv run char simenv get f pl pl pl 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 c Of atmo g over time alll dependent on pl p2 p3 p4 Op 19 PES simenv slice f atmo 3 levelt 1 level 1 simenv slice f atmo 4 idecade t1 idecade t1 simenv_put_f atmo atmo simenv_sts simenv slice f bios 3 idecade 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 224 S ayy Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 mar
97. size 12 in the 2 dimensional factor space X2 x g X2 o X21 default nominal numerical factor constellation of model M Fig 4 5 Sample for DFD m g AA Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 ay H p J 25 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 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 a Deterministic Factorial
98. 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 sin gle run itself is an optimization procedure which could result in an unfeasible wall clock time con sumption If the sub keyword is not used in the gdf file wall clock time consumption per single run is unlimited e Ifthe sub keyword options is not specified the GAMS main model is started with the default options 1120 lo 2 dp 0 complemented by lf main model simenv run char nlog Optdir Check also Section 5 7 3 e 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 simenv run char of the current workspace cf Section 5 7 3 The shell script has one argument the current run number simenv run char formed from six characters For example the script can be used to copy some files into the sub directory run simenv run char where the GAMS model is called from Make sure by the Unix Linux command chmod u x directory2 file name 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
99. stat_measure values equidist_end 4 1 5 see Section 8 4 5 same as for UNC_MC see Section 8 4 5 see Section 8 4 5 then in result processing morris max atmo reewaike ical jeullievatia p cellas Vos cr stil rr wieseseal ss Gales enne J Having a model output variable definition as in Example 5 1 on page 44 Assume the experiment description file GSA_EE from Example 6 3 on page 77 importance measures u and c for max atmo for the four defined factors Dimensionality 2 Coordinates factor sequ stat measure Extents 4 2 ranks the importance measure y rank 1 for the most important factor for max atmo for the four defined factors Dimensionality 1 Coordinates factor_sequ Extents 4 Example file world post_GSA_EE Example 8 10 Experiment post processing operators for GSA_EE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 coordinate values as described above the second additional dimension has the extent 2 and accord ing to Tab 11 11 the first index of this dimension holds the averages ys and the second index the variances o to descr
100. stored in subdi rectories s setting number of the model output directory as specified in model cfg For post processing 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 ap plied outside a multi run operator is an argument to the operator as well as inside the operator is an argument of a multi run operator multi run operators In fact both operators do not make sense when applying outside a multi run operators This is not checked when analysing a result expres sion m s ear Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y Hi l 1 51 e Operator bay_bc_run_weight The weight that is assigned to a single run of type accepted or reflected is the number of all sub sequent single runs of types outrange or rejected until the next single run of type accepted or reflected The single run under consideration also contributes to the weight The resulting weight is multiplied with arg1 Single runs of type rejected get an undefined weight e This experiment type allows to post process the whole run ensemble as an UNC MC experiment Tab 8 16 Experiment specific operators for BAY BC Name Meaning Argument restriction s result description Tab 8 1 page 118 Argument value restriction bay bc
101. the direction of the jump will not be changed There are two major reasons for changing the jump length 1 jump length 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 the jump length is not specified a default value 1 is assumed resulting in no modifi cation of the jump length Sub keyword settings SimEnv allows for composing the likelihood function from performing a single model run for a num ber of different model settings where all settings consistently follow the single or multiple likelihood function case This approach is called the multiple setting likelihood function case check Section 4 7 Model settings in such a case may differ in model calibration or site conditions While the result part of the likelihood function s is are unique for all settings the data part s differ s among the set tings Settings always count from 1 Please check Section 6 7 2 below for more information how to set up such an experiment Sub keywords model output 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 measure
102. the last SE HOME bin simenv sh dot script S SE HOM Example 15 8 E bin simenv end sh Model interface for Mathematica model shell script model run E Sa Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 SE 233 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 SETS I canning plants SEATTLE SAN DIEGO J markets NEW YORK CHICAGO TOPEKA PARAMETERS ANG mgeexehbuy oep lant at 3t Gleiske SEATTLE 350 SAN DIEGO 600 B J demand at market j in cases NEW YORK 325 CHICAGO 300 TOPEKA 2758 f Before using parameters here dem ny and dem ch as SimEnv experiment bs factors they have to be declared as GAMS model parameters Ww with default values from above Then insert include lt model simeny get inc d simenv 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 SAN DIEGO dem ch TABLE D I J distance in thousands of miles NEW YORK CHICAGO TOPEKA SEATT
103. the loop character argument Appending suffix _e _e stands for run ensemble Aggregate separately for each element of the only non character non constant argument over the ensemble of all single simulation runs but single run 0 Such operators are multi run operators check Section 8 4 1 The result has same dimensionality extents and coordinates as the argument Exceptions to the above rules hold for operators minprop maxprop and hgr Additionally the operators can be used in the selection aggregation filter argument char_arg1 of the multi run operator dfd for the experiment type DFD For details check Section 8 4 3 For examples without suffix and with suffix n check Section 8 3 5 with suffix _e check Section 8 4 5 S y H a j l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Tab 8 5 Built in standard aggregation moment operators without suffix Aggregation and moment operator Argument restriction s result description Tab 8 1 page 118 max arg1 min arg1 sum arg1 avg arg1 var arg1 avgg arg1 avgh arg1 avgw arg arg2 4 1 arg2 weight count char arg1 arg2 3 char arg1 all def undef maxprop arg1 minprop arg1 d imres Xtres 1 dimres for dima gt 1 1 d iMargt else 0 return the index of that element of arg1 where th
104. then factor adj valis set to factor def val 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 output adjusted factor value factor adj val 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 asaninteger 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 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 1 Jan 25 2013 To the Tab 5 8 following remarks apply For the model interface at the shell script level i e within the shell script lt model gt run the adjusted experiment factors for the current single run from the whole run ensemble can be made available to forward them to the model under investigation by any means the modeller is responsible for One common way to forward experi
105. when starting the post processor is set to sampletresample Keep in mind that only the resulting runs of the first three cases follow the distributions as specified in model edf by the sub keyword 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 44 Assume the experiment description file GSA VB from Example 6 4 on page 79 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 g 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 Coordinates without Extents without Example file world post_GSA_VB Example 8 11 Experiment post processing operators for GSA_VB J a j Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 8 4 4 Deterministic Factorial Design
106. where the sample for the factors of the single runs are not determined be fore the experiment but in the course of the experiment by the optimization algorithm Consequently only the header of the file model smp is created during experiment preparation The records be longing to the performed single runs are written during experiment performance In parallel to the file model smp an ASCII file lt model gt fct is written during experiment perform ance with the value of the cost function for each of the single runs 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 from the sub directory bin of the SimEnv home directory to model opt sa options txt in the cur rent workspace and edit this file During the experiment the edited file is used instead of the file with the default constellation in the SimEnv home directory The description of the options and parame ters of this file can be found in Ingber 2004 OPT SA experiments cannot be restarted by the SimEnv service simenv rst y HN T J l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 e n 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 num ber 0 and
107. z e Z x Z x sym rel z sym abs zs E measure S E z x AN 30 y TT i J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 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 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 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 to compare the influence of different factors x on the same state variab
108. 0 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 int 1 555 312 512 000 1 4 records with a fixed length of 512 000 Bytes Remaining bytes in the last record are undefined Example 10 5 IEEE compliant model output data structure 10 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 simenv_res_char gt ieee ascii holds the result dynamics e model infssimenv res char ieee ascii holds structure and coordinate information The IEEE post processor output files e model rescsimenv res char ieee and e model infssimenv res char ieee are unformatted binary files with IEEE float int number representation while for the ASCII post processor version e model rescsimenv res char ascii and e model infssimenv res char ascii formatted ASCII files are used Files for both output file formats have for each result subsequently the follow ing structure m m TT m Q 1 78 y HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Record structure of lt model gt inf lt simenv_res_char gt ieee ascii for each result Tab 10 5 Record structure of lt model gt inf lt simenv_res_char gt ieee ascii for
109. 013 e Operator undef The operator undef supplies a O dimensional result as undefined Among others this operator can be used as an argument for the if operator e Operator usage 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 Section 8 5 The operator is a stand alone operator It must not be operands of any other operator e For additional 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 page 44 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 S Oielaeie dir other model T atmo D
110. 1 2 corresponds to to one two dimension s and the values of the variable are represented by a vector a matrix In general a dimensionality of n corresponds to an n dimensional array The extent relates to each dimension of a model output variable and represents the number of elements in that dimension Extents are always greater than 1 A 4x5 matrix mati i1 4 j 1 s has an extent of 4 for the first dimension and of 5 for the second one To each dimension a coordinate is assigned to Coordinates have a name and a well defined number of coordinate values A subset or even the whole set of values of a coordinate is assigned to the dimension of that variable Consequently the number of coordinate values is the extent of this dimension A single model output variable must not have identical coordinate names but can have identical coordinate values Finally coordinate axes are defined A coordinate axis is a strictly monotonic ordered sequence of coordi nate values and has a description and a unit A complete coordinate axis or a part of a coordinate axis is assigned to each dimension of a model output variable Consequently each variable is defined on a coordi nate system formed from the assigned coordinates For reasons of simplification in result evaluation with visualization techniques coordinate systems are as sumed as rectilinear and block structured Rectlinear refers to an orthogonal Cartesian coordinate system and block struc
111. 1 Max Planck Institute for Meteorology 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 effects In Jezowski J Thullie J eds 19 European Symposium on Computer Aided Process Engi neering ESCAPE19 June 14 17 2009 Cracow Poland Elsevier 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 Wenzel V K cken 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 Matth us E Flechsig M 1990 One Decade of SONCHES Syst Anal Mod amp Sim 7 411 428 Wierzbicki A P 1984 Models and Sensitivity of Contro
112. 1 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 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 1sint args6 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 0 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 r 2 n r tan 0 0 cot arg1 cotangent 1 arg xn m cot 1 5708 0 asin arg1 arc sine 1 abs arg1 831 asin 0 0 acos arg1 arc cosine 1 abs arg1 31 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 3 ri Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN J 121 The following explanations hold for the operators in Tab 8 4 8 3 3 All
113. 1 69 lt model gt odf operator description file 8 5 4 162 lt model gt mac macro description file 8 6 163 lt model gt gdf GAMS description file 5 7 2 54 arbitrary file name coordinate transformation file 12 2 205 The following restrictions hold for user defined files Tab 12 2 Constraints in user defined files with the exception for GAMS model source code file names Element Constraints line length max 360 characters name max 64 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 120 value for sub keyword descr without name max 512 characters total sum over all lines for sub keyword descr with lt name gt max 128 characters for sub keyword string 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 12 3 lists the reserved forbidden names and file names that cannot be declared in user defined files Tab 12 3 Reserved names and file names in user defined files Element Reserved forbidden names name built in model output variables according to Tab 11 9 with the exception of GAMS built in coordinates model source code file names according to Tab 11 11 special keywo
114. 1 long name atmo res O1 units atmo unit res 01 data range 1999 95f 2002 39f res 01 FillValue 3 4e 38f float res 02 lat res 02 lat res 02 lat standard name SimEnv model coordinate res 02 latlong name geographic latitude res 02 lat axis Y res 02 lat units deg float res O2 time level lon res 02 lat res 02 standard name aggregated atmospheric state res 02 long name sin atmo i 2 37 res 02 units atmo unit res 02 data range 1 f 1 f res O2 index range lat 2 37 res 02 FillValue 3 4e 38f lat 88 84 84 88 res O2 lat 84 80 52 56 Example 10 2 Additional coordinates in NetCDF post processor output S y H a j l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 The following NetCDF variable attributes are used according to the NetCDF CF standard Tab 10 3 Variable NetCDF attributes Name Value Data type NetCDF CF compliant lt NetCDF_variable_name gt see below char standard name NetCDF variable name see below char long_name lt NetCDF_variable_name gt see below char units lt NetCDF_variable_name gt X Y Z T char axis only for lt NetCDF_variable_name gt lt co_name gt lt NetCDF_variable_name gt variable type depending missing value type dep _ FillValue see Tab 11 13 NetCDF CF non complian
115. 3 levell level t1 Simenv sts simenv slice c atmo 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 idecadel simenv sts simenv put c bios char amp bios SHEN Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 simenv sts simenv put c atmo g char amp atmo g compute dynamics of bios g simenv sts simenv put c bios g char amp bios g simenv sts simenv end c return 0 Example file world c c Example 15 3 Model interface for C models model world c c r4 m l PER Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 SHMI 227 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 IS SE_HOME inc include simenv mod c inc class World declare atmo without dimensions level and time and bios without time beca se they are computed in place and simenv slice c is used p
116. 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 inter face function simenv_get_ The file lt model gt smp always contains the sampled values according to the experiment and factor specific sampling scheme as defined by the sub keyword sample without applying the adjustment 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 e factor adjustment type add and lt factor_def_val gt 0 e factor adjustment type multiply and factor def val 1 e factor adjustment type relative and any factor def val For the factor adjustment types multiply and relative a default nominal value val float 0 is forbidden All experiment specific information is explained in the appropriate Sections Specify at least one experiment factor The sub keyword sample is conditional for experiment type DFD undefined for experiment type LSA and mandatory for all other experiment types When preparing an experiment an experiment input file model smp is generated with the sampled values factor smp val 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 factor
117. 55r br Is 20 run OY 7 enemies 95 5 5 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 m TIAM Q 1 48 y HN T J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hgr_e bin_no 0 0 0 min_1 10 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 stet ell 0 5 01 0 05 25 Jumbo 1 3107 atmo 208 207 7 1 200 J 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 13 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 30 Experiment post processing operators for UNC MC Tab 8 14 Experiment specific operators for LSA Argument Argument value Name Meaning restriction s g e PUDE restriction result description sens abs absolute sensitivity mea
118. 8 6 Example equ 100yrs m e Wildcard operands cf Section 8 7 Example amp v amp As for model output variables also to each operand with the exception of character string operands e A dimensionality dim gt 0 Extents ext i gt 1 Coordinates coord i with i 1 dim with i 1 dim are assigned to cf Section 5 1 The dimensionality is the number of dimensions an extent is re lated to each dimension and represents the number of elements in that dimension Extents are al ways greater than 1 To each dimension a coordinate is assigned to Coordinate specification for operands follows that for model output variables For more information see Section 5 1 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 8 1 3 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 opera tors 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 extents and a coordinate assignment Model Output Variables A variable of dimensionality n corresponds to an n dimensio
119. C 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 but 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 and meaning is pre defined by SimEnv cf Tab 11 11 The values of the dimension generated additionally as the last argument by applying the operators stat full and stat red of the correspond to the following statistical measures 1 Deterministic run run number 0 2 Run ensemble minimum Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Run ensemble maximum Run ensemble mean Run ensemble variance Run ensemble positive distance of confidence measure from run ensemble mean for a probabil ity of error real arg1 7 Run ensemble positive distance of confidence measure from run ensemble mean for a probabil ity 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
120. Example Implementation for the Experiment Post Processor User Defined Operator matmul f c 239 Fortran Implementation ici iecce bored os ke ceed ccbee Papa ees sau eun es En rttr tnter Dee LER Cea aR Ra B e a E ERERL Dres 239 Sx Lusia p X M 242 Example for an Experiment Post Processor Result Import Interface ssssssssssssessss 245 Experiment Post Processor Built In Operators ssssssssssssssssseseneeeneneee neret enne nenne 247 Experiment Post Processor Built In Operators in Thematic Order sees 247 Experiment Post Processor Built In Operators in Alphabetic Order eene 251 Character Arguments of Experiment Post Processor Built In Operators esenee 255 Constant Arguments of Experiment Post Processor Built In Operators 257 Experiment Post Processor Built In Unit Invariant Operators eeeee m 258 Additionally Used Symbols for the Model and Operator Interface ssssesee 259 GIOS SAV pec Em 261 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Vii Tables 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 Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab Tab
121. 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 differ ence derivative approximations from M For numerical validation purposes model analysis sub model sensitivity m ulti Run Simulation Environment SimEnv ser Guide for Version 3 an 25 T gt I Multi Run Simulation Envi SimE U Guide for Version 3 1 Jan 25 2013 21H Sf 1 e Bayesian technique Bayesian calibration Reduce uncertainty about factor values by deriving a representative sample from factor prior distri butions while having measurement values from the system available for model measurement comparison For uncertainty analysis and reduction with a Bayesian technique e Optimization Simulated Annealing Determination of optimal factor 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 f
122. I YS CONIC p4 default Ze factor p4 sample ciste N Sore P9 factor p4 sample include 3 9 4 1 sample only within the 30 interval specific runs 10000 chain length Example file world edf BAY BC Example 6 8 Experiment description file model edf for BAY BC general descr settings 1 multiple case general descr 3 multiple setting case general settings il or 3 general method metropolis reflected general cov matrix ixl bay DC COW likelihood lf atmo model output Gud JL 00 1 retento 5 5 CHT l 8 116 16 values in total likelihood lf atmo data world dat BAY BCl likelihood JE degno model output Sum JE ODE likelihood I TOS model output loatexs CSOs 1 9 1 08 10 3 1 8 9 6 values in total likelihood IEOS data world dat_BAY BC2 Example file world bdf Example 6 9 Bayesian calibration description file lt model gt bdf Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 lt model gt run bin sh SSE HOME bin simenv ini sh my model is a model that is initialized calibrated for a setting by the Tilg getting KSSneiewiave 1016 5 imi only for the multiple case running the model only in setting 1 my model lt setting l ini only for the multiple setting case running the model for all settings SSE HOME bin simenv bay bc sh my model setting run sh SSE HOME bin simenv end sh User shell script my model setting run
123. LE 2 5 157 1L SAN DIEGO 2 o3 IS WA G SCALAR F 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 Gg emm LOOM 5 VARIABLES X I J shipment quantities in cases Z EOL rails pOmeciatOnmCoOst Seine eNO sando koi kao MEES POSITIVE VARIABLE X EQUATIONS COST define objective function SUP PAs as observe supply limit at plant i DEMAND J satisfy demand at market j COSTER A a SUMI Q5 Cr EN SUPPLY T SUUM IS 2 Er d ZES XE 2 DEMAND J SUM T X T B T 7 MODEL TRANSPORT ALL SOLVE TRANSPORT USING LP MINIMIZING Z ii TT n m Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 sub models sub ml and sub m2 are coupled cf Example 5 3 call gams sub ml gms ll lo 2 lf sub ml nlog dp 0 Optdir call gams sub m2 gms ll lo 2 lf sub m2 nlog dp 0 Optdir Example file gams model gms Example 15 9 Model interface for GAMS models model gams mode
124. Operators Tab 8 8 Built in advanced operators Argument Argument Name Meaning eeo value Example result description restriction Tab 8 1 page 118 classify classify arg4 into int arg1 1 classify int arg1 classes 10 real arg2 potentially restrict classi diMarg4 gt O 0 real arg3 fication to interval int arg number of classes 0 arg4 real arg2 real arg3 2sint arg1s atmo number of values of arg4 0 automatic determination number of classes max 2 nmb 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 dimarg2 gt 0 clip char_arg1 char_arg1 dimes Xtres i depend on char arg1 NO E lu l0f arg2 and arg2 atmo char arg1 7 clip range cumul cumulate compute par 1 cumul char_arg1 tial sums of arg2 0001 arg2 according to char_arg1 dimarg2 gt 0 atmo char_arg1 cumulation indicator per dimension distr_par get for experiment types 7 distr par char_arg1 with probabilistic sam po 2 int_arg2 pling the value of a fac char_arg1 factor name tor s distribution parame int_arg2 number of the distribu ter tion parameter lt 2 flip flip arg2 according to 1 flip char_arg1 char_arg1 but coordinates are also flipped 0001 arg2 atmo dimargz 20 char_arg1 flip indicato
125. Performance After experiment preparation experiment performance is the second step in running a model inter faced to SimEnv Each multi run experiment 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 node in foreground or in background and controlled by a Distributed Resource Manager synonym job system SimEnv supports the Distributed Resource Managers load leveler LoadL and PBS Torque Experiment performance on the login node is organized in a way that the single runs of the experiment are performed sequentially Experiments under a Distributed Resource Manager control enable assignment of the simulation load of the single runs of the experiment to a number of processor cores in distributed parallel or sequential mode The following conditions are valid when running an experiment For more details check the corresponding Sections e For all experiment settings the user model has to be wrapped in a shell script model run cf Sec tion 7 2 and also Fig 5 1 e The model variables to be output during experiment performance are declared in the model output description file model mdf Output of such declared model variables into SimEnv structures is achieved by the applic
126. RS for factor i i21 k resulting sample point from RS 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 ACOs pi type set factor pl default ile factor pl sample method pseudo factor pl sample cigs 1 125372 AC Onta i9 type set factor p2 default 2 factor p2 sample method stratified factor p2 sample clase IN 2 10 4 ACE One p2 sample include 0 inf ACOs O5 type set factor i93 default e factor jos sample method pseudo factor p3 sample diste Ub 102 12 factor p4 type set factor p4 default 4 factor p4 sample method stratified LaCt p4 sample distr N 4 0 4 PACE ONE 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 1 Jan 25 2013 6 4 Deterministic Factorial Design DFD The experiment specific information for experiment description files in Tab 6 1 on page 69 is defined for a DFD experiment as follows Tab 6 7 Experiment specific elements of an edf file for a DFD experiment line type m mandatory Sub Line Max Keyword Name keyword type line Value Explanation nmb factor lt factor_ sample see 1 val list value list of factor samples name be facto
127. Theoretically with a Monte Carlo analysis moments of a state variable z can be computed as Mz 7 2X9 pdf X dX Xx with Z Xx state variable z as a function of X pdf X probability density function of X M 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 x of x 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 experiment m x ER Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Y Hi l 2T Tab 4 3 Statistical measures
128. 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 Other format 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 performance 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 files 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 resul
129. 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 a 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 asa96 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 of Output from a Computer Code Technometrics 221 239 245 Morris M D 1991 Factorial plans for preliminary computat
130. User Guide for Version 3 1 Jan 25 2013 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 methodologi cally sound and pre formed manner applying sampling techniques e Runensembles 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 be tween 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 ex periment 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 Mathe matica and GAMS models e Support of distributed models Independently on the kind distributed model components are interfaced to SimEnv and am
131. _exclude intervals specified in lt model gt edf Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 pro vided Sequence of rows and columns of the matrix is determined by the sequence of factors in lt model gt edf Line number i i 1 k for k factors of the file has to have i values where value no j j 1 i 1 is the covariance 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 de rived from the corresponding distributions as defined by the sub keyword sample in lt model gt edf sample include sample exclude intervals as potentially also specified in model edf are not taken into account for deriving the variances For the file syntax check Section 12 3 on page 208 Sub keyword jump length From the last accepted point of the chain of visited points a new candidate point is constructed by a multivariate normal jump The length of the jump can be modified by the specified multiplier value while
132. 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 e 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 Example avg pl min p2 normally differs from min p2 avg pl e Anunused experiment factor in the selection and aggregation filter contributes with an additional di mension 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 additional dimension corresponds to the number of selected values of this factor by the select opera tor Consequently an empty character string arg1 forces to output the operand arg2 over the whole fac tor space of the experiment e The name of the coordinate that is assigned to an additional dimension is the name of the corre sponding factor Coordinate description and coordinate unit cf Section 5 1 on page 37 are associ ated with the correspondi
133. ab 8 8 126 real arg3 arg4 clip char arg1 arg2 clip arg2 according to char arg1 advanced Tab 8 8 126 cnf e real arg1 arg2 positive distance of confidence line from run UNC MC Tab 8 13 ensemble mean avg e arg2 3 ri Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T ji 251 On Name Meaning Type See page cor e arg1 arg2 run ensemble correlation coefficient between UNC MC Tab 8 13 145 arg and arg2 cos arg1 cosine trigonom Tab 8 4 121 cosh arg1 hyperbolic cosine trigonom Tab 8 4 121 cot arg1 cotangent trigonom Tab 8 4 121 coth arg1 hyperbolic cotangent trigonom Tab 8 4 121 count char arg1 arg2 count number of values aggr mom Tab 8 5 123 count e char arg1 arg2 run ensemble count UNC MC Tab 8 13 145 count l char arg1 dimension related count numbers of values of aggr mom Tab 8 7 124 char arg2 arg3 arg3 cov e arg1 arg2 run ensemble covariance between arg1 and UNC MC Tab 8 13 145 arg2 cumul char arg1 arg2 cumulates arg2 according to char arg1 advanced Tab 8 8 126 dfd char arg1 arg2 general purpose operator for navigating and DFD Tab 8 11 142 aggregating of arg2 in the factor space dim arg1 arg2 positive difference basic Tab 8 4 121 distr char arg1 int arg2 get distribution parameter int arg2 of factor
134. ace that is gt sampled by an experiment as well as construction of additional output func tions by declaration and computation of results Experiment post processing operator operator Experiment factor 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 sampled in an experiment specific manner Currently available experiment types are gt GSA EE gt DFD UNC MC gt LSA and gt OPT SA Expression result expression Extent ext The number of values for a dimension from the gt dimensionality of a model gt variable or of an operator result in gt experiment post processing Extents are always greater than 1 Model output variables and operator results of dimensionality O do not have an extent 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 GAMS The General Algebraic Modeling System http www gams com 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
135. al array order models for SimEnv model interface functions 39 Elements of a model output description file model mdf eeeeee emen 42 lus carcee 43 Model interface functions for Fortran and C C models seen ene 45 Model interface modules methods functions for Python Java and Matlab models 48 Elements of a GAMS description file model gdf ssssssseee eene eene 54 Model interface functions at shell script level ssesseeneeeenn emen enne 59 Model interface functions at ASCII level ssssssssssssssssesssesseeeeneeee eren nene nnne enne nnan nnn n nnne 61 Built in variables by simenv mod auto f c inc sssss enm emen 65 Elements of an experiment description file lt model gt edf for all experiment types sssuuusse 69 Factor adjustment types in experiment preparation emen 71 Additional elements of lt model gt edf for experiment types with probabilistic sampling 72 Probability density functions and their parameters ccccccceececeeceeeeeeeeeeeaeceeeeeseeeeaaeeeeeeeseseeaeeeeeeeeeees 74 Experiment specific elements of an edf file for GSA EE sssessseseeeeene emen 76 Experiment specific elements of an edf file for GSA VB sssssssse eee nennen 78 Experiment specific
136. ality extents and coordinates as all the non character non constant arguments coordinates all the other non character non constant arguments with dimensionality 0 2 1 dimMres dima Xtres j eXxtarg j for all j coordres j COOrdarg j for all j 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 dimMres diMarg 2 2 eXtres j extarg for alll j coordres j COOrdarg j for all j The 0 dimensional argument is ap plied to each element of the non zero dimensional argument 3 dimensionality extents and coordinates of the dime 0 only non character argument can be arbitrary all non character non constant arguments with dimes 0 4 1 same dimensionality extents and coordinates 4 some non character non constant arguments dimes 0 4 2 with same non zero dimensionality extents and the 0 dimensional argument is applied to each element of the non zero di mensional argument dimensionality extents and coordinates of the first non character non constant argument arg can be arbitrary all the other following argu ments have to have dimensionalities extents and coordinates of this argument or have to have dimensional
137. 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 69 For examples see Example 8 12 and Example 8 13 e Operator run_info The operator run info returns for the character argument run nr the run number of the current single run 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 e Operator transpose The operator transpose enables to transpose an operand that has a dimensionality gt 1 Sequence of ex tents of the transposed result is described by character argument char_arg1 It consists of digits 1 diMarg2 where the digit sequence corresponds to the re ordered sequence of the operator result extents A character argument char_arg1 123 results for the operator transpose in the identity of argument arg2 m err S 134 y HN T J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2
138. ample 8 12 Experiment post processing operator dfd for DFD 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 restriction s Argument value Name Meaning AA Sm result description restriction Tab 8 1 page 118 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 e 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 arg2 weight m s ur Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Y Hi l 1 45 Argument Name Meaning restriction s Argument value result description restriction Tab 8 1 page 118 hgr_e run ensemble dimres diMargs 1 char_arg1 heuristic eXtres j eXtargs j forj 1 diMargs int_arg2 pdf s sepa eXtres diMres number of bins real_arg3 rately calcu coordres diMres char_arg1 real_arg4 lated for each for char_arg1 bin no bin number arg5 index of arg5 coordres diMres valu
139. 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 11 7 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 model 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 11 9 In Example 15 5 on page 230 the Python model world py py is described in detail in Example 15 6 on page 231 the Java model world ja java and in Example 15 7 on page 232 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 99 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 ja m 70 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
140. and or lt model gt mdf see below Attribute is omitted otherwise m S A Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T J 173 long_name lt result_expression gt SimEnv post processor output chain see Section 8 1 1 macros are resolved units lt result_unit gt if defined in result descriptor and or lt model gt mdf see below Check Section 8 1 1 for more information on the approach how missing information on lt re sult_description gt and lt result_unit gt from the optional result descriptor can be emulated from the corresponding information from lt model gt mdf for single operand single operator result expressions e For coordinates in model output or post processor output If NetCDF variable name co name or var name res_ lt digit gt lt digit gt co name see above then standard name descr string if specified in model mdf Attribute is omitted otherwise long_name SimEnv model coordinate units lt unit_string gt if specified in model mdf otherwise where descr string und unit string are the related strings for co name var name res digit digit co name from model mdf or a built in coordinate name see Tab 11 11 The axis attribute is assigned to a coordinate variable and used according to the NetCDF CF stan dard to identify coordinates
141. ar z N boundaries a a probability of error tan significance boundaries of Student distribution heuristic probability density hgr z number of zi with clasSmin lt Zi lt ClaSSmax ClaSSmin ClASSmax boundaries of equidistant classes z8 SIE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 Tab 4 4 Probability density functions Aer ee Short TA ONE Distribution Ut Probability density function pdf Distribution parameters uniform U a b 1 a lower bound pdf x era if x e a b p upper bound gt a pdf x 0 otherwise it is mean atb 2 standard deviation y b a 12 normal N 1 0 i TA u mean pdf x exp H o standard deviation gt 0 oV2n 207 lognormal L 0 2 4 1 E pdf x exp neo P u ifx 0 c 20 XovN2z 26 pdf x 0 otherwise litis In x N z o exponential E mean gt 0 P loaba Lo x ifx gt o Hu Hu pdf x 0 otherwise it is standard deviation 4 The number of runs to be performed during an UNC_MC experiment has to be specified An experiment is described by the factors involved in the analysis their distribution and the appropriate distribution param
142. arg2 absolute linearity measure lin rel char arg1 arg2 relative linearity measure sens abs char arg1 arg2 absolute sensitivity measure sens rel char arg1 arg2 relative sensitivity measure Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Name Meaning See sym_rel char_arg1 arg2 sym_abs char_arg1 arg2 absolute symmetry measure relative symmetry measure Multi run operators UNC_MC also applicable for all other experiment types Tab 8 13 on page 145 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 krt e arg1 run ensemble kurtosis 4 moment max e arg1 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
143. arg4 Both operators were designed for application of an appropriate visualization technique in result evaluation in future The operator stat red was introduced as computation of the median and quan tiles consumes a lot of auxiliary storage space oo RO Having a model output variable definition as in Example 5 1 on page 44 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 86 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 ava tatem o 7 ip 18 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 Wale eco 7 5 7 p io 19820 euo 57 Io 19820 anomaly for run ensemble variance from the default nominal run for level 1 the last two decades Dimensionality 3 Coordinates lat lon time Extents 45 90 2 Wee eeu 5
144. at a resolution of level x time 2 4 x 20 gams model GAMS GAMS example model gams model gms Additionally 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 model f c cop py ja m model source code cf also example files in Section 15 2 gms model model executable compiled and linked from model f c cpp world edf GSA EE GSA VB DFD a b c d LSA UNC MC BAY BC OPT SA experiment description files corresponding to the individual experiment types to be copied to world_ f c cpp py ja m sh edf and or world_f_1x1 edf and world_f_05x05 edf world post_ GSA_EE GSA_VB DFD c LSA UNC_MC BAY BC OPT SA Experiment specific post processor input file complete experiment for the corresponding description files world edf_ lt exp_type gt simenv res world f c cpp py ja m sh new append replace world post exp type world post bas adv Experiment type unspecific post processor input file for single run post processing of a selected single run simenv run int simenv res world f c cpp py ja m sh new append replace simenv run int lt world post bas adv world dat DFD d UNC MC adv data files use
145. ated With this it holds the following ANOVA HDMR V Z Xv DIV L aste t Viz and it can be shown that V VE ZIX Vj V EZIXX Vi V Vin s V E Z Xm s P 2 Mrs of lower order Vik V E Z X4 7 V4 k of lower order Dividing the ANOVA HDMR by V Z 1 SES DLS Dw DSy e S42 it holds Si V E ZIX V Z 1 order sensitivity index VE ZIXiX V Z Si S 2 order sensitivity index Si Sm s V E Z Xm s V Z 2525 4 of lower order S4 V E Z X4 V Z i DSi waa 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 sNw Nw 2 1 where Ny is the Monte Carlo sample size Saltelli defined another sensitivity index the total sensitivity index as Sr sum of all terms in that include factor X total effect index and showed that it can be computed by Sri 1 V E ZIX V Z E V ZIX4 V Z Sx is a measure for the total contribution to the output variation due to factor x The smaller S1 S1 0 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 m x AR Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 5j Hi inii J 23 The following properties apply for 1 order
146. atio 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 1 D 1 1 T T T T T 0 20000 40000 60000 80000 20000 40000 60000 s0000 run number run number Fig 4 9 Trace plots of a MCMC chain for one factor Chain length 100000 runs left chain does not converge right chain converges m AA S 32 y HN T J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 As for the experiment type UNC MC the prior distribution is assumed to be decomposed into marginal distri butions pdfp X for k all individual factors k pdfp Xx LI pdfi 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 nonzero covariances as normally they contradict the requirement
147. ation of SimEnv function lt model gt edf in the model 5 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 O error for model smp ternatives 7 wrong single run number m x EZ Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y Hi l 45 Funchoninane Function Arguments Argument function value description function value description 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 reai 4 default nominal factor value as specified in factor def val in the current factor def val model edf factor adj val single run input If factor name is not defined in model 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 current runas simenv run int an integer value output simenv run int anda character character 6 current run number with leading zeros simenv_ string simenv run_char run char output integer 4 return code simenv
148. ation of the generic SimEnv model interface function simenv put and simenv slice in the model source code e The type and the factors of the experiment to be performed are declared in the experiment descrip tion file model edf 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 Model output from run number simenv run int is stored in the file lt model gt out all simenv run char nc ieee For all experiment types a run number 0 with the default nominal values of all experiment factors is declared additionally to the runs described in the experiment de scription file model edf e During experiment performance a model interface log file lt model gt mlog is written where the ad justed experiment factor values are logged All model output to the terminal is re directed within SimEnv to the experiment model native output log file model nlog During experiment perform ance an experiment log file model elog is written with the minutes of the experiment e The status of any running experiment can be acquired by the SimEnv service simenv sts For more information check Tab 11 4 After the experiment has been finished an email is sent on demand cf Section 11 1 to the address as specified in lt model gt cfg e Experiments may be performed partially only
149. atory for all experiment types with random sampling and for sample distr For sample file the sub key word is undefined A sample method can not be specified for experiment types GSA EE and BAY BC The sub keyword sample method allows to select the random sampling method to be applied indi vidually for each factor For pseudo random numbers a deterministic algorithm is used that ap proximates the properties of the given factor s distribution by a sequence of generated numbers The sequence depends 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 its distribution is divided into val int from the sub keyword runs intervals of equal probability according to the given distribution From each interval exactly one sampling point is drawn The sampling point within each interval is drawn with a pseudo random number approach The quasi random sampling is based on the usage of pre defined Sobol sequences Sobol 1967 amp 1976 for the interval 0 1 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 qualifies it for numerical integration For quasi random sampling the
150. b 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 Operator classify The operator classify transforms the values of an operand arg4 that has dimensionality gt 0 into the class numbers 1 int arg1 of int_arg1 classes Classes are assumed to be equidistant If both arguments real arg2 and real arg3 are equal zero then min arg4 forms the lower bound of class number 1 and max arg4 forms the upper bound 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 bound range Operator clip The operator clip clips an operand arg2 that has dimensionality gt 0 The portion to clip from the operand arg2 is described by the argument char arg1 The argument char arg1 uses syntax for model output variable addressing cf Section 8 1 3 on page 114 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 unequal 1 in the model output description file In general extents differ between the res
151. b keywords from Tab 12 4 can be used to struc m S aa Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T i 129 ture 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 column major order 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 character argument char arg3 is an optional argument Unlike for ASCII data files the keyword modify is allowed Having a model output variable definition as in Example 5 1 on page 44 and assuming a data file data asc as data file with 6 values IO 20 30 40 5 50 EEG 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 ilies assign as first dimension a new coordinate new coord assign 1 coord new_coord assign 1 coord extent 1H 0 8 8 1L 9 coordinate new coord values liest L00 TET then get_data ascii data asc data def dummy has Dimensionality 2 Coordinates new_coord time Extents 2 3
152. b mode for best utilization of all job class processor cores m E Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN Tl 103 e On pre allocated processor cores of a class queue 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 queue During the experiment one communication proces Sor core 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 available in this class queue 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 Onone pre allocated processor core of a class seq sequential sub mode SimEnv also offers a sequential sub mode under control of the Distributed Resource Manager One processor core of a job class queue is assigned to the whole experiment and the experiment is per formed sequentially on this processor core The experiment performance will start when one proces Sor core of this job class queue is available After an experiment was submitted to the Distributed Resource Manager the current login session can be closed Default job control files are supplied b
153. basic Tab 8 4 121 char arg1 effects 1st arg1 linear effects of all factors for arg1 Tab 8 10 139 effects tot arg1 total effects of all factors for arg1 Tab 8 10 139 ens arg1 whole run ensemble UNC MC Tab 8 13 145 exp arg1 exponential function basic Tab 8 4 121 flip char arg1 arg2 flip arg2 according to char arg1 advanced Tab 8 8 126 get data char arg get data from an external file advanced Tab 8 8 126 char arg2 char arg3 arg4 get experiment char arg1 include an other experiment advanced Tab 8 8 126 char arg2 char arg3 arg4 get table fct char arg table function with linear interpolation of table advanced Tab 8 8 126 arg2 char arg1 for position arg2 gsa vb run mask select sub sample to apply to subsequent GSA VB Tab 8 10 139 char arg1 UNC MC operators hgr char_arg1 int_arg2 argument histogram of values aggr mom Tab 8 5 123 real_arg3 real_arg4 arg5 hgr_e char_arg1 int_arg2 run ensemble heuristic probability density UNC_MC Tab 8 13 145 real_arg3 real_arg4 arg5 function hgr_I char_argi char_arg2 dimension related argument histograms of aggr mom Tab 8 7 124 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 126 int arg1 integer truncation value basic Tab 8 4 121 krt e arg1 run ensemble kurtosis 4 moment UNC MC Tab 8 13 145 lin abs char arg1 arg2 absolute linearity measure l
154. ber string current run number as string of the length 6 with get_run_ of the current run simenv get run leading zeros pylja m as a string D If an error occurred then function value j 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 Ver Darme file s declaration of data of variable var name to be stored as simula field field tion results according to model mdf input string py return code int ja m 0 ok simenv put 0 an error occurred function value ES 3 ri 48 y H T f l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Function name Function Arguments Argument function value 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 pylja m corresponding input simenv put int dimension to be sliced var name call only a slice of igim idim variable var_name input ifrom This announce THESE ito ment becomes int slice to start at position ifrom inactive after per ifrom ifrom corresponds to an index from index_extents formance of the input in lt model gt mdf corresponding int slice to end at position ito simenv_put_ ito ito corresponds to an index from index_extents in input lt mo
155. bility density function serves to represent a probability distribution in terms of integrals A probability distribution assigns to every interval of real numbers a probabil ity Python Python http www 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 result Row major order model A rule how to store the elements of a multi dimensional data array to a 1 dimensional linear vector representation and vice versa gt column major order model Sample A set of numerical factor values created during experiment preparation or performance Shell X 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 scrip
156. ble 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 11 5 at page 188 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 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 direct is allowed 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 sp
157. cing is sup ported at the programming language level for C C Fortran Python Java Matlab Mathematica and GAMS programming languages the model is implemented in and at shell script level 5 1 General Approach The 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 model edf cf Section 6 1 have to be associated to the corresponding model source code entities parameters initial values drivers When performing the model these entities are modified numerically by the sampled values and the default nominal values of the factors according to the specified factor adjustment types The process of such a modification is called 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 model 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 mode
158. ck 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 3 3 on page 104 To declare runs for in cluding into a SimEnv experiment use either sub keywords begin run and end run or sub keyword include runs For begin run and end run assign appropriate run numbers Make sure that begin and end run values 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 of the whole run ensemble Alternatively 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 be gin run end run include 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 d
159. clude i 0 6 i GOs FME 102 15 LAC TOT po descr equivalent to p4 factor po sample distr N 0 0 04 LECTOR i95 sample include 0 680 6 factor p5 sample exclude adt sdb IEEE p6 descr sample from 5 inf ACIEONS p6 sample diister Em OF Oe A factor p6 sample exclude POSSE S5 XXX any value S 0 Example 6 2 Include exclude for probabilistic sampling in an experiment description file lt model gt edf ra Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Save 75 6 2 Global Sensitivity Analysis Elementary Effects Method GSA_EE The experiment specific information for experiment description files in Tab 6 1 on page 69 is defined for GSA_EE experiments as follows Tab 6 5 Experiment specific elements of an edf file for GSA_EE line type m mandatory o optional Max Keyword Name k atr bine ine 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 real valq lower bounds real val and include real val47 upper bounds real vali of EEEE intervals to include for sam lt real_valn gt pling according to distribution lt real_val 2 gt lt distribution gt real vali lt real vali sample _ 0 1 real val4 lower bounds real val and exclude real val427 upper bounds real vali
160. code and or e forthe model interface at the shell script level and ASCII level as a dot script in model 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 model cfg cf Section 11 1 The Fortan C C Python model interfaces offer to use different names of corresponding factors in the model description file model 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 model f c sh as inc and model 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 model edf the source code sequences have the f
161. 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 file name 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 coord file name in simple mode coord coord Name of a model output variable coordinate simenv put as input Lines in file name correspond to coordinate simple is a values If coord is not specified file name 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 model as simenv run char holds lines with a factor name and its resulting adjusted value per line Each factor name is separated 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 model 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 model mdf Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Having
162. ctor names and their adjusted values in an ASCII file 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_as 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 factors to be ex perimented with in the current single run lt simenv_run_ char gt output names and resulting adjusted values in the form lt factor_name gt lt factor_adj_val gt Sequence of the factor lines in the file corresponds to the sequence of the factors in the experiment description file model 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 coord lt coord gt Name of a model output variable coordinate simenv_put_as is input Lines in lt file_name gt
163. d 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 Sub keyword sample distr distribution For implicitly specified distributions according to Tab 6 4 sample values factor smp val are generated from the distribution with the assigned distribution parameters For distribution distr shortcut distr param 1 distr param 2 check Tab 6 4 file directory2 file name For explicitly specified samples by an ASCII file directory2 file name the sample values of any distribution are taken directly from this file Each record of the ASCII file can hold only Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 syntax rules for ASCII data files check Section 12 3 Sample size has to be identical to val int from the sub keyword runs Explicitly specified samples can not be applied for experiment types GSA EE and BAY BC Sub keyword sample method The sub keyword is mand
164. d are the indices of model output variable bios lat lon time for the appropriate grid cells 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 Tab 5 5 Model interface functions for Fortran and C C models Function name Function Arguments Argument function value description function value description simenv initialize model integer 4 return code ini f c coupling interface simenv_ini_ 0 ok flc 1 warning function multiple called function value only the first call is executed 2 O error for experiment output file 3 error memory allocation 4 Perform always I O error for simenv_edf_bin tmp as the first as the structured represent
165. d in world edf DFD d UNC MC and or world post adv Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 File Explanation usr_opr_ lt opr gt f c source code for user defined operator lt opr gt usr_opr_ lt opr gt executable for user defined operator lt opr gt land_sea_mask nil 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 nil f executable and source code for the result file import interface of ASCII and IEEE compliant result output 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 opr c are imple mented in Fortran and available as source files usr opr opr f Tab 15 6 Available user defined operators Pps iior TEME Operator arguments Explanation Example opr gt char_test char_arg1 character test char test argll 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
166. dditional examples check Example 10 4 S SHEY Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Having a model output description file as in Example 5 1 and an experiment description file DFD_aas in Example 6 5 then a NetCDF attribute definition file world ndf could look like replace global attribute SimEnv_model glob_attr replace SimEnv_model text my own model description replace in model output for factor p1 text attribute units lioe uelis pi replace units text new unit define in model output for all variables text attribute new attr 1 loc attr amp v amp nepllacegenewlat M text new attribute 1 text delete in model output for variable atmo text attribute new attr 1 locfa ter Eat delete new attr 1 define in model output for variable bios float attribute new attr 2 with 3 values iro eratis bios replace new attr 2 loge list 314 1 6 12 47il delete in post processor output for all results text attribute standard_name loce cuti iets delete standard name Example 10 4 NetCDF attribute definition file world ndf 10 2 IEEE Compliant Binary Model Output IEEE compliant binary model output is written in records of fixed length to files e model out ssimenv run char ieee and or e model 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 mode
167. dditional rules and explanations apply e The sequence of the four integer values int val4 int val4 follows the sequence of arguments in built in user defined and composed operators e The sum int val int val4 has to be less equal 9 e Use the SimEnv service simenv chk to check user defined and composed operators Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 general descr Operator description for the general descr examples in the SimEnv User Guide opr defined matmul f descr netii milciolication aim Fortrenn opr defined matmul f arguments OPO One opr defined matmul c descr merri malci l icercion am opr defined matmul c arguments omor 0 2 opr defined Corr COSTE descr oscila opr defined Corr CORE arguments O O 0 2 opr defined div descr arithmetic division opr defined div arguments 0 0 0 2 opr defined simple div descr division without undefined check opr defined simple div arguments 07 0 0 2 opr defined chiamate sit descr test character arguments opr defined Chareecsic arguments 25 Oy Op 1l opr composed rel count descr relative count opr composed rel count arguments 1b 7 9 01 11 opr composed rel count define 100 count argl arg2 opr composed rel count define Coun ala ener Example files world_ f c cpp py ja m sh J odf Example 8 18 Operator description file lt model gt odf
168. del gt ini for ex periment restart begin_run o 1 val int begin single run number end run 1 last val int end single run number include runs o 1 lt val_list gt single run numbers to include in the experiment exclude_runs 0 1 lt val_list gt single run numbers to exclude from the experiment email o 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 o 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 o 1 strong weak post processing coordinate without check by operators opr_directory o 1 directory directory the post processors expects user defined operator executables factors in output o 1 yes no determine whether factor val ues are stored in SimEnv model output display values 0 1 lt val_int 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 11 2 the following additional rules and explanations apply e For keyword Message output is controlled by this information general sub keyword message level Specify X info to output errors and warnings and additional informatio
169. del gt mdf int return code simenv slice 0 ok function value 20 an error occurred simenv close model string py return code end coupling interface int ja m 0 ok pylja m simenv end Perform always function value as the last SimEnv function in the model To Tab 5 6 the following remarks apply 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 For multi dimensional model output the simenv_put_m function expects the output stored in a model source code array the field as described in Tab 5 6 according to the column major order model cf Section 15 7 Glossary that is used by Fortran by default For Python Java and simenv put py simenv put ja the row major order model cf Section 15 7 Glossary used by Py thon Java by default is expected The sequence of the dimensions of the source code array is de termined by the sequence of the coordinates for the associated variable in the file model mdf check Section 5 2 Model output variables that are not output completely or only partially within the user model are han dled in experiment post processing as their corresponding nodata values cf Section 11 8 Application of simenv slice py ja m demands a corresponding slice entry in the configuration file model
170. del interface sssssssssssssssseseseee en enneeneeentnnnnee 259 Additionally used symbols for the operator interface ssssssssssssssseseseee nennen nnne 259 DIMENV SYSLEMGESIGN 13 08 OR 2 Fact r SPACG M 16 izcpWeleiemctl mius 20 Sample for GSA EE Sample for GSA VB 25 Sample tor DED soira e DFD examples for scanning multi dimensional factor Spaces sss eee 26 Sample for UNG MG ssion T 27 Sample f r LSA c 30 Trace plots of a MCMC chain for one factor nennen nnne nnns 32 Part of a sample for OPT_SA generated during the experiment ssssseseeeee 35 Conceptual scheme of the model interface for C C Fortran Python Java and Matlab 40 ENOAT c E E E 41 Model output variable definition Grid assignment ccccccceesecceceeeeeeeeeeeeeeeeeeesecaeaeeeeeeeseceasaeeeeeeeeeeeees 45 Probabilistic sampling Pseudo and quasi SAMPpIing ccccccceecceceeeeeeeeeeeeeeeeeeesecaeaeeeeeeeseeecenaeeeeeeeeneeea 74 Probabilistic sampling Latin hypercube sampling esee emen 75 Flowcharts for performing simenv run and simenv rst
171. dimens ide aL kk lpi ae see amie dergil ofris ierg uei melt leute iEl yen teil EIC 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 gera cy MEOS aei rese d NONE oie Gh eabatre sE d amp abs Ese akeuee il ortesi fo Tees a k eese at d 39 wee Lo value820 indi defined 0 for 1 1 1 lt iext1 1 1 ateubeabewesb Outcry l iL eese di O diei iLenuop Oier facl simenv get arg c 1 ial fac2 simenv get arg c 2 ia2 if simenv chk undef c facl simenv chk undef c fac2 indi defined ale qe oreet ded r8fac2 fac2 value8 value8t r8facl r8fac2 lieu 0 m m oe Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 JHN mh j 243 iesiewiein yp m m 1 if indi defined 0 res m 1 simenv put undef c 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 out
172. distr distribution and distribu name distribution tion parameters to derive file lt directory gt a sample of values file name factor smp val file file name to import an external sample of val ues factor smp val sample _ see 1 pseudo random sampling method method be stratified only for distr lt distribution gt low quasi sample __ Oo 1 real val4 lower bounds real val and include real val427 upper bounds real vali of CEU intervals to include for sam real valy pling according to distribution lt real_val 2 gt lt distribution gt real vali lt real vali sample _ 0 1 lt real_val 41 gt lower bounds real val and exclude real val427 upper bounds real vali of MECR intervals to exclude from sam real val pling according to distribution real valgo distribution real vali lt real vali specific nil seed o 1 random fixed method how to initialize the random number generator 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 according 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 ad
173. during experiment post processing only for value yes of sub keyword visualization in model cfg simenv get experiment exc SE WS experiment post processing auxiliary file for operator get experiment simenv tmp SE WS all services auxiliary files Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Fig 11 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 model mdf lt operator gt opr lt model gt run lt model gt rst lt model gt ini lt model gt end lt model gt gadf lt model gt edf lt model gt mac model bdf lt model gt odf lt model gt ndf lt model gt ndf lt model gt cfg Model description d Model Interface 2 User macros and operators Experiment description General configuration P P Experiment Experiment Experiment Preparation Performance Post p processing Experiment Evaluation j Supported formats NetCDF CF IEEE binary ASCII ont tor Port proce stor Visualize results lt model gt out lt model gt res lt model gt inf Experiment outputs Post processor output lt model gt smp lt model gt elog l
174. e loginO1 iplex 01 sys applications simenv Impact Research PIK login02 www pik potsdam de PIK viss02 pik potsdam de iplex 01 sys applications simenv www pik potsdam de PIK bs08 pik potsdam de usr local simenv www pik potsdam de TU Berlin drawe evur tu berlin de drawe opt simenv www evur tu berlin de Global Climate Forum opt simenv www globalclimateforum org Multi Run Simulation Environment SimEnv EY User Guide for Version 3 1 Jan 25 2013 y HN T J J 11 3 2 Limitations Problems and Their Workarounds Tab 3 4 Limitations problems and their workarounds in Version 3 1 Where Limitation nti Problem Description Workaround Where Overall Limitation Current SimEnv technical limitations as specified in Tab 15 3 on page 219 Workaround None Where Overall but visual result evaluation with SimEnvVis Limitation Without graphical user interface Workaround None Where 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 11 3 Where Experiment performance Under Distribut
175. e 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 12 3 For restrictions in the path to the directory of the character argument char arg1 see Tab 12 3 Check the table function world dat adv in the example directory SE_HOME exa of SimEnv for more information e Operator if The operator if supplies a general conditional if construct It operates for each element of the operand arg2 in the following way if condition char arg1 arg2 then arg2 defined arg2 undefined char arg1 def char_arg1 undef res arg3 else res arg4 endif with condition char arg1 arg2 arg2 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 e Operator mask The operator mask supplies a method to mask to set undefined elements based on their values It op erates 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 arg3 char arg1 lt arg2 lt arg3 char arg1 lt arg2 gt arg3 char arg1 gt arg2 2 arg3 char arg1 gt arg2 arg3
176. e 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 m x AA Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y Hi l 29 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 positive e from the neighbourhoods 4 Em two members X X4 XitEj Xia 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 model enlargements
177. e adaptation the following simple changes have to be applied to the model e For Fortran and C C models Link the model with the object library SE_HOME lib libsimenvdummy a instead of SE HOMEllb 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 e For Python models Replace in the model source code from simenv import by from simenvdummy import For these modules e Simenv get py forwards factor def val to factor adj val e Simenv get run py returns run 000000 e allother SimEnv model interface function values return codes are 0 e 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 codes are 0 e 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 r
178. e by one of the operators or An explicit stated combination combination is normalized before running the experiment in the fol lowing sense e Segments of combination that are separated by the operator arbitrary order ki can be re arranged in an Example p2 p1 is equivalent to p1 p2 e Factors that are scanned in parallel can be re arranged in an arbitrary order Example p4 p3 p2 p1 is equivalent to p3 p4 p2 p1 S AO Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T l 81 e combination is rearranged in a way that factors are used in the sequence they are declared in the experiment description file Example If four factors are declared in the sequence p1 p2 p3 p4 then the explicitly stated combination p4 p2 p3 p1 is normalized to p1 p3 p2 p4 e 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 For comb file lt directory gt lt file_name gt The sequence corresponds to the sequence of the sampled factor values in the file file name For comb combination with the normalized combination x4 x2 x and x X8 Xo so X 15 Xi Hor fori 1 N loop over all factor sample values Xp j 1 n for x ron
179. e eeeeeeaeceeeeeseseeeaeaeeeeeseseesaeaeeeeeees 44 GAMS description Tile lt MOdel gt Of iis ccicccsccssccnsscctmets sreecsnacetesanceenusaeendsucds iian aiaei iaiia hiaai 56 GAMS description file for coupled GAMS models sse eene 56 Model output description file for a GAMS model sse emen 57 Addressing factor names and values for the model interface at shell script level 60 ASCII file structure for the ASCII model interface sssssseeee emen 62 Shell script model run for a parallel model ssseee nee 66 General layout of an experiment description file model edf Include exclude for probabilistic sampling in an experiment description file model edf I5 Experiment description file model edf for GSA EE sese enm eee 7T Experiment description file model edf for GSA VB sse eene 79 Experiment description files lt model gt edf for DFD experiments sssssssssseeee 83 Experiment description file model edf for UNC MC ssssseeemme emm ene 86 Experiment description file model edf for LSA sssssssee eene menm nennen 87 Experiment description file model edf for BAY BC sse emm 93 Bayesian calibration description file model bdf ssseee emen 93 model run for BAY BC ere ter
180. e extreme is reached the first time according to the processing sequence of the argument field arg by the column major order model cf Section 15 7 Glossary hgr char_arg1 int_arg2 real_arg3 real_arg4 arg5 one heuristic pdf from all values of arg5 dimres 1 Xtres 1 number of bins no _of_bins coord es 1 char arg1 for char arg1 bin no bin number coord 1 values equidist end 1 1 no of bins for char arg1 bin mid bin mid coordres 1 values equidist end 1 bin mid bin width no of bins char arg1 bin_no bin_mid int_arg2 no of bins 4sint arg2 x no of values or 0 automatic determination no of bins max 4 no 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 O determine bounds by min arg5 and max arg5 min arg5 max arg5 all result values are undefined Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 118 max n arg1 arg2 arg3 argn min_n arg1 arg2 arg3 argn maxprop n arg1 arg2 arg3 argn minprop n arg1 arg2 arg3 argn return per result element
181. e 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 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 e During experiment preparation the file model simenv put inc and during experiment performance files model simenv getinc 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 language level cf Sections 5 4 and 5 5 e The GAMS include statement include model 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 Direct
182. e whole ex periment Choosing experiment performance in the background a temporary shell script is generated by SimEnv that represents the simulation experiment as a whole This shell script is submitted as a cron job to the 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 correspond ing experiment After experiment preparation the login session can be closed For background per formance make sure to have rights to manage cron jobs on the node the experiment is started from e distributed on the multicore login node mcore multi core sub mode For a multi core processor login node 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 lat ter a cron job is generated which is removed from the cron job list directly after the start of the cor responding experiment For cron job submission make sure to have rights to manage cron jobs on the node the experiment is started from As for background sub mode in multi core sub mode the login session can be closed after experiment preparation 7 3 2 Experiment Performance controlled by the Distributed Resource Manager SimEnv enables the parallelization of the experiment in the sense that several single runs can be performed in parallel without influencing each other This open
183. e with IS SE HOME inc asmeitucdesersmimenvaso prim eu c declare fields to hold extents and coordinates dimension iext1 9 iext2 9 cgmensmongte onde 6D yee omm RO dimension ico beg posl 9 ico beg pos2 9 character 64 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 stmeny Get CO arg 1 1600 Aril LeO beg pOSle 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 idimensi1 ne 2 or idimens2 ne 2 then c wrong dimensionalities ierror else if iextl 2 ne iext2 1 then c wrong extents ierror 2 else iit bero aauedi 2 stexers ico nra il then c coordinates identical slit Ete ome POEL ec eo Insc jos L Then 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 20 iextl1 2 1 c get coordinate values iretvl simenv get co val f it ico nrl1 2 ico beg posl 2 j valuel iretv2 simenv get co val f it ico nr2 1 ico beg pos2 1 j value2 Q4 m S mae Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 My HN PI 239 c iret 33 diffe
184. each result Record Record length Record contents File header 1 33 max 10 characters used SimEnv Version 2 33 max 465 characters user workspace prefixed by user name and login node 3 33 20 characters timestamp Result number 1 4 33 max 1024 characters result name string same as the NetCDF variable name for post processor output Section 10 1 2 5 33 max 128 characters result description string same as NetCDF attribute standard name for post processor output Section 10 1 2 6 33 max 1024 characters result operator string same as NetCDF attribute long_name for post processor output Section 10 1 2 7 33 max 32 characters result unit string same as NetCDF attribute units for post processor output Section 10 1 2 8 33 characters 9 int values extents ext 1 ext dim 0 0 of the result 9 33 max 64 characters coordinate name of dimension 1 10 10 float values ext 1 coordinate values of dimension 1 in records of 10 values last record may have less values XXX 33 max 64 characters coordinate name of dimension dim XXX 1 10 float values ext dim coordinate values of dimension dim in records of 10 values last record may have less values Result number 2 The 33 characters prefixed in most of the records hold information on what the contents of the record is Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Record structure of lt model gt
185. ected 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 specification sequence in the corresponding experiment description file model edf e f more than one factor increment value and or sign was selected by the filter argument arg1 it con tributes with an additional dimension to the result of the LSA operator e For factors an additional dimension factor_sequ 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 ex tent of this additional dimension corresponds to the defined and or selected number of factors in crement values and or signs For a definition of the additional dimensions check Tab 11 11 Firstly dimension factor_sequ is appended on demand secondly dimension incr and thirdly dimen sion sign m AER 150 Y HN T J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Having a model output variable definition as in Example 5 1 on page 44 and assuming address_default coordinate in lt model gt cfg Assume the experiment description file LSA from Example 6 7 on page 87 then in result processing sens abs atmo g absolute sensitivity measure for atmo g for all factors increments and signs Dimen
186. ed Resource Manager DRM 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 model cfg Workaround Perform experiment at login node or under load leveler DRM control in an other sub mode 3 m 12 3 HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 3 3 Known Bugs and Their Workarounds Tab 3 5 Known bugs and their workarounds in Version 3 1 Where Bug Description Workaround Where Experiment performance Experiment type UNC_MC with stopping rule under Distributed Resource Manager DRM control in distributed sub mode dis or on the login machine distributed on a multicore processor machine Bug Experiment may not come to an end Workaround Use an other experiment performance setting 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 unmask_file Bug Do not work with the coordinate range c coordinate value lt coordinate_valuez gt Workaround Use index range i index value index valuez instead
187. ed 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 model 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 two C C or Fortran functions cf Tab 8 18 e Function simenv check user def ope
188. eeeeseeaaeeeeeeeseseecaeeeeeeesnceaeeeeeeeseeeeea 126 Experiment specific operators for GSA EE sse enne ener nennen 138 Experiment specific operators for GSA VB sss eee eene ener enne nennen 139 Experiment specific operators for DFD cesccceeseeneceedeeeeseadeceedecdeeeedendeenedeedusseceecessedeesescedeedenneeensnseetee 142 Syntax of the filter argument 1 for operator dfd ssssssssseeeneen emere 142 Experiment specific operators for UNC MC ssssssseeeeeenn eene nnnm nennen 145 Experiment specific operators for LSA ssssssssseeee ene eene eene nnne enne enne 149 Syntax of the filter argument 1 for LSA ssssssssssseseeeene eene eene nnne en nennen nnne nnns 150 Experiment specific operators for BAY BC sssssssesseseeeenenen eene nennen e enne ementi 152 Experiment specific operators for OPT SA sssssssssseseseeeene eene mene enne emnes 153 Operator interface functions for the declarative and computational part seeeeeeee 158 Operator interface functions to get and put structural information 156 Operator interface functions to get check put arguments and results 159 Elements of an operator description file model odf sssssssssssssseseseeeeeeeener eene 162 Elements of a macro description file model mac sseseeeenmene eene eene 164 NetCDF data type S rice cause
189. efining a 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 and the corresponding optional result descriptor for both check Sec tion 8 1 1 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 experiment factors respec tively 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 The same applies to the optional result descriptor m AER S 164 y IM T f l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 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 by I begin of result string and e postfixed by 1 end of result string Having a mod
190. efinition in model 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 always a complete address For keyword X 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 X postproc sub keyword coord check During 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 X 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 val ues 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 mul tidimensional result output the first values according to the co
191. eib Tok sineny Get CO arg ct comi 1C Mp SOM ame ichk modus simenv get co chk modus c if idimens1 2 idimens2 2 ierror 1 wrong dimensionalities else if iextl 1 iext2 0 ierror 2 wrong dimensions else alae Lee aedi 1 eeshexo 30362 0 if ico beg posl 1 ico beg pos2 0 iret 31 else iret 33 coordinates identical else f abxexEe 9p differing coordinates if ichk modus 1 oie 939p ak Ibl asp v5s Gub kor weak ea Check 97 get coordinate values iretvl simenv get co val c n eommemusereomoegseposiasiiehsrreszasiiu ey iretv2 simenv get co val c ico nr2 0 ico beg pos2 0 5j amp value2 ps irec 339s olbirseteucabolor Coordinate Wellies 7 if valuel value2 iret 33 aap NANA 242 J I T 1 J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 ierror 0 if ichk modus 2 if iret 31 ierror 3 else if ichk modus 1 Iie aS SD aleueweoie 3 9 if ierror 0 iextl1 1 iext2 1 3e mer see inse EET 8 t00 e0 mPOA Pa cob edgaepos Pale MOS SB TAE ties rau ce S ei O sie edem emere es eic Omnia y atc oM e qao ose 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 i
192. el gt ndf amp amp e amp c amp and amp v amp or amp r amp e var name or co name and within each processing step if specified first for delete and afterwards for replace loc attr amp amp replace lt attr name gt text lt string gt to define for each variable lt var_name gt and each coordinate lt co_name gt an attribute lt attr_name gt with the value lt string_ gt loc attr amp v amp replace attr name text string v afterwards to overwrite for each variable var name the attribute attr name by the value string v loc attr var namel replace attr name text string var namel afterwards to overwrite for variable var name12 the attribute attr name by the value string var name loc attr lt var_name2 gt delete attr name and to delete for variable var name2 the attribute attr name Example 10 3 Processing sequence of the NetCDF attribute definition file All global attribute values are of data type character which corresponds to the identifier text in lt model gt ndf Local attributes allow besides character attributes for numerical data type attributes identified by byte short int float and or double Numerical values of the corresponding type are declared after the type identifier in an explicit value list see Tab 12 5 as lt val_list gt list lt val gt lt val gt For a
193. el output variable definition as in Example 5 1 on page 44 and assuming the experiment description file DFD b from Example 6 5 on page 82 then in result processing ool 9 7 eam es results in dfd sin atmo Chea V sima loaLios i CEEA ein ene 6 GUEOL A nsi o3 Ch dfd amp v amp amp f amp results in ohtgl u ext 9L etel esee dfd atmo g p1 GHEOL lodo gr cite rato 92 e 7 j9so8 92 AC GT EMO pe S sel V loos G2 Example 8 20 Experiment post processing with wildcard operands 8 8 Undefined Results By performing operator chains and due to possibly undefined 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 Section 11 8 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 m S aa Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 SHF 165 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 9 Visual Experiment Eval
194. elemental Tab 8 3 120 arg1 identity elemental Tab 8 3 120 arg1 negation elemental Tab 8 3 120 arg1 parentheses elemental Tab 8 3 120 abs arg1 absolute value basic Tab 8 4 121 acos arg1 arc cosine trigonom Tab 8 4 121 acot arg1 arc cotangent trigonom Tab 8 4 121 asin arg1 arc sine trigonom Tab 8 4 121 atan arg1 arc tangent trigonom Tab 8 4 121 avg arg1 argument arithmetic mean of values aggr mom Tab 8 5 123 avg e arg1 run ensemble mean UNC MC Tab 8 13 145 avg l char arg1 arg2 dimension related argument arithmetic means aggr mom Tab 8 7 124 of values of arg2 avgg arg1 argument geometric mean of values aggr mom Tab 8 5 123 avgg e arg1 run ensemble geometric mean UNC MC Tab 8 13 145 avgg l char arg1 arg2 dimension related argument geometric means aggr mom Tab 8 7 124 of values of arg2 avgh arg1 argument harmonic mean of values aggr mom Tab 8 5 123 avgh e arg1 run ensemble harmonic mean UNC MC avgh l char arg1 arg2 dimension related argument harmonic means aggr mom Tab 8 7 124 of values of arg2 avgw arg1 arg2 argument weighted mean of values aggr mom Tab 8 5 123 avgw_e arg1 arg2 run ensemble weighted mean UNC_MC Tab 8 13 145 avgw_l char_arg1 arg2 dimension related argument weighted means aggr mom Tab 8 7 124 arg3 of values of arg3 classify int arg1 real arg2 classification of arg4 into int arg1 classes advanced T
195. elements of an edf file for a DFD experiment ssseee 80 Experiment specific elements of an edf file for UNC MC sssseseeeeeeeneeem emnes 84 Experiment specific elements of an edf file for LSA ssssssssseee emen mene 86 Experiment specific elements of an edf file for BAY BC emm eene 88 Elements ofa BAY BC bdf file rere erri fees ceva Fre peteret ae Ra ET AGE E ECAA ARERR 89 Experiment specific elements of an edf file for OPT SA eene enne 96 Experiment related user shell scripts and files essssssssssssseseeeneee nennen 108 SimEnv files to store for later experiment post processing sseeeee me 110 Classified argument restriction s result description for post processing operators 118 Built in generic standard aggregation moment operators sseee eem 119 Built in elemental operators ssesssssssssssssssssesesesen nennen ernst stet tenete Eest sn tereti sisi nnn te setis nsns ee en 120 Built in basic and trigonometric operators ssseeeneene eene enne 121 Built in standard aggregation moment operators without suffix 123 Built in standard aggregation moment operators with suffix n sssse m 124 Built in standard aggregation moment operators with suffix 1 124 Built in advanced Operators ececeeececececeeeeeeeeeeeeeeeeeeeaeaeeeeeeeseceaeaecee
196. ends if one of the criteria in the file model simenv opt sa options txt see above is 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 corre sponding 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 ORM Sia factor pl descr latitudinal phase shift factor oul unit jou 152 6 RACOR pl type set factor pl default ike factor pl sample 12 12 minimize cost function for p1e 12 12 gt factor p2 type set RACER p2 default D factor p2 sample Lee factor p3 type set factor p3 default Ske FECTOR p3 sample SAS factor p4 type set factor p4 default 4 factor p4 sample Leite 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 7 Experiment
197. ensitivity 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 V DEV D V m s 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 V42 fraction caused by interaction of all k factors Theoretically the unconditional variance V Z of Z can be reduced by fixing X to its real value x Voi ZIXi x conditional residual variance of Z when fixing X to any x w
198. ent description from general descr of lt model gt edf gt 10 1 2 Variable Labeling and Variable Attributes For NetCDF variables two cases of labeling are distinguished e 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 is used e Otherwise an additional coordinate var name co name is defined where the NetCDF variable depends on The additional coordinate is described in the di mension and data part of the NetCDF file Additionally the SimEnv specific attribute index range original coordinate name see Tab 10 3 is assigned to such a NetCDF variable Check also Example 10 1 and Example 10 2 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Having a model output variable definition as in Example 5 1 on page 44 and assuming in lt model gt cfg model out_ format netcdf model out separation yes During experiment performance model output variables atmo and bios are stored as follows excerpt from ncdump netcdf world f out000000 dimensions lat 45 lon 90 level 4 time 20 bios lat 36 variables float lat lat lat standard name SimEnv model coordinate latlong name geographic latitude lat units deg lat axis Y float atmo time level
199. ent value Name Meaning restriction s puis result description dfd navigation and aggregation in the dimres diMarg2 char_arg1 factor space for arg2 according appended dimensions arg2 to char_arg1 according to char_arg1 char_arg1 selection aggregation filter according to Tab 8 15 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 operators gt lt operator gt lt operator gt lt select_operator gt lt aggreg_operator gt select operator sel factor val type factor name factor val range aggreg operator aggreg type factor val type factor name factor val range factor name name of the experiment factor according to the experiment description file factor val type specification how to interpret factor val range i as a range of position indices of factor values always count from 1 S as a range of sampled factor values factor smp val a as a range of adjusted factor values factor adj val factor val range vali lt val gt 3 C for val nil val val4 ue use all values from factor name vali val int for factor val type i vali val float else aggreg type an aggregation mo
200. entity in a model output description file and the used SimEnv interface func tion in the model source code as well as the above exceptions are reported to the interface log file lt model gt mlog cf Tab 11 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 Distributed Resource Manager DRM 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 user model native output to the terminal is redirected during the experiment to the SimEnv experiment log file lt model gt nlog For running an interfaced model outside SimEnv it comes with a dummy library to link run the model with Its corresponding interface functions ensure the same model dynamics as before interfacing the model to SimEnv cf Section 5 12 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 interfaced to SimEnv For multi dimensional model output the simenv put Ing function expects the output stored in a model Source code array the ent
201. 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 Te weed 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 factor name dfd factor values dependent on experiment description and operator arguments Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 11 7 Case Sensitivity As stated in Tab 11 12 all names used in SimEnv are case insensitive Internally they are mapped on a lowercase 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 11 12 Case sensitivity of SimEnv entities Case Where Entity da Example sitiv ity overall e model name yes simenv chk World f user defined files e keyword no experiment END RUN last cf Section 12 1 e name e Sub keyword e information value no xperiment nd_run LAST general descr This is model interface e variable and factor name no iok simenv put f ATMO atmo atmo factor name P1 factor value 1 SE HOME bin simenv get sh experiment e optional resul
202. equired e For GAMS models Handle in the model source code the include statements e include model simenv get inc e include model simenv put inc as a comment m l ES Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 d I T 67 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 General Approach Experiment Description File lt model gt edf 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 scription file model edf lt model gt edf is an ASCII file that follows the coding rules in Section 12 1 on page 203 with the keywords names sub keywords and value as in Tab 6 1 Tab 6 1 Elements of an experiment description file model edf for all experiment types line type m mandatory o optional Max Sub Line Keyword Name keyword type line Val
203. er of values according to char arg1 hgr char_arg1 int_arg2 real_arg3 real_arg4 argument histogram of values arg5 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 3 m d dl Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 248 HIE TH Name Meaning See minprop arg1 index of the element where the minimum is reached the first time sum arg1 var arg1 argument sum of values argument variance of values Multiple aggregation a nd moment operators for arguments Tab 8 6 on page 124 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 arg1 argn argument position 1 n where the minimum is reached the first time Dimension related aggregation and moment operators for arguments Tab 8 7 on page 124 avg l 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 l char arg1 arg2 dimension related argument harmonic means of values of arg2 avgw char arg1 arg2 arg3 dimension related argument weighted means of values of a
204. erand dimension for Fig 4 6 c two additional dimensions are appended to the operand dimension 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 e Asa third option it is possible to select only a sub space out of the factor space Example 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 description file DFD a in Example 6 5 in Section 6 4 2 on page 82 e The operator dfd also enables to aggregate operands in the factor space Sequence of performing aggregations is important Example 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 afterwards 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 m S TS Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 V HN J 141 Tab 8 11 Experiment specific operators for DFD Argument Argum
205. erate 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 model 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 sig nificantly Nevertheless for models that store a multi dimensional model output field in a lower dimensional ar ray this 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 model 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 consump tion Nevertheless checking on undefined values can support model debugging 11 4 Model Interface Scripts Include Files Link Scripts Tab 11 5 lists all these dot scripts and shell scripts that can must be used in lt model gt ini run end J Tab 11 5 Shell scripts and dot scripts that can be used in model ini run end For built in shell script variables in lt model gt
206. es atmo c 88 88 c 178 178 c 1 16 c 1 20 and atmo atedl o5 s1 90 died ii 320 ele atmo 1 1 45 c 178 178 sree Leas ie 0 TL odi 1s 20 euo 1 945 o il ero iiss bea TES 240 address all 45 90 4 20 values and the following holds for this addressed variable Dimensionality 4 Coordinates lat lon level time Extents 45 90 4 20 addresses all values of last 10 decades Dimensionality 4 Coordinates lat lon level time Extents 45 90 4 10 addresses all values of the first decade for level 1 Dimensionality 2 Coordinates lat lon Extents 45 90 addresses all values of level 1for the last decade at equator Dimensionality 1 Coordinates lon Extents 90 addresses all values of level 1for the last decade at equator Dimensionality 1 Coordinates lon Extents 90 addresses the value for the last decade at lat lon level time 0 2 1 20 Dimensionality 0 Coordinates without Extents without 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 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 m s AUGE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 J Hi l lt l 1 15 8 1 4 Operato
207. es equidist end 1 1 no of bins for char arg1 bin_mid bin mid COOrdres diM es values equidist_end 1 bin mid bin width no of bins char arg1 bin no bin mid int arg2 number of bins 4 lt int_arg2 lt no of runs or 0 automatic determination max 4 no _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 a char_arg1 all def undef maxprop e return the run number where the 1 arg1 maximum is reached the first time processing sequence starts with run number 1 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 real arg1 0 001 real arg1 confidence measure from real arg probability of 0 01 0 05 0 1 arg2 avg_e arg2 error soe run ensemble correlation coeffi arg1 2 1 cient between arg1 and arg2 arg2 cov e run ensemble covariance be argi tween arg1 and arg2 a arg2 ens run ensemble values 6 arg dimes diMargi 1 Xtres diMres no _of_runs Coord res diMres name run values equidist_end 1 1 no _of_runs 3 m 1 46 3 HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1
208. es Tab 11 9 slices no above structure standard Section 5 11 and above experiment restart_ini no Section 7 4 begin_run 0 Chapter 7 and above end_run last Chapter 7 and above include_runs lt nil gt above exclude_runs lt nil gt above email lt nil gt Section 7 1 postproc out_directory Jl above out format NetCDF Chapter 10 address default coordinate Section 8 1 3 and above coord check strong Section 8 1 5 and above opr directory J Section 8 5 factors_in_output yes above display_values 0 above visualization yes above Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 185 general descr General configuration file for the general descr examples in the SimEnv User Guide general message level info model out directory mod out model out format netcdf model out separation yes model auto interface E model structure standard experiment begin run 45 experiment end run 300 experiment exclude runs file runs2exclude dat postproc out directory reS OUT postproc out_format netcdf postproc address default index postproc coord check strong postproc opr directory of postproc visualization no Example 11 1 User defined general configuration file model cfg 11 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
209. es number of values val int end element end value real val val int gt 1 val int 2 values are placed within the interval begin value end value 1 Lise Bp SB Ty 95 id 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 equidist ivl 3 5 11 is equivalent to 1 6 file my values dat is equivalent to 1 with my values dat 3 5 7 om LT 7 equidist end 11 2 3 differs from 1 6 values are identical ordering sequence differs Example 12 3 Examples of value lists Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 MV 2T S THE 209 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 endians Model interface e for R models Experiment preparation e Experiment type stochastic analysis e UNC MC sampling of correlated factors Experiment performance e Experiment performance for distributed models across networks e Multi file model output storage Experiment post p
210. esolved length relative to absolute paths environ variables resolved characters 256 User defined files entities cf also Section 12 1 length of a record in a user defined file characters 360 length of all general descriptions descr characters 512 length of a local description descr characters 128 length of a unit characters 32 length of a name characters 64 values in a value list number 5 000 length of a record of a referred ASCII data file characters 1 024 lt model gt odf user defined and composed operators number 27 lt model gt ndf total length of a global attribute string characters 256 length of all define strings for a macro or a composed operator characters 512 Model interface and experiment preparation entities single model runs in an experiment number 999 999 experiment factors in n model edf number 100 model output variables in lt model gt mdf number 100 all but Java models dimensionality of a model output variable 9 Java models dimensionality of a model output variable 4 Coordinates in lt model gt mdf number 100 coordinate values and sampled factor values number 200 000 active slices during performance of a model number 30 GAMS models storage size of a float real 4 model output variable Mbytes 64 Experiment post processing entities length of the optional result description string characters 128 length of the optional result unit string characters 32 arguments of an operato
211. essing 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 data Generally speaking a post processor result is specified by a chain of operators which are applied to model output variables and or data This operational description of the result is optionally prefixed by a result descriptor where a name and or attributes can be assigned to the result result result descriptor result expression result 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 experiment post processing sess
212. est 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 m Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN Tl 33 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 single objective optimization method is to find the global minimum of a cost function synonym objective function F Z F ST Xx that depends on model s state variables Z and consequently on the experiment factors X X Xk minimize F Z X1 Xk subject to Ximin Xi Ximax fori 1 K Often F represents a distance measure in a specific met
213. eti ir asardo Rent P Rote Ere ant RR ERO ERR Rent ha nite grana 94 Data files for the likelihood functions of a BAY BC experiment 95 Experiment description file model edf for OPT SA ssssssseeeeneeem e nennen 97 Shell script model run to wrap the user model sese emen 101 Shell script lt model gt ini for user model specific experiment preparation sssssss 101 Shell script model end for user model specific experiment Wrap Up sees 101 Shell script model run with shell script simenv kill process esmmm 102 Handling model input and output files in multi run experiments ssssssseeseeeee 105 Shell script lt model gt rst to prepare model performance during experiment restart 107 Addressing results in experiment post processing ssssssssseseeeeeeen enne 113 Addressing model output variables in experiment post processing seene 115 Checking rules for coordinates nerit ect cte teet uuu enne danse apice aa er re eeu Lee cones Ya d cous 119 Experiment post processing operator get data and coordinate transformation file 130 Experiment post processing operators unjmask file 132 Operator Move vo Ec 133 Operator Pak e 134 Experiment post processing
214. f file for BAY_BC line type m mandatory o optional Max Keyword Name k Eu Line ine Value Explanation eyword type nmb factor factor sample m 1 distr prior distribution to generate a name distribution representative sample of val ues factor smp val given the information defined in lt model gt bdf sample _ 0 1 real val4 lower bounds real val and include real val47 upper bounds real vali of A peta intervals to include for sam lt real_valn1 gt pling according to distribution lt real_val 2 gt lt distribution gt real vali lt real vali sample Oo 1 real val4 lower bounds real val and exclude real val427 upper bounds real vali of aee 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 real vali specific lt nil gt seed o 1 random fixed method how to initialize the random number generator runs m 1 lt val_int gt chain length number of runs to be per formed for the experiment will be smaller To Tab 6 10 the following additional rules and explanations apply Sub keyword sample Each factor in a BAY_BC experiment comes with its own marginal prior distribution which will be qualified in the course of experiment by generating a representative sample by taking into account measurement values and measurement errors from the real s
215. f 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 model edf for self as a range of signs for sels factor val range val vab 0 for val nil val val use all values from lt factor_name gt vali val int for val type i vali val float for val type s vali factor name for val type n self vali and lt val gt nil for val type 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 in terpreted 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 val ues 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 filter argument e For val type i i e if a factor value range is specified by position indices those factors are se l
216. facl simenv Cak undef f fac2 eq 0 then indi defined 1 r8facl facl r8fac2 fac2 value8 value8 r8facl r8fac2 endif enddo m m 41 irae Cerine eren OD Mte e rm res m simenv put undef f else res m simenv clip undef f value8 endif enddo enddo G portura orror Cocks simenv compute user def operator 0 TO VIRA end Example file usr opr matmul f f Example 15 13 Experiment post processor user defined operator module operator matmul f m cr 7944 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 3 II jd Is 241 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 rinclades eimen opr Gino ZANE OM AGS wito IESR HOME EIE int simenv_check_user_def_operator aame alepxiedl P S eexts 24 9 2 ime Leo mrig ieo arrol e0 beg posle tea beg joos2 S 7 576 9 dimensions 64 characters char co namel 576 co name2 576 pr ar er 5 yer int idimensl idimens2 int ichk_modus int iret iretvl iretv2 j iok ierror 0 float valuel value2 get dimensionality idimens extents iext formal coordinate number ico nr and formal coordinate begin position ico beg pos P idimensl simenv get dim arg c 1 iextl idimens2 simenv get dim arg c 2 iext2 aoi s memva Get CO arg Cll ico nri teogbegaposimeomnmnam
217. figuration file lt model gt cfg For more information check Section 11 1 Application of simenv slice f c for NetCDF model output may result in a higher consumption of computing 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 functions as integer 4 int for Fortran and or C C Apply the shell script link simenv mod f c cpp sh model name from the SimEnv library directory SE_HOME lib to compile and link an interfaced Fortran C C model User models implemented in C C or Fortran have to be linked with the following libraries to inter face them to the simulation environment e SE HOME lib libsimenv a e libnetcdf a from usr local lib or usr lib Tab 15 13 lists the additionally used symbols when interfacing a Fortran or C C model to SimEnv In e Example 15 1 on page 224 the model world f f e Example 15 3 on page 227 the model world c c e Example 15 4 on page 229 the model world cpp cpp are explained m x r Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y Hi l 47 5 5 Model Interface for Python Java and Matlab Models Due to the special features of
218. for Version 3 1 Jan 25 2013 y HN T J 143 For experiments that use a sample file lt model gt edf specific comb file instead of explicit sam ple definitions lt model edf gt specific comb default combination 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 experiment 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 44 and assuming address_default coordinate in world_ cfg Assume the experiment layout in Fig 4 6 c on page 26 and the corresponding experiment description file from Example 6 5 DFD_c on page 82 then in result processing eie joes 2 20 last time step of bios dependent on p2 p1 and p3 Dimensionality 4 Coordinates lat lon p2 p3 Extents 36 90 4 3 eli amp el sell 92 r bioc 9 2 9520 last time step of bios dependent on p1 p2 and p3 Dimensionality 4 Coordinates lat lon p2 p3 Extents 36 90 4 3 cke gel a2 UJ eed sb 95 1 emo 55 9 5 355 select the single run out of the run ensemble for level 1 p2 4 and p3 3 3 Dimensionality 3 Coordinates lat lon time Extents 45 90 20 cke Sell_a jo les sel s95 2583 Guo 5 97 1 520 last time step of atmo for level 1 depend on p2 p1 and p3 use only runs for p2
219. 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 m S ae Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T J 263 OpenDX The Open Data Explorer OpenDX http www 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 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 erator 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 sionalit
220. 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 m s AG Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs Ii a j l lt 91 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 The argument lt adapt_and_perform_setting_script gt to this script is the name of a shell script where the ad aptation 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 adapt and perform setting script If so take care to perform SE HOME bin simenv ini sh before SE HOME bin simenv end sh must not be applied in adapt and perform setting script 6 7 3 Bayesian Calibration Log Files model blog and model bmlog During the random walk by the Metropolis Hastings algorithm a new candidate point in the factor space can be e outra
221. formance of the current single run simenv run int due to any condition of this run make sure a file SE WS model err simenv run char exists as an indicator to stop Create this file in the model or in model run Use the corresponding SimEnv function simenv get run to get the current run number simenv run char Cf Tab 5 8 on page 59 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 the experiment log file model elog to identify these single runs e SimEnv supplies a shell script simenv kill process to kill processes of models programs that were started within model run and that consumed more than a given threshold of CPU time For exam ple with this script the process associated with the model run that does not converge and would run infinitely can be killed Start this script in background directly before the process is started that is to be monitored SE HOME bin simenv kill process program to monitor CPU time threshold in sec When the program is killed a file SSE WS model killed simenv run char exists as an indica tor Keep in mind that for killed models the status of model output to SimEnv data structures may be undefined Sub processes of the killed model are not killed by the shell script simenv kill process Check Example 7 4 e For GAMS models and for the experiment t
222. from an external file get experiment char arg char arg2 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 123 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 numb
223. g edf world Ing mdf world Ing run and or world Ing Ing To experiment with other models replace world Ing by model 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 to the PIK visualization server check in Section 11 2 on page 186 the SimEnv service simenv key user name anh 10 y H m i J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 3 Version 3 1 This chapter summarizes differences between the current and the previous SimEnv release limita tions and bugs and their workarounds 3 4 What is New Tab 3 1 SimEnv changes in Version 3 1 Type Check see On page Description update Section 5 4 45 Link scripts for models and user defined operators Section 8 5 1 154 SE HOME lib simenv mod opr f c cpp Ink renamed to SE HOME lib link simenv mod opr f c cpp sh Bug fixes Tab 3 2 User actions to upgrade to Version 3 1 Upgrade type Upgrade action mandatory Re link interfaced models and user defined operators Tab 3 3 SimEnv installations Organization Machine Cluster SE HOME login node Potsdam Institute for Climate cluster pik potsdam d
224. g1 arg2 dimension related argument sums of values of aggr mom Tab 8 7 124 arg2 sym abs char arg1 arg2 absolute symmetry measure loc sens Tab 8 14 149 sym rel char arg1 arg2 relative symmetry measure loc sens Tab 8 14 149 tan arg1 tangent trigonom Tab 8 4 121 tanh arg1 hyperbolic tangent trigonom Tab 8 4 121 transpose char arg1 arg2 transpose arg2 according to char arg1 advanced Tab 8 8 126 undef undefined element advanced Tab 8 8 126 usage char arg1 get usage of post proc operator char arg1 advanced Tab 8 8 126 var arg1 argument variance of values aggr mom Tab 8 5 123 var e arg1 run ensemble variance UNC MC Tab 8 13 145 var l char arg1 arg2 dimension related argument variances of val aggr mom Tab 8 7 124 ae dl dy Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 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 Arg
225. h run eseeeeeeses 236 Model interface for ASCII files model shell script world as run seen 237 Semi automated model interface at shell script level model shell script world_sh_auto run 238 Experiment post processor user defined operator module operator matmul_f 241 Experiment post processor user defined operator module operator matmul c 244 ASCII compliant experiment post processor result import interface sseeees 246 m ulti Run Simulation Environment SimEnv ser Guide for Version 3 an 25 c ul pt A st Ae Xl Multi Run Simulation Envi SimE User Guide for Version 3 1 Jan 25 2013 3 HS ih XI Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 number 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 values or driving forces spaces The resulting
226. he corresponding interfaced models GAMS Distribution 20 http www gams com Java Version 1 4 http www java com Matlab http www mathworks com Version 7 7 Mathematica Version 4 1 http wwwwolfram com For the visualization framework SimEnvVis OpenDX Version 4 4 4 http www opendx org Qt http www trolltech com products qt Version 3 3 5 Ferret http ferret wrc noaa gov Ferret Version 4 4 OpenGL Version 1 4 http www opengl org 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 11 1 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 15 1 2 Technical Limitations Tab 15 3 Current SimEnv technical limitations Sampled factor values defined with equidist_ end nmb ivl see Tab 12 5 allocate only 6 storage places Entity Maximum entity value Directory strings SE_HOME bin current workspace in user defined files and operators r
227. he 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 12 5 Tab 12 5 Syntax rules for value lists Value list type Syntax Explanation number of values explicit list real val4 lt 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 directory2 file name file directory2 file name contains the explicit value list implicit equidist end real val4 real val real vala description of an equidistant list with of values with begin element begin value real val increment increment real val end element end value real vals real val real vals real val 0 Number of resulting values have to be 1 implicit equidist nmb real val4 real val val int description of an equidistant list with of values with begin element begin value real val increment increment real val number of values val int real val 0 val int 1 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Value list type Syntax Explanation implicit equidist_ivl lt real_val gt val int real val description of an equidistant list with of values with begin element begin value real val number of valu
228. he 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 r k 1 2 3 e Forall the other sub keywords check Section 6 1 1 on page 72 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 The first trajectory is selected randomly e Assuming to have already determined rye trajectories Then generate randomly 10 5 r rger 1 potential trajectories and select from them as the trajectory gett 1 that one which has to the existing rye 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 IBSXT EGRE pl descr latitudinal phase shift factor pl unit 931 1122 factor pi type set LECTOT pl default lla factor p1 sample distr U 12 12 use factor values 9 3 3 9 LECTOR p2 type set factor p2 default o factor p2 sample etes 19 CL 11 0 use factor values 2 25 4 75 7 25 8 75 LECTOR p3 type set factor p3 default S LECTOR p3 sample
229. he same operator also for user defined operators are possible Example 10g10 min_n 3 min_n log10 atmo 1 c 20 400 10 bios_g tal operators use the common form of notation Example forthe operator addition with two operands atmo_g and 345 etme Gp r 345 Operator Classification Flexible Coordinate Checking 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 strongly restrict application of experiment post processing especially for hypothesis checking 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 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 coord check weak To ensure for two arguments with same dimensionalities and extents to have same coordinates it is necessary that e as
230. he temperature Temp with respect to a free parameter in the optimization problem Furthermore avoid ance 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 should climb out Q4 7394 34 y HN T i J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 t where t is the annealing time The ASA schedule is much faster than Boltzmann annealing where kg Temp Tempo In t and faster than fast Cauchy annealing where kg Temp Temp t4 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 x4 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 m XE M
231. heck SE_HOME bin simenv_settings txt Start this service only one time before the first access to simenv vis and or simenv res or if the access does not work properly An email will be sent from SimEnv when the access is enabled To Tab 11 4 the following remarks and explanations apply e All but services simenv cpy simenv hlp simenv key and simenv sta 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 Version 3 1 Jan 25 2013 11 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 model 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 mod
232. here 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 As the real value x of factor X is unknown consider instead the average residual variance Ex V xi ZIXi7X 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 Ex V x ZIXi x lt V Z Taking into account the variance decomposition rule for conditional distributions V Z Vx Ex ZIX x Ex VXx Z Xi x abbr 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 VE ZIX V Z 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 m ARA S 22 y Li T th Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 In parallel z x4 Xy can be developed in a high dimensional model representation HDMR Rabitz et al 1999 of 2 terms as z 4 X 2zo LZ LLZy L LZm st Zi lsicje m s sk with Zo constant Zi zx Zi Zi X Xj Zm s Zm s Xm Xs Zik ZG s Xk This decomposition is unique provided that the factors x xy are orthogonal A necessary condition for orthogonality of the factors x4 xx is that they are uncorrel
233. hi 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 end m 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 Example file world m m Example 15 7 Model interface for Matlab models model world m m Y HN T i y Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 simenv run char and simenv run int SE HOM E bin simenv get run sh get run fac the tor names and adjusted values and Mathematica model model m CER SE_HOM E bin simenv run mathematica transfer ASCII model output files to SimEnv model output Example 15 10 and Example 15 11 remove temporary sub directory run simenv run char rmdir run simenv run char perform always and as
234. i x z for each factor xi With O4 run ensemble variance of factor values x i71 K and o run ensemble variance of variable z consider the distributions i 1 k FS di x z 0 0 and compute mean ur d x z r Fi di x z o o and compute variance o d x z Xd x z rY r 1 abs Consider in the c plane the points u c i 1 K e a high value of p with respect to the other yj indicates an important overall influence of the factor x on the model state z abs e a high value of oi with respect to the other oj indicates that the factor xi is involved in interactions with other factors or indicates that the effect of xi on the model state z is non linear Saltelli et al 2004 See also Fig 4 2 m S V Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN T J lt 19 Note the following remarks Fig 4 2 According to Saltelli et a 2004 and as a rule of thumb The number of levels p of the grid should by even and should be 4 or 6 The optimal unique jump width A in the factor quantile space is p 2 p 1 The number of trajectories r should range around 10 According to Sin and Gernaey 2009 The sensitivity measures u and o are non dimensional as they are scaled by o and o This allows for applying the Morris method with factors that significantly differ in their value ranges i e for factors wi
235. ibe the importance of the corresponding factors The sequence of the factors in the appended factor 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 special designed trajectories in the factor space 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 118 Argument value restriction effects 1st arg1 first order sensitivity indices of arg1 6 dimres diMargi 1 Xtres diMyes no of factors coordres diMses name factor_sequ values equidist_end 1 1 no of factors arg1 must not contain strings enclosed in effects tot arg1 total effect sensitivity indices of arg1 6 dimMres diMargi 1 Xtres diMres no _of_factors COOrdres diM es name factor sequ values equidist end 1 1 no of factors arg1 must not contain strings enclosed in gsa vb run mask mask runs to use for subse 7 sample resample char arg1 quent UNC MC experiment sample specific operators resample all resample but this is NOT a factor name multi run operator resample but all same as for
236. ic commands can follow Python programming language is used to prepare run and to end an experiment with a GAMS model Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HEIN 53 5 7 2 GAMS Description File lt model gt gdf lt model gt edf lt model gt mdf For each GAMS model an ASCII GAMS description file lt model gt gdf has to be supplied It 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 12 1 on page 203 with the keywords names sub keywords and values as in Tab 5 3 Tab 5 7 Elements of a GAMS description file lt model gt gdf line type m mandatory o optional Max Keyword Name Que Pine Dre Value Explanation keyword type nmb general nil descr any lt string gt GAMS coupling description keep_runs 0 1 lt val_list gt value list of run number
237. iens eine ann tha anao Pauca ea tarn e Pa eve eva raa nnn 52 Standard Dot Scripts for GAMS Models ssesseee eene eene nnnm enn ennemis 53 GAMS Description File lt model gt gdf model edf lt model gt mdf ccccccceeceeceeeeeeeeeeeeeeeeeeseeseeaeees 54 Files Created during GAMS Model Performance sse eee ene 58 Model Interface at Shell Script Level nennen nennen ennemi nennen enne 58 ee Miacucie apmilellicmee e 61 Semi Automated Model Interface ssssssssseesesee eee eren nnne nnne nennen 63 S pp rted Model SthUClU ES C XX Feeds 66 Using Interfaced Models outside SIMENV esses eene nennen nnnm ener nenne 67 acutum Global Sensitivity Analysis Variance Based Method GSA VB RUM SCQU ONCE woes EXeUM le si T s Deterministic Factorial Design DED 3 anotar eerte ea dense steces ea N aaa rep Eea aAa Formalisation of the Inspection Strategy Run Sequence clle Paues Uncertainty Analysis Monte Carlo Method UNC MC Soho ce acce E O Local Sensitivity Analysis LSA ouai trn ro tee tae dpa ecd Era Lean chu sven a peo ste a aada aaa taai Sensitivity F
238. ifference for atmo between the current experiment and another model other_model located in directory other_dir 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 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 atdg Qin EO 10 atmo 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 m S Ae Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T J 135 avg atmo 19 20 global all level mean over the last two decades Dimensionality 0 Coordinates without Extents without maxprop atmo indices of this element of atmo where the maximum of atmo is reached the first time Dimensionality 1 Coordinates index Extents 4 min 3 Chemo 928 565 55 1 5 1320 LO 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 apo OTO aTe 200 8 210 7 tr wiley 219 zonal tropical minima of atmo for the last decade and level 1 Dimensionality 1 Coordinates lat Extents 11 min
239. im dim dim Ox Ss DEKE dim dim O1 new2 new2 coordinate Further assume the coordinate transformation file model ctf as descr descr rename DOS ONES Eat values shift values add values shift 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 103 1003 1006 1009 coundiis cmendi ACIO coundi tendim SP equidist end 88 4 88 Scuicisic uel B 1 SC Having a model output variable definition as in Example 5 1 on page 44 and assuming address_default coordinate in lt model gt cfg Assume the experiment layout in Fig 4 6 c on page 26 and the corresponding experiment description file from Example 6 5 DFD_c on page 82 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 lige 1 10 100 LOOG equidist_end 2 2 20 Scmaichisic eel 3 S 310 equidist end 4 1 43 Scmichisic exuwel 5 UL SC example of a coordinate transformation file newl Bo 2 list 1006 1009 3 lat Bes SOs S new2 SOR 8 5c new coordinate coundi Ciel 50 TR get experiment mydir model model ctf modvarl modvar2 coordinate use coordinate definition coordinate definition coordinate definition equidist end 88
240. in node and or on a compute cluster The above 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 Aoa sh perform always and as the first SE HOME bin simenv sh dot script SSE HOME bin simenv ini sh get run number SSE HOME bin simenv 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 CONES my model in my model mv my model out my model out simenv run char lel oa 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 m S AE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 3 Hn S p
241. index simenv_ get_arg_ Operands of any type are transferred by flc simenv get arg f c toa 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 column major order 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 seta real 8 value value fic to an undefined input real 4 result value if appropriate real 4 Example l underflow simenv_ res i simenv clip undef f c set a real 8 value Clip undef value to real 4 0 fic if appropriate function value 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 fic put_undef_ fic function value Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 e n 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 located in that directory that
242. ing 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 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 The feature of accepting by a certain probability a state with a higher energy than the previous state allows for climbing out from local sub optimal energy states during simulated annealing 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 optimiza tion 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 in implementation of a simulated annealing algorithm is that there is no obvious analogy for t
243. ingle run Flowcharts for performing simenv run and simenv rst First and last single run always refer to the corresponding settings in lt model gt cfg ra Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 SIENY 109 7 6 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 assigned to the keyword model lt model gt mdf lt model gt edf do not modify all information including the sequence of the model output vari ables and or experiment factors lt model gt smp lt model gt fct for UNC MC BAY BC and OPT SA with stopping rule model blog for BAY BC model elog Optional from the current workspace model mlog model nlog model dis par seq aix linux jcf pbs model bmlog for BAY BC model olog for OPT SA model opt sa options txt for OPT SA Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 8 Experiment Post Proc
244. integer 1 byte value e g 123 lt val_short gt integer 2 short value e g 12345 m s M Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Ui Ii a f l 5 Placeholder Description lt val_int gt integer 4 int value e g 123456 lt val_float gt real 4 float value in integer 4 int e g 123456 fixed point e g 123 456 or floating point scientific e g 1 23456e 2 notation val double real 8 double value in integer 4 int e g 123456789 fixed point e g 123 456789 or floating point scientific e g 1 23456789d 2 notation val list list of values in explicit or implicit notation according to Tab 12 5 var name variable name as defined in model mdf or a built in variable see Tab 11 9 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 dim dimensionality of a variable operand or result ext i i21 dim extent of dimension i of a variable operand or result coord i i 1 dim coordinate of dimension i of a variable operand or result no of number of Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 1 2 Example Layout
245. inux command chmod u x lt model gt run ini end m ETT M 100 Y HN T J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 For the shell script world_f run the following contents could be defined bin sh 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 SSE HOME bin simenv get run sh touch SSE WS world f err simenv run char Fa perform always and as the last SE HOME bin simenv sh dot script SE HOME bin simenv end sh Example file world f run Example 7 1 Shell script model 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 erit dixo WOrrllcl iim mita Tetun Cocks s 6 as an indicator not to start the experiment ex
246. ion nmb assign lt original_ coord 0 1 lt co_name gt assign to the dimension with coordinate _ coordinate number lt coordi name gt nate_nmb gt only for operator lt coordinate_ get_data ascii and or nmb gt lt original_coordinate_name gt else an already defined co ordinate or a coordinate de fined by the keyword coordi nate coord extent o 1 co val assigns start and end coordi co val nate value to the dimension of the result under consideration coordinate new descr o 1 lt string gt coordinate axis description one unit o 1 lt string gt coordinate axis unit name values 0 1 lt val_list gt strictly monotonic sequence of coordinate values for syntax see Tab 12 5 To Tab 12 4 the following additional rules and explanations apply 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 inserted at the begin of the coordinate for a negative value of lt values_shift_val gt Coordinate val ues 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 specified automatically by simply applying the equidista
247. ion is finished by entering ret instead of a result possibly prefixed by white spaces For case sensitivity of result check Tab 11 12 on page 197 result descriptor result name result description result unit Optionally describes the name of the result and its description and unit in the corre sponding result output file cf Chapter 10 For one post processor output file one post processor session result name has to be unique The result descriptor with its separator has to be specified in the first input line The result expression itself may follow at the following input line result description and result unit are case sensitive result name is transformed to lower cases All three properties can be empty and or a character string with white spaces In the absence of result description and result unit there are default values for them if the result expression is a special type of a single operand single operator expression In the absence of result name there is a general default name All three strings can comprise wildcard substrings For all defaults and wildcard see be low result expression is a chain of SimEnv and user defined operators applied to model output variables and or data Can be continued on a new input line continue expression if the current input line OREM on or on the operand separator on ORD ends on one of the operators
248. ional experiments Technometrics 33 2 161 174 LLNL 2012 NetCDF Climate and Forecast CF Metadata Convention Lawrence Livermore National Labora tory http cf pcmdi IInl gov NCO 2012 NetCDF operator Homepage http nco sourceforge net 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 m S ae Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN T J lt 213 Schulzweida U Kornblueh L Quast R 2009 CDO Climate Data Operators Version 1 4
249. iple setting case differs only in the value of the sub keyword settings from that for the other two cases However instead of checking and using the data files 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 setting number 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 created in the model output directory as specified in model cfg Subdirectory names are s setting number As usual experiment related output files are stored in the current workspace Multiple setting experiments can not be post processed in a common post processing session Instead modify temporarily the model output directory in model 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 consisting only of nodata elements for those settings where an individual likeli hood is not to be applied To interface the model to SimEnv for the multiple setting case the model wrap shell script model run is used that represents a single model run Since a single run
250. 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 12 3 on page 208 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 sep sep 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 12 3 Having a model output variable definition as in Example 5 1 on page 44 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 20290 7 19820 this is equivalent to i 17327 disS0 2 19220 this is equivalent to C 208 20 c 20860 2 19820 Antarctica all levels and decades C 60e 8 this is equivalent to i Sgodi ww S s this is equivalent to e 60e LaSO ised 1820 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 m NTC 132 y HN T J lt L Multi Run Simulation Environmen
251. is re directed to the log file lt model gt nlog e Fora restart the optional user defined experiment preparation shell script lt model gt ini will be per formed only on demand The corresponding 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 7 1 m EA 106 y HN T J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Restart can be launched in a different mode on the login node or under job Distributed Resource Manager control the latter also in an other job class queue and sub mode and or on an other node than that of the previous interrupted experiment e Minutes of the restarted experiment will be appended to the log files model mlog lt model gt nlog and lt model gt elog respectively from the previous interrupted experiment e Experiment restart 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 236 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 SE HOME bin simenv ini sh
252. is server hostname hostname name of the visualization server that hosts the visualization component SimEnvVis SimEnvVis home directory directory SimEnvVis home directory SimEnvVis working directory directory SimEnvVis working directory on the visualization server server SimEnv home directory directory SE HONME directory on the visualization server ssh local lt directory gt binary ssh implementation of the client com puter Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 scp_local lt directory gt binary scp implementation of the client com puter ssh keygen_local lt directory gt binary ssh keygen implementation of the client computer nc_libpath lt directory gt directory the NetCDF shared object libraries are located for Linux 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 12 1 on page 203 with the keywords names sub keywords and info as in Tab 11 2 Tab 11 2 Elements of a general model related configuration file lt model gt cfg line type o optional Sub Line Max Keyword Name line Value Explanation keyword type nmb general nil descr o any string general configuration description message level o
253. ist end 1 1 4 1 2 3 4 for p2 factor p3 type multiply Here p3 default Se factor p3 sample list 2 0 2 8 3 3 6 0 8 4 9 9 for p3 specific comb PIPPA PS world edf_DFD_d general descr mag dio 9 general type DED file world dat DFD d IEEE pl type multiply iL 0 ACE Ons pl default il E il factor p2 type add 7 2 factor p2 default do 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 6 5 Uncertainty Analysis Monte Carlo Method UNC_MC The experiment specific information for experiment description files in Tab 6 1 on page 69 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 line type m mandatory o optional Max keyword Name k atr Line Bine 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 file name factor smp val file file name to import an external sample of val ues factor smp val sample _ see 1 pseudo quasi sampling strategy method ex stratified
254. it rc land sea mask Example files world f c cpp py ja m sh as J 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 J end Example 7 3 Shell script lt model gt end for user model specific experiment wrap up m T Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 5 HN T J lt 101 For the shell script world_f run the following contents could be defined bin sh 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 SSE 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 SSE 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 iti perform always and as the last SE HOME bin simenv sh dot script SE HOME bin simenv end sh Example file world f run Example 7 4 Shell script model run w
255. ith shell script simenv kill process 7 3 Experiment Performance 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 node in foreground background and distributed mode and e distributed on a compute cluster under control of a Distributed Resource Manager in parallel distributed and sequential mode For an experiment performance controlled by a Distributed Resource Manager or on the login node in back ground make sure that the environment variable SE HOME is set correctly in the file HOME profile m m 3 102 Jj HN T J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 7 3 1 Local Experiment Performance on the Login Node Two different distribution strategies are offered by the simulation environment for running an experiment on the login node Perform the single runs of an experiment e sequentially on the login node foreg foreground sub mode backg background sub mode For an experiment in foreground sub mode the login session must be active during th
256. ition is introduced to avoid to run into a local point of change UNC MC experiments with a stopping function cannot be restarted 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 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 latitudinal phase shift factor SiL vnit Of IZo factor pl type add LECTOR pl default qe TACTOL 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 factor p2 default 2 LECTOR p2 sample method pseudo factor p2 sample distr N 2 04 p1 is sampled from a normal distribution with mean 1 and variance 0 4 In simenv get each sampled value is multiplied by 2 factor p2 sample include 1 6 2 4 sample only within the 20 interval Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 oy Hey as LACTO i93 type set factor p3 default Slo factor p3 sample file world dat UNC MC sample for p3 is read from file world dat UNC MC specific runs 250
257. ito 4 Slice storage exceeded 5 warning slice overwritten or slice represents the total dimension function value simenv close model integer 4 return code end f c coupling interface simenv end 0 ok f c 2 O error for experiment output file Perform always function value the last SimEnv function in the model To Tab 5 5 the following remarks apply 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 For multi dimensional model output the simenv_put_f function expects the output stored in the For tran model source code array the field as described in Tab 5 5 according to the column major or der model cf Section 15 7 Glossary that is used by Fortran by default For C C and simenv_put_c the row major order model cf Section 15 7 Glossary used by C C by default is expected The sequence of the dimensions of the source code array is determined by the sequence of the coordinates for the associated variable in the file model mdf check Section 5 2 Model output variables that are not output completely or only partially within the user model are han dled in experiment post processing as their corresponding nodata values cf Section 11 8 Application of simenv_slice_ f c demands a corresponding slice entry in the con
258. ity as described in Tab 5 1 above according to the order model that is used by the corresponding language Ing The sequence of the dimensions of the source code array is determined by the sequence of the coordinates for the associated variable in the file lt model gt mdf check Section 5 2 Tab 5 2 Language suffices and multi dimensional array order models for SimEnv model interface functions for the Mathematica and GAMS interface check Section 5 6 and 5 7 resp Model a us Order model Source code ng SNR for simenv put Ing cf Section 15 7 Glossary ASCII file as 5 9 column major C C C 5 4 row major Fortran 5 4 column major Java ja 5 row major Matlab m 55 column major Python py n5 row major Shell script sh 5 8 simenv put sh not available check Section 5 8 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 oy Heh se Description Files Experiment description file lt model gt edf Model output description file lt model gt mdf factor edf_factor type c variable mdf var type factor Q default 2 variable coords m factor specific info variable index extents Model Model wrapper shell script lt model gt run SE HOME simdhv ini sh 2 associate perform model with model source code from below description file entity model with l oe source code entity SE HOME simenv Vend For trans
259. ity 0 same dimensionality extents and coordinates as the first non character non constant argument dimes diMarg extres j Xtarg j for all j coordres j COOrdarg j for alll j dimensionality extents and coordinates of the only non character non constant argument arg can be arbitrary dimensionality is higher than that of the only non character non constant argument Extents and coordinates of this argument are copied to the result appended dimensions are explained individually diMres gt diMarg eXtres j eXxtarg j for all j coordres j COOrdarg j forallj only character arguments constant arguments dimes 0 or without arguments Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Having a model output variable definition as in Example 5 1 on page 44 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 E yes yes arene Gh Imese escam mo 219 0 0 7 eue differing coordinate names same coordinate values ne ES Ee atmo_g c 6 16 atmo_g c 8 18 same coordinate names differing coordinate values be js yee atmo g c 20 atmo c 0 c 2 c 1 c 1 two operands with dimensionality
260. ked in bold c c c program world f auto declare SimEnv interface functions compile with I SE HOME inc simenv sts simenv run int and simenv run char are also declared include simenv mod auto f inc declare atmo without dimensions level and time and bios without time because they are computed in place and simenv slice f is used real 4 atmo 0 44 0 89 real 4 bios OS 35 0282 integer 4 atmo_g 0 19 integer 4 bios g foul iL p2 2 jos Se p4 4 include source code sequence for the semi automated model interfac include world f auto f inc compute dynamics of atmo and bios over space and time of atmo g over time all 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 idecade 41 idecade 1l simenv sts simenv put f bios bios enddo simenv slice f atmo 3 level41 1level t1 simenv slice f atmo 4 idecade 1 idecade 1 simenv_put_f atmo atmo simenv sts simenv put f atmo g atmo g 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 Q4 m S MAE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 3 Hn S p lt 225 15 2 4 C Model With
261. keyword is mandatory for variables with dimensionality gt 0 and undefined for variables with dimensionality O e Coordinate values co val and index values in val are assigned in a one to one manner e Formulti dimensional variables that do not exist on an assigned grid completely or partially simply assign formal coordinate axes to e Specify at least one model output variable in model mdf e The model output description as specified by general descr lt string gt is used for NetCDF model and or post processor output files check Section 10 1 1 Tab 5 4 SimEnv data types SENS GLENS 2 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 4bytes integer float real 4 4bytes real double real 8 8 bytes real not for Python and Java models m x aA Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y Hi l 43 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 7 general descr World with a resolution of general descr 4 lat ss 4 lon x general descr 4 levels x 20 time steps general descr Data centred per lat lon cell general descr This file is valid for all models general descr would p eee p
262. l z lt factor def val factor smp val z factor def val for adjustment type Relative t factor smp val sens abs factor def val factor smp val z lt factor def val 1x factor smp val z factor def val t factor def val factor smp val 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 6 6 2 Example general descr Experiment description for the examples general descr in the SimEnv User Guide general type LSA factor pl descr latitudinal phase shift factor pl unit 92 112 s factor pi type add ACOs pi default ile factor p2 type relative factor p2 default p LECTOR p3 type relative factor p3 default S Specific incrs lrst O 001 0 01 0 05 0 1 Example file world edf LSA Example 6 7 Experiment description file lt model gt edf for LSA Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 6 7 Bayesian Technique Bayesian Calibration BAY_BC 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 Tab 6 10 Experiment specific elements of an ed
263. l edf Sequence as in model edf e Built in pre defined model output variables Sequence as in Tab 11 9 e Model output variables Sequence as in model mdf 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 of bytes divisible by 8 where the data can be stored Multi dimensional data fields are organized according to the column major order 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 simenv run int Consequently data from default nominal single run O is stored in the first and potentially the following records m S LIE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN J lt 177 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 pi 1 float 4 8 p2 1 float 4 8 sim time 1 float 4 8 atmo 45 x 90x 4 x 20 float 1 296 000 1 296 000 bios 36 x 9
264. l yes Nuc 1 N gt gt 0 multi dimensional OPT SA yes distributions global yes unpredictable multi dimensional 3 ri 1 8 J H E J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 3 Specify for each factor x i71 k a distribution with its distribution parameters Span up in the factor space X a k dimensional p level grid by determining for each factor x p equi distant quantiles q Gp These quantiles vary in 0 1 and the corresponding individual factor val ues in the factor space f
265. l transform model output to SimEnv could look like pl 1 p2 2 p323 p4 4 EON SSE and mkdir run eel bin sh perform dot script world sh auto sh inc alternatively perform dot script SE HOME bin simenv ini sh WS world sh auto sh inc create temporary directory run simenv run char to perform the model cd run simenv run char 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 rm fR run simenv run char perform always and as the last SE HOME bin simenv sh dot script semi automated model interface at shell script level model output transformation from native to SimEnv structure there run simenv run char the model SE 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 ri 3 238 J HN um J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 15 3 Example Implementation for the 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 f f integer 4 function simenv check user def operator o declare SimEnv interface functions compil
266. l 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 keyword sep value Tab 11 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 While all the entries in the table above and including SimEnvVis availability are manda tory for any SimEnv installation all entries below SimEnvVis availability are only requested if SimEnvVis is available for reachable from the current SimEnv installation Tab 11 1 Elements of the file simenv settings txt Keyword Value Explanation institution character string institution SimEnv is used by used in NetCDF output in global attrib ute institution SimEnv admin email address email address of the SimEnv adminis trator logfile directory directory directory to store SimEnv log files which services were used SimEnv home directory2log directory SE HONME directory to store log files from drm system LoadL PBS Torque _ installed distributed resource manager drm login node hostname login node for a compute cluster to ac cess the SimEnvVis availability yes no availability of visualization tool SimEnvVis SimEnvV
267. l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 12 2 For restrictions in the path to the directory of the character arguments char_arg1 and char_arg3 check Tab 12 3 Attention Make sure e that no SimEnv service is running from the directory char arg1 of the external experiment be fore applying this operator e to have full access permissions to the experiment directory char arg1 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 e Operator get table fct With the operator get table fct a table function is applied to each element of the operand arg2 If neces sary 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 el
268. l Systems Studies in Automation and Control Vol 5 Elsevier Amsterdam m 214 hy I T Vy lt Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 m we WAL Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 E HN PI 215 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 installa tion 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 exa SimEnv examples as used in the User Guide Version repository of SimEnv at PIK version_archive manner as the latest version SimEnv ver
269. l 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 factor def val to the factor variable factor name in the model source code whether this variable was already set to its adjusted value by if ValueQ lt factor name gt False factor name gt factor def val factor name factor name For an experiment with k factors the temporary Mathematica model for single run number simenv run int has the following structure factor name lt factor_valUe4 lt simenv_run_int gt factor name factor valU amp i simeny run in model This file is generated in a temporary sub directory run simenv run char of the current workspace The sub directory itself is created automatically when performing the single run simenv run int 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 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 externa
270. l 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 m s EAD Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs Ii a j l lt 51 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 model gms where model is the model name a SimEnv service is started with e and 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 b
271. l gms m s TRARRE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 JHN a Vy as 235 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 model sh inc for semi autom model interface tory run simenv run char 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 simenv run char and simenv run int SSE 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 SE HOME bin simenv get sh factor name p3 factor def val p3 SSE HOME bin simenv get sh factor name p4 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
272. l gt bdf ASCII user defined Bayesian calibration description file BAY BC 74 mandatory qM lt model gt gdf ASCII user defined GAMS model output description file GAMS models 72 mandatory m lt model gt ndf ASCII user defined NetCDF attribute description file optional 30 1 3 model run model shell script to wrap the model executable mandatory 15 model rst model shell script to prepare single model run restart optional 7 5 model ini model shell script to prepare simulation experiment optional additionally to standard SimEnv preparation for Python Java Matlab and GAMS 7 5 models manda tory and stan dardized model end model shell script to wrap up simulation experiment optional for GAMS models manda 1 9 tory and stan dardized I model Ink model shell script to link an interfaced C C Fortran optional model Used in the course of experiment preparation for experiment run not restart if a semi automated model interface auto interface no was declared in 540 lt model gt cfg for the appropriate programming lan guages Can also be used stand alone for non semi automated model interface Is normally based on SE_HOME lib link_simenv_mod_ f c cpp sh lt model gt _ user specific job control file to perform a model under optional dis par seq Distributed Resource Manager control in distributed 75 aix linux parallel sequential mode jfc for LoadL pbs for
273. l sedis 3 c ibeg iend 1 j ibeg iend enddo e further processing of coordinate values deallocate coord values enddo allocate result values length result ibeg 1 do whil ibeg le length result iend min0 ibeg 9 length result mec 2 9 LOGS 7 auo esueateshEmE result wellwes J ibeg iend 1 j ibeg iend enddo S further processing of result values deallocate result values enddo S VATES Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 By t PI 245 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 ri ccr x 246 J HN um J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 15 5 Experiment Post Processor Built In Operators 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 120 arg1 arg2 addition arg1 arg2 subtraction arg1 arg2 multiplication arg1 arg2 division arg1 arg2 exponentiation arg1 identity arg1 negation
274. l to the simulation environment Generally speaking e each experiment factor and e each model output variable demand one additional SimEnv function call in the model source code According to Tab 5 1 model interface functions are generic Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 M MIIN s Tab 5 1 Generic SimEnv model interface functions for language Ing cf Tab 5 2 Function name Description simenv ini Ing open model coupling interface simenv get Ing associate a model source code entity parameter initial value driver with an experiment factor from model edf and as sign the adjusted factor value to the entity simenv get run Ing get the current single run number of the run ensemble simenv put Ing associate an entity in general an array a state variable of the model with a model output variable from model mdf and output the entity to SimEnv data structures simenv slice Ing enable slicing i e a repetitively partial output of a model out put entity simenv end Ing close model coupling interface With the function simenv slice Ing a slice portion an output entity array variable can be ouput to SimEnv data structures by a subsequent function call of simenv put Ing In particular such slicing can be applied formodels with multi dimensional output variables where at least one dimen
275. lds value lat lon 1 sin n omega lat lon phi lat lon n 12 value lat lon last 2 sin 0 omega_ lat lon phi lat lon n 12 value lat lon last sin n 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 l 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 m S ETTA Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN T J lt 223 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 Sim py nv interface functions compile with I SE 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 C because they are computed in place and simenv slice f is used real 4 real 4 integer 4 integer 4 pl p2 ps pa m WN HE simenv_sts simenv_sts
276. le 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 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 val_int gt 5 single runs after that single run that represents the point of change val int is the number of declared runs in model edf see above This cond
277. le for coupled GAMS models Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 types 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 tate plant number coordinate plant values equidist_end 1 1 2 coordinate market descr canning markets coo
278. le z while due to their normalization factor the relative measures enable comparison of the influence of one factor x on different state variables z 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 For 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
279. les 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 E lateral vertical temporal semi automated example for lat x lon number of number of model interface language lt Ing gt 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 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 8E 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 11 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 1 Jan 25 2013 Multi Run Simulation Environment SimEnv
280. lihood functions differ in their data and result parts from each other and each like lihood function follows the rules for the single likelihood function case Again the single case likeli hoods are multiplied to determine the multiple case likelihood y H a j l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 The file for the data part of the likelinood function has to follow the syntax rules of ASCII data files in Section 12 3 Per data record one data pair has to be specified 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 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 as specified in model cfg or the corresponding default nodata value see Section 11 8 For data that are scarcely scattered compared to the number of result elements the shortcut lt val_int gt nodata with lt val_int gt 2 1 can be used instead of specifying lt val_int gt succeeding nodata pairs 3 4E 38 3 4E 38 3 4E 38 3 4E438 where 3 4E 38 is the default float real 4 nodata value representation If an other nodata value for float real 4 is specified in model cfg use that instead Keep in mind that the prior distribution is only determined by the
281. lly 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 See also gt PBS Torque 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 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 system and advanced connectivity to other applications Matlab MATLAB htto Awww mathworks de products matlab is a high level language for computations and interactive environment for developi
282. lon lat atmo standard name SimEnv model output variable atmo long name aggregated atmospheric state atmo units atmo unit atmo FillValue 3 4e 38f atmo data range 1999 95f 2002 39f float bios lat bios lat bios lat standard name SimEnv model coordinate bios lataxis Y float bios time lon bios lat bios standard name SimEnv model output variable bios long name aggregated biospheric state bios units bios unit bios index range lat 2 37 bios FillValue 3 4e 38f bios data range 1982 372f 1999 391f lat 88 84 84 88 bios lat 84 80 52 56 Example 10 1 Additional coordinates in NetCDF model output m S Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 V HN J Having a model output variable definition as in Example 5 1 on page 44 and assuming in lt model gt cfg postproc out_format netcdf During experiment post processing results atmo and run O sin atmo i 2 37 are stored as follows excerpt from ncdump netcdf world f resO1 dimensions lat 45 lon 90 level 4 time 20 res 02 lat 36 variables float lat lat lat standard name SimEnv model coordinate latlong name geographic latitude lat units deg lat axis Y float res O1 time level lon lat res Of standard name aggregated atmospheric state res O
283. 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 multipl multiplied by the factor default value Py factor adj val factor smp val factor def val relativo increased by 1 and afterwards multiplied by the factor default value factor adj val 1 factor smp val factor def val general descr Experiment description file general descr examples general type experiment type alee Ons pl descr parameter pl alee Ons pl unit ol umit factor pl type set aC BOs pl default qe iE EOS pi sample experiment type specific factor p2 type set factor p2 default 2s factor 192 sample experiment type specific specific experiment type specific Example 6 1 General layout of an experiment description file lt model gt edf m l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 yy I m 6 1 1 Elements of model 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 line type m mandatory o optional Max Keyword Name Mus d line Value Explanation nmb factor factor sample m 1 distr
284. 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 nodata nodata 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 Q4 2l sy ASCII file structure for the ASCII model interface Multi
285. lumn major order model cf Section 15 7 Glossary are shown Set display_values to 0 to suppress this output For keyword X postproc sub keyword visualization Specifies whether to directly visualize an entered result during experiment post processing Works only if the visualization system SimEnvVis is available according to the value of the entry SimEnvVis_availability in Tab 11 1 J a J l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 11 3 lists the default values in the general configuration file in the case of absence of the appropriate sub keyword Tab 11 3 Default values for the general configuration file in the case of absence of the appropriate sub keyword Keyword Sub keyword a in RE general descr nil above message level info above nodata value byte 127 Section 11 8 nodata value short 32767 Section 11 8 nodata value int 2147483647 Section 11 8 nodata value float 3 40E 38 Section 11 8 nodata_value_double 1 79D 308 Section 11 8 model out_directory J above out_format NetCDF Chapter 10 out_separation yes above out_builtin_vars y
286. ly after the include statement the factor variables with the adjusted factor values have to be assigned to the model variables e The GAMS include statement include model 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 output by GAMS put statements e 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 ensemble 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 cop ied to this sub directory and are performed from there Keep this in mind when specifying in any GAMS model include statements with relative or absolute paths In Example 15 9 on page 235 the model gams_model gms is described in detail gt 52 y HN T I J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Note the following information e To output the GAMS model status to SimEnv a PARAMETER modstat has to be declared and the statement modstat lt model name 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 descrip
287. mask coarsed world sh pl p2 p3 p4 read model results and output them to SimEnv world shput clear and remove directory NT rm fR run simenv run char perform always and as the last SE HOM SE 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 236 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 simenv run char e atmo g asciicsimenv run char e bios g ascii simenv run char 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 loan si perform always and as the first SE HOME bin simenv sh dot script altera perform SE WS model sh inc for semi autom model interface SSE HOME bin simenv ini sh get current run number simenv run char and simenv run int SSE HOME bin simenv get run sh
288. ment error check Section 4 7 The sub keyword data supplies the data part of the likelihood func tion Specify here the name of a file where the measurement data averages and variances are de fined With the sub keyword model output the model output part of the likelihood function is sup plied A model output variables and or result of any dimensionality has to be specified here Both parts are combined during performance of the experiment 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 sequential approach The i th individ ual likelihood is computed from the i th data pair the i th record and the i th element of the result Determination of the i th element of multidimensional results follows the column major order model see Glossary in Section 15 7 Individual likelihoods are multiplied afterwards to form the final likeli hood function and consequently the posterior probability as described in Section 4 7 The number of average variance data pairs and the number of values of the result 7 product of the extents 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 model bdf for the multiple likelihood function case several likelihood functions with different likelihood name Generally the like
289. ment 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 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 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 After running the dot script SE_HOME bin simenv_get_sh the name of an experiment factor 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 fac tor_name gt 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 trans formation program that reads in all the native model output and outputs it to SimEnv
290. ment operator from Tab 8 5 on page 123 The following restrictions apply e aggregations avgw and hgr cannot be used e aggregation count has a differing syntax count factor value type all def undef factor name factor value range multiple application of minprop and or maxprop causes senseless results Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 The following rules hold for the operator dfd e Generally by the filter argument arg1 those runs from the run ensemble are selected and or aggre gated here interpreted as filtered that are used for the formation of the result Consequently if no filter is specified all runs are used Example czes mn cj 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 represents the full range of values by factor name or lt factor_name gt Example sel pl sel pl Seis pil eel mi sel a pl eel ifjfol sel spLi eel _a jel and all these select operators are redundant e The select operator can also be applied to force a certain experiment factor to be used as a coordi nate in the result of the operator dfd if this factor is combined in parallel with other factors By de fault the first factor of
291. model gt _ f c py sh as inc SE WS generated during experiment preparation only for service run not for service restart 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 model run for the shell script and ASCII interface Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 11 5 User Defined Files and Shell Scripts Temporary Files Tab 11 7 lists the mandatory or optional shell scripts and files the user has to provide for running SimEnv services Tab 11 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 the file lt file gt has execute permission Shell script file pout deo trs rtu Explanation Exist status mation workspace see SE WS Section lt model gt cfg ASCII user defined general configuration file optional 11 1 lt model gt mdf ASCII user defined model variables description file mandatory 21 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 mode
292. mp could be moving averaged for all values of lat lon1 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 time1 The operator that allows for this double averaging would have the arguments move arg 201 lin O bios Example 8 6 Operator move avg 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 after performing moving averages for those dimensions that correspond to digits smaller than the current one If the n th digit of arg1 is 0 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 m E Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN Tl 133 e Operator rank 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 arg2 and arg2 of arg2 that are identical or have a maximum relative difference of abs arg2
293. n 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 consumption see Section 11 3 For keyword general nodata value short noda ia value float nodata value byte noda a value int nodata value double sub keywords Check Section 11 8 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 not applied set the value to no If it is applied in Fortran 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 consumption per call of simenv slice and simenv put since slice information is then stored in external files rather than internally as for slices 7 f c For keyword model sub keyword auto interface Che
294. nal 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 out put variable or parts of it can be addressed in experiment post processing see below Dimensionality di mensions and coordinate description of this data field is derived from the model output variable description in model mdf Model output variables are specified in the ASCII model output description file model mdf cf Tab 5 3 on page 42 by their Name Data type cf Tab 5 4 on page 43 Dimensionality Extents Coordinate assignment to each dimension Index assignments to each dimension Use the service simenv chk to check variables description in model output description file lt model gt mdf Addressing model output data fields or parts of it in experiment post processing is done by corresponding model output variables names For variables with a dimensionality greater than 0 it is possible to address only a part of the whole variable field by Specifying for a dimension an index range i by i lt index_value gt index valuez lt index_value gt lt index value index value2 index value if index value is missing i denotes the complete range of a dimension Specifying for a dimension a coordinate range c by c lt coordinate_value gt coordinate valuez coordinate value4 lt coordinate value2 fo
295. names in user defined files sss 204 Elements of a coordinate transformation file ssssssssssssssssseseseeeeeeeneeener enne nnne 205 Syntax rules for value lists eene ener enne ren nenne enne nnns 208 SimEnv installation directory structure sssessseeseenen eene nennen mre enne nnne nnns 217 System requirements for running SimEnv sssssssesesseeeene nennen nennen eren nennen nnns 217 Current SimEnv technical limitations svici enn ener nennen nnne 219 Implemented example models for the current version nennen 220 Implemented model and operator related user files for the current version 221 Available user defined operators cce etae Haseena te Led Roe ER aa Ra RV fescue oe e ad p ae 222 Factors of the generic model world 0 0 0 2 ce cece cece ee eeeeee eect eect cece aeaeeeeeeeeeceaeaeeeeeeeeeceaeaaeaeeeeeeeeencueeeeeeeeeeeea 223 Experiment post processor built in operators in thematic order 247 Experiment post processor built in operators in alphabetical order cccccceeceeceeeeeeeeeecteeeeeeeeeeeees 251 Character arguments of experiment post processor built in operators eeeene 255 Constant arguments of experiment post processor built in operators eeeeeee 257 Experiment post processor unit invariant built in operators sseeeen eme 258 Additionally used symbols for the mo
296. ncorrelated and additive Consequently the likelihood 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 s 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 the inspection of the factor space for a given chain length but reduces the efficiency of the algorithm in terms of the ratio between outranged candidates and the chain length That s why SimEnv offers beside the stan dard Metropolis Hastings algorithm a 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 Me tropolis r
297. nction run ensemble of the bias of cost function from its optimal value Replace xxx by the result of the previous operator run ensemble of the ranks of the cost function Example file world post OPT SA Example 8 16 Experiment post processing operators for OPT SA m S ar Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T J 153 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 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 1 4 A user defined operator itself is a stand alone executable that is execut
298. nennen enne entes 213 Didzdszspszcmm 215 Version Mienet inizio pem System Requirements Eee BEI Ce lees Linking User Models and User Defined Operators ssssssee eee 220 Example Models and User FileSend nen esempi aa taairan ataa idiin 220 Example User Defined Operators cene enero rh ntn nnan nena reste k aa bisti REA ERR unns 222 Examples for Model Interfaces cniin teorica aaa aida aana a secare dan 223 Example Implementation of the Generic Model world eee eem 223 olaca alele AR 224 Fortran Model with Semi Automated Model Interface 225 Xm 226 erc 228 a 1 iaTornd iore A 230 Java Model sanee EE 231 Matlab Model 232 Mathematica Mode o 233 CLERI 234 Model Interface at Shell Script Level ssssssee diniinan 236 Model Interface for ASCII Files cccccccceceeececcee cece ee eeeeeeaeaeeeeeeeeeaaeaeeeeeeesecaaeaeeeeeeeseeeeeaeeeeeeeensaeaeees 237 Semi Automated Model Interface at Shell Script Level 238
299. nfiguration file eene 185 Nisl ee 186 Shell scripts and dot scripts that can be used in lt model gt ini run end J es 188 SimEnv include files and link scripts ssssssseeeeeene nennen eren 189 User files and shell scripts to perform any SimEnv service ssssee emm 190 Files generated during performance of SimEnv services esssseeee em 191 Built in model output variables cccccccceeceeeee cece ee ceceeeaeeeeeeeeeceeaaeceeeeeseseeaaeaeeeeeseseecaeeeeeeesesecaeeeeseeeeeeeea 195 Built in shell script variables in model run sseeseeeee eee enne 195 Built in coordinates for experiment post processing ssssssssssseseseeeeeenen eene 196 Case sensitivity of SimEnv entitles ciis e cinee t teneat tad dee da dados Faune dac aa nc adea dae dae 197 Data type related default nodata values sssssssssssssssssssssssesesee enne nennen eren ntn nter nnne 198 Environment ucc E 200 Programs to include in the environment variable PATH c ccceceeeeeeeeaeeeeeeeseeeeeaeeeeeeeeeeenaeeeeeeeeeeeea 201 User defined files with general structure ssesseeeeneeeneene enne enne eren nennen 204 Constraints in user defined THES ooi tede tet EE ertet etude rhe deb He e a eR ro nee Due ege noce 204 Reserved names and file
300. ng 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 factors into a sequence of output values gt variables Normally inputs are parameters initial values or driving forces to the model outputs are state variables of the model For many cases the model will be state deterministic time and space dependent For SimEnv the model its factors and variables are coupled the SimEnv in the process of gt interfacing the model to SimEnv Model coupling model interface Model interface Interfacing a 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 variable 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
301. ng 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 coordi nate usage The result of the operator dfd is always arranged according to ascending coordinate values for all additional dimensions e Independently from the declared sequence of the applied aggregation and select operators in ar gument 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 im plicitly by the select operator e 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 factor from this parallel sub space in the normalized see Section 6 4 1 comb line is used in the result m S ET Multi Run Simulation Environment SimEnv User Guide
302. nge 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 candidate 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 likelihood 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 model blog is larger than the number of sample points in lt
303. ni 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 restart 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 simenv run char touch such a file in model run and or in model rst as an indicator to stop the complete experiment after single run simenv run int 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 pbs model specific job control file to submit an experiment in dis tributed parallel and or sequential sub mode under Distrib uted Resource Manager control jcf for LoadL pbs for PBS Torque e Copy from SE_HOME bin simenv_ dis
304. ni_c check return code of model interface functions at least here if simenv_sts 0 return 1 fe enmeny ger b Dec emily INEO ee SQ V2 Sl simenv sts simenv get run c amp simenv run int simenv run char simenv sts simenv get c pl amp pl 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 World world world computeAtmo pl p2 p3 p4 simenv sts simenv put c atmo g char amp world atmo g world computeBios pl 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 IH 229 ALTE 4 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 d H 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 amo zeros AS 90 ATP T bloat bios zeros 36 90 20 Float atmo g zeros 20 Float pl 1 p2 2 DSSS p4 4 simenv ini py simenv get run py o
305. nly a run slice out of the whole run en semble 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 11 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 function BAY BC and OPT SA For more information check Fig 7 1 m ERE 104 X HN T J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 7 3 4 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 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 Forsequential experiment performance on the login node and or on a compute cluster rename in the model wrap shell script model run after running the model its outputs to run number related file names This solves most of the problems since always only one model run is active e For parallel and distributed experiments on the log
306. nly if necessary simenv run int int simenv get run py pl float simenv get py pl p1 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 e es 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 m ASA 230 y H T j i Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 static float bios new float 36 90 20 static int atmo g new int 20 eite testem t bios g public static void main String args int simenv sts simenv run int int idecade level float phi lat 1 F tloat omegalelat 2 E float pollen float omega lon 4 F simenv sts Simenv simenv ini ja
307. nsional 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 na m S n Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 3 Hn S p lt 261 Default value The nominal standard numerical value of an gt experiment gt factor The default value is specified 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 varia
308. nt Performance controlled by the Distributed Resource Manager csere 103 Experiment Partial Performance cccccccesceeeececeeeeeeeeeaeeeceeeeeseaaeaeceeeseeeaanaeceeeeeseesaeaeeeeeeeesnanaeees 104 Peculiarities of Multi Run Experiment Performance sseseee eee enn 105 Inter Node Communication for Parallel Sub Mode at Compute Clusters seseesssss 106 Experiment Restante cee 106 Experiment Related User Shell Scripts and Files emen 108 Saving EXperlITiBrits sects ecncceesscacesteadeaescnscth dst tomes e se RSS enis Pe vales 1a E un AS FLUR ESSE Bets ar ss iateedgsiten goidean 110 EXPERIMENT POST PROCESSING bs 1 1 cavahicncsuaes aar aaa aaa a a iaaa da nd EL e den apa E Ru US tii GENE Fall APPFOACH pm 111 Post Ptocessor Results eerie rein nir tn tr rete By adr saad censtandsade Paci ERR KON RATE Shed deus cadeneeneaeeeaees 111 Su ruf 113 Model Output Variables E 114 Operator Sras 116 Operator Classification Flexible Coordinate Checking sseee 117 Built In Generic Standard Aggregation Moment Operators ssessee em 119 Built In Elemental Basic and Advanced Operators eene enne 120 snae 120
309. nt relate files e Start simenv run world Ing 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 Ing latest lt simenv_res_char gt to visualize output from the latest post processing session world Ing res simenv res char 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 Ing mod more simenv dmp world Ing res more to dump a SimEnv model or post processor output file Check in the current workspace the model interface log file world Ing mlog native model terminal output log file world Ing nlog experiment performance log file world Ing elog Start simenv cln world Ing 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 Ing cfg world In
310. nt rule for this coordinate For a coordinate with non equidistant coordinate values the coordinate values necessary for the co ordinate extension are defined by the sub keyword values_add If both position_shift and values_shift are specified for one coordinate firstly position shift is ap plied to the coordinate and then the additional coordinate values from values_shift are added the the coordinate without applying the position_shift value Coordinate numbers lt coordinate_nmb gt are integers counting from 1 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 For the keyword coordinate the same rules apply as for the keyword coordinate from the model out put description file model mdf Coordinates are incorporated additionally into the original coordinate set only for the current result 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 J a j l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 akwWNDN general general modify modify modify modify modify assign assign assign assign ahwWN dimension dimension coordinate coordinate name newl dim2 dim3 lat new2 coordinate name dimi dim2 dim3 dim4 dim5 dim dim dim dim d
311. nv 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 run number Ea for model run rst of a single run Value simenv run int SE RUN1 first single run for model run rst of an experiment Value yes no Additionally make sure that in the shell the noclobber option is not set To perform SimEnv make sure that paths to the directories of the programs as specified in Tab 11 15 below are included in the environment variable PATH Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Tab 11 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 11 14 above internally by all SimEnv services Keep in mind to specify a PYTHONPATH environment variable dependent on interfaced Python models
312. oc sens Tab 8 14 149 lin rel char arg1 arg2 relative linearity measure loc sens Tab 8 14 149 log arg1 natural logarithm basic Tab 8 4 121 log10 arg1 decade logarithm basic Tab 8 4 121 ess 3 ri 252 y HN T J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 On Name Meaning Type See page mask char arg1 arg2 arg3 mask elements of argument arg2 set them advanced Tab 8 8 126 undefined un mask file char arg1 mask elements of argument arg2 set them advanced Tab 8 8 126 arg2 undefined according to information in file char arg1 matmul arg1 arg2 matrix multiplication advanced Tab 8 8 126 max arg1 argument maximum of values aggr mom Tab 8 5 123 max e arg1 run ensemble maximum UNC MC max l char arg1 arg2 dimension related argument maxima of values aggr mom Tab 8 7 124 of arg2 max n arg1 argn maximum per element aggr mom Tab 8 5 124 maxprop arg1 index of the element where the maximum is aggr mom Tab 8 5 123 reached the first time maxprop e arg1 run number where the maximum is reached UNC MC Tab 8 13 145 the first time maxprop l char arg1 arg2 dimension related argument position 1 n aggr mom Tab 8 7 124 where the maximum is reached the first time of arg2 maxprop n arg1 argn argument posi
313. odel script script model 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 Normally this shell script will call the link scripts for inter faced models in SE_HOME lib 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 func tions 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 integer 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 O The source code sequences are included in the model source code e for Fortran e for C C e for Python e forthe model interface at shell script level e forthe model interface at ASCII level by by by by by include lt model gt _f inc include lt model gt _c inc from lt model gt _py import SE_WS lt model gt _sh inc SE_WS lt model g
314. 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 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 an array White spaces gt also known as blanks ASCII characters space and horizontal tabulator used in gt user defined files or within gt result expressions in gt experiment post processing Workspace The directory a SimEnv service is started from and the SimEnv user defined files such as lt model gt mdf lt model gt edf model run lt model gt cfg are located in Q4 m RIS Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN T J lt 265 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013
315. ollow their own distributions In the corresponding k dimensional factor quantile space QX this results in a regular equidistant grid 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 selected from an existing grid point to compute an elementary effect as described below In the fac tor space X the unique jump width A transforms for each factor x to values Aim where m corre sponds to the value of x of the existing grid point Select at the p level grid in the factor space randomly a starting grid point x X4 X and ran domly another grid point x X1 Ls Xi XitAim s Xie sess XQ that differs from x in exactly one factor X by Aim i71 K Compute from these two grid points the elementary effect of the factor x for the model state variable z by d x z z x ging BETS Xi im Xie 3 3 Xk 2 x4 er Xx Aim Proceed by randomly selecting a new grid point x to the previous grid point x for another elemen tary effect dj x z ij until k 1 points xX SS X are sampled Such a series of k 1 points is called a trajectory For one trajectory k elementary effects di x z i 1 K one for each factor can be determined by two consecutive points x and x i 0 K Determine randomly r trajectories in this way finally resulting in r elementary effects d
316. ollowing 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 54 0 x1 simenv sts simenv get f 5x 0 Xx e 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 amp simenv zero amp x simenv sts simenv get c amp simenv zero amp x e for Python file lt model gt _py py from simenv import simenv ini py simenv run int int simenv get run py x1 float simenv get py 4 0 x float simenv get py Xk 0 a 64 y HN T I J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 e forthe model interface at shell script level file model sh inc 8E HOMEj bin simenv ini sh 8E HOME bin simenv get run sh factor name x4 factor def val 0 SE HOME bin simenv get sh factor namez 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 model edf For the Fortran C C model interface e a m
317. ols such as the CDO Schulzweida et al 2009 or NCO NCO 2012 operators lt model gt ndf is an ASCII file that follows the coding rules in Section 12 1 on page 203 with the keywords names sub keywords and value as in Tab 10 4 Use the SimEnv service simenv chk to check a NetCDF attribute description file Tab 10 4 Elements of a NetCDF attribute description file model ndf line type o optional Max Keyword Name Que Line ine Value Explanation keyword type nmb general lt nil gt descr o any lt string gt general attribute description glob attr lt nil gt delete o 1 attrib name delete global attribute attrib name replace o any lt attrib_name gt replace insert global attribute lt string gt lt attrib_name gt by lt string gt loc_attr lt var_ delete 0 1 attrib name delete local NetCDF variable name attribute attrib name for co name var name co name or amp v amp wildcard amp amp amp c amp replace o 1 attrib name replace insert local NetCDF amp r amp text lt string gt variable attribute amp amp byte short int attrib name float double by lt string gt and or val list val list for var name val list co name or list wildcard amp amp lt val gt lt val gt 3 ri Multi Run Simulation Environment SimEnv User Guide for Version 3 1
318. onally used symbols for the operator interface interface functions in Tab 8 19 and Tab 8 20 from the object SE_HOME lib libsimenv a to a user defined experiment post processing operator Used symbols csimenv_ lt string gt isimenv_ lt string gt jsimenv_ lt string gt Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 library Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 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 www ansi org is used in SimEnv to store information in gt user defined files and on request in post processing output files BAY BC Bayesian calibration gt Experiment type to reduce uncertainty about gt factor values by deriv ing a representative sample from factor prior distributions while having measurement values from the system available for gt model measurement comparison Column major order model A rule how to st
319. ong 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 specific operators There is a simple interface to write user defined and to derive com posed 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 binary format m Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 J HN T J 3 m 8 4 Solis Ys Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 in grey boxes 1 1 Document Conventions Tab 1 1 Document conventions Character I Meaning string angle brackets enclose a placeholder for a string braces enclose an optional element sss Loss ee
320. only for plan sample distr lt distribution gt sample __ Oo 1 real val4 lower bounds real val and include real val427 upper bounds real vali of aee intervals to include for sam real val pling according to distribution real valy2 distribution real vali lt real vali sample _ 0 1 real val4 lower bounds real val and exclude real val427 upper bounds real vali of ECT intervals to exclude from sam lt real_valm1 gt pling according to distribution lt real_valm2 gt lt distribution gt real vali lt real vali specific nil seed o 1 random fixed method how to initialize the random number generator runs m 1 lt val_int gt number of runs to be per formed for the experiment function o 20 lt result gt stopping function to use by 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 3 m 84 y HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 To Tab 6 8 the following additional rules and explanations apply 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 72 6 5 4 Stopping Ru
321. operators are applied to each element of the argument Example sin bios sin bios i j k for all addressed i j k If an argument value restriction is not fulfilled for an operand element the corresponding element of the operator result is undefined For examples check Section 8 3 5 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 appending suffixes to the generic operator name Appending no suffix Aggregate the only non character non constant argument The result is a scalar an operator result of dimensionality 0 Appending suffix _n _n stands 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 The result has same dimensionality extents and coordinates as the arguments Appending suffix 1 stands for loop Aggregate the only non character non constant argument separately for selected dimensions Di mensions to select are described by an additional loop character argument These operators corre spond to the group by clause of the standard query language SQL of relational database manage ment systems The result has a lower dimensionality as the only non character argument according to
322. or Additionally lt model gt odf hosts for composed operators the corresponding operator chain using formal 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 line type m mandatory o optional Max Sub Line Keyword Name keyword type line Values Explanation nmb general nil descr o any lt string gt general operator descriptions opr_ lt user_ descr o 1 lt string gt operator description defined defined_ arguments 1 int val4 number of arguments defined operator int val for the operator name gt int vals int vali 2 0 int val character arguments int val 2 0 integer constant arguments lt int_val3 gt 2 0 real constant arguments lt int_val gt gt 0 normal arguments opr_ composed descr 0 1 lt string gt operator description composed operator_ arguments m 1 int vali number of arguments defined name gt int valz for the operator int vals Explanations and restrictions int vali 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 a
323. ordinates of arg2 arg2 result to transform coordinates run values of arg 2 for the 1 run char arg selected single run 0 arg2 number explicitly or implic char arg1 run number selection atmo itly coded in char arg1 for all experiment run types sel t pl 4 run number atmo 0 lt char arg1 lt no of runs addit for DFD and LSA filter argument same as filter argument of operators dfd and sens lin 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 run nr and or char_arg1 run information type total number of runs of the run nr experiment for current run number nr of runs for number of runs of the experiment transpose transpose arg2 according diMarg2 21 transpose char_arg1 to sequence in char arg1 diMres diMarg2 3142 arg2 eXtres i EXtarga 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 usage advanced char arg1 operator name or all basic trigonometric aggr moment advanced multi run user defined for the corresponding operator classes MEME 3 ri 1 28 y HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 The following explanations hold for the operators in Ta
324. ore the elements of a multi dimensional data array to a 1 dimensional linear vector representation and vice versa A multi dimensional data array array 1 ext 1 ext2 1 eXtgim 1 1 Xtaim of gt dimensionality dim and gt extents exti ext eXtaim4 exta is mapped on a 1 dimensional vector vector 1 ext ext extq4 exta of ex tent ext ext extgim 1 exta in the following way ipointer 0 do dim 1 eXtuim dO igim 1 1 EXtaim 1 do iz 1 ext do i 1 ext ipointer ipointer 1 vector ipointer array i i2 laim 1 laim 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 The column major order model is used in Fortran and Matlab The opposite model where rows of a matrix are listed in sequence is called row major order model and is used in C C 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 dime
325. ormally more than one lines with differing sub keywords belong to one keyword block e sub keyword is a string Sub keywords are defined only in relation to the user file and the keyword under consideration e value lt substring gt sep lt substring gt is a string with user file keyword and sub keyword related information e sep is 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 12 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 11 12 on page 197 Q4 m S ae Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN T J lt 203 Tab 12 1 User defined files with general structure File Contents See description in Section on page lt model gt cfg general configuration file 14 1 181 lt model gt mdf model output description file 5 1 37 lt model gt edf experiment description file 6
326. ormance Tuning 2 1 niei terere adierei hana dee aca de Fear nea aeta in educa 188 Model Interface Scripts Include Files Link Scripts sssssssssssssseeeneeneeener nnne 188 User Defined Files and Shell Scripts Temporary Files ssem em 190 BUilt IN Cu C MMEMEMMMEEEEEEEEEEEEEEEEEEAASAAVWW W UuUqQ 195 Case Sensitivity PE 197 3 m cJ HN PIE Meme Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 11 8 11 9 12 12 1 12 2 12 3 13 14 15 15 1 15 1 1 15 1 2 15 1 3 15 1 4 15 1 5 15 2 15 2 1 15 2 2 15 2 3 15 2 4 15 2 5 15 2 6 15 2 7 15 2 8 15 2 9 15 2 10 15 2 11 15 2 12 15 2 13 15 3 15 3 1 15 3 2 15 4 15 5 15 5 1 15 5 2 15 5 3 15 5 4 15 5 5 15 6 15 7 Numerical Nodata Representation sciis a a arai 198 Operating System Environment Variables ccc essen meer nnne 200 STRUCTURE OF USER DEFINED FILES COORDINATE TRANSFORMATION FILES VALUE LISTS 203 General Structure of User Defined Files sssssssssssssssssssesseeeen nennen eren nne 203 Coordinate Transformation File corteo inet tarte aaa EEOAE EELEE NEE 205 ASCII Data Files and Val e LEISts accetto tho tein repe st Ka see Seed Ro tae Pa S Ex aene ca se DE e ede 208 DIMENV PROSPEC WS ixccccsscececs 211 REFERENCES AND FURTHER READINGS sese eene ene enn enne
327. 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 column major order model for multi dimensional fields cf Section 15 7 Glossary lt user_name gt lt begin_date gt lt end_date gt simenv hlp acquire basic SimEnv help information for the specified topics topics simenv sta 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 repetition time 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 key lt user_name gt get access to the SimEnv visualization server Only for systems where the SimEnvVis visualization server is not hosted on the local machine c
328. 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 DRM services for the end of the last parallel single model run To support bookkeeping of SimEnv applications on PIK s compute cluster under LoadL control insert into the job control 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 model 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 under DRM LoadL control llsubmit my parallel model jcf f or run a single run of the model under PBS Torque control qsub my parallel model pbs SSE HOME bin simenv end sh Example 5 7 Shell script model run for a parallel model Q4 Re 66 J HN TT i J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 5 12 Using Interfaced Models outside SimEnv To run a model interfaced to SimEnv outside the simulation environment in its native mode as before cod
329. parency 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 inl f simenv_get_f sim real 4 model facta source code e dirm nslon model var source code ef model factor is the default factor value as specified in the previous statement to be used as the adjusted value if edf factor is undefined in model edf model factor simenv_sts simenv get f Cedf_factor model factor model factor model var simenv sts simenv put f model var simenv_sts simenv ini fW simenv sts simenv end f model factor is 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 m S yi HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 5 2 Coordinate and Grid Assignments to Variables To each model output variable that is to be stored during the perfomance of a SimEnv experiment to SimEnv output data structures e Adimensionality dim 20 e Extents ext i 21 with i71 dim e Coordinates coord i with i71 dim are assigned to The dimensionality is the number of dimensions the model output variable has A dimensionality of 0 corr sponds to a single scalar dimensionality of
330. perand within a multi run operator normally results in application of the operator on the op erand values from the whole run ensemble or parts of it and in aggregating across the run ensemble accord ing to the operator Addressing an operand outside a multi run operator results in using the operand for the default run number 0 of the experiment The majority of the built in experiment specific operators are multi run operators Exceptions are referenced 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 can not be applied recursively For experiment type UNC MC one of the multi run operators is avg e arg that computes for each element the run ensemble average for the operand arg The corresponding single run operator is avg arg that compute the average from all elements of the multi dimensional operand arg avg arg computes the average of arg from all of its elements for the default run number 0 of the experiment as it is applied outside a multi run operator Dimensionality 0 Coordinates without Extents without avg_e arg computes for each element of arg its average over all single runs excluding run no 0 of the run ensemble Dimensionality dimensionality of arg Coordinates coordinates of arg Extents extents of arg avg_e avg arg
331. prop STOA atmo 20752107 47 7 2 0 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 age JL 39 Aoin 1397 5057 05 encuo ZO8 20 1720 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 eve LOTOO ouo Jb OE p euge 20 8 2 0 7 55 7 5575 2 9 temporally averaged all level zonal tropical minima Dimensionality 1 Coordinates lat Extents 11 Example file world post adv Example 8 8 Experiment post processing with advanced operators 8 4 Built In Experiment Specific Operators 8 4 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 individu ally from each single run and assigns this result also to that single run m Bae 136 J T i J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Addressing an o
332. 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 is an For model validation system model comparison control design decision mak nealing i ing Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 The experiment types come with special properties 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 Some methods take the sample from pre defined factor levels rather than from pre defined factor distributions The former approach allows for performing an analysis without knowledge about factor distributions and the accompanying distribution parameters 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
333. put 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 64 res nmb 2 parameter NR DIM MAX 9 reote Ep ome Chimemssom s EE eoo dava es reali pointer chimemsiem s 89 result wellues integer 4 idim iext NR DIM MAX character result expr 1024 coord name 64 prefix 32 header 400 Chieicecreie seexudl ieu 197 wesullic Cese il2si seule iab 32 open Unie isle mimm tee name inf rea TRO 2 Sra ene torm formatted status old open unit 2 file trim model name res res_nmb ascii form formatted status old do irec 1 3 read 1 a33 a400 iostat iostat prefix header enddo iostat 0 do while iostat eq 0 read i ass all92 cr estostat dostat pretixresultemame SEXE FRO Sitecitee ne cO Sie read il a33 8120 7 uO Sica Os ales pretiz eee Suite dese reedi 33 8 1024 lostat iostatil pretiz result egr reedi assis 4 ee O Sie ale ALO Se clesls pretiz result unir Read ly a33 9al3 ates istas meta rest 1 1 1 NR DTM MAS Fengeh result do i 1 NR_DIM MAX if iext i eq 0 exit llremenetbgrse suscite meae e sisse cB read 1 a33 a64 iostat iostatl prefix coord name allocate coord values iext i ibeg 1 do whil ibeg le iext i iend min0 ibeg 9 iext i reac i v LOIS 7 p lostat icstati eexosee
334. r number 9 dimensionality of a result 9 length of a complete result string with optional description and unit characters 1 024 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Entity ie allocatable main memory segments for computing a result number 10 total allocatable main memory MBytes 2 048 results res_ lt digit gt lt digit gt in a NetCDF post processor output file number 99 post processor output files lt model gt res_ lt digit gt lt digit gt nc ieee ascii number 99 15 1 3 Linking User Models and User Defined Operators 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 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 15 1 4 Example Models and User Files For the following models corresponding files of Tab 11 7 of can be copied from the cor
335. r NetCDF output files are visualized by SimEnvVis and all post processor output is of type float real 4 IH 199 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN ALTE 11 9 Operating System Environment Variables The following operating system environment variables are used by SimEnv Tab 11 14 Environment variables Environment Definition Variabile Meaning Status Explanation SimEnv access settings Set by the user Used within all SimEnv services SE_HOME SimEnv home mandatory Value has to be defined by the user directory 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 val int 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 SimE
336. r per dimension get_data get data from an external dimensionality extents and coordi get data char_arg1 file nates according to char_arg3 and netcdf char_arg2 char_arg4 data nc char_arg3 data def 22 M lee a char arg2 data file name char arg3 coordinate specification transformation file name arg4 variable to get from the data file 1 m 126 z H T f Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Name Meaning Argument restriction s argum En E value result description m restriction Tab 8 1 page 118 Example get experiment char arg1 char arg2 char arg3 arg4 include an other post processed experi ment output 1 but coordinates according to char arg3 char arg1 experiment directory char arg2 model experimented with char arg3 coordinate transfor mation file result from the other experiment arg4 get experiment mod res mod Mnodsctt avg atmo 400 get table fct apply table function with 1 get table fct char arg1 linear interpolation of table table usr arg2 char arg1 to arg2 char arg1 file name atmo if conditional if construct 5 if char arg1 ver arg2 char arg1 comparison operator atmo arg3 arg2 comparator 400 arg4 arg3 arg4 new assignments atmo mask mask values of arg2 5 mask char arg1 set them undefined by
337. r smp val low for syntax see Tab 12 5 specific nil 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 e Sub keyword sample is either mandatory for all factors or undefined for all factors e Forsub keyword comb the following rule holds e value default combination for used sub keyword sample e value file directory2 file name for unused sub keyword sample e Values of a value list have to be unique for used sub keyword sample and each factor Assigned values from file directory2 file name can be multiple defined for each factor The sequence of the single runs is determined by the sub keyword comb 6 4 4 Formalisation of the Inspection Strategy Run Sequence The experiment type DFD allows for a flexible deterministic inspection strategy of the factor space in com bined sub spaces e The combination combination defines the way in which the space spanned by the experiment factors will be inspected by SimEnv This is done by concatenating all stated 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
338. r strictly increasing coordinate values coordinate value 2 coordinate value for strictly decreasing coordinate values coordinate value coordinate value if coordinate value is missing c denotes the complete range of a dimension Dimensions with their individual index 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 For one variable c and i can be used in mixed mode for different dimensions Or each dimension c isidentical to i isidenticalto In the general SimEnv configuration file model cfg cf Section 11 1 on page 181 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 J a j l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 cem o ey y e iLL S20 cemere atmo c 0 1 i 20 atmo i 23 1 i 20 atmo c 0 c 2 c 1 c 20 atmo c 0 c 1 9 c 1 c 20 atmo c 0 c 1 c 1 c 20 Having a model output variable definition as in Example 5 1 on page 44 then in experiment post processing result expressions can be and and and and and with address_default index in model cfg and with address_default index in model cfg atmo atmo aAEMOUC Ay el
339. rator 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 charac ter arguments can be checked Dimensionality extents and coordinates of the result have to be de fined 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 dependency of its operands is computed m SEAL S 154 X HN T J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Tab 8 18 Operator interface functions for the declarative and computational part Function name Function description Inputs outputs function value 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
340. rdinate market vaie market number coordinate market values scuaichisic Gime i 1 S variable a descr plant capacity variable a unit cases variable a type float variable a coords plant variable a nine exiccmes eZ variable x descr shipment quantities variable x wae cases variable x type float variable x coords plant market variable ES index esssente cmi 5g ies variable Z descr total transportation costs variable Z unit 1043 US variable Z type float variable modstat descr model status variable modstat type float Example file gams model mdf Example 5 4 Model output description file for a GAMS model m s E o Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 SHN 57 5 7 3 Files Created during GAMS Model Performance Additionally to the files listed in Tab 11 8 during the performance of a GAMS model the files lt gams_model gt _ pre main post inc are created temporarily in the current 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 simenv run int from the experiment is performed individually in a sub directory run simenv run char of the current workspace Each directory is generated automatically before performing the corresponding single run and removed after performance of
341. rds in model edf for DFD default file file name see Section 12 m TE 204 J Ii T f J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 mac descr This is a macro description file mac descr for the SimEnv User Guide macro np_atmo descr atmo outside polar reg final time level 1 macro np_atmo unit atmo_unit macro np_atmo define atmo c 84 56 c 1 c 20 macro mi define avg atmo g c 11 20 Example 12 1 Structure of a user defined file 12 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 Acoordinate description of the result has to be modified in a way that it matches with a defined co ordinate of the model experiment under consideration
342. re 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 Section 11 8 e f no coordinate is defined as the second argument the values of all zero dimensional variables are expected 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 12 3 with the ex ception 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 number 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 interpretation 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 Initiali
343. recast arg2 from arg1 regrid char arg1 arg2 assign new coordinates to arg2 advanced Tab 8 8 126 rng e arg1 run ensemble range UNC_MC Tab 8 13 145 max_e arg1 min_e arg1 3 m Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T J 253 ues of arg2 Name Meaning Type See ae round int arg1 arg2 round value arg2 to int arg1 decimal places basic Tab 8 4 121 run char_arg1 arg2 values of arg2 for a single run selected by advanced Tab 8 8 126 char_arg1 run_info char_arg1 current run number and or number of single advanced Tab 8 8 126 runs of the current experiment sens_abs char_arg1 arg2 absolute sensitivity measure loc sens Tab 8 14 149 sens rel char arg1 arg2 relative sensitivity measure loc sens Tab 8 14 149 sign arg1 sign of value basic Tab 8 4 121 sin arg1 sine basic Tab 8 4 121 sinh arg1 hyperbolic sine trigonom Tab 8 4 121 skw_e arg1 run ensemble skewness 3 moment UNC_MC Tab 8 13 145 sqrt arg1 square root trigonom Tab 8 4 121 stat full real arg full basic statistical measures UNC MC Tab 8 13 145 real arg2 real arg3 real arg4 arg5 stat red real arg reduced basic statistical measures UNC MC Tab 8 13 145 real arg2 arg3 sum arg1 argument sum of values aggr mom Tab 8 5 123 sum e arg1 run ensemble sum UNC MC sum l char ar
344. res lt simenv_res_char gt ieee ascii for each result 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 i for dim gt 0 i 1 21 else result number 02 The vector result value is stored in the column major order model cf Section 15 7 Glossary The Fortran code in Example 15 15 reads experiment post processing ASCII output files model res simenv res char 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 m EE 180 Ey HN T n lt Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 11 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 experiment 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 11 1 Genera
345. responding exam ples directory SE_HOME exa to 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 LEE d Explanation source code world f Fortran global atmosphere biosphere model world f f at resolution of lat x lon x level x time 45 x 90 x 4x 20 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_m Matlab world_m m world_sh Shell script level world_sh f world_shput f world_as ASCII interface world_as f m AAA x 220 J HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 model Language source code Explanation world f auto semi automated model interface Fortran world f auto f world sh auto Shell script level 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 world f 05x05 f 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
346. rg2 count l char arg1 char arg2 arg3 dimension related count numbers of values of arg3 hgr l char arg1 char arg2 int arg3 real arg4 real arg5 arg6 dimension related argument histograms of values of arg6 max l char arg1 arg2 dimension related argument maxima of values of arg2 maxprop l char arg1 arg2 dimension related argument position 1 n where the maximum of arg2 is reached the first time min l char arg1 arg2 dimension related argument minima of values of arg2 minprop l char arg1 arg2 dimension related argument position 1 n where the minimum of arg2 is reached the first time sum l char arg1 arg2 dimension related argument sums of values of arg2 var l char arg1 arg2 dimension related argument variances of values of arg2 Multi run operators GSA EE Tab 8 9 on page 138 morris arg1 get global sensitivity measures for arg1 Multi run operators GSA VB Tab 8 10 on page 139 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 142 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 149 lin abs char arg1
347. ric 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 Markov Chain Monte Carlo MCMC method check also Section 4 7 for examining the state equa tions 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 initially at high temperature Temp and disordered is slowly cooled so that the system at any time is approximately in thermodynamic equilibrium As cooling proceeds the system becomes more ordered and approaches a frozen ground state at Temp 0 Hence the process can be thought of as an adiabatic approach to the lowest energy state E If the initial temperature of the sys tem is too low or cooling is done insufficiently slowly the system may become quenched form
348. ring coordinate values if valuel ne value2 iret 33 enddo endif endif ierror 0 if ichk modus eq 2 then if iret gt 31 ierror 3 elseif ichk_ modus eq 1 then alae lret GETA alienate endif endif endif if ierror eq 0 then 1extl 2 1ext2 2 ntc omes P2 E ite oM 2 ncoBbegaposds 2 ECoNDSgacos2i2 Tok sineny PUT Sema res 36 0 icimensl Sse Cle miei ie ORIS OCTO SAN endif c return error code simenv check user def operator ierror TSE WI end integer 4 function simenv compute user def operator res len res c SimEnv operator results are always of type real 4 Be ESA rss len Tes integer len res Cc declare SimEnv interface functions compile with IS SE HOME inc include simenv opr f inc c auxiliary variables integer 4 iext1 9 iext2 9 IS OMS ORE SUICIDE Os c NP EIS Os 2 c get dimensionality idimens and extents iext for both arguments idimens simenv get dim arg f 1 iextl idimens simenv get dim arg f 2 iext2 C perform matrix multiplication m 0 do k 1 iext2 2 targ quts i il 93 902 11 do i 1 iext1 1 duel ubica wae ab d Sum eges a dL sues br 9 value8 0 indi defined 0 do l 1 iext1 2 lel lergl orret I vates Gb abel aleuaoPA Oris facl simenv get arg f 1 ial fac2 simenv get arg f 2 ia2 m S JHN T iY c Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 if simenv Cak undef f
349. rocessing 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 m E Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 d HN T J lt 211 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 Potsdam http www pik potsdam de research publications pikreports files pr47 pdf Flechsig M Bohm
350. rs Operators transform dimensionality dimensions and coordinates of the their non character operator argu ments into unique dimensionality dimensions and coordinates of the operator result cf Section 8 1 2 There are Single argument operators that replicate dimensionality dimensions and coordinates from the only argument to the operator result Example sin atmo 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 Operators that increase the dimensionality of the operator result and assign new coordinates to the additional dimensions cf Tab 11 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 operands 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
351. run mask arg1 this is NOT a multi run operator mask all values of arg1 set them undefined that belong to single runs of type rejected 1 arg1 must not be a multi run operator bay_bc_run_weight arg1 mask all values of arg1 set them undefined that belong to single runs of type rejected and weight arg1 of unmasked values values that arg1 must not be a multi run operator 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 see Section 8 4 5 UNC MC sum e bay bc run weight 1 ens bay bc run mask arg run 1 bay_bc_run_mask arg bay bc run mask ens arg ens bay bc run weight arg Mask rejected runs of the whole run ensemble returns for rejected runs the undefined value otherwise arg returns for run no 1 the undefined value if it was rejected otherwise arg returns a meaningless result Mask rejected runs and weight runs of type accepted or reflected of the whole run ensemble rejected runs get undefined weights accepted and reflected runs get a weight which is the number of assigned subsequent runs of type outrange or rejected Sum is icreased by 1 Weight is multiplied with arg run 0 bay bc run weight 213 eil the result returns the chain length Example file world post BAY BC Example 8 15 Experiment post processing
352. 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 proc essed 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 random 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 behaviour in the factor space X by a discrete numerical sampling with a flexible 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
353. s 8 3 1 Elemental Operators Tab 8 3 Built in elemental operators Argument Argument restriction s Name Meaning NUM value Precedence result description restriction Tab 8 1 page 118 left parenthesis first right parenthesis first arg1 arg2 exponentiation 2 argi gt 0 second arg1 arg2 multiplication 2 third arg1 arg2 division 2 arg2 0 third arg1 arg2 addition dyadic 2 fourth arg1 arg2 subtraction dyadic 2 fourth arg1 identity monadic 1 fourth arg negation monadic 1 fourth The following explanations hold for the operators in Tab 8 3 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 Ifan 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 8 3 2 Basic and Trigonometric Operators Tab 8 4 Built in basic and trigonometric operators Argument Argument restriction s Name Meaning Se value Example result description restriction Tab 8 1 page 118 Basic operators abs arg
354. s where single GAMS model runs are to be stored by keep ing their corresponding sub directories for syntax see Tab 12 5 time_limit fe 1 lt val_int gt wall clock time 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 o 1 lt string gt sub model output descrip name gt tion type m 1 main sub identifies GAMS main or sub without model eMension get m exactly factor name _ get resulting adjustment for gms number factor name to this model of factors put m exactly var name put values of SimEnv model number suffix set output variable var name of lt index_set gt from this model to SimEnv model lt format gt output output GAMS variable var name vari has the specified suffix and ables index sets and is interfaced from GAMS to SimEnv ac cording to format 3 m 54 y HN T l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 To Tab 5 7 the following additional rules and explanations apply e 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 following single run
355. s Tab char arg1 eXtres diMres number of bins no of bins char arg2 coordres diMres char_arg2 int_arg3 for char_arg2 bin no bin number real arg4 coordres dim e values equidist end 1 1 no of bins real arg5 for char arg2 bin mid bin mid arg6 coordres dim e values equidist end 1 pin mid bin width no of bins heuristic pdfs separately calculated for each index char arg2 bin no bin mid of the those dimensions int arg3 number of bins of arg5 that remain 4 lt int_arg3 no of values of arg6 according to char arg1 or 0 automatic determination max 4 no _of_values_of_arg6 10 real_arg4 left bin bound for bin number 1 real_arg5 right bin bound for bin number int_arg3 real arg4 real arg5 0 determine bounds by min arg6 and max arg6 min arg6 max arg6 all result values are undefined The loop character argument char arg 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 0 at position n means aggregate over the corresponding dimension n of the argument 1 at position n means do not aggregate over the corresponding dimension n of the argument e Loop character arguments formed only of 0 0 0 or 1 1 1 are forbidden m l a Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 d H m 1 25 8 3 4 Advanced
356. s ac cording to the specified factor adjustment type cf Tab 6 2 below before finally influencing the dy namics of the model The sequence of elements columns of each record of model smp corresponds to the sequence of factors in the factor name space cf Section 12 1 on page 203 the sequence of records corre sponds to the sequence of single model runs of the experiment For each experiment a single model run with run number O0 simenv run int 0 and simenv run char 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 model smp The experiment description as specified by general descr lt string gt is used for NetCDF model and or post processor output files check Section 10 1 1 y H a j l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 value is Sat Set to the adjusted factor value
357. s 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 of an experiment for compute cluster architectures Currently IBM s Job management system load leveler LoadL with the parallel operating environment POE and the Linux tools PBS Torque are supported as Distributed Resource Managers DRM For DRMs the processors of a compute cluster are assigned to job classes queues where jobs can be submitted to Three different distribution strategies are offered by the simulation environment Perform the single runs of an experiment e Oonallthe available processor cores of a job class queue dis distributed sub mode The single runs are submitted to the job class queue as single jobs in a way that all available proc essor cores of the class can be used Due to controlling the submit process dynamically by SimEnv the job class queue will not be overloaded by the single run jobs of the experiment Instead the submit process will wait if necessary The submit process itself is started in the background The ex periment performance will start with the first submitted single run when a processor core of the se lected job class queue is free Use this su
358. samples are taken from dis tributions the whole probability density function is explored 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 Often modelers and or analysts are confronted with correlated factors Even if specification of an experiment in SimEnv does not explicitly support correlated samples for example method UNC_MC it allows to import such samples 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 Ny denotes the number of Monte Carlo runs Experi Model Sample taken Factor range vesc SU VEU ment type free from multi factor variation x doors ee en GSA_EE yes levels global no 10 k 1 1 multi dimensional GSA VB yes distributions global no Nw k 2 1 multi dimensional DFD yes levels global yes design dependent multi dimensional UNC MC yes distributions global yes Nuct1 multi dimensional LSA yes levels local no 2 k 1 BAY BC yes distributions globa
359. sed from wildcard operands amp v amp and or amp f amp see Sections 8 1 2 and 8 7 then the three elements of the optional result descriptor can also comprise these wildcard Having a model output variable definition as in Example 5 1 on page 44 then in experiment post processing abs atmo 3 multi operand multi operator result expression applies operator abs to atmo and adds 3 result name res 01 lt result description gt undefined result unit undefined Energy MWh abs atmo 3 as above but result name energy result unit MWh Ginetta cya eer MUI NES as above abs atmo E atmo single operand single operator expression Applies no operator to variable atmo result name res 02 result description aggregated atmospheric state according to lt model gt mdf lt result_unit gt atmo_unit according to lt model gt mdf abs atmo single operand single operator expression Applies operator abs to atmo to variable atmo Operator abs is invariant w r t the unit of its operand result name res 03 lt result_description gt aggregated atmospheric state according to lt model gt mdf result unit atmo unit according to lt model gt mdf sign atmo single operand single operator expression Applies operator sign to variable atmo Operator sign is not invariant w r t the unit of its operand resul
360. sed operators Composed operators 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 related to Example 8 17 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 related to Example 8 17 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 argument arg1 and consequently multiplication between arg1 and hgr is impossible m S a Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T J 161 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 12 1 on page 203 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 operat
361. see Section 8 4 5 see Section 8 4 5 see Section 8 4 5 UNC MC Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 rea sons of numerical stability from the standardized variable arg1 avg_e arg1 sqrt var_e arg1 in stead 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 cor responds 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 opera tors If the character argument of the operator gsa vb run mask is e sample resample all runs from the sample and the re sample e sample all runs from the sample e resample all runs from the re sample e all all runs e resample but factor name all runs where all factors but factor name are from the re sample e resample but all all runs but the sample and the re sample are taken into account The selected case is active until a new selection is made The default value
362. sensitivity indices S and total effect indices Sq 0 lt Si lt 1 numerical irregularities may occur orthogonality xsi 1 ditto S 1 for additive models without interaction effects and orthogonal uncorrelated factors S 20 numerical irregularities may occur orthogonality XS7 21 ditto 3S4 1 for additive models without interaction effects and orthogonal uncorrelated factors Si 2 Si Su 72S if x is not involved in interactions with other factors To determine the 1 order sensitivity indices S and total effect indices S1 Saltelli Saltelli 2002 Saltelli et al 2008 proposed the following cost efficient method For k factors x4 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 i i Si Sik Ai Nk fip 69s aspe Su fin U TA a Sy s s r r r r S r r i 0 nl nk nl nk nl ni l ni nitl nk PS FS nk Sample S Resample R Resulting sample RS Run model for the sample S the re sample R and the k resulting samples RS to get z S 21 zn Z 44 je Sq js Z Sn js Z Su z R z4 z P G4 ETE ETERNA LN USE RREA em vw Zn i z sr44 E sra
363. sh for the multiple setting case running my model for one setting TES DAY IC SIMEON ais tne current Serting NUnbDer i Cile getting KSSiicling Moy salina NOCES GSLTING SPSCLTIC MOCEL amueommieiciLom my model lt setting SE BAY BC SETTING ini Excerpt from model cfg model out directory scratch modout Experiment output is stored for the multiple case and for other experiments with a single likelihood case to scratch modout multiple setting case for setting 1 to Iscratch modout s 1 multiple setting case for setting 2 to Iscratch modout s 2 multiple setting case for setting 3 to Iscratch modout s 3 Example 6 10 model run for BAY BC Multiple case settings 1 data files for the likelihood function file world dat BAY BC1 file world dat BAY BC2 16 data entries in total and 6 data entries in total and data pairs for time 2 1 6 11 16 data pairs for time 2 1 3 6 float nodata value 3 4E 38 TESTE STE OP UTINTE WAL dk 9 s ILL 4 nodata So Aras Ssmo a2 2 iL 1122 57 9x27 4 nodata 2 nodata VISS Osis 12343 9c 123 4 nodata WESA OETA Multiple setting case settings 3 data files for the likelihood function for setting 1 file world dat_BAY_BC1_s_1 same as file world dat_BAY_BC2_s_1 same as file world dat_BAY_BC1 file world dat BAY BC2 see lt model gt run see model run m S v HN T l Multi Run Simulation Environment SimEnv User Guide
364. shell script variables in lt model gt run Built in shell script Meaning variable name 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 Tab 11 11 lists the built in pre defined coordinates that are used in experiment post processing when addi tional dimensions are generated by an operator m s AE Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 o Hi l lt l 1 95 Tab 11 11 Built in coordinates for experiment post processing Built in coordinate name Generated by operator Meaning Definition cf Tab 12 5 bin mid hgr bin mid values equidist end lt xx gt lt yy gt hgr e 999999 hgr with xx 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 sign sens abs signs of incremental change equidist end 1 2 1 sens rel 1 1 stat_measure stat_full basic statistical measures
365. signed 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 coord check without To ensure for two arguments with 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 m S AED Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN J lt 117 Tab 8 1 Classified argument restriction s result description for post processing operators for the different levels of checking a coordinate description see below Argument restriction s result description type number Argument restriction s Result description cf Section 8 1 2 for syntax dimensionality extents and coordinates of the only non character non constant argument arg can be arbitrary same dimensionality extents and coordinates as the only non character non constant argument dimes diMarg extres j Xtarg j for all j coordres j COOrdarg j for all j all non character non constant arguments arg with same dimensionality extents and coordi nates same dimension
366. signed coordinates to the variable Tab 5 3 Elements of a model output description file lt model gt mdf line type m mandatory o optional Max Sub Line Keyword Name keyword type line Value Explanation nmb general nil descr 0 any lt string gt model output description coordinate lt co_name gt descr o 1 lt string gt coordinate axis description unit o 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 12 5 variable lt var_name gt descr o 1 lt string gt variable description unit o 1 lt string gt variable unit type m 1 see Tab 5 4 variable type in the simulation model coords see 1 co name assigns a coordinate axis by be its name to each dimension of low co name the variable Determines in this way implicitly the dimen sionality n of the variable coord extents see 1 lt co_val 1 gt assigns start and end coordi be co vali nate real values from each low coordinate axis to the vari co vala able If missing all coordinate co val values will be used from all assigned coordinates index extents see 1 in val assigns integer value start be in vali2 and end indices for each low ies dimension to the variable in val Indices can be used to ad in val dress the variable during ex periment post processing
367. simenv_ get number of integer 4 number of arguments get_nr_arg_ arguments of the simenv_ flc current operator get nr arg fic function value simenv_ iarg gt 0 integer 4 argument number 0 for result get type arg get data type of an iarg fic argument input larg 0 integer 4 type of argument result larg get data type of simenv_ 1 byte 4 float the result get type arg f 2 short 8 double function value 2 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 fic function value 3 ri 1 56 J H ji Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Inputs Function Function outputs Inputs outputs function value name description f description unction 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 larg tions of an argu lico nr 9 ico nr 1 ico nr simenv get dim ec ment output arg f c Dp d integer 4 formal begin value positions of the coordinates F ico beg pos 9 ico beg pos 1 ico_beg_pos simenv_get_dim_ output arg f c character 64 coordinate names co name 9
368. simenv_res_char gt ieee ascii postproc out_directory experiment post processing output structure description file of an experiment post processing session Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 File Generated in Explanation location Temporary files do not delete during performing the corresponding service lt model gt experiment performance if the experiment is performed by the load leveler in out lt simenv_run_char gt nc ieee model out_directory if out separation no in lt model gt cfg 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 experiment 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 lt model gt _ pre main post inc SE WS experiment performance only for GAMS models auxiliary files model GAMS main and all interfaced sub models model res00 nc SE WS experiment post processing NetCDF representation of the current result for visualization
369. sin max atan max_e avg max avg e max n avg_ med_e avgg_e min avgh_e min_e avgw min_ avgw_e min_n avgw_ nint bay_bc_run_mask qnt_e clip rng_e cnf_e round cos sens_abs cosh sin cot sinh coth sqrt cumul sum dfd sum_e distr_par sum_ exp sym_abs flip tan gsa_vb_run_mask tanh int unmask_file 3 m 258 y HN T ji Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 15 6 Additionally Used Symbols for the Model and Operator Interface Tab 15 13 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 13 Additionally used symbols for the model interface Used symbols csimenv string isimenv string jsimenv string string nc string nc lt string gt nf_ lt string gt f2c_ lt string gt c2f_dimids cdf_routine_name read_numrecs write_numrecs Tab 15 14 lists those symbols subroutine function and common block names that are linked in addition to the SimEnv operator Tab 15 14 Additi
370. sion 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 15 1 1 System Requiremen ts 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 http Awww 03 ibm com servers aix any distribution with the Linux kernel shell Bourne shell sh Python Version 2 3 http www python org NetCDF Version 3 6 0 http www unidata ucar edu packages netcdf Fortran compiler xlf Version 8 0 IBM Fortran compiler http www 306 ibm com software awdtools fortran xlfortran Intel ifort Version 10 0 http www intel com cd software pr oducts asmo na eng 282048 htm or gfortran Version 4 2 GNU Fortran 95 compiler http gcc gnu org Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Component Unix Specification Linux xlc Version 7 0 IBM C C compiler C C compiler cc is used http www 306 ibm com software awdtools xlcpp For the compiler the symbolic link gcc Version 3 3 GNU C C compiler http gcc gnu org MPI only for performing experi ments in compute cluster mode see Section 7 3 http www mpi forum org Version 1 0 For running t
371. sion is omitted in the state variable declaration in the model the source code because the dynamics for this dimension is calcu lated in place The simenv slice Ing function ensures that model output over the omitted source code dimension can be handled in experiment post processing in common Example A typical example is a model to study the temporal dynamics of a process on a latitude longitude grid by analyzing after the experiment a variable out var lat lon time If in the model source code the corresponding array mod var lat lon only depends on lat and lon since the temporal dynamics is modeled in place then this mismatch is handled by the SimEnv interface slice function Fig 5 1 shows the conceptual scheme for the SimEnv interface for a Fortran model The alignment of the contents of the SimEnv model output and experiment description file 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 paradigm 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 out put variable from model mdf is not associated with is handled during the model performance in such a way
372. sionality 4 Coordinates time factor sequ incr sign Extents 20 3 4 2 Sems weil sels in sr Sele a 1 7 sewnuuo 3 relative sensitivity measure for atmo_g for factor p1 and all positive increments Dimensionality 2 Coordinates time incr Extents 20 4 sene abe seli s 0 500 210 05 Marcie omc 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 lim elo seli 0 5 09 805 0 5 7 atmo 5j 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 14 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 The following explanations hold for the operators in Tab 8 16 As discussed in Section 6 7 3 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 experiment output For the multiple setting likelihood function case check Section 6 7 2 only the run ensemble from an individual setting can be post processed Individual setting experiment outputs are
373. 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 6 6 Local Sensitivity Analysis LSA The experiment specific information for experiment description files in Tab 6 1 on page 69 is defined for a LSA experiment as follows Tab 6 9 Experiment specific elements of an edf file for LSA line type m mandatory Sub Line ERG Keyword Name keyword type line Value Explanation nmb factor lt factor_ sample 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_smp_val gt from lt val_list gt have to be positive and ordered in a strictly monotonic increasing manner for syntax see Tab 12 5 To Tab 6 9 the following additional rules and explanations apply 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 m CERE 86 y H T f l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 6 6 1 Sensitivity Functions Run Sequence Example The absolute sensitivity function cf Tab 4 5 on page 30 is as follows for adjustment type Add sens abs factor def val factor smp va
374. square brackets enclose a list of choices separated by a vertical bar italic a keyword or a sub keyword in user defined files au double quotation marks enclose a value string of a sub keyword from user defined files nil 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 attr name NetCDF attribute name co name coordinate name as defined in model mdf or generated automatically see Tab 11 11 directory path to a directory factor adj val resulting adjusted value of a factor by factor smp val and factor def val factor def val default nominal value of a factor as defined in lt model gt edf factor name name of a factor to experiment with as defined in model edf factor smp val sampled value of a factor from lt model gt smp file name name of a ASCII data file model model name to start a SimEnv service with simenv res char 2 character experiment post processor output file number 01 02 99 simenv res int integer post processor output file number 1 2 99 simenv run char 6 character single run number 000000 000001 of an experiment simenv run int integer single run number 0 1 of an experiment sep sequence of white spaces as item separators in user defined and related files lt string gt any string lt val_byte gt
375. sure for dimes diMargo char arg arg2 according to char arg1 appended arg2 dimensions sens rel relative sensitivity measure for according to char arg1 arg2 according to char arg char_arg1 arg2 char arg1 lin abs absolute linearity measure for B h 1 2 dina to ch 1 selection char_arg1 arg2 according to char_arg aggregation filter arg2 lin_rel relative linearity measure for arg2 char_arg1 according to char_arg1 arg2 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Tab 8 15 Syntax of the filter argument 1 for LSA Placeholder Explanation lt filter gt lt select_operator gt select operatorz select operatora select operator self seli sels factor val type factor val range with self select factor range seli select increment range sels select sign range only for sens abs and sens rel factor val type specification how to interpret val range i as a range o
376. t lt NetCDF_variable_name gt lt value_min gt lt value_max gt type dep data range NetCDF variable name index min index max int index range coordinate To Tab 10 3 the following rules and explanations apply e For the standard name long name and units attributes the following information from the op tional result descriptor of an result see Section 8 1 1 and from model mdf model edf are used Keep in mind that the standard name attribute value normally does not follow the NetCDF CF standard as it is defined in the optional result descriptor model edf or model mdf and is not checked for CF compliance For model output If NetCDF variable name var name or built in variable name see Tab 11 9 then long name SimEnv built in model output variable If NetCDF variable name factor name then long name SimEnv model factor For both types is standard name descr string if specified Attribute is omitted otherwise units lt unit_string gt if specified a otherwise where lt descr_string gt und lt unit_string gt are the related strings for lt var_name gt from lt model gt mdf and or for lt factor_name gt from model edf Post processor output lt NetCDF_variable_name gt result name if defined in result descriptor res lt digit gt lt digit gt otherwise standard name result description if defined in result descriptor
377. t SimEnv User Guide for Version 3 1 Jan 25 2013 e Operator matmul The operator matmul performs a simple matrix multiplication for 2 dimensional arguments arg1 and arg2 e Operator move_avg 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 Maien with elements 4 i j max 1 i rl 1 Wj jemax aj j max 1 i rl 1 where wj are weights Value ma is averaged from the rl values ai a i4 ai n 1 Accordingly the first rl 1 values ma ma May are averaged from less than rl values i For the linear moving average the weights are wj 1 and yw min rl i j max 1 i rl 1 Hi for the exponential moving average the weights are Wj e i 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 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 t
378. t _as inc Examples can be found in Example 15 2 and Example 15 12 Multi Run Simulation Environment SimEnv m User Guide for Version 3 1 Jan 25 2013 hs HN T i J 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 11 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 distributed 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
379. t description yes Energy kW my_opr atmo post processing and unit e character arguments yes char_test argll Arg2l atmo of user defined operators e variable and factor name no 3e 6 exp atmo 3E 6 EXP ATMO e operator name e number e macro name e macro identifier m e character arguments no count ALL atmo of built in operators with pre defined values cf Tab 15 10 e character arguments check get table fct MyFile dat atmo of built in operators Tab get experiment Model f without pre defined values 15 10 atmo Exceptions information e directory and yes model out directory MyDir value in file name factor pl sample file MyF user defined files for lt sub keyword gt factor pl unit kWh string directory and in val list e value for lt sub keyword gt descr unit Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Case 4 sen 2 Where Entity ia Example ity lt model gt edf e factor name yes factor pl sample list 1 2 3 for Mathematica asin factor P1 sample list 3 4 5 models the model lt model gt gdf e GAMS model file name yes model sub ml type sub for GAMS model sub M1 type sub models lt model gt ndf e lt attrib_ name gt yes glob attr delete attribl glob attr delete Attribl 11 8 Numerical Nodata Representation For model output with the
380. t 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 column major order model cf Section 15 7 Glossary Use the SimEnv service command simenv dmp for browsing model and result output files See Tab 11 4 for more information 10 1 NetCDF Model and Experiment Post Processor Output The intention for applying NetCDF format for model and experiment post processor output is to provide a self describing platform independent data file format with metadata that can be interpreted by subsequent analyses techniques such as visualization The conventions applied for SimEnv represent a compromise between 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 6 LLNL 2012 Additionally global and local attributes the latter in NetCDF terminology for independent and dependent NetCDF variables that are to be deleted replaced or defined are described by the file model ndf see Section 10 1 3 In principle any NetCDF file can be viewed by the NetCDF service program ncdump NetCDF file Model output data types as declared in the model output description file model mdf cf Tab 5 4 are automatically transferred into NetCDF data types cf the Table
381. t model gt mlog lt model gt nlog lt model gt blog lt model gt bmlog lt model gt olog lt model gt fct mandatory file model experiment type output format dependent Sample and Experiment logs Fig 11 1 SimEnv user shell scripts and files Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 194 11 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 11 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 model mdf and without using the corresponding model interface coupling functions simenv_put_ in the model Tab 11 9 Built in model output variables Built in Dimen model output B Extents Data type Meaning sionality variable name sim time 0 float elapsed user time in seconds when perform ing usr bin time p lt model gt run Tab 11 10 lists the built in pre defined shell script variables that are defined used by the model coupling interface dot scripts S8E HOME bin simenv sh and simenv run mathematica gams and that are fi nally available in lt model gt run Tab 11 10 Built in
382. t model output data structure sese nennen 178 User defined general configuration file model cfg ssee em 186 Structure of a user defined file sssssssssssssssssssssssesee eene enne re nnne 205 Coordinate transformations by a transformation file 207 Examples Of LIE RC M 209 Model interface for Fortran models model world ff 224 Semi automated model interface for Fortran models model world f auto f 229 Model interface for C models model world c c ssssseee eee enn 227 Model interface for C models model world cpp cpp see me 229 Model interface for Python models model world py py se 230 Model interface for Java models model world ja java ssssssssessssseeeeenees 231 Model interface for Matlab models model world m m ssseee e 232 ENA Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Example 15 8 Example 15 9 Example 15 10 Example 15 11 Example 15 12 Example 15 13 Example 15 14 Example 15 15 Model interface for Mathematica model shell script model run eene 233 Model interface for GAMS models model gams model gms see 235 Model interface at shell script level model shell script world s
383. t name res 04 lt result_description gt undefined lt result_unit gt undefined Energy new description abs atmo lt result_name gt energy lt result_description gt new description lt result_unit gt atmo_unit according to lt model gt mdf m a 112 y H T J J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Energy new description sign atmo lt result_name gt energy lt result_description gt new description lt result_unit gt undefined Example 8 1 8 1 2 Operands Operands in result expressions can be e Model output variables In the following abbreviated by Addressing results in experiment post processing as defined in lt model gt mdf arg Example atmo e Experiment factors In the following abbreviated by as defined in lt model gt edf arg Example p1 e Integer constants val int or real constants val float In the following abbreviated by int arg and or real arg Example 12 and 12 12 34 and 1 234e41 e Character strings lt string gt In the following abbreviated by enclosed in single quotation marks char_arg Example tie avg e Operator results In the following abbreviated by arg Example abs atmo atmo 3 e Macros as defined in lt model gt mac cf Section
384. th dimensionality gt 0 and undefined for vari ables with dimensionality 0 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 co val and or co vali The number of coordinates values of the portion has to be greater than 1 co val co val for strictly increasing values of coordinates co val lt co val for strictly decreasing values of coordinates This sub keyword is optional for variables with dimensionality gt 0 and undefined for variables with dimensionality O e With the sub keyword index extents portions of variables are made addressable during SimEnv experiment post processing In the same way multi dimensional 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 described by a start and an end integer value index in vali and or in val exti The index set is a strictly increasing equidistant set of integer values with an index increment of 1 in val4 lt in vali in vali lt 0 is possible This sub
385. th 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 gt Interaction with other factors Nonlinear effect on model output Sensitivity w r t model output gt Result plot for GSA_EE of 21 factors Factors bounded by the dotted line were identified as sensitive factors bounded by the dashed line show interactions with other factors and or a nonlinear effect on model output by HN T n a Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 QX q x q x2 lower figure sample for optimal A 3 5 in the factor quantile space QX q x q x2 numbers indicate individual trajectories The arrows indicate the se quence how each trajectory was generated from sampling points Fig 4 3 Sample for GSA EE Multi Run Simulation Environment SimEnv n User Guide for Version 3 1 Jan 25 2013 J Meath 4 3 Global S
386. that correspond to latitude longitude vertical or time axes If the lower case representation of a coordinate name co name or var name res digit digit co name for the latter see above is e longitude or lon then axis X e latitude or lat then axis Y e level or lev or height then axis Z e time or date then axis T For all other cases the axis attribute is omitted The _FillValue attribute holds SimEnv type dependent undefined values according to Tab 11 13 As result variables res_ lt digit gt lt digit gt are always of type float real 4 the corresponding SimEnv undefined value is used The _ FillValue is not applied to coordinate variables but coordinate run The data_range attribute provides the value range that is covered by the variable in the NetCDF file The value range is bounded by the minimum and the maximum value of the variable The visualization system SimEnvVis see Chapter 9 that is coupled to SimEnv expects that the no data value see Section 11 8 assigned to the variable data type is outside the value range of this variable Normally type dependent default nodata values are outside the value range This may be violated for user defined nodata values In particular pay attention to a user defined float real 4 nodata type when post processor output is stored in NetCDF format as post processor NetCDF out put files are
387. that the factor is unadjusted and or the model output variable is not output In particular the value of 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 data structures and can not be addressed in SimEnv experiment post processing This approach enables adaption of the model source code for a number of potential experiment fac tors and model outputs where only a subset of these factors is under consideration in a special ex periment and or requested for model output m 56 38 y H T f l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 model edf as a fac tor and or in the model output description file lt model gt mdf as an output variable and where the cor responding SimEnv functions in the model source code are missing can be addressed during ex periment 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 un defined in the NetCDF file s A regular matching between the
388. the sub keyword is not stated initial seed is set to random Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Tab 6 12 Experiment specific elements of an edf file for OPT_SA line type m mandatory o optional Keyword Name Max line Value Explanation nmb Sub Line keyword type factor lt factor_ sample m 1 real val47 lower bound real val4 and name real val upper bound real val to define the factor range where the cost function is to be mini mized on real val4 lt real val Values factor smp val are sampled in this factor range specific nil seed 0 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 val_int gt number of single runs to end the experiment without check ing the other optimization method related stopping crite ria 6 8 1 Special Features in OPT_SA For an optimization experiment in general and for the coupled simulated annealing algorithm in particular the following features have to be kept in mind This is an experiment type
389. the argument position 1 n where the extreme is reached the first time Processing sequence starts with arg1 4 Tab 8 7 Built in standard aggregation moment operators with suffix Aggregation and moment operator Argument restriction s result description min I char arg1 arg2 max I char arg1 arg2 sum I char arg1 arg2 avg I char arg1 arg2 var l char arg1 arg2 avgg I char arg1 arg2 avgh I char arg1 arg2 avgw_ char_arg1 arg2 arg3 count I char arg1 char arg2 arg3 dimargi 21 extag arbitrary dimes Xtres i according to char arg1 and argi dimargz diMarg3 Xtarga i eXtarga i arg3 weight char_arg2 all def undef minprop I char arg1 arg2 maxprop I char arg1 arg2 as above but dimres is increased by 1 Xtres diMres dimargz coordres diMses name index 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 values equidist end 1 1 n argument field arg2 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Aggregation and Argument restriction s moment operator result description hgr I dim es 1 dim of all other operators of thi
390. tion 1 n where the maxi aggr mom Tab 8 5 124 mum is reached the first time med e arg1 run ensemble median UNC MC Tab 8 13 145 min arg1 argument minimum of values aggr mom Tab 8 5 123 min e arg1 run ensemble minimum UNC MC min l char arg1 arg2 dimension related argument minima of values aggr mom Tab 8 7 124 of arg2 min n arg1 argn minimum per element aggr mom Tab 8 5 124 minprop arg1 index of the element where the minimum is aggr mom Tab 8 5 123 reached the first time minprop e arg1 run number where the minimum is reached UNC MC Tab 8 13 145 the first time minprop l char arg arg2 dimension related argument position 1 n aggr mom Tab 8 7 124 where the minimum is reached the first time of arg2 minprop n arg1 argn argument position 1 n where the mini aggr mom Tab 8 5 124 mum is reached the first time mod arg1 arg2 remainder basic Tab 8 4 121 morris arg1 get global sensitivity measures for arg1 glob sens Tab 8 9 138 move_avg char_arg1 moving average of running length int arg3 for advanced Tab 8 8 126 char arg2 int arg3 arg4 arg4 nint arg1 nearest integer value basic Tab 8 4 121 qnt e real arg1 arg2 run ensemble quantile of arg2 UNC MC Tab 8 13 145 rank char arg1 arg2 rank of arg2 according to char arg1 advanced Tab 8 8 126 reg e arg1 arg2 run ensemble linear regression coefficient to UNC MC Tab 8 13 145 fo
391. tion 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 11 9 5 7 1 Standard Dot Scripts for GAMS Models lt model gt ini lt model gt ini cf Section 7 1 on page 99 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 For an experiment restart with a GAMS model cf Section 7 4 on page 106 lt model gt ini has to be per formed again To force this specify in lt model gt cfg cf Section 11 1 on page 181 for the sub keyword re start ini the value yes lt model gt run lt model gt run cf Section 7 1 on page 99 has for each GAMS model the same contents bin sh SE_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 99 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 specif
392. to sample from Sam ple include and sample exclude can not be used for distributions imported from files Keep in mind that the generated sample of factor values normally does no longer follow the statisti cal properties of the specified distribution when applying sample include and or sample exclude In particular moments will differ from those as determined by the distribution and its parameters Sub keyword seed This sub keyword controls the seed of the used random number generator for implicitly specified dis tributions distr lt distribution gt A random seed will result in different generated samples for repeti tive performance of the same experiment while with a fixed seed the generated samples will be iden tical 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 m S A Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN J lt 73 Tab 6 4 Probability density functions and their parameters Distribution distr_ SET function shortcut distr_param_1 distr_param_2 Restriction uniform U lower bound upper bound lower bound lt upper bound normal N mean value variance variance gt 0 lognormal L mean value of a variance of a nor variance gt 0 normally distributed mally distributed factor factor exponential E mean value mean value gt
393. tor works matmul f c arg1 matrix multiplication of 2 matmul f c arg2 dimensional operands matl mat2 simple div arg1 division without consideration of simple div 2 4 arg2 overflow underflow and division 0 5 by 0 3 m 222 y HN T J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 15 2 Examples for Model Interfaces 15 2 1 Example Implementation of the Generic Model world According to Example 1 1 on page 7 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 Factor meaning factor nominal parameter name unit value p1 1 phi lat T 12 latitudinal phase shift p2 2 omega lat 2 m latitudinal frequency p3 3 phi lon 71 12 longitudinal phase shift p4 4 omega_lon 2 17 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 ho
394. ts 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 child 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 SimEnvVis Simulation Performing an experiment with a model m T E 264 y HN T J lt L Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 UNC NC 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 variable and its relation to the pdf s of the factors Unix A computer operating system http www unix org originally developed at AT amp T USL SimEnv runs under the AIX Unix implementation for RS6000 hardware and compatibles from IBM User defined files A set
395. tured to variable distances between adjacent coordinate values A model output variable values then exist on the rectilinear grid spanned up from the coordinate values of the coordinate axes The left side of Fig 5 2 shows a model output variable of dimensionality 2 The first dimension has an extent of 5 and is associated with coordinate axis coord Variables of dimensionality 0 do not have extents and coordinate coordinate axes coordinate system as signments 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 completely or partially disjoint coordinate sys tems coord coord coord Rectilinear grid supported by SimEnv Curvilinear grid not supported by SimEnv Fig 5 2 Grid types m S a Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 hs HN J lt 41 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 with a dimensionality gt 0 is always defined on a coordinate system formed from the as
396. u Argument value Operator ment pre defined values Remark number are case insensitive avg I 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 sdirectory2 file name d ud M N l Ma l Ma Mta M A UOD ea AON eaa Nja Dn aj ee ee en Ma Ma 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 l def undef lin_abs not pre defined case insensitive lin_rel not pre defined case insensitive mask lt
397. uation 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 format SimEnvVis does not belong to the standard SimEnv distribution It can be obtained from the SimEnvVis 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 SimEnvVis framework offers visualization modules with 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 scatter plot matrixes techniques Furthermore approaches to navigate intuitively through large multi dimensional data sets have been applied including details on demand interactive filtering and animation Using the OpenDX platform OpenGL and
398. ue Explanation nmb general nil descr o any lt string gt experiment description type m 1 GSA_EE experiment type DFD LSA UNC_MC OPT_SA factor lt factor_ descr o 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 val_float gt factor default nominal value lt factor_def_val gt sample see 1 experiment specifies how to sample the be specific factor to get sampled values low factor smp val specific nil experiment m lt ex experiment experiment specific informa specific gt peri specific gt tion ment spe cific gt m S EAD Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 y HN T l 69 To Tab 6 1 the following additional rules and explanations apply A factor name is the symbolic parameter driver initial value name corresponding to factors of the investigated model Correspondence is achieved by applying the SimEnv model interface function simenv_get_ in the model 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
399. ult 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 Operator cumul The operator cumul cumulates computes partial sums of an operand arg2 that has dimensionality gt 0 Cumulation is performed for all values of the 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 Operator distr par 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 Operator flip 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
400. ulti Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 d HN T J 35 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 5 Model 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 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 performance 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 the transfer of sampled numerical values of model factors under investigation from the simulation environment to the model and to the transfer of model output variables under investiga tion from the model to the simulation environment for later experiment post processing Interfa
401. ument Argument value Operaio number type restriction classify 1 int_arg 0 22 classify 2 real_arg arg2 arg3 0 classify 3 real_arg arg2 lt args cnf 1 real_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 O hgr 4 real arg arg3 arg4 hgr e 2 int arg 0 24 hgr e 3 real arg arg3 arg4 O hgr e 4 real arg arg3 lt arg4 hgr 3 int arg 0 24 hgr I 4 real arg arg4 arg5 0 hgr 5 real arg arg4 lt args move_avg 3 int_arg 0 23 qnt 1 real arg 0 arg1 x 100 round 1 int arg 1sarg1s5 stat full 1 real arg 0 001 0 01 0 05 0 1 stat full 2 real arg arg 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 15 5 5 Experiment Post Processor Built In Unit Invariant Operators Tab 15 12 lists those built in experiment post processor operators that have only one non constant non character argument and are invariant with respect to the unit of the operand For more information check Section 8 1 1 Tab 15 12 Experiment post processor unit invariant built in operators operators marked by have more than one non constant non character argument Operator Operator monadic lin_abs abs log acos log10 acot mask_file a
402. unction 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 SimEnv Original Model Model Experiment N Experiment peur Experiment Interface Preparation Performance os Evaluation processing 4 4 Z Model z l Update Au J Fig 0 1 SimEnv system design or 2 J Ia T iY Multi Run Simulation Environment SimEnv
403. unctions Run Sequence cupj see uc Bayesian Technique Bayesian Calibration BAY BO ssssessse eene 88 Bayesian Calibration Description File model bdf ssssseeee enm ee 89 Multiple Setting Likelihood Function Case sssseeene enm eem nnnm 91 Bayesian Calibration Log Files model blog and model bmlog eeeeee 92 cipe Em 93 ra a ulti Run Simulation Environment SimEnv ser Guide for Version 3 an 25 c ire V Multi Run Simulation Envi SimE U Guide for Version 3 1 Jan 25 2013 is iy V 10 1 10 1 1 10 1 2 10 1 3 10 2 10 3 11 11 1 11 2 11 3 11 4 11 5 11 6 11 7 vi Optimization Simulated Annealing OPT SA sssssssseeeee eene nenne enne 95 Special Features in OPT SA n een nennen nnn en nennen nene i enne Ennan annen nant 96 cie 97 EXPERIMENT PERFORMANCE 22e turu ctia e iure ced eot teeth cepa iaa c Reve Fines a a adu dran deg 99 ICs Fiume S 99 Model Wrap Shell Script model run Experiment Specific Preparation and Wrap Up Shell Scripts 100 Experiment Performance Parallelization sssssssssseseseesenenee nennen nnne nenr nennen 102 Local Experiment Performance on the Login Node ssseseeen emere 103 Experime
404. uolics loat atmo 45 90 ponto on MES TK ats bosib oiio publies ime atmo_g 20 publies Amg 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 2S for idecade 0 idecade lt 19 idecade oes for level 0 level lt 3 level Taes idim 3 levell levell 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 fe and of Dios g all dependent on jolo92 193 4 7 int simenv_sts for idecade 0 idecade lt 19 idecadet isses idim 3 idecadel idecadel1 1 simenv_sts simenv slice c bios amp idim amp idecadel amp idecadel simenv sts simenv put c bios char amp bios compute dynamics of bios g m AAG 228 y H T j i Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 main void int simenv sts simenv run int char simenv run char 6 ilo 194 159 icloyeue 192 Z p loa jos c 358 idkoeic jo 4 7 simenv_sts simenv_i
405. usted 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 X 4 m MATS S 1 6 y H E J Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 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 assessing any model Deterministic factorial design Tab 4 1 SimEnv experiment types Expanmeni Description type GSA_EE Qualitative ranking of a large number of factors with respect to their sensitivity on
406. 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 t Zo Model behaviour Z is determined for fixed k and At by state transition description ST parameters P driving forces IX and initial values Zo 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 X normally is a time dependent vec tor 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 piso 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 X 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 Byparametrising the shape of a driving force m x E Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 Hi
407. visualized by SimEnvVis and all post processor output is of type float real 4 The index_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 as var name res_ lt digit gt lt digit gt J co name for the latter see above to this NetCDF variable The index range attribute describes the sub range of the coordinate co name for which the NetCDF variable is de fined Range indices count from 1 J a j l Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 10 1 3 NetCDF Attribute Description File lt model gt ndf The optional SimEnv NetCDF attribute description ASCII file lt model gt ndf allows to delete insert and or replace global and local NetCDF variable attributes during experiment performance and result post processing from in the respective NetCDF output files SimEnv NetCDF file based experiment performance post processing analysis and the coupled visualization system SimEnvVis work with the global and local attributes as defined in Sections 10 1 1 and 10 1 2 respectively Other analysis software with input from SimEnv NetCDF output may require modified or additional information attributes The file lt model gt ndf eas ily and flexibly facilitates basic management of NetCDF attributes Advanced functionality for NetCDF man agement is provided by open source to
408. with advanced operators sssssssssssesseeeeneee 136 Multi and single run experiment post processing operators eee m 137 Experiment post processing operators for GSA EE sse enn 138 Experiment post processing operators for GSA VB ssssseeeeeee eene 140 Experiment post processing operator dfd for DFD sss 145 Experiment post processing operators for UNC MC meme 149 Experiment post processing operators for LSA ssssssssseeee ee eee nennen 151 Experiment post processing operators for BAY BO sssssseee eene enn 152 Experiment post processing operators for OPT SA eene eene eren 153 ioo ulsiozeioezricftee e aurak ani Eia aia aE E aari iE E irii 161 Operator description file lt MOdel gt Odf 0 00 ee eee eeeeeeee enna eeeeeaeeeeeeeeeeeeaeeeeeeaaeeeseeeaeeesneeeesenaeeeeeeaees 163 User defined macro definition file lt mOdel gt MaC ccccceeeeeeecneceeeeeeeeeeeaeeeeeeeeesenaeaeeeeeenseeeeeaees 164 Experiment post processing with wildcard Operands sseeeeeee eem 165 Additional coordinates in NetCDF model output eee 171 Additional coordinates in NetCDF post processor output sesessse eem 172 Processing sequence of the NetCDF attribute definition file n 176 NetCDF attribute definition file world ndf ssssssssssssssesee ener 177 IEEE complian
409. 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 Operator get data With the operator get data data from external files can be included in post processing Character argu ment char arg1 specifies the data file format 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 12 3 Cur rently ASCII and NetCDF files are supported char arg1 ascii netcdf For ASCII data files the file syntax rules from Section 12 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 12 2 Keywords general assign and coordinate and the appropriate su
410. wrap up by model end performances redirected from terminal simenv run and all successive simenv rst model nlog is organized single run by single run runcsimenv run char 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 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
411. y Ja m sh as coordinate lat descr geographic latitude coordinate lat unit deg coordinate lat values equidist end 88 4 88 coordinate lon descr geographic longitude coordinate lon unit deg coordinate lon values equitem eA ON 4 ie coordinate level descr atmospheric vertical level coordinate level unit level no coordinate level values lus ip Fp dip Le coordinate time descr time in decades coordinate time unit 10 years coordinate time values equidist nmb 1 1 20 variable atmo descr aggregated atmospheric state variable atmo unit atmo unit variable atmo type float variable atmo coords lat lon level time variable atmo nime M M MIO ON 134 7 Ls2e variable bios descr aggregated biospheric state variable bios unit biog vmit variable bios type Float variable bios coords lat g Alem time variable bios Goguel Gxvemes Bd s 56 i7S9 siUSg 1920 variable bios am dexee cseniesqisr6 5 de 9X9 p d 82 variable atmo g type sine variable atmo g coords time variable atmo g index extents 1 20 variable bios g type Lae Example files world f c cpp py ja m sh as mdf Example 5 1 Model output description file lt model gt mdf r4 aa Odi ns Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 time 10 years 36 1 20 model variable bios lat lon time 90 20 Definition of model output variable bios refers to Example 5 1 above The triples at the edges of the gri
412. y 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 PBS Torque Portable Batch System or simply PBS is the name of computer software that performs job scheduling and provides functions for building submitting and processing them Torque is a fork of OpenPBS the open source version of PBS See also gt Load Leveler 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 proba
413. y SimEnv to ensure communication with the Distributed Resource Manager These job control files may be copied to the current workspace can be modified and will then be used instead of the default job control files to start an experiment with one of the SimEnv parallelization strategies If necessary copy the ASCII job control file simenv_ dis par seq aix linux jcf pbs from the sub directory bin of the SimEnv home directory to model dis par seq aix linux jcf pbs in the current workspace modify the file according to the needs of the model one wants to perform and or the node one wants to use and start afterwards simenv run and or simenv rst If available in the current work space the modified job control file is used instead of the original file in the sub directory bin of the SimEnv home directory simenv dis par seq aix linux jcf pbs and or model dis par seq aix linux jcf pbs submit a job in distributed parallel sequential sub mode under Distributed Resource Manager control The default job control files do not enable automatic restart of the experiment by the Distributed Resource Manager after an abnormal end The user has to restart the experiment manually after such an event For performing a parallel model itself in a DRM environment see Section 5 11 7 3 3 Experiment Partial Performance SimEnv enables to perform an experiment partially by performing o
414. ype BAY BC with the multiple setting case lt model gt run has to have a special pre defined structure For GAMS models check Section 5 7 1 and for the ex periment type BAY BC with the multiple setting case check Section 6 7 2 for more information The user can define an optional model specific experiment preparation shell script model ini that is per formed additionally after standard experiment preparation and before setting up a new experiment For ex periment restart model ini is performed only on request cf Section 7 4 below After the experiment has been finished the experiment can be wrapped up with the optional model experiment specific shell script lt model gt end e n 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 Terminal output from lt model gt ini is re directed to the log file model nlog For Python Java Matlab and GAMS models lt model gt ini is a mandatory shell script with standardized contents Check Sections 5 5 1 and 5 7 1 for more information e Terminal output from lt model gt end is re directed to the log file lt model gt nlog For GAMS models lt model gt end is a mandatory shell script with standardized contents Check Section 5 7 1 for more information The shell scripts lt model gt run lt model gt ini and lt model gt end have to have execute permission Ensure this by the Unix L
415. ystem Sub keyword runs Specify here the length of the chain of visited points in the factor space The number of single simu lation 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 distribution and optional sample_include sample_exclude intervals Sub keyword type Section 6 1 1 on page 72 For BAY_BC only the factor adjustment type value set is allowed For all the other sub keywords check Section 6 1 1 on page 72 y H a j Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 6 7 1 Bayesian Calibration Description File lt model gt bdf Bayesian calibration is the only experiment type that comes with a mandatory SimEnv file which supple ments the experiment definition file model 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 Tab 6 11 Elements of a BAY BC bdf file line type m mandatory o optional Max Keyword Name Sub Line ine Value Explanation keyword type nmb general lt nil gt descr o any string overall likelihood descriptions method m 1 metropolis __ Markov chain Monte Carlo standard MCMC
416. zation 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 experiment 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 Multi Run Simulation Environment SimEnv User Guide for Version 3 1 Jan 25 2013 oy HERIDA es These source code sequences can be used e for Fortran C C Python model source codes as include files in the model source

SimEnv User Guide - Potsdam Institute for Climate Impact Research

Contents

Download Pdf Manuals

Related Search

Related Contents