Home

MpmasQL 2.52 - Universität Hohenheim

1. or same thing but more readable ofert sql 1 SELECT goods_code 1 FROM tbl_consumables WHERE goods_code IN qlist ORGANICFERT 3 Move all tables from the configuration file into the new MPMAS TABLES section and adapt them to the new format Important as these tables have a predefined structure you must not specify the number of keys The following tables have to be renamed DEMOTAB gt HOUSEHOLD_DYNAMICS SEXAGECAT gt HOUSEHOLD_MEMBER_TYPES ASSETENDOW gt ASSET_ENDOWMENTS HOUSEHOLDENDOW gt HOUSEHOLD_COMPOSITION a b c a 154 e AGENTINFO gt AGENT_INFO f ASSETCDF gt ASSET_CDF g HOUSEHOLDCDF gt HOUSEHOLD_CDF So e g if this was before in your cfg SEXAGECAT sql SELECT code kind sex lowage upage FROM tbl_MASsexagecat it should now look like this in your var HOUSEHOLD_MEMBER_TYPES sql SELECT code kind sex lowage upage FROM tbl_MASsexagecat or like this would also work HOUSEHOLD_MEMBER_TYPES sql 4 SELECT code kind sex lowage upage FROM tb1_MASsexagecat 4 Move all non table entries which you deem model parameters rather than model configuration from cfg to var MPMAS PARAMETERS This is optional and rather cosmetic in nature to mpmasql it does not matter whether entries are in cfg or var MPMAS PARAMETERS but consider this more logical if we have a configuration and a data file So in my thinking configura t
2. 1 this instance _hhnutrient_balance_ this by 0 1 Hactivityby hhnutrient_deficita HHNUTRIENTS name this by 0 deficit type MASnutdeficit this instance _hhnutrient_balance_ this by 0 1 this instance _hhnutrient_deficitc_ this by 0 Hactivityby utility_penalty_hhnutrient HHNUTRIENTS name this by 0 deficit type MASnutpenalty orow 1 table utility_penalty 2 this by 1 this instance hhnutrient_deficitc_ this by 0 1 145 Appendix C mpmasq l function language mpmasql and mpmasdist use a special function language that can be used at specific points in their input files to express variable values A piece of function code that defines a value is generally called an expression During the preparation of input files mpmasq1 may evaluate an expression many times under many different circumstances e g for different instances and scenarios and arrive at very different values depending on the values that certain variables have under these circumstances Expressions can evaluate to single values like a number or a string empty results or a list of values array C 1 Numbers and Strings The most simple expressions only consists of a number or a single string e g 1 1 0 0753 crop Hire labor Such expressions evaluate to itself except for double quoted strings where the resulting value is only the string inside the double quotes Generally strings withou
3. MASscborrow 1 1 1 this instance _stcredit_balance 1 Hactivity stcredit_defaulted name unit type Short term credit defaulted var CURRENCY MASscdefault this instance _stcredit_balance 0 135 harvest gt this instance _stcredit_balance 1 this instance _defyno 1 activity remaining_cash 4 name Remaining cash end of year unit var CURRENCY type MASrcash type_of_payment 0 this instance _ligendofyear 1 Hactivity stdeposit 4 name Short term deposits type MASdep unit var CURRENCY orow var INTEREST_SHDEP this instance __ongliq 1 Hthis instance _ligendofyear 1 Hvar INTEREST_SHDEP activity liqtrans 4 type transfer name Transfer start liquidity to pre harvest liquidity unit var CURRENCY this instance __ongliq 1 this instance _yearlliq 1 this instance _liqendow 1 Hactivity liqtransend type transfer name Transfer remaining pre harvest liquidity to end of year cash unit var CURRENCY this instance __ongliq 1 this instance _liqendofyear 1 activity penalty_for_credit_default 4 type MASpenalty name Utility penalty for defaulting on credits unit var CURRENCY integ 1 ubound 1 orow 1 var UP_CREDIT_DEFAULT this instance _stcredit_defyno 1 var MAX_DEFAULT class SOILS 4 constraint soil name Soil of
4. STEP 120 DESCRIPTION Distribute fruit plantations TYPE distribute_observation_list AGENTS SEED var SEEDFRUITS OBSERVATIONS table fruit_plantations 0 f fruit table fruit_plantations 2 this observation id 1 size table fruit_plantations 3 this observation id 1 DEL_count table fruit_plantations 4 this observation id ASSIGN 4 this observation fruit _plantation this observation size OUTPUT ASSSIGNMENTS var outfolder agent_assets tab Note each statement needs to go on one line line breaks in the example only for readability in this manual If the setup above was contained in the control file example dst repeated calls to mpmasdist could look as follows mpmasdist example dst set SEEDFRUITS 123 mpmasdist example dst set SEEDFRUITS 3456 mpmasdist example dst set SEEDFRUITS 789 91 Bibliography Schreinemachers P 2006 The Ir relevance of the Crop Yield Gap Concept to Food Security in De veloping Countries With an Application of Multi Agent Modeling to Farming Systems of Uganda G ttingen 92 Appendix A Command line options A 1 mpmasq mpmasql lt options gt lt control file gt lt options gt Table A 1 Command line options for mpmasql Option Description C compact use compact matrix format only for use with mqlmatrix h help print this help n nomas do not chec
5. Table B 20 Structure of the PRODUCER_ORGANIZATIONS table Column Type Description PO integer Description text File path Table B 21 Running PO number key Name of PO Path to cll file containing PO decision problem relative to working directory Structure of the PRO DUCER_ORGANIZATION_SERVICES table Column Type Description PO integer Running PO number key POservice identifier Identifier of PO service key member_activity identifie PO_qconstraint identifie PO_gactivity identifie PO_profit identifie r identifier of quantity activity in farm agent MIP r identifier of quantity constraint in PO MIP r identifier of quantity activity in PO MIP r identifier of profit activity in PO MIP Table B 22 Structure of the REGION table Column Type Description gisid integer ID of the village sector in the GIS map overall ID for the region code string Name for the Region catchid integer Id of the Catchment District subsector 0 1 Is this a subsector beingused 0 1 Is this sector to be used rank integer Rank of the sector Additional columns if the EDIC hydrology model is used reuse number Initially Expected Reuse Factor canalefficieny share Canal Efficiency 121 watersystemefficiency number Water System Efficiency due to Overnight Storage bcoeff share b calibration coefficient of the EDIC model gcoeff share g calibration coefficient of the EDIC model num_random_wr integer Numbe
6. less A 2 mgqlmatrix mqlmatrix lt name _of _matrix _file gt lt file format option gt lt other options gt Table A 2 Command line options for mqlmatrix File format specifying one of these formats is obligatory F expect matrix in failed format mip mpx S expect matrix in single agent format mtx D expect matrix in debug format mip mpx V lt subformat gt expect matrix in mpmas input file for mat dat lt subformat gt 0 basic format 1 with second production stage harvest milp with advanced consumption model 11 TSPC with second production stage not implemented 12 TSPC with advanced consumption model not implemented compact c expect tableau in compact format only in combination with V and S Override default settings A lt filename gt specify file containing activity descrip tion C lt filename gt specify file containing constraint de scription O lt directory gt override output directory lt directory gt specify directory containing description files if not specified the directories are read from mqlmatrix conf in the working directory and names of description files are guessed from the matrix file name 94 M lt filename gt filename of MilpCheck executable de fault usr local bin MilpCheck XP lt command gt set program for paging defaults most less XS lt command gt set spreadsheet program for table views defaults gnumeric oocalc
7. male_hhmember_aged_19 male_hhmember_ and these would be set to values according to the user defined table hhmembersbyclass For the code to make sense we assume this table to contain three key columns the first containing the agent class the second the age and the third the gender while in the fourth column a quantity information might be recorded AGENTS male female _hhmembers_aged_ steps 18 30 1 table hhmembersbyclass 4 this agent class this attribute 2 this attribute 1 To set values of attributes as the result of a predefined distribution algorithm you can use the ON_ASSIGN section which will only assign values to those agents which have been selected by the distribution algorithm and provides specific local variables to refer to the results of the process The syntax for the ON_ASSIGN section is a bit different as for the AGENTS section Since as you will see later on also attributes of observations can be changed here we need to explicitly mention that we refer to agent attributes by putting an agent in front of the attribute name Specific local variables will be discussed during the presentation of individual distribution algorithms ON_ASSIGN agent asset_counter this agent asset_counter 1 6 3 2 Removing attributes The CLEAN section allows to remove agent attributes at the end of the distribution step For example the following code would delete the attribu
8. where gt is the variance covariance matrix of the gross margins of the individual production activities To implement this in MPMAS the Q matrix needs to be set to 1 x r x 2 as can easily be seen by comparing equations 4 8 and 4 5 50 4 9 Exogenous changes to matrix coefficients and agent independent right hand sides Sometimes you may want a matrix coefficient or and agent independent capacity to be changed at a certain point of the simulation e g to reflect a shift in policy This can be achieved by adding fields with the exchange gt marker to the activity or constraint in question The general syntax for coefficients is Hactivity exchange gt lt id_of_constraint gt _ lt year_of_change gt lt new_value gt whereas right hand side values are exogenously changed as follows constraint type MASzero exchange gt value_ lt year_of_change gt lt new_value gt Note that the timing of the change is given as explicit year mpmasq1 will automatically adapt the matrix file depending on the value of your STARTYEAR configuration entry This also holds for standalone matrix generation For example in the following case Hactivity soil_transfer 4 exchange gt EU_livestock _limit_1994 10 exchange gt EU_livestock _limit_1999 2 exchange gt EU_livestock _limit_2001 1 9 exchange gt EU_livestock _limit_2002 1 8 If your START YEAR is 1998 the value of the coeffici
9. Others p print matrix in single agent format mtx and exit R import solution vector h help print this help V print version information risk_aversion lt value gt set risk aversion coefficient for evalu ation of imported quadratic solution to lt value gt A 3 mpmasdist mpmasdist lt opti Option ons gt lt control file gt lt options gt Table A 3 Command line options for mpmasdist Description V print version information set lt variable gt lt value gt set lt variable gt defined in the control file A 4 mpmas Hint Contrary to the to lt value gt for this run other programs and most other standard Linux applications there is no space between the mpmas options and their argument E g its has to be Ntest _ and not N test _ mpmas N lt name _of _scenario _file gt lt other options gt Required N Optional A C D E H M O P Table A 4 Command line options for mpmas is followed without blank by the simulation name spatial maps see BasicData Second sheet set filename of canal efficiencies EDIC save maps for debugging when coupled with external crop model set filename of lambda expectation parameters set water surplus factor EDIC is the path to the input folder which must contain two subfolders dat and gis export agent LP matrices in compressed format mpx is the path to the output folder which must contain su
10. SCONMIN Nahm 4 1 where nanm is the number of household members and maes is the net cash surplus of the year Cash consumption thus consists of a minimum consumption needed to maintain the family and an extra consumption that depends on the performance of the household enterprise If cash reserves of the household are not enough to cover even the minimum consumption the full cash reserves are consumed You can however specify a minimum threshold as a share of the minimum consumption SCONRED that is the absolutely essential part of the consumption and if this cannot be satisfied the household will exit The parameters of the basic consumption model are specified in the MPMAS PARAMETERS sec tion of the data file For example MPMAS PARAMETERS SCONEXTRA 0 25 SCONMIN 10000 SCONRED 0 2 4 4 2 Advanced three stage consumption model The extended three stage consumption model has been developed to model subsistence farming It is a parametric model whose parameters can be estimated econometrically and which partitions the household income into savings expenditure for non food goods and expenditure for different food categories Food demand is expressed in demand for nutrients and depends on the household size Food demand can be covered by consuming self produced goods or by buying food from the market The model is quite complex and is not going to be explained in full detail here the full rationale and equations of the mode
11. name Income Function type MASxc_inc_func unit var CURRENCY this instance _xc_inc_transc 1 this instance _xc_sav_transc 1 this instance xc_sav_balance 1 savings block constraint xc_sav_transc name Savings Transfer type MASxc_sav_trans unit var CURRENCY eqtype 3 constraint xc_sav_funcc name Savings Function type MASxc_sav_func unit var CURRENCY eqtype 3 F constraint xc_sav_balance name Savings Balance INC EXP SAV type MASxc_sav_balance unit var CURRENCY eqtype 3 constraintby xc_sav_lbound steps 1 count XC_SAV_INCSEGS 1 name Savings Segment lowerbound this by 0 type MASxc_sav_lbound unit var CURRENCY constraintby xc_sav_ubound steps 1 count XC_SAV_INCSEGS 1 E name Upperbound Savings Segment Hthis by 0 type MASxc_sav_ubound unit var CURRENCY F activity xc_sav_funca name Savings Function type MASxc_sav_func unit var CURRENCY this instance _xc_sav_funcc 1 this instance _xc_sav_balance 1 138 Hactivity xc_sav_seg_0 1 name Savings Segment 0 type MASxc_sav_seg0 unit var CURRENCY this instance _xc_sav_transc 1 this instance _xc_sav_funcc 0 this instance _xc_sav_lbound_ steps 1 count XC_SAV_INCSEGS 1 1 gt ubound set by MP MAS activityby xc_sav_seg steps 1 count XC_SAV_INCSE
12. sql 1 SELECT crop labor_req_harvest FROM tbl_crops_labor length_of_harvest_period sql 1 SELECT crop length_of_harvest_period FROM tbl_harvest_periods crop labor_req_harvest wheat 5 barley 6 maize 8 crop length_of_harvest_period wheat 8 barley 7 maize 20 3 6 4 Machinery use While labor soil and liquidity are special assets whose handling is controlled by MPMAS using the special type marks you have to define the relation between all other assets and the equation in the decision problem in a more specific way For simplicity let us assume our tractors have a certain capacity per year e g with one plough you can work 50 ha a year Of course we could also be more specific and distinguish different peak labor periods or different machinery sizes et cetera The corresponding constraint equation for each machinery type would then be No Ag lt CaPm Nm 3 13 cj where w is the number of times you need to work the field with a certain type of machinery for crop 24 C Nm is the number of equipments of type m the household owns and cap is the yearly working capacity of that machinery type As you need one constraint for each machinery type we include it into the MACHINERY class and we add the corresponding coefficients to the crop production activities class MACHINERY asset machinery_asset con this instance capacity multiplier table machinery 4 this insta
13. table prices 3 this instance var STARTYEAR i orow_ foreach YEARS table prices 3 tthis field 1 Hthis instance tthis instance _balance 1 Hactivityby production_on_soil foreach SOILS 4 name produce this instance on soil this by 1 unit ha 16 type crop_production orow 1 table variable_costs 2 this instance this instance balance 1 table yields 3 this instance this by 1 this by 1 _soil 1 class SOILS 4 constraint soil name Area of soil this instance type MASsoil This looks quite complicated at the first glance but we will go through the fields and expressions one by one name unit Like with assets the name field in all model elements contains a description of the activity respectively constraint that will appear in the commented model files and the model info The unit field indicates the unit of the variables respectively the terms in the equation It serves also only informative purposes and is not used by MPMAS itself eqtype The eqtype field of a constraint indicates the equation sign used between left and right hand side A one stands for less or equal lt a two for greater or equal gt and a three for equal Less or equal is the default so we could also omit this in our case as we have done for the soil constraints type The type field indicates special elemen
14. 2 33 5 Aug 2013 3 3 194 DEF236 2 32 30 Jul 2013 3 3 193 DEF235 2 28 6 May 2013 3 3 186 DEF233 2 27 26 March 2013 3 3 180 DEF229 2 26 24 March 2013 3 3 180 DEF229 2 23 30 January 2013 3 3 167 DEF224 2 22 16 January 2013 3 3 160 DEF222 2 19 15 November 2012 3 3 143 DEF217 2 14 4 September 2012 3 3 137 DEF209 2 12 16 July 2012 3 3 136 DEF209 2 10 04 July 2012 3 3 135 DEF207 2 08 10 May 2012 3 3 134 DEF206 2 06 26 April 2012 3 3 130 DEF206 2 05 20 April 2012 3 3 130 DEF205 2 04 03 April 2012 3 3 130 DEF204 2 02 26 March 2012 3 3 128 DEF202 2 00 03 March 2012 3 3 DEF200 1 05 beta 22 Feb 2012 3 3 DEF200 1 04 beta 12 Jan 2012 3 3 DEF192 1 03 beta 9 Dec 2011 3 1 DEF182 1 02 beta 16 Nov 2011 3 1 DEF176 0 97 beta 9 June 2011 3 1 DEF169 0 94 beta 23 May 2011 3 1 DEF164 0 93 beta 20 May 2011 3 1 DEF164 0 90 beta 10 May 2011 3 1 DEF161 0 88 alpha 15 Feb 2011 3 0 DEF155 0 87 alpha 21 Dec 2010 3 0 0 86 beta 03 Dec 2010 3 0 0 85 beta 30 Jun 2010 3 0 DEF152 2010 06 18 Linux 0 84 alpha 15 Feb 2010 3 0 DEF141 2010 02 15 Linux 0 82 alpha 24 Sep 2009 3 0 DEF128 2009 05 24 Linux 152 D 2 1 Conversion control file ini 1 Rename the following entries a CONFIG gt CONFIGURATION b CLASSES gt STRUCTURE c VARIABLES gt DATA 2 Adapt the SCENLIST SCENDEF RHSLIST RHSDEF entires to the new table format a For SCENDEF you now have two options apart from leaving it empty i SCENDEF sql 4 SQL SELECT statement which can also
15. MFL expression gt Examples WEATHER dry MONTHS steps 1 12 1 PRODUCTS Httable products 0 B 3 6 INSTANCES The INSTANCES section contains lists corresponding to classes in the model structure file Each class of the model structure file is a blueprint describing all the model elements like activities assets constraints that are to be created for every item in the corresponding lists The list members have to correspond to the rules for identifiers i e they can contain only letters of the English alphabet digits and underscores You can use MFL functions to specify these lists referring to all global and user variables configuration and MPMAS parameters and user defined tables The syntax is simply lt classname gt lt list MFL expression gt Examples PRODUCTS wheat barley maize MACHINERY sql SELECT machinery_id FROM tbl_machinery WHERE available_in_study_area TRUE PERENNIALS table perennials 0 124 B 4 Model structure file The model structure file is subdivided into four sections These section headings are syntactically meaningful i e you cannot omit them however you can rearrange their order if you like ACTIVITY TYPES Here you can define additional types of LP activities apart from the pre defined ones Activity types are mainly used to sort the activities in the LP matrix and to refer to groups of activities in mqlmatrix CONSTRAINT TYPES Here you can de
16. The lower the value the higher the priority Negative values indicate person cannot become house hold head values above 5000 indi cate person can only become house hold head when old one dies monetary minimum consumption of household member Additional columns for the advanced consumption model energy number nutrient2 number Yearly energy need within this age seg ment only Further nutrient needs within this age segment optional and only for ad vanced consumption models Table B 15 Structure of the HOUSEHOLD_SWITCHING table Column Type Description pop integer orig_career identifier Population key The Career Identifier key 119 reason new_career probability integer identifier fraction Reason for switching O Career of de scendants 1 Career to switch to af ter marriage 2 Career of partner 3 Career to switch to when becoming household head 4 Career to switch to when partner becomes household head 5 Career to switch to when re tiring The Career Identifier key the probability to switch to spawn the new career in case the reason applies Table B 16 Structure of the INFPROJ and INFPROJPARTICI PANTS tables Column Type Description INFPROJ project_id identifier Project Identifier year integer Year of Project Implementation object idientifier Network object that is supplied by Project size number Size of network object provided e g ha total_c
17. a TL 3 10 Cj where wdh stands for the number of days needed to harvest a hectare of crop c n is the yearly capacity of labor of the household which is calculated by MPMAS using the information in the POP ULATION_DYNAMICS table and the household member information and hd is the length of the harvest period of crop cin days The equation also takes into account that household members may have off farm employment OL and may hire temporary labor TL to increase the amount of work that can be done during harvest times 22 Because of the multiplication on the right hand side this equation is a bit more difficult to rearrange and we need the help of a transfer activity O and adding an additional equation to the system O OL lt nm 3 11 Y wdhe A The Oi ae lt 0 3 12 cj We did not distinguish different labor types but to be general we would have to repeat these equa tions for each different labor type We thus put them into the class LABOR to which we assign our labor type farm as an instance INSTANCES LABOR farm The blueprint for the labor CLASS would look like this class LABOR 4 Hconstraint hhlabor 4 name Household labor of type Htthis instance unit person year type MASlab labgrp this instance constraintby labor_capacity foreach CROPS 4 name Labor capacity of type this instance in harvest season of this by 1 unit person
18. a A AAA A 154 D 2 4 Model structure file cl 4 022060888 ya a0 POSS AA aa 155 D 3 Changes 2 03 2s 8 bee ode eae ed 26 Ge ee A A ed 157 D 4 Changesin2 04 2 2 0 ee 157 D 5 Changesin2 08 ee 157 D 6 Changesin2 10 i adaos ee 157 Di7 Chandesin 212 42 earvedan ae nee ed heed a ea and 158 D8 Changes in 2 14 2p atecetd an 28 A AI a 158 Di9 lt Ghanges 216 2 2 ea ee kg i A ee ete Boe Le sarria 158 D 10 Ghanges 21D oie te a ao a Ge le Be E ee Sods ae ea 158 Del VGhangessin 2 20 200 ici te a aos ee E ww ah de As a ea ee 158 Dil2 Changes 2 2 1 lowe ee ea ea EEE eee ee eee dd as 158 Dit3 Changesiin 2 22 cies cle ig sds at ee ar ac a A lal al ae 159 Dl4 Changesiini 2 23 secs oy cutee a A BE Bara AME A OE ee pit plane 159 D 15 Changes in 2 24 1 159 D 16 Changes 2 26 riranin a Ea ten FAS a uke ee oe 159 D17 Ghanges i227 gtr prania a a ere Ok ele de a ar we Ree eee 159 D 18 Changes in 2 28 ee 159 D49 Changes IN 2 S2 ama a pa pa ao a a a teeta dd aaa a A a ae 159 D 20 Changes IN 238 aa eared ame Quy aid dat e 159 Di21 GHANQES IN 2 36 cerrar E aoe ee dt ea aR GRA se 160 D 220hanges 2 39 cae Oe yk ae a aches ee OE SE ESS MOOS SaaS 160 D 23Changesin2 40 ee 160 D 24 Changes IMAAT nce eee eR ee ee aa ae ee Soe eG oS 160 D 25 Changes in 247 0000 eee ee AA SS SG 160 D 26 Changes in 2 48 402 AA ee AAS ERY A ee AA G 160 D 27 Changes in 2 52 2 1 ee 161 vii Chapter 1 Installati
19. etc mpmasq l default cll You only need to specify those settings which you want to change and you must not put a class DEFAULTS around it anymore E g if you would like to make all activities integer activities by default and set the default priority to 100 you re DEFAULTS section would look like this DEFAULTS Hactivity activity 4 integ 1 priority 100 If you do not want to specify any customary default settings you can omit the whole section The MODEL section contains the rest of the cll file as it was before however there have been some major changes to the syntax and you will need to adapt your code Networkobjects are now called assets so change all networkobject to asset For performance reasons thisinst thisby and thisfor have been replaced by a generic this function So please change a thisinst gt this instance b thisby gt this by 0 c thisfor 1 gt this field 1 You can now also refer to parts of the by specification that resulted from tables or foreach if you choose a number higher than 0 zero gives you the whole construct You can now also refer to the full field name by using this field 0 The this function is a function and not a local variable anymore so it cannot be included into strings So something like Growing thisinst on soil thisby will have to become Growing this instance on soil this by 0 g y
20. span over several lines ii but still experimental SCENDEF ascii name of an ascii file with tab separated values b For RHSDEF you have the same options as for SCENDEF plus a third one i RHSDEF transform_assets If you use this option the RHS is directly created from the ASSET_ENDOWMENT HOUSE HOLD_COMPOSITION and AGENT_INFO tables in the var file see below and the soil RHS is either directly read from MP MAS input maps if you specify the map directory in the control file RHS_MAPDIR directory Or alternatively read from a table specified in the control file RHS_SOILTAB sql SQL SELECT statement which can also span over several lines c For SCENLIST and RHSLIST you have three options apart from leaving them empty i SCENLIST sql SQL SELECT statement which can also span over several lines ii but still experimental SCENLIST ascii name of an ascii file with one entry on each new line SCENLIST list list of comma separated values D 2 2 Configuration file cfg ili Rename the following entries if you are using them a MAXSOLVETIME gt OSL_MAXSOLVETIME b MAXITERATE gt OSL_MAXITERATE c MAXNODES gt OSL_MAXNODES d there is an additional entry OSL_SKIPMODE1 which skips mode 1 153 2 A whole number of entries will be moved out of the configuration file and into the new MPMAS PARAMETERS and MPMAS TABLES section in the data file
21. var Everything which is a table has to go to MPMAS TABLES Everything which is can be considered model configuration like start year submodel switches osl control number of soils populations type of consumption type of diffusion will remain in cfg Everything which is rather a model parameter like interest rates liquidity leverage overlap should go to MPMAS PARAMETERS although the later would still work if they remain in the configuration file Tables won t work in cfg anymore More detail is provided in the section on var below 3 In case you used an external crop growth model the XNTABLE and XNYIELDCHANGE have been replaced by the attribute group externalcropgrowth gt to be implemented in cll D 2 3 Data file var 1 The data file now has six sections GLOBALS MPMAS PARAMETERS MPMAS TABLES USER TABLES e USER VARIABLES f INSTANCES Please rename TABLES gt USER TABLES and VARIABLES gt USER VARIABLES and intro duce the MPMAS PARAMETERS and MPMAS TABLES sections The ORDER section is moved to the structure file cll and reformated see below a b c d wo we ZA FTI DS 2 Reformat your user tables The new format is tablename tabletype number of keys MpmasQL Function Language that results in an SQL statement and can span several lines e g ofert sql 1 SELECT goods_code 1 FROM tbl_consumables WHERE goods_code IN qlist ORGANICFERT
22. we need only key column which contains the instance identifier i e the type of machinery Definitions of user tables are placed into the USER TABLES section of the model data file and are of the following format tablename tabletype number of key columns tablesource MFL expression that can 13 span several lines and results in an SQL query for sql tables and a filename for ascii tables F For example machinery sql 1 SELECT machinery lifetime acqcost FROM tbl_machinery The corresponding table might look like this machinery lifetime acqcost tractor 10 10000 plough 6 1000 seeder 12 3000 harrow 8 760 cultivator 8 900 When mpmasq1 now creates the asset for the tractor instance it will encounter the MFL expression table machinery 2 this instance for the field lifetime The first thing it will do is re place this instance by tractor leaving it with table machinery 2 tractor It then looks into the table machinery looks for the row which has a value equal to tractor in the first column and takes the value it finds in the second column of that row and then knows that the lifetime of a tractor is 10 years Note that the table contains information for more types of machinery than we used in our model We simply deliberately chose only to consider tractors ploughs and seeders the additional information is read by mpmasql1 but remains unused If we want to change that and
23. 1 activity xc_foo_funca name Food Expenditure Function type MASxc_foo_func unit var CURRENCY 142 this instance _xc_expenditure_balance 1 this instance __xc_fnf_funcc 1 this instance _xc_foo_constc 1 this instance __xc_foo_hhsizec 1 this instance _xc_foo_pricec 1 this instance __xc_foo_fexc 1 activity xc_foo_consta name LA AIDS Constant type MASxc_foo_const unit var CURRENCY tthis instance _xc_foo_constc 1 this instance __xc_foo_foodcat_ table foodcats 0 table foodcats 4 this field 1 activity xc_foo_hhsizea name LA AIDS HHSize type MASxc_foo_hhsize unit var CURRENCY this instance _xc_foo_hhsizec 1 tthis instance _xc_foo_foodcat_Httable foodcats 0 table foodcats 6 this field 1 activity xc_foo_pricea name LA AIDS Price type MASxc_foo_price unit var CURRENCY this instance _xc_foo_pricec 1 this instance _xc_foo_foodcat_ table foodcats 0 table foodcats 5 this field 1 Hactivity xc_foo_seg_1 name LA AIDS FEX Seg 1 type MASxc_foo_segl unit var CURRENCY this instance _xc_foo_fexc 1 this instance _xc_foo_lbound_1i 1 ubound listelement XC_FOO_FEXSEGS 1 activityby xc_foo_seg steps 2 count XC_FOO_FEXSEGS 1 1 name LA AIDS FEX Seg this by 0 type MASxc_foo_seg2 unit var CURRENCY this inst
24. 3 Long term market Use permanent crops Simple infrastructure subsidy policy model Activate certain study specific modifica tions Re run production decision with up dated yields and fixed land area after crop growth model results DEMOGRAPHY_MODELType of demography model 0 ba DIFFUSION NETWORKS COMTYPE CUMADOPT THRESHOLDS HYDROLOGY NINFLOWS VINFLOWS CROP GROWTH XNSEASONS DYNAMICS OFFLIQEQ OFFHHAGING OFFLIVEAGE OFFASSAGE sic demography model 1 advanced demography model currently only for COUNTRY 5 Number of Innovation Networks inte ger Type of communication Type of diffusion model list of fractions that denote the lower bound of innovation segments Number of inflows Values supplied per inflow set to 2 if EDIC is used External crop growth models Number of cropping seasons per year Switch off updating of liquidity and eq uity 0 1 Switch off aging of households 0 1 Switch off aging of livestock 0 1 Switch off aging of assets 0 1 104 optional optional optional optional optional optional optional optional optional optional optional required optional optional optional optional optional optional optional optional optional optional o OFFINV OFFINVDELAY OFFDYNSOIL OFFDYNFLOW SOLVER MINOBJ OSL_MAXSOLVETIME OSL_MAXITERATE OSL_MAXNODES OSL_SEQUENCE OSL_M4_ATTEMPTS OSL_M4_ITHRESH OSL_M4_NTHRESH O
25. 7 Acquisition cost of assets in agents in ventory at simulation start are divided by 1 1 9 to account for the fact that purchases prices were lower in the past minimum_age_of_asset_at_simulation_start Country switch Germany 5 Minimum 1 age an agent s asset of this type can have at the beginning of the simulation maximum_age_of_asset_at_simulation_start Country switch Germany 5 Maxi 1000 mum age an agent s asset of this type can have at the beginning of the simu lation Perennial attributes and subelements Livestock attributes and subelements SOS attributes and subelements Table B 33 Attribute fields for special ordered sets Field Description Values Defaults name Name ofthe SOS for commented input any string N A files 130 type Type of sos 1 at maximum one of the integer 3 activities in the set can be non zero 2 at maximum two of the activities in the set can be nonzero and these have to be neighbors 3 exactly one of the ac tivities in the set has to be one all oth ers zero priority branch and bound priority of the set 0 1000 1000 Time preference penalty attributes and subelements 131 Table B 34 Example Results for this instance and this by lt i gt in the respective element activitiy id instance by 0 by 1 by 2 wheat_grow_0_high wheat 0_high 0 high wheat_grow_0_ medium wheat O_medium 0 medium wheat_grow_0_low wheat 0_low 0 low wheat_grow_1_high wheat 1_high 1 high wheat_gro
26. Exchange maps with external crop model based on files and not TDT Suppress coupling T14 Write endogenous prices to files T15 Basicdata reading translation table T16 Allocate crops to maps but read crop yields from external file Look up table T17 Save agent crop mixes and solution vectors before and after spa tial correction for maps T18 Ignore sub pixel crops in land use maps but keep them in produc tion solution T19 Debug information for exchanging land use and crop yield look up tables T20 Raster2D exporting irrigation table T25 Landscape construction of sectors landscape cells T28 Outputs for spatial allocation to cells T29 De activate sectors during initialization with special input file for use in Mpmas stand alone T30 For coupling reads some data with ending _coupl dat instead of dat T31 Evaluate Edic Routing etc T32 Export sector wise land use data using InputData class T33 Crop water module simple checks for plant water demands irri gation water and water deficits T34 Read input data reading out all Dat and Gis files T35 Prints a dot on screen after each 20th agent T36 Suppress all outputs T37 Medium level of verbosity for OSL messages T1 is highest level of verbosity T38 Used in deactivated Wasim coupling code 96 T39 T41 T42 T43 T50 T51 T52 T53 T55 T56 T57 T60 T65 T66 T67 T68 T69 T70 T71 T72 T73 T74 T7
27. However the class INTERMEDIATES additionally needs a buying activity and a transformation activity which e g trans forms hay into energy and raw fodder input for animal production To save you time and ensure that any changes you make to the elements in the PRODUCTS class also immediately apply to the INTERMEDIATES class you can just let INTERMEDIATES use the selling activity and the yield balance constraint from the PRODUCTS class by adding an has elements like statement Or as syntactic sugar if you think if your class name is in plural your statement should also be in plural you might opt for have elements like too Or if you prefer standard object oriented language you can write inherits from Assuming you already defined a PRODUCTS class with a contraint balance and an activity sell you write the following to include the same elements into the INTERMEDIATES class and additionally define a buy and a transform activity class INTERMEDIATES has balance sell elements like PRODUCTS Hactivity buy 4 activity transform 4 An asterisk instead of a list of elements uses all elements of the parent class Thus aS balance and se11 are all the elements in the class PRODUCTS you could have also written have elements like PRODUCTS Further you can override attributes of a reused class If because of whatever reason you have stored your intermediate product prices in a dif
28. _sell external_crop_growth gt producti_balance this instance balance external_crop_growth gt product2_balance 1 external_crop_growth gt initial_yield_producti table yields 3 this instance this by 1 external_crop_growth gt initial_yield_product2 0 link is the ID to be put into the map for the activity The crop growth model or a wrapper is supposed to understand the ID and transform it into input for the plant model producti_sales_activity The identifier of the sales activity of the product only necessary if you do not use an explicit harvest consumption decision see Sec 4 3 4 product1_balance The identifier of the balance constraint of the first product product2_balance The identifier of the balance constraint of the second product only possible if you use an explicit harvest consumption decision initial_yield_product1 The expected yield of the first product for the first simulation period initial_yield_product2 The expected yield of the second product for the first simulation period priority is an integer indicating how close the area should be placed to the farmstead of the agent the smaller the number the closer crop_type indicates whether the activity is seasonal 0 annual 1 or perennial cop 2 or whether it is a fallow activity 3 or deactivated 1 40 At least one activity per soil type should be marked as fallow activity and this activity should not require any limited resou
29. additionally the compact flag in case you created it with this flag in mpmasql 5 2 3 MP problems automatically saved by mpmas for debugging Whenever a decision problem of an agent cannot be solved by the OSL because it is infeasible unbounded or solving it surpasses the time or iteration limit MP MAS saves the associated matrix in the out test folder These matrices have the extension mip or if you run mpmas with the flag in the much more compact mpx format To load such matrices into mqlmatrix you have to use the type flag F mqlmatrix uses the extension to distinguish between mip and mpx format 5 2 4 MP problems saved by mpmas for debugging on request You can also request that the decision problems of a specific agent be always saved by mpmas e g to check the coefficients dynamically generated at runtime You only have to include the farmstead identifier into the DBGMILPS list of the mpmasq control file E g DBGMILPS 1235 124 345 will save the decision matrices of agents with farmstead id 1235 124 and 345 The files will be written into the out test directory and be either in mip or mpx format depending whether you used the m flag or not To load such matrices into mqlmatrix you have to use the type flag D mqlmatrix uses the extension to automatically distinguish between mip and mpx format 67 5 3 Indicating the location of the model info files mqlmatrix needs the ActivityInfo and ConstraintInfo fil
30. agents dat at the end of step 20 STEP 20 OUTPUT AGENTS agents tab STORE_AGENTS agents dat Note For the use in Linux pipes mpmasdist also accepts the keyword STDOUT as a file name in the OUTPUT section The population attribute list saved by the AGENTS keyword does not contain the specifically des ignated list of agent assets and agent household members see further below which can be saved in human readable format using the keyword ASSIGNMENTS and MEMBERS This allows an easier separation of agent characteristics which are only needed during the distribution process and those which should enter as asset or household member information into the model The member and assigments lists have a file format that facilitates upload to a database 6 2 4 Restoring agent populations Agent populations that have been saved with the STORE_AGENTS keyword can be restored the RESTORE keyword with the filename between the AGENTS keyword and the curly brackets e g AGENTS RESTORE agents dat 6 3 Defining and manipulating attributes and assets Agents can have attributes that describe characteristics of the agent relevant in the distribution pro cess Agents can be assigned assets and household members which are kept in separate lists that 74 are themselves attributes of the agents The list of assignments and household members cannot be used to formulate conditions or calculate agent characteristics during the distribut
31. define as many constraints as you like by indicating the corresponding LP row a minimum age and a right hand side value to insert if the household falls into the category This right hand side value is then inserted into the constraint representing the current remaining expected lifetime of the household The re spective constraint is the one whose minimum life time is surpassed while the minimum lifetime of the next following constraint is not surpassed List producer organizations and links them to the files containing their decision problem describes the links between farm agent activities and de cision problem of producer organizations a table describing the sectors of the model Table that lists a seed for each sector to initialize the random distribution of assets and household members ta ble Table containing segment specific restrictions on peren nial investments to avoid over investment and bankruptcy due to gestation periods Table providing segment specific financial variables Table to override any of the global SUCCES SION_CONTROL_ MPMAS parameters with population specific settings optional optional optional required required optional optional optional 115 Description of table structures Table B 5 Structure of the AGENT_ INFO table Column Type Description farmstead_id integer GIS ld of the farm key pop integer Population ID clu integer Clu
32. field name MFL expression gt lt value MFL expression gt class lt class2name gt Model element types There are seven types of model elements that can be included into a class see Table B 29 Each of these have a number of predefined fields attributes and subelement fields whose values must respectively can be set in the model structure file For LP activities every other field is interpreted as the coefficient of this activity in the constraint with the identifier that corresponds to the attribute name In all other elements unknown fields are ignored Table B 29 provides an overview of available types of model elements and the next subsections will describe the defined attributes for each type of model element Table B 29 Types of model elements Type Description activity An activity in the decision model constraint An constraint in the decision model asset A farm asset resource that provide ca pacities to the agent can be invested into may be associated to a debt pay ment ages and wears 127 perennial livestock sos A complex element that contains activ ities constraints and an asset linked to a perennial crop type A complex element that contains activ ities constraints and assets linked to a livestock type A special ordered set a set that groups some binary integer activities of which only one can be chosen timepreferencepenalty Activity attributes Table B 30 Attri
33. folder which has some conventions you can set your own de faults for all of these locations by placing a file named mqlmatrix conf into the working directory the directory from which you call mqlmatrix If such a file exists mqlmatrix will read the defaults from these files though they can still be overridden using the flags The mqlmatrix conf is a simple text file and can have the following entries all of them are optional outdir lt output directory gt milpcheck lt milpcheck executable gt infofiles lt location of the ActivityInfo and ConstraintInfo file gt 68 Chapter 6 Preparing agent populations with mpmasdist The tool mpmasdist allows its user to create endow and spatially distribute model agents It employs similar concepts and language elements as mpmasql Data may be provided in the form of SQL queries tables in text files and maps in ESRI ASCII format Using mpmasdist agent populations are sequentially built up over a number of steps For example in a first step a list of agents is created and in a second step the number of plots each agent owns could be determined In a third step agents farmsteads could be spatially distributed and in a fourth step their plots Subsequently buildings and machinery could be determined Content and sequence of steps can be freely determined by the model user and are defined in the control file in text format by convention with the extension dst Each agent is
34. foodcats 0 f name Buy_ table foodcats 2 this by 0 type MASfoodbuy orow 1 table foodcatprice 3 this by 0 var PRICEYEAR orow_ foreach YEARS 1 table foodcatprice 3 this by 0 var PRICEYEAR this instance _hhnutrient_supplyc_ foreach HHNUTRIENTS table food_category_nutrients 3 this by 1 this field 1 consumption gt category this by 0 this instance _xc_foo_cattransc_ this by 0 1 table food_category_prices 3 this by 1 var PRICEYEAR Balancing Food Requirements constraintby hhnutrient_demandc HHNUTRIENTS name this by 0 demand type MASnutdemand eqtype 3 consumption gt nutrient this by 0 constraintby hhnutrient_supplyc HHNUTRIENTS 4 name this by 0 supply type MASnutsupply 144 eqtype 3 constraintby hhnutrient_deficitc HHNUTRIENTS name this by 0 deficit type MASnutdeficit eqtype 3 constraintby hhnutrient_balance HHNUTRIENTS name this by 0 supply type MASnutbalance eqtype 1 Hactivityby hhnutrient_demanda HHNUTRIENTS 4 name this by 0 demand type MASnutdemand this instance _hhnutrient_balance_ this by 0 1 this instance _hhnutrient_demandc_ this by 0 1 Hactivityby hhnutrient_supplya HHNUTRIENTS 4 name this by 0 supply type MASnutsupply this instance _hhnutrient_supplyc_ this by 0
35. has the same probability of receiving a plantation STEP 120 DESCRIPTION Distribute fruit plantations TYPE distribute_observation_list AGENTS OBSERVATIONS table fruit_plantations 0 f fruit table fruit_plantations 2 this observation id size table fruit_plantations 3 this observation id 1 DEL_count table fruit_plantations 4 this observation id ASSIGN 4 this observation fruit _plantation this observation size F Note each statement needs to go on one line line breaks in the example only for readability in this manual The OBSERVATIONS section of the step generates the list of observations Between the OBSER VATIONS keyword and the open curly bracket mpmasdist expects a list of observation IDs which is in this case simply read from the key column of the fruit_plantations table Observations have attributes that are defined in the OBSERVATIONS section in a similar way as agent attributes The local vari able this observation allows the use of the observation ID or previously defined observation 77 attributes In our case we read the information in the further table columns an store them in attributes named fruit size and DEL_count The DEL_count attribute is a reserved attribute that tells mpmasdist how often an observation with an ID should be distributed In the example above assets with a name formed from the content of the fruit attribute of
36. in 2 33 compatibility for mpmas 3 3 194 159 D 21 Changes in 2 36 compatibility for mpmas 3 3 204 mostly changes to Germany model and bug fixes quadratic programming e extended mqlmatrix improved quadratic programming interface D 22 Changes in 2 39 e implemented BIOVERSION 4 e sorting of LandUseActivityIDs by LP Column e Debugging output for Expert N coupling D 23 Changes in 2 40 e implemented producer organizations e bug corrections multiple markets D 24 Changes in 2 41 e implemented user variables in the scenario list and definition of the ini file and set flag for mpmasa D 25 Changes in 2 47 e bug fixes e activated exogenous yield expectations for country switch Peru e added feature to add agent attributes to matrix only country switch Germany D 26 Changes in 2 48 e bug fixes e landscape cell attributes to matrix custom NRU grouping of soils e disinvestment of assets except perennials only Germany e household member attribute 160 D 27 Changes in 2 52 bug fixes e land market parcel group version gross investments in p File 161
37. increase readability the possibility to read in tab separated ascii tables instead of sql queries as table information in fact you do not actually need a MySQL database anymore to work with mpmasg still experi mental the introduction of block comments to comment whole sets of lines syntax highlighting in the gedit editor improved structure of input files more logical distribution of entries over files better naming for some entries special ordered integer sets in the matrix improved functionality in mqlmatrix the possibility to use ASSET_ENDOWMENT information for MPMAS to create right hand sides for single farm analysis mpmasdist a tool to create agent populations However all of this comes with some major costs you actually have to do some major changes to your input files and the old manual and tutorial are outdated will rework the documentation and files in the next days This document already provides an overview of the changes you have to make in order to use mpmasgq 2 0 To update to mpmasa version 2 0 you have to do the following changes in your mpmasa input files 151 Table D 1 Version History mpmasql Date MPMAS executable Default Input Dataset 2 52 13 Aug 2014 3 3 244 DEF241 2 48 13 June 2014 3 3 230 DEF241 2 47 08 May 2014 3 3 223 DEF240 2 40 21 Feb 2014 3 3 215 DEF239 2 39 12 Dec 2013 3 3 210 DEF239 2 38 11 Dec 2013 3 3 210 DEF239 2 36 17 Sep 2013 3 3 204 DEF238 2 34 8 Aug 2013 3 3 196 DEF237
38. it 2 From the extracted v3_os11ib_1linux folder extract osllib tar 3 Copy the extracted subfolder lib and the insta11_os1 program to your home folder e g home lib if this folder does not exist create it 4 Open a terminal cd to your created folder e g exampleuser and type sudo install_osl osllib academic and press enter The process for retrieving a license will start To accept the license type yes if asked and enter username and institution 5 Open the file bashrc in your home directory with a text editor it is a hidden file if you use the file browser to find the file you need to tick View gt Show hidden files and append the following lines note the format is important here if LD_LIBRARY_PATH then export LD_LIBRARY_PATH 1lib else export LD_LIBRARY_PATH LD_LIBRARY_PATH 1lib fi Database Although not strictly required mpmasql has been developed for the use with MySQL databases MySQL is open source Under Linux it is either already included in your distribution or you can get it from your Linux repository Install the packages mysq l client and mysql server You have to fill your database with data of course before you can use mpmasq1 to create MPMAS input files from it Generally you are very flexible in the set up of your databases as long as you can provide tables in the required format to mpmasq1 with one single but possibly nested SQL SELECT statement Don t forget to
39. it is available 5 1 Interactive commands Once you loaded the matrix into memory mqimatrix provides an interactive command line environ ment The following commands are available 63 GENERAL exit help quit 1 0 printmtx lt suffix gt printtxt lt suffix gt reload solve lt suffix gt impsol lt filename gt COLUMN ROW INFORMATION info act lt id gt con lt id gt col lt C gt row lt R gt coef col lt C gt I coef row lt R gt l rhs lt R gt Ins lt R gt Ihsib lt R gt Q lt C gt multiply Q lt value gt divide Q lt value gt LISTING list act I o t list con l o t list l o t list Ihs I f e d o t list rhs l f e d o t list sol I e d o t list int I o t list Ib 1 o t list Inslb I f e d t o Options for listing commands 64 quits the interactive session prints this help quits the interactive session saves the matrix as mtx into a file with the indicated lt suffix gt saves the commented matrix into a file with the indicated lt suffix gt reloads the matrix from the original file tries to solve the matrix and to import the solution vector if successful import solution vector from file prints general information about the matrix prints information about activity with mpmasal identifier lt id gt prints information about constraint with mpmasal identifier lt id gt prints information
40. lists You can use mpmasql function language to set variable values referring to global variables configuration entries MP MAS parameters and user defined tables INSTANCES Here you provide the lists of class instances to fill your model structure with data You can use mpmasql function language to set variable values referring to global variables configuration entries MP MAS parameters user defined tables and user defined variables 106 B 3 1 GLOBALS Globals are variables that you can refer to anywhere else in the model design files i e in the model configuration the model data file and the model structure The only place where you cannot refer to them is in global definitions that come before the one in which they are defined Their main use is to implement scenarios that change MPMAS parameters or table queries The definition syntax is simple lt globalname gt lt value or list MFL expression gt and you refer to them later by using var for scalar variables respectively foreach list or qlist for list variables Examples FIRSTYEAR 2000 LASTYEAR 2010 YEARS steps var FIRSTYEAR var LASTYEAR 1 EQSH 25 B 3 2 MPMAS PARAMETERS In the MPMAS PARAMETERS section you supply values for scalar parameters for the dynamics of the MP MAS model and its submodules The definition syntax is similar to the definition of configuration entries or globals lt parametername gt lt value or
41. maize_sel1 should be double the value observed in the scalar notation of the objective function Also recall that all elements associated to the same two vari ables should be equal For example in the activity maize_se11 the value assigned to quadratic gt wheat_sell needs to be the same as the value assigned to quadratic gt maize_se11 in the activity wheat_sell mpmasql will cross check this Example implementation model structure file class CROPS 4 Hactivity sell 4 quadratic 1 quadratic gt foreach CROPS _sell table quadratic_terms 3 this instance this field 1 and data file quadratic_terms sql 2 SELECT wheat wheat 2 UNION SELECT barley barley 4 UNION SELECT maize maize 6 UNION SELECT wheat barley 1 UNION SELECT wheat maize 2 UNION SELECT barley wheat 1 UNION SELECT barley maize 0 5 UNION SELECT maize barley 0 5 UNION SELECT maize wheat 2 y 4 8 2 Example for quadratic risk programming Quadratic programming is often used to model risk behavior using a functional form like E 0 5rV 4 8 as objective function see e g Hardaker et al 2004 p 192 where E is the expected value of the gross margin r is the risk aversion coefficient and V is the variance of the total gross margin E is equivalent to the linear part of the objective function c x while V is calculated as x
42. mark_household_head and mark_successor 4 16 Selling of assets Note This feature currently only works with the special country switch for Germany 5 not for peren nial or livestock assets or any other assets with land demand To allow agents the selling of farm assets you can include activities of type MASdisinvest Since an agent may own several units of the same type of asset with different ages and thus different potential resale values it is useful to include several disinvestment activities for each asset you want an agent to be able to sell To define a disinvestment activity you only need to set the activitiy type to MASdisinvest and add an disinvest gt asset field that indicates the type of asset which is sold by this activity Remeber to use an integer activity for indivisible assets For example the following would define five disinvestment activities for the tractor asset activityby tractor_disinvest steps 1 5 1 type MASdisinvest disinvest gt asset tractor integ 1 ubound 0 lbound 0 The values for the upper and lower bounds should be set to zero mpmasq will do so automatically anyway as the upper bound will be set by MPMAS according to the number of assets owned by the agent represented by this activity While you are free to define coefficients for the activity MPMAS will fill certain coefficients of the activity according to the individual assets owned by the agent It wil
43. more than one place This ensures consistency and saves you work whenever you change a parameter value later on We add this variable to the USER VARIABLES or the GLOBALS section of the model data file GLOBALS EQSH 0 25 3 6 6 Hiring machinery Two of our example farms do not have a tractor and one does not have any machinery at all Investing into machinery is often not profitable and households hire machinery when needed To complete our introductory model we should also consider this in the model structure We simply add a hiring activity for each machinery type to our model class MACHINERY 4 Hactivity hire 4 name hire tthis instance unit ha orow 1 table machinery 5 this instance MAS_ongliq 1 table machinery 5 this instance 28 this instance capacity 1 The price per hectare is simply added to the machinery table machinery lifetime acqcost capacity hiring_price tractor 10 10000 500 50 plough 6 1000 50 15 seeder 12 3000 50 25 harrow 8 760 100 10 cultivator 8 900 100 12 machinery sql 1 SELECT machinery lifetime acqcost capacity hiring_price FROM tbl_machinery P y 8 P y As this activity is not linked to any asset it does not lead to a permanent increase in asset capacity but only extends the asset capacity for this season 3 7 Running the model 3 7 1 Creating the MPMAS input files with mpmasq1 After the model design has been creat
44. needs by setting the corresponding entries in the STATA SCRIPT section of your control file see B 1 3 9 3 Importing results into R Like for stata whenever you create a new input file set for MPMAS mpmasq1 will also create an import script for R It is named lt prefix gt _import R and placed into the same folder as the lt prefix gt _run script You can run it by typing R vanilla lt lt prefix gt _import R at the terminal after changing into the root directory of your MPMAS version By default the data is stored in the file lt prefix gt Rdata located in the subdirectory R data workspaces You can open it in R using the load function after that your workspace will at least contain two data frames per scenario one containing the combined performance information RHS and solution for each agent and period _combined and one contain ing the combined sets of user variables _userset Further there will one data frame for each set of user defined variables and scenario 3The vanilla just tells R not to neither restore nor save any data into the workspace of the current directory 32 You can fine tune the behavior of the script by adapting it manually yourself or let mpmasq1 do that for you according to the entries of the R SCRIPT section of the conversion control file see B 1 3 9 4 Transforming results into text files databases If you do not want to use neither R nor stata to analyze your data you may still
45. of the MPMAS TABLES section This table has three columns the first refers to the farm household by its farmstead id the second to the type of household member and the third to the number of members of that type which form part of the household HOUSEHOLD_COMPOSITION sql SELECT farmstead_id hh_member_type quantity FROM tbl_hh_members The corresponding table in your database could look like this farmstead_id hh_member_type quantity 300 man 1 10 300 woman 300 boy 300 girl 67 young_man 67 elder_woman 67 elder_man 15 young_man 15 young_woman A AA dl dl e y This table provides the composition of households at simulation start Unless you turn off aging of households setting OFFHHAGEING to 1 in the model configuration they will get older when the simulation years pass This has consequences for the type and amount of labor they can provide the probability of dying or giving birth and in case you use an advanced consumption model also for the amount of food they need The corresponding information is given in the table HOUSEHOLD_DYNAMICS which has at least seven columns HOUSEHOLD_DYNAMICS sql SELECT pop career upperage labgrp labprov mortality fertility FROM tbl_hh_dynamics The first column refers to the population for which the information holds remember that we could have several agent populations the second is the code for the career and the upper bound of the age range for whi
46. prices could be declared in the model data file like this prices sql 2 SELECT product year price FROM tbl_prices And the corresponding table prices could contain the following lines product year price wheat 2009 170 maize 2009 160 barley 2009 110 wheat 2010 150 maize 2010 170 barley 2010 100 wheat 2011 200 maize 2011 190 barley 2011 130 wheat 2012 130 maize 2012 180 barley 2012 90 As you can see this table contains more than one line for each crop So only by using the first column we cannot uniquely identify a row in the table On the other hand we want to record only one price for each crop in each year and so the first two columns are enough to form our row key In the table function we thus also need two elements in the key array For orow the first argument is again the instance and the second argument is the start year minus one In other words we make the very simple assumption that farmers expect to receive the same price in 2010 that they received in 2009 this field 1 For the other orows we use the function this with the arguments field and 1 When ever you have used an MFL expression resulting in a list to define a field name the this field function refers to the current index in the list More specifically this field 0 refers to the whole field name 18 this field 1 to the result of the first function that resulted in an array this field 2 to the second in case you
47. required for advanced consumption tablesource MFL expression that can The table type can be either sql or ascii For tables of types sql the expression in the curly brackets should result in an SQL SELECT statement that is being send to the database specified in the control file and results in a table of the required format E g ASSET_ENDOWMENTS sql f SELECT farmstead_id asset quantity FROM example_db tbl_assets WHERE scenario Hvar ASSETSCEN For tables of type ascii the expression in the curly brackets should result in a filename of a text file with values in tab separated format experimental E g ASSET_ENDOWMENTS ascii data assets txt List of MPMAS data tables Table B 4 MPMAS data tables Field Description Required Default 112 AGENT_INFO ASSET_CDF ASSET_ ENDOWMENTS CROPWAT_PRECIPEXPECT CROPWAT_PRECIPACTUAL CROPWAT_EVAPOEXPECT CROPWAT_EVAPOACTUAL EDICROUTING EDICINFLOWEXPECT EDICINFLOWACTUAL EDICAGENTRIGHTS EDICSECTORRIGHTS EDICIRRIGMETHODS FIXCOSTS Table that contains agent info like internal MP MAS agent_id cluster population etc from each agent Table that lists cumulative distribution functions for as sets for each cluster Table that lists asset endow ments for each household CropWat Model Table with initially expected monthly precipitation for each sector CropWat Model Table with actual monthly precipitation for each sector and sim
48. resources or assets to farm households apart from land This is done using a table called ASSET_ENDOWMENTS It looks very similar to the household composition table ASSET_ENDOWMENTS sql SELECT farmstead_id asset quantity FROM tbl_farm_assets Cash One of the basic assets of a household is cash or liquidity as it is called in MPMAS You have two options how to assign cash to a household in the model You can give a default amount of cash to every household by setting the LIQUIDITY entry in the MPMAS PARAMETERS section of the model data file E g MPMAS PARAMETERS LIQUIDITY 1000 Now every household in the model would have 1000 monetary units cash at the start of your simula tion You can override this default for every household by assigning the special asset liquidity to a household E g if the table tol_farm_assets in your database contains the following lines farmstead_id asset quantity 300 liquidity 8000 15 liquidity 250 Household 300 would start with 8000 and household 15 with 250 monetary units while household 67 would start with the default 1000 monetary units Other assets Cash and land are the only assets that are predefined by MPMAS All other assets have to be defined in the model structure So let s say you want to assign some basic implements for crop production to the agents e g ploughs and tractors While you do have to create a specific asset plough and an asset tractor these will
49. tab MEMBERS var outfolder agents_hhmembers tab Note each statement needs to go on one line line breaks in the example only for readability in this manual A slightly enhanced version of the fixed distribution type is provided by the fixed_repeated type which allows to repeat the assignments formulated in the ON_ASSIGN ASSIGNMENTS and MEM BERS section while the condition formulated in the DYNAMIC_CONSTRAINTS section are true 76 6 4 Distribution algorithms for attributes assets and household members mpmasdistoffers a number of predefined distribution algorithms in order to allow flexible random as signments of assets attributes or characteristics 6 4 1 Distributing a list of observations The most basic algorithm named distribute_observation_list randomly allocates a list of observations among agents Let us assume we have observed a number of fruit plantation in the area and gathered this information in the following table which was loaded to memory as fruit_plantations with one key column in the TABLES section id crop size quantity 1 apple 12 2 2 pear 8 1 3 apple 34 1 4 apple 5 3 5 kiwi 13 1 6 kiwi 1 10 According to the table we want to have two apple plantations of size 12 let s say ha in our pop ulation one 8 ha pear plantation and so on With the following code we would tell mpmasdist to randomly distribute all the observed populations among all agents in memory Each agent
50. the observation and the suffix _plantation are directly assigned to the asset list of the agent selected by the distribution algorithm The number of assets assigned is set according to the size attribute of the observation We could alternatively or additionally manipulate attributes of the selected agent using an ON_ASSIGN section or assign household members using a MEMBERS section Exclusiveness and accumulation The default behavior of the distribute_observation_list algorithms assumes that an agent is eligible only once for assignment of an object with the same observation ID but that it can receive several observations in the observation list as long as they have different IDs So in our example an agent could receive only one 12 ha apple plantation but it could well receive a 5 ha apple plantation or a pear plantation in addition This behavior can be changed in both directions If you assign the attribute DEL_exclusive to an observation and set it to one an agent that has been selected for an observation cannot be selected for another observation after that in the same step OBSERVATIONS table fruit_plantations 0 f fruit table fruit_plantations 2 this observation id 1 size table fruit_plantations 3 this observation id 1 DEL_count table fruit_plantations 4 this observation id DEL_exclusive 1 Note each statement needs to go on one line line breaks in th
51. the table function STEP 20 71 LOOPS 4 class family part_time commercial sector table sectors 0 Note The OUTPUT section will be processed after running through all loops Distribution types Currently the following types of distributions have been implemented They will be described in more detail in the following sections Table 6 1 Distribution types TYPE Description none does nothing only the AGENTS OUTPUT DROP_IF and CLEAN fields an sections will be processed fixed deterministic assignment fixed_repeated distribute_observation_list assign_by_cdf match match_cdf fit_into_ subarea maps_assign_farmstead maps_assign_plots maps_artificial make_secondary_maps_for_mpmas deterministic assignment which is repeated until a specified condition is true distribute a list of individual assets among agents distribute assets to agents following a probability distribu tion function match agents and list of assets respecting two sided con straints have the asset distribution match a probability distribution function with two sided constraints distribute agents over subareas such that upper limits to attributes in the area are respected spatially distributes farmsteads on a suitability map spatially distributes agents plots on a suitability map generate simplified maps for cases where spatial structure is irrelevant create population cluster network sector and catchment
52. type unit ha type MASsoil eqtype 3 this instance 136 class LABOR 4 constraint hhlabor 4 name Household labor of type Htthis instance unit person year type MASlab labgrp Htthis instance constraint labor_capacity name Capacity of labor of type this instance unit person year activity perlabin 4 name Hiring in permanent labor of type this instance unit persons type MASlabpin integ 1 ubound var LIMIT_LABOR_PERM orow 1 var WAGE_PERMANENT this instance labor_capacity 1 Hactivity hhlabout 4 name Hiring out household labor of type this instance unit persons type MASlabpout orow 1 var WAGE_HHOUSEHOLD this instance _hhlabor 1 Hactivity labor_transfer name Transfer household labor of type this instance unit persons this instance _hhlabor 1 this instance _labor_capacity 1 class MASCONSUMPTION income top block constraint xc_inc_transc name Income Transfer type MASxc_inc_trans unit var CURRENCY eqtype 3 constraint xc_inc_funcc name Income Function type MASxc_inc_func unit var CURRENCY eqtype 3 137 activity xc_inc_transa_ name Income Transfer type MASxc_inc_trans unit var CURRENCY this instance _xc_inc_funcc 1 this instance _xc_inc_transc 1 activity xc_inc_funca
53. types Remember to set the model configuration parameter NSOIL accordingly NCOLS 5 NROWS 5 XLLCORNER 3513136 YLLCORNER 5403903 CELLSIZE 100 NODATA_VALUE 1 000 1 1 2 2 1 22 1 2 0 0 1 0 2 1 0 1 1 0 0 1 0 3 5 The agent population A multi agent model needs of course a number of agents which we call the agent population In MPMAS the main class of agents are farm households In fact there may be several agent populations with different characteristics e g different ethnicities and also very different types of agents But we ll come to that later 3 5 1 Farmsteads and land ownership Every farm household owns a farmstead which is identified using an ID in the farmstead map CatchMap00Farm txt This farmstead ID is the identifier of the farm in all other model design files You can freely choose any integer number greater than zero and smaller than 999900000 E g the following map contains three farmsteads NCOLS 5 NROWS 5 XLLCORNER 3513136 YLLCORNER 5403903 CELLSIZE 100 NODATA_VALUE 1 1 1 300 1 1 1 1 1 1 1 1 1 1 15 1 67 1 1 1 1 1 1 1 1 1 Every farm household should also own some land It definitely owns the land where its farmstead is located but it can of course also own other cells as long as they lie in the study area in the same sector as the farmstead and on a cell for which a soil type has been defined The land properties of the farm household are specified in the prop
54. which are suitable and un used which could form a plot Make a list of these polygons giving them an ID and record their location i e one handle cell and size and make a polygon map i e a map which contains the IDs of the polygon a specific cell belongs to 4 Order the agents by a prespecified priority criterion e g start with the largest or smallest farm and form a queue with the farm with the highest priority in front 5 Take the first agent from the queue and randomly draw a plot size smaller or equal to the re maining area of the current plot type still to be distributed for this agent and smaller than the largest polygon still available in the map distribution to be drawn from can be changed by the user 6 Look for a suitable polygon of size equal to or larger than the randomly drawn plot size in the map e Start at the agents farmstead look at the ring of 8 neighbouring cells to see if any of them belongs to a polygon large enough If yes select that polygon and go to 7 If not look at the 16 cells around this and so on making the ring wider and wider e If after 20 widening iterations a suitable cell has not been found check if the agent already has a plot and start the same procedure at a cell of this plot e If there is no plot or all plots have already been checked and still there is no suitable polygon draw one randomly from the list of polygons wherever it is in the map 88 7 Assign the required number of c
55. will be ignored in matching algorithms A likelihood of zero does not set a hard constraint if the number of observations is smaller or equal to the number of agents The algorithm will distribute all observations and if necessary choose a combination with zero likelihood in case there is no other better option available To avoid this you can e g include observations of size zero and making sure they have a small positive likelihood If the number of observations is larger than the number of agents the user can use the field OBS_NONUSE_PENALT to name an observation attribute that defines the likelinood of an observation not being assigned mpmasdist will include artificial non use agents and assign a non use penalty equal to the value of the chosen attribute to the combination of the observation with a non use agent STEP 120 4 DESCRIPTION Distribute fruit plantations TYPE match_cdf MATCHING match_hungarian OBS_NONUSE_PENALTY_ATT nonusepenalty OBSERVATIONS table fruit_plantations 0 f nonusepenalty 1000000000 random_number 1000 Internally the algorithm minimizes negated log likelinoods i e it transforms the values specified in LIKELIHOODS by taking logarithms and multiplying with minus one The penalty is taken as is and directly corresponds to the negated log likelihood i e to make non use a matter of last resort it should probably be a very high positive number Remaining observations If not all obse
56. years should it run which submodules shall be used and so on Your configuration should at least contain the following entries TIME STARTYEAR 2010 STARTMONTH 7 STARTDAY Sl ENDYEAR 2030 ENDMONTH 6 ENDDAY 30 SEASONSTART 10 SEASONEND 9 NORTHERN El LANDSCAPE NSOIL 3 The first six entries under the headline TIME mean that the simulation shall cover the time span from July 1 2010 to June 30 2030 i e 20 simulation years The next two entries inform MPMAS that the cropping season starts every year in October and ends in September and setting NORTHERN to 1 indicates that the study region is situated in the Northern hemisphere choose 0 for Southern hemisphere The NSOIL entry informs MPMAS how many different soil types it has to expect in the soil input maps Again there are many more entries you can include into the configuration file They will be explained at the appropriate places in later sections of this manual The full overview is given in appendix B 2 3 4 The landscape Land is the defining resource of agriculture and no MPMAS model can do without a landscape which is defined using maps in ESRI ASCII raster format Maps in this format are just text files meaning you can create them in a simple text editor or spreadsheet software Sooner or later however when your model gets larger it is much better to use real GIS software nearly all of which can create and read maps in this format Each map fil
57. 3 5 3 Household members and the dynamics of aging and labor provision 9 3 5 4 Money machinery and other farm assets 12 3 6 Production and investment decisions 0 0 0 e 15 3 6 1 Crop production soils and yields 0 eee ee 15 3 62 LiquidityMeeds er aoe rr a e 20 3 6 3 LADOMUSE io in aa ee He oe a OG 22 364 Machinery USE oca a a a a ae ae eR eee ae ee aa 24 3 6 5 _Investinents s 2 6 eee BE a oe a a eee a a 26 3 6 6 Hinno MacNN 2 0 04 4 ak Be AGES A ale aa ea eS AAA 28 3 7 Running the Model dilo de de A Pe oe Ge ee EAE BE G 29 3 7 1 Creating the MPMAS input files with mpmasql o 29 3 7 2 Running MPMAS o e 30 38 SCONAMNOS e ia o ae Pee ed OY td de A 30 3 9 OutputanalySiS ee 31 3 9 1 Defining output variables a es ci bata wesa saa Kga i iii ee 31 3 9 2 Importing results into stata 2 2 2 ee ee 32 3 9 3 Importing resultsintoR 2 2 02 2 ee ee 32 3 9 4 Transforming results into text files databases 33 4 Model design with mpmasql MPMAS submodels and features 34 41 Perennial GOPS soso a da rara rd A A hast ei ed re 34 Ae uLIVESIOCK 2 A hele ie hehe E A a y 37 4 3 Crop growth models ee 38 O WAL ae Jy inani area ta Reto Sade tats A ay amp Been ee ag gy Wonk es eels oe 39 4 3 2 External crop growth models 2 2 e e ee
58. 5 T76 T77 T78 T79 T80 T81 T82 T88 T89 T90 T91 T92 T93 T94 T98 T99 Note A useful set of flags to debug input files is T1 T34 sometimes T99 might be of help Note that T1 writes all input dat files to the out test folder as tst files very useful when checking what the Dissecting maps into smaller sector wise maps writing sector Gis to file Debug shrinking of maps Debug info for land rental market Debug info for producer organizations Linux debugging verbose not recommended Edic outputs extended not recommended Translation of land use grid joining into larger map Transforming units of inflows from Wasim routing model into MP MAS Minmax Communicate all data Table of Etr Livestock Prints detailed information about the updating of household com position at the end of the period onto the screen Saving image of livestock list still under development Write results from water assignment to catchment file Save results of asset assignment detailed log file of lottery plus It and lt2 files Exogenous land use scenarios EDIC calibration run Land uses fixed by sector Save agent income data Print entries for Forced Solution to screen Always stop after random assignment Stop or continue after random assignment Waits for user input Stop after first Investment Lp solved Stop or continue after first Investment Lp solved Waits for user input Stop after first Prod
59. A small change the format of the result group feature has now been made consistent with other subelements and uses a gt ate the end So instead of resultgroup crop table process 2 this instance you now have to write resultgroup gt crop table process 2 this instance In case you knew and used the sign to get debugging output this has now become obsolete It is replaced by a new report function The syntax is report id condition arguments to report id is anid you can freely choose it is meant to avoid confusion if you use several reports condition report is only written to screen if condition is true so you can e g restrict it to certain buggy instances 156 The report function returns all except the first two arguments to the expression so the actual calculation is not affected even if you put it inside an expression Examples orow report this instance 1 1 table prices 2 this instance gt prints the result for the field orow for every instance of the class on the screen and each report is identified by the instance id orow report test this instance 24 1 table prices 2 this instance gt prints the result for the field orow for instance 24 onto the screen and the report is identified as test orow 1 report test this instance 24 table prices 2 this instance gt prints the value read from the table for instan
60. E default value can be overridden by agent spe cific values Liquidity Reserve percentage of ex pected end of year cash demand that is not entered into the MILP fraction Liquidity at the start of the simulation default value can be overridden by agent specific values Land market Minimum bid relative to average shadow prices Land market Minimum bid absolute value 109 optional optional optional optional optional optional 0 2 20 0 2 0 0 0 0 LMMAXBIDREL LMMAXBIDABS LMMKUPOUT LMMKUPIN LMTRYOUT LMTRYIN LMMAXDIST LMDURATION LMSHPAYEND MAXAGEPERM MIGRATIONPULL OPPWAGE OVERLAP PAREX RESELL SCONEXTRA SCONMIN SCONRED Land market Maximum bid relative to average shadow prices Land market Maximum bid absolute value Land market Markup for renting out decisions Land market Markup factor for renting in decisions Land market Number of renting out at tempts Land market Number of renting in at tempts Land market Maximum distance for placing bid in grid cells Land market Duration of rental con tract years Land market Share of rental payment paid after harvest Policy model Maximum age of subsi dized permanent crops integer Migration pull factor default value can be overridden by segment specific val ues in SEGINFO Opportunity wage of the household head default value can be overrid den b
61. ECT hh_member_type career sex lowage upage FROM tbl_hh_member_types The column names are not actually important what is important is the order of the columns The first column gives a name to the household member type It serves as an identifier for the type Identifiers are used very much in mpmasql and may consist of the letters a z or A Z the numbers 0 9 and the underscore The second column links the member type to a course of life or career that describes what happens to the person when it gets older This is discussed in detail a bit further below The third column indicates the gender where O indicates female and 1 indicates male The fourth and fifth column the lower and upper age You could be very specific and define a member type for each potential age a household member might have or you could be rather coarse and give an age range then MPMAS will choose the age the person has at the beginning of the simulation randomly from within this range The table in your database could look like this hh_member_type career sex lowage upage boy male_farmer 1 0 16 young_man male_farmer 1 17 30 man male_farmer 1 31 60 elder_man male_farmer 1 61 80 girl female_farmer 0 0 16 young_woman female_farmer 0 17 30 woman female_farmer 0 31 60 elder_woman female_farmer 0 61 80 Now you can use these household member categories to assign household members to each house hold You do this with the entry HOUSEHOLD_COMPOSITION which is also part
62. EXCLUDE 4 5 12 MKPATHS input gis population 70 The MKPATHS can be used to ensure that certain folders will be created if they do not exists This is especially helpful if you create various populations with one control file and want them to be saved in different folders 6 1 6 DISTRIBUTION The steps that make up the distribution algorithm are listed in the DISTRIBUTION section The de scription of each step starts with STEP lt number gt and ends with a closed bracket Steps will be processed by mpmasdist starting from the step with the lowest to the step with the highest number The order they appear in the file is irrelevant although for consistency and understandability it is of course recommendable to list them in order Numbers need not be consecutive so you can leave gaps in case you might want to introduce a step in between at a later point of time Common fields and sections for all distribution types Steps may perform very different tasks and require very different types of information to do so All types of distribution steps do however accept the fields DESCRIPTION TYPE VERBOSE SEED and the sections AGENTS OUTPUT and LOOPS The TYPE field is required and first defines what type of distribution should be performed the DESCRIPTION field is just a comment that will be printed on screen during runtime in order to facilitate supervision of program runs The VERBOSE field sets the level of debugging ou
63. GS 1 1 name Savings Segment this by 0 type MASxc_sav_seg2 unit var CURRENCY this instance _xc_sav_transc 1 this instance _xc_sav_lbound_ this by 0 1 this instance xc_sav_ubound_ this by 0 1 ubound listelement XC_SAV_INCSEGS this by 0 activity xc_sav_seg_last 1 name Savings Segment type MASxc_sav_seg3 unit var CURRENCY this instance _xc_sav_transc 1 this instance _xc_sav_ubound_ count XC_SAV_INCSEGS 1 ubound listelement XC_SAV_INCSEGS count XC_SAV_INCSEGS Hactivity xc_sav_bin_1 name Savings Binary i type MASxc_sav_binl unit var CURRENCY integ 1 ubound 1 this instance _xc_sav_ubound_1 1 listelement XC_SAV_INCSEGS 1 activityby xc_sav_bin steps 2 count XC_SAV_INCSEGS 1 name Savings Binary this by 0 type MASxc_sav_bin2 unit var CURRENCY integ 1 ubound 1 this instance _xc_sav_lbound_ this by 0 listelement XC_SAV_INCSEGS this by 0 1 this instance __xc_sav_ubound_ this by 0 1 listelement XC_SAV_INCSEGS this by 0 food non food block constraint xc_expenditure_balance name Expenditure balance type MASxc_expbal unit var CURRENCY eqtype 3 139 constraint xc_fnf_funcc name Food Expenditure Function type MASxc_fnf_func unit var CURRENCY eqtype 3 J constraint xc_fnf_constc na
64. KELIHOODS land_restr this agent land gt this observation size 50perc 1 abs 0 5 this agent land this observation size random_number 0 00001 ASSIGN 4 this observation fruit _plantation this observation size The likelihood part labeled land_restr and due to the multiplication the whole likelihood is zero for all agent observation combinations in which the plantation is larger than the agent s land In all other cases the land_restr part is one and the overall likelihood is determined by the second part labeled 50perc which results from dividing one by the absolute difference between plantation size and half of the agent land and adding a small random number This random component ensures that the algorithm arrives at a unique solution even if two combinations of agent and observation have the same absolute difference The magnitude of the random component compared to the difference quotient determines how important the restriction is Some further notes to the above example In the matching algorithm each observation ID can be allocated only once so the DEL_count attribute cannot be used Instead the OBS_multiply attribute clones the observation as many times as requested giving each clone a separate ID While using non observation specific FIXED_CONSTRAINTS is possible DYNAMIC_CONSTRAINTS MIP is still experimental and not further described here 81 sections
65. Mathematical Programming based Multi Agent Systems MPMAS MpmasQL 2 52 Layer 1 Human actors Communication networks mpmasdist Layer 2 Land and water markets mpmasql Layer 3 Landuse cover e Model info input maps input files input files txt do R i gt gt dai E 7 A z T am 7 Layer 4 Farmsteads Layer 5 Ownership MilpCheck Layer 6 Soil quality Layer 7 Water flow Christian Troost Using MPMAS with the MpmasQL toolbox User manual amp reference UNIVERSITAT HOHENHEIM MpmasQL 2 52 User manual amp reference Contact Christian Troost Dept of Land Use Economics in the Tropics and Subtropics 490d Hohenheim University 70599 Stuttgart Germany christian troost uni hohenheim de This manual is available at https mp mas uni hohenheim de Manual version 1 20 created August 14 2014 Christian Troost Universitat Hohenheim 2011 2014 Contents 1 Installation 1 2 Overview 3 3 Model design with mpmasq l A basic MPMAS model 5 Sul Folder structure 2 2 a de ae ded a de ae eee E de we ate e pe Meee ek A 5 3 27 Control tile oho dea eee eee ke te cae A ay amp E rose a 6 3 3 The model configuration 2 2 20 PE eaaa 6 3 4 The landscape susi aaa a alee be ie er 7 3 5 The agent populati0N o e 8 3 5 1 Farmsteads and land ownership 0 e eee 8 3 5 2 Populations clusters and networks 0 o e 9
66. NF_COEF_CONST Estimated constant in the food non food ex penditure share function XC_FNF_COEF_EXP Estimated coefficient of total expenditure in the food non food expenditure share func tion XC_FNF_COEF_HH Estimated coefficient of total expenditure in the food non food expenditure share func tion XC_FNF_EXPSEGS List with the widths of the total expenditure segments in the food non food expenditure share function XC_FOO_FEXSEGS List with the widths of the food expendi ture segments in the food category expendi ture share function Example Savings function coefficients XC_SAV_COEF_INC 0 3197431 XC_SAV_COEF_INC2 9 09E 006 XC_SAV_COEF_HH 89 21698 XC_SAV_COEF_CONST 5975 1 Income segementation into five segements XC_SAV_INCSEGS 800 2100 3700 7000 34000 gt FOOD NON FOOD XC_FNF_COEF_CONST 56 76446 XC_FNF_COEF_EXP 0 8757261 XC_FNF_COEF_HH 0 6778122 Segmentation of food non food expenditure XC_FNF_EXPSEGS 4500 6800 9800 15000 53000 XC_FOO_FEXSEGS 3814 5775 8259 12044 42860 Model structure It is best to simply copy the class MASCONSUMPTION provided in the appendix Sec B 4 3 This class contains most of the necessary elements which you can automatically adapt to your implemen 44 tation using the settings you provide in the data file You also need a different MASSTANDARD class which can be found in Section B 4 3 Apart from the elements in this class you should ad
67. ON_WHO LEVERAGE LIQRESERVE LIQUIDITY LMMINBIDREL LMMINBIDABS Advanced demography model Turn on investment horizon model If set to one this allows you to make investment be havior depend on the expected remain ing lifetime of the household using the corresponding parameters Advanced demography with invest ment horizon MPMAS will go through the retirement probabilities of each rel evant household member who these are is determined by the INVESTMENT _ HORIZON _WHO setting The age where the retirement probability first surpasses the value given here is iden tified as the probable end of household lifetime Expected remaining house hold lifetime if this member is then cal culated by subtracting the current age of the household member from this age The actual expected remaining household lifetime is the maximum one found among all relevant household members Advanced demography with invest ment horizon This indicates who is considered relevant for the remaining household lifetime O only the cur rent household head 1 the current household head and the household member who would become household head if the current household head re tired today 2 as in 1 plus a po tential future household head which is not old enough to become household head today but will become available as household head before the current one needs to retire Leverage at the start of the simulation 1 EQSHARE EQSHAR
68. S 2 eee i a ee ee is a en GG a ee ee A 70 6 1 6 DISTRIBUTION 2 niece de Ae AE AAA A e 71 6 2 Generating removing saving and importing agents 72 6 2 1 Generating agents o a ee 73 6 2 2 Removing agents aaao oaa a a a a 73 6 2 3 Saving agent populations oa a 74 6 2 4 Restoring agent populations o a 74 6 3 Defining and manipulating attributes and assets a 74 6 3 1 Setting and using attributes o a oa a 75 6 3 2 Removing attributes 2 0 a a a aa ae o 75 6 3 3 Assigning assets and household members o o 76 6 4 Distribution algorithms for attributes assets and household members 77 6 4 1 Distributing a list of observations 0 0 02200 0000 77 6 4 2 Assignment following a probability distribution 83 6 5 Spatial distribution o oo 86 65 1 QUICKMAPS lt ai aaa a e BAKA A ror ahaa dde dead dde 86 65 2 More realistic Maps 1 04 24 408 4 444 4 448409988 waa eee es 87 6 5 3 Making population cluster network sector and catchment maps 90 6 6 Varying agent populations 2 0 a 90 References 92 A Command line options 93 AGT Mpmasal aiii 4 bobo Ge i es a A A ee ae AAA 93 Az A Sette faecal SS Slee fe aed ot cA tudinal eRe ELE ee 94 AS IMPIMASGISt ot dd SS Gude de dee AG Aged Me Gl hed ed eee eh eee 95 AGA SMpINaS amp amp So ck dee hh da eee te
69. SIZE 10 DISTRIBUTE_ORDER 1 OUTPUT PROPERTYMAP var LOCATION gis var SEED CatchMap00Prop txt Note each statement needs to go on one line line breaks in the example only for readability in this manual The MAP section indicates the user loaded suitability map and the SUITABLE section list for each agent attribute that represents a type of land the cell values indicating suitability for this land type in the suitability map AVGPLOTSIZE controls the tentative number of cells that should be agglomerated to one plot The optional field DISTRIBUTE_ORDER controls whether the algorithm starts with the agents with largest if set to 1 default or smallest if set to 2 value for the plot type to be distributed 3The plot size is randomly drawn from a probability distribution which has AVGPLOTSIZE as its mean If the optional field PLOT_PDF is set to one default this distribution is a normal distribution with o 2x AVGPLOTSIZE if it is two itis a uniform distribution 89 Note For many agents and large farm sizes the algorithm can take very long several days to complete the task 6 5 3 Making population cluster network sector and catchment maps Once farmstead and property maps have been created mpmasdist can automatically create the other MPMAS input maps except soil maps The distribution type make_secondary_maps_for_mpmas requires only the special agent attributes MASPopulation MASNet
70. SL_M4_STHRESH OSL_M4 _LP_PRESOLVE OSL_M4_LP _PRESOLVE_ONFAIL OSL_M4_SCALE OSL_M4_SCALE _ONFAIL OSL_M4_CRASH OSL_M4_CRASH _ONFAIL OSL_M4 _CRASHMODE OSL_M4 _ PRESOLVE OSL_M4 _ _PRESOLVE _ONFAIL OSL_M4 _ _ STRATEGY OSL_M4 _ HEURPASS Switch off investments 0 1 Delay turning off investments by x peri ods Switch off soil dynamics 0 1 Switch off dynamic inflows 0 1 Minimum objective value MP MAS is sues a warning if an agent obtains an objective value lower than this Maximum solving time Maximum number of iterations Maximum number of nodes OSL sequencing 0 4 0 start in mode 1 1 or 2 start in mode 2 3 start in mode 3 4 start in mode 4 number of attempts in mode 4 Mode 4 max number of integers for first attempt Mode 4 max number of nodes pro cessed in all but last attempts Mode 4 max number of solutions to be found in all but last attempts Mode 4 first attempt to use LP presolv ing Mode 4 use LP presolving if previous attempt failed Mode 4 first attempt to use scaling Mode 4 use scaling if previous attempt failed Mode 4 first attempt to use crashing Mode 4 use crashing if previous at tempt failed Mode 4 crash mode 1 4 1 dual fea sibility may not be maintained 2 dual feasibility is maintained if possible by not pivoting in variables that are in the objective function 3 dual feasibility may not be maintained but the sum of the infeasibilities wil
71. TS 4 this agent land_for_fruits gt this observation size ASSIGN 4 this observation fruit _plantation this observation size ON_ASSIGN 4 agent land_for_fruits this agent land_for_fruits this observation size Note each statement needs to go on one line line breaks in the example only for readability in this manual If you formulate such a constraint you will want to make sure that the distribution proceeds in a suitable order usually starting with the observation that is hardest to distribute Otherwise the only agent with enough land to accommodate the 200 ha apple plantation may not be eligible any more at the time this plantation is distributed because it already received a 50 ha apple plantation and a 70 ha kiwi plantation You can determine the order in which observations will be treated using the special observation at tribute DEL_priority The lower the value of this attribute the earlier the observation will be distributed irrespective of its place in the observation list In the example above it would be a good idea to start with the largest plantations which could be achieved by adding the following line to the OBSERVATIONS section DEL_priority 1 this observation size Complex constraints and matching While in the presence of a one sided constrained ordering observations is usually enough to ensure that as many observations as possible are distributed more complex
72. about matrix column no lt C gt prints information about matrix row no lt R gt prints all coefficients lt gt O of matrix col umn no lt C gt prints all coefficients lt gt O of matrix row no lt R gt prints the rhs for row lt R gt calculates the LHS for row lt R gt based on the current solution calculates the Ihs for row lt R gt based on the lbounds of columns show Q matrix entries for column C multiply Q matrix by lt value gt divide Q matrix by lt value gt list all activities list all constraints list all equality constraints prints all LHS values lt gt 0 or all with f prints all RHS values lt gt 0 or all with f lists the solution for all activities where itis lt gt 0 list all integer activities list all activities with lower bounds gt 0 list the LHS based on lbounds where LHS lt gt 0 redirects the output to pager in a sepa rate window o lt filename gt redirects the output to filename e scientific number format d lt n gt number of decimals default n 3 f prints all elements not only those lt gt 0 t lt type gt list only constraints activities of mp masa type lt type gt TABLE VIEW tab lt C1 gt lt C2 gt lt R1 gt lt R2 gt view tableau between columns C1 and C2 and rows R1 and R2 in spreadsheet tab lt typelistA gt lt typelistC gt view tableau for activities constraint of types given in spreadsheet where lt typelist gt is a c
73. ally be associated to a class and they occur only once Most of them are also special because they are required by MPMAS To implement this in the model structure we introduce a class MASSTANDARD which contains all elements required by MPMAS which occur only once We just assign one instance MAS to the class in the model data file MASSTANDARD MAS The class implementation would look like this class MASSTANDARD constraint liqendow name unit type Liquidity endowment Euro MASliq constraint yearllig name unit type constraint name unit type constraint name unit type Year 1 liquidity Euro MASlyl ongliq 1 Pre harvest liquidity Euro MASong stcredit Short term credit limit Euro MASscl Hactivity stcreditact name Short term credit unit Euro type MASscred orow 1 Hvar INTEREST_SHCRD this instance __ongliq 1 this instance _stcredit 1 Hactivity stdeposit name Short term deposits type MASdep unit Euro orow var INTEREST_SHDEP this instance _liqendow 1 21 Hactivity ligtrans type transfer name Transfer Liquidity unit Euro this instance __ongliq 1 this instance _yearlliq 1 this instance _liqendow 1 MPMAS inserts the households cash reserves into the right hand side of the constraint of type MASliq There can only be
74. ample a common cll file is used to define the decision problem of a maize and a wheat marketing organization each of which runs a grain storage and has to decide when to sell its produce ACTIVITY TYPES sales default storage transfer finance CONSTRAINT TYPES balance default finance 52 INSTANCES POCROPS table PRODUCER_ORGANIZATIONS 4 this PO FINANCIAL account MODEL class POCROPS 4 Hactivity collect_from_members 4 name Collect this instance harvest from members unit t type transfer Hthis instance _production_of_members 1 this instance _at_PO 1 account_fbalance 0 001 activity sell_immediately name Sell this instance immediately unit t type sales this instance _at_PO 1 account_fbalance table prices 3 this instance var STARTYEAR 1 activityby sell_after_month steps 1 11 1 name Sell this instance after this by 1 months unit t type sales this instance _stored_for_ this by 1 1 account_fbalance table prices 3 this instance var STARTYEAR 1 1 4 0 01 this by 1 7 22 constraint production_of_members name this instance production of members unit t type balance constraint at_PO name this instance transported to PO unit t type balance constraintby stored_for steps 1 11 1 f name this instance stor
75. ample let s consider the following example table named members and assume it has two key fields i e the first two fields are supposed to uniquely identify each row in the table farm member gender age 1 2 m 20 1 4 f 1 3 1 f 71 3 2 m 55 The code table members 4 2 1 would return the value 71 i e the value which can be found in the fourth column of the row whose first column is 2 and whose second column is 1 If the key array of the table function contains less keys than the number of key columns defined for the table the table function returns a list of all unique values in the first omitted key column the column index is then ignored E g table members 0 would return 1 3 and table members 0 1 would return 2 4 this inserts the value of a local variable defined by mpmasql or mpmasdist this lt local variable gt this lt local array gt lt arrayindex gt this lt local object gt lt attribute name gt var inserts the value of a user defined variable global MP MAS parameter or configuration entry var lt variable name gt 150 Appendix D Version history and changelog D 1 Version History D 2 Changes from version 1 03 to 2 00 MPMASQL version 2 00 comes with some convenient new features much faster conversion for large models the CSA model converts about 2 times faster than before the possibility to have table definitions in var split over several lines to
76. an MFL expression The activity names are then formed according to the following format lt instance id gt _ lt fixed_element_id gt _ lt MFL gt In our example we get the following activities wheat_production_on_soil_0 wheat_production_on_soil_1 wheat_production_on_soil_2 maize_production_on_soil_0 maize_production_on_soil_1 maize_production_on_soil_2 barley_production_on_soil_0 barley_production_on_soil_1 barley_production_on_soil_2 this by 1 Similar to fields you can use this by 1 to refer to the current index in the by expression So the yield and soil balance fields Hthis instance _balance 1 table yields 3 this instance this by 1 1 this by 1 _soil 1 become 19 wheat_balance 1 table yields 3 wheat 0 0_soil 1 for activity wheat_production_on_soil_0 in the intermediate step What is now still missing is incorporating the yield and the variable costs tables into the model USER TABLES yields sq1 2 41 SELECT crop soil yield FROM tbl_yields variable_costs sql 1 SELECT crop variable_cost FROM tbl_variable_cost The corresponding two tables in the database could look like this crop soil yield wheat 0 6 wheat 1 7 5 wheat 2 8 maize 0 8 maize 1 10 maize 2 9 5 barley 0 5 5 barley 1 6 barley 2 6 2 crop variable_cost wheat 700 maize 950 barley 500 3 6 2 Liquidity needs Apart from soil we assigned three other resources to the age
77. ance __xc_foo_fexc 1 this instance xc_foo_lbound_ this by 0 1 this instance __xc_foo_ubound_ this by 0 1 ubound listelement XC_FOO_FEXSEGS this by 0 activity xc_foo_seg_last name LA AIDS FEX Seg count XC_FOO_FEXSEGS type MASxc_foo_seg3 unit var CURRENCY this instance _xc_foo_fexc 1 this instance _xc_foo_ubound_ count XC_FOO_FEXSEGS 1 ubound listelement XC_FOO_FEXSEGS count XC_FOO_FEXSEGS 143 Hactivityby xc_foo_bin steps 1 count XC_FOO_FEXSEGS 1 1 name LA AIDS FEX Binary this by 0 type MASxc_foo_bin unit var CURRENCY integ 1 ubound 1 this instance xc_foo_lbound_ this by 0 listelement XC_FOO_FEXSEGS this by 0 this instance _xc_foo_ubound_ this by 0 1 1 listelement XC_FOO_FEXSEGS this by 0 1 Food category transfers constraintby xc_foo_cattransc table foodcats 0 4 name Food Category Transfer table foodcats 2 this by 0 type MASxc_foo_cattrans unit var CURRENCY eqtype 3 Hconsumption gt category Hthis by 0 Hactivityby xc_foo_cattransa table foodcats 0 f name Food Category Transfer table foodcats 2 this by 0 type MASxc_foo_cattrans unit var CURRENCY this instance _xc_foo_cattransc_ this by 0 1 this instance _xc_foo_foodcat_ this by 0 1 Hactivityby buy_foodcat table
78. aphy model index of a MILP activity whose solution value needs to be larger than zero for suc cession at death to occur Advanced demography model share of household minimum consumption to be covered for voluntary retirement and succession Advanced demography model mini mum income to be reached for volun tary retirement with succession Advanced demography model index of a MILP activity whose solution value needs to be larger than zero for volun tary retirement and succession to occur not used yet Advanced demography model share of household minimum consumption to be covered for succession after obliga tory retirement Advanced demography model mini mum income to be reached for succes sion after obligatory retirement Advanced demography model index of a MILP activity whose solution value needs to be larger than zero for suc cession after obligatory retirement to occur Transport cost for one gridcell number for land markets Advanced consumption model List with the width of the income segments except first of the savings function Advanced consumption model Esti mated coefficient of income in the sav ings function Advanced consumption model Esti mated coefficient of squared income in the savings function Advanced consumption model Esti mated coefficient of household in the savings function 111 optional optional optional optional optional optional optional o
79. associated to a list of assets and a number of attributes that are generated changed used or deleted during the distribution process After each step all the information associated to the agent population can be saved Each step can start with the agents in memory or by restoring a stored agent population from file In this way the generation process can be stopped and re initiated allowing alterations to later steps without having to run through previous steps again and also giving the user the opportunity to split up the generation algorithm over several control files The distribution is started by calling mpmasdist with the name of the control file e g mpmasdist example dst 6 1 File structure The control file is subdivided into six parts that bear the headings DB VARIABLES TABLES MAPS CONTROL and DISTRIBUTION The actual steps of the distribution process are defined in the DIS TRIBUTION section The CONTROL section determines which of these steps will be run The other sections define or import the necessary data 6 1 1 DB The DB section contains the information necessary to connect to the database similar to the mpmasq1syntax It is of course only needed if database queries are to be used If the password is not provided in the file mpmasdist will ask for it at runtime 69 DB DB mpmasql_example_db localhost DBTYPE mysql DBUSER testuser DBPWD testuse 6 1 2 VARIABLES In the VARIABLES subsection user
80. at_fstd mapcell soil_in_studyarea this agent farm_x this agent farm_y Distributing plots The plot distribution algorithm of mpmasdist is designed to ensure a random distribution of plots to agents while taking account of the fact that plots of farmers are usually agglomerated and not com pletely randomly distributed over the maps Plots in reality are usually larger than one grid cell and mpmasdist tries to form contiguous stretches of land belonging to the same farmer On the other hand usually not all land of a farmer forms one contiguous plot so the algorithms tries to find a balance This reflects the typical central European situation for other situations an adaptation of the algorithm should be discussed with the mpmasdist developer team Contrary to the quick algorithm the more sophisticated algorithm does not transform attributes into cell values but looks for suitable cells in an existing suitability map for each type of plot linked to an agent attribute What the algorithm does The algorithm loops over plot types distributing area of one type first and then the next so the following is repeated for each plot type 1 Reclassify the landscape map into suitable and non suitable cells according to the specified condition 2 Mark all cells containing a farmstead and all those which have already be assigned as property in previous steps as used 3 Go through the map and identify polygons i e neighbouring cells
81. be overridden by segment specific values in SEGINFO and by asset specific val ues in the model structure file Type of expectations 0 constant 1 naive 2 adaptive 3 foresight default value can be overridden by agent specific values Income transfer migration submodel default value can be overridden by segment specific values in SEGINFO Interest rate on long term credits de fault value can be overridden by seg ment specific values in SEGINFO Interest rate on short term credits de fault value can be overridden by seg ment specific values in SEGINFO Interest rate on short term deposits default value can be overridden by segment specific values in SEGINFO Advanced demography with invest ment horizon If set to one this con straint makes the agent use his ex pected remaining household lifetime to calculate investment costs of new as sets whenever it is smaller than the lifetime of the asset Note currently not yet implemented for perennial crops and livestock E g if a an asset has a lifetime of 8 years but the lifetime is ex pected to remain in farming only 5 years more the annuity would be calculated based on 5 instead of 8 years 108 optional optional optional optional optional optional optional required required required optional 1 7E 04 6 4E 01 4 8E 04 1 0E 03 INVESTMENT _HORIZON_MODEL INVESTMENT _HORIZON _PTHRESHOLD INVESTMENT _HORIZ
82. be saved at the lowest hierarchy level i e in the folder that bears the name of the model version 3 2 Control file The content of the control file looks like this INPUT CONFIGURATION cfg example cfg STRUCTURE cfg example cll DATA cfg example var DBTYPE mysql DB example_db localhost DBUSER username DBPWD somepassword OUTPUT OUTDIR input dat OUTDIR_CM xlsInput PREFIX example The first three entries under the INPUT headline tell mpmasql the names of the model design files and that they are located in a subfolder called cfg The next four entries contain all the information needed to connect to the database Type database name and host user name and password If you do not specify the password in the file you will be asked for it at runtime The three entries in the OUTPUT section tell mpmasq1 to write the MPMAS input files to the subfolder input dat the commented files to the subfolder x1sInput and use example as the first part of the filename The rest of the filenames consists of a scenario name in case you use the scenario function and fixed parts required by MPMAS to recognize the files There are many more entries you can include into the control file They will be explained in later sections The full overview is given in appendix B 1 3 3 The model configuration In the model configuration you control the general setup of your MPMAS model When does the simulation start how many
83. bfolders out and out test set path to GIS input overwrites default folder name 95 set digits on the right side of decimal point used for rounding floating points S assign seed value for random events after lottery integer value T specify specific test runs see list below U set upper bound maximum absolute floating point in MILP X set path to xml files Y set number of simulation periods i e complete earlier than spec ified in input files Z specify name of file for dynamic switches previously flag D Debugging T1 Write all input files back to out test folder T2 Print detailed water related info to screen and file wAg files T3 Wait for user input at end of year T4 Save expected and actual water supply data for all agents in pop ulation cannot be used together with T9 T5 Save expected and actual water demand data for all agents in population cannot be used together with T9 T6 Write agents water data to file if activated in SAVE_AGENT fstd T7 Save expected and actual yields for all agents in population be fore and after estimating yields of missing crops T8 Write all random number that were generated to file in test folder T9 Save expected and actual yields for all agents in population can not be used together with T4 T10 Allocate water demand spatially 111 Save expected and actual prices for all agents in population T12 Testing input routine trace model run T13
84. bute fields for activities Field Description Values Default name Name of the activity for commented in any string N A put files unit Unit of the activity for commented input any string N A files type compare Section B 4 1 type identifier default account Account for partitioning of total gross account identifier not_specified margin lbound Lower Bound any number 0 ubound Upper Bound any number 1031 integ Integer activity 0 1 0 priority Branching priority for integer activities 0 1000 1000 pseudo_down downside pseudo costs for integers number 0 01 pseudo_up upeside pseudo costs for integers number 0 01 sos SOS the activity belongs to sos identifier 1 sos position position in SOS integer 0 orow objective row coefficient for Initital Year any number 0 and Single Matrix Mode orow_ lt modelyear gt actual objective row coefficient for year any number 0 lt modelyear gt consfix Fixed in end of year decisions 0 1 0 landfix Fixed in land market decisions 0 1 0 cptype Type of changing production costs 0 integer 0 normal 1 perennial 2 no updating of liquidity and credit coefficients account When using the R output script this not_specified field can be used to for a detailed de composition of revenue and cost into different accounts 128 type_of_payment Determines how the objective row co integer 5 efficient of the activity is treated in the MPMAS income and cash flow calcula tion 1 cash earning income
85. can be used in MFL expressions defining the tables for SCENDEF SCENLIST RHSDEF and RHSLIST using the var function All control parameters and user vari ables of the ini file can be overwritten at program call using the set flag see section A 1 In this way you can generate various scenario sets using a single ini file Table B 1 Parameters in the control file Entry INPUT optional Section heading CONFIGURATION required Name and path of the configuration file e g tutorial cfg STRUCTURE required Name and path of the structure file e g tutorial cll DATA required Name and path of the data file e g tu torial var DBTYPE required Type of the database or more specif ically of the perl DBD to be used e g mysql DB required Name of the database to connect to e g mp masql_example_db localhost DBUSER required Username for the database DBPWD optional Password for the database OUTPUT optional Section heading OUTDIR optional directory the input files shall be written to ending with a under Linux By default testoutput is used OUTDIR_CM optional directory the commented input files shall be written to ending with a under Linux By default testoutput is used OUTDIR_S optional directory where standalone matrices shall be written to ending with a under Linux By default testoutput is used OUTDIR_S CM optional directory where the commented stan dalone matrices shall be written to
86. can open the matrix or its commented version in a spreadsheet program MPMAS matrices can easily grow large and hard to handle as a whole in spreadsheets mqilmatrix provides an interface to browse experiment and solve your matrices using the standalone solver of MPMAS MilpCheck It can read a number of different matrix formats that can are either produced as debugging output of MP MAS or directly created using mpmasql see 5 2 All of these files only contain numbers and no descriptions and so mqlmatrix has to rely on the ActivityInfo and ConstraintInfo files that mpmasq1 creates when creating mpmas input files mqlmatrix lt name_of_matrix_file gt lt typeflag gt lt otherflags gt where lt typeflag gt specifies what type of matrix the browser should expect See 5 2 for more information on matrix types It is required and should be one of V lt number gt mpmas input matrix dat S standalone matrix mtx F failed matrix mip mpx D requested matrix mip mpx The optional lt otherflags gt are used inter alia to help mqlmatrix find the model info files required see 5 3 For an overview of all command line options run mqlmatrix help One of the most useful functions of mqlmatrix is showing selected parts of the matrix in a spread sheet At least under Ubuntu 10 04 we strongly recommend installing gnumeric for this task as OpenOffice takes rather long to open mqlmatrix will automatically choose gnumeric if
87. cash flow 2 earning in kind income 3 purchase of food cash flow 4 consumption of self produced food in come 5 production cost income cash flow 6 appreciation of assets income 7 utilities neither nor The following activity types have predeter mined values MASsell 1 MASsel Ikind 2 MASfoodbuy 3 MASfood consume 4 MASfuture 6 MASzero 7 MASnutpenalty 7 MAStppenalty 7 MASpenalty 7 The default value for all other activities is 5 and can be overriden here Constraint attributes Table B 31 Attribute fields for constraints Field Description Values Default name Name of the constraint for commented any string N A input files unit Unit of the constraint for commented any string N A input files eqtype Equation operator default is 1 lt digit 1 lt 2 gt 3 1 epsilon Precision for equality constraints number 0 range Lower bound for LE and EE upper number lt 103 bound for GE constraints only very sel 0 dom required to be set gt 10 type compare Section B 4 1 type identifier value for MASzero constraints cf Sect B 4 1 any number default 0 only the value to be set labgrp for MAS1ab constraints cf Sect B 4 1 labour group identifier only the labour group this labour con straint belongs to Asset attributes and subelements Table B 32 Attribute fields for assets Field Description Values name Name of the asset for commented in any string put fi
88. ce 24 onto the screen and the report is identified as test D 3 Changes in 2 03 e Corrections for perennials and livestock e Introduction of OSL mode 4 added necessary entries to model configuration mpmasqlnow creates stata import scripts automatically added necessary entries to control file Implemented interface for P flag to choose map locations D 4 Changes in 2 04 e Special country model switch Germany 5 with new asset field available_until_period e bug fixes livestock and perennials e implemented automatic creation of R import scripts e renamed THIRDMILP to HARVEST_DECISION e revised external crop growth interface D 5 Changes in 2 08 e efficiency improvements bug fixes and error checking mpmasdist livestock manual D 6 Changes in 2 10 e change matrix coefficients over time exchange gt example models e error correction in tutorial model in manual e bug fixing 157 D 7 Changes in 2 12 e New naming convention MpmasExe gt mpmas D 8 Changes in 2 14 bug fixes e runonly option D 9 Changes in 2 16 e bug fix livestock model replaced EE sign for total endowment by LE D 10 Changes in 2 19 e bug fixes mostly related to advanced consumption model and R scripts e introduced artificial maps and cluster etc maps into mpmasdist D 11 Changes in 2 20 bug fixes mostly related to advanced consumption model livestock and R scripts country model Germany min max age and inflat
89. ce in the balance sheet of the household This is achieved by assigning the identifier of the activity to the field act of the asset This field is a required field i e you need to have an investment activity for every asset even if you do not want to allow investments into that asset otherwise you will get an error You can set a multiplier of zero an unbound of zero or use the innovation diffusion submodel to avoid investments into the asset integ All our machinery assets are indivisible and thus we also need to make sure that their invest ment activity can only take integer values This is achieved by setting the integ attribute of an activity to one ubound Usually activities have an upper bound of 10 1 i e they can take near infinite values if the constraints allow this Integer activities should be constrained to some lower realistically expectable maximum value in order to help the mixed integer solver find a solution This can be done using the ubound attribute In our case we expect it to be highly unrealistic that any household might want to buy more than 10 pieces of the same machinery type at the same time var EQSH In section 3 5 4 we had explicitly set the equity share of machinery investments to 25 As we use the equity share in several of the calculations it is a good idea to define a variable for it and set the value once for all It is good practice to use variables whenever a value is used in
90. ch the following information holds The lower bound is given by the next lowest upper bound in another line referring to that career or zero The fourth column specifies which type of labor the household member is able to provide at that age This gives you the possibility to distinguish different types of labor to reflect cultural legal or educational constraints to certain activities The fifth column gives the amount of labor in the unit of your choice a household member can provide at that age in one year The sixth and seventh columns give the probability of dying respectively giving birth to a child in each year of the age range For example a household dynamics table could look like the following if we want to distinguish only one type of farm labor and take the yearly work power of an adult man as a reference unit for the labor provision pop career upperage labgrp labprov mortality fertility O female_farmer 12 farm 0 0 01 0 O female_farmer 16 farm 0 3 0 001 0 001 O female_farmer 21 farm 0 9 0 003 0 003 O female_farmer 45 farm 0 9 0 003 0 03 O female_farmer 70 farm 0 9 0 005 0 O female_farmer 90 farm 0 2 0 003 0 O female_farmer 91 farm 0 1 0 0 male_farmer 12 farm 0 0 01 0 0 male_farmer 16 farm 0 3 0 001 0 0 male_farmer 25 farm 1 0 008 0 0 male_farmer 70 farm 1 0 004 0 0 male_farmer 90 farm 1 03 0 0 male_farmer 91 farm 1 1 0 11 3 5 4 Money machinery and other farm assets Now you will probably assign some other
91. cit 47 4 5 Harvest decision If you do not want to implement a full advanced consumption model but do want to let farmers react to the results of the harvest e g by buying more animal feed if the hay harvest was worse than expected you can let agents solve a second production MILP after harvest Consumption is determined as usual using the basic consumption model The harvest decision is activated by including the following line in the model configuration HARVEST_DECISION 1 This second MILP is solved after harvest Compared to the pre season production decision it will contain actual yields and actual prices instead of expectations Like for the consumption stage you can use the consfix attribute to fix activities that can t be changed at the end of the season you should at least fix all land use activities except fallow and you can use the harvest gt subelement to change any coefficient that should differ from the pre season values 4 6 Hydrology 4 6 1 EDIC Sector based Hydrology The EDIC model is a simple sector based node link hydrology model used in the Chilean case It is hard coded into the MPMAS executable and interacts with the CropWat model which simulates crop growth under water deficit and monthly irrigation decisions Here we only point to the necessary entries for mpmasq1 consult a full description of the EDIC model for further information Note that the random water rights allocation is not yet implemented i
92. coefficients are usually missing e g yields or investment cost The type flag to use is V and you have to provide the additional information whether you use a second production or a consumption decision in your model Note if you use TSPC this won t work yet VO basic format V 1 with second production stage harvest milp V2 with advanced consumption model 65 If your matrix is very large it will take a long time to write it and to load it into mqlmatrix If you run mpmasql with the flag compact it will write only non zero coefficients in triplet format into the matrix file This file cannot be used by MP MAS however you can look at it in mqlmatrix if you also use the compact flag when loading 5 2 2 MPMAS standalone MP problem format mtx As noted above solving a standard mpmas input matrix does not make sense as the RHS is empty and several coefficients are usually missing e g yields or investment cost It is often useful to really test your matrices before including them into a full MP MAS setup Fortunately mpmasq1 has a special feature for this task Creating standalone MP problems with mpmasql If you run mpmasql with the flag S it omits creating all other input files and creates a matrix file in the correct layout for standalone matrix use mtx Like for dat matrices you can also use the compact flag to save disk space and time However you have to help mpmasq1 by putting in the additional coefficien
93. constraint structures require the use of a matching algorithm otherwise receiving a suitable allocation by random allocation may be very unlikely mpmasdist offers the match type of distribution which currently offers matching algorithms based 80 on the Hungarian method or mixed integer programming MIP In both cases all observations are matched to agents simultaneously such that an overall likelihood measure is maximized Likelinoods have to be defined for the agent for each combination of observation and agent in a special section called LIKELIHOODS This section can consists of any number of lines with a label part and a likeli hood value part separated by Each likelihood value part is evaluated and its value is combined with the likelihood values of other lines by multiplication As an example let us assume that we expect farmers would generally plant around 50 of their area with fruit plantations and that of course the total fruit plantation area cannot be larger that the total land area of the agent STEP 120 DESCRIPTION Distribute fruit plantations TYPE match_cdf MATCHING match_hungarian AGENTS OBSERVATIONS table fruit_plantations 0 f fruit table fruit_plantations 2 this observation id 1 size table fruit_plantations 3 this observation id 1 OBS_multiply table fruit_plantations 4 this observation id 7 FIXED_CONSTRAINTS this agent sector 2 LI
94. create a or choose an existing database user account for your script grant use and select privileges to all databases you want to use with mpmasql1 and adapt the database connection entries in the conversion control file If you want to use the tutorial database you can create it once you have installed a MySQL database server on your computer Use the MySQL client of your choice to create a schema named mpmasq1_example_db and a user account for your model to which you give access to the new schema The example model uses the username testuser and password testuse but you can adapt that in example ini Open the script create_example_db sql in the subfolder example_db in a graphical client interface like MySQL Workbench and run it or use the command line client mysql u lt username gt p mpmasql_example_db lt create_example_db sql Chapter 2 Overview MpmasQL is a toolbox that contains a collection of tools that assist you in working with the multi agent model MPMAS All of these tools are command line programs i e they do not have a graphical user interface but are intended to be run using the Linux terminal Input data for the tools is provided using text files and database connections Apart from providing the current version of the mpmas executable the MpmasQL package contains the following tools mpmasql1 is the core tool in the toolbox used to prepare input files for mpmas mqlmatrix canbe used to test mixed i
95. ction Probability distribution functions are defined in the OBSERVATIONS section Each distribution func tion is understood as a separate observation from which each agent receives only one value so exclusiveness is ensured by default Distribution functions can be specified in the form of frequency distributions cumulative distribution functions or quantile functions inverse cumulative distribution functions mpmasdist will internally transform them into quantile functions for Monte Carlo sampling As a frequency distribution The following table with two key columns named fruit_plantations contains three frequency distributions one for apple plantations one for pear plantations one for kiwis crop size quantity apple 12 2 apple 34 1 apple 5 3 pear 8 1 kiwi 13 1 kiwi 1 10 The frequency distribution could then be specified as follows OBSERVATIONS table fruit_plantations 0 f CDF_ftype freq CDF_freq_for_value_ table fruit_plantations 0 this observation id table fruit_plantations 3 this observation id this attribute 1 Note each statement needs to go on one line line breaks in the example only for readability in this manual As a cumulative distribution The following table with two key columns named fruit_plantations contains three cumulative probability distributions one for apple plantations one for pear plantations one for kiwis The cumulative distribution could then be spec
96. ction heading list of RHS scenarios for single matrix mode table with RHS scenario definitions for single matrix mode table with soil information if RHSDEF transform_assets is used directory with MP MAS input maps if RHSDEF transform_assets is used section heading list of input files to be skipped list of agents for which debugging MILPs shall be saved by MP MAS section heading LUE Group Simulation Server to use for remote simulation LUE Group Simserv User for remote simulation LUE Group Simserv Executable identi fier for remote simulation Model Version Identifier for remote sim ulation section heading root directory for stata scripts Default argument for set mem command in stata script Default 1000M argument for set maxvar command in stata script Default 5000 directory where MPMAS output is lo cated Default RUNOUTDIR out directory where labeling and group variable files are located Default RUNINDIR input dat section heading root directory for R scripts Default 101 R_MPMASOUT optional R_MPMASLAB optional R_TO_WORKSPACE optional R_TO_TAB R_ALL R_JOIN_RAW optional optional optional R_NO_USERVARS optional R_NO_USERSET optional R_FILTER optional B 2 Model configuration The model configuration controls the general setup of the MP MAS model It contains section head ings and entries Section headings are used to improve readability b
97. ctive crop summed over all soil types activityby production_on_soil foreach SOILS 4 resultgroup gt crop this instance You could additionally create a variable for each soil type giving you the total area of crops grown on each soil type e g activityby production_on_soil foreach SOILS 4 resultgroup gt crop this instance resultgroup gt cultivated_area_of_soil this by 0 The above will create the three crop variables as above as well as the three variables cultivated_area_of_soil_0 cultivated_area_of_soil_1 and cultivated_area_of_soil_2 Of course you can also create variables from capacities by adding resultgroup gt fields to constraints 3 9 2 Importing results into stata Whenever you create a new input file set for MPMAS mpmasq1 will also create an import script for stata It is named lt prefix gt _import_to_stata do and placed into the same folder as the lt prefix gt _run script If you use the standard folder setup you can just open stata change to the MPMAS root directory and run the script there You will then find one stata file per scenario in the subfolder Stata combined containing performance data RHS LHS solution and all user defined variables for each agent and period If you use a different folder setup or want the files to be written into different places you can change the first part of the script accordingly or let mpmasql1 directly create the script according to your
98. d After adding constraints the sampling result will probably not correspond to the original probability distribution anymore because the constraints lead to selective truncation of the sampled distribution for each agent To avoid this you can add the attribute CDF_ensure_full to the observation and set it to one mpmasdist will then first draw as many values from the distribution as there are agents and then use the ordered distribute_observation_list algorithm to try to distribute all the full range of the dis tribution function among the agents The value of the attribute CDF_ensure_full_sorting is used to 85 determine whether the distribution should start with the lowest if set to 1 or the highest default or set to 1 value drawn The attribute CDF_priority determines which observation i e which of several distribution functions is used first For more complex constraints the distribution type match_cdf combines the assign_by_cdf type with the match distribution type explained above It samples as many values from a specified distri bution function as there are agents and then finds the matching that maximizes the likelihood The syntax is similar to the syntax of the match type except that the OBSERVATIONS section uses the syntax for probability distributions explained for assign_by_cdf Drawing only from parts of the distribution function In some cases you may want the distribu
99. d a self consumption activity for all of those products which can be self consumed for covering household food needs These activities should be of type MASfoodconsume have a field consumption gt category which links it to one of the food categories in the MASCONSUMPTION class For example class CROPS 4 activity consume_own name Consume own this instance type MASfoodconsume this instance _balance 1 CONS_hhnutrient_supplyc_ foreach HHNUTRIENTS table products_nutrients 3 this instance this field 1 consumption gt category table products_food_categories 2 this instance When using the consumption model the decision problem is solved three times once for invest ments once for the production decision at the beginning of the season and once for the harvest and consumption decision at the end of the season The pre and post season MILPs look similar only actual prices and actual yields are inserted instead of expectations Further certain parts of the solution cannot be changed anymore at the end of the season e g especially the crop production activities except fallow should be fixed at their original values To indicate which activities should be fixed in the consumption stage you need to add a consfix attribute to the corresponding activities and set it to one MPMAS will then set the lower and upper bound of these activities to the solution of the pre season solution Note Th
100. d each matrix cell represents the coefficient of the variable in the equation Often only non zero coefficients are included into the matrix Equations are equalities or inequalities and are usually arranged such that all terms containing variables are arranged on the left hand side of the in equality sign and all constant terms on the right hand side 3 6 1 Crop production soils and yields Formulating equations For our farm household we will first consider two kinds of activities It can produce a certain range of crops and it can sell them To reflect this we need to include a production and a selling activity S for each crop c into the model These activities are connected by a balance equation i e you cannot sell more of a crop c than you produced Production is equal to the yield ye times area on which you produced the crop Aec Se lt Ye Ae 3 1 Rearranged such that all variable elements are left and all constant elements right In this case there is no constant element thus the right hand side is zero Se Ye K Aec lt 0 3 2 Of course the household cannot cultivate an infinite area but is restricted by the amount of land it owns Further we expect different yields on different soil types and consequently we have to distin guish production depending on the soil type j it is produced on The equation then becomes 15 Se X Vea Ac j lt 0 3 3 J The area restriction aslo distinguished by soil types can be form
101. days Hactivityby templabin foreach CROPS name Hiring in temporary labor of type this instance in harvest seasons of this by 1 unit person days type MASlabtin orow 1 Hvar WAGE_PER_DAY Hthis instance _labor_capacity_tthis by 1 1 activity hhlabout 4 name Hiring out household labor of type this instance unit persons type MASlabpout orow var WAGE_HOUSEHOLD this instance _hhlabor 1 activity labor_transfer name Transfer household labor of type this instance unit persons this instance _hhlabor 1 this instance _labor_capacity_ foreach CROPS 1 table length_of_harvest_period 2 this field 1 The household labor capacity calculated by MPMAS is entered on the right hand side of the equa tion which is marked as MASlab and whose attribute labgrp is set to the corresponding labor type 23 WAGE_PER_DAY and WAGE_HOUSEHOLD can be set in the USER VARIABLES section of the model data file E g WAGE_PER_DAY WAGE_HOUSEHOLD 120 28000 The harvest labor requirements of crop production can then be incorporated like this class CROPS 4 activityby production_on_soil foreach SOILS 4 farm_labor_capacity_ this instance table harvest_labor 2 this instance The two tables harvest_labor and length_of_harvest_period would have to be added to the model which could look like this USER TABLES harvest_labor
102. dered in income nor cash flow MAStppenalty Time preference penalty not considered in in come nor cash flow MASpenalty User defined disutility not considered in in come nor cash flow MASzero an activity not counted in cash income calcu lation go even after future selling activities Constraints MASlig Liquidity Endowment Constraint MASlab Household labour endowment MASsoil Soil Endowment MAScas Cash Financing Constraint MASinv Soil Constraint for Perennial Investments MASly1 Liquidity in first year MASong Ongoing Liquidity MASscl Short Term Credit Limit MASzero Zero Constraint go last static RHS value for all agents 126 B 4 2 DEFAULTS Here you can change default settings for elements of all classes E g if you would like to make all activities integer activities by default and set the default priority to 100 you re DEFAULTS section would look like this DEFAULTS Hactivity activity 4 integ 1 priority 100 If you do not want to specify any customary default settings you can omit the whole section B 4 3 MODEL The main model structure section contains class definitions which themselves contain model element definitions which then again contain field or attribute definitions and subelement field definitions class lt classiname gt 4 lt elementtype gt lt element identifier gt lt field name MFL expression gt lt value MFL expression gt lt subelement gt gt lt
103. dinate gt lt y coordinate gt max returns the maximum of a list of values max Hvar VARIABLE1 var VARIABLE2 min returns the minimum of a list of values min var VARIABLE1 var VARIABLE2 protected_divide performs a usual division but returns zero instead of an error in case of a division by zero or an empty array protected_divide lt dividend gt lt divisor gt qlist converts an array into a string containing the comma separated list of the double quoted array values Useful to construct IN subexpressions in SQL statements qlist lt array gt random_number draws a random number from a uniform distribution on the interval between 0 inclusive and the argument exclusive random_number lt upper bound gt regexp compares a string to a regular expression see here http perldoc perl org perlre html for information on the Perl regular expression syntax regexp lt strings to check gt lt regular expression gt replace_null replaces an empty result by the specified argument replace_null lt function result to be replaced if null gt lt replacement value gt report is a debugging function It prints arguments to screen during expression evaluation Inserts all but the first two of its arguments report id condition arguments to report id is an id you can freely choose it is meant to avoid confusion if you use several reports condition report is only writte
104. ds which are used by only one of the generated elements Shared 37 fields are name lifetime acqcost unit purchase_age salesactivity_meat The first five should be self explaining salesactivity_meat should refer to the identifier of the selling activity of the meat of the animal Specific fields are again marked with a gt surrounding the subelement they belong to The subele ment asset gt contains all fields for the asset Fields act con and div are set automatically Subele ments maintain gt and investment gt refer to fields and coefficients of the growing and investment activity that do not change with age Subelements salesstart gt and salesend gt refer to the sell at start of period and sell at end of period activities As all of these are integer activities it is recom mendable to set at least a reasonable upper bound for them Subelement disinvest gt refers to the disinvestment sell all constraint The dynamic part of the livestock element is split up into several field group dyn_liveweight dyn_offspring dyn_sales dyn_internal dyn_liquidity dyn_land dyn_labor Value def initions for these fields can either result in a scalar then they will be constant over all ages for this specific instance or they can be a function that contains this dyn as a variable referring to a specific age dyn_liveweight should contain one field whose field definition should contain the identifier of the balance constrain
105. e __ongliq 1 Hactivity ligqtrans type transfer name Transfer Liquidity unit var CURRENCY this instance __ongliq 1 this instance _yearlliq 1 this instance _liqendow 1 class MASSTANDARD constraint liqendow name Liquidity endowment unit var CURRENCY 134 type MASliq constraint yearllig name unit type constraint name unit type constraint name unit type constraint name unit type eqtype constraint name unit type constraint name unit type Year 1 liquidity var CURRENCY MAS1y1 ongliq Pre harvest liquidity var CURRENCY MASong stcredit Short term credit limit var CURRENCY MASscl liqendofyear End of year liquidity var CURRENCY MASliqend 8 stcredit_balance Short term credit balance var CURRENCY MASscbal stcredit_defyno Short term credit potential default var CURRENCY MASscdef Hactivity stcredit_repaid 4 name unit type orow this instance liqendofyear this instance _stcredit_balance Short term credit repaid var CURRENCY MASscred 1 var INTEREST_SHCRD 1 Hvar INTEREST_SHCRD 1 Hactivity stcredit_taken 4 name unit type consfix this instance _ongliq this instance _stcredit Short term credit taken var CURRENCY
106. e available in the fourth period of the simulation 4 12 4 Assigning agents to networks and segments Agents can be assigned to an innovation segment in two different ways On the one hand the special asset innovativeness can be included into the ASSET_ENDOWMENTS respectively ASSET_CDF tables and assigned the value of the segment On the other hand the innovativeness of an agent may be determined by the assets she owns To do so you can assign an innovativeness attribute to each asset The agent will be assigned to the lowest innovativeness value indicated by any of her assets the value given in the ASSET_ENDOWMENTS resp ASSET_CDF table will then only apply if it is lower than this E g in our example agents which own machinery should be assigned to segment 2 or lower other wise the initial distribution of assets would be inconsistent with the diffusion of the innovation It would therefore be necessary to include the innovativeness attribute for all machinery assets and set it to two 58 class MACHINERY asset machinery_asset innovativeness 2 4 12 5 Fine tuning the diffusion process The diffusion process can be fine tuned using the OVERLAP see B 3 and the CUMADOPT and COMTYPE parameters see B 2 4 13 Using agent attributes in the decision problem Note This feature currently only works with in the Germany version of MPMAS Ask a maintainer to activate it for your application if you want to use it Som
107. e example only for readability in this manual Conversely if you define the attribute DEL_accumulate and set it to one agents may receive several observations with the same ID Be aware that any assignment in the ASSIGN or MEMBERS section is cumulative i e if an agent already has 12 assets of type apple_plantation and additionally receives 5 it will have 17 afterwards This is different in the ON_ASSIGN section as you do not add asset s members to a list but manipulate attributes and need to define yourself whether the value is added to the attribute or replaces the old value For an addition you could for example write the following make sure that the agent attribute has been defined before ON_ASSIGN agent this observation fruit _plantation this observation size this agent this observation fruit _plantation Note each statement needs to go on one line line breaks in the example only for readability in this manual More complex compatibility relations can be defined using the DYNAMIC_CONSTRAINTS section explained in more detail in the next section For example if we wanted to make sure agents are assigned only one plantation of each fruit type we could introduce auxiliary attribute has_ lt fruit gt that is zero in the beginning and set to one as soon as the agent gets an asset of that type The constraint 78 then makes sure that the agent is not eligible for an observation of a type
108. e in ESRI ASCII format starts with lines of metadata NCOLS 5 NROWS 5 XLLCORNER 3513136 YLLCORNER 5403903 CELLSIZE 100 NODATA_VALUE 1 The first two lines indicate the number of columns and rows of the cell raster grid So in the example the map has 25 cells distributed over five rows and five columns The next two entries indicate the geodetic coordinates of the lower left corner of the lower left cell of the grid These values do not matter to MPMAS but are important if you import the maps into a GIS and want to compare it to other spatial information The cell size indicates the size of one cell i e the length of one side and the sixth line says that all cells containing a 1 should be regarded as empty After this header comes the actual cell grid Each line equals to one row of the grid and in each row there are NCOLS numbers separated by spaces tabs do work too for MPMAS each containing the actual value observed at that point in the landscape Three files define the study area its subdivisions villages administrative areas hydrological catch ments sectors or similar and the different terrains e g soil types that provide different opportunities for agricultural production Subdivisions are required for certain submodels e g the EDIC model but should be avoided if not necessary Any farm agent you later on place into the landscape can only own and rent land in the sector where his farmstead lies All map files sho
109. e te a Boda As As ds oe a ac ee A A Ale hg 95 B mpmasd file reference 99 Bali GOmtrol files atea diodos cage trot te cie teria de Ch dl Gh online eran a ds e 99 B2 Model configuration jc cocos a ia HAGE Ge POR ee eS 102 Bis Model data tile s www 0 jh ohh hae ew eines oe BUS Bee ee a 106 B 3 1 GEOBAES ss ip daria dig Ae eats tae de 107 B 3 2 MPMAS PARAMETERS oo e 107 B 3 3 MPMAS TABLES cuicos A lr pac E A 112 B 3 4 gt USER TABLES riina he arado a a a a a BA EA a N 124 B 3 5 USER VARIABLES 000002 eee eee ee 124 B 3 6 JINSTANCES ic nico a a af E A oe ae 124 B 4 Model structure fles y co cartwn E A Ree eee eS AA A 125 B 4 1 ACTIVITY TYPES and CONSTRAINT TYPES 125 Bi4 2 DEFAULES da tai kk Nee he A Que staat adnan Ae de he e 127 B 4 3 MODEL a mera atta a eh e bt AA So ale aie a 4 4 ea dee 127 C mpmasd function language 146 C 1 Numbers and StringS o e o 146 C2 Operators ts ar le iron ita HAS E ied tages ene 146 G3 Aay A AAA AAA Pe SR SAR a a 147 G 4 FunCONS 3 2 5 rt A it a eee SREB AE ee ed 148 D Version history and changelog 151 Did VErsion HIStory s sy ic ede de de Senne BP PPS he he eee aa S 151 D 2 Changes from version 1 03 to 2 00 0 0002 eee ee 151 D 2 1 Conversion control file ini aoa a ee 153 D 2 2 Configuration file cfg 2 2 02 002 ee ee 153 vi D 23 Data Te Va 5 oP doch ede Qo dn E Ha ae
110. e to 0 The expected use life of the asset lifetime can be found in the second column of the user defined table machinery in the row whose key contains the identifier of the instance The price that was or has been paid when buying the asset acqcost can be found in the third column of the same table When such an asset is bought the buyer has to pay 25 of the price in cash eqshare the rest can be financed using a credit that has the same duration as the use life of the asset at an interest which is the same for all assets of the class machinery and equal to the MPMAS parameter INTEREST_LGCRD i e the interest on long term credits Similar to household members also assets get older every year Standard assets however do not change their characteristics like household members when getting older However their lifetime is limited and once it is reached they have to be renewed or the agent has to do without them During their lifetime the household has to pay debt service for the share it did not finance itself and the associated interest There are special assets like livestock or perennial crops which do change their characteristics with age but these will be discussed in the next chapter The functions this table Q and var constitute part of the mpmasq1 function language MFL and are used to form expressions that help you make values of model elements or even the structure of model elements dependent on instances o
111. ed the creation of MPMAS input files is started by running mpmasq1 with the name of the conversion control file as an argument Open a terminal change into the model directory and type e g for our example application mpmasql example ini mpmasql will then write the input files for our example into the subfolder input dat and a commented version of the files into xlsInput Further it will create a file called lt prefix gt run i e in our case examplerun and place it into the model directory This file is a shell script that you can run to start the simulation Since it is also merely a text file you can open it in a text editor and have a look at it It should look like this bin sh mpmas Nexample__ The first line just instructs Linux that this is a shell script and the second line is the command that is to be run in the shell in our case the MPMAS executable with the option N which tells MPMAS to read the input files that start with example__ MPMAS automatically expects these to lie in a subfolder called input dat If you want you can edit the file and e g append another MPMAS option to the program call e g Y5 which tells MPMAS to stop the simulation after five years bin sh mpmas Nexample__ Y5 You can also tell mpmasq1 to always append an option to the program call by including a FLAGS entry into the conversion control file Best placed under a heading RUN SCRIPT 29 RUN SCRIPT FLAGS Y5 3 7 2 Run
112. ed for this by 1 months unit t type balance Hactivityby store_until_month steps 1 11 1 f name Store this instance until end of month this by 1 53 unit t type storage this instance _at_PO 1 this instance _stored_for_ this by 1 1 account_fbalance 0 1 0 01 this by 1 class FINANCIAL constraint fbalance name Financial balance unit var CURRENCY type finance activity profit name Financial balance unit var CURRENCY type finance orow 1 tthis instance _fbalance 1 activity fix_costs_accounting name Fix costs unit var CURRENCY type finance this instance _fbalance 1 this instance _fix_costs 1 constraint fix_costs name Fix costs unit var CURRENCY type MASzero value if this PO 0 5 10 4 11 2 The farm agents marketing decision Similar to the consumption or harvest decision stage certain decisions have already been taken and can not be reversed in the the marketing stage e g the cropping decision Activities that cannot be changed in the marketing stage are marked by setting the marketfix attribute of the activity to one class CROPS 4 Hactivityby production_on_soil foreach SOILS 4 marketfix ifthenelse this instance eq fallow 0 1 Further the activities that represent the decision of agents to market through the pr
113. eee 40 4 3 3 Exogenous yield time series 0 e eee 41 4 3 4 Adaptation of production decisions after harvest 41 4 3 5 Yield expectations for crops not grown oo o e 42 44 CONSUMPTION sismo o E Re GLA A a a 42 4 4 1 Basic consumption model o e e 43 4 4 2 Advanced three stage consumption model o 43 45 Harvest decision id EA EA 48 4 6 Flydrology 44 4 ss A AA AAA AAA AA 48 4 6 1 EDIC Sector based Hydrology o o e ee 48 4 7 Fine tuning of OSL solver o e 48 4 8 Quadratic Problems o 49 4 8 1 Example starting from a scalar valued function 49 4 8 2 Example for quadratic risk programming o o o e 50 4 9 Exogenous changes to matrix coefficients and agent independent right hand sides 51 4 10 Fragmented markets differentiate prices or LP coefficients between different groups of A A espe Gaze esas ase att ib a gar camper Roce a aa cas ih ee aha ise aia A 51 4 11 Producer organizations o a 52 4 11 1 The producer organization o o e mm 52 4 11 2 The farm agents marketing decision o o o o o 54 4 11 3 Linking farm agents and producer organizations 55 4 12 Diffusion of innovations o a 56 4 12 1 Defining the number of segments and its thresholds 56 4 12 2 Defi
114. empt reaches specified limits on the number of nodes to process or feasible solutions to find For each attempt you can add additional preprocessors to the solving sequence using a simple configuration for the first attempts and only if the solution proves too complicated and the attempt reaches its limit use more preprocessing tools in the next attempt You can also decide to keep a solution at the end of an attempt if the deviation of the solution found from the estimated best solution is within acceptable bounds See section B 2 and the OSL solver manual for more information about the specific settings for mode 4 4 8 Quadratic Problems Apart from mixed integer linear programs the agents production investment and consumption deci sions may also be formulated as quadratic programming QP problems The generic formulation of a QP problem is as follows max 5x Qx c x 4 2 Az lt b 4 3 4 4 The linear part of the objective function c7x and the constraints are implemented similar to the linear programming problem The quadratic part 3x7 Qx includes the matrix Q which is symmetric with as many columns and rows as the length of the vector of solution variables x 4 8 1 Example starting from a scalar valued function To understand the meaning of its coefficients it may be helpful to use an example with two solution variables and rewrite the formula as a scalar function M11 12 z 4 5 Q q21 22 ER 1 1 5 Qx c7x 3
115. ending with a By default testoutput is used RUN SCRIPT optional section heading RUNSCRIPTDIR optional directory where MP MAS invocation scripts should be written to EXEC optional path and name of the MP MAS exe cutable to be used default mpmas i e the standard executable that has been installed into usr local bin when installing updating mpmasal 100 RUNINDIR RUNOUTDIR RUNTDTDIR RUNCNLDIR FLAGS SCENARIOS PREFIX SCENLIST SCENDEF RHS RHSLIST RHSDEF RHS_SOILTAB RHS_MAPDIR DEBUG SKIP DBGMILPS MASPIPE MASPIPESERVER MASPIPEUSER MASPIPEEXEC MASPIPEVERSION STATA SCRIPT STATA_ROOT STATA_MEM STATA_MAXVAR STATA_MPMASOUT STATA_MPMASLAB R SCRIPT R_ROOT optional optional optional optional optional optional required optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional value for the I flag of MP MAS value for the O flag of MP MAS value for the X flag of MP MAS Directory where EDIC canal files are written other flags for MP MAS section heading A prefix for all MP MAS input file names for all scenarios Note required entry but assignment of empty value is pos sible list of scenarios the conversion script has to convert input files for table with scenario definitions se
116. ent of soil_ transfer in the constraint EU_livestock_limit will be 10 in any stand alone matrix and in the first period of the multi agent model It will change to 2 in the second period of the multi agent simulation then to 1 9 in the fourth and to 1 8 in the fifth 4 10 Fragmented markets differentiate prices or LP coefficients between different groups of agents The fragmented markets feature let s you distinguish prices i e objective function coefficients and MILP coefficients between groups of agents A group of agents with common prices or coefficients forms one market By default you have only one market with ID zero in your model If you want more markets you need to include the following entry into your configuration file MARKETS lt number_of_markets gt Markets like populations soils networks or clusters need to be numbered from zero to the number of markets minus one To assign an agent to a specific market you need to include the special asset which_market into the asset table and give it the corresponding number of the market By default all agents are part of market 0 Within the model structure file you can then use the local variable this market to differentiate values between different markets This local variable works in the value definitions of orow and orow_ lt year gt MILP coefficients of activities as well as exchange gt and harvest gt subelements 51 It does not work in by li
117. er Table that specifies the household composition in terms of household member categories and population for each household Table specifying characteris tics of population members at different ages career Table that defines the household member cat egories used in HOUSE HOLD_COMPOSITION or HOUSEHOLD_CDF table Advanced demography model Table indicating the probability that the part ner descendant of a person of career X gets career Y respectively the probability of a household member of career X to switch to career Y if certain events occur Policy model Table describ ing the characteristics of in frastructure projects Policy model Table listing farmstead_ids of participants of infrastructure projects Table specifying the availabil ity of innovations to innova tion segments Table to override any of the global INVEST MENT_HORIZON_ MPMAS parameters with population specific settings 114 required if ASSETDIST TYPE 0 required if ASSETDIST TYPE 1 required required optional optional optional optional option INVESTMENT_HORIZON _CONSTRAINTS PRODUCER_ORGANIZATIONS PRODUCER_ORGANIZATION _SERVICES REGION SEEDS SEGBOUNDS SEGINFO SUCCESSION_CONTROL Advanced demography model with investment hori zon Table listing constraints which allow to directly in fluence the LP decisions of the household depending on expected household lifetime You can
118. er the cells with soil type NRU 0 and enter it on the right hand side of constraint elevation constraint elevation 4 landscape_attribute_to gt value mean_SO_PO 4 15 Household member specific attributes Note This feature currently only works with the advanced demography model and the special country switch for Germany 5 For example for modeling farm succession it is useful to be able to mark certain household members with their own attributes e g to make sure that one person can receive subsidies for young farmers only once By adding the hhmember_mark gt subelement to an activity you can request that the solution value of of this activity in the investment problem be added to or subtracted from a household member specific marking value The field definition of the hhmember_mark gt subelement indicates for which household members the value should be recorded currently gt household_head and successor are the only options and the value definition defines whether the value should be added add or subtracted subtract For example the following would add the solution value of the employ_successor activity to the mark attribute of the next potential successor of the household head 60 Hactivity employ_successor hhmember_mark gt successor add The recorded marks can be used in any decision problem using the feature described in Section 4 13 The corresponding attribute names are
119. erty map CatchMap00Prop txt In our example household 300 owns seven plots household 15 owns five plots and household 67 owns eight plots Two plots are owned by no one NCOLS 5 NROWS 5 XLLCORNER 3513136 YLLCORNER 5403903 CELLSIZE 100 NODATA_VALUE 1 300 300 300 1 1 67 300 300 15 1 67 15 300 15 15 67 15 300 67 1 67 67 67 1 67 3 5 2 Populations clusters and networks Farm households can belong to different populations and different communication networks Differ ent populations may have different life expectancies birth rates and labor force while communication networks are relevant for simulating the diffusion of innovations see 4 12 and may face different con ditions for financing Populations may be further subdivided into clusters which are used during the initial allocation of farm assets see Clusters networks and populations are counted from zero and for historical reasons the association of a farm household with populations clusters and net works has to be specified in maps For our example and assuming all agents are associated with the same population cluster and network all three maps CatchMap00Pop txt CatchMap00Clu txt and CatchMapOONetw txt would look like this NCOLS 5 NROWS 5 XLLCORNER 3513136 YLLCORNER 5403903 CELLSIZE 100 NODATA_VALUE 1 1 1 0 1 1 1 1 1 1 1 1 1 1 0 1 O 1 1 1 1 1 1 1 1 1 3 5 3 Household members and the dynamics of aging and labor provisio
120. es produced by MPMASQL to interprete the matrix file There are several options you can let mqlmatrix guess help it with guessing or explicitly give the files If you do not specify file names explicitly mqlmatrix will guess these filenames from the name of the matrix file and look for them in x1sInput e g mqlmatrix F Mpmas out test Failed _BSL _ _ 10351_ Preloaded122 mip will make mqlmatrix look for BSL_ActivityInfo txt and BSL_ConstraintInfo txt in x1sInput Or you can specify a different folder using the flag I lt infofiles gt e g mqlmatrix F Mpmas out test Failed _BSL _ _ 10351_ Preloaded122 mip I input dat will make mqlmatrix look for BSL_ActivityInfo txt and BSL_ConstraintInto txt in input dat Or you can specify a different folder by placing a file named mqlmatrix conf into the working directory the directory from which you call mq1matrix and put in it infofiles lt folder name gt Or you can explicitly use the flags A and C to tell the script which files to use e g A input dat GEN _ActivityInfo txt C input dat GEN _ConstraintInfo txt 5 4 mqlmatrix conf By default mqlmatrix will write files to the current working directory and look for MilpCheck in usr local bin MilpChe This can be overriden by using the 0 lt outdir gt and M lt milpcheck gt flags As it would be pretty cumbersome to always specify all these locations by hand especially as you usually work in an MPMAS version
121. es still need to be linked First each pro ducer organization needs to know its members This is achieved through the producer_organization gt membership element that can be added to symbolic investment objects and takes the ID of the PO as an argument Each agent that owns such an asset is considered a member of the PO There may be several types of assets that indicate a membership in a PO but each asset can only indicate membership in one single PO Second members activities need to be accounted for in the PO decision problem and the result of the PO activity needs to be reinserted into the final farm agent outcome These linkages are defined in the table PRODUCER_ORGANIZATION_SERVICES in the MPMAS TABLES section This table needs 55 six columns two of which are key columns The first column contains the PO number the second the PO service remember a PO may offer several services The third column contains the identifier of the activity in the farm agent decision problem that indicates the quantity of the service the agent wants to apply for i e in our case the quantity of produce it offers to the PO The fourth column indicates the constraint in the PO decision problem where the sum of all member service applications is entered on the right hand side i e in our case the total amount of produce offered to the PO by its members The fifth column contains the identifier of the activity in the PO decision problem which indicates how
122. etimes you will want to make agent decisions dependent on agent specific characteristics that are not covered by any of the other submodels The agent_attribute_to gt subelement allows you include further agent specific characteristics into the matrix Used within constraint definitions agent_attribute_to gt value lt agent attribute name gt would enter the agent specific value for the desired characteristic on the right hand side of that con straint Within activity definitions agent_attribute_to gt orow lt agent attribute name gt would enter the agent specific value for the desired characteristic as the objective function coefficient of that activity while agent_attribute_to gt lt constraint identifier gt lt agent attribute name gt would enter it as a coefficient of that activity in the indicated constraint Currently the following agent attributes have been activated for the use with this feature Attribute identifier Description age_household_head The age of the household head only with Ad vanced Demography Model age_successor The age of the next successor to the house hold head only with Advanced Demography Model last_income Last year s income 4 14 Using plot attributes in the decision problem Note This feature currently only works with the special country switch for Germany 5 59 Similar to agent attributes also plot related attributes can be entered into the matrix These p
123. etworks and innovativeness segments Networks de termine which other agents actually have an influence on an agent s knowledge about an innovation Different networks are completely isolated i e even if an innovation diffuses through network one most agents in network two might never hear of the innovation Networks might e g be defined on geographical terms or distinguishing socioeconomic strata e g commercial and family farms The in novativeness segments reflect agent traits like curiosity education risk aversion and connectedness relative to other agents Highly innovative agents are well connected hear first about and innovation and are always prepared to try something new less innovative agents are more skeptical and less well connected they wait and observe the experience of other agents before they themselves try an innovation In the model when an innovation is introduced it becomes available first only to the highly innovative segment of agents and only if a certain percentage of this segment defined by the OVER LAP parameter has adopted the innovation it becomes available to the next higher segment The theory behind the module is described elsewhere in more detail here we focus on its implementation in mpmasql 4 12 1 Defining the number of segments and its thresholds First you need to define into how many networks and innovativeness segments you want subdivide your agent population You do this by specifying the number
124. ferent table than your product prices e g inputprices you could still let INTERMEDIATE use the se11 activity from PRODUCT and override only the orow attribute afterwards class INTERMEDIATES 4 has balance sell elements like PRODUCTS Hactivity sell orow table inputprices 3 thisinst The resulting selling activity will have the same attributes as the one in the PRODUCT class only the objective row attribute is defined differently In this case it is of course important that you put the has elements like statement before the overriding attribute definition Otherwise you will first define a new activity which is then overriden by the copied one 133 Templates for standard classes class MASSTANDARD constraint liqendow name Liquidity endowment unit var CURRENCY type MASliq constraint yearlligq name Year 1 liquidity unit var CURRENCY type MASlyl1 constraint ongliq name Ongoing liquidity unit var CURRENCY type MASong constraint stcredit 4 name Short term credit limit unit var CURRENCY type MASscl Hactivity stcreditact name Short term credit unit var CURRENCY type MASscred orow 1 var INTEREST_SHCRD this instance __ongliq 1 this instance _stcredit 1 J activity stdeposit name Short term deposits type MASdep unit var CURRENCY orow var INTEREST_SHDEP this instanc
125. fine additional types of LP constraints apart from the pre defined ones Constraint types are mainly used to sort the constraints in the LP matrix and to refer to groups of constraints in mqlmatrix DEFAULTS Here you can change default settings for all elements MODEL This is the main part where you define your decision model and the links to submodels B 4 1 ACTIVITY TYPES and CONSTRAINT TYPES These two sections look the pretty much the same They just contain a comma separated list of the additional types you want to define in the order you want them to appear in the LP tableau The lists can stretch over several lines Example ACTIVITY TYPES grow hire default invest CONSTRAINT TYPES balance default endowment For matrix constraints and activities types fulfill a double role First there are predefined types which denote special elements that have to be indicated to MP MAS in the input file e g the liquidity constraint short term credit activity household labor endowment soil endowment and so on see Section B 4 1 These types are known to MP MAS and should not be included into the ACTIVITY TYPES and CONSTRAINT TYPES section as there position in the input file is fixed an should not be changed Second these types are used to sort the matrix elements according to the sorting order specified by the user in the variables file The user is free or better is advised to define additional types for those ma
126. fnf_hhsizec 1 activity xc_fnf_seg_1 name Food Expenditure TEX Seg 1 type MASxc_fnf_seg1 unit var CURRENCY this instance _xc_fnf_texc 1 this instance _xc_fnf_lbound_1 1 ubound listelement XC_FNF_EXPSEGS 1 Hactivityby xc_fnf_seg steps 2 count XC_FNF_EXPSEGS 1 1 name Food Expenditure TEX Seg this by 0 type MASxc_fnf_seg2 unit var CURRENCY this instance xc_fnf_texc 1 this instance xc_fnf_lbound_ this by 0 1 this instance _xc_fnf_ubound_ this by 0 1 ubound listelement XC_FNF_EXPSEGS this by 0 activity xc_fnf_seg_last name Food Expenditure TEX Seg type MASxc_fnf_seg3 unit var CURRENCY this instance _xc_fnf_texc 1 this instance _xc_fnf_ubound_ count XC_FNF_EXPSEGS 1 ubound listelement XC_FNF_EXPSEGS count XC_FNF_EXPSEGS Hactivityby xc_fnf_bin steps 1 count XC_FNF_EXPSEGS 1 1 name Food Expenditure TEX Binary this by 0 type MASxc_fnf_bin unit var CURRENCY integ 1 ubound 1 this instance _xc_fnf_lbound_ this by 0 listelement XC_FNF_EXPSEGS this by 0 this instance _xc_fnf_ubound_ this by 0 1 1 listelement XC_FNF_EXPSEGS this by 0 1 activity xc_nonfood_expenditure name Non food expenditure type MASxc_nf_exp unit var CURRENCY this instance _xc_expenditure_balance 1 Hforeach MASSTANDARD _ligend
127. ger cropwat gt zerolab whether the activity is a zero labour ac 0 1 tivity needed for spatial allocation Further you need to define one water balance constraint for each irrigation month of type MASwater which is best placed in the class MASSTANDARD E g class MASSTANDARD constraintby watersupply foreach MONTHS type MASwater name Water availability in month this by 0 unit m73 s 39 4 3 2 External crop growth models MPMAS provides an interface to communicate with external crop growth models using the TDT library MPMAS sends a map with a numeric ID of a cropping activity in each cultivated cell or 1 for an uncultivated cell and expects the crop model to return a map with the corresponding yield in each cell The external crop growth model interface is activated by setting both the CROP_MODEL as well as the LANDSCAPE_MODEL entry in the model configuration to 3 SUBMODELS CROP_MODEL 3 Each cropping activity whose yield is to be calculated using the crop growth model needs to include additional fields which are marked with external_crop_growth gt class CROPS 4 Hactivityby production_on_soil foreach SOILS 4 external_crop_growth gt link ttable xcwlink 3 this instance this by 0 external_crop_growth gt soil this by 0 external_crop_growth gt crop_type 1 external_crop_growth gt priority 1 external_crop_growth gt producti_sales_activity this instance
128. greater than zero will refer to the current element of the it array that was used in the element field name definition For example class CROP Hactivityby grow foreach SOIL _ foreach INTENSITY 4 table crop_products 0 this instance _balance 1 table yields 4 this instance this field 1 this by 1 this by 2 Let s assume the instance list CROP contained a wheat instance let s further assume the user defined lists SOIL was 0 1 2 and the user defined list INTENSITY contained high medium low then the above element definition would return 9 activities Then the values return by the local vari ables accessed through the this function would be as shown in Table B 34 Further let s assume that the table query tttable crop_products 0 this instance _balance returned a list with two elements wheat straw the each of the 9 activities would have a field wheat_balance 132 and straw_balance corresponding to the coefficients of the activity in the constraints of the same name Then the this field 1 in the value expression would evaluate to wheat for the first and straw for the second field Reusing elements of other classes You may have classes which are pretty similar and differ only in a few elements For example you could have a class PRODUCTS and a class INTERMEDIATES Both need a yield balance constraint and a selling activity assuming there is a market for intermediate products
129. h demand of the newly planted perennials plus the foregone revenue from the crops he had previously grown on the soil surpass his liquidity a further constraint is added MPMAS will place the cash surplus of the previous year to the rhs as a basis for the estimate of future cash flows During simulation MPMAS will set the coefficient of the investment activity in this constraint to the highest cash demand for a year in the gestation period and add a certain amount on top accounting for the loss in positive cash flow from the previous use of the plot In effect this constraint restricts investment such that the sum of the highest cash demand during the gestation period of all perennials planted during this season is lower than last year s cash surplus minus the foregone cash flow of the crops that cannot be produced anymore A The later is not calculated endogenously but given exogenously as a kind of shadow cash surplus for each soil type class MASSTANDARD constraint invcash name Future expected cash surplus type MAScas Besides this another option is to restrict investment into perennial crops to only a share of the currently free plots The free plots are then divided by a physical investment bound Both physical investment bounds and shadow cash surplus can be specified for each soil type in the SEGBOUNDS table given in the MPMAS TABLES section of the data file see Tab B 26 in section B 3 The default values are 1 for the
130. hinery_asset 300 seeder_machinery_asset 300 harrow_machinery_asset 300 cultivator_machinery_asset 67 plough_machinery_asset A Ll dl dl od 3 6 Production and investment decisions We now have defined the households its members and assets and what will happen to them in evitably during the course of their life The most interesting thing about an agent however is that it can act according to his own decisions In MPMAS the most important decision for a farm household is what it grows or produces this year in order to make a living This decision is modeled using con strained mathematical programming i e the agent chooses the production plan which is optimal with respect to his objective in most cases maximizing expected income while at the same time feasible given all technical financial and resource constraints to production and satisfying all other needs and objectives of the household e g not going bankrupt or producing enough food to feed the household members in the case of subsistence farmers The decision is modeled using mixed integer linear programs and thus provides a very flexible tool that can be adapted by the model user to reflect all kind of empirical or theoretical situations A linear program consists of equations for the objective and the constraints which contain linear combinations of variables activities and is often presented in matrix format where the columns represent variables and the rows the equations an
131. i e a 200kW Tractor in the sample files There are three different ways to specify RHSDEF in the control file As an SQL query to the database RHSDEF sql SQL SELECT statement which can also span over several lines As a path to an text file in tab separated format 66 RHSDEF ascii name of an ascii file with tab separated values or as a request to transform the asset table of the full multi agent model RHSDEF transform_assets If you use the third option the RHS is directly created from the ASSET_ENDOWMENT HOUSE HOLD_COMPOSITION and AGENT_INFO tables in the data file and the soil RHS is either directly read from mpmas input maps if you specify the map directory in the control file RHS_MAPDIR directory Or alternatively read from a table specified in the control file RHS_SOILTAB sql SQL SELECT statement which can also span over several lines Similar to the SCENLIST entry you then further need an RHSLIST entry in your control file telling mpmasql which RHS should actually be created You also have three options to specify RHSLIST RHSLIST sql SQL SELECT statement which can also span over several lines RHSLIST ascii name of an ascii file with one entry on each new line RHSLIST list list of comma separated values Loading standalone MP problems with mqimatrix To load a standalone matrix you have to run mqlmatrix the using the S type flag and
132. if the corresponding attribute has been set to one STEP 120 DESCRIPTION Distribute fruit plantations TYPE distribute_observation_list AGENTS has_ apple pear kiwi 0 OBSERVATIONS table fruit_plantations 0 f fruit table fruit_plantations 2 this observation id size table fruit_plantations 3 this observation id 1 DEL_count table fruit_plantations 4 this observation id DYNAMIC_CONSTRAINTS 4 this agent has_ this observation fruit 0 ASSIGN 4 this observation fruit _plantation this observation size ON_ASSIGN 4 agent has_ this observation fruit 1 F Note each statement needs to go on one line line breaks in the example only for readability in this manual One sided constraints and distribution order Often not all agents will be eligible for a certain type of observation and the distribution algorithm should be subjected to restrictions mpmasdist distinguishes two types of constraints FIXED_CONSTRAINTS are checked only once at the beginning of a distribution i e if they contain any this observation variable before the distribution for an observation is started or if they do not contain observation specific information even only once at the beginning of the whole step For example if only agents with the sector attribute set to two should be able to receive fruit planta tions the following fixed constraint ensures that onl
133. ified as follows OBSERVATIONS table fruit_plantations 0 f CDF_ftype cdf CDF_bin_for_value_ table fruit_plantations 0 this observation id table fruit_plantations 3 this observation id this attribute 1 83 crop size cumulative_percentage apple 0 0 apple 5 50 apple 12 83 33 apple 34 100 pear 0 0 pear 8 100 kiwi 0 0 kiwi 1 91 kiwi 13 100 Note each statement needs to go on one line line breaks in the example only for readability in this manual As a quantile function The following table with two key columns named fruit_plantations contains three cumulative probability distributions one for apple plantations one for pear plantations one for kiwis crop cumulative percentage size apple 0 0 apple 50 5 apple 83 33 12 apple 100 34 pear 0 0 pear 100 8 kiwi 0 0 kiwi 91 1 kiwi 100 13 The quantile function could then be specified as follows OBSERVATIONS table fruit_plantations 0 f CDF_ftype cdf CDF_value_for_bin_ table fruit_plantations 0 this observation id table fruit_plantations 3 this observation id this attribute 1 Note each statement needs to go on one line line breaks in the example only for readability in this manual Interpolation and discreteness The distribution function is usually given as an empirical function indicating only a few points on the function For sampling it has to be interpolated By default mpmasdist
134. include all the machinery for which there is information in the table we can use the table function in the definition of the instance list INSTANCES MACHINERY table machinery 0 The third argument to the table function is the so called key array whenever it is empty the function simply returns all different entries in the first column of the table so in our case it would be equivalent to writing INSTANCES MACHINERY tractor plough seeder harrow cultivator The main difference is that when you add a row to the table machinery e g information for a combine this will automatically be added to the instance list in the first case but not in the second Finally we still have to set a value for the MPMAS parameter INTEREST_LGCRD This is done in the MPMAS PARAMETERS section of the model data file E g if the interest rate for long term financing is 8 we should wirte the following MPMAS PARAMETERS INTEREST_LGCRD 0 08 Assigning assets to agents The asset definitions we just created can now be used to assign assets to the agents We simply have to add corresponding entries to the AGENT_ENDOWMENTS table we already introduced above E g if household 300 owns a full set of machinery household 67 only a plough and household 15 no machinery at all the table would have to look like this 14 farmstead_id asset quantity 300 liquidity 8000 15 liquidity 250 300 tractor_machinery_asset 1 300 plough_mac
135. ion they are rather intended as a cleaned list facilitating the extraction of those attributes relevant for use in MPMAS later on It may thus make sense to let the distribution steps first define and distribute assets as attributes and only at the end transform them to designated asset and household member assignments 6 3 1 Setting and using attributes Attributes can be created and changed in the AGENTS section For example the following code would create an attribute named liquidity and set it to 1000 for all agents an attribute named sector which is equal to the looping iterator sector and an attribute class which is an integer between 0 and 4 randomly determined for each agent Each attribute definition needs to go on a separate line in the AGENTS section and consists of a definition of the attribute name and the value it should receive separated by a AGENTS liquidity 1000 sector this sector class floor random_number 5 Similar to field definitions in mpmasq 1 attribute definitions can also create a list of fields with one line of code using e g the table foreach steps functions or an explicit array The function this attribute is used to refer to elements in the original list The function this agent allows to refer to pre viously defined attributes of the agent So the following code would create 26 attribute for each agent named male_hhmember_aged_18 female_hhmember_aged_18
136. ion is for thinks that activate submodels debugging features or provides information on number of soils populations etc while parameters is everything that is directly used during simulation of processes like interest rates consumption shares etc D 2 4 Model structure file cll 1 First a good message have programmed syntax highlighting for cll files So after installing mpmasql you should now be able to choose View gt Highlight Mode gt mpmasql gt mpmasq cll in gedit maybe you have to close gedit and reopen it after installing An have a nicely colored and better readable cll syntax Also try Edit gt Preferences gt View gt Highlight matching brackets very helpful 2 The model structure file is now also subdivided into sections which are as follows a ACTIVITY TYPES b CONSTRAINT TYPES c DEFAULTS d MODEL 3 Move the ORDER section from the var file here and adapt it to the new format If it looked like this in your var file before ORDER ACTTYPEORDER grow hire default CONTYPEORDER balance default It should now look like this in your cll file ACTIVITY TYPES grow hire default CONSTRAINT TYPES balance default 155 10 The DEFAULTS section replaces the default class The default class is now read from etc mp masq default cll and you only need to include entries into the defaults section in case you want to change default setting compared to the settings in
137. ion rate correction for assets at simulation start Result handling partitioning of TGM into user defined accounts Revision of advanced consumption model removed disinvestment and extra consumption related activities and constraints from con sumption class add energy deficit constraints deficit transfer and deficit penalty including table utility_penalty updated R import to new p File output advanced demography model D 12 Changes in 2 21 e investment horizon component for advanced demography model e income balance for advanced demography model 158 D 13 Changes in 2 22 e applied corrections for advanced consumption model revised MASCONSUMPTION and MASSTANDARD classes new user variables needed see Section 4 4 2 D 14 Changes in 2 23 implemented change of coefficients between production and consumption LPs fine tuning pa rameters D 15 Changes in 2 24 e implemented the several markets feature D 16 Changes in 2 26 e bug fixes D 17 Changes in 2 27 e bug fix in mpmasdist e Advanced consumption model MASTANDARD activity stcredit_taken set consfix to 1 MASTANDARD activity stcredit_defaulted relaxing of stcredit_balance only in harvest gt MASCONSUMPTION constraint xc_fnf_funcc set eqtype 3 D 18 Changes in 2 28 e introduced the STANDARD_LAND_ RENTS table D 19 Changes in 2 32 e introduced quadratic programming problems plus bug fixes D 20 Changes
138. ions e g table foreach sq1 Arrays remain arrays when an arithmetic or string operator is applied in combination with a scalar and form Cartesian products combinations of every element with every other element whenever an operator acts on two arrays When a numerical comparison operator is applied to an array the size of the array is used as an argument while logic operators take an array to be true whenever it is not empty e g 1 2 3 3 3 6 9 1 2 3 1 2 3 1 2 3 2 4 6 3 6 9 1 2 3 gt 1 2 1 1 2 3 gt 5 0 1 amp amp 1 2 3 0 wheat maize barley on soil 0 1 wheat on soil 0 wheat on soil 1 maize on soil 0 eee The behavior of functions when applied to an array depends on the function In general just a few functions can deal with arrays at all 147 C 4 Functions Functions take a number of arguments i e numbers strings or arrays or any expression resulting in either of them Of course they can be nested abs returns the absolute value of the expression abs lt expression gt annuity calculates an annuity annuity lt interest rate gt lt present value gt lt lifetime gt count counts the elements of an array count lt array gt floor returns the integer part of a number i e removes any decimals floor lt number gt foreach inserts a user defined array or variable as an array foreach lt user defined array gt fvalue fi
139. iration share share surface runoff share share subsurface runoff share 117 ground_sh share groundwater loss share Table B 10 Structure of the FIXCOSTS table Column Type Description pop integer Population ID key clu integer Cluster ID key upbound number Upper bound of farm size segment hectare to which the following fix costs apply key fix number Fixed cost that does not depend on farm size within the size class in mon etary units var number Additional fixed costs that depends on farm size in monetary units per ha Table B 11 Structure of the HOUSEHOLD_CDF table Column Type Description pop integer Population ID key clu integer Cluster ID key kindsexageid identifier Sex Age Category upbound number 0 100 Upper bound of CDF segment value integer number of members to assign for this CDF segment Table B 12 Structure of the HOUSEHOLD_ COMPOSITION table Column Type Description farmstead_id integer GIS Id of the farm key sexagecat identifier Identifier of the sex age category key value number number of members Table B 13 Structure of the HOUSEHOLD _MEMBER_TYPES ta ble Column Type Description For the basic demography model code identifier ID of household member category key career identifier ID of the career of this category sex 0 1 O female 1 male lowage integer lower age bound upage integer upper age bound For the advanced demography model code identifier ID of househ
140. ityby production_on_soil foreach SOILS 4 yield_expectation gt similarity_1 tthis instance yield_expectation gt similarity_2 this by 0 Inthe example above we defined two similarity levels At level one all cropping activities of the same crop are considered similar and at level two all cropping activities on the same soil Whenever new expectations have to be formed let say for wheat production on soil type 0 and the farm household did not practice this activity it will first look for all other wheat activities it realized If it did not grow wheat at all it will check all other cropping activities on soil type 0 If it did practice activities that can be considered similar it will check whether obtained yields differed from its expectation and update its yield expectation for wheat production on soil type 0 in the same way it updated the yield expectations for similar cropping activities on average 4 4 Consumption In reality farm households cannot put all of their money onto the bank or reinvest it but they will need a certain amount of money for consumption purposes In MPMAS the modeler has the choice between a basic and an advanced three stage consumption model By default the basic consumption model is used 42 4 4 1 Basic consumption model The basic consumption model is a simple Keynesian style parametric consumption model Cash consumption is calculated using the formula SCONMIN nynm SCONEXTRA tes
141. k for compatibility with MP O lt directory gt S V X nocomment r runonly set lt variable gt lt value gt Additional output a1 a2 Verbosity flags 11 12 13 14 15 MAS format override output directory set in ini file for both uncommented and com mented files single matrix mode print version information suppress writing of commented files create only run script change value of ini variable report on matrix consistency produce files for EDICMatlab routines show conversion control settings show model configuration verbose when reading model structure file verbose when processing scenario adaptations verbose when binding variables and ta bles verbose when preparing model ele ments verbose when parsing field and value definitions 93 18 verbose when sorting matrix elements 19 verbose when creating input files Hint Especially when using verbosity flags and converting many scenarios mpmasq prints a lot of text to STDOUT and your shell environment might be flooded with text You might not be able to read all text in your terminal because you are not able to scroll back as far as necessary To check all screen messages you can pipe the output into a file you can later open with an editor e g mpmasql lt inifile gt lt flags gt gt dbg txt Under Linux you can of course also use a pipe to the less or most text pagers mpmasql lt inifile gt lt flags gt
142. l can be found in Schreinemachers 2006 Here we only describe how the parameters and elements of the model have to be implemented in mpmasql1 Model configuration Set the CONSTYPE entry in the configuration file to 1 The three stage consumption model respects the nutrition requirements of household members The configuration entry HHNUTRIENTS provides a list of identifiers of these nutrients and your HOUSE HOLD_DYNAMICS table should contain columns at the end indicating the nutrient requirements for each sex and age of a kind of population member At least one nutrient has to be included Example CONSUMPTION CONSTYPE 1 HHNUTRIENTS energy protein MPMAS PARAMETERS Table 4 2 lists the parameter names used to enter the estimated coefficients and the widths of lineariza tion segments for the savings food nonfood expenditure and food category expenditure functions All 43 are required and none has a default value and all should be included in the MPMAS parameters sec tion Table 4 2 Parameters of the Field Description XC_SAV_INCSEGS List with the widths of the income segments except first of the savings function XC_SAV_COEF_INC Estimated coefficient of income in the savings function XC_SAV_COEF_INC2 Estimated coefficient of squared income in the savings function XC_SAV_COEF_HH Estimated coefficient of household in the sav ings function XC_SAV_COEF_CONST Estimated constant in the savings function XC_F
143. l never increase 4 dual feasibility is maintained if possi ble by not pivoting in variables that are in the objective function In addition the sum of the infeasibilities will never increase Mode 4 first attempt to use LP presolv ing Mode 4 use MIP presolving if previous attempt failed Mode 4 Strategy for MIP solving and presolving Mode 4 number of heuristic passes in MIP solving presolving 105 optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional optional 5 5 999 999 999 99 999 999 0 OSL_M4_ACCEPT Mode 4 accept attempt if absolute dif optional _DIFF ference to best estimated solution is smaller than this OSL_M4_ACCEPT Mode 4 accept attempt if relative dif optional _RELDIFF ference to best estimated solution is smaller than this OSL_M4_CONT Mode 4 continue after failed attempt optional _ONFAIL yes no OSL M4 MODE3 Mode 4 continue in mode 3 if all at optional _ONFAIL tempts failed yes no OSL M4 PRE Mode 4 max number of rows to be optional _ADDROWS added for integer presolving OSL_M4_LOG Mode 4 log solving process optional SHADOW PRICE CALCULATION SHDW_SWITCH Activate calculation of shadow prices optional 0 for every agent 0 1 SHDW_LPMODE Shadow prices for production orinvest optional ment LP p
144. l set the multiplier value into coefficient of the capacity constraint to account for the reduction of capacity and it wil set coefficients in the MASong MASly1 and the CASHFLOW_COEF constraint if applicable to record the additional liquidity and the reduction in debt service achieved by the disinvestment Note that on selling the asset the agent will have to repay any loan taken for it even if the resale value is lower than the remaining principal to be paid It will also set the objective function coefficient of the activity Assuming a correct objective function value is a bit tricky In terms of accounting the sale of an asset only produces income if the return of the resale is greater then the book value of the asset accounted for in the balance sheet if it is lower it even results in a loss However for plaaning we might want to assume that a farmer considers the book value of an asset he does not use anymore to be zero it will only lose value over time but not generate any income Further disinvestment in MPMAS is associated to the direct repayment of any loan taken on the asset so that disinvesting will also save interest which otherwise would have to be paid The objective function coefficient is therefore calculated as resale_share time value of asset resale_book_share time value of asset saved_interest INTEREST_SHDEP 61 Multiplication with INTEREST_SHDEP transforms the change into an infinte annuity for the an
145. les innogrp Innovation group the asset belongs to innovation group identi cf Sect 4 12 fier optional type Asset type 0 Asset with land demand integer 1 Asset without land demand 2 Sym bolic asset gt 2 Asset types defined by special country versions 129 div acqcost lifetime terrain mininvest act con perm multiplier innovativeness eqshare irate available_until_period Asset is divisible Acquisition cost of asset life time of the asset soil type the asset requires perennials Minimum investment size The related investment activity The related endowment constraint the related yield constraint for perenni als value passed into the rhs endowment when agent invests into one unit of the asset Innovativeness this object indicates Share of the acquisition cost that has to be financed from own capital Interest rate on foreign capital used to buy the asset last period the object is available for in vestment currently only for COUNTRY 5 0 1 any number any positive integer integer 0 activity identifier constraint identifier constraint identifier or 1 any number default fraction between 0 and 1 fraction between 0 and 1 integer oname Shortname for the asset 10 charac 10 Character String ters passed to MP MAS landreq Does the object require land for lottery 0 1 inflation_rate_past Country switch Germany 5 Assumed 0 average price increase in the past
146. list MFL expression gt MFL expressions can refer to global variables only Examples LIQUIDITY 10000 EQSHARE var EQSH LEVERAGE 1 var EQSH var EQSH The following table lists all defined MPMAS parameters Table B 3 MPMAS parameters Field Description Required Default ASSETMAXAGE Maximum age of assets at simulation optional 7 start integer ASSETMINAGE Minimum age of assets at simulation optional 1 start integer DURPOLICY Policy model Duration of policy mea optional 0 sure integer EFFRAIN _TYPE CropWat Model Effective rainfall optional USDA USDA USDA formula Regression regression approximation EFFRAIN_CONST CropWat Model Effective rainfall Con optional 1 3E 00 stant for Regression EFFRAIN_CWR CropWat Model Effective rainfall Co optional 3 5E 02 efficent of CWR for Regression 107 EFFRAIN_CWR2 EFFRAIN_PREC EFFRAIN_PREC2 EFFRAIN_CWRPREC EQSHARE EXPECTATIONS INCTRANS INTEREST_LGCRD INTEREST_SHCRD INTEREST_SHDEP INVESTMENT _HORIZON_AFFECT _LIFETIME CropWat Model Effective rainfall Co efficent of CWR squared for Regres sion CropWat Model Effective rainfall Co efficent of PREC for Regression CropWat Model Effective rainfall Co efficent of PREC squared for Regres sion CropWat Model Effective rainfall Co efficient of the interaction term of PREC and CWR for Regression Minimum share of equity financing for investments default value can
147. llows selling products at a higher price one might use the following implementation class PRODUCTS 4 activity sell_for_export 4 export_access 1 class ACCESS asset access_asset name symbolic 1 act this instance _get_access con this instance _access multiplier 1000000 lifetime 100 interest 0 eqshare 1 innogrp this instance div 0 constraint access name unit 57 Hactivity get_access name unit integ 1 ubound 1 The multiplier should of course be chosen adequately high and the instance export should be in cluded in the class ACCESS 4 12 3 Defining availability and accessibility of innovations To define which object is available in which segment at the beginning you need to include the table INNOVATIONS into the MPMAS TABLES section E g MPMAS TABLES INNOVATIONS sql SELECT network segment innovation_group availability accessibility FROM tbl_innovations A corresponding table for our example could look as follows In the example mechanization has network segment innovation_group availability accessibility mechanization 0 mechanization mechanization mechanization mechanization export export export export export O0o0O0O0O0O0O0O0oOoOOoO BON ORONO BARA APROOCOO 0000000 already diffused into the early majority segment while export access is an innovation which will only becom
148. lly determine the number of producer organizations from the number of entries in thie table The table has one key column and at least two further columns They first key column should contain the running number of the producer organiza tion starting from 0 The second column contains a name or description of the producer organization and the third column should contain the relative path to a cll file containing the decision problem of the producer organization Feel free to add further columns for your own use MPMAS TABLES PRODUCER_ORGANIZATIONS sql SELECT 0 PO wheat cfg po cll wheat UNION SELECT 1 PO maize cfg po cll maize The cll file for producer organizations looks similar to a standard cll file except that it should addi tionally contain its own INSTANCES section Further as of now producer organizations do not have assets SO asset perennial or livestock entries are meaningless Only exchange gt subele ments are defined MASzero constraints can be used to set fixed right hand side values You can either define separate cll files for each producer organization or have several producer or ganizations share a common cll file and distinguish between then using the local variable this PO as in the following example This local variable works in field and value definitions by lists the INSTANCES section and exchange gt subelements In the following ex
149. look very similar as both are machinery and only differ in some of their attributes e g price and lifetime Later on other model elements like LP activities and constraints will be associated to these assets and they will also look very similar and only distinguish itself in a few coefficients We can therefore create a blueprint for machinery that tells mpmasq1 which model elements need to be created for each type of machinery Objects that share similar characteristics can be said to belong to a class e g in our case the class machinery The objects that belong to a class are called its instances i e in our case a plough a tractor or a seeder would all be instances of the class machinery Defining assets Blueprints for classes are defined in the MODEL section of the model structure file MODEL class MACHINERY asset machinery_asset name this instance div 0 12 lifetime table machinery 2 this instance acqcost table machinery 3 this instance eqshare 0 25 irate var INTEREST_LGCRD The above code tells mpmasq1 that for every instance of the class MACHINERY an asset which we identify as machinery_asset has to be created The name of the asset which is used as an infor mation in commented input and model description files shall simply be the identifier of the instance Machinery assets are indivisible i e you cannot buy half a tractor so we set the div attribut
150. lot at tributes are specified in user defined maps which are named CatchMap00Udef00 txt CatchMapO00Udef01 txt Each of these maps may contain a user defined attribute that is specific to a grid cell of the map To use these maps you need to set NUDEF in the model configuration to the number of maps you want to use Note Maps need to be consecutively numbered from 0 to 1 NUDEF For incorporating these values into the decision problem a landscape_attribute_to gt subelement is provided by mpmasq1 with the generic syntax landscape_attribute_to gt lt what gt lt aggregated_plot_attribute gt lt what gt can be value for the RHS value of a constraint orow for the objective function coefficient of an activity or any constraint_idientifier for the coefficient of an activity in the constraint Plot attributes need to be aggregated by soil type respectively nutrient response unit to be entered into the matrix The lt aggregated_plot_attribute gt expression consists of three elements lt aggregation_function gt _S lt soil_type gt _P lt mapid gt Aggregation functions currently defined are Code Function mean mean average sum sum med median with average of two values for even samples min minimum max maximum medl with smaller of two values for even samples medu with greater of two values for even samples For example the following would average the value in the CatchMap00Udef00 txt file ov
151. m assets inte ger Safe rounding factor for indivisible as sets Minimum investment size amounts smaller than this will not change the en dowment of the agent Minimum share of plant water demand that has to be fulfilled for assignment of irrigated perennials in the lottery frac tion List of household nutrients Type of consumption model 0 simple 1 advanced Type of crop growth model 0 none 1 TSPC 2 CropWat 3 External 103 required optional optional optional optional required optional optional optional optional optional optional optional optional optional optional optional required for advanced consumption model optional optional gis 30 10 BIOVERSION Version of biophysical model 0 stan dard 1 CropWat Chile 2 CropWat with flood factor 3 External yields from lookup table 4 External with internal coupling in memory EXTERNAL_CROP_MODfEbnd which link files for an exter XNDBGFILES LANDSCAPE_MODEL IRRIGATION nal crop growth model are to be cre ated by mpmasq l currently available EXPERT N Whether debug yield and crop activity id files are to be created Type of landscape model 0 none 1 EDIC 2 3 External Use irrigation with landscape model 1 y LANDMARKET_MODEL Turn on land market model 0 No PERMCROP_MODEL POLICY COUNTRY HARVEST_DECISION land transfers 1 Land to Other Farm Agent 2 Rental market
152. maps in MPMAS format 6 2 Generating removing saving and importing agents At the beginning of each step the user may define that the next step should be performed with a newly generated agent population the agent population currently in memory or restored from a previously saved file If the AGENTS section is completely omitted or the space between the AGENTS keyword and the opening bracket is empty the population currently existing in memory is used AGENTS 72 6 2 1 Generating agents If an mpmasql function language expression is found between the AGENTS keyword and the opening bracket it is interpreted as a list of agent identifiers for a new agent population to be created Example 1 AGENTS 1 2 3 This would create an agent population consisting of three agents identified by the agent IDs 1 2 and 3 respectively Example 2 AGENTS steps 400 500 2 4 This would create an agent population consisting of 51 agents identified by the agent IDs 400 402 404 500 Example 3 AGENTS table land 0 This would create an agent population based on the table land Each unique value found in the first column of the table becomes the identifier of one agent cf section C 4 for the use of the table function Example 4 LOOPS sector 12 14 15 AGENTS this sector 1000 steps 1 table sectors 4 this sector 1 4 In this rather complex example the alg
153. me Food Expenditure Constant type MASxc_fnf_const unit var CURRENCY eqtype 3 constraint xc_fnf_hhsizec name Food Expenditure HHSize type MASxc_fnf_hhsize unit var CURRENCY eqtype 3 constraint xc_fnf_texc name Food Expenditure TEX type MASxc_fnf_tex unit var CURRENCY eqtype 3 constraintby xc_fnf_lbound steps 1 1 name Bound this by 0 count XC_FNF_EXPSEGS Food Expenditure TEX Segment Lower count XC_FNF_EXPSEGS type MASxc_fnf_lbound unit var CURRENCY eqtype 1 constraintby xc_fnf_ubound steps 2 name Food Expenditure TEX Segment Upper Bound this by 0 type MASxc_fnf_ubound unit var CURRENCY eqtype 1 Hactivity xc_fnf_funca name Total Expenditure Function type MASxc_fnf_func unit var CURRENCY this instance __xc_sav_balance 1 this instance _xc_fnf_constc 1 this instance __xc_fnf_hhsizec 1 this instance _xc_fnf_texc 1 this instance _xc_expenditure_balance 1 Hactivity xc_fnf_consta name Food Expenditure Constant type MASxc_fnf_const unit var CURRENCY 140 1 1 gt this instance _xc_fnf_constc 1 this instance _xc_fnf_funcc var XC_FNF_COEF_CONST activity xc_fnf_hhsizea name Food Expenditure HHSize type MASxc_fnf_hhsize unit var CURRENCY this instance _xc_
154. much of the produce was actually taken up by the PO The sixth column contains the identifier of the activity in the PO decision problem which indicates the income obtained by the PO related to this service that is to be redistributed among the agents PRODUCER_ORGANIZATION_SERVICES sql 4 u SELECT 0 wheat_sale gt wheat_sell_through_PO gt wheat_production_of_members gt wheat_collect_from_members account_profit UNION SELECT 1 maize_sale gt maize_sell_through_PO gt maize_production_of_members maize_collect_from_members account_profit 4 12 Diffusion of innovations MPMAS includes a module for the communication process involved in the diffusion of innovations This model assumes that the adoption of an innovation consists of two phases First an agent needs to learn about an innovation and be convinced that it actually works then second he will check calculate and assess whether it is profitable for him to actually use it himself The second phase is inherently represented by solving the optimization problem in the investment production decision if the activities related to the innovation are part of the solution the farmer adopted the innovation The diffusion of innovations module represents the first phase and thus deals with the question whether the activities related to the innovation are at all included in the optimization problem For short agents are grouped into communication n
155. n Every farm household consists of a number of household members Before you can assign house hold members to a household you first have to define which types of household members you want to be able to assign You do so using a table of five columns which you assign to the entry HOUSE HOLD_MEMBER_TYPES which is part of the section MPMAS TABLES in the model data file You do not put the table itself into the model data file rather you provide a link to the table either by specifying the name of a text file containing the table in comma separated format or by providing an SQL statement that retrieves a table of the required format from the database The advantage of a database query is that you do not actually need to have a table of the required format in the database you just need to be able to formulate a query that results in a suitably formatted table For the definition of household member types this is not so important but for many other tables it gives you the opportunity to store your data in a way that is best suited for the data and then extract a table format that suits your model by queries If you change your model setup or design scenarios you then simply need to adapt your queries and not your tables For the following we will always assume that you use SQL queries to specify tables A suitable query for the definition of household member types could look like this MPMAS TABLES HOUSEHOLD_MEMBER_TYPES sql SEL
156. n mpmasq1 You can activate the EDIC model by setting the LANDSCAPE_MODEL entry under SUBMODELS in the cfg File to 1 Second you should set the VINFLOWS variable to two third you should activate IRRIGATION SUBMODELS LANDSCAPE_MODEL 1 IRRIGATION 1 VINFLOWS 2 To use the EDIC model you will have to provide additional input in your cfg file First your REGION table needs additional columns as shown in Tab B 22 Second you need the additional MPMAS TA BLES described in Tab B 9 Section B 3 Note that months should be specified as calendar months mpmasql1 automatically transforms these into irrigation season months based on the SEASONSTART and SEASONEND values given in the TIME section 4 7 Fine tuning of OSL solver The OSL solver is a very powerful tool to solve mixed integer programming problems Apart from the branch and bound and LP solvers it offers a number of preprocessing tools that help to improve the efficiency of the main solver These preprocessing tools may be combined in very different constella tions Unless you choose a quadratic problem mpmasq1 assumes you want to use the costumizable MP MAS solver mode 4 modes 1 3 can be considered outdated and obsolete The general idea behind mode 4 is that you have several attempts to solve the MILP In each attempt except the last a solution is searched using the specified tool The attempt ends if either the optimal solution has been found 48 or the att
157. n to screen if condition is true so you can e g restrict it to certain buggy instances The report function returns all except the first two arguments to the expression so the actual calculation is not affected even if you put it inside an expression Examples orow report this instance 1 1 table prices 2 this instance gt prints the result for the field orow for every instance of the class on the screen and each report is identified by the instance id orow report test this instance 24 1 table prices 2 this instance 149 gt prints the result for the field orow for instance 24 onto the screen and the report is identified as test orow 1 report test this instance 24 table prices 2 this instance gt prints the value read from the table for instance 24 onto the screen and the report is identified as test round_to rounds a number to specified number of decimals round_to lt number gt lt decimals gt sql retrieves data from an sql database sql lt SQL select statement gt steps evaluates to an array of values of equal distance Hsteps lt start value gt lt end value gt lt stepsize gt table inserts a value or array read from a user defined table table lt tablename gt lt column index gt lt keyarray gt Internal tables in mpmasql and mpmasdist are indexed by a number of columns which was defined when the table was loaded As an ex
158. nancial function used to calculate the coefficient of average fixed equity on an investment 1 1 1D txi fvalue lt interest gt lt lifetime gt if returns a value depending on a condition if lt condition gt lt value if true gt lt value if false gt ifalone distinguishes field values between conversion modes The setup of some matrix elements differs depending on whether you are converting standalone matrix files or full MP MAS input files For example investment activities should have a 0 in the constraint they add an endow ment to in full MP MAS mode as this will be entered by MP MAS according to the network file while they need an entry there in Standalone Matrix Mode ifalone lt value when in standalone mode gt lt else gt ifthenelse like if but the condition is evaluated as a perl expression allows the use of string com parison regular expressions etc ifthenelse lt condition gt lt value if true gt lt value if false gt list converts an array into a string containing the comma separated list of the unquoted array values Hlist lt array or list gt list_concat concatenates several arrays 1list_concat lt array1 gt lt array2 gt list_element inserts the ith element of an array 148 list_element lt array or list gt lt index gt mapcell retrieves a value from a cell in a raster map currently only in mpmasdist mapcell lt mapname gt lt x coor
159. nce constraint capacity name this instance capacity class CROPS 4 activityby production_on_soil foreach SOILS 4 table work 0 this instance _capacity table work 3 this instance this field 1 con The con attribute of an assets links it to the constraint of its capacity you simply have to assign it the identifier of the corresponding capacity constraint multiplier The multiplier specifies the capacity per asset i e it would be 50 for our plough It is read from the fourth column of our machinery table so we have to make sure our machinery table also contains four columns The updated table might look like this machinery lifetime acqcost capacity tractor 10 10000 500 plough 6 1000 50 seeder 12 3000 50 harrow 8 760 100 cultivator 8 900 100 And we need to make sure the additional column is also imported into our model machinery sql 1 SELECT machinery lifetime acqcost capacity FROM tbl_machinery table work The machinery requirements for the different crop production activities are read from a table named work which might look like this crop machinery frequency wheat plough 1 25 maize plough barley plough wheat harrow maize harrow barley harrow wheat seeder maize seeder barley seeder maize cultivator A AA Al ANA ee As you can see the different crops have multiple and different field preparation requirements so thi
160. nd their interaction as independent variables The evapotranspiration values are reference values which are transformed into plant specific evap otranspiration by multiplying them with the respective plant specific coefficient for the corresponding months ke These k are entered for each cropping activity in the model structure file together with other essential values needed for the CropWat model For this purpose a new field marker cropwat gt is introduced that can be placed inside activities and perennial objects Under this marker the fields listed in Tab 4 1 should be specified Table 4 1 Required fields with the cropwat gt marker Field Description Values cropwat gt irrigation_method irrig_id as specified in EDICIRRIG integer METHODS or 1 for rainfed cropwat gt k_y yield sensitivity to water deficit number cropwat gt ipg irrigation priority group 1 unirrigated integer cropwat gt seasonality cropwat gt yield_potential cropwat gt yield_start 0 highest priority seasonality 2 annual potential yield without deficit agent yield expectation in first year integer 0 2 number number cropwat gt kc_ foreach MONTHS kc value of crop for each months of the number irrigation season cropwat gt yield_constraint identifier of the yield constraint of the identifier crop cropwat gt sales_activity identifier of the sales activity of the identifier product cropwat gt soil soil type inte
161. nd will be ignored by mpmasql This is also a comment which spans over several lines MFL expressions At many locations in the files you can use mpmasql1 function language MFL to write expressions to specify that a certain value depends on another value e g the scenario the specific instance of a class or another variable The reference of all available MFL functions and operators is given in chapter C B 1 Control file The control file contains settings that instruct mpmasq1 which model design and data sources to use to build the model where to write and how to name the output and which scenarios to create It contains a number of entries of the form lt control parameter gt lt scalar list MFL expression gt The SCENDEF RHSDEF SCENLIST RHSLIST and RHS_SOILTAB entries are special because they expect a table definition tablename tabletype 4 tablesource an SQL statement for type sql a filename for type ascii or a comma separated list for type list 99 All of the tables can be of type sql or ascii SCENLIST and RHSLIST can also be of type list For RHSDEF you can specify a type transform_assets with empty curly brackets indicating that you want right hand sides to be automatically created from the ASSET_ENDOWMENT HOUSE HOLD_COMPOSITION and RHS_SOILTAB tables Apart from the predefined control parameters listed in table B 1 you can also define own user vari ables with the same syntax which
162. ning MPMAS Especially the first time you try to run MPMAS on a computer you ll probably need to make sure it is permitted to execute mpmas and the lt prefix gt run script assuming you have installed the OSL properly If you get problems with permissions set the executable permissions by typing the following in a terminal in your model directory chmod a x examplerun No you can simply run the examplerun script examplerun and MPMAS will start running and writing output to the out subfolder 3 8 Scenarios For each scenario you want to run you have to create a separate set of MPMAS input files This does however not mean that you have to create new model configuration files for each scenario mpmasql offers an easy to use scenario mechanism which allows to adapt any parameters or variables you have used in your model design according to scenario settings you provide to mpmasql More specifically you can adapt every entry in the model configuration any MPMAS parameter all global and user defined variables any instance list and the source string of every MPMAS and user defined table using the scenario mechanism So basically you can change everything except the table types and structure even the model structure if you use your variables and lists wisely in the definition of the model structure The basis of the scenario mechanism is a table which is assigned to the SCENDEF field in the conversion control file It needs only
163. ning innovations 2 20 o e 57 4 12 3 Defining availability and accessibility of innovations 58 4 12 4 Assigning agents to networks and segments 4 58 4 12 5 Fine tuning the diffusion process 0 0 00 022 ee eee 59 4 13 Using agent attributes in the decision problem ooo 59 4 14 Using plot attributes in the decision problem oo o 59 4 15 Household member specific attributes 0 o e 60 4 16 Selling of assets oo 61 Testing decision models with mpmasql and mqlmatrix 63 5 1 Interactive commands A E AEE ain Ba Ar T E E a A 63 5 2 Formats of MP problems 0 000 ee 65 5 2 1 MPMAS input format dat o oo e 65 5 2 2 MPMAS standalone MP problem format mtx o o 66 5 2 3 MP problems automatically saved by mpmas for debugging 67 5 2 4 MP problems saved by mpmas for debugging On request 67 5 3 Indicating the location of the model info files o 68 DA MQUIIATNECON Lavin rr a A AM Ne es 68 Preparing agent populations with mpmasdist 69 631 ARIO STUCULS Di chek eR Ge Bt ER Se he eases 69 Bide SDB AN NA 69 6 1 2 VARIABLES S uti fone net anaes hs ee ee de a Role nen ee 70 6 13 TABLES z aca ee Seana neh ee eee a ee EE ba a Pes 70 Baldio MAPS oras a aor at ar ae Me re a Me AA iw wo Br 70 63125 CONTROL
164. nnial_preharvest_cost 0 dynamic gt perennial_harvest_cost 0 dynamic gt farm_labor_capacity_ foreach CROPS table perennial_labour 4 this instance this dyn this field 0 investment gt this by 0 _soil 1 investment gt this by 0 _invsoil 1 production gt this by 0 _soil 1 There are so called shared fields which are used by several of the created model elements and there are specific fields which are used by only one of the elements Shared fields are name lifetime acqcost terrainand managementswitch and except for the later these are already known from the basic model elements Specific fields are marked with a gt surrounding the subele ment they belong to The subelement asset contains all fields for the network object Including perm which refers to the yield balance constraint of the crop The act and con fields are filled automatically by mpmasql and should not be given Subelements production and investment refer to fields and coefficients of the growing and invest ment activity that do not change with age Those coefficients that do change with age are included in the subelement dynamic gt Three fields are obligatory perennial_yield perennial_preharvest_cost and perennial_harvest_cost perennial_yield should contain the relative yield at a certain age as a share of the maximum yield that can be obtained in the best producing age Every other field is interpre
165. nteger programming matrices which are used to model several decisions in mpmas mpmasdist can be used to create agent populations based on statistical distribution functions and theoretical assumptions including random distribution of agricultural plots over study areas Figure 2 1 provides an overview of the modeling process using the MpmasQL toolbox The basic idea is to store any empirical information you gathered in the field or from secondary sources in a relational database e g MySQL in a structured and normalized form Spatial data should be processed and stored using GIS software and linked to the database e g the GIS maps could contain information about the spatial distribution of soil types but any further information on how the different soil types affect production should be stored in the database Often detailed information about all the individuals to be represented as agents in the model is not available In those cases mpmasdist can help you create artificial but representative agent populations using statistical information and heuristic rules Based on your theoretical and empirical knowledge about the processes and interactions relevant for your simulations you can then create a model design which you describe in three text files using the model design format required by mpmasql This model design defines the model structure and contains references to information in the database but does not contain the data itself Furthe
166. ntrol file FLAGS T16 4 3 4 Adaptation of production decisions after harvest Whenever a crop growth model is used the harvested yields and as a consequence the income obtained by the agent will most probably differ from the agents original plan As long as the farm household only sells the crops obtained MPMAS will simply correct the farm household s revenue using the yield obtained and the price information of the associated selling activity This simple approach only works as long as the farm household does not consume the produced crop itself or uses it as an input for another production process e g as fodder for animals or feed stock for a biogas plant In this case the original production plan will have to be revised once the production result is known e g in order to buy additional food or feed from the market If you are using the advanced consumption model this is part of the consumption decision in other cases you have to explicitly request a revised harvest decision by setting the corresponding entry in the model configuration to 1 HARVEST_DECISION 1 41 At the end of the season the farm household can of course not undo his planting decisions and therefore all cropping activities and all other activities that have to be considered irreversible at the end of the season have to be fixed at the values determined in pre season decision except the fallow activities in order to allow for rounding This is achieved by se
167. nts cash labor and machinery We still need to connect these to the production opportunities of the household Cash is used in MPMAS to invest Im into new assets which is discussed in the investments section below and to reflect the cash constraints a farm household may face during the season Farms have to pay a lot of inputs upfront for production activities phc and receive their revenue only at the end of the season so either they have enough liquidity to pay all inputs or they have to take credit sterd and pay interest If they have more cash than they need they can put it on the bank to receive interest for short term deposits stdep Since you expect to be able to receive at least the amount of cash you paid for inputs as a revenue at the end of the year you can use the same money for investments and pre financing of inputs You can of course make different assumptions here and change the model structure accordingly We thus have two cash balance equations 5 phe A j stdep sterd lt Neash 3 6 cj gt edm ACQm Im stdep lt Neash 3 7 20 Farm households cannot take unlimited credit One assumption may be that they can use the standing crop as a collateral and receive credit on the upfront input cost The credit limit restriction could be formulated and rearranged as follows sterd lt 5 phce Ao cj amp sterd S phes A j lt 0 c j The liquidity related model elements cannot re
168. nualized form of investment calculation used in the MPMAS investment decision The two share coefficients used in the formula have to be defined in the corresponding asset For example asset tractor 4 resale_share 0 9 resale_book_share 1 0 disinvest_completely O The resale_share determines which share of the time value of the asset the agent may recover by selling it Besides the objective function coefficient it directly affects the increase in cash caused by the selling The resale_book_share only affects the objective row and determines whether the agent fully considers the change in the balance sheet for his decision In some cases the asset might denote e g a stable place and the amount of the asset owned by an agent does not correspond to a number of single asset objects but rather to the size of one asset i e a stable In this case youo would typically want the agent to either sell the full asset the whole stable or nothing rather than only a few stable places This can be achieved by setting disinvest_completely attribute to one 62 Chapter 5 Testing decision models with mpmasq l and mqlmatrix While developing and calibrating your model you will often encounter situations where things do not work as expected In case you suspect the error to lie in the decision matrix you will need to have a look at the prepared matrix experiment again with some different coefficients and solve it outside of MP MAS Although you
169. oducer organi zation have to be included In our example it just consists of the corresponding sales activity and the symbolic object representing membership in the PO which is required for the agent to have the 54 option to use the PO marketing channel Note The table POs is just an auxiliary user table linking crop to PO number The harvest gt subelement also applies to the marketing stage class POCROPS activity sell_through_PO 4 name sell this instance type MASsell unit t orow table prices 3 this instance var STARTYEAR 1 1 05 orow_ foreach YEARS table prices 3 this instance var STARTYEAR 1 1 05 this instance _balance 1 1 harvest gt this instance _balance 1 this instance _PO_member 1 asset PO_membership name this instance PO membership div 0 symbolic 1 lifetime 1 acqcost 0 eqshare 1 irate var INTEREST_SHDEP con this instance _PO_member act this instance _PO_become_member multiplier 1000 innogrp never producer_organization gt membership table POs 2 this instance 7 constraint PO_member name Member in PO this instance type ability unit t F activity PO_become_member name Become member in this instance PO integ 1 ubound 0 4 11 3 Linking farm agents and producer organizations Finally farm agent activities and producer organization servic
170. of networks and a list of lower thresholds for each segment in the model configuration E g one network and the five standard segments would be implemented as follows 56 NETWORKS THRESHOLDS oll me o o N o BR O 0 5 0 84 4 12 2 Defining innovations Then you need to define your innovations respectively innovation groups An innovation in MPMAS is always tied to an investment asset The adoption of the innovation is actually modeled as an investment into this asset To make an asset an innovation you have to assign it to an innovation group This is done by setting the innogrp attribute of the asset If your innovation is actually represented by an asset anyway e g in the case of a new type of machinery you can directly work with this asset E g the following would make all machinery part of the innovation mechanization Of course most of the times you would probably use a table function to assign different types of machinery into different innovation groups class MACHINERY asset machinery_asset innogrp mechanization In other cases e g when the innovation is the access to a new market you have to introduce a symbolic access asset without any cost and infinite lifetime and also the corresponding invest ment activity and constraints All activities related to the innovation are then restricted by a positive requirement in the access constraint E g for an access to export markets which a
171. ofyear 1 LA AIDS Food category block 141 constraintby xc_foo_foodcat table foodcats 0 f name Food Category table foodcats 2 this by 0 type MASxc_foo_foodcat unit var CURRENCY consumption gt category this by 0 consumption gt xc_foo_coeff_expsi table foodcats 5 this by 0 consumption gt xc_foo_coeff_hh table foodcats 6 this by 0 consumption gt xc_foo_crossprice_ table foodcats 0 table crossprice 3 this by 0 this field 1 consumption gt budget_share table foodcats 7 this by 0 constraint xc_foo_constc name LA AIDS Constant type MASxc_foo_const unit var CURRENCY eqtype 3 constraint xc_foo_hhsizec name LA AIDS HHSize type MASxc_foo_hhsize unit var CURRENCY eqtype 3 constraint xc_foo_pricec name LA AIDS Price type MASxc_foo_price unit var CURRENCY eqtype 3 constraint xc_foo_fexc name LA AIDS Food expenditure type MASxc_foo_fexc unit var CURRENCY eqtype 3 constraintby xc_foo_lbound steps 1 count XC_FOO_FEXSEGS 1 1 name LA AIDS FEX Segment Lower Bound this by 0 type MASxc_foo_lbound unit var CURRENCY eqtype 1 constraintby xc_foo_ubound steps 2 count XC_FOO_FEXSEGS 1 name LA AIDS FEX Segment Upper Bound this by 0 type MASxc_foo_ubound unit var CURRENCY eqtype
172. old member category key career identifier ID of the career of this category probably_married 0 1 if the household member is married at the beginning of the simulation only if suitable partner available lowage integer lower age bound 118 upage integer upper age bound Table B 14 Structure of the HOUSEHOLD DYNAMICS table Column Type Description pop integer Population key career identifier The Career Identifier key upperyear integer The upper bound of the age segment the information is provided for key labgrp identifier Labour category the agent provides labour to in this age segment labprov number Amount of labour per year the agent provides within this age segment mortality fraction Probability of dying for every year within the age segment fertility fraction Probability of giving birth for every year within the age segment Additional columns for the advanced demography model p_marriage fraction p_leaving fraction p_retiring number priority_hhead number mincons number probability of finding a partner in case member has not got one yet probability of leaving the household with partner values between 0 and 1 indicate proba bility voluntary attempt to retire values above one indicate sure obligatory re tirement Retirement for normal house hold members always succeeds retire ment of household head requires con ditions to be met priority in selection procedure for new household head
173. omma separated list of mpmasa types MODIFYING modify row lt R gt lt attr gt lt new value gt sets attribute lt attr gt of row lt R gt to lt new value gt modify col lt C gt lt attr gt lt new value gt sets attribute lt attr gt of column lt C gt to lt new value gt modify rows lt R1 R2 gt lt attr gt lt new value gt sets attribute lt attr gt of rows lt R1 gt to lt R2 gt to lt new value gt modify cols lt C1 C2 gt lt attr gt lt new value gt sets attribute lt attr gt of column lt C1 gt to lt C2 gt to lt new value gt modify coef lt C gt lt R gt lt new value gt sets coefficient in column lt C gt and row lt R gt to lt new value gt OTHER OPTIONS set_risk_aversion lt value gt set risk aversion coefficient for evalua tion of quadratic part of objective val ues Note has no effect on current Q matrix denotes optional arguments 5 2 Formats of MP problems mqlmatrix can read mpmas input or standalone matrices created by mpmasql1 matrices saved during mpmas simulations automatically because the OSL failed solving it or matrices you requested to be saved by mpmas during simulation with the DBGMILPS entry in the mpmasq1 control file 5 2 1 MPMAS input format dat You can directly read in the mpmas matrix input file usually named lt scenarioname gt _MILP dat for inspection Solving such a matrix usually does not make sense as the RHS is empty and several
174. on mpmasql has been developed for GNU Linux operating systems You may have to install certain additional software Database perl interpreter and certain Perl modules You also need a working internet connection so missing Perl modules can be installed during the installation OS GNU Linux tested on Ubuntu 10 04 12 04 perl The use of mpmasql requires the installation of a perl interpreter on your computer Most Linux distributions come with one included mpmasql 2 52 was tested under perl v5 10 1 Ubuntu 10 04 Non standard Perl modules will be installed by the mpmasa1 installation script Install mpmasq1 Installing the main program requires a working internet connection 1 Download and extract mpmasgq zip 2 Open a terminal and change into the directory mpmasql_release_252 3 If you do not want to use mpmasdist run sudo install_mpmasql 4 If you want to use mpmasdist run sudo install_mpmasql x This installs also the addi tional Perl modules needed for mpmasdist You can also skip this now and run it later whenever you decide to use mpmasdist Installing OSL solver library The mpmasq l installation script will automatically install the mpmas executable in usr local bin The mpmas executable requires the IBM OSL solver library to run and this has to be installed by the user Please consult i490d uni hohenheim de if you have problems installing this library 1 Copy v3_os11ib_linux tar to your home folder and extract
175. on would be expanded as follows for a the wheat instance plough_capacity table work 3 wheat plough harrow_capacity table work 3 wheat harrow seeder_capacity table work 3 wheat seeder tractor_capacity table work 3 wheat tractor Whereas the expansion for maize would look like this plough_capacity table work 3 maize plough harrow_capacity table work 3 maize harrow seeder_capacity table work 3 maize seeder cultivator_capacity table work 3 maize cultivator tractor_capacity table work 3 maize tractor 3 6 5 Investments Of course it should also be possible for households to invest into new or additional machinery In MPMAS investment and production decisions are separated into two steps The production decision 26 is always taken for the coming cropping season while an investment decision needs to take a longer perspective into account it is taken with an average year in the near future in mind This becomes especially important when you have assets whose characteristics change over time like perennial crops E g for perennial crops the average yield to be expected over the next years may differ considerably from this season s especially in the first year when the expected yield is often still zero Investing into an asset is an activity in the LP decision problem Both investment and production a
176. one of these constraints but we need the value on the right hand side of two equations that is why we use a transfer activity liqtrans Equation 3 6 is marked as MASong equa tion 3 7 is marked as MASly1 and equation 3 9 as MASscl The short term credit and deposit ac tivities are marked as types MASscred and MASdep The two variables INTEREST_SHCRD and INTEREST_SHDEP are MPMAS parameters we have to include into the model data file e g MPMAS PARAMETERS INTEREST_SHCRD 0 1 INTEREST_SHDEP 0 02 Then we still need to specify the coefficients for the pre harvest liquidity and short term credit limit equations to the definition of the production activities We simply assume that 80 of variable cost occur before the crop is harvested class CROPS 4 Hactivityby production_on_soil foreach SOILS 4 MAS_ongliq 0 8 table variable_costs 2 this instance MAS_stcredit 0 8 table variable_costs 2 this instance 3 6 3 Labor use Labor is mainly an issue in peak seasons e g during harvest times Household members can only work a certain amount of time during the maybe 8 days where wheat can be harvested or the 7 days where barley can be harvested respectively the 20 days were maize can be harvested Assuming these three harvest periods do not overlap and neglecting all other labor peaks which there certainly are we need to incorporate three equations of the form Y wdhe Ac j lt m OL
177. ontiguous cells starting with the cell found using a random walk to neighbouring suitable and unused cells Update the property map to record ownership of these cells 8 If after that no cell is left in the polygon delete the polygon from the polygon list If cells are left check whether the polygon has been split into two polygons Adapt the polygon size in the list and add a new polygon to the list if necessary 9 If the agent has more area to be distributed re append it to the end of the agent queue 10 The algorithm stops if there is no agent left in the queue or with a warning when no suitable cells are left in the map Implementation in the control file The mpmasdist distribution type for plot distribution is maps_assign_plots It expects that a farmstead map already exists in memory This can either be created with the maps_assign_farmstead distribution type or loaded from file in the MAPS section of the control file assigning it the reserved name FARMSTEADMAP Already existing property maps in memory are updated allowing the user to split plot distribution over several steps An existing property map can be loaded from file in the MAPS section of the control file assigning it the reserved name PROPERT YMAP STEP 30 DESCRIPTION Assign_plots TYPE maps_assign_plots MAP land AGENTS SUITABLE black_soil 112 114 156 clay_soil 202 297 231 sandy_soil 14 34 89 70 AVGPLOT
178. orithm loops over a list of three sectors For each sector the number of agents to be created is read from column for of the table sectors cf section C 4 for the use of the table function Agent identifiers have five digits with the first two indicating the sector and the last three indicating the running number of the agent within the sector 6 2 2 Removing agents Individual agents can be dropped from the agent population in the memory at the end of a distribution step using the DROP_IF field which takes a condition to determine which agents should be dropped This is done after all loops and before any output is saved For example the following code would drop all agents with an agent ID larger or equal to 4000 at the end of step 30 and all agents whose land attribute is smaller than 10 at the end of step 40 STEP 30 DROP_IF this agent id gt 4000 73 STEP 40 DROP_IF this agent land lt 10 6 2 3 Saving agent populations Agents populations can be saved in two formats i as a tab separated table of agent attributes in human readable text files by using the AGENTS keyword in the OUTPUT section or ii as a binary file which allows to reload the agent population into mpmasdist at a later point of time by using the STORE_AGENTS keyword in the OUTPUT section The following example code would save the agent population in human readable format in the file agents tab and in binary format in the file
179. ose activities marked as no labor activities in the crop growth section should not be fixed otherwise the MILP might become infeasible Any other change of coefficients between production and consumption stage can be indicated using the harvest gt subelement E g if you used security equivalents to calibrate your model these should be set to one for the consumption stage as shown below class CROPS 4 eri production_on_soil foreach SOILS 4 consfix 1 Hactivity sell 4 this instance _balance 1 2 harvest gt this instance _balance 1 45 Data file To make the MASCONSUMPTION class work you should include the following entry in the USER VARIABLES section of your data file It just sets the name of the monetary unit used in the definition of MASCONSUMPTION Under INSTANCES you should include one instance CONS for the class MASCONSUMPTION USER VARIABLES CURRENCY lt currency name gt UP_CREDIT_DEFAULT lt utility penalty for defaulting on credits gt MAX_DEFAULT lt maximum credit that can be defaulted gt INSTANCES MASCONSUMPTION CONS Most work will however go into providing data for the tables used in MASCONSUMPTION in the USER TABLES section These tables are described in Tab 4 3 You can of course adapt naming of tables and columns to the structure of your database Unless you want to adapt the MASCON SUMPTION class itself you are of course free to do so if you dare you should however
180. ost number total cost of the projects over all partic ipants subsidized_ share share Share that has been subsidized INFPROJPARTICIPANTS project_id identifier Project Identifier farmstead_id integer Farmstead id of participant catchment_id integer Catchment Id of Farmstead sector_id integer Sector Id of Farmstead Table B 17 Structure of the INNOVATIONS table Column Type Description network integer network index counting from 0 key segment integer segment index counting from 0 key innogrp identifier innovation group identifier key available integer model period the networkobjects of this innovation group become available to the agents of this segment exact avail ability depends on COMTYPE accessible 0 1 whether the networkobjects of this in novation group are accessible to the agents of this segment at simulation start or not Table B 18 Structure of the INVESTMENT HORIZON table Column pop Type integer Description Population key 120 parameter parameter setting any of the INVEST setting number Table B 19 MENT_HORIZON_ parameters population specific value Structure of the INVEST MENT_HORIZON_CONSTRAINTS table Column Type Description pop integer minlife integer constraint identifier rhsvalue number Population key lower bound of remaining lifetime seg ment identifier of corresponding constraint value to be entered on the right hand side of the constraint
181. physical investment limit and O for the opportunity cost 4 2 Livestock The livestock model is a pretty detailed individual based representation of livestock production includ ing simulation of offspring and aging and use of livestock as a liquidity reserve which is especially useful to represent small holder decision making in developing countries For other cases you would probably prefer an aggregate herd based representation which you should be able to implement with the basic MPMAS assets The livestock is activated by setting the LIVESTOCK_MODEL entry under SUBMODELS in the model configuration to 1 The implementation in mpmasql is similar to perennial objects There is a compound livestock ele ment livestock resp livestockby which is automatically transformed into a number of model elements an investment activity a maintenance activity a sell at start of period and a sell at end of period activity for each age an overall endowment constraint and one for each age a disinvestment sell all constraint and a livestockfile entry All of these activities are doubled because each is gen erated once for each sex of the livestock type You can differentiate field and value definitions by sex using the special variable this sex e g females should produce offspring while males should not Like perennials livestock elements contain shared fields which are used by several of the sub elements and there are specific fiel
182. prefer to transform the raw MPMAS output to more conveniently formatted text files including your user defined variables If you set the R_TO_TAB entry in the control file to 1 you mpmasq1 will create an R import script that saves the same setup you would find in your R workspace as tab separated text files in the subdirectory R data tab You run it the same way as described above By default the RData output is also created but you can omit this by setting the control file entry R_TO_WORKSPACE to zero 33 Chapter 4 Model design with mpmasql MPMAS submodels and features The model setup described in the previous section is a relatively simple one it does not contain agent agent interactions no real interactions with the environment and only very simple kinds of assets MPMAS contains complex features for all of these and in this section the ones implemented with mpmasql are presented 4 1 Perennial crops Perennial crops are crops which once planted occupy land for a certain lifespan longer than a year Yields production costs and input requirements may change with age Planting them is an investment decision Within MPMAS perennial crops are represented by several model elements As perennial crops are investments there has to be an asset an investment activity and an endowment constraint As they are production processes there is a growing activity and because the same perennial plant can be managed in different ways there a
183. provide columns with the indicated content in the given order 46 Table 4 3 TABLES for MASCONSUMPTION Column Description food category id foodcats Id for the food category name of of food category Name of the food category unit of food category Unit of the food category xc_foo_const xc_foo_coeff_expsi xc_foo_coeff_hh budget_share Constant term in the LA AIDS expendi ture function for this food category Coefficient of expenditure price index in the LA AIDS expenditure function for this food category Coefficient of household size in the LA AIDS expenditure function for this food category observed budget share of the food cat egory food category 1 id food category 2 id crossprice id of first food category id of second food category coefficient Coefficient of price of second category in the LA AIDS expenditure function for this food category products _food_categories product id id of product food category id id of food category the product belongs to food category id year price food_category_prices Id for the food category model year price in given model year food_category_id food_category_nutrients id of food category hh_nutrient id of nutrient quantity nutrient content products_nutrients product_id id of food category hh_nutrient id of nutrient quantity nutrient content utility_penalty hh_nutrient id of nutrient penalty objective function penalty for defi
184. ptional optional optional optional required for advanced consumption required for advanced consumption required for advanced consumption required for advanced consumption 9999 999999999 9999 999999999 9999 999999999 XC_SAV_COEF_CONSTAdvanced consumption model Esti mated constant in the savings function XC_FNF_COEF_CONSTAdvanced consumption model Esti XC_FNF_COEF_EXP XC_FNF_COEF_HH XC_FNF_EXPSEGS XC_FOO_FEXSEGS mated constant in the food non food expenditure function Advanced consumption model Esti mated coefficient of total expenditure in the food non food expenditure function Advanced consumption model Esti mated coefficient of total expenditure in the food non food expenditure function Advanced consumption model List with the width of the total expenditure segments in the food non food expen diture function Advanced consumption model List with the width of the food expenditure segments in the food category expen diture function B 3 3 MPMAS TABLES In the MPMAS TABLES section you specify the data sources for all tables that have a fixed format required by mpmasq1 The syntax for MPMAS table definitions is tablename tabletype 4 span several lines required for advanced consumption required for advanced consumption required for advanced consumption required for advanced consumption required for advanced consumption
185. qur 2203 q1201 2 q911122 C1 X1 C2 2 4 6 ls e E 31171 aa 7 1272 5 92 q21 01 2 0101 C222 4 7 So as can be seen the diagonal elements of the matrix qi and q22 are twice the coefficient of the square of x respectively x2 The off diagonal elements of Q represent the coefficients of the product oftwo variables and those associated to the same two variables should be equal hence the symmetry of the matrix In case all the elements of Q related to a solution variable are zero this variable has no quadratic component and enters the solution function only linearly For simplification in MPMAS only those variables with at least one non zero element in Q need to be marked as quadratic and considered in the formulation of Q Implementation of a quadratic programming problem in mpmasq includes two steps First all quadratic activities have to be marked as such using the quadratic attribute Second the subelement quadratic gt is used to specify the elements of the Q matrix of the row first index associated with the activity The field names of the subelement refer to the columns of the Q matrix using activity identifiers The 49 actual order of columns and rows is automatically determined by mpmasql according to the order of activities in the decision matrix Remember that the element of Q referring to the multiplication of the activity with itself e g for the ac tivity maize_sel1 the value for tquadratic gt
186. r you create a control file instructing mpmasq1 which model design and database to use which scenarios to create and how to adapt the model for different scenarios You can then run mpmasql and it will create the input files for mpmas model description files and importing scripts for statistical software Whenever you add or update something in your database that is referenced in the model design this will automatically be reflected in the mpmas input the next time you run mpmasql because the model design only contains references to the data and not the data itself Spatial input for mpmas can be created directly with GIS software After you ran mpmas you can use the importing scripts created by mpmasq1 to import the mpmas output into a statistical software package for analysis currently Stata and R are supported Thttp en wikipedia org wiki Database_normalization Empirical data collection control file dst Model design configuration cfg structure cll data var Database MySQL MPMAS input maps ASCII txt MPMAS input files dat Commented input files txt Model info txt do R MPMAS debug files ASCII mip mtx MPMAS output files ASCII out Figure 2 1 Overview of the modeling process with MPMAS using the MpmasMySQL setup Chapter 3 Model design with mpmasq l A basic MPMAS model mpmasql prepares mpmas input files u
187. r of random water rights to be allocated 0 Table B 23 Structure of the SEEDS table Column Type Description gisid integer identifier of the sector key seed integer random seed Table B 24 Structure of the SEGBOUNDS table Column Type Description network integer network index counting from 0 segment integer segment index counting from 0 soil integer soil index counting from zero physbound number physical bound for investments on that soil type oppcost number estimated opportunity cost for invest ments on that soil type Table B 25 Structure of the SEGINFO table Column Type Description network integer network index counting from 0 segment integer segment index counting from 0 variable name of MP MAS parameter to set value segment specific setting Table B 26 Structure of the STANDARD_LAND_RENTS table Column Type Description network integer network index counting from 0 segment integer segment index counting from 0 soil integer soil index counting from zero rent number price for renting out selling of land if agent has shortage of liquidity when land market and perennial model are not used Table B 27 Structure of the SUCCESSION CONTROL table Column Type Description 122 pop integer Population key parameter parameter setting any of the SUCCES SION_CONTROL_ parameters setting number population specific value 123 B 3 4 USER TABLES In the USER TABLES
188. r scenarios MFL expressions can be used at many different locations in the model design files A full reference of all the functions is given in section C We now still have to tell mpmasq1 which instances are part of the MACHINERY class and provide the data that we referred to in the class definition First we create the instance list in the INSTANCES section of the model data file INSTANCES MACHINERY tractor plough seeder In the example we have included three instances into the model by including their identifiers into the instance list for the machinery class An identifier must consist only of letters a z A Z digits and underscores The identifier is used to create a unique identifier for the assets which consist of the instance identifier an underscore and the identifier you used in the element definition i e in our case the model will contain assets of type tractor _machinery _asset plough _machinery _asset and seeder _machinery _asset Second we have to provide the table machinery which contains the data on lifetime and acqui sition cost This is a user defined table because contrary to the MPMAS tables the format is not predefined by MPMAS The most important thing you have to define is how many key columns your table contains Key columns are used to identify the rows in your table This key can consists of the content of one or several columns which have to be the first columns in the table In our case
189. rces e g labor This is important because in order to create a map of cropping activities MPMAS has to round the crop areas to full integers in order to distribute them over the map cells To avoid any conflicts with resource constraints MPMAS will only round towards zero and allocate the remaining area to a fallow activity which should not require any resources class FALLOW Hactivityby on_soil foreach SOILS 4 external_crop_growth gt link table xcwlink 3 this instance this by 0 external_crop_growth gt soil this by 0 external_crop_growth gt crop_type 3 external_crop_growth gt priority 1 4 3 3 Exogenous yield time series Instead of an external crop growth model you can also provide a time series of yields for every period and cropping activity The external crop growth interface looks the same as in the previous section you only have to add a value for each product and simulation period as shown below class CROPS 4 Hactivityby production_on_soil foreach SOILS 4 external_crop_growth gt yield_producti_ foreach YEARS table yield_time_series 4 this instance this by 1 this field 1 external_crop_growth gt yield_product2_ foreach YEARS 0 You then have to run MPMAS with the flag T 16 to make it read the yields from the input files instead of waiting for input from the crop growth model You can have mpmasq1 do that for you by including T16 into the FLAGS list in the co
190. re based on the same decision matrix except that in the investment decision the coefficients that allow an investment are added to the investment activities These are the coefficient in the capacity constraint of the investment the objective row containing the annualized cost of the investment debt service and linear de preciation on equity capital the cash demand in the year of investment the self financed part of the purchase price the average cash demand for the next years the fixed equity the expansion of the credit limit because the self financed part of the investment can be used as a collateral for short term credits the fixed equity In the production decision these coefficients are zero such that the activity is ignored by the house hold In the model structure file these coefficients should be empty The corresponding values are cal culated automatically by MPMAS using the long term interest rate parameters INTEREST_LONGCRD INTEREST_SHDEP and the lifetime acqcost and multiplier fields of the asset In case you want to test the investment decision problem in standalone mode i e outside of MPMAS see chapter 5 you will want to have the coefficients that MPMAS calculates in the matrix For this purpose mpmasql provides the function ifalone The first argument to this function is the value used when creating a standalone matrix the second the one used when preparing MPMAS input files In this
191. re switching activities between different management practices Further as yields and input requirements change with age there is a perennial file entry which supplies the respective values for each age Every perennial is equal in this respect and thus perennials of course in principle form a decision class However mpmasql saves you the work of specifying each model element individually by pro viding a special type of element the perennial You can activate the perennial crops model by setting the PERMCROP_MODEL entry under SUB MODELS in the configuration to 1 Perennial elements are specified in the model structure file in a similar way as definitions for basic model elements activities constraints assets As usual there is also a perennialby element Let s look at an example class PERENNIALS perennialby trees foreach SOILS f shared fields name table perennials 0 this instance on soil this by 0 34 lifetime table perennials 4 this instance acqcost table perennials 5 this instance terrain table perennials 7 this instance managementswitch table perennial_switching 2 this instance _trees specific fields asset gt perm table perennials 3 this instance _balance asset gt innogrp default asset gt landreq 1 dynamic gt perennial_yield table perennial_yields 3 this instance this dyn dynamic gt pere
192. ributed over the map and in a second step the plots are allocated more or less closely around the farmsteads In both steps the distribution is based on an existing suitability map that provides the map extents and whose cell values indicates which cells are suitable for farmsteads respectively certain types of plots Distributing farmsteads The distribution type for distributing farmsteads is maps_assign_farmstead It expects only two fields The MAP field indicates which of the maps loaded in the MAPS section of the control file should serve as the basis for the distribution and the SUITABLE field that indicates the list of cell values suitable for farmsteads STEP 20 DESCRIPTION Assign farmsteads TYPE maps_assign_farmstead AGENTS 4 MAP land SUITABLE 5 9 OUTPUT FARMSTEADMAP gis CatchMap00Farm txt Note each statement needs to go on one line line breaks in the example only for readability in this manual If a farmstead map already exists in memory from a previous step it is going to be updated allowing the user to split farmstead distribution over several steps 87 An ON_ASSIGN section can be added to update agent attributes when the farmstead is set e g one could record the soil type at the location of the farmstead using the mapcell function and the special agent attributes farm_x and farm_y from a user loaded map called soil_in_studyarea ON_ASSIGN agent soil_
193. rices 3 this instance var STARTYEAR orow_ foreach YEARS table prices 3 this instance this field 1 this instance balance_future 1 constraint balance_future name Future balance of this instance type product_balance unit kg constraint balance name Balance of this instance type product_balance unit kg activity sell name Sell table perennials 2 this instance type MASsell orow table prices 3 this instance var STARTYEAR orow_ foreach YEARS table prices 3 this instance this field 1 tthis instance _balance 1 Perennials block plots These plots cannot be used for other crops and especially you cannot plant other perennial crops on them To make sure this does not happen a special constraint of type MASinv has to be added to the MILP for each soil MPMAS will enter the soil that has not been blocked by perennials on the RHS of these constraints during the investment stage Each perennial investment activity should have a coefficient of 1 in the respective constraint class SOILS 36 constraint invsoil 4 name Investments on terrain this instance unit ha type MASinv Often perennial crops have a long gestation period in the first years during which they do not yet give full yield they produce a negative cash flow To make sure the agent does not go bankrupt because the cas
194. roduction or investment SHDW_FIRST Identifier of first constraint for which optional shadow prices are to be calculated SHDW_NUM Number of constraints for which optional shadow prices are to be calculated B 3 Model data file The data file has six sections GLOBALS Here you can define global variables and lists which you can use in mpmasq1 function language expressions in all of the model design files except in other globals defined above a specific global MPMAS PARAMETERS In this section parameters for the dynamics of the MP MAS model and its submodules are set You can use mpmasql function language to do so referring only to global variables MPMAS TABLES In this section you specify database queries for MP MAS parameters or exoge nous variables expected by mpmasq in a pre defined table format You can use mpmasq 1 function language to do so referring only to global variables USER TABLES In this section you can define your own tables and the database queries to fill them which you can then refer to in the definition of the model structure cll the user variables and the instance lists You can use mpmasq1 function language to define the database queries referring only to global variables configuration entries and MP MAS parameters USER VARIABLES In this section you can define and set your own variables and lists which you can then refer to in the definition of the model structure cll and the instance
195. rvations could be distributed in a distribute_asset_list step e g due to unfulfilled con straints or less agents than observations with exclusive assignments mpmasdist will inform the user printing a message on the screen and add the unassigned observations to a special list If desired the user can then make a second attempt to distribute these observations in a subsequent step e g relaxing constraints or assigning to a different group of agents This is achieved by using the keyword NOTASSIGNED as observation list OBSERVATIONS NOTASSIGNED 4 Alternatively the list can be stored at the end of a step using STORE_NOTASSIGNED lt filename gt in the OUTPUT section and restored at a later point of time using RESTORE lt filename gt as observations list Saving in human readable format is also possible using the NOTASSIGNED lt filename gt keyword in the OUTPUT section 2Note By default the algorithm uses a penalty of plus infinity as pseudo log likelihood for agent observation combinations with zero likelihood This can be adapted assigning a USE_ZEROL_PENALTY field of the distribution step so allowing a balancing between non use and violations of zero likelihoods 82 6 4 2 Assignment following a probability distribution To assign assets attributes or household members by Monte Carlo sampling from a distribution func tion mpmasdist offers the assign_by_cdf distribution type Specification of the distribution fun
196. s table needs two keys to uniquely identify rows Also tractors are not mentioned but we can conclude that for every work you always need a tractor so the tractor demand of a crop production activity is the sum of all frequencies of the different works We could add additional lines to the table but then we would always have to be sure to update it manually whenever we update the table because we learned farmers in our study area rather use the harrow twice for wheat and not once So rather we add the lines for tractor use with a UNION statement while importing the table into mpmasq work sql 2 4 SELECT crop machinery frequency FROM tbl_work UNION SELECT crop tractor SUM frequency FROM tbl_work GROUP BY crop We already mentioned that a table function call with an empty key array as third argument returns all different entries in the first column This behavior is extended to incomplete key arrays too To assign the capacity requirement to our production activities we used the following code table work 0 this instance _capacity table work 3 this instance this field 1 The field name definition contains a table function call that contains less keys that are actually needed to uniquely identify one row In this case the function returns a list of all different values of the sec ond column where the first column matches they key provided In other words in the imaginary intermediate step the expressi
197. s may define variables and lists for use in the other section using the MpmasQL Function Language similar to the use in mpmasq VARIABLES SEED 123 SOILS steps 0 4 1 The values of these variables may be overridden when running mpmasdist by using the command line option set see also section A 3 6 1 3 TABLES The tables section has the same same syntax as the USER TABLES section in mpmasql cf sec tion 3 5 4 For example the code below defines a table land_cdf with two key columns and fills it with data retrieved from the database using the shown query TABLES land_cdf sql 2 4 SELECT soil_type upper_bound quantity FROM soil_distribution 6 1 4 MAPS The MAPS section is used to load maps in ESRI ASCII format The code below for example loads the map contained in the file study_area_land_use txt and makes it available for further use under the name landuse MAPS landuse study_area_land_use txt 6 1 5 CONTROL The CONTROL subsection can be used to control which of the distribution steps defined under DIS TRIBUTION will actually be performed The keyword INCLUDE can be used to number the steps which should be performed Alternatively the keyword EXCLUDE to let mpmasdist skip some steps If both keywords are used at the same time only those steps which are listed under INCLUDE but not under EXCLUDE are performed e g 11 11 13 14 below CONTROL INCLUDE 10 11 12 13 14
198. s of agents into the smallest rectangle possible It groups all plots of all agent sequentially and breaks them up into as many rows as required to fit the input into a map of a user defined North South extension STEP 40 DESCRIPTION Make artificial property farmstead and soil maps TYPE maps_artificial AGENTS SOILCODES black_soil 0 clay_soil 1 sandy_soil 2 86 MAPHEIGTH 10 CELLSIZE 100 OUTPUT FARMSTEADMAP gis CatchMap00Farm txt PROPERTYMAP gis CatchMap00Prop txt SOTLMAP gis CatchMap00Soil txt Note each statement needs to go on one line line breaks in the example only for readability in this manual The SOILCODES section defines which attributes of the agents shall be transformed to plots and by which code these shall be represented in the map mpmasdist rounds the values contained in the attributes to full integers So for example an agent whose black_soil attribute contains the value 18 3 would receive 18 cells with code 0 in the map The MAPHEIGTH field defines the North South extension of the map in cells and the CELLSIZE field defines the sidelegnth of the cell in meters The keywords FARMSTEADMAP PROPERTYMAP and SOILMAP tell mpmasdist to save the cor responding map in the indicated file 6 5 2 More realistic maps The more sophisticated distribution algorithm of mpmasdist requires two distribution steps In the first step the farmsteads of the agents are dist
199. section you can define tables for data you want to refer to in the part of the model structure which you define yourself As the table format is not predefined you have to specify the number of columns mpmasq1 should treat as key columns The syntax for user table definitions is tablename tabletype number of key columns tablesource MFL expression that can span several lines The table type can be either sql or ascii For tables of types sql the expression in the curly brackets should result in an SQL SELECT statement that is being send to the database specified in the control file and results in a table of the required format E g yields sql 3 SELECT crop_id soil_id intensity quantity FROM example_db tbl_yields WHERE weather var WEATHERSCEN For tables of type ascii the expression in the curly brackets should result in a filename of a text file with values in tab separated format experimental E g yields ascii 3 data dry_year_yields txt B 3 5 USER VARIABLES In the USER VARIABLES section you define your own variables and lists which you can then use the model strcuture file and the INSTANCES section of the model data file The definition syntax is similar to the definition of configuration and MPMAS parameters and global variables MFL expressions can refer to global variables configuration parameters MPMAS parameters and user defined tables lt variablename gt lt value or list
200. sing data stored in a database and a model design described in three text files The model configuration file cfg the model structure file cll and the model data file var Despite its name the model data file does not contain the actual data except for some simple parameters but instructs mpmasq1 which data to use from the database A fourth text file the control file ini tells mpmasq1 which model design files and which database to use where to write its output and which scenarios to create Note The files which are described in this chapter are contained in the mpmasql_tutorial_files folder of mpmasgq zip In the subfolder ab you find the backup of the corresponding mysql database You can load this to your server by first creating the corresponding schema example_db on the server and then run mysql h hostname u username p example_db lt create_mpmasql_example_db sql in a terminal 3 1 Folder structure It is convenient to keep all files for a model application in one folder The following subfolder structure is suggested but can be adapted according to your own needs if you adapt mpmasq1 files and mpmas command line options lt modelversion gt cfg gt mpmasql model design files input dat gt input files for MPMAS gis gt input maps for MPMAS out gt MPMAS writes output here test gt MPMAS writes debugging info here xlsInput gt commented input files The mpmasal control file should
201. ster ID catchment integer Catchment agent_id integer MP MAS internal agent index sec integer MP MAS internal sector id not gis_id numplots integer number of plots Table B 6 Structure of the ASSET _CDF table Column Type Description pop integer Population ID key clu integer Cluster ID key asset identifier Identifier of networkobject key upbound number 0 100 Upper bound of CDF segment key value number number of members to assign for this CDF segment Table B 7 Structure of the ASSET _ ENDOWMENTS table Column Type Description farmstead_id integer GIS Id of the farm key asset identifier Identifier of networkobject key value number endowment Table B 8 Structure of CropWat tables Column Type Description CROPWAT_PRECIPEXPECT gisid identifier Gis ID of sector month integer calendar month 1 12 precipitation number volume CROPWAT_PRECIPACTUAL gisid identifier Gis ID of sector year integer year of flow month integer calendar month 1 12 precipitation number volume CROPWAT_EVAPOEXPECT gisid identifier Gis ID of sector month integer calendar month 1 12 evapotranspiration number volume 116 gisid year month evapotranspiration CROPWAT_EVAPOACTUAL identifier Gis ID of sector integer year of flow integer calendar month 1 12 number volume Table B 9 Structure of EDIC tables Column Type Description EDICROUTING from_gisid integer gisid of sector where flow origina
202. stical software package mpmasql automatically generates import scripts for the two statistical software packages stata and R The R script can also be used to transform the data into more conveniently formatted tab separated text files which can then be imported into your database spreadsheet software or any statistical software package of your choice 3 9 1 Defining output variables The MPMAS output contains for each agent and simulation period among others the updated solu tion and the right and left hand side capacities of the last decision model solved i e the production plan as well as a number of performance indicators e g income cash flow equity Especially in large decision models many variables e g transfer activities will not really be of interest to you Further often the variable of interest is split over several activities e g to get the total area grown with a certain crop you may have to sum over all the different activities representing the different combinations of terrain types and management options associated to that crop The 31 importing scripts can automatically do that for you if you indicate to which aggregate variable an activity belongs This is done using user defined fields which are marked with resultgroup gt E g in our exam ple the following would give you three result variables for each agent crop_wheat crop_maize and crop_barley each containing the total area grown with the respe
203. sts or field definitions as the structure of the MILP needs to be the same as usually It also will not work in asset definitions 4 11 Producer organizations Producer organizations can for example be marketing cooperatives of small holders that collect the produce of their members process store and sell it and distribute their profit among members The following examples are given in terms of such marketing organizations however also other types of organizations can be modeled using MPMAS producer organizations Agents can be members in several producer organizations and each producer organization may offer various services to its members Note Currently producer organizations cannot be used in combination with fragemented markets If the producer organization feature is activated agents solve a marketing decision problem after crop yields have been determined deciding how much of their harvest they want to market through their producer organization After that the producer organizations solve their own decision problem determining what to do with the collected harvest and determining their profit After that the profit is redistributed among its members Only after that farm agents then take their consumption 4 4 2 or harvest decision 4 5 4 11 1 The producer organization Producer organizations are activiated by including a PRODUCER_ORGANIZATIONS table into the MP MAS TABLES section of the data file mpmasqlwill automatica
204. t for the meat of the animal and whose value definition should provide the liveweight of the animal at each age dyn_offspring should contain one field whose field definition should contain the identifier of the bal ance constraint of the offspring and the value definition should result in the number of offspring produced by an individual of this livestock type sex and age dyn_sales should contain one field per marketable product e g milk wool that is produced by an individual of the respective livestock type sex and age The field definition should contain the identifier of the balance constraint of the product and the value the amount produced dyn_internal should contain one field per internal consumable used or produced e g manure feed that is produced by an individual of the respective livestock type sex and age The field definition should contain the identifier of the balance constraint of the consumable and the value the amount produced positive value or consumed negative value dyn_liquidityshould contain one field whose field definition should contain the identifier of a liq uidity constraint usually MAS_ongliq and whose value definition should indicate the required liquidity dyn_land may contain as many fields as you have soil types in your model though usually less The field definition should contain the identifier of a soil constraint and the value definition should indicate the required amount dyn_labor ma
205. t quotes are allowed as long as they consist only of letters of the English alphabet digits and underscores If they include spaces or punctuation they have to be included in double quotes In general numbers can also be treated as strings but strings not necessarily as numbers C 2 Operators Numerical operators evaluate to what you would expect 1 1 result in 2 and 274 in 16 Logical and comparison operators result in 1 whenever for true or O for false Logical operators accept any value unequal to zero or an empty value as true Logical operators are short circuit i e if the condition left of an evaluates to true the right hand condition is not evaluated any more and the result is true likewise if the condition on the left of an amp amp is false the right hand condition is not evaluated and the result is false The operator forms one string out of two 146 Table C 1 Operators Strings concatenation optional Simple arithmetics addition subtraction multiplication division A exponentiation Numerical comparison equal not equal gt greater or equal lt smaller or equal gt greater than lt smaller than Logical amp amp AND OR NOT C 3 Arrays Arrays can be formed using square brackets and commas e g 1 2 3 wheat is a four element array with the first three natural numbers and the string wheat as its elements Arrays can also result from certain funct
206. ted as a coefficient for a constraint Value definitions for these fields can either result in a scalar then they will be constant over all ages for this specific instance or they can be a function that contain the placeholder this dyn for the age and result in different values for different values of this dyn Note that you do not have to specify a value for each age Missing values will be filled automatically by taking the value of the next higher age for which a value has been supplied So for example if your perennial crop produces a proportional yield of 0 in the first five years 0 5 in the next five years and 1 over the rest of its 25 years of use life it would be enough if the table perennial_yields in the above example would contain three entries for this instance 5 0 10 0 5 and 25 1 A value for the highest age has to be supplied however During simulation MPMAS will look into the dynamic element to select the value for the current age of the perennial plantation and enter it into the matrix Actually it does an area weighted average over all currently present age levels 35 Once grown the management applied to a perennial crop may sometimes be changed during the course of its life For each type of management a separate perennial object has to be introduced into the model because age specific yield or input requirements usually differ However the agent later does not have to cut down his plants and replant ne
207. tes asset_counter and unoccupied_soil from all agents 75 CLEAN asset_counter unoccupied_soil 6 3 3 Assigning assets and household members To assign something to the designated list of assets using the ASSIGN section which is provided by the different types of distribution algorithms The same is to with respect to designated household members which are assigned in the MEMBERS section The most straightforward of the algorithms is the fixed distribution algorithm which does nothing special and can for example be used to transform agent attributes into designated assets and members For example the following code would assign an asset named fruit_plantation to each agent which is sized according to the attribute of the same name but only if the size is greater than zero It similarly creates a designated household member for each corresponding attributes Finally the attributes are deleted and the assets and member lists are saved to files STEP 100 DESCRIPTION Transform attributes to assets TYPE fixed AGENTS ASSIGN if this agent fruit_plantation gt 0 fruit_plantation this agent fruit_plantation MEMBERS male female _hhmembers_aged_ steps 18 30 1 this agent this attribute 1 _hhmember_ this attribute 2 CLEAN male female _hhmembers_aged_ steps 18 30 1 fruit_plantation OUTPUT ASSIGNMENTS var outfolder agents_assets
208. tes to_gisid integer gisid of sector where flow arrives surface_coeff share surface flow coefficient subsurface_coeff subsurface flow coefficient EDICINFLOWEXPECT inflow_id identifier ID of inflow month integer calendar month 1 12 flow number volume of flow EDICINFLOWACTUAL inflow_id identifier ID of inflow year integer year of flow month integer calendar month 1 12 flow number volume of flow EDICPRECIPEXPECT gisid identifier Gis ID of sector month integer calendar month 1 12 precipitation number volume EDICPRECIPACTUAL gisid identifier Gis ID of sector year integer year of flow month integer calendar month 1 12 precipitation number volume EDICAGENTRIGHTS catchment_ integer Catchment ID 0 gisid identifier Gis ID of sector farmstead_id integer Farmstead Id as used in maps inflow_id identifier ID of Inflow share_in_sector_flows share Agent s share of sector s share of inflow EDICSECTORRIGHTS gisid identifier Gis ID of sector inflow_id identifier ID of Inflow water_right_share share Sector share to inflow max_flow_capacity number Maximum flow capacity of canals in sector with respect to this inflow irrig_id irrig_ txt irrig_code night_sh evapo_sh surface_sh subsurface_sh EDICIRRIGMETHODS integer ID of irrigation technology string Name of irrigation technology string MP MAS Code of Irrigation technology share Loss through night time runoff share evapotransp
209. three columns scenario variable value Column ordering is significant column naming is not The first two fields serve as key thus if the same combination of scenario and variable appears several times only the last entry is used Scenario names have to follow the identifier naming rules A Z a z 0 9 _ mpmasql will automatically find out what kind of variable is referred to so please in general do not user parameter names if you define your own variables In the example Tab 3 15 the user defined variable WAGE_PER_DAY would be set to 140 in Sce nario scent and to 80 in Scenario scen2 The MPMAS parameter SCONEXTRA would be set to 0 6 in Scenario scen2 while in Scenario scen3 the user defined list LABPERIODS would be replaced by the list retrieved from a database according to the specified SQL Statement Variables not listed for a scenario simply remain the same as in the baseline Table 3 15 Sample SCENDEF table scenario variable value scen1 EQSH 0 2 scen2 EQSH 0 02 scen2 SCONEXTRA 0 6 scen3 LABPERIODS sqi SELECT DISTINCT Class2 FROM labperiods 30 The second step is to tell mpmasq1 which scenarios to create by assigning a list of scenario identifiers to the control file entry SCENLIST If you include a scenario in this list that does not have any entry in the SCENDEF table this will simply be equal to the original settings of your model configuration files E g ass
210. time and usually the price they will be able to sell their crop for at the end of the season is not known to the household while making the production plan at the beginning of the year The actual price households receive in a specific year is given using fields that have the format orow_ lt year gt SO e g orow_2012 contains the actual price for 2012 The prices used by the households for planning differ and depend on your choice of price expectation submodel which will be discussed in the next chapter In our case we spare ourselves the work of typing each year by using the foreach function referring to the user defined variable YEARS This leads us to an important feature You can also use MFL functions in field names and whenever you use a function that results in a list instead of one field a whole list of field is created So if the list YEARS contains all years from 2010 to 2030 we can create the fields orow_2010 orow_2011 orow_2012 and thus supply the prices for all years using just one line of code The list YEARS has to be defined in the USER VARIABLES section of the model data file We can use the step function to include all years of our simulation E g USER VARIABLES YEARS steps var STARTYEAR var ENDYEAR 1 table The orow fields receive their values using a table function We already introduced the table function above but we have not discussed table functions with more than one key The table
211. tion integer required ENDYEAR End year of simulation integer required 5 STARTMONTH Start month of simulation integer required ENDMONTH End month of simulation integer required STARTDAY Start day of simulation integer required ENDDAY End day of simulation integer required SEASONSTART Start month of the cropping season in required teger 102 SEASONEND IRRIGMONTH NORTHERN SPINUPS LANDSCAPE MAPS NSOIL CELLSIZE FINANCIAL CURRENCYSCALE AGENTS POPULATIONS CLUSTERS Last month of cropping season inte ger Number of irrigation months integer Is the model location on the Northern Hemisphere 0 1 Number of phasing in periods integer directory with input maps relative to in put number of soil types integer Size of gridcell in the map number if the currency is given in a different unit than 1 e g in 10 000 CHP Influences the precision of calculations Number of agent populations integer Number of clusters within each popula tion integer AGENT_INFO_FROM_M f ther an explicit AGENT_INFO ta ASSETS ASSETDISTTYPE LOTTERYLOOPS NFARMASSETS SAFEROUND MINPERM MINWATER CONSUMPTION HHNUTRIENTS SUBMODELS CONSTYPE CROP_MODEL ble is given or whether the correspond ing information should be read from the maps Initial allocation of assets 0 random assignment by MP MAS 1 supplied by user Number of lottery loops Tentative number of far
212. tion algorithm to draw only from a part of the distribution function e g because you used a copula to define a joint distribution function In this case you can add the attributes CDF_part_lb_attribute and or CDF_part_ub_attribute to the OBSERVATIONS section to indicate the name of an agent attribute that contains an lower respectively upper quantile of the distribution function between which the agent should be located For example the following code would tell mpmasdist to look for the apple_lb and apple_ub at tributes of the agent read them and if they contained for example the values 40 respectively 60 it would draw a random value from the third quintile of the qunatile function OBSERVATIONS apple CDF_part_lb_attribute this observation id _1b CDF_part_ub_attribute this observation id _ub 6 5 Spatial distribution mpmasdist currently offers two algorithms to create plot maps for MPMAS The first is a quick version for cases where spatial relations are not really important and you just want to create maps in order to comply with the MPMAS format for representing the soil endowments of agents as well as cluster network etc The second one is a more sophisticated distribution algorithm which use existing land use maps to allocate farmsteads and plots in a realistic pattern 6 5 1 Quick maps For quick maps mpmasdist offers the distribution type maps_artificial which simply fits the plot
213. tput with zero or omission being no debugging output What it is written on screen depends very much on the type of distribution performed in the step The SEED field resets the random generator with the given seed value before performing the step The AGENTS section indicates whether a new agent population is created or loaded from a file or whether the agent population currently loaded in memory is to be used in the distribution It also allows to add or change agent attributes before the distribution starts The OUTPUT section defines whether and what information should be written to disk at the end of the steps and in which files it should be saved As a very simple example the following code does nothing but saving the current agent popula tion in reloadable binary format into the file agents_after_step_10 dat in the folder defined by the outfolder variables which was set in the VARIABLES section of the control file VARIABLES outfolder out DISTRIBUTION STEP 10 DESCRIPTION Save agents TYPE none OUTPUT STORE_AGENTS var outfolder agents_after_step_10 dat The LOOPS section defines whether the whole step should be repeated and defines iterator vari ables which take on a different value in each loop For example the following code would loop over a class variable and a sector variable and repeat all tasks of the distribution step 20 for each combination of class and sector cf section C 4 for the use of
214. trix elements which do not have to be marked as special elements in order to have control over the positioning of the elements in the matrix Activities and constraints are sorted first according to the type order you specify in the first two section inf the structure file and then alphabetically by activity identifiers numbers receive special treating in alphabetical treatment making sure that e g labor_in _month_2 is located before labor_in _month_12 Special activity and constraint types Table B 28 Special matrix element types 125 Activities MASsell Selling activity need a Market dat entry and are placed first in the matrix MASbuy Buying activity also need a Market dat entry and are placed after selling activities MASfoodbuy Advanced consumption model Buying food not considered in income but in cash flow cal culation MASfoodconsume Advanced consumption model Consuming self produced food not considered in cash flow but in income calculation MASlabpin a hiring permanent labour activity MASlabpout a selling permanent labour activity MASlabtin a hiring temporary labour activity MASlabtout a selling temporary labour activity MASsav savings activity MASdep short term depositing activity MASscred short term credit activity MASfuture future selling activity have to go last and not counted for cash flow calculation but for in come MASnutpenalty Advanced consumption model disutility for starving not consi
215. ts e g the selling activity is of the type MASsell Selling activities are special because product prices may change over time and have to be used to recalculate income in case yields were not as expected when using a crop growth model Also the soil constraints are special because MPMAS needs to insert the n the soil owned by the household on the right hand side and the MASsoil type help it to recognize the corresponding constraints The actual identifier soil can be freely chosen so you could also name it terrain or land_class or whatever you like All special types start with MAS You can also use your own types These are used to group model elements and help you navigate through large matrices e g using mqlmatrix see chapter 5 We have used the types product_balance and crop_production which we have to include into the lists of user defined activity respectively constraint types which are located under the corresponding headings at the top of the model structure file ACTIVITY TYPES crop_production CONSTRAINT TYPES product_balance orow The orow field contains the objective function coefficient of an activity More specifically for the selling activities it contains the objective function coefficient of the selling activity in the first year or in other words the price the household expects to receive in the first year As shortly mentioned 17 before prices may change over
216. ts and providing right hand sides To avoid having to manually change your files whenever you want to create a standalone matrix use the ifalone function see C then mpmasq will know which value to take when run with S and which when not You can create several matrices each with a different RHS in one go similar to scenarios Sets of Right hand side values Right hand sides or RHS for short are defined in much the same way as scenarios are You can convert several matrix files with differing RHS at the same time You can also mix this with the scenarios feature e use the same collection of RHS once for every scenario You need a RHSDEF table with the columns rhs constraint rhsvalue Again the column or dering is important the column naming is not and the combination of the first two should be unique constraint refers to a constraint by the internal constraint identifier and value specifies the value to be put on the right hand side Values not specified are set to zero Table 5 2 Sample RHSDEF table rhs constraint value farm1 farm_labendow 3 farm2 farm_labendow 1 farmi 1_machinery_owned 2 farm2 2 machinery_owned 1 In the example Tab 5 2 assuming the RHSs represent a farming household each farm1 has three units of labour and two units of MacT067_owned which in the sample files stands for a 67kW Tractor and farm2 has one unit of labour and three units of MacT200_owned
217. tting the special field consfix to 1 for all activities that shall be fixed class CROPS 4 activityby production_on_soil foreach SOILS 4 consfix 1 4 3 5 Yield expectations for crops not grown As the crop yield is unknown to the farm households at the time of planning they have to take their decisions based on expectations The yield expectation for the first year is given as a field in the crop growth model interface and in the following years are updated according to the rules for expectation formation as described in section However while it is rather easy for a farm household to observe all market prices also for products it did not buy or sell it is less easy to observe crop yields for crops it did not grow respectively for combinations of crops soil types and management options it did not use Yield expectations for cropping activities a farm household did not practice can be formed by analogy to crops that have been observed E g if a farm household observes a constant decline of yields of wheat fertilized with pig manure it might assume that the same decline would also be observed if it used cow manure instead In order to facilitate such comparisons you can specify similarity relationships between cropping activities Similarities can be specified at different priority levels This is done using the special field marker yield_expectation gt with fields named similarity_ lt level gt class CROPS 4 Hactiv
218. uction Lp solved Stop or continue after first Production Lp solved Waits for user input Save all MILP as MPS files Write agent objective values in Investment and Production LPs into files Do wasim control Read external land use maps and irrigation key file and quit then Suppress initialization of Wasim coupling water constraints and expectations set to 9999 not constraining Print header lines to MP MAS output files Test consistency of maps Chile hard coded Create sector maps according to inflowlDs of ActWaterRights Ghana hard coded Catch segmentation faults in OSL when in solving mode 4 only for Linux Save updated original LP matrix for producer organizations Save updated original LP matrix for farm household and other farm agents Suppress saving pre loaded MILPs after failure Suppress saving OSL loaded MILPs after failure Reads LP input file ignoring text not sure if this really works Interrupts model run and waits for user input 97 program actually reads from files 98 Appendix B mpmasad file reference This chapter gives an overview of the structure and a reference of all possible entries in the mpmasql1 control and model design files Comments In all of the files a line starting with an apostrophe is ignored and can be used for comments You can also stretch comments over several lines with block comments Block comments start with and end with this is a comment line a
219. ula tion year CropWat Model Table with initially expected potential reference evapotranspiration for each sector CropWat Model Table with actual monthly potential ref erence evapotranspiration for each sector and simulation year EDIC Model Table with sur face and subsurface routing coefficients between sectors EDIC Model Table with ex pected monthly river flows EDIC Model Table with ac tual monthly river flows for ev ery simulation year EDIC Model Table with wa ter rights of agents as a share of sector share of inflow EDIC Model Table with sec tor shares of rights to each in flows EDIC Model Table with efficiency characteristics for each irrigation method Table of fix costs the agent have to face additional to debt service for assets and depreciation cluster specific 113 required if ASSET DISTTYPE 1 and not AGENTINFO_FROM_MAPS 1 required if ASSETDIST TYPE 0 required if ASSETDIST TYPE 1 required required required required required required required required required required optional 0 HOUSEHOLD_CDF HOUSEHOLD_COMPOSITION HOUSEHOLD_DYNAMICS HOUSEHOLD_MEMBER_TYPES HOUSEHOLD_SWITCHING INFPROJ INFPROJPARTICIPANTS INNOVATIONS INVESTMENT_HORIZON Table that specifies the household composition in terms of sex and age categories and population as cumulative distribution function for each clust
220. ulated as follows 5 Aoc lt N gt 3 4 where N is the amount of land of soil type j the household owns The objective equation representing the income of the agent would contain the revenue of his crop sales i e price p times amount sold minus the production cost i e variable cost ve times area max pe Se Ve Ae 3 5 Implementation in mpmasql Again using the concept of classes and instances looking at the above we can say we are dealing with two classes the class CROPS and the class SOILS and we can already add two instances lists for these two classes in the INSTANCES section of the model data file SOILS Hsteps 0 var NSOIL 1 1 CROPS wheat barley maize While we provide the CROPS instances explicitly the SOILS list is formed using the steps function To create a list of numbers starting from 0 and ending with the number of soils in the model minus one with a distance of 1 between each number and the neighboring In our case this is equivalent to writing 0 1 2 i e the soil type identifiers we used in the map However whenever we start using more soil types the list will be automatically updated Next we should create the blueprints for each class in the model structure file class CROPS 4 constraint balance name this instance _balance unit t type product_balance eqtype 1 Hactivity sell 4 name sell this instance type MASsell unit t orow
221. uld be placed into the input gis subfolder Study area The map containing the study area delimitation is called CatchMap00Catchment txt for historical reasons It might look like this indicating that the three cells in the upper right corner do not belong to the study area NCOLS 5 NROWS 5 XLLCORNER 3513136 YLLCORNER 5403903 THave a look at Quantum GIS www qgis org if you look for a free open source GIS Theoretically it is possible to have several study areas or hydrological catchments in one model but this feature is currently still experimental Files of additional catchments would then be named CatchMap01Catchment txt CELLSIZE 100 NODATA_VALUE 1 000 1 1 0000 i1 00000 00000 00000 Sectors The map containing the subdivision of study areas into sectors is called CatchMap00Sector txt In the usual case of no subdivisions it can look the same as the study area file defining just one sector with the ID 0 Terrains The different types of terrains you want to distinguish in your landscape have to be num bered starting from zero As the soil type is usually a major determinant of agricultural production the corresponding map is called CatchMap00Soil txt However the soil types in this map do not necessarily have to refer to pedological soil types but could also be used e g to distinguish between irrigable and non irrigable soil flat and inclined areas and so on The following example shows a map with three soil
222. uming the sample SCENDEF table is stored in your database as tbl_scenarios the com plete control file section could look like this SCENARIOS SCENDEF sql SELECT scenario variable value FROM scenarios SCENLIST list base sceni scen2 scen3 This would result in four scenarios one equal to the baseline the others with the changes as described above Of course you can also include less scenarios than specified in your table SCENARIOS SCENDEF sql SELECT scenario variable value FROM scenarios SCENLIST list base scen2 If you do not specify any scenarios or omit SCENLIST entirely your scenarioname is an underscore In general the MPMAS input file names follow the following format lt PREFIX gt lt scenarioname gt _ lt predefined MPMAS file name gt dat With four scenarios as above your examplerun file will now look like this bin sh mpmas Nexamplebase_ mpmas Nexamplescenl_ mpmas Nexamplescen2_ mpmas Nexamplescen3_ So if you now run examplerun MPMAS will simulate one scenario after the other and always write the output files to out 3 9 Output analysis MPMAS writes the simulation results into plain text files which are similar as the input files and hard to read because they contain no commentary and easily grow very large especially if your deci sion model is large To work and analyze the results it will usually be necessary to import the re sults into a stati
223. used more than one To understand this better you can imagine mpmasql1 doing an intermediate step From orow_ foreach YEARS table prices 3 this instance this field 1 it first creates this orow_2010 table prices orow_2011 table prices orow_2012 table prices orow_2013 table prices this instance 2010 this instance 2011 this instance 2012 this instance 2013 w w w w SE g N SA NS before calculating the field values this instance _balance All fields of an activity that have no predefined meaning are interpreted as the coefficient of an activity in the corresponding constraint As mentioned before the full element identifier is formed from the instance identifier an underscore and the element identifier you used in the element blueprint So the crop balance constraints of our model will be called wheat_balance maize_balance and barley_balance To say that the selling activity of a crop should get a coefficient of one in the balance constraint of the crop we wrote this instance _balance 1 activityby Remember that we needed to create a production activity for every combination of soil type and crop The by suffix enables us to use MFL functions also in the definition of an element identifier and e g to create several similar activities for one instance of a class However you need to first supply a fixed part the produce in our case before you can add
224. uses linear interpolation code linear By adding the attribute CDF_interpolation to the OBSERVATIONS section you can choose 84 between stepwise interpolation code step or cubic Hermite spline interpolation code pmch E g for the later OBSERVATIONS table fruit_plantations 0 f CDF_interpolation pmch If you want to ensure only integer values are assigned also after interpolation you can add the CDF_discrete attribute and set it to one OBSERVATIONS table fruit_plantations 0 f CDF_discrete 1 Assignment The result of the sampling is saved in the local variable this observation CDF_value_assigned which can be used to make the assignment e g TYPE assign_by_cdf OBSERVATIONS table fruit_plantations 0 f CDF_ftype cdf CDF_value_for_bin_ table fruit_plantations 0 this observation id table fruit_plantations 3 this observation id this attribute 1 fruit this observation id ASSIGN 4 this observation fruit _plantation this observation CDF_value_assigned y Constraints FIXED_CONSTRAINTS and DYNAMIC_CONSTRAINTS can be added to the model in a similar way as for the distribute_observation_list type The local variables this observation CDF_value_assigned can be used to in the constraint formulation to test the drawn value E g DYNAMIC_CONSTRAINTS this agent land gt this observation CDF_value_assigne
225. ut do not have any specific function You are free to choose your own directory where MPMAS output is lo cated Default RUNOUTDIR out directory where labeling and group variable files are located Default RUNINDIR input dat whether data frames shall be kept in the workspace for each scenario 0 1 de fault 0 whether data frames shall be exported as tab separated text files 0 1 default 1 whether all raw output shall be kept ex ported 0 1 default 0 whether a combined data frame of raw output incl performance rhs Ihs and solution shall be generated 0 1 de fault 1 omits generation of data frame with ag gregated columns according to user defined resultgroups 0 1 default 0 omits generation of a combined data frame of aggregated columns according to user defined resultgroups 0 1 default 0 list of variables to be used to create a subset of the combined data frame of user variables lt configuration parameter gt lt scalar list MFL expression gt Entries in the configuration file can be assigned scalar values and lists and mpmasq1 function lan guage expressions can be used to do so These expressions may refer to variables in the GLOBALS section of the data file not to USER VARIABLES Local variables are not defined The following entries are defined Table B 2 Entries in the model configuration file Field Description Required Default TIME STARTYEAR Start year of simula
226. w ones to switch management practice e g change irrigation practice or fertilizer use but he can just use one perennial object as if it was the other This is called switching in MPMAS Switching should of course only be possible where it makes sense e g from furrow to drip irrigated apple but not from apple to pear trees So for each perennial object you can supply a list of those perennial objects from which you can switch to the present one This list should be given as a value to the management switch field The indicate it is an array field For each entry in the list an activity is implemented automatically which has the coefficients of the new management practice except for the endowment constraint where the coefficient is placed in the endowment row of the original management practice Perennial objects need a future yield constraint and a future selling constraint Future selling activities should be of type MASfuture and are otherwise similar to selling activities Future yield constraints have to be placed directly after the current yield balance row To achieve this they have to be of the same type as the yield balance row and should have an identifier that is automatically sorted directly behind the yield row remember that matrix elements are sorted by type and then alphabetically by identifier class PERENNIALS activity sell_future name Future selling of this instance type MASfuture orow table p
227. w_1_medium wheat 1 medium 1 medium wheat_grow_1_low wheat 1_low 1 low wheat_grow_2_high wheat 2_high 2 high wheat_grow_2 medium wheat 2 medium 2 medium wheat_grow_2 low wheat 2 low 2 low Use of mpmasq1 function language in class definitions For field name and value definitions you can use mpmasql function language MFL expressions You can also use MFL expressions to create complex element identifier if you append by to the element type and provide a fixed element identifier part The resulting element identifier will be lt instance identifier gt _ lt fixed identifier gt _ lt result of MFL expression class lt classiname gt 4 lt elementtype gt by lt fixed identifier gt lt MFL expression gt For model element identifiers and field names the result of any MFL expression is interpreted as a list and consequently if the resulting list contains several items one element field for each of the list items is created if the list is empty no element field is created at all With a few exceptions value definitions can only be given as MFL expressions that result in a scalar value If they receive a list they usually use the first item in the list only You can refer to the identifier of the instance currently created with this instance in any MFL expression in the whole class You can refer to the current non fixed part of the element identifier with this by 0 and to the current field created with this field 0 Any number i
228. way you can make sure the coefficients automatically have the desired value whenever you switch between conversion modes without having to update your files by hand In the following example we have used the ifalone function to show you the formulas MPMAS uses internally to calculate the coefficients The actual value found in the input file matrix is however zero in any case class MACHINERY asset machinery_asset eqshare var EQSH act this instance _invest activity invest name invest into this instance integ 1 ubound 10 orow 1 ifalone var EQSH table machinery 3 this instance table machinery 2 this instance annuity var INTEREST_LGCRD 1 var EQSH table machinery 3 this instance table machinery 2 this instance 0 this instance capacity 1 ifalone table machinery 4 this instance 0 MAS_ongliq ifalone fvalue var INTEREST_SHDEP table machinery 2 this instance var EQSH table machinery 3 this instance 0 27 MAS_yearilig ifalone var EQSH table machinery 3 this instance 0 act The investment activity needs to be connected to an asset so whenever the activity is chosen by the household i e greater than zero in the solution MPMAS knows that it has to add this asset to the household s endowments and account for the upfront payment and debt servi
229. work etc to be defined for each agent The file names for the maps are defined using the corresponding keywords in the OUTPUT section STEP 40 4 DESCRIPTION Make other maps for MPMAS TYPE make_secondary_maps_for_mpmas AGENTS MASPopulation 0 MASCluster this agent cluster MASNetwork 0 MASSector this agent sector MASCatchment 0 OUTPUT POPULATIONMAP gis CatchMap00Pop txt CLUSTERMAP gis CatchMap00Clu txt NETWORKMAP gis CatchMapOONetw txt SECTORMAP gis CatchMapOOSector txt CATCHMENTMAP gis CatchMap00OCatchment txt Note each statement needs to go on one line line breaks in the example only for readability in this manual 6 6 Varying agent populations As mentioned in section 6 1 2 the values of user defined variables may be overridden when running mpmasdist by using the command line option set This may be used to generate variations of the agent population for uncertainty analysis e g by varying the random seed or a constraint For example the following setup would allow to create different distributions of fruit plantations among the agents by repeatedly running mpmasdist The setup also makes sure that the output is saved in different folders named after the seed and that this folder is created if it does not exist VARIABLES SEEDFRUITS 2761 outfolder out var SEEDFRUITS CONTROL MKPATHS out var SEEDFRUITS 90 DISTRIBUTION
230. y contain one field whose field definition should contain the identifier of a labor con straint and the value definition should indicate the required amount of labour If you need more labor constraints put them as internal consumables 4 3 Crop growth models One of the special features of MPMAS is its ability to be coupled with crop growth models So far we have assumed that plant growth occurs as planned but in reality crop yields are often depending on natural conditions 38 4 3 1 CropWat CropWat is an internal MPMAS implementation of the FAO56 model for crop growth under water deficit To simulate irrigation it has to be combined with the EDIC hydrology model however if only rainfed crops are modeled the EDIC model is not necessary It is activated by setting the CROP_MODEL entry under SUBMODELS in the model configuration to 2 SUBMODELS CROP_MODEL 2 In the MPMAS TABLES section of the model data file time series for precipitation and potential evapotranspiration have to be provided for each sector as well as values for the initial expectations for both Required table columns are given in Tab B 8 Section B 3 Optionally you can adapt the formula used to calculate effective rainfall i e the amount of rain that can be used by the plant from observed rainfall The default is the USDA formulation alternatively you can specify the coefficients of a quadratic equation that includes precipitation the crop water demand a
231. y segment specific values in SEGINFO Overlap of network thresholds Parameter for adaptive expectations see Brandes et al 1997 382 Share of acquisition cost that can be re covered when reselling the investment default value can be overridden by segment specific values in SEGINFO Simple consumption model Extra con sumption percentage if income sur passes minimum consumption frac tion Simple consumption model Minimum consumption money that is consumed at least if the liquid means suffice num ber Simple consumption model Essential share of minimum consumption that has to be maintained even if liquidity does not suffice fraction 110 2000 1 3 0 7 30 0 0 optional optional optional optional optional optional required required required SUCCESSION_AD _MINCONS_FACTOR SUCCESSION_AD _MINIMUM_PROFIT SUCCESSION_AD _DECI SION_ACTIVITY SUCCESSION_VR _MINCONS_FACTOR SUCCESSION_VR _MINIMUM_PROFIT SUCCESSION_VR _DECI SION_ACTIVITY SUCCESSION_VR _MINIMUM_RENTAL SUCCESSION_OR _MINCONS_FACTOR SUCCESSION_OR _MINIMUM_PROFIT SUCCESSION_OR _DECI SION_ACTIVITY TCOST XC_SAV_INCSEGS XC_SAV_COEF_INC XC_SAV_COEF_INC2 XC_SAV_COEF_HH Advanced demography model share of household minimum consumption to be covered for succession at death Advanced demography model mini mum income to be reached for succes sion at death Advanced demogr
232. y these are included in the list of candidate agents for an assignment FIXED_CONSTRAINTS this agent sector I Ul N Note You can formulate any number of constraints in separate lines Each line has to evaluate to true for the set of constraints to be fulfilled DYNAMIC_CONSTRAINTS are checked before each single random allocation DYNAMIC_CONSTRAINTS should only be used if the evaluation result of the condition might change during the distribution pro cess otherwise the repeated evaluation unnecessarily slows down the distribution process One example for a dynamic constraint has already been given in the previous section Another example is ensuring that the agent does not receive more fruit_plantations than the amount of area it 79 owns In teh following example the auxiliary agent attribute land_for_fruits is introduced and set to the value contained in the land attribute of the agent in the beginning Every time the agent receives a plantation the attribute is reduced by the corresponding amount of area reduced STEP 120 DESCRIPTION Distribute fruit plantations TYPE distribute_observation_list AGENTS land_for_fruits this agent land OBSERVATIONS table fruit_plantations 0 f fruit table fruit_plantations 2 this observation id size table fruit_plantations 3 this observation id DEL_count table fruit_plantations 4 this observation id DYNAMIC_CONSTRAIN

MpmasQL 2.52 - Universität Hohenheim

Contents

Download Pdf Manuals

Related Search

Related Contents

MpmasQL 2.52 - Universit&auml;t Hohenheim

Contents

Download Pdf Manuals

Related Search

Related Contents

MpmasQL 2.52 - Universität Hohenheim