linking farm economics and hydrology: model integration for watershed-level irrigation ... ·...

FACULTY AGRICULTURAL SCIENCESCover page of Electronic Appendix to dissertation

Institute of Agricultural Economics and Social Sciences in the Tropics andSubtropics (490)

Land Use Economics in the Tropics and Subtropics(Josef G. Knoll Professorship)

Prof. Dr. Thomas Berger (Supervisor)

Linking farm economics and hydrology:

Model integration for watershed-levelirrigation management applied to Chile

Dissertation

Submitted in fulfillment of the requirements for the degree ‘Doktor der Agrar-wissenschaften’ (Dr.sc.agr. / Ph.D. in Agricultural sciences)

to the

Faculty of Agricultural Sciences,

presented by

(Name) Thorsten Arnold

(Place of birth) Bielefeld

(Year of publication) 2009

Part II

Electronic Appendix

I

Table of Contents

A Review Of Literature On Irrigation Modelling 1

A.1 Objectives of disciplinary review . . . . . . . . . . . . . . . . . . . . . . . . . . 1

A.2 Improving water management for irrigation . . . . . . . . . . . . . . . . . . . . 1

A.3 Modelling To Support Irrigation Management . . . . . . . . . . . . . . . . . . . 3

A.4 Sector-level models and economics . . . . . . . . . . . . . . . . . . . . . . . . 5

A.5 Physical modelling of irrigation-dominated watersheds . . . . . . . . . . . . . . 7

B EDIC Sector Routing Model For Irrigation 13

B.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13

B.1.1 Scope of EDIC approach . . . . . . . . . . . . . . . . . . . . . . . . . . 13

B.2 Equations And Processes Of The EDIC Model . . . . . . . . . . . . . . . . . . . 15

B.3 Irrigation Methods At Field Scale . . . . . . . . . . . . . . . . . . . . . . . . . 21

B.4 Calibrating The EDIC Model . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

B.4.1 Relevant Background . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23

B.4.2 Calibration parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 25

B.4.3 Calibration steps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

C WASIM-ETH and Technical Implementation of Water Rights 27

D Technical Description of Coupling and Source Code 31

D.1 Technical description of MP-MAS data handling . . . . . . . . . . . . . . . . . . 31

D.1.1 Transfer of Spatial Variables to Agents . . . . . . . . . . . . . . . . . . 31

D.1.2 The handling of Time . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

D.2 The sequencing within MP-MAS: Source code . . . . . . . . . . . . . . . . . . 35

D.3 Documentation of MP-MAS source code . . . . . . . . . . . . . . . . . . . . . 37

D.4 Details on data flows and protocols . . . . . . . . . . . . . . . . . . . . . . . . 38

D.5 Rescaling between WASIM-ETH and MPMAS . . . . . . . . . . . . . . . . . . 41

D.5.1 Theoretical considerations for downscaling . . . . . . . . . . . . . . . . 41

D.5.2 Functional steps in scaling from fine-scale to coarse-scale . . . . . . . . 41

D.5.3 Fine to coarse-scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42

D.5.4 Coarse to fine-scale . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

D.5.5 Source code example . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

D.6 TDT Description Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

D.7 Starting a fully coupled model run . . . . . . . . . . . . . . . . . . . . . . . . . 48

D.7.1 File directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

D.7.2 Adjusting the bash shell . . . . . . . . . . . . . . . . . . . . . . . . . . 49

D.7.3 $MAS/AllDefaultsCoupl.txt . . . . . . . . . . . . . . . . . . . . . . . . 50

D.7.4 Executables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51

D.7.5 Calling all executables simultaneously . . . . . . . . . . . . . . . . . . . 51

D.8 Tools for data processing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

D.8.1 Script to create standalone application . . . . . . . . . . . . . . . . . . . 52

D.8.2 Script for Remote Access . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Appendix A

Review Of Literature On IrrigationModelling

A.1 Objectives of disciplinary reviewThe research project Integrating Governance & modelling (IGM) aims to develop and use amulti-purpose modelling system within a stakeholder-driven research process. This multi-purposemodelling system should be based on theory and parameterized with empirical data.

As a background to this model setting, this chapter first reviews the most important pol-icy issues for irrigation water management. Then, modelling approaches are briefly reviewed,including their scales and purposes, and an extended review is carried out for the core modeltypes that are used within this model system: (watershed-level) physical irrigation models andsector-level water balance models, also in combination with inter-sector models for optimization.Finally, concepts to evaluate the efficiency of irrigation schemes are compared.

A.2 Improving water management for irrigationIt is becoming general knowledge that water is increasingly the most relevant production con-straint for the long-term survival of humankind. Reports on global water scarcity were publishedby United Nations (HDR 2006, . . . ), by the World Bank (World Bank 1993), by CGIAR centerssuch as IFPRI (Rosegrant et al. 2003) and IWMI (Molle et al. 2007), and in popular books (Pos-tel 1999, Lomborg 2004 or Pearce 2007). Access to drinking water and sanitation was recentlyaccepted as human right1. For rural areas, irrigated agriculture consumes around 78% of watersupplies (World Bank).

On the production side, improving water usage in agriculture is an imperative (Molden 1997),for which a good understanding of irrigation water flows and balances at irrigation sector leveland at watershed is essential (Droogers et al. 2000). This understanding must be complementedby an understanding of water-governing institutions (Rosegrant et al. 2005), from the demandperspective (Hoekstra and Chapagain 2007), from the perspective of producers that interact withother producers (Berger et al. 2007a), and ultimately from the perspective of an integrated foodchain. Only this food chain perspective on the globally integrated commodity markets allows for

1General Comment No. 15 (2002) on Articles 11 and 12 of the International Covenant on Economic, Social andCultural Rights

1

2 APPENDIX A. REVIEW OF LITERATURE ON IRRIGATION MODELLING

an analysis of who produces for which consumers and who actually benefits from an improvedproduction technology – in other words, how are total benefits generated shared among produc-ers, marketers, food processors and finally consumers.This section reviews the most relevant political themes for irrigation management at watershedlevel.

Policy failure to increase investments. Singh and Woolhiser (2002) discuss how more investmentinto irrigation can improve food security. Later in the same report, Yoshinaga discusses theparadox that

although meeting the increasing demand for food will require more irrigated land,the investments may not be forthcoming. Given the long lead time between plan-ning and implementing irrigation projects, failure to reverse the downward trend ininvestments could soon lead to food shortages with direct consequences for manydeveloping countries and particularly for the poor (Yoshinaga, p. 55)

Allocation of irrigation water to non-food products. The ongoing market price increase of bio-fuel crops and the increasing consumption of meat, cause a re-allocation of land and waterresources (but also research funds and efforts) away from crops for food and livelihood of thepoor and toward energy and fodder crops (de Fraiture et al. 2008). Because markets are drivenby buying power rather than by basic needs or human rights, better-off segments of the globalcommunity are setting global market incentives and thus driving the re-allocation of land andwater away from basic food production, in favour of energy and meat production, while an in-creasing number of poor people have few assets with which send signals through commoditymarkets. Even within the agricultural sector, the political objectives of food security competeswith the other objectives.

Allocation of irrigation water to non-agricultural sectors. The first dimension of integration isthe integration of multiple water-using sectors in water allocation processes in one location.This is especially relevant during the utilization and allocation phase of river development.Ultimately, such integration can answer questions on how water should be allocated betweenenvironmental, industrial, urban, hydroelectrical and agricultural uses within a single region,based on sectoral production functions and sectoral shadow prices (e.g. Cai 1999, Cai et al.2007). Finally, an integrated view of all relevant sectors in one location forms the basis of con-clusions on how scarce water really is in a region and how this region should participate in theglobal trade in virtual or real water.

Benefit sharing along the food chain. A second dimension of integration requires an assessmentof the benefits, related to water use, along the entire food chain: from the producers, through themarketing and processing chain, to consumers. This dimension of intengration must ensure thatwater use actually meets the objective of securing food for all and addresses the market failuredescribed above.

Molle et al. (2007) differentiate between three development stages of river development: thedevelopment stage, with problem solving dominated by improvement of infrastructure to grantphysical access; the utilization stage, where dams are developed and water shortages requireimproved management; and finally the allocation stage. During this last stage, water productivityis improved by re-distributing water from less efficient to more efficient uses. The shift from

A.3. MODELLING TO SUPPORT IRRIGATION MANAGEMENT 3

engineering solutions to management solutions and policy mechanisms to re-allocate access towater is mirrored in the requirements of modelling software.

A.3 Modelling To Support Irrigation ManagementThe objectives of irrigation water management define which modelling approaches will be ade-quate. These objectives determine both the assessment and model scale, the temporal resolutionand the model type.

The growing concern on water scarcity is giving rise to model-based policy assessment tools thatintegrate multiple disciplines, driven by external scenarios such as climate change, trade liberal-ization, environmental development windows and limits, and changing agricultural institutions(Donatelli et al. 2007, Foreword). Irrigation models can be divided into irrigation managementmodels, irrigation impact models, and integrated models. Irrigation management models aim tooptimize the benefits of water management (McKinney et al. 1999), at field level or at sectorlevel. Irrigation impact models aim to analyze the impact of externally determined irrigationpractices – on plants, on water flows and solute transport within a field or in a watershed. Thesemodels are usually the domain of the natural sciences; of physics, plant and soil sciences. ThisPh.D. thesis focuses on integrated models which are developed to analyze the impact of andfeedbacks from the use of irrigation practices across multiple assessment scales. To analyze howmanagement practices feed back on other resource users, an integrated model needs to embraceboth dimensions: the management process that is influence by the resource base and the impactof management practices on the resource base. The objective of this review is to summarizemodel approaches for both impact and management models, as components of an integrated sys-tem.

Computer-based assessment tools use are based on integrated economic-hydrological modelsfor water management (see McKinney et al. (1999) for water management models, and Ahrendset al. (2008) for integration approaches for irrigation modelling). Three approaches to modellingwhich are employed in water management are:

Field-level models are used to analyze local processes, with study sites of just one or a fewhectares and model resolutions of a few meters. Outputs may be optimal irrigation schedul-ing (e.g. CropWAT, Smith 1992) or process descriptions of erosion, percolation, nutrient miningor pesticide transport. These outputs may be geared toward plant growth and crop yields (seeMmolawa and Or 2000 for a review).

Such models translate the quantity and timing of crop water deficit into the reduction of a po-tential maximum yield. Building on Doorenbos and Pruitt (1977) and later Allen et al. (1998) inmodelling crop yields, the water requirement satisfaction index is computed with data on waterdemand and supply, ultimately giving an estimate of crop yield. Typically, the monthly plantwater requirements are estimated with measurements, monthly water availability from precipi-tation data and a water balance model that describes the soil, field (CropWAT, Allen et al. 1998)or entire region (Gleick 1987).

Bio-Economic Farm Models (BEFM) are usually classified as normative or positive models. Method-ologically, most such models use constrained optimization at different levels of sophistication


and as variations of linear programming (LP, see Hazell and Norton 1986). Extensions or varia-tions are nonlinear, positive and dynamic programming or multiple goal objective functions. Allmethods allocate a set of available resources/inputs among alternative activities, while optimiz-ing a utility function and satisfying constraints.

An alternative classification is presented by Janssen and van Ittersum (2007), who suggests theterm ‘empirical’ for models that are valid within the calibration range, and ‘mechanistic’ if theycan be used outside of the calibration bounds2.

Conradie and Hoag (2004) classify bio-economic, mathematical irrigation models into threecategories: Optimal temporal allocation models aim to improve water use efficiency throughdifferent scheduling practices, often using dynamic programming. As input data, crop yieldseither result from measurements or, more frequently, use the results of other, process-based cropmodels. The second category includes water demand models, which use a set of productiontechnologies and treat water as one input. The models can compute water demand (or usage)under different pricing scenarios. The third category describes variations and/or extensions ofthe two former categories.

Sector-level water balance models and economic sector models Sector-level water balance mod-els describe a watershed as a network of interconnected storages (sub catchments or sectors)through which water passes via a natural flow regime (rivers, ground water, creeks) or artificialconnections (canals, pipes, etc). In each storage node, a balance equation equates water sources(precipitation and external inflows from canals, rivers and ground water), changes in storagevolume, and water sinks (evapotranspiration, percolation, outflows). Such models date back to1948 (Thornthwaite) and have been applied to a wide spectrum of hydrological and managementproblems (for a review and history, see Xu and Singh 1998). The short runtimes and conceptualsimplicity of sector-level balance models explains their use in other disciplines, notably as com-ponents in economic optimization problems.

In economic models, a sector-model for water management usually refers to specific branchesof the economic system, e.g. agriculture, urban residential demand for water, energy use (forcooling or for hydroelectric power generation), for industrial production, or for ecosystem ser-vices. In economic sector models, a function that describes water demand – as an input for theeconomic value chain, which is used up, polluted or otherwise utilized exclusively – is used toestimate returns from water and other inputs. Shadow price analysis then provides an estimationof returns to additional water. Models may also offer a benchmark for additional returns thatmay be achieved through re-allocation.

A review on combinations of hydrological sector models and economic sector models is givenin Section A.4

Watershed-level distributed models are based on physical laws, which are scaled and eventuallyadapted to reduce data requirements. Watershed-level models cover areas of one to hundredsof square kilometers and may involve a multitude of creeks and canals, and a heterogeneity ofirrigation practices (Khanna and Malano 2006). A detailed analysis is given in Section A.5.

2This economic definition of ‘mechanistic’ conflicts with its hydrological use, which refers to non-process re-gression models that can only be used within bounds (Young 1998).

A.4. SECTOR-LEVEL MODELS AND ECONOMICS 5

Further approaches Model approaches that are not considered here include data-based mecha-nistic models, where high-dimensional impulse response functions (or transfer functions) areestimated using data (Young 1998 , Young and Garnier 2006). Parameters lack interpretablemeaning, which makes them adequate tools for technical applications, sensitivity analysis andeven for prediction, but such models are less adequate to explain and elucidate cause-effectchains.

Rule-based modelling approaches for group modelling are only briefly mentioned: their aim andstrength is consensus making and the elucidation of knowledge (Barreteau et al. 2001 or Ravetz2006). For group modelling and/or multi-agent systems which aim to tackle sustainability incontemporary agro-ecological systems (e.g. Barreteau et al. 2001, Etienne et al. 2003, vanPaassen 2004, Barreteau and Abrami 2007), multiple perspectives and values of stakeholdersare incorporated and alternative system formulations can be compared. The transparency ofsuch rules is highly advantageous in group modelling sessions and role playing, and to stimulatelearning and mutual understanding of water users. However, such models are less adequate fortheory-based and/or predictive analysis, which are the aims of this study.

