Welcome to the first America's Water Model tutorial! In this tutorial, you are going to learn how to (0) install the model, (1) run the model in simulation and optimization mode with different configurations, (2) look at the results, and (3) make requests of and get updates from the modeling team.
We are going to use a bunch of terms in this tutorial, so it's important to clear up the confusion.
Julia: The programming language used for the model.
Julia is a high-level, high-performance dynamic programming language for technical computing, with syntax that is familiar to users of other technical computing environments.
If you are an advanced user, you can follow the more succinct installation instructions and then skip to "What you just got" below.
You will need some basic software to use the America's Water Model.
Julia (command line version) from http://julialang.org/downloads/
Check your installation by running Julia and writing some arithmetic.
Git from https://git-scm.com/book/en/v2/Getting-Started-Installing-Git
If you're on Windows, also download PowerShell (https://msdn.microsoft.com/en-us/powershell/)
Check that it's installed by opening a terminal/PowerShell and typing git --version and see a version number.
Jupyter Notebook from http://jupyter.readthedocs.io/en/latest/install.html
Check that it's installed by opening a terminal/PowerShell and typing jupyter notebook and see a browser window pop up.
Now it's time to download the model. First, decide where you want to put the model, and open a terminal to this location.
cd <directory>. <directory> can be any of the following:..) to go to the parent directory..) to not go anywhere./).~) to go back to your home directory./) to go to the root of the server.docs subdirectory of that folder.In the directory where you want the model folder, paste the following command:
git clone https://github.com/AmericasWater/awash.gitThe model is organized into different folders. Here is what is in there:
configs/: Configuration files, that determine the basic operation of the model.data/: Input data files. There is also a data/cache/ folder, with saved preparation files. You can delete this to force the model to reinitialize.docs/: Documentation, including tutorials like this one.prepare/: Some source data files and the scripts needed to prepare them for use in the model.results/: The standard location for output results, along with code for post-processing.src/: The main source code for the model. All the magic happens here.test/: Automatic testing scripts, to make sure changes don't break how the model should work.For the purposes of this tutorial, the main interface of the model is Jupyter Notebooks, and the existing tutorials in the docs/ subdirectory. To start the model, do the following:
docs/ subdirectory of the model.jupyter notebook.start.ipynb and click on it.If this is the first time you're running the model, it is going to install some needed libraries and data.
In [1]:
include("../src/nui.jl")
The configuration file determines the general bounds of the model. The current configuration parameters are:
netset: The top-level decision of the world we are deciding.
options: usa (full-country), three (3-counties), dummy (5-counties)
filterstate: Only include counties within this state (give as 2 digit FIPS).
e.g., "10" for Delaware (3 counties), "08" for Colorado (64 counties)
startmonth and endmonth: First and last month of the simulation.
e.g., 10/2000 - 9/2010
startweather: The weather entry to match to startmonth.
e.g., 1 to use the first month in VIC_WBfor the first month in the simulation.
timestep: The number of months for each timestep of the model.
The larger this number, the faster the model will run. Currently agriculture is calculated separately for each timestep.
There are three configuration sets to know about:
complete.yml: A monthly run from 1949 - 2010. This is basically impossible on a laptop.standard.yml: A 6-month timestep run from 2000 - 2010. This is about the maximum practical for a laptop.standard-1year.yml: A 6-month timestep run for 10/2009 - 9/2010 (two timesteps). This is good for testing.single.yml: A 12-month timestep run for 10/2009 - 9/2010 (one timestep). We will use this one here.Here is what the single.yml configuration looks like:
In [2]:
prepsimulate("single.yml");
This loaded up the model geography of the model, put together the sectors, and prepared all of the inputs. Now we can run the model.
In [3]:
runmodel();
There are lots of ways to see the results of the model, but they all require that you know which variables you want to look at. Start by identifying the component that you are interested, as a box in this image:
Let's consider the Agriculture component. Next, we need to know what variables are available within that component, which we do with the getvariables function.
In [4]:
getvariables(:Agriculture)
Out[4]:
The : is important for both the component name and the variable names below.
Then to see the results, call getdata(<component>, <variable>).
In [5]:
getdata(:Agriculture, :production)
Out[5]:
To save the data to a file, call savedata(<filename>, <component>, <variable>). The savedata function is best used on 2-D data (or less) and since production is of dimension COUNTY x CROP x TIME, we would like to drop one. We can do this with a fourth argument, which has the syntax for a Matlab index.
In [6]:
savedata("../results/agprod.csv", :Agriculture, :production, (:, :, 1))
Finally, we can plot it. This only works so far for results that describe nation-wide values, but it's a start.
In [7]:
mapdata(:Agriculture, :production, (:, 5, 1))
Out[7]:
In [4]:
using RCall
In [5]:
R"x = rnorm(100)"
Out[5]:
In [6]:
R"hist(x)"
Out[6]:
In [7]:
myjuliavar = [1, 2, 3]
Out[7]:
In [8]:
myjuliavar
Out[8]:
In [9]:
R"plot($myjuliavar)"
Out[9]:
In [10]:
x = R"rnorm(100)"
Out[10]:
In [11]:
x
Out[11]:
In [12]:
Pkg.add("YAML")
In [13]:
countyinfo = readtable("../data/county-info.csv")
Out[13]:
In [14]:
areas = countyinfo[:, :LandArea_sqmi]
Out[14]:
In [18]:
# The Brewery Component
# This is how we make beer
using Mimi
@defcomp Brewery begin
region = Index()
production = Parameter(index=[region, time], unit="liter")
hopsdemand = Variable(index=[region, time], unit="MT")
waterdemand = Variable(index=[region, time], unit="1000 m^3")
end
function run_timestep(c::Brewery, tt::Int64)
v, p, d = getvpd(c)
v.hopsdemand[:, tt] = .07 * p.production[:, tt]
v.waterdemand[:, tt] = 2 * p.production[:, tt] / 1e6
end
function initbrewery(m::Model)
brewery = addcomponent(m, Brewery)
production = readtable("../data/county-info.csv")[:, :LandArea_sqmi]
brewery[:production] = repeat(production, outer=[1, numsteps])
end
Out[18]:
In [29]:
m = Model()
setindex(m, :time, [1]) # Single period
setindex(m, :region, length(dropna(readtable("../data/county-info.csv")[:LandArea_sqmi])))
In [31]:
initbrewery(m)
In [32]:
brewery = addcomponent(m, Brewery)
production = readtable("../data/county-info.csv")[:, :LandArea_sqmi]
Out[32]:
In [33]:
brewery[:production] = repeat(convert(Vector{Float64}, dropna(production)), outer=[1, numsteps])
Out[33]:
In [30]:
function initbrewer(m::Model)
brewery = addcomponent(m, Brewery)
production = readtable("../data/county-info.csv")[:, :LandArea_sqmi]
brewery[:production] = repeat(convert(Vector{Float64}, dropna(production)), outer=[1, numsteps])
end
Out[30]:
In [34]:
run(m)
In [35]:
m[:Brewery, :hopsdemand]
Out[35]:
In [36]:
m[:Brewery, :waterdemand]
Out[36]:
In [ ]: