Wednesday, December 21, 2011

Modeling Water Rights



Introduction
Water law often drives the decisions made in operations and planning of water systems. Water law is the foundation for administering and managing water supplies. Because of the importance of water law in water planning and operations modeling, water rights modeling capability in your model should adequately represent the legal systems currently in place.

This post summarizes the basic legal systems used to manage and facilitate allocation of limited water supplies. The summaries of legal systems presented in this post are founded on my understanding of U.S. Water Law and a cursory review and comparison of systems used in Canada and Australia. Following a short description of each basic legal system, a summary of modeling requirements for the system is explored.

Legal Systems for Water Allocation
For the purposes of this post, I refer to a water user as an “account.” All accounts have a demand for water and a water right that justifies use of their water. Water rights are used to manage and administer allocation of limited water supplies. Types of water rights include:
  •  The right to divert water from a stream (i.e. to a WTP, reservoir, canal, etc.)
  •  The right to store water in a reservoir or groundwater aquifer
  •  The right to use flow thru demand (i.e. instream fish flows, mills, recreation, etc.)
  •  The right to pump water from groundwater
  •  The right to capture diffused water
Water rights are administered using one (or combination of) of a multitude of basic legal doctrines. The most fundamental doctrines of water law include:
  •  Riparian Right
  •  Prior Appropriation
  •  Absolute Ownership
  •  Reasonable Use

Riparian Rights
Riparians are landowners who own property that borders a waterway. Under the riparian doctrine, all riparians have the right to make reasonable use of the water that borders their land. Some riparian rights allow for multiple uses so long as the quantity and quality is preserved. Riparian water rights work well for flow thru uses such as supplying water to saw mills, navigation, fishing, and recreation. Modern riparian rights allow for consumption of flows for domestic use cases. Riparian water law generally applies to states east of the Mississippi River (Currently used in 29 of the U.S. states).

Allocation of Limited Water Supply
If there is not enough water to satisfy all users, allotments are generally fixed in proportion to frontage on the water source or the size of the riparan parcel. These rights cannot be sold or transferred other than with the adjoining land, and water cannot be transferred out of the watershed. If water is naturally available, then you can take water on an “as-need” basis up to your allotment specified in a permit.

Requirements for Model Implementation
Water must be distributed in proportion to properties of the account, such as property size or riparian frontage length. Shortages are shared among all users with possible exceptions. The exceptions would be treated as higher priority of other uses, and therefore would trump others. The effects of an upstream allocation on a downstream riparian right must take into account lags and losses as water moves downstream.

Prior Appropriation
Prior Appropriation doctrine applies to the United States west of the Mississippi River and in areas where water is scarce. In contrast to the Riparian water rights system, prior appropriation doctrine specifies that rights depend on water use and not land ownership. Once beneficial use of the water can be established (perfecting the right), the right becomes permanent, so long as the right is not abandoned. The water right of a user with an older date of first use has priority over a newer water right. Higher priority water rights are known as “Senior” rights while lower priority rights are known as “Junior” rights. Appropriation rights can be transferred because location of use relative to the water source is not considered as criteria for the right.

Allocation of Limited Supply
When the amount of natural flow in the river is not sufficient to satisfy all water needs, water supply must first satisfy senior water rights before allocation to more junior rights are made.

Requirements for Model Implementation
  •  Senior water rights must be satisfied before junior water rights.
  •  Equal priorities are curtailed relative to their flow needs
  •  The user must be able to define custom boundary conditions for the water use permit (i.e. timing, max flow rate, accrual based maxima, etc.)
  •  Sometimes, diversion of water to service a demand is limited by physical constraints of the hydraulic system rather than the water right
  •  The effects of an upstream allocation on a downstream senior right must take into account lags and losses as water moves downstream.
  •  Releases from reservoir storage accounts are not priority date driven and are therefore not included in the prior appropriation allocation process. Diversions to reservoir storage accounts are treated like any other stream diversion right

Hybrid Systems
Hybrid systems are used for areas that started out with a riparian right scheme then later converted to prior appropriation law, while maintaining the existing riparian rights in place. Your model may need to be capable of simulating hybrid systems.

Special Types of Water
Most water available for use falls within one of the three legal systems stated above, but special types of water fall outside of those systems. These are Groundwater and Diffused Surface Water.

Groundwater
Groundwater right law is tricky because it is most in flux within modern legal systems. Until recently, groundwater was loosely considered to be a non-depletable resource and the effects of our usage were unknown. For a long time, groundwater was simply not managed or allocated. Today, many laws have been established to treat groundwater as part of the surface water system and/or with rules that are different from rules used for allocation of surface waters. Groundwater withdrawals in the Sacramento Valley of California are still not managed.

Groundwater is treated differently because users are able to extract water from the source at a faster rate than what replenishes the source. Another unique problem is that a new diversion (well) might endanger existing accounts in the same aquifer.

Allocating Limited Supplies of Groundwater
Absolute Ownership
A landowner has an unlimited right to withdraw any water found beneath the owned land. The account with the biggest pump and deepest well gets the most water.

Your model needs to be able to allocate water flows based on the properties of the account, like pump size and well depth. The total, available water supply is limited to the amount available in the aquifer.

Rights of Prior Appropriation
The person who started pumping (using) the water first has the highest priority to use the water. This is not very practical because absolute protection of the user’s right is not possible. This system is used mainly for groundwater that is connected hydraulically to surface water bodies. Sometimes the total withdrawal rates are set in accordance to what the total recharge rate is.This system can be implemented in your model the same way surface waters are allocated.

Groundwater as a Public Resource
Most jurisdictions recognize groundwater as public property. In areas where groundwater is not considered to be public property, appropriations are governed by doctrines of “reasonable use”, “correlative rights”, and other bases. Application of reasonable use doctrine means that your model must be able to model accounts with priorities. Priorities can be defined using properties that represent some measure of reasonable use. Application of correlative rights means that shortages need to be shared across all accounts.

Diffused Surface Water
Not all water types are able to be managed by governments. Thus, water right legal systems exclude from coverage oceans, water in the process of evaporation or transpiration, and precipitation. Most jurisdictions allow landowners to make use of diffused surface water on their property without limitation. In these cases, we would assume the doctrine of absolute ownership of the diffused water.

Precipitation and evaporated water can only be captured within the property the water accumulates in. Because of this, there is no need to allocate the water. Ocean water use (i.e. desalination) likely will be modeled as an infinite source so allocation is not needed.

Conclusions
It appears that all the doctrines of water law can be simulated using one (or a combination) of two methods:
  •  Shared appropriation
  •  Priority appropriation
The challenges we are faced with in designing a model to be used for water rights are:
  •  Water is owned property that is constantly changing through time and space
  •  The study of water law is a relatively young and dynamic field
  •  There are many different ways to administer and manage water use depending on the location, nature of the water system, and the history of the legal systems currently in use
Another challenge in modeling water rights is the simulation of “colored water”. This is where water that belongs to an account is separated from water belonging to other accounts. I have not seen an existing tool that handles this very well. I’m not sure yet if it would be worth our time to implement this ability.

References
Getches, David H. "Water Law in a nut shell". 1984.
Sax, Joseph L., et al. "Legal Control of Water Resources, Cases and Materials." Third Edition, 2000.
Nowlan, Linda. "Customary Water Laws and Practices in Canada", 2010.
Australian Office of Legislative Drafting and Publishing. "Water Act 2007", Attorney General's Department, Canberra. 2011

Wednesday, October 19, 2011

Optimization in Integrated Water Resources Management

Introduction
Optimization is a very large topic, even within the confines of water resources planning and management. For today, I would like to focus on a single application, which I found while reading the Journal of the American Water Resources Association (JAWRA). I highly recommend JAWRA as a great source on all things water resources and for updates on the latest issues. In the February 2011 issue (yes, I'm a little behind on my reading), there is an article called "Optimal Pollution Trading without Pollution Reductions: A Note". I would like to take the time to write up a review of this article.

Pollutant Trading Application

Pollutant trading is in it's infancy - the experimental stages. Current challenges include high transaction costs, difficulties in transferring liabilities, and pollution allowances in existing programs. This article describes how two different types of polluters (farm and factory) can collaborate in order to reduce the impact on receiving waters. While the factory discharges pollutants at a constant rate, irrespective of its surroundings, a farm might discharge in spikes depending on the occurrence of storm events. Optimization was used to minimize the environmental damage to the receiving water body. Factors considered in the optimization include uncertainty in runoff pollutants and enforcement costs.

Traditionally with pollutant trading, the thing being traded is a reduction in pollutant concentration. A reduction in pollutant load at point A is traded for an equal increase in pollutant load at point B on the receiving water body. In the case of this example, temporary retention of pollutants is instead being traded.



References:
Garcia, Jorge H., Heberling, Matthew T., Thurston, Hale W. "Optimal Pollution Trading without Pollution Reductions: A Note". JAWRA 2011, Vol. 47, No. 1, pg 52.

Modular Systems Modeling


It is necessary to study not only parts and processes in isolation, but also to solve the decisive problems found in the organization and order unifying them, resulting from dynamic interaction of parts, and making the behavior of parts different when studied in isolation or within the whole.
Systems
Modular systems modeling is an approach to modeling that can be very useful for applications in integrated water resources management because of its inherent structure and organization. Every system is designed to achieve some objective. A system is made up of a network of interrelated components, which may consist of data, data processors, reporting elements, and subsystems.

The term "Systems Modeling" was introduced in the early 1960's and became famous shortly after the birth of FORTRAN. Since that time, it grew steadily in popularity until finally plateauing in the year 2000. The term "Systems Approach" peaked in 1975 and has since been on a steady decline. The grandfather of the Systems approach is known by some to be Alfred James Lotka from his work entitled, "Elements of Physical Biology" (1925). We are indebted to him for the formulation of the basic concepts of the Systems approach to studying the behavior of interconnected pieces to understand the greater whole. It makes sense that the advent of the computer gave us the power to begin using the Systems approach on problems of increasing complexity.

A closed system is a system that works independently of its environment and an open system is influenced by its environment and also interacts with subsystems outside of it.

Systems often have the ability to self-regulate or self-adjust. They can adjust behavior based on influences from outside such as changes in input data. This is often accomplished through feedback logic in the model.

Systems are classified into two different categories.
  • Deterministic Systems
  • Probabilistic Systems
Deterministic systems respond to inputs supplied to them and they react in a way that is predictable. This does not mean these systems are necessarily simple but rather that respond to instructions given.

Probabilistic systems have varying degrees of outcomes. It is very difficult to predict what the outcome of a probabilistic system will be. Outcomes from these types of systems is characterized in terms of chance rather than a given, predicted value.

Feedback
Feedback plays an important role in systems modeling because it can be found naturally in most real-world systems we are trying to represent. Below is a depiction of a typical feedback scheme.
A common example found in IWRM is in the water conservation model, where new policies stimulate the population to conserve water use and therefore cause the revenue stream generated by the metered water customers to drop. This response causes a feedback stimulus to the water provider to increase water usage rates, thereby changing the stimulus on the population.

Representing the System Using a Schematic
Schematic representations of the system are very useful in depicting the elements of a system and their influences. The image below is a screen capture of a computer model representing a water supply system located in Southern Utah. This is a schematic representation of the real system.

The blue lines in this figure represent the flow of water, red lines represent influences on operations, and the gray lines represent monitoring. This schematic happens to represent a dynamic system model that is changing through time. Because it is dynamic, it must include self-regulating and self-adjusting logic in order to behave with a purpose. This is done with feedback loops (red lines) and monitoring logic (gray lines).

Systems Modeling for IWRM
While the systems modeling approach has been very useful for many different applications, it is even more so for Integrated Water Resources Management. It is important that the system to be modeled is understood, including the influences between components of the system. A schematic representation of the system should be laid out prior to constructing a computer model. All major interactions and feedback loops should also be mapped out in the schematic and a formulation for dealing with these sketched out. Doing this before beginning the modeling work will save time in the long run.

I hope this information was helpful. Please comment if you think so.

References:

  • Awad, Elias M. "Systems Analysis and Design". 1979, Florida International University.
  • Lillywhite, Jason "Performance of Water Supply Operations Measured by Reliability and Marginal Cost". 2008, University of Utah.
  • GoldSim Technology Group, LLC. GoldSim Dynamic Simulation Software. 2011.
  • Bertalanffy, Ludwig von. "General System Theory, Foundations, Development, Applications". 1968.
  • Google Ngram Viewer for words "Systems Approach" and "Systems Modeling". 2011. 


Thursday, March 31, 2011

Simulation of Reservoir System Operations

Introduction

Reservoir storage is necessary to regulate highly variable water flows for more constant uses such as municipal and industrial water supply, irrigation, hydroelectric power generation, and navigation. Typically, the water drawn from a reservoir is used at a much slower (and constant) rate than the rate and consistency of the water flowing into the reservoir (see Figure 1). Reservoir modeling has typically been employed to help size reservoir storage capacities, establishing operating policies, evaluating operating plans, administering water allocations, developing management strategies, and real-time operations.

Figure 1 - Inflow and Outflow Hydrograph

The basic requirement for adequate representation of a reservoir is employment of the continuity equation, or conservation of volume over a period of time. This is a function that interacts dynamically with the current state of the reservoir. The foundational equation for conservation of volume is:

The term “Reservoir System Operations” refers to the practice of maintaining and managing a reservoir for multiple purposes, under dynamic conditions. The word “system” is used because of the complexity inherent in the operations of a typical reservoir or network of reservoirs. The state of the reservoir system is constantly in flux, requiring dynamic methods of simulation to evaluate and model them. The term “Reservoir System Operations Model” refers to a computer program used for simulating and optimizing changes in storage, water deliveries, and flood control for one or multiple reservoirs.

Often times, the objective of the reservoir operation is to balance the control of flood storage and maintain reliable water supply. Operational procedures are different for flood events than what are employed under water scarce conditions and therefore, the model must be adapted for these changing conditions.
To better manage potential changes to reservoir operations given uncertainties or changes in circumstances, it is helpful to develop a calibrated simulation model of the reservoir. Some key topics related to reservoir system operations modeling are presented in this paper.


Single pool operations

The main purpose of a reservoir is to control a determined amount of water during some period of time. The amounts that are controlled depend on the properties of the reservoir system, which include components such as the dam, spillway, inflow facility, and outlet works. Figure 2 depicts a simple example of a basic reservoir system. Inflow to a reservoir is typically uncontrolled if the reservoir is on the river. Some dams are built off-stream and water is delivered to the reservoir in a controlled manner. Usually, the controls on inflows to the reservoir are a function of the water level in the reservoir.

Figure 2 - Simple Reservoir Diagram

As the reservoir begins to approach an upper limit, the flow into the reservoir is turned off if the inflows are able to be controlled. For reservoirs that are located on a stream, the inflows cannot be controlled so the reservoir must operate a flood control system that usually includes an outlet works and an uncontrolled spillway. When the outlet works are not able to discharge enough water to lower the reservoir level, then the water will rise above the spillway and water will discharge over the spillway at a flow rate that is dependent on the height of water above the spillway.


Often times the reservoir system operations need to be simulated in a computer model. Typically, a reservoir model must include the major parts of the reservoir system in order to evaluate the reservoir system operations. The fundamental aspect of reservoir modeling is the routing of water. This is done in various ways, depending on the situation and modeling requirements. All routing methods are based on the continuity of volume.



Operation of multiple pools

Typically, reservoirs are operated based on policies that involve multiple pools that are defined to be used for different purposes. An example of a typical multi-pool reservoir is shown in Figure 3, where the reservoir is divided into surcharge, flood control, conservation, and dead pool zones. Often times, the conservation pool is referred to as the multi-use zone because water needs to be conserved in this pool for multiple and often conflicting uses.

The flood control zone is to remain empty except during the times following a flood event upstream of the reservoir. Flood control zones often include a surcharge zone, which is the uncontrolled storage volume above a spillway elevation. Usually, it is not in the interest of reservoir operators to spill water over the spillway because it is uncontrolled and poses a risk to the channel downstream. The flood zone is typically drained in a controlled manner through use of an outlet works with an operated gate or valve.

Figure 3 - Reservoir Pools

The conservation pool is used to store water temporarily for downstream uses such as power generation, recreation, navigation, irrigation, municipal and industrial water supply, and instream flows for habitat. This pool is only drawn down if a request is made in behalf of one of these uses. Often times the top of the conservation pool varies seasonally as shown in the simple example in Figure 4. Typically, the top of the conservation pool rises during the part of year that additional storage is needed to supply water for beneficial use later on. A rise in the conservation pool poses greater risk on the operations of the reservoir because it requires that the flood pool zone is decreased, which gives the reservoir less opportunity to evacuate flood flows before the reservoir level enters the surcharge stage.

Figure 4 - Seasonal Variations in Conservation Pool

Often times, the top of the conservation pool acts as a guide, target, or rule curve for operators. The reservoir is operated in order to try and keep the reservoir level as close as possible to the top of the conservation pool. Obviously, it is critical that the seasonally varying conservation pool limit is first optimized using appropriate methods prior to actual use in the field.


Interaction with groundwater in bank storage

Since the permeability of the bottom of a reservoir tends to decrease over time due to sedimentation, seepage from the reservoir into the surrounding groundwater aquifer is usually ignored. This said, it is possible for groundwater seepage to be a significant factor in overall reservoir losses for some sites and an appropriate method of seepage simulation should be considered. Some reservoirs are intentionally sited in locations were permeability is high as a way to inject water into the ground. This is referred to as aquifer storage recovery and it is becoming more popular as many groundwater aquifers are being mined of their water supply due to increased groundwater pumping.

One of the simplest ways to estimate seepage to groundwater is to develop a function related to reservoir depth. This usually requires the assumption that seepage flows are always a net loss from the reservoir, which is likely case for most sites. However, there are times when you might need to consider bi-directional flux due to seepage outflows and inflows, depending on the elevation of the reservoir pool compared to the surrounding groundwater levels.


Water Supply Allocation

Before discussing allocations of water to multiple users from a reservoir or reservoir system, it is necessary to first introduce the term “firm yield”. This is an important concept used in reservoir system operations. Firm yield is the amount of water that can be continuously delivered from a reservoir with 100% reliability over a historical period-of-record or hypothetical repetition of hydrology. Reliability is usually defined as the ratio of total water supplied by the reservoir (n) to the total amount of water requested (V). The equation looks something like this:

There are other reservoir yields (i.e. secondary yield, etc) that can also be provided for beneficial use but are not 100% reliable. Often times, water from a reservoir is allocated based on various levels of reliability, with the highest priority water demand being given the 100% reliable yield. This is how multiple water users are allocated their supplies: Each successive priority is given an incrementally less reliable reservoir yield.

Another important aspect of water supply allocation is the implementation of a permit system and adjudication of water rights. Usually, priorities are assigned to the various permit/water right holders as a way to simulate the allocation of water supplied to the user. Due to the complexity, a numerical methods formula such as linear programming (LP) might be necessary to solve for the overall firm yield given multiple users with varying priorities. The LP algorithm might also be useful for solving a priority based water allocation for a reservoir and water demand network. A good reference for this type of programming for reservoir operations is the book entitled, “Modeing and Analysis of Reservoir System Operations” by Ralph A. Wurbs, 1996 Prentice Hall PTR.

Network flow programming might also be appropriate as this is an efficient form of LP which can be used to represent a network of nodes and links similar to a reservoir/water demand network. This type of algorithm has been used many times for complex models that require prioritization of water supplies to multiple and conflicting water demands. Other methods include dynamic programming (DP), various non-linear programming techniques, and univariate gradient search.


Multiple reservoirs in series

When evaluating the operations of multiple reservoirs in series, special considerations need to be made. The decision of which reservoir to release water from will affect overall operations of the system. Typically, it is best practice to minimize spills from the upstream reservoirs so that capacity in the downstream reservoirs is preserved and will be able to catch uncontrolled spills from the upper reservoirs and thus protect the downstream river channel. It is also helpful to maximize conservation pool water in the upper reservoirs so that the most users will benefit at any given time. It is easy to release water from an upstream reservoir to a downstream reservoir but not the other way around. Figure 5 shows a simple example reservoir network with two reservoirs in series (Reservoir A and Reservoir B).
Figure 5 - Simple Reservoir Network Example

The objective for reservoirs in parallel should be to balance storage depletions between the two (see Reservoir B and Reservoir C). Under such a reservoir system setup, you might end up with control points to operate Reservoir A located at diversions 1-4 and the other two reservoirs. As discussed in the previous section, more complex systems like this may require an LP or optimization solver approach.

Thank you!

Thank you for reading! I hope you found this information useful. Please feel free to comment. I welcome criticism and suggestions.


References:

Wurbs, Ralph A. "Modeling and Analysis of Reservoir System Operations". 1996 Prentice Hall.

Wurbs, Ralph A. Modeling river/reservoir system management, water allocation, and supply reliability. Journal of Hydrology, Volume 300, Issues 1-4, 10 January 2005, Pages 100-113

Wurbs, Ralph A, Reservoir-System Simulation and Optimization Models. Journal of Water Resources Planning and Management, Vol. 119, No. 4, July/August 1993, pp. 455-472

Yazicigil, Hasan; Houck, Mark H.; Toebes, Gerrit H. Daily operation of a multipurpose reservoir system. WATER RESOURCES RESEARCH, VOL. 19, NO. 1, PP. 1-13, 1983

Yeh, William W-G. Reservoir Management and Operations Models: A State-of-the-Art Review. WATER RESOURCES RESEARCH, VOL. 21, NO. 12, PP. 1797-1818, 1985









Wednesday, February 2, 2011

Water Resources Challenges

Over the years, I've heard what people consider to be the challenges we face in trying to manage our water resources and plan for the future. I decided to take it upon myself and discover what people are publishing in regards to the types of challenges we face. I searched about 30 documents (articles and other publications) and found that most the challenges can be organized into 6 categories.

The challenges include:

  1.  Water quality 
  2.  Competing Uses 
  3.  Increasing demands 
  4.  Climate change 
  5.  Land use change 
  6.  Institutional challenges*  

I counted which categories people focused on and summarized it in a pie chart. Most publications listed more than one type of challenge.

*managing risk, coordination, corruption, conflicting policies, inadequate funds


Within these different types of challenges people focus on, I found some interesting aspects regarding the types of authors that report these challenges. These findings are summarized below:
  • Energy industries tend to focus on growing competition
  • Regulators tend to focus on water quality and climate change
  • Global organizations tend to focus on increasing demands and climate change
  • Regional water purveyors and utilities tend to focus on climate change, water quality, and increasing demands
  • Governments tend to focus on increasing demands and institutional challenges
  • Authors writing about poorer countries tend to focus on institutional challenges, water quality, and increasing demand
  • Authors writing about richer countries tend to highlight climate change, land use change, and pop growth
  • Academics tend to focus on climate change


References 




Four Pillars of IWRM

The Kirshen approach to IWRM

I recently read an interesting article titled, "Challenges in Graduate Education in Integrated Water Resources Management" (Kirshen, 2004) that expressed the need for implementation of integrated water resources management. In this article, four pillars of IWRM were presented.
The pillars are summarized as:



These pillars are described in detail below.

Systems Analysis includes system evaluation, optimization approaches, statistical analysis, simulation modeling, decision analysis, risk assessment, multi-criteria analysis, and the development of indicators and metrics for analyzing problems.

The Science and Technology of Water involves hydrology, fate and transport of environmental contaminants, water chemistry, water quality, water conservation, and water resources engineering.

Biological Aspects of Water, Health and Nutrition covers ecology, environmental impacts, food and nutrition, epidemiology of water-borne diseases and animal-to-human transmission through water, and ecohydrology.

Planning and Policy of Water includes environmental and water resource economics; legal and institutional frameworks; social, cultural, and behavioral issues; water security at the household, local, regional, national, and international levels; the ethics of local, national, and international systems for dealing with water security; and how to integrate them and other issues in the planning process.

Critique of the Kirshen approach
In my first blog post, I referenced a figure that I originally felt summarized the basic aspects of IWRM. In this post, I noted that the "4 pillars" are:
  1. Natural elements
  2. Structural components
  3. External human factors
  4. Viewpoints, policies, and economics



I'm glad I read Kirshen article because it reminded me that having an overarching idea or process to include these pillars is important for IWRM. I now consider my 4 pillars as distinct elements within an over-arching systems framework. The big green area around the pillars is the fabric which you would use to evaluate and study the real system as part of the decision making process. The Kirshen idea is an interesting one but it takes the systems analysis out as a branch of the work rather than the trunk.

Another question I have about Kirshen's approach is why are Nos. 2 and 3 separate? To me, it seems there are too many overlapping issues within these two pillars to ignore. It might work well for an academic curriculum plan (which is what this article was addressing), but might be inadequate for a real-life decision making process.

The desired goal of IWRM is to make better decisions and so the Kirshen 4 pillar idea concisely sets up some basic components, it does not provide a fabric that holds the ideas together. Whether we call it system analysis or decision-making, the point is, we need an overriding framework to incorporate the pieces together. 


References:
Kirshen, Paul H. Challenges in Graduate Education in Integrated Water Resources Management. 2004. Tufts University. Link

Tuesday, January 11, 2011

Model Documentation

I would like to try and address a few questions about model documentation. This is often said to be an important part of building models for Integrated Water Resources Management because there are usually a lot of people involved from various disciplines and backgrounds.

Typically you will see two different forms of documentation out there, including user documentation and programmer documentation. The user documentation is usually created to assist the end user interact with the input controls and view the results. The latter is usually there to help the user and/or programmer how the program actually works.

So, first and foremost: What is model documentation?

Model documentation is written text that accompanies the computer model. It either explains how it operates or how to use it or both, and may mean different things to people in different roles (Wikipedia, 2011).

Why do people think documentation is important?

The US Army Corps of Engineers (which happens to develop some very important software in the water resources modeling industry) says good documentation is needed and necessary. It should be assembled for every model and it should be done well (Johnson, 1982).

There are two main reasons why people might stop using a model:

  • It is not trusted
  • It is not needed
To address the first issue, you need someone qualified to review the model other than the primary author of the model. Often times, model documentation is critical for such a review.

While it is true that model documentation is important, we need to keep in mind that it will never replace the model itself. The first and foremost factor is a well designed and calibrated model that is shown to represent reality. It is also important to understand that good documentation will not create a need for the model if it is not already there.

Many others have noted the importance of model documentation.

"Documentation is not fun. It is hard, nasty and boring business, but this in no way makes it any less critical, particularly in a heavily user-oriented environment." (Brewer, 1976) This quote is important when considering modeling for an IWRM application since the environment in these situations is usually very user-oriented.

What constitutes good documentation?
The following information should be included in model documentation:

  1. Abstract/Introduction/Background
  2. The underlying methodology (theory)
  3. Model limitations (and capabilities)
  4. Data requirements
  5. Input specifications (how is data put into the model?)
  6. Summary of model output and any processing of results
  7. Example application of the model

An interesting article I found in my research was written by Saul Gass called, "Documentation for a Model: A Hierarchical Approach" (Gass, 1981). While recognizing that good documentation is very difficult for a large-scale math model, it is critical for the legacy of the model. Documentation should be integral with the construction of the model. The costs, resources, review procedures, and milestones should be specified at the beginning of the modeling effort. The hierarchical approach involves development of documentation in 4 categories:

  1. Operations (requirements for basic execution of the runs)
  2. Use (Math theory, data requirements, and model processes)
  3. Maintenance (modeling scenarios, maintenance log)
  4. Assessment (assessment, applications, summary, history)
The final document should end up with all 4 features. This can be graphically represented as a bookcase with the 4 categories represented on each shelf of the bookcase.
Source: Gass, 1981

But we can't forget that one of the most important steps in developing good documentation is to first set up a plan for the organization of the documentation so you can incorporate the work into your schedule and budget.

What is preventing people from writing good documentation?

  • Sufficient funds were never allocated for documentation in the first place
  • It is difficult and time consuming to translate model logic and formulation to written descriptions
  • The person writing the logic might not have the patience or ability to assist with documentation
  • Poor documentation is more common than good documentation so people might be lacking a good example to draw from
I would love to hear comments from anyone out there. 
I would bet some other modelers out there have some experience they would like to share that would significantly add to this post. 

Thank you.


Bibliography:


Johnson, William. US Army Corps of Engineers. "Documentation Needs for Water Resources Models", 1982. Link

Wikipedia. "Software Documentation". 2011. http://en.wikipedia.org/wiki/Software_documentation

Brewer, G.D. Documentation: An Overview and Design Strategy. Simulation & Games 7, 3 (1976), 261-280.

Gass, S.I. Computer Model Documentation: A Review and An Approach. NBS Special Pub. 500-39, U.S. Gov. Printing Office, 1979.

Gass, S.I., "Documentation for a Model: A Hierarchical Approach". 1981

House, P.W., and McLeod, J. Large-Scale Models for Policy Evaluation. John Wiley & Sons, New York, 1977.