An integrated hydrological-agronomic-economic-institutional model should allow for theanalysis of water quantity and water quality regulation, represent spatial and temporal exter-nalities, as well as the effects of uncertainty and risk concerning both water supply and demand,across and within sectors (McKinney et al. 1999).

A.4 Sector-level models and economicsHydrological sector-level balance models are defined as a spatial network of storage nodes,which are represented with balance equations, and links, which represent natural flow regimes orartificial canals/pipes (Xu and Singh 1998). Water balance models are intended to develop basicunderstanding of core processes and are adequate to assess which level of complexity can besupported with a given set of data available to estimate model parameters (Schaake et al. 1996).

In economics, sectors are defined as functional entities, such as agriculture, urban residents,industrial production, energy or ecosystems. Economic sector models assess the input demandand value produced from these inputs, as well as the allocation mechanisms between these func-tional sectors (Hazell and Norton 1986). Technical works are the estimation of a sector-levelproduction function and the computation of shadow prices.

The hydrological and the economic sector approach is often combined and used to analyzebenefits of water usage, externalities and intra-sector reallocation mechanisms. For example,Louw and van Schalkwyk (2000) assess the potential of water markets as reallocation mecha-nisms for the Berg River (South Africa). Social benefits, expressed as consumer and producersurplus (while not considering the share of surpluses lost to marketing surplus), are estimated forsix agricultural sectors, urban and industrial use (for other examples, see Noel and Howitt 1982,Lefkoff and Gorelick 1990, Becker and Hattermann (2005)).

The most recent, prominent and complete example of this model type may be Cai et al.(2007) from IFPRI, which builds on the Ph.D. thesis from Cai (1999) and is discussed here inmore detail. This model uses a sectoral production function to assesses economic returns fromwater use in each sector, including agriculture, urban, environmental, hydroelectric and industrial


use. Shadow prices for water are derived for each sector. Benefits from re-allocation betweensectors are then postulated.

Production functions for each sector differ and may include complex relations; Cai, Ringlerand Rosegrant (2007) (p. 24ff) uses a nonlinear regression function to estimate yields underdifferent levels water stress and salinity, as well as different irrigation methods. The regressionmodel is parameterized with a complex, field-level crop growth model. Further, the evaluationof a field survey on crop yields indicates that – at the input levels of 1999 – the growth of high-value crops is mostly constrained by water, while low-value crops are constrained both by waterand by other inputs. As a result, water benefit functions (as shadow prices) linearly decrease inupstream sectors and hyperbolically in downstream sectors. To explain these forms, Cai et al.identify crop pattern and irrigation methods, but also climatic conditions, water quality and theefficiency of the delivery system. A water trading module is then used to re-allocate water be-tween sectors. Institutional rules are modeled as external model constraints.

Optimization across sectors, as performed in the above example, provides insights on how toimprove the benefits of water use in a watershed, by re-allocating water between sectors. Thesemodels build on four premises:

1. Technical feasibility. The re-allocation between sectors is physically feasible, which isreflected in the parameters of the node-link-model. Further, the aggregated monthly timeresolution that is commonly used does not add false assumptions that make re-allocationpractically impossible.

2. Sector-level production functions reflect the full costs and benefits of water usage and arethus equivalent to welfare functions.

3. Within-sector benefit neutrality. The re-allocation process that changes access to watercauses a rearrangement of water management institutions (and thus power). This rear-rangement does not leverage resource capture by some group, which may impact within-sector distribution, and undermine the original benefit function that was aggregated atsector-level.

4. Relevance. Between-sector distribution is more important than within-sector allocation ofwater ownership.

For areas in which the distribution of within-sector access is equally or more relevant thanbetween-sector allocation, the inherent assumptions of sector-level allocation models may over-shadow the politically sensitive resource capture processes of reallocation within sectors.

To model the impact of access to water rights for agricultural production under irrigation,Berger (2000) linked a micro-economic-based, multi-agent model, MP-MAS, with a hydrolog-ical irrigation sector model, EDIC. This node-link network model focuses on intra-agriculturalallocation between irrigation sectors and on reuse and return flows between these sectors (MOP1992).

The model approach from Berger complements the Cai-approach, because it captures internaldynamics within agricultural irrigation sectors, by representing a population of farmers in astatistically consistent manner (Berger and Schreinemachers 2006). It opens up the analysisfor a new problem domain; the elucidation of re-distributive dynamics of farm enterprises both

A.5. PHYSICAL MODELLING OF IRRIGATION-DOMINATED WATERSHEDS 7

within and between irrigation sectors. In addition, it links hydrological-economical modellingwith the micro-meso-macro assessment perspective (see Section 3.1.3).

An agent-based irrigation model allows for the analysis of the problem domain of complexinteractions, for the following issues:

• Inherent differences in competitiveness, resulting from (a) the asset distribution amongfarmer agents and (b) access to production technologies.

• The capability of agents to relax production constraints, by improving their asset endow-ment, for example by investing in production technologies or by participating in land andwater markets.

• Peer-2-peer interactions, such as the diffusion of innovation and changing access to pro-duction technologies.

• Spatial interactions, such as through upstream-downstream water routing

• External scenarios for price changes or climatic changes.

A.5 Physical modelling of irrigation-dominated watershedsOverview

Process description of physical irrigation modelling relies on two basic hydrological equations:the conservation of momentum (NAVIER-STOKES or derived forms) and the conservation ofmass (continuity equation). From these two equations, simplifications were derived to deal withspecific hydrological processes in specific zones:

• For surface flows (‘flow above porous medium’), a full or simplified version of the shallowsurface SAINT-VENANT equation is used to simulate the dispersion of water at the surfaceand surface runoff;

• To describe infiltration of water into the soil, empirical functions are usually used. The fullRICHARDS equation is applicable, but requires very fine resolution;

• For vadose zone modelling, most models use the 1-D RICHARDS equation for verticalflows;

• For saturated zone modelling (ground water), DARTHY’s law and continuity equations areused.

• For routing models (river or canal flows), either MANNING’s empirical formula is used ornumerical schemes that compute advection based on NAVIER-STOKES.

The applicability of all equations is further limited by the temporal and spatial model resolution,and both equations and parameterization must be adapted accordingly (e.g. Harter and Hopmans2004). Spatial scales are typically classified into pore level (µm–mm), for which the Navier-Stokes equation is applied; the macroscopic or Darcy level (cm-1 m), for which Darcy andRICHARDS equation used; the field level (m–1 km), which is usually modeled with RICHARDS

equation; and the regional level (>1 km). In regional models, physical approaches (RICHARDS,


Darthy) coexist with cell-level balance models (e.g. TOPMODEL (Beven3) or with sector-levelbalance models (Xu and Singh 1998).

As broad categorization of physical-based irrigation models, Furman (2008) distinguishesthe matter of research: volume irrigation or precise irrigation. With precise irrigation techniques(drip, sprinkler), little or no water is lost to runoff or percolation, so that hydrological modelsmust only take into account local parameters. The irrigation water flux is determined by soilwater deficit and added to the topsoil directly. Infiltration should include all water that is not lostto interception or surface evaporation and is described with empirical functions. Models that usethis approach include SWAT and the original WASIM-ETH irrigation module.

Surface irrigation (flood, furrow, basin, border) are prevalent in most countries, but especiallyin developing countries (e.g. USA 115.000 km2, India >500.000 km2, USDA/FAO, in Furman2008). These techniques are inefficient and large shares of irrigation water drain into the canal- orriver system. The results is that water can be reused by others, while chemical loads accumulatein runoff and in soils. When using surface irrigation techniques, the effectiveness of and returnflows from irrigation are determined by the technology of each farmer, as a function of thesize and topography of fields, crop choice and the quantity and scheduling of irrigation. Thisdecision takes into account the farmer’s experience and recommendations from others (Berger2001). Because surface irrigation techniques are mostly applied to crops with very small profitmargins, the farmer’s cropping decision balances the cost for improved irrigation techniques,with field- and soil characteristics and with labor and energy costs. A precise physical modellingof the outcome of this every-day farm management problem would require detailed descriptionof soil properties: including infiltration-inhibiting topsoil crusts that form during the drying ofsoils, macro pores that facilitate infiltration, and the absorption capabilities of the soil (related toorganic matter content). All of these factors are very much dependent on farming practices.

The most difficult process to model is the drainage of excess water back into the canal system,because simple human alterations to canals have strong effects and because neighboring farmscan abstract drainage water again (cyclic reuse). Cyclic water flows are in the order of 10 - 60%of irrigation water use (Molden et al. 2001, Gosain et al. 2005). A faulty representation of theseflows would necessarily make results from a physical model unreliable.

Not surprisingly, Furman summarizes surface irrigation modelling as “among the most diffi-cult tasks for modelling surface flows” (p.748), especially because soil properties (and numericalgorithms) change during the plant development cycle – the advance phase, wettening, depletionand recession phase. For modelling surface irrigation on a single field, Furman highlights twocommonly used softwares, namely SRFR and SIRMOD. Both models use modifications of theempirical Kostiakov infiltration function and simplifications of the Saint-Venant shallow surfaceflow equation, to model a one- or two-dimensional irrigation event, because the use of the (phys-ically correct) RICHARDS equation requires iterative solution of surface and vadose zone flows.Similar algebraic approaches include the Green and Amp formula (Green and Ampt 1911), orits modification by Peschke (1987), which is used in WASIM-ETH.

Issues of resolution, assessment level and heterogeneity

Irrigation systems are composed of processes that occur at multiple spatial levels simultaneously.Farmers apply irrigation water at field scale, soil processes occur at the Darthy scale, but relevant

3http://www.es.lancs.ac.uk/hfdg/topmodel.html

http://www.es.lancs.ac.uk/hfdg/topmodel.html


outcomes (return flows, diffuse sources of nutrient loads or chemical contamination) are mostlyobserved at the regional level. Furthermore, field-to-field interactions, such as the cyclic reuse ofrunoffs from excess irrigation, add additional complexity to the modelling of irrigation systems.Therefor, this section addresses issues of scaling and heterogeneity.

Most natural processes occur continuously in time and space..However, for the purpose ofanalysis and modelling, only a discrete number of levels can be treated (Wagenet and Hutson1996). Temporally, models focus on single irrigation events (infiltration and flow, erosion), onfull cropping periods (yield generation), or on multiple years (soil degradation, salinization, irri-gation security). Spatially, models describe the root zone of single plants4 (Warrick and Gardner1983, Jackson and Caldwell 1993), small and confined fields (also called ‘irrigation basins’, seeKhanna and Malano 2006), and watersheds, where process-oriented irrigation modelling doesnot yet play a prominent role (e.g. the review for watershed models by Singh and Woolhiser(2002) does not even mention irrigation), or assumes precise irrigation techniques that are easierto model (most SWAT applications).

Vereecken et al. (2007) reviews upscaling approaches from the macroscopic Darcy scale(1 cm – 1 m) to field level for the vadose zone. The modelling of soil water processes at field, oreven at watershed level, requires that vadose zone processes are represented at units that are or-ders of magnitude (OoM) larger than actual physical interactions. Vereecken et al. distinguishes‘forward upscaling’ approaches, which induct larger-scale behavior from micro data using statis-tical methods, in combination with micro measurements, from ‘inverse upscaling’ approaches,which measure or estimate large-scale properties and boundary fluxes, and infer micro scaleproperties5. Re-parameterization of vadose zone equations, as a result of the scale shift, canfurther be distinguished into effective and equivalent formulation of equations, where effectiveequations use physical- and data-based properties and are thus generic, while equivalent for-mulations are site specific reformulations that behave accordingly. In practice, this distinctionis blurred, because the data demands for effective re-parameterization are hardly ever satisfied(ibid).

More generally, Bierkens et al. (2000) distinguish four scaling classes from micro to macrodata: (i) averaging, (ii), finding representative (effective) parameters, (iii) the use of averagingmodel equations, and (iv) model simplification. They also use four model categories: (i) Lin-ear/Nonlinearity, (ii) site- and time specificity of a model, (iii) invariance of the model form atdifferent scales, and (iv) the analytical traceability of the connection between scales. Downscal-ing was defined as “restructuring the variation of a property at a smaller scale from informationat a larger scale” (Corwin et al. 2006). This inverse problem of upscaling poses the challenge ofnon-unique solutions and equifinality (Bierkens et al. 2000).

If a scale transition of matter or energy occurs, the modeller must find an adequate descriptionfor effects from spatial and temporal heterogeneity of sub-resolution processes. Unfortunately,the spatial coefficient of variation (CoV) is highly variable for many hydrologically relevant soilcharacteristics and depends on the location (soil genesis) and its history (Jury 1986). Parameters

4In the vadose zone, scale issues also raise the problem of measurement: the typical correlation length of soilproperties is 50 cm for 50% of all processes (From Pore to Core to Field: Processes and Observations, Nice, France,April 2003). For these variables, even perfect measurement data, which includes all parameters at one location,provide few insights just a meter away.

5This difficulty is analogous to limits in agro-ecological assessment, see Wagenet (1999) or page 23, and also ineconomics, e.g. Hazell and Norton (1986))


with low CoV are soil porosity, bulk density, and maximum soil water content. Parameters withhigh CoV are water flow parameters and those effected by organic matter (saturated hydraulicconductivity and infiltration). In addition to these physical parameters, chemical characteristicsdiffer greatly: around perennial plants, soil nutrient concentrations vary by a factor of 2 OoM(Jackson and Caldwell 1993). Furthermore, the characteristics of soil variables strongly changeover the yearly cycle because of natural processes and of human interventions. Capturing theheterogeneity of soils, especially with regard to scaling, is and remains difficult (Corwin et al.2006, p. 133 for review).

Using numerical experiments, Liang and Xie (2001) found significant errors in regional modelswhen estimating surface and subsurface runoff. Faust, Ferre, Schaap and Hinnell (2006) sys-tematically compared the impact of different pedotransfer functions (PTFs) on the prediction ofrecharge, where recharge estimates of a spatial water balance model vary by 1 OoM dependingon the choice of PTF.

For surface techniques, the actual irrigation practice (scheduling and preparation of soils)seems to play a more prominent role than inherent soil heterogeneity. For efficient sprinklertechniques, site-specific measurements from Lia and Kawan (1996) suggest that even the hetero-geneity that results from irrigation practices is leveled out by advective and cappilar soil flows.However, at micro scale, crop yields remain affected by the non-uniformity of both soil charac-teristics and irrigation (Warrick and Gardner 1983).

The issue of scaling thus remains a major challenge to improve modelling of surface irriga-tion processes.

