Skip to content

Commit

Permalink
Update quickstarter.ipynb
Browse files Browse the repository at this point in the history
  • Loading branch information
@mengqi-z
mengqi-z committed Jun 26, 2024
1 parent a8814a4 commit 39f1f40
Show file tree
Hide file tree
Showing 2 changed files with 203 additions and 11 deletions.
2 changes: 1 addition & 1 deletion docs/source/getting_started.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -86,7 +86,7 @@ With the example data downloaded, a simple configuration can be run:
import os
# modify the path if downloaded to a different directory
config_file = os.path.join(glory.default_download_dir, 'example', 'example_config.yml')
config_file = os.path.join(glory.default_download_dir, 'example_config.yml')
glory.run_model(config_file=config_file)
Expand Down
212 changes: 202 additions & 10 deletions notebooks/quickstarter.ipynb
View file
Original file line number Diff line number Diff line change
@@ -1,51 +1,243 @@
{
"cells": [
{
"cell_type": "markdown",
"source": [
"# Getting Started with GLORY\n",
"\n",
"This notebook walks you through the steps of installing `GLORY` and running an example.\n",
"\n",
"## Installation\n",
"\n",
"### Pre-requirements\n",
"\n",
"1. Before proceeding, ensure that Python is installed (version 3.9 or above). We recommend using Anaconda to set up a virtual environment.\n",
"\n",
"2. Additionally, you will need to install the linear programming solver `glpk`. The recommended method is to use conda to avoid unexpected issues (refer to the [Pyomo documentation](https://jckantor.github.io/ND-Pyomo-Cookbook/notebooks/01.01-Installing-Pyomo.html#glpk)). Make sure to use the same Python environment for all packages. Install `glpk` with `conda install -c conda-forge glpk`\n",
"\n",
"### Install `GLORY`\n",
"\n",
"**Option 1:**\n",
"\n",
"You can install `GLORY` from Github using `pip` in a command prompt or terminal:\n",
"\n",
"`pip install git+https://github.com/JGCRI/glory`\n",
"\n",
"This command will automatically install the dependencies. To avoid package version conflicts, consider using a virtual environment.\n",
"\n",
"**Option 2:**\n",
"\n",
"Alternatively, users can clone the `GLORY` package from GitHub. Navigate to the desired directory:\n",
"\n",
"`git clone https://github.com/JGCRI/glory`\n",
"\n",
"Then, navigate into the cloned glory folder and install GLORY from a command prompt or terminal:\n",
"\n",
"`pip install`\n",
"\n",
"Try importing `GLORY` to confirm that installation was successful:"
],
"metadata": {
"collapsed": false
},
"id": "f4734eaf0fc3bad5"
},
{
"cell_type": "code",
"execution_count": null,
"outputs": [],
"source": [
"import glory\n",
"\n",
"# get glory example dataset\n",
"glory.__version__"
],
"metadata": {
"collapsed": false
},
"id": "5c37a64df889bbda"
},
{
"cell_type": "markdown",
"source": [
"## Example Data\n",
"\n",
"Example data and configuration file can be downloaded from Zenodo through this link, or by using the `GLORY` function:"
],
"metadata": {
"collapsed": false
},
"id": "6ead0bd353aab76d"
},
{
"cell_type": "code",
"execution_count": null,
"outputs": [],
"source": [
"import glory\n",
"\n",
"# The example data will be downloaded to the cloned package folder by default.\n",
"glory.get_example_data()\n",
"\n",
"# check the path to the default downloaded folder\n",
"example_dir = glory.default_download_dir"
],
"metadata": {
"collapsed": false
},
"id": "1f3fcb88d950c596"
},
{
"cell_type": "markdown",
"source": [
"Or, if the user didn’t clone the `GLORY` package, then specify a desired download location."
],
"metadata": {
"collapsed": false
},
"id": "bc829b9b157cbed6"
},
{
"cell_type": "code",
"execution_count": null,
"outputs": [],
"source": [
"import glory\n",
"\n",
"# modify example_data_directory to your own desired location\n",
"glory.get_example_data(example_data_directory='path/to/desired/location')\n"
],
"metadata": {
"collapsed": false
},
"id": "72902990ddbd1cd2"
},
{
"cell_type": "markdown",
"source": [
"## Run\n",
"\n",
"With the example data downloaded, a simple configuration can be run:"
],
"metadata": {
"collapsed": false
},
"id": "18060daf69da9935"
},
{
"cell_type": "code",
"execution_count": null,
"outputs": [],
"source": [
"import os\n",
"import glory\n",
"\n",
"# modify the corresponding directories (e.g., root and gcam exe) in the yaml file\n",
"config_file = os.path.join(example_dir, 'example_config.yml')\n",
"config_file = os.path.join(glory.default_download_dir, 'example_config.yml')\n",
"\n",
"# read config file\n",
"config = glory.ConfigReader(config_file)\n",
"print(config.__dict__)"
"# run glory model\n",
"glory.run_model(config_file=config_file)"
],
"metadata": {
"collapsed": false
},
"id": "7746897dce3e4800"
},
{
"cell_type": "markdown",
"source": [
"Check your example\\outputs folder for the results!"
],
"metadata": {
"collapsed": false
},
"id": "10578b63a13f46d6"
},
{
"cell_type": "markdown",
"source": [
"## Use `GLORY` Modules\n",
"\n",
"Instead of running the entire model, one can choose to run certain modules.\n",
"\n",
"To generate a capacity-yield curve and a supply curve with discrete points for a single basin, users can easily instantiate the `glory.SupplyCurve()` object by providing the configuration object. The `glory.SupplyCurve()` will then undertake the process of identifying reservoir storage capacity expansion pathways and calculating the optimized water yield at each storage capacity point. The example below uses California River basin (basin ID is 217) for time step 2020."
],
"metadata": {
"collapsed": false
},
"id": "faf411de211883c1"
},
{
"cell_type": "code",
"execution_count": null,
"id": "2244cdad-9cf6-4c8a-bcdc-1feac9be5af6",
"metadata": {},
"outputs": [],
"source": [
"# run glory model\n",
"glory.run_model(config_file=config_file)"
]
"import glory\n",
"\n",
"# indicate the path to the config file\n",
"config = glory.ConfigReader(config_file=config_file)\n",
"\n",
"# demand_gcam and capacity_gcam is set to None because the model is not linked with GCAM in this example\n",
"sc = glory.SupplyCurve(config=config,\n",
" basin_id=217,\n",
" period=2020,\n",
" demand_gcam=None,\n",
" capacity_gcam=None)\n",
"\n",
"# Check the capacity-yield curve\n",
"sc.capacity_yield\n",
"\n",
"# check the supply curve\n",
"sc.supply_curve"
],
"metadata": {
"collapsed": false
},
"id": "23829083ed319406"
},
{
"cell_type": "markdown",
"source": [
"One can effortlessly apply the `glory.lp_model()` function to execute a linear programming model that determines the optimized water yield for a given reservoir storage capacity. Below is an example with arbitrary numbers. Please note that volumetric units should be consistent across variables."
],
"metadata": {
"collapsed": false
},
"id": "c465130e3032a86e"
},
{
"cell_type": "code",
"execution_count": null,
"outputs": [],
"source": [
"import numpy as np\n",
"\n",
"lp = glory.lp_model(K=1, # set storage capacity as 1 km3\n",
" Smin=0, # minimum storage\n",
" Ig=5, # annual inflow in volume\n",
" Eg=1, # annual reservoir surface evaporation in volume\n",
" f={i+1: num for i, num in enumerate(np.random.dirichlet(np.ones(12), size=1)[0])}, # dictionary: monthly profile for demand\n",
" p={i+1: num for i, num in enumerate(np.random.dirichlet(np.ones(12), size=1)[0])}, # dictionary: monthly profile for inflow\n",
" z={i+1: num for i, num in enumerate(np.random.dirichlet(np.ones(12), size=1)[0])}, # dictionary: monthly profile for reservoir surface evaporation\n",
" m=0.1, # percentage of water reuse\n",
" solver='glpk')\n",
"\n",
"# view the solution\n",
"lp.display()"
],
"metadata": {
"collapsed": false
},
"id": "b55683bb0fe60cb1"
},
{
"cell_type": "markdown",
"source": [
"This will return a `pyomo` object. To display the solution of the linear programming model for each variable, use `lp.display()`."
],
"metadata": {
"collapsed": false
},
"id": "f2769ed41fe77c15"
}
],
"metadata": {
Expand Down

0 comments on commit 39f1f40

Please sign in to comment.