Physical irrigation modelling at the watershed level:Purpose and challenges

The purposes of physical irrigation models differ greatly. Models for watersheds describe waterflows and the behavior of chemicals, including the following: non-reactive tracers (radioactivetracers, salt, some pesticides and some heavy metals, e.g. Schulla et al. 1999); the (bio-)chemicalsorption processes of chemicals that interact with the soil matrix (e.g. Ingwersen and Streck2006), and finally biologically active matter that is modified by soil microbes (carbon and nu-trients), which requires explicit consideration of microbial activities (Pohlert et al. 2007, Julichet al. 2008).

However, in the literature, few models are applied to watershed-level irrigation studies. Anumber of studies were performed with the hydrograph-based SWAT, with distributed, grid-based models such as MIKE-SHE (Hansen et al. 2007) and WASIM-ETH (Schulla et al. 1999,Uribe et al. 2009). Originally, all these models were developed for efficient micro irrigationtechniques (precise irrigation) and no model explicitly assesses the impact of cyclic flows (waterreuse and return flows). The models mentioned, balance water at the level of each cell (or re-sponse unit) and at the level of some sub-watershed, as defined by a pour point. Some forms ofnear-surface interactions between grid cells of one sub-watershed are offered by these models,and include overland 2D flows and approximation of lateral flows within the root zone. However,the actual parameterization of such interactions is difficult, especially because topography-basedoverland flow is not relevant in an area with heavily modified drainage and canal networks.


In summary, despite the increased awareness of the global relevance of agricultural irrigationmodelling, its physical characteristic poses a systemic challenge – in addition to the inherentcomplexity of partial differential equations:

1. Even if physical processes could be modeled adequately, the heterogeneity of soils prac-tically impedes modelling with measured parameters (Hansen et al. 2007), and insteadrequires the use of effective (or equivalent) parameter values (Kool et al, 1986), and opensthe problematics of upscaling and downscaling in hydrology ( e.g. Bierkens et al. 2000).

2. Irrigation management at farm and larger levels is heavily influenced by non-physical pro-cesses: farm management, canal maintenance, and cyclic water reuse. Hydrological mod-els that do not explicitly treat cyclic use of water usually have an error of 10 - 60%, whichmay be calibrated but fundamentally changes local physics;

3. Practicality. Any modelling tool that aims to reproduce and predict irrigation for naturalresource management must be useful within its institutional context. Once the prototypestage of a model is passed, a modelling tool must offer useful insights at realistic researchcosts (data collection and data treatment, human resources needs), and results must becommunicated such that it is accessible to interested parties, without hiding uncertainties.

Appendix B

EDIC Sector Routing Model For Irrigation

B.1 Introduction to the EDIC model

The sector irrigation model EDIC is a Node-Link-Network (NLN) model that quantifies waterflows between irrigation sectors, and parameterizes cyclic flows within sectors. The NLN wasdeveloped through a collaborative research project of the Chilean institutions EDIC and CEDEC(MOP 1992), for an irrigated area in the 7th province of Chile. The aim was to estimate the ef-fect of irrigation activities on the water flows and return flows within a catchment of the Maule,Putagan and Longaví Rivers. Irrigation is managed in sectors and water is allocated to the ir-rigation sectors, from where it is distributed to the water users–the farmers. On-field irrigationefficiency is parameterized with measured data. Direct reuse is assumed to be proportional tothe on-field efficiency parameters, while return flows incorporate an additional calibration factor.Return flows and reuse allows for the estimation of watershed level efficiency. The model wasextended and balances were closed.

This technical annex reviews the history of the EDIC model and the scope of its approach. Itdescribes all model equations and processes in detail, as well as irrigation methods at field scale.Furthermore, it explains calibration parameters and strategy and the technical computation withinthe MP-MAS model.

Figure B.1 conceptualizes the micro interactions of the model for a single sector, under theassumption that all n farmers endow equal water rights 1

n. The model then abstracts from the

spatial order of the farmers, and assumes that return flows are proportional to the water uptakeof each agent.

B.1.1 Scope of EDIC approach and limitations

The original purpose of the model was to estimate the impact of a new canal in the Maulewatershed (Chile). The area modeled covers 670km2, with 5400 farm households (each withat least 2.5 HRB ), with a multitude of medium and small-sized irrigation canals. Key modelassumptions are:

• The research area is subdivided into irrigation sectors. Each sector receives inflows ac-cording to the water rights of its irrigators and outflows from other sectors (either surfaceor lateral). Return flows that re-enter the river and may be re-taken into the canal networkare included in surface flows.

13

14 APPENDIX B. EDIC SECTOR ROUTING MODEL FOR IRRIGATION

Figure B.1 — The EDIC model: A bucket irrigation model to describe water allocation between differentirrigation sectors and return flows between them. Return flows are the share of excessiveirrigation water that returns to the canal system. This graph shows five farmers, each ofthem entitled to use one fifth of the total available flow. Each may use some proportionalfactor bmore water than they would be able to without these flows. Note that mass balancesremain closed.

• An institution exists that regulates the water flows into the irrigation sectors such that theinflows match the water demands of the farmers. Thus, each irrigation sector only receivesas much water as is actually apply to the fields within it.

• The time resolution is one month.

• Return flows may be re-used within a sector during each time step. Thus, the actual amountof irrigation water is a factor (1 + b > 1) of the inflows assigned to an area. This factoris known to the regulating institution, which takes it into account when calculating waterrequirements.

Furthermore, NLN models are often used in conjunction with MP optimization techniques tominimize flows and costs related to flows, maximize benefits at nodes, or combinations thereof(compare Cai et al. 2007).

The model aims to capture both on-field (classic) irrigation efficiency and watershed level(neoclassic) efficiency explicitly. Calibration to measurement data provides a robust tool for es-timating the reused fraction of water, both for in-sector reuse and between-sector return flows

B.2. EQUATIONS AND PROCESSES OF THE EDIC MODEL 15

(see Molden 1997 or Perry 2007).

The model uses a monthly temporal scale. This means that both water shortages and waterabandunce at daily scales cannot be analyzed within this framework. Also, as very few floodingevents are responsible for most erosion, canal clogging, and thus require management to preventthe siltation of dams, monthly inflows need to be pre-processed to reflect the amount of wateractually available for irrigation.

Secondly, soil properties such as elevation and moisture are not reflected within the model.Instead, the model uses effective precipitation at sector scale, which incorporates these. Worse,these processes are independent of soils for all irrigation methods, as the whereabouts of waterused within irrigation is pre-determined by input data. This is equivalent to the assumption thatall soils are processed by the irrigator, to match a typical slope and consistency for each irrigationtechnology1.

Finally, many groundwater effects are disregarded in the model (i.e. no changes in thegroundwater level, no extraction from groundwater, rooting depth of plants is not relevant).Again, these effects may be parameterized - both by introducing new irrigation methods forspecific rooting types, and by modifying in-between sector flows.

B.2 Equations And Processes Of The EDIC ModelA lumped or empirical model may never contradict basic physical laws; neither water nor energyshould be created within the model, nor should unrealistic transfers in time and space occur. Suchconstraints can be fulfilled explicitly by stating balance or continuity equations, or implicitlyby selecting appropriate input parameters. The original EDIC study used measurement-basedparameterization for a set of irrigation methods, that were fine-tuned to ensure that no water was‘produced’ by the model. These tuned parameters ensure that water balances are maintainedboth at sector and field level.

Balance at sector level: The EDIC model defines in- and out-flows for each sector (see Fig.B.2). As in all balance models, these sum up to the change of mass within the sector (assumingan incompressible medium), where all water movements (through canals, rivers, groundwaterand by air) are regarded as flows indexed with i;∑

i

flowi = ∆SSj

where ∆SSj is the change in local water storage, primarily in soils. Within the EDIC approachthat uses a monthly time interval, we assume2

∆SSj ≡ 0

1If different soil characteristics are to be included into the model, then new irrigation methods should be intro-duced. Careful: those methods have to reflect certain relations among each other and with the between-sector flowcoefficients.

2The lack of both groundwater flows and changes in soil storage were key criticism of the EDIC approach, whichultimately led to the development of a newer model, MAGIC


Figure B.2 — A Flow chart of the EDIC model. In this chart, we assumed the equilibrium case, in whichinflows from freshwater Netfresh and other sectors Extinflow, together with internal reuseR, just satisfy plant water requirements.

The EDIC bucket model considers only net evapotranspiration WRnet,j = ET potj − Pj , wateruptakes from canals or other sectors, and surface and lateral outflows;

0 = Qj −WRnet,j − Extoutj

= Qj −WRnet,j − Extsurfacej − Extlateral

j − Extlossj (B.1)

with

Qj Total water uptake of sector jWRnet,j Net water demand of all plants in j, after reducingETpot by effective

precipitation PExtsurface

j Water that leaves the sector as surface runoffExtlateral

j Water that leaves the sector as lateral flowExtloss

j Irrigation water lost to groundwater or out-of-model area


Outflows Extj: Furthermore, the EDIC model assumes that outflows depend upon two factorsβj and γj , and flow from sector j into other sectors k;

Extsurfacej = βj D′

j (Assumption 1a) (B.2)

Extlateralj = (βj + γj)D′

j (Assumption 1b) (B.3)

Extlossj = ζj D′

j (B.4)

with

D′j The amount of water actually applied in sector j to irrigate

βj Factor on irrigation water that goes into surface waterγj Factor on irrigation water that directly enters lateral waterζj Fraction of irrigation water that is lost as percolation evaporation

within sector, or as lateral outflows outside of the model area.

The share of outflows from sector j that are reuseble in sector k are computed with additionalparameters ∂jk for surface return flows, and ejk for lateral return flows:

RF surfacejk =

∑k

∂jk · Extsurfacej (B.5)

RF lateraljk =

∑k

ejk · Extlateralj (B.6)

(B.7)

with

∂jk Fraction of Extsurfacej that flows from sector j to kejk Fraction of Extlateralj that flows from sector j to k

Water uptakes Qj of a sector are composed of a sector’s share of external freshwater inflows,and of return flows from upstream sectors. Freshwater inflows may origin from mountain rivers,from dams or from deep groundwater. Net freshwater inflows of a sector j are those availablefor irrigation in one sector according to its accumulated water rights, after abstraction from itssources. The model assumes that net water uptakes of each sector is regulated by some institutionto exactly match the irrigation requirements in j, and that return flows are taken into accountwithin such regulation. Under- or over-supplies may occasionally occur, but do not effect thekey routing parameters.

Netj =∑i

WRij ·Qriver,

where Qriver is the water taken out of the river at point i into the canal system, and WRij are theaccumulated water rights of all farmers in sector j to inflow i.


Water uptakes Qj also include return flows from other sectors k 6= j Extinflows,k. Theseflows comprise surface flows, and near-surface (or lateral) flows:

Qj = Netj + Extinflows,j = Netj +∑k

(RF surfacejk +RF lateral

jk )

= Netj +∑k

(∂kj βk + ekj(βk + γk)) ·D′

k (B.8)

Note the revised order of indexes in ∂kj and ekj , which means from k into j.

Water available for irrigation: The amount of water Davailj available to irrigate sector j is

determined by water uptakes Qj and the internal reuse of water due to inefficient irrigation, Rj .It is assumed that Rj is proportional to the sector’s water uptakes:

Davailj = Qj +Rj ≡ Qj(1 + βj) (Assumption 2) (B.9)

Again, the same factor βj that defines outflows from sector j is used. Return flows can then berelated to the water applied:

Rj = Davailj −Qj = Davail

j −Davailj

1 + βj= Davail

j ·(

βj1 + βj

)(B.10)

Precipitation and effective rainfall: Crops are supplied with water by rainfall (precipitation)and when this is insufficient to meet plant water demand, by irrigation. A portion of the rainwater percolates beyond the root zone of the plants and another flows away above the soil assurface run-off3. These portions are not available to plants. The remaining portion is called ef-fective rainfall (Brouwer and Heibloem 1986). If rainfall is high, a relatively large portion of thewater is lost to deep percolation and run-off. In many countries, a location-specific formula wasparameterized, which takes into account rainfall reliability, topography, prevailing soil type etc.The FAO authors suggest using a fixed table to correct real precipitation to effective precipitationwhen there are no local data or formulas available.

Plant water demand and irrigation water: The net amount of irrigation water required byall plants in the sector j, WRnet,j , is potential evapotranspiration minus effective precipitationpreceff ;

WRnet,j = ET potj − preceffj =

∑act

ωact,j(ETpotact,j − prec

effact,j) (B.11)

for all plant species i in j, weighted with its area ratio ωact,j in j. Within the EDIC model,precipitation that does not directly affect plants but replenishes neighboring soils is disregarded(EDIC has no soil storage!)4

A factor for irrigation efficiency estimates on-farm water losses. The intermediate water demandis then defined as

Dinterj = WRnet,j/ηj (B.12)

3Even though not explicitly considered in this model, a further portion may be absorbed by dry soils below thewilting point

4This portion of rain should be regarded when extending EDIC to consider soil storage.


where ηj is the averaged irrigation efficiency factor in sector j. If disaggregated, this becomes

Dinterj =

∑act

ωact,j(ETpotact,j − prec

effact,j)/ηact,j (B.13)

which defines the field-level irrigation efficiency for a sector ηj as

ηj =

∑act ωact,j (ET potact,j − prec

effact,j)∑

act

(ωact,j (ET potact,j − prec

effact,j)/ηact,j

) (B.14)

Irrigation water actually applied: The total amount of water actually applied in sector j iscalculated from the net plant water demand Net and an "averaged" irrigation efficiency factorηj ∈ [0, 1], which is determined by the irrigation methods used in j. This value D is compared tothe actually available water Qj(1 + βj) to form D

′j;

D′

j = min(Dinterj , Davail

j ) (B.15)

The water actually consumed by plants, called "water demand satisfied" WDS as in the EDIC

study, is the part of the plant water requirement that is met through irrigation (in the same unitas water demand):

WDS = WRnet,j ·D′j

Dinterj

(B.16)

This value, or a time-weighted average of the ratiopreceffj +WDS

ET potj

, is then used to estimate plant

growth as well as yields. 5

Reuse factor U: The internal reuse factor U of irrigation water actually applied Dj can becalculated from (B.9) and (B.15). It is the proportion of water applied to the field that is actuallyreused. We can define U as a ratio of water uptakes and actual irrigation quantity D′j , and usingeq. (B.9) follows:

Uj ≡Qj

D′j

=1

1 + βj(B.17)

The balance and irrigation efficiency η as a dependent function. The irrigation system isdefined as being closed, if all sectoral water uptakes are fully used for irrigation, and plant waterdemand is fully satisfied. This situation reveals how efficiency factors of irrigation methods re-late to the reuse factor βj and γj:

D∗j ≡ Davail ≡ Dinterj (Assumption 3) (B.18)

We can also define εj =∑

k ejk and δj =∑

k ∂jk. Thus, (B.2) and (B.3) simplify to

Extsurfacej = δj βj D

∗j

Extlateralj = εj (βj + γj) D

∗j

Extlossj = ζj D∗j (B.19)

5


Substituting equations (B.19) into water balance (B.1), and then substituting (B.15) for D∗j , weget the identity

ηj =1

1 + βj− δjβj − εj(βj + γj)− ζj, (B.20)

where the reuse coefficient Uj(βj) is expressed in βj .This equation reveals that water flows within EDIC are highly interdependent with parametersfor irrigation methods, as presented in subsection B.3. It means that the efficiency parametersof irrigation methods must be consistent with parameters determining the destination of returnflows and non-recoverable flows. Otherwise, the balances are violated and water may either be"produced" or "disappears" due to a numerical fallacy.

Balance and total losses within the sector: Total losses result from the balance of each sector,which is the difference of inflows into j and its outflows, which is then solved for ζj:

Extlosses,j = ζj Dj (B.21)

= Qj − ηj Dj − Ext surfacej − Ext surface

j

ζj =1

1 + βj− ηj −

∑k

∂jk βj −∑k

ejk (βj + γj) (B.22)

As mentioned, these losses comprise both deep percolation and surface outflows outside themodel area, which are not distinguished further in this model.

Capturing external losses within the outflow coefficient ejj: To ensure that all flows areincluded in the water balance without introducing a new variable, we can define that losses Lto deep groundwater within sector j are included within outflows Extsurfacej and Extlateralj . Thesimplest way to do this is to include losses into the parameter ejj , as outflows that remain insector j. This little re-interpretation gives us a closed system, without undermining the modelstructure6.

Extlossj = ζj D′

j ≡ ejj (βj + γj) D′

j + ∂jj βjD′

j

thus

ejj =ζj − ∂jj βjβj + γj

(B.23)

The equation relates ejj , ∂jj and losses ζj . The new coefficients ejj , djj can be interpreted as theshare of outflows from j that are lost and not available to the system. ∂jj might include flows toareas not considered in the EDIC model, and ejj takes care of groundwater losses.

Closing the balance: In a simpler form, one may also plot eq. more easily:

ηj =1

1 + βj− δj βj − εj (βj + γj) (B.24)

6In the original EDIC parameter tables, the diagonal entries for both ∂jk and ejk are zeros; groundwater lossesare not regarded in the EDIC study.

B.3. IRRIGATION METHODS AT FIELD SCALE 21

One can interpret ζj as having two components: one component, determined by ∂jj , is the shareof surface runoffs that cannot be recovered in the routing system, as it may flow into non-reusableareas where it evaporates. The other share, ejj , is the share that gets lost to deep groundwaterwithin the cell, as it is formulated as subsurface flow within the sector, and to outside. Forreasons of simplicity, we assume that ∂jj ≡ 0, and ejj =

ζjβj+γj

. This relates outflows to lossesin at the same scale and unit.

B.3 Irrigation Methods At Field Level, And CoefficientsIrrigation methods are defined as on-field-structures that distribute water from canals to plants.Our economists partners use the terms "technologies" in broader sense, which describes a spe-cific activity. That activity is determined by the specific crop, the soil, all inputs including labor, the timing of input requirements, by machinery, and by the specific irrigation method that isdescribed here.

Irrigation method coefficients specify the whereabouts of water flows after applying irriga-tion water with such an irrigation method. Data was originally collected within the EDIC studyand complemented by irrigation experts (see Berger 2000). These whereabouts include pre-irrigation losses, such as losses to surface and groundwater from the canals and losses fromovernight ponding.

Irrigation water that is applied to the field may be evapotranspirated, or enter surface, near-surface (lateral) or groundwater (see table on page 21).

Method Flood Furrow Terras- Drip Improved Advanced Sprinklersing furrow furrow

Canal losses LC 10% 10% 10% 10.0% 10% 10% 10%lateral g1 6% 6% 6% 6.0% 6% 6% 6%groundwater l1 4% 4% 4% 4.0% 4% 4% 4%

Surface runoffs (night) b1 10% 10% 10% 10.0% 10% 10% 10%Irrigation water 80% 80% 80% 80.0% 80% 80% 80%

evapotranspiration η 24% 36% 49% 72.0% 40% 40% 64%surface b2 36% 28% 21% 0.0% 24% 24% 6%lateral g2 12% 10% 6% 4.8% 10% 10% 6%groundwater l2 8% 6% 4% 3.2% 6% 6% 4%

Surface coefficient B =∑bi 46% 38% 31% 10% 34% 34% 16%

Lateral coeff. G =∑gi 18% 16% 12% 11% 16% 16% 12%

Losses to groundwater L =∑li 12% 10% 8% 7% 10% 10% 8%

Evapotranspiration η 24% 36% 49% 72% 40% 40% 64%Sum (on-field balance) B +G+ L+ η 100% 100% 100% 100% 100% 100% 100%

Table B.1 — Irrigation methods, field-level irrigation efficiency and flow coefficients. Values from Berger(2000). The loss coefficients were added by the author.

On-field irrigation efficiency7 can be defined as the ratio from evapotranspiration because ofirrigation (ETact − preceff ) to total irrigation water applied D′act for a specific activity act thatdetermines the crop:

ηact =ETact − preceff

D′act

7See further discussion on the definition of irrigation efficiency in ch. 5.3.2


Furthermore, these coefficients combine into the on-field balance equation for a field using irri-gation method Mact of that activity:

1 = BMact +GMact + LMact + ηMact (B.25)

Relation between field coefficients and sector coefficients: The area share of an irrigationmethod M is use as weighting factor ωM,j:

ωM,j =

∑act τMact,M · Aact,j∑

actAact,j, where τMact,M =

{1 for Mact = M

0 otherwise(B.26)

Now, sector-level reuse coefficients βj, ηj, ζj and γj are estimated as weighted averages for allmethods M in a sector8:

βj = bj∑M

ωM,j ·BM (B.27)

γj = gj∑M

ωM,j ·GM (B.28)

Two new factors are introduced, as calibration factors for bjand gj . These factors allow to modifythe share of each sector’s return flow that remains inside as cyclic internal reuse (bj), which alsodirectly impacts on surface runoffs into neighboring sectors. The factor gj does not influenceinternal reuse, but also return flows to neighbouring sectors (as lateral flows).

Careful: Sector values of βj and γj have to meet sector-level the balance (B.4.3).

Total water losses at sector-level (groundwater, non-reusable fraction, weed evapotranspiration,. . . ) are at least as big as the total field-level losses:

ζj ≥∑M

ωM,j ZMact

Additional losses (cyclic flows that are not reusable or reused) then increase ζj , increasing itsdifference with Zj9.

Sector-average of field-level irrigation efficiency ηj . At sector level, all field variables on wa-ter flow quantities, namely irrigation efficiency, runoffs, lateral flows and losses, are aggregated.

8 In addition, a calibration factor may be introduced which allows to lower the share that is reused internally.9Comment Thorsten: Actually, from infinity consideration, the weighting function for sector-level efficiency ηj

does not use area, but rather water quantity: in a case of deficit (or supplemental) irrigation with inefficient methods,but with very little water, the impact on a sector-aggregate should also be little.

B.4. CALIBRATING THE EDIC MODEL 23

The average field-level irrigation efficiency within a sector, ηj , is aggregated at sector-level fromthe irrigation water applied by each farmer for each activity (and thus the irrigation method M ):

ηj =

∑hh∈j

∑act(ηact · IRRhh,act)∑

hh∈j∑

act IRRhh,act

)

The field-level irrigation efficiency ηj for a sector is distinguished from sector-level effectiveirrigation efficiency, which is the ration of irrigation water beneficially evapotranspirated to thetotal net water uptake Qj of sector j.

Sector-level effective efficiency η̃j is a unitless factor η̃j < 1, describing the share of irrigationwater that crops transform into evapotranspiration. With this definition, cyclic movement ofwater (internal reuse) becomes irrelevant, and only the final irrigation outcome at sector level ismeasured:

η̃j =

∑hh

∑actAhh,act · (ET realact − prec

effact )

Qj

. (B.29)

B.4 Calibrating The EDIC Model

B.4.1 Relevant BackgroundSummary On Relevant Processes And Variables The EDIC model was designed for two lev-els of analysis. The first level parameterizes interaction between irrigation sectors as return flows.The second level links sector-level processes and field- (or farm-) level processes to sector-levelaggregates of these. Especially the treatment of field-level irrigation efficiency ηact to sector-leveleffective efficiency η̃j , and the treatment of internal reuse within farms and within sectors is rel-evant.

Field-level efficiency is defined as the share of actually applied irrigation water that plantsevapotranspirate. To account for precipitation water uptake of plants, real evapotranspiration iscorrected by effective rainfall:

ηact =ET realact − prec

effact

IRR(hh,Mact)

At sector level, all field variables on water flow quantities, namely irrigation efficiency, runoffs,lateral flows and losses, are aggregated. The field-level irrigation efficiency for a sector ηj isaveraged at sector-level, using the irrigation water applied by each farmer for each activity andconsidering the irrigation method M :

ηj =

∑hh∈j

∑act ηact ∗ IRRhh,act

IRRj

with IRRj =∑

hh∈j∑

act IRRhh,act.

This field-level irrigation efficiency for a sector ηj is distinguished from sector-level effectiveirrigation efficiency, which is the ratio of irrigation water beneficially evapotranspirated by crops,


to the total water uptake Qnetj = IRRj/(1 + βj) of sector j, where βj is the actual internal reuse

share:

η̃j =

∑hh

∑actAhh,act ·max(0, ET realact − prec

effact )

Qnetj

.

The sectoral aggregatesBj andGj of field-level runoff coefficientsBM andGM are weightedaverages of irrigation method coefficientsM (see table on page 21). For averaging, the area shareof each activity is used10:

Bj =

∑actBMact ·

(∑hh∈j Aact,hh

)∑

act

∑hh∈j Aact,hh

,

For Gj , we respectively get

Gj =

∑actGMact ·

(∑hh∈j Aact,hh

)∑

act

∑hh∈j Aact,hh

,

Field-level losses ZMact,act of an activity with method Mact are defined as the share of water thatis not available for later reuse, because it is directly lost in the field:

ZMact,act = 1− ηact −BMact −GMact

Field-level losses Zact are accumulative. Thus, total losses ζj of sector j are greater or equal tototal field-level losses. In the same time, sector-level losses ζj can be computed from the sectorbalance:

ζj ≥∑hh,act

Aact,hh · Zhh,act (B.30)

∧ ζj = Qj −∑hh,act

Aact,hh · (ET realact − preceffact )− Extoutflows,j

with (B.31)Qj = Netj + Extinflows,j

Extoutflows,j = Netj + Extinflows,j

Using the model equations, the maximum water that can be recycled downstream is βj ·(Qj(1 + βj)) (Assumption 2, Eq. B.9). Return flow from sector j to k is parameterized with twovalues, ej,k and dj,k (coefficient for "surface flows" and "lateral flows" respectivley), which addup to one or less

dj ≡∑

k ∂j,k ≤ 1.0

ej ≡∑

k ej,k ≤ 1.0 (B.32)

These parameters control the share of reusable return flows that remains within the larger studyarea. If all return flows are reusable within the study area, then relations (B.32) become equali-ties.

10It could be argued to use, as weighting function, the quantity of irrigation water actually applied to each activityand method, instead of using the area. This would require iterative calculations though.

B.4. CALIBRATING THE EDIC MODEL 25

B.4.2 Calibration parametersTo ensure that overall water availability within each sector matches observations, the parameter-based EDIC model requires fine tuning. All calibration parameters are classified into three basictypes, and calibration ranges are identified, as changes of water available – partly from fixedlimits, partly from plausibility:

’Global’ tuning parameters’ are those parameters that affect all sectors equally.

Irrigation method parameters (return flows, efficiency, etc) are adjusted to local characteristics(e.g. because of soil permeability, inclination). The parameter BM affects the internal reuseas well as the return flow . GM only affects return flows. Finally, leaving field-level losses1 − ηM − BM − GM = ZM ≥ 0 may account for weeds, for non-useful evaporation or forpercolation to ground water.Calibration range:

• 5% – 10% for efficiency ηM• 5% – 10% for BM +GM ,

• and 5% – 10% for losses ZM .

Irrigation efficiency η for all irrigation methods may be varied if field-level data is given, to takeinto account within-farm reuse. Other method parameters are adjusted accordingly. All methodsneed to be treated consistently.Calibration range: 10% – 15%

The parameterization of the effective precipitation formula may also be modified, if reason existthat the FAO formula is not justified - especially because of inclination, soil surface characteris-tics (crusts) and soil treatment´, but also because of sudden and infrequent rainfall events.Calibration range: 0% – 15%, depending on month and year, but also on how extreme physicalsoil conditions are.

Sectoral tuning parameters are parameters that affect water availability in one sector only.Three options exist here:

Modify the paths for return flows between sectors, and the quantity of it, through parametersejk and ∂jk. We recommend to interpret return flows through canals as surface flows, andtopography-determined natural flows as lateral flows.Calibration range depends on total relation Aj

Akbetween upstream/downstream sector and on the

length and hydrological importance of shared boarders.

If upstream sector is irrigating a large area, and if the downstream sector is small, then thevariation range may be very large, otherwise smaller.

Modify the internal reuse (internal losses) of the sector, using bj and gj within the allowed range(0 < bj < bmaxj / 0 < gj < gmaxj ). Here, enlarging βj = bj · Bj enlarges both internal reuse andreturn flows to downstream sectors, and decreases the water demand from the sector11, whileγj = gj ·Gj only enlarges return flows.Calibration range: Depending on bmaxj : 0%−−100 · bmaxj %

11Net water demand of sector j is Q′j =PWDj/ηj(1+βj)


At sector level, canal losses may be introduced to scale down water availability. Depending onparameters bj and gj , this might cause additional return flows elsewhere.Calibration range: 0% – 25%, depending on month and year, but also on the canal properties ofthe area.

Further data tuning If (and only if) the values mentioned are not capable of producing properresults, then the following options remain.

• Globally, all or single inflow volumes may be scaled down proportionally or using a flow-dependent weighting function. This scaling corresponds to the uncertainty in aggregatingdaily flow values to monthly flow values, because the sediment load after precipitationevents makes large flows not usable for irrigation.Calibration range: 0% – 50%, depending on month and year

• Also, the monthly value of water equivalence for one or all rivers may be changed.Calibration range: 0% – 50%, depending on each month and year

Both options result in a decrease of water availability for the whole region.

B.4.3 Calibration stepsStep 1: Ensure consistency of sector-level balances with EDIC parameters βmaxj and γmaxj

Water balances at sector-level then needs to be calibrated, to ensure that field-level losseswithin the sector remain consistent even with high reuses.

To ensure that relation (B.30) and equality (B.31) are fulfilled, two calibration factors bj andgj are available that connect field-level parameters BM and GM with sector-level cyclic reuseparameters βj and γj (see Eq. B.27 and B.28). This first calibrating step ensures that water isnot "generated" within the model through miss-parameterization, by adjusting bj and gj below amaximum value:

0 ≤ bj ≤ bmaxj ≤ 1.0

0 ≤ gj ≤ gmaxj ≤ 1.0 (B.33)

Step 2: Matching sector water availability with data. Within the parameter parameter rangesassessed in (B.33), further fine tuning may be required, with the aim is to reproduce observedwater availability. Calibration proceeds from global to local parameters, as described in the nextsection.

Appendix C

WASIM-ETH and TechnicalImplementation of Water Rights

For coupling with WASIM , the meaning of inflows are re-interpreted. The inflows in the EDIC

specification were rivers entering the study area, but for the purpose of coupling are internal waterflows through irrigation canals. The second difference is that the full inflows are distributed toagents, so factors µr and λ are dropped. Instead, the routing and the calculation of how largeinflows are is determined within WASIM-ETH. Within MP-MAS , the same data structure anddata formats are used: water rights are specified as shares of inflows. Equivalent to the EDIC

model realization of water rights, rights can be specified both at sector level (∑

sWRj = 1) andat agent level (

∑aID WRaID = 1).

Two different specifications of the WASIM-ETH canal model exist: these are different inter-pretations of inflows. The first one pools all irrigation canal flows, regardless of the origin, intoone sub watershed. Thus, the total flows entering a sub watershed are first added and then re-distributed to those sectors/farmers within the sub watershed. The number of inflows Nin equalsthe number of sub watersheds with irrigation. As second alternative, information about the riveras prime source is maintained. The total number of inflows thus increases to Nin = Nsub ·Nrivers.

In this section, the concept of WASIM abstraction is summarized first, and how we appliedit to the study area. For details, we refer to the manual (Schulla and Jasper 2007). Then, weexplain how the routing within the area is realized, and how data are treated for it.

Abstractions and inflows in WASIM-ETH

Three interventions into the WASIM-ETH routing module are relevant. Internal bypasses areflows from one pour point to another, which are abstracted from a river at one time step, and re-injected into another pour point the next time step. The amount of flows is not directly accessibleand controlable after each time step, so this option - though simplest - was not used.External inflows enter the system from outside, and abstractions leave the system. In our model,we have realized routing with abstractions from one location and corresponding inflows to an-other. Inflows are read from file, and abstractions are written to file.

(Inter alia), abstractions are specified with three parameters: QRmin is a threshold for be-ginning the abstraction, the minimum flow of the river which always remains in the river. Thesecond parameter α determines, which share of the flow beyond QRmin is abstracted, until themaximum canal capacity QCmax is reached (Fig. C.1) Technically, WASIM-ETH first servesirrigation water. Then, abstractions are served in the order of appearance in the control file, until

27

28APPENDIX C. WASIM-ETH AND TECHNICAL IMPLEMENTATION OF WATER RIGHTS

Figure C.1 — Definition of abstractions

all abstractions were satisfied, or until the minimum restriction of the river constraints.

Realization of irrigation canals in WASIM-ETH

Farmers hold water rights which are abstracted from rivers at ’abstraction points’ - bocatomas.There, water is withdrawn form the river into main canals, then through minor canals and finallyto the field.

Abstractions from sub watershedsas absolute rights (a) and as localpercentages of river flows (p)

Figure C.2 —

Within WASIM-ETH, all abstractions are withdrawn in the pourpoint of a sub watershed. Several withdrawal points for irrigation wa-ter can be defined: from ground water (if specifically specified), fromreservoirs, or from the main river (in the pour point). WASIM balancesall flows in the pour points: water from surface routing, base flow, in-flows, irrigation withdrawal and external abstractions (Fig. 7.2). Forsurface irrigation, we realize canal abstractions from the river for theirrigation of one field by abstracting water from the sub watershed inwhich the canal uptake point (bocatoma) is located. This water is thenre-injected into the sub watershed in which the field is located.

The quantity of river water withdrawn into abstra_S_T is calculatedusing water rights registries. WRUaID,r [Units], which are shares ofone river, but do not add to 100 or 1. Additional to the agentID andriverID, also the source watershed S in which the bocatoma of thecanal is located, is used to determine canal parameters.

First, the maximum abstraction quantity can be defined for eachmonth, using also water equivalence values WREr,m [liter/sec, unit]:

QCmaxr,S,T,m =

∑i∈T

WRUaID,S,r ·WREr,m (C.1)

For cases with sufficient water, the minimum river threshold parameters was set to QRmin = 1.0[m3/sec].

As first version, these amounts are fully abstracted from the river. Canal abstractions definedby α = 1, QCr,S,T,m and QRmin are written into a file named abstra_S_T , specifying the sourcewatershed (S) of abstraction, and the target watershed (T ). The total quantity of irrigation waterapplied in the target watershed, IRRT , cannot exceed the sum of total canal flows

IRRT ≤∑S

abstra_S_T

29

A second, more complex realization defines river abstractions directly as percentages of the river.Using a routing diagram, WASIM sub watersheds were alligned in Strahler order (CITE). Waterrights WRUr [units], stated as shares to river flows, are first stated as percentages of the totalriver inflow that is abstracted from a watershed S as aS ∈ [0, 1] [% of total river inflows], andthen translated into percentages to actual river flows at the canal uptake point, as pS ∈ [0, 1] [%of local river flow].

For a sub watershed S = B of a river r = R (Fig. C.2),

aB =WRU(S≡B,R≡R)∑

(r∈R) WRUr(C.2)

Then, this absolute percentages to the river inflows were transformed into percentages oflocal river flow pB to flows in uptake point B [ pB ∈ [0, 1]]. By hand, all absolute percentages ofdownstream sub watersheds, aD, were added beforehand, analog to eq (C.2). The share to localriver flow in B is then

pB =aB

aB +∑aD

This local percentage defines the canal constant α ≡ pB.The routing diagram of case study (Figure 7.3(b)) shows both the sub watersheds, as nodes,

and the rivers r that fall under the responsibility of one Junta de Vigilancia, as boxes. The fullrouting graph is given on page 146, Section 7.3.2. Parameters are listed in Table C.1.

30APPENDIX C. WASIM-ETH AND TECHNICAL IMPLEMENTATION OF WATER RIGHTS

Source sub water-shed

Target sub water-shed

Minimum riverflow

Percentage of river Maximum canalflow

[m3/sec] [1/1] [m3/sec]

21 21 1.0 0.02 0.2622 22 1.0 0.27 3.0523 1 1.1 0.85 6.9723 23 1.1 0.04 0.3223 9999 1.1 0.11 0.9431 1 1.0 0.18 1.3531 3 1.0 0.08 0.5831 12 1.0 0.01 0.0831 22 1.0 0.27 2.0131 23 1.0 0.4 3.0031 31 1.0 0.05 0.3731 43 1.0 0.02 0.1542 1 11.0 0.37 93.1442 12 11.0 0.5 38.1142 23 11.0 0.06 15.6842 31 11.0 0.01 1.3442 42 11.0 0.01 3.6642 43 11.0 0.04 9.6042 80 11.0 0.21 53.2143 1 2.8 1 9.4551 9999 489.4 1 271.8651 12 10.8 0.49 164.3851 53 10.8 0.04 13.0251 80 10.8 0.07 22.8351 90 10.8 0.24 82.2751 91 10.8 0.09 30.6951 92 10.8 0.07 25.1553 12 7.7 1 3.6560 22 1.0 1 10.0080 1 1.0 0.86 0.1680 12 1.0 0.13 0.0280 23 1.0 0.01 0.0091 91 1.0 0.15 17.4891 12 1.0 0.85 2.99

Table C.1 — Table of irrigation water abstractions (source sub basin to target sub basin), created fromwater rights registries. Targets named 9999 are situated outside of the study region.

Appendix D

Technical Description of Coupling andSource Code

D.1 Technical description of MP-MAS data handling

D.1.1 Transfer of Spatial Variables to AgentsThe class landscape receives spatial input data and central for the transfer of grid data (classgridcell) to the spatial units owned by individual agents (class parcel).

To reduce source code complexity, the class landscape was ‘wrapped’ and is now accessthrough a single function1 rather than separate with functions for each variable.

Figure D.1 — The class CropMixClass con-nects the decision matrix with thespatial maps, using lists of pointersto parcels. They are classified by soiltype, and by cropping activitiy.

Managagement of spatial data in MP-MAS.Spatial data is read by the catchment class. Itis dissected and passed along to the sectors,which store spatial information in the land-scape class, in the data of each grid is hold bythe container class cell.

From this data container class cell, farmagents are first equipped with their assets, es-pecially their land and soil types. In the orig-inal MP-MAS model, all information was firstcopied into a class parcel, which is stored asa list (an ordered collection of grid-like enti-ties). After all information was processed andpassed on to the parcel class, the landscapewas deallocated to free its memory.

For model applications with spatial inter-actions, the landscape class is maintained,because raster data can easily be conducted through to cells, and ultimately to parcels, withinthe existing data handling routine. Also, data can be updated from parcels to cells2 (see FigureD.2). The third option directly connects the solution vector of the LP with the landscape. It

1getContentFromCell(int row, int col, ContentType cont)2copyContent_Parcels2Landscape (ContentType cont)

31

32 APPENDIX D. TECHNICAL DESCRIPTION OF COUPLING AND SOURCE CODE

is used to export the outcomes of decisions, or to import data into the decision matrix directlyCropMixClass.

Grid-level or sector-level handling of spatial data. Data may either be handled heteroge-neously at grid-level, or it may be homogenized and stored as single value, at sector level asmeso-scale spatial holon. If a parcel requests information from the landscape 3 – depending onthe content type, data either read from the cell specified, or taken directly from the sector. Thishandling enables data handling at different aggregation levels. In a similar way, data that wasread from a catchment-level raster map is either stored at grill cell, or aggregated and stored atsector level. Aggregation functions implemented are mean and median. Within MP-MAS, twolevels of spatial handling exists. The first uses maps of grids, which are read in ASCI format butcan also be imported into any GIS program easily. These maps are stored within the landscapeclass, each grid cell as one cell object, and each data as one attribute to this class.

Secondly, agents own a chained list of parcels. These parcels have few spatial properties,such as distance to home, but also remember the cell they originate from. Thus, spatial data canbe imported into MP-MAS through the landscape, and then copied into the parcel.

In non-spatial mode, the landscape is deallocated directly after initialization, and only keptin spatial mode. For this reason, parcels own (and thus duplicate) all properties.

In spatial mode, parcels can copy their information back into cells, and then export it back togrid maps, which may then be used for coupling.

Additionally, spatial data may be kept at grid resolution, or as aggregate at sector resolution.This decision is currently hard-coded, in two functions

• raster = getSpatialInfo_Content(ContentType)

• setSpatialInfo_Content(ContentType, raster)

If data is to be stored at sector level, such as precipitation, then the mean value is computedfrom all non-nodata entries in the map, and stored as double. If later cell-level information isrequested through <getSpatialInfo_Content(int row, int col, cont)>, sector-level average is pro-vided.

An external input file is used to define which data should be stored at sector level, or at celllevel (see page 120).

Connecting spatial data and the decision matrix. The outcomes of agents’ decisions arestored in the solution vector. A subset of these entries correspond to cropping activities, the con-nection of which is defined in the CropWat.dat input file. This input file is used to referencegrowth information into the decision matrix (yield potential, irrigation requirements, or modeloutcomes such as growth/water deficit, and yields).

The heuristic that is initially used to connect the LP decision to parcels is outlined in sectionD.1.1. Technically, the result of this allocation routine is a stack of the type CropMixClass,one for each soil type. Each member of the CropMixClass contains a stack of ParcelPointerList,one for each cropping activity. The length corresponds to the area that is cropped, and each mem-ber points to the parcel that is used for it (see Figure D.1).

3getContentLandscape (ContentType cont, int row, int col)

D.1. TECHNICAL DESCRIPTION OF MP-MAS DATA HANDLING 33

From agents to parcels:Reallocating plots to grids The agent’s decision takes place at the level of soil suitibility or‘Response Units’ (RU, see Section 5.2.1). All parcels are spatially referenced and also to an RU,while activities are only reference to an RU. Thus, activities must be re-assigned to parcels. Thisis also done with the CropMixClass. Because activities are given in rational areas, they cancover areas smaller than a parcel and rounding errors occur.

To minimize rounding errors, the following heuristic is used: activities are distributed toparcels until only below-parcel size rests remain. Spatially, high irrigation groups are locatedas close to the farm as possible, which is in line to practical findings of field research. Then,those activities with the largest rest are assigned until the total area assigned equals the total areacropped. Very small plots and small remainders are thus lost.

This resolution error is small if remainders are only a small proportion of total fields. Espe-cially if the farming population consists of many very small farms, it is reasonable to increasethe spatial resolution.

All other attributes (irrigation technologies and the irrigation column applied) follow theattribution of activities.


Figure D.2 — Classes and functions to transfer spatial data, as input or from external model. Spatialinformation in MP-MAS exists twice: as grid maps, and as a list of parcels.

D.1.2 The handling of TimeWithin the model system, time is governed by a time handler class, which holds both modeltime (time steps since model initialization) and real time equivalents (years, month, days). Aglobal time handler maintains the forward-stepping characteristic of real time. Local models areinitialized with a local copy of the time handler, which may run to estimate decision outcomeslocally, and are deallocated then.

The time handler knows two basic functions:

• th.nextMonth(), and

• th.nextPeriod().

In addition, for spinup model runs (repeated model runs without updating of anything but expec-tations), it can be reset to the start time:

• th.resetAllDatesToStart().

Any action of the Time handler is written to the log file (invoked with parameter -L). Further,local copies of the time handler are instantiated with a copy constructor, but a new name has tobe to the time handler to avoid confusion in log files. These local copies can be set to the start ofspecific years with

• th_local.resetToStartOfYear(int y);.

D.2. THE SEQUENCING WITHIN MP-MAS: SOURCE CODE 35

D.2 The sequencing within MP-MAS: Source codeAn edited extract of the most relevant MP-MAS source code is given here.

Listing D.1 — The annual sequence within MpMas1 / / EXPECTATIONS FOR YEAR (ON WATER, PRICES e t c )2 / / 1 ) pe r fo rm i n v e s t m e n t d e c i s i o n3 / / 2 ) pe r fo rm p r o d u c t i o n d e c i s i o n4 / / −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−//5 w a t e r s h e d . Ag en t s Do Ex pe c t a t i o nA nd P l an n i ng ( t imeHand le .GETYEAR( ) ) ;6 / / [ . . . ]7

8 / / −−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−//9 / / HYDROLOGICAL MODEL & MONTHLY LOOP

10

11 / / Annual p r o c e s s e s12 w a t e r s h e d . coupl ingHydrologyWasimAnnual ( t imeHandle , o u t f i l e s ) ;13

14 / / −−−−−−−−−−−− START : MONTHLY LOOP −−−−−−−−−−−−//15 f o r ( i n t m = 0 ; m < t imeHand le .MONATE( ) ; m++)16 {17 / / Pe r fo rm f u l l r o u t i n g , i n c l u d i n g b _ l i s t e : : w a s s e r _ p e r i o d e _ r e f a c t u r e d18 / / . . . I r r i g a t e s f o r e v e r y month , and t h e n c a l l s e i t h e r19 / / . . . TDT t r a n s f e r f u n c t i o n s o r f i l e −based SAVE20 / / . . . t o communicate wi th WASIM / C o n t r o l l e r . I n t e r n a l l y ,21 / / . . . c a l l t o EDIC r o u t i n g ’ w a t e r s h e d . w a s s e r _ p e r i o d e ’22 w a t e r s h e d . coupl ingHydrologyWasimMonthly ( t imeHandle , o u t f i l e s ) ;23

24 t imeHand le . nextMonth ( ) ;25 }26

27 / / p r o d u c t i o n r e s u l t s28 w a t e r s h e d . a g e n t s C o m p u t e P r o d u c t i o n ( ) ;29

30 / / a g e n t s make income s t a t e m e n t and d e c i d e on consumpt ion / s a v i n g s31 w a t e r s h e d . agen tsCompute Incomes ( ) ;


Listing D.2 — Monthly coupling1 vo id r e g i o n : : coupl ingHydrologyWasimMonthly ( TimeHandle& t h _ c o n s t )2 { / / I n i t i a l i z e v a r i a b l e s3 Ras te r3D Map3D_dry , Map3D_irr , Map3D_delta ;4 //−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−//5 / / . . . WASIM DRY RUN i s execu t ed , and ended6 //−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−//7

8 boo l f l a g _ s u p p r e s s W a s i m A f t e r w a r d s = f a l s e ;9 s t r i n g fn_append = "DRY" ;

10 / / . . . c a l l c o u p l i n g f o r one i t e r a t i o n s t e p . I f l a s t s t e p , t h e n sendi r r i g a t i o n map t o C o n t r o l l e r and re−run wasim

11 c o u p l i n g _ O n e S t e p ( t h _ c o n s t , fn_append , f l a g _ i s L a s t C o u p l i n g S t e p , Map3D_dry ) ;12

13 //−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−//14 / / . . . . i r r i g a t i o n run i n WASIM . . .15 //−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−−//16 / / S u p r e s s e s second s e n d i n g of i r r i g a t o i n map17 f l a g _ s u p p r e s s W a s i m A f t e r w a r d s = t r u e ;18 / / Append t o f i l e n a m e s when s t o r i n g d a t a19 fn_append = " IRR " ;20

21 / / . . . c a l l c o u p l i n g f o r one i t e r a t i o n s t e p . I f l a s t s t e p , t h e n sendi r r i g a t i o n map t o C o n t r o l l e r and re−run wasim

22 c o u p l i n g _ O n e S t e p ( t h _ c o n s t , fn_append , f l a g _ s u p p r e s s W a s i m A f t e r w a r d s ,Map3D_irr ) ;

23

24 / / Add f u r t h e r i t e r a t i o n s , o r loop ! A l l b u t l a s t i t e r a t i o n s t e p w i l l g e tf l a g ’ f l a g _ i s L a s t C o u p l i n g S t e p == f a l s e ’

25 / / c o u p l i n g _ O n e S t e p ( t h _ c o n s t , fn_append , f l a g _ i s L a s t C o u p l i n g S t e p , Map3D_irr) ;

26

27 / / Compute d i f f e r e n c e between l a s t i r r i g a t i o n run and dry run , o r betweeni t e r a t i o n s t e p s )

28 boo l f l a g _ c o m p u t e D e l t a = f a l s e ;29 i f ( t r u e == f l a g _ c o m p u t e D e l t a )30 { s t r i n g f n _ d e l t a ="DELTA " ;31

32 Map3D_delta . s u b t r a c t ( Map3D_irr , Map3D_dry ) ;33 / / . . . Upda tes f i l e names and save34 s t r i n g fnS = upda teF i l enamesWi thCon tType ( Map3D_delta , f n _ d e l t a ) ;35 Map3D_delta . w r i t e T o F i l e s ( fn ) ;36 }37

38 / / Update Wasim r e s u l t s t o Landscape , and t h e n t o p a r c e l s , send map t oc a t c h m e n t > l a n d s c a p e > c e l l > p a r c e l

39 i n t numLayers=Map3D_irr . g e t L a y e r s ( ) ;40 f o r ( i n t z = 0 ; numLayers ; z ++)41 { / / Read c o n t e n t from l a y e r42 Conten tType c o n t = Map3D_irr . g e t C o n t e n t ( z ) ;43

44 / / Check i f l a y e r c o n t e n t i s i n t e r p r e t e d a t s e c t o r l e v e l o r a t c e l ll e v e l . i f NOT e v a l u a t e d a t s e c t o r l e v e l −−> w r i t e d a t a t o c e l l ! [ . . .

r e a d from i n p u t f i l e "## _ S p a t i a l E x p o r t I n f o " , t h i r d colum ! ]45 boo l f l a g _ t o C e l l =! s p a t i a l E x p o r t I s A t S e c t o r L e v e l ( c o n t ) ;46

D.3. DOCUMENTATION OF MP-MAS SOURCE CODE 37

47 / / Pa s s p o i n t e r t o r a s t e r −l a y e r , and w r i t e t o l a n d s c a p e48 r e g i o n . c o p y R a s t e r 2 L a n d s c a p e ( Map3D_irr . g e t P o i n t e r t o L a y e r ( z ) , con t ,

f l a g _ t o C e l l ) ;49

50 / / Update v a l u e s from l a n d s c a p e c e l l s t o p a r c e l s w/ b _ l i s t e51 r e g i o n . c o p y C o n t e n t _ L a n d s c a p e 2 P a r c e l s ( con t , f l a g _ t o C e l l ) ;52 }53 }

D.3 Documentation of MP-MAS source codeA documentation to the full source code is on-line, created with the DOXYGEN environment incombination with graphical .dot, as exemplified in Figure D.3. It can be accessed via internet4.

��

��

��

��

��

��

��

��

��

�� !"#$��

%�&��' (�'(�'))(�%%�*+��

Figure D.3 — Example of source code documentation, see internet.

4https://www.uni-hohenheim.de/mas/documents/DOXYGEN/mpmas/html/index.html

https://www.uni-hohenheim.de/mas/documents/DOXYGEN/mpmas/html/index.html


D.4 Details on data flows and protocols

Figure D.4 — Detailed description of data exchange between MP-MAS and WASIM-ETH. The left sideshows some relevant MP-MAS processes, most importantly the yearly and monthly timeloop. The right side depicts the two monthly WASIM-ETH runs (dry and with irrigation)

This section describes the data exchange between MP-MAS and the WASIM-ETH wrapperin a bit more details. Currently, there are five data transfers, each with its specific data formatsand translation/transformation functions (protocols). Figure D.4 depicts the points and directionsof data exchange. Subsequently, each protocol is described, with input data and formats, internalfunctions, and output data.

Protocol 1 is the initial expectation of agents with regards to water availability over the fullyear, before doing the cropping decision. This data is read from a monthly file5. For each month,a file is requested called ‘inflow_M.mat’. The file should contain one ID for each inflow thatreferences to the IDs6, and a double value for the water flow in the canal, in [m3/s].

Protocol 2 is the transfer of a MP-MAS map of cropping´activities into the format that WASIM-ETH land use requires. MP-MAS generates a raster map, in MP-MAS resolution, with the ac-tivity ID in each grid cell. WASIM-ETH requires a binary file of a raster in WASIM-ETHresolution, with an ID corresponding to the control file template ([landuse_table]).

5[SCEN]/input/expectations6[SCEN]/input/dat/[##]EdicRiverFlows.dat

D.4. DETAILS ON DATA FLOWS AND PROTOCOLS 39

Using data base functionalities, every MP-MAS cropping activity is translated into a Crop andthen into a WASIM-ETH landuse class, for which physical parameters are defined (rootingdepth, ETpot, etc).If required, the MP-MAS activity raster is first re-scaled to WASIM-ETH resolution, and WASIM-ETH uses a map of coarse-scale land use IDs.

Protocol 3 is the transfer of water abstractions from WASIM-ETH to MP-MAS. This processis done in a multi-step procedure:

1. (transcription) WASIM-ETH writes daily abstractions from rivers abstra_i_j fromall pour points i to a target j, where j is either the ID of another sub catchment, or of anirrigation sector. Also, inflows from outside of the study area are added (inflow_i_j).

2. (translation) The first step is the transformation of WASIM-ETH river abstractions intoEDIC-type inflows to irrigation sectors, and options exist to perform this. River abstrac-tions are defined by its source sub basin and the sub basin where water is applied (target).Technically, water is abstracted from the source pour point and re-injected into the targetsub basin, and then – within WASIM-ETH – automatically taken from its pour point andapplied to the fields. In the simplest implementation option, all daily irrigation abstrac-tions are added for each target sub basin, and reported as irrigation water that is availableto MP-MAS. For details on the routing model within WASIM-ETH, see Uribe, Arnold,Arumí, Berger and Rivera (2009).

3. (translation) Daily WASIM-ETH irrigation water flows are aggregated to monthly flowsusing the median rule, because it filters out events with peak flows, e.g. after a precipitationevent, which are not relevant for irrigators.

4. The Sequencer sends all monthly median flows to MP-MAS , as a 2-column-matrix withinflow ID 7 and water flows. The unit is specified in WASIM-ETH control file template aswell as in the file InflowsKEY.txt, and [m3/s] is recommended.

5. MP-MAS receives that matrix of inflows from the Sequencer and passes it to all sub catch-ments. Sector-level water rights are defined as shares of total area of each sub basin agri-cultural land, so a rounding error occurs8 (Protocol 1).

Protocol 4 is the cell-wise information transfer from WASIM-ETH to MP-MAS . Here, allvariables defined in dataExchange.ini are read from WASIM-ETH binary files and passedto MP-MAS as a three-dimensional raster file of monthly values. Original resolution of MP-MAS

is retrieved with the rescaling matrix of protocol 2, and usage within MP-MAS is defined in theMP-MAS input file [##]_SpatialExchangeInfo.dat.

7In MP-MAS Version 1, this corresponds to the target of the abstraction files8For a more detailed model, the aggregation at target sector level can be avoided, which increases the number of

flows by a factor 9, and makes input file handling more painfull.


Protocol 5 is the transfer of MP-MAS irrigation decisions to WASIM-ETH irrigation formatsas used in the WASIM-ETH control file. MP-MAS attributes the water that is available tocropping activities which are spatially distributed, in [l/sec,ha]. To use the WASIM-ETH controlfile format, these absolute values, together with irrigation method that encodes for efficiency,were converted into an irrigation table and a map of irrigationTypeIDs that point to this table, asinputs for WASIM-ETH . Each irrigationTypeID contains information to the method, and to thecolumn that is applied to the fields every day. Technical constraints are

• each activity may have a different irrigation time line. Thus, the irrigation table should bespecific enough to resolve activities as one dimension.

• Even though agents might have different strategies, we are not aiming to model individualirrigation behavior (scheduling, etc). Instead, water application at coarse grid scale (1 −4km2 is reproduced, to model watershed-level dynamics.

• The number of MP-MAS activities is high, ranging around 1000. There are 8 irrigationmethods.

The following strategy is implemented:

1. Cyclic within-sector reuse cannot be computed within WASIM-ETH, because this modeldoes not capture grid-2-grid interactions. Cyclic flows are crossed out at sector level,which reduces the ‘sector-level effective per-hectare irrigation column’ [l/sec] that is ap-plied. Further, this increases ‘effective sector-level irrigation efficiency’ above field levelvalues (see Appendix, WASIM-ETH Irrigation Module). In WASIM-ETH , only effectivesector-level values can and should be used.

2. A temporary table on irrigation activities TabIrrAct1 is defined. It contains columns withactivity ID, irrigation technology ID, crop ID, and the maximum water requirement of thisactivity over the year.

3. Then, a second temporary table TabIrrAct2 is used that expands the first table n-fold.For each activity, this table contains n slots or intervals with specific irrigation quantitiesi ∗ qmaxa /n, with i = 1 . . . n.Activity a at position ra in TabIrrAct1 is now referenced with index posa = n∗ra+ i−1.Each row receives the row number as final irrigation ID. As name tag, it uses a 3-digitcharacter ‘MAS’, the 3-digit cropping activity ID and then the irrigation technology andinterval, eac in 2 digits. As example, MAS2800304 is activity a = 280, technology 03 andinterval 4.

4. For all cells, the actual irrigation quantity was determined by the farm agents. Each cellis then matched with the table TabIrrAct2, and the irrigation column must fall into oneof these intervals. The irrigation water hight is entered of each interval is written into theirrigation table in the control file, while the final irrigation ID is written to the WASIM-ETH irrigation raster. Also, the irrigation method that codifies irrigation efficiency can beretrieved via the activity name (last two digits)9.

9While dirty, this way a minimum of changes were needed for the WASIM-ETH source code, which maintainscompatibility with other control files.

D.5. RESCALING BETWEEN WASIM-ETH AND MPMAS 41

Protocol 6 is the data transfer of grid-wise data after the WASIM-ETH irrigation run. Dataformat and treatment is equivalent to the protocol 4. The MP-MAS model can receive monthlydata defined in ‘SpatialExchangeInfo’10.

D.5 Rescaling between hydrological cells of WASIM-ETH andparcels of the MPMAS

D.5.1 Theoretical considerations for downscalingApplication-specific considerations for downscaling were gathered from discussions with projectmembers from different disciplines. Those are

A simple format for data transfer All data passed between models should use the same file for-mats, to facilitate computational issues. As such, only raster maps (ascii format) and matricesare exchanged.

Completeness of representation Each cropping type in MP-MAS is represented in WASIM-ETH. If aggregation of cropping types occurs, also disaggregation must be possible. Also, everyMP-MAS grid cell receives data from a linked WASIM grid cell, e.g. on ETpot, ETreal.

Consistency 1 Overall balances need to be equal in both WASIM should match MP-MAS . Thisconcerns all water flows to all times (water uptakes from rivers, evapotranspiration, etc.)

Consistency 2 Errors resulting from aggregation should be minimal

In addition, one should consider that the translation process also attributes many (hundreds orthousands) MP-MAS cropping activities, each with a complete specification of the productiontechnology, to few WASIM-ETH land use activities, which also results in a loss of data. Ap-plying the above-mentioned mapping criteria, a later refinement of land uses remains possiblewithout modification of code.

D.5.2 Functional steps in scaling from fine-scale to coarse-scaleThe rescaling routine is implemented in three functional steps:

Creation of linkage pointers With every change in land use pattern, an updated map between fineand coarse rasters is required. Thus, the creation of linkage pointers connects each cell fromthe fine map to one "similar" or "representing" cell of the coarse cell, using a relatively slowalgorithm that makes sure all theoretical considerations are met. As output, both a coarse-scalemap of the fine map is created, and a link-map that connects the "representing" coarse cells tothe fine cells. This linkage maps are held in memory.

Translation from fine to coarse Using that link-map, every future raster map can be translatedfrom fine-scale to coarse-scale very quickly. Currently, we use either the median or the mean asaggregation rule.

10Eventually, the WASIM-ETH control file template needs to be modified to save data as daily grids.


(a) (b)

Figure D.5 — The spatial rescaling routine (a) Mapping rules. Arrows show cells that are mapped tospatially distinct coarse cells (b) First order resolution error

Translation from coarse to fine To extrapolate a fine raster from coarse calculations, a routinewith minimum error is applied. Again, the link-map connects every fine-scale cell to a coarsecell.

D.5.3 Technical steps for rescaling: Fine to coarse-scale

1. Create a raster g with fine resolution that shares boarders with the coarse map C of the fullarea

2. Memorize shift from origin of C to g and initialize coarse map G with boarders of g

3. Calculate the mapping ratio r = cellsizecoarsecellsizefine

.

4. Create histogram hfull(c) of all data categories i 6= NODATA for the full fine-scale raster

5. For each coarse raster cell j, create histogram hj(c) for r2 fines cells falling into j, andidentify most frequent category cmax

i∈j

6. For each category c in hfull, identify one coarse cell j most appropriate to represent it (eithermaximum or center-of-gravity rule), in order to satisfy the completeness requirement

7. For each fine cell, remember which coarse cell represents it in a link map ML (couplingrequirement)


8. Attribute one coarse cell j to each category c following a maximum rule, untilhfull(c)− r2 · counti∈j(c(i) ∼= c(j)) ≤ r2

2

9. Link all fine cells i that fall into a coarse cell j with c(i) ≡ c(j) to j.

10. For all remaining fine cells, link them to the closest coarse cell (minimum distance rule)

Figure D.6 — Rescaling: Computational steps

The minimum distance rule (R. 10) in con-juncture with the maximum rule (R. 8) causessome coarse cells to be over-weighted if repre-senting a sparse land use category. This is obviousif comparing the rescaling of a spatially uniformlydistributed land use (e.g. traditional maize), and aheavily clustered land use (e.g strawberries withsome maize). The maximum rule will causethe cells within the cluster to become strawberrycells, while maize cells will shift to surroundingareas that are dominated by maize.Having applied these rules, a function returns thelink mapML and the shift shiftL2C fromML intothe full area C according to R. 2.As shown in Fig. D.5, the error of misrepresentation is small and converges to zero with largermaps. A larger mapping error occurs due to spatial inhomogeneity, especially if some categoriesoccur only very seldom and are mapped to far-off coarse cells.

D.5.4 Technical steps for rescaling: Coarse to fine-scaleUsing the link map ML, all subsequent rasters can be rescaled. The r2 fine cells i falling into onecoarse cell j need to be aggregated. Options include mean rule, median rule, or more complexmethods that take into consideration higher-order moments. For the purpose of hydrologicalmodelling, we require that water balances remain consistent both between and within the models.WASIM-ETH internally attributes irrigation water, thus here no inconsistency occurs.


D.5.5 Source code example

Listing D.3 — Example use of rescaling function.

# i n c l u d e " B a s i c D a t a . h "# i n c l u d e " Ras te r2D . h " / / c l a s s f o r r a s t e r maps# i n c l u d e " B a s i c S t r e a m s . h "# i n c l u d e " MpmasWasimInterface . h " / / a l l t r a n s l a t i o n f u n c t i o n s

i n t main ( i n t a rgc , c h a r ∗ a rgv [ ] ){

/ / 1 . Read example d a t aRas te r2D C ; / / c o a r s e m a t r i xRas te r2D f ; / / f i n e ma t r ix , l o c a t e d w i t h i n CC . i n i t i a l i z e F r o m F i l e ( " t e s t A s c i M a p C o a r s e . t x t " ) ;f . i n i t i a l i z e F r o m F i l e ( " t e s t A s c i M a p F i n e . t x t " ) ;

/ / 2 . C r e a t e t r a n s l a t i o n map L and p o s i t i o n map/ / c a l l e d cG , and r e c e i v e by r e f e r e n c e :/ / c o a r s e m a t r i x and t r a n s l a t i o n m a t r i xRas te r2D G; / / c o a r s e m a t r i x a round f . Kept

/ / i n memory , a s i t c o n t a i n s l o c a t i o n !Ras te r2D L ; / / Link ma t r ix , p o i n t s f o r a l l c e l l s

/ / i n f t o some c e l l i n C/ / . . . r e c e i v e by r e f e r e n c e : S h i f t be tween i n t o Ci n t Y_shif t_C2G ; / / row s h i f t be tween C and Gi n t X_shif t_C2G ; / / c o l s h i f t be tween C and G

/ / . . . c r e a t e t r a n s l a t i o n m a t r i x and c o a r s e m a t r i x Gi n t r a t i o = rescale_CREATEMAP_f2G (

C , f , G, L , Y_shift_C2G , X_shif t_C2G ) ;/ // / . . . . [ o t h e r f u n c t i o n s ]/ / . . ./ / . . ./ / 3 . T r a n s l a t i o n from any o t h e r f i n e r a s t e r f2/ / t o c o a r s e r a s t e r G2 ,/ / u s i n g same t r a n s l a t i o n map LRas te r2D G2 , f2 ;f2 . i n i t i a l i z e F r o m F i l e ( " t e s t A s c i M a p F i n e . t x t " ) ;r e s c a l e _ f 2 G ( f2 , L , G, G2 ) ;

/ / 4 . Load c o a r s e r a s t e r ( any d a t a ) and e x t r a c t d a t a/ / from c o a r s e r a s t e r back i n t o f i n e r a s t e rRas te r2D C2 , T a r g e t ;C2 . i n i t i a l i z e F r o m F i l e ( " t e s t A s c i M a p C o a r s e 2 . t x t " ) ;


r e s c a l e _ C 2 f (C2 , / / i n p u t d a t a a s r e f e r e n c eL , / / i n p u t d a t a a s r e f e r e n c eY_shift_C2G , / / i n p u t d a t a a s d a t aX_shift_C2G , / / i n p u t d a t a a s d a t aT a r g e t ) ; / / o u t p u t da t a , a s r e f e r e n c e

r e t u r n 0 ;}


D.6 TDT Description FilesData channels and their definition Function used to define TDTconfigureation files:

Listing D.4 — Data types and roles in coupling setup.enum TypeDataExchangeType{ typeMatrixDouble,

typeRaster2D};

enum TypeRoleInCoupling{ typeSequencer,

typeDatamanager,typeMPMAS,typeWasimWrapper,typeCropModel

};

Listing D.5 — Name of configuration file.string getTDTConfigFilename(

TypeDataExchangeChannel dataChannel,TypeDataExchangeType dataType);

string filenameConfigFile(TypeRoleInCoupling roleInCoupling );

/* Allowed types:

* typeMPMAS, typeWasimWrapper, typeCropModel

*/

XML definition of data, exemplified with Raster2D

Listing D.6 — Configuration.xml1 <?xml version="1.0" encoding="ISO-8859-1"?>2 <program name="Raster2d.cpp">3

4 <channel name="send"5 mode="out"6 host="localhost"7 port="2238"8 type="socket"9 datadesc="./xmlFiles/Raster2d.xml">

10 </channel>11

12 <channel name="receive"13 mode="in"14 host="localhost"15 port="2237"16 type="socket"17 datadesc="./xmlFiles/Raster2d.xml">18 </channel>19 </program>

D.6. TDT DESCRIPTION FILES 47

Listing D.7 — Data description Raster2D1 <?xml version="1.0" encoding="ISO-8859-1"?>2 <data_desc>3

4 <decl name="intArray">5 <array size="0">int</array>6 </decl>7

8 <decl name="layers">int</decl>9 <decl name="lenStr">int</decl>

10 <decl name="rasterContentType">int</decl>11 <decl name="numCols">int</decl>12 <decl name="numRows">int</decl>13

14 <decl name="Xcoord">double</decl>15 <decl name="Ycoord">double</decl>16

17 <decl name="cellsize">double</decl>18 <decl name="noData">int</decl>19

20 <decl name="doubleArray">21 <addr>22 <array size="0">23 <addr>24 <array size="0">double</array>25 </addr>26 </array>27 </addr>28 </decl>29

30 </data_desc>

For each data channel, a channel description file exists, which specifies a unique socket andthe data description file.

Executable Control file

Sequencer controller_conf.xmlData manager dataManager_conf.xml

Wasim wrapper wasimModule_conf.xml

Table D.1 — Configuration files


D.7 Starting a fully coupled model runThis section summarizes briefly the steps necessary to run the coupled MP-MAS/WASIM-ETHmodel, using existing input data and data structure. For further details, consult the Manual(Arnold 2008).

All files are located in the same directory $DISS, which must be defined globally in the bashcontrol file ‘.bashrc’.

D.7.1 File directoriesThe DVD attached to this dissertation contains the following, which should be copied to a localhard drive:

$DISS The base directory which contains all further directories

$DISS/base contains shell scripts, and is the directory to call executables from. This directory issaved in the global variable $MAS.

$DISS/COUPL_inputs/executables Executables, compiled under Scientific Linux 3.8

$DISS/COUPL_inputs/chiFull271: All MP-MAS input and output files

$DISS/COUPL_inputs/chiFull271/iniFiles2000: Data files for coupling

$DISS/COUPL_inputs/wasim_coupl All WASIM-ETH input and output files

D.7. STARTING A FULLY COUPLED MODEL RUN 49

D.7.2 Adjusting the bash shellUse bash shell. In the home directory, edit profiler for the bash shell ‘bashrc’ and add thefollowing variables.

# ------------------------------------------------------------## TARNOLD - MODEL#export DISS_BASE=/mnt/fat/Coupl## ----------------------------------------------## Projekt-Struktur / Source code## (Hier befindet sich das "Eclipse"-Projekt)# ----------------------------------------------## Directory with source code projectexport PROJDIR=$DISS_BASE/ProjectIMS/trunk## ... with TDT source codeexport TDTPOS=$PROJDIR/lib/tdtall/tdtsrc/tdtexport EXPASTPOS=$PROJDIR/lib/tdtall/tdtsrc/expat#alias ecl=’cd $PROJDIR’# libraries# ... expat libraryexport LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$EXPATPOS:$TDTPOS## ----------------------------------------------# Data directories# ----------------------------------------------# ... wasim dataexport DIRWASIMOUT=$DISS_BASE/COUPL_inputs/wasim_couplexport WASIMDAT=$DIRWASIMOUT## ... base directory with scripts,# location to call executables fromexport MPMAS=$DISS_BASE/baseexport MAS=$MPMAS#alias mas=’cd $MAS’alias killmas=’sh $MAS/killMPMAS.sh’## this is just a string, used for the filenames during compilation# and consistent with killMas.sh and runAll.shexport COUPLNM=coupl## .. shortcut to remove temporary files from WASIMalias cleanwasim=’sh $MAS/removeWasim.sh’# ------------------------------------------------------------


D.7.3 $MAS/AllDefaultsCoupl.txtAllDefaultsCoupl.txt is a short asci file that contains a list of file- and directory names,in $MAS. It is read automatically by all executables. Most importantly, the coupling scenario[SCEN] is defined here (the first two lines). These names are overwritten though by the argu-ments that are directly passed to the executable (like -Ixxx, -Nxxx). If no default file is found,internal defaults will be used, which are normally the local directory.

The file contains (in order):1. Location of scenario (refered to as [SCEN]), where it also expects the MP-MAS input file directory input/

2. The sub directory of files for coupling, within the above directory

3. The location of MP-MAS output directory out

4. Name trunk of all MP-MAS input files (.dat)

5. Position of xmlFiles (cannot be changed)

6. Directory for intermediate WASIM-ETH output files, which are created by data manager

7. Filename for delimiting MP-MAS model area as sub area of full WASIM-ETH area (raster, generated auto-matically by MPMAS.exe in [SCEN]/temp/).

8. File to extract MP-MAS inflows from abstraction files (see detailed paragraph below on [SCEN]/iniFiles/)

9. Directory with WASIM-ETH input files (not changeable for now)

10. Directory where monthly WASIM-ETH output directories will be created (not changeable for now).

11. Directory with spinup data, to start the first year with.

Listing D.8 — Example file $MAS/AllDefaultsCoupl.txt1 /disk/ArnoldDiss/COUPL_inputs/chiFull2712 iniFiles20003 /disk/ArnoldDiss/COUPL_inputs/chiFull2714 P3I1S2_5 ./xmlFiles6 /disk/ArnoldDiss/COUPL_inputs/wasim_coupl/tmpRaster7 raster_sectors_tight.txt8 InflowKey.txt9 /disk/ArnoldDiss/COUPL_inputs/wasim_coupl/input

10 /disk/ArnoldDiss/COUPL_inputs/wasim_coupl11 /disk/ArnoldDiss/COUPL_inputs/wasim_coupl/spinupOut_2000

D.7. STARTING A FULLY COUPLED MODEL RUN 51

D.7.4 ExecutablesEither re-compile executables11. Otherwise, copy executables from directory$DISS/COUPL_inputs/executables into some directory listed in the $PATH variable:

cp \$DISS/COUPL\_inputs/executables \$BINS

D.7.5 Calling all executables simultaneouslyTo start all four executables,

1. Open four bash terminals

2. In each terminal, move to $MAS directory

3. In each terminal, call one of the following lines (the WASIM wrapper also calls the wasimexecutable, couplwasimuzr

4. Outputs are created in the directoriesspecified in AllDefaultsCoupl.txt

# MPMAS executableMPMAS_tdt -L -T30 -A47 -A46## SequencercouplSEQUENCER.exe -T13## Wasim Wrapper (calls couplwasimuzr)couplWASIMWRAPPER.exe -T13## Data managercouplDATAMANAGER.exe -T13

The meaning of arguments

-L Create log file-T30 Use input files named ‘##coupl.dat’-A46 Export land use spatially-A47 Export irrigation table spatially-T13 Use TDT outputs

11Source code available from Prof. Thomas Berger on request, [email protected].

[email protected]


D.8 Tools for data processing

D.8.1 Script to create standalone applicationThe following script calls a number of help functions:

glueAllStatisticFiles.exe

glueAbstractionInflowFiles.exe

createIrrigTableFromFiles.exe

CreateControlFileFromTemplate.exe

Also, the necessary directories are created, and data are copied as required. The final programcall is printed at the end:

couplwasimuzr $FN_WASIMCONTROLFILE

Explanations can be found in the script file.

Listing D.9 — Preparation of input data for WASIM-ETH1 echo --------------------------------2 echo3 echo PREPARATION OF STANDALONE WASIM RUN4 echo5 echo ... if "echo" then nothing happens as programs are6 echo not executed, but command is simply written to screen.7 echo Used to debug variables!8 echo9 echo --------------------------------

10 #11 # ==================================================12 # Setting directories (dont change!)13 # ==================================================14 # (cannot be changed! Link to global directory variable $MAS)15 BASEDIR=$MAS16 #17 # (cannot be changed! Link to global directory18 # variable $DIRWASIMOUT)19 DIR_OUT_MULTIRUN=$DIRWASIMOUT20 #21 # Output of full-run files (cannot be changed!)22 DIR_FULL=$DIR_OUT_MULTIRUN/fullrun23 #24 # ==================================================25 # Setting directories (may be changed)26 # ==================================================27 # Input for coupling scenario28 SCENARIODIR=/mnt/fat/model/mas/SCENARIO_V1_fixed29 #30 # Output directory of standalone wasim data31 DIR_FULL_OUTPUT=$DIR_FULL/output32 # Input directory of standalone wasim data33 DIR_FULL_INPUT=$DIR_FULL/input

D.8. TOOLS FOR DATA PROCESSING 53

34 #35 # make directory if it does not yet exist36 mkdir -p -v $DIR_FULL37 mkdir -p -v $DIR_FULL_OUTPUT38 mkdir -p -v $DIR_FULL_INPUT39 #40 # clear directory (DANGEROUS - totally kills content of this directory.)41 echo rm -f $DIR_FULL42 #43 # ==================================================44 # Function ’glueAllStatisticFiles.exe’45 #46 # It does the following:47 # - As statistic files, takes all that start with the strings indicated in

$BASEDIR/allFilenames_stat.txt48 # - Searches those statistic files in $DIR_FULL/ $STR_outdirs###### (once

for each line in $BASEDIR/allFilenames_stat.txt )49 # - Creates time matrix according to time handle50 # ("$SCENARIODIR/input/dat/TimeHandler.dat")51 # Copies values from statistic files into time matrix52 # - Saves full time matrix as statistic file. The header is taken53 # over from the EARLIEST output directory (" $STR_outdirs")54 # - Outputs are written to directory "$DIR_FULL/FullRunData_DRY" and "

$DIR_FULL/FullRunData_IRRIG"55 #56 # SETTING ARGUMENTS57 # ==================================================58 # String that monthly Wasim output directories start with (full name:

output_yyyy_mm)59 STR_outdirs=output60 #61 glueAllStatisticFiles.exe62 $DIR_FULL63 $DIR_OUT_MULTIRUN64 $STR_outdirs65 $SCENARIODIR/input/dat/TimeHandler.dat66 $BASEDIR/allFilenames_stat.txt67 #68 # ==================================================69 # Function ’glueAbstractionInflowFiles.exe’70 #71 # It does the following:72 #73 # Same as above, but instead of statistic files, looks into74 # subdirectories "zl" and "al", and writes it into75 # "$DIR_FULL/fullrun/FullRunData_DRY/al", ... zl, and76 # "$DIR_FULL/fullrun/FullRunData_IRRIG/al" and ... zl77 #78 glueAbstractionInflowFiles.exe79 $DIR_FULL80 $DIR_OUT_MULTIRUN81 $STR_outdirs82 $SCENARIODIR/input/dat/TimeHandler.dat83 #84 #85 # ==================================================


86 # CREATE WASIM IRRIGATION TABLE FOR YEARLY IRRIGATION87 # -> Function ’createIrrigTableFromFiles.exe’88 #89 # Call to ’createIrrigTableFromFiles.exe’90 # from file within temp-directory91 # into temp-directory of Scenario outputs92 #93 # It does the following:94 # Take input table $FN_TABLE_IRRIG from local95 # directory $SCENARIODIR/$FN_TABLE_IRRIG and96 # writes it to $SCENARIODIR/$FN_PROCESSED_IRRIGTABLE.97 # (warning: The table is only valid for one single year!)98 #99 # SETTING ARGUMENTS

100 # ==================================================101 # Input: Matrix with content for standalone irrigation102 # table, as exported by DataManager at first irrigation103 # period of year104 #105 FN_TABLE_IRRIG=standalone_IrrigTable_1996.txt106 FN_PROCESSED_IRRIGTABLE=_standalone_Final_IrrigTable.txt107 #108 createIrrigTableFromFiles.exe109 $SCENARIODIR/temp110 $FN_TABLE_IRRIG111 $FN_PROCESSED_IRRIGTABLE112 $SCENARIODIR/input/dat/TimeHandler.dat113 #114 #115 # ==================================================116 # Function ’CreateControlFileFromTemplate.exe’117 #118 # SETTING ARGUMENTS119 # ==================================================120 # Filename of control file template121 FN_TEMPLATE_WASIM=$SCENARIODIR/iniFiles/templ500_Steuer_7.5.str122

123 # Filename of output: Wasim control file124 FN_WASIMCONTROLFILE=$DIR_FULL_INPUT/FulltimeSteuer.str125

126 # Filename of TimeHandler127 FN_TIMEHANDLER=$SCENARIODIR/input/dat/TimeHandler.dat128

129 # Flag (do irrigation or not?)130 IRRIG_FLAG=1131

132 # Filename of irrigaiton table133 FN_IrrigationTable=$SCENARIODIR/temp/$FN_PROCESSED_IRRIGTABLE134

135 # Call to executable136 CreateControlFileFromTemplate.exe137 $FN_TEMPLATE_WASIM138 $FN_WASIMCONTROLFILE139 $FN_TIMEHANDLER140 $DIR_FULL_INPUT141 $DIR_FULL_OUTPUT


142 $IRRIG_FLAG143 $FN_IrrigationTable144 #145 echo --------------------------------146 echo147 echo COPY SOME FILES148 echo149 echo --------------------------------150 #151 # In input diectory, delete temporary files from old model run152 #153 rm $DIR_OUT_MULTIRUN/input/*."$"*154 #155 # -----------------------------------------156 # 1. Copy input files (not copying sub directories!)157 #158 cp $DIR_OUT_MULTIRUN/input/*159 --target-directory=$DIR_FULL/input160 # -----------------------------------------161 # 2. Create directories162 #163 # ... general outputs, and first: start values from spinup164 mkdir -p -v $DIR_FULL_OUTPUT165 #166 # ... inflows167 mkdir -p -v $DIR_FULL_OUTPUT/zl168 #169 # ... here wasim writes abstractions170 mkdir -p -v $DIR_FULL_OUTPUT/al171 #172 # -----------------------------------------173 # 3. Copy files containing grids and stacks174 # from spinup run (end on .grd)175 #176 #177 cp $DIR_OUT_MULTIRUN/input/spinupOrig/*.grd178 --target-directory=$DIR_FULL_OUTPUT179 #180 # Copy file with current routing level and fluxes181 #182 cp $DIR_OUT_MULTIRUN/input/spinupOrig/storage_richards.ftzd183 --target-directory=$DIR_FULL_OUTPUT184 #185 #186 # -----------------------------------------187 # 4. Copy inflows, as created by "glueAbstractionInflowFiles.exe"188 #189 cp $DIR_FULL/FullRunData_IRRIG/zl/*.dat190 --target-directory=$DIR_FULL_OUTPUT/zl191 #192 # -----------------------------------------193 # 5. Copy land use grid from $SCENARIO/temp - directory194 # into input directory195 #196 # Name of land use grid (as binary).197 # Asci file with same content exists in same direcotry (.txt)


198 #199 GRID_LANDUSE=$SCENARIODIR/temp/standalone_LanduseGrid_1996.grd200 #201 # Name of land use binary, as specified in WasimControl file202 #203 FN_GRID_LU_CONTRFILE=$DIR_FULL_INPUT/m500.use204 #205 cp $GRID_LANDUSE $FN_GRID_LU_CONTRFILE206 #207 # -----------------------------------------208 # 6. Copy irrigation grid from $SCENARIO/temp - directory209 # into input directory210 #211 # Name of irrigation grid (as binary).212 # Asci file with same content exists in same directory (.txt)213 #214 GRID_IRRIGATION=$SCENARIODIR/temp/standalone_IrrigGrid_1996.grd215 #216 # Name of land use binary, as specified in WasimControl file217 FN_GRID_IRR_CONTRFILE=$DIR_FULL_INPUT/m500.irr218 #219 cp $GRID_IRRIGATION $FN_GRID_IRR_CONTRFILE220 #221 echo --------------------------------222 echo223 echo Call to wasim:224 echo225 echo couplwasimuzr $FN_WASIMCONTROLFILE226 echo227 echo --------------------------------228 \end{listing}229 %\end{boxedverbatim}230 \subsection{Script for calling post-processing routine}231 The following routine is used to create a tsv-table of cellwise information.

A filter map is applied to a list of specified \wasim output maps: Foreach grid cell of the filter that contains a value, a table row will becreated. The first columns are key columns, with row, column, catchment.\\

232 The script calls the routine twice: Once for extracting constant propertiesof the research area, used for cluster analysis etc. The second call isused to extract time series, at daily resolution.

233 \begin{listing}[10]{1}234 # --------------------------------235 # Definition of key directories236 # --------------------------------237 SCENARIODIR=/mnt/fat/model/mas/SCENARIO_V1_fixed238 DIRWASIM=/mnt/fat/model/wasim_chile239 #240 # Define relative directories in DIRWASIM:241 DAYDIR=$DIRWASIM/gisOut242 OUTDIR=$DIRWASIM/post-processing243 #244 # File used to filter all cells of interest.245 # Usually used: Irrigation grid, as ASCII246 FILTER=$DAYDIR/raster_LU_filter.txt247 #


248 # --------------------------------------249 # SOME OUTPUT TO TERMINAL250 echo --------------------------------------251 echo252 echo CREATING CELLWISE TABLE OF CONSTANT VARIABLES253 echo254 echo assuming WASIM directory: $DIRWASIM255 echo daily files in: $DIRWASIM/$DAYDIR256 echo257 echo careful: Argument -E[eee] needs to258 echo be before variables -D[ddd]259 echo --------------------------------------260 echo261 echo Arguments:262 echo263 echo -E[eee] file (E)xtentsion , like ’grd’264 echo -C[ccc] info on (C)ellsize, like ’m500’,265 echo as used in WASIM control file266 echo -I[iii] (I)nput directory267 echo -F[fff] (F)ilter for grid cells (ASCII format).268 echo All NON-nodata-cells will be exported269 echo -W[www] (optional) (W)asim binary raster file(s)270 echo ( -W[www]) (optional) any further binary271 echo grids to be used in the header, max 15272 echo273 echo -R[rrr] (optional) Wasim Irrigation grid (binary format)274 echo275 echo -D[ddd] one or many (D)aily variables,276 echo format [ddd_ccc_year_month_day.eee], max 15277 echo ( -D[ddd] ) further daily variables, to be saved in other files278 echo279 echo --------------------------------------280 #281 post-processing.exe282 -Edgrd -Cm500 -I$DAYDIR -O$OUTDIR -F$FILTER283 -W$DIRWASIM/input/ZONEGRID_m500.ezg284 -W$DIRWASIM/input/m500.use285 -W$DIRWASIM/input/m500.dhk286 -W$DIRWASIM/input/m500.irr287 -W$DIRWASIM/input/m500.slp288 -W$DIRWASIM/input/m500.art289 #290 echo XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX291 echo292 echo CREATING CELLWISE TABLE OF TIME SERIES293 echo294 echo format: [ddd_ccc_year_month_day.eee]295 echo296 echo Example:297 echo etr_m500XXXXXXX1996_10_3.dgrd298 echo299 echo careful: Argument -E[eee] needs300 echo to be before variables -D[ddd]301 echo302 echo XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX303 #


304 post-processing.exe305 -Edgrd -Cm500306 -Detp -Detr -Dprec -Dtemp

D.8.2 Script runMPMAS.sh for running coupling in background (for re-mote access runs)

To call remote access, a shell script is used that pipes all program outputs into separate text files,using the Linux pipe operator ">". The output files are also useful for debugging.Careful: some or too many test flags will create very large output files!

Listing D.10 — Running the full coupling from remote access1 echo ----------------------------------------2 echo Call to Shell Script RUNMPMAS.SH3 echo4 echo This will call all coupling executables5 echo ----------------------------------------6 echo Assuming output directory: $MPMAS7 echo Assuming file of defualts: $MPMAS/AllDefaults.txt8 #9 # clean directory from temporary files

10 rm -f wq_tab*11 rm -f Runoff*12 rm -f *.log13 #14 # Now call to 4 executables, with parameters,15 # and pipe output to $MPMAS/output/XXX.out16 #17 echo ----------------------------------------18 echo Calls to execute MPMAS WASIM coupling.19 echo20 echo To interrupt, write ’killmas’21 echo ----------------------------------------22 couplSEQUENCER.exe -T13 > ./output/sequencer.out &23 couplWASIMWRAPPER.exe -T13 > ./output/wasimWrapper.out &24 couplDATAMANAGER.exe -T13 > ./output/dataManager.out &25 couplMPMAS.exe -T80 -T13 > ./output/mpmas.out &

linking farm economics and hydrology: model integration for watershed-level irrigation ... ·...

Documents