Introduction

Research in water-energy-land systems (WEL) [1, 2] and understanding the implications of water scarcity on WEL systems [3, 4, 5] is rapidly progressing. Additional impacts to water resource management are now also being considered when addressing supply-demand cycles and reservoir effects from potential water shortages [6]. Xanthos 2 was created to accommodate these progressive advancements in water-energy-land science that support cutting-edge research in human-Earth systems interactions. Currently, Xanthos 2 provides water supply, accessibility, and hydropower potential to the Global Change Assessment Model (GCAM) which is an integrated human-Earth systems model [7, 8, 9]. Xanthos 2 was built upon previous development by Li et al. [10] by creating a Python framework where core components of the model (potential evapotranspiration (PET), runoff generation, and river routing) can be interchanged or extended without having to start from scratch. Xanthos 2 utilizes a component-style architecture which enables researchers to quickly incorporate and test cutting-edge research in a stable modeling environment prebuilt with diagnostics to keep up with advancing science objectives. The new default configuration of Xanthos now supports the Penman-Monteith [11, 12] PET module which incorporates more comprehensive climate drivers as well as dynamic land cover data to allow land atmosphere interactions. The abcd water balance module was also added as the default runoff component to account for groundwater recharge and baseflow in runoff estimates [13]. Additionally, the following enhancements were also made: improved water velocity considerations for the Modified River Transport Model (MRTM) routing module [14, 15], hydropower production assessment and potential capacity modules, and a built-in differential evolution optimization module to calibrate abcd parameters based on benchmark global runoff.

Implementation and architecture

Xanthos 2 was created as a Python package to facilitate reuse. Xanthos runs are setup using a configuration file to describe which components of the model are used, data parameterization, run-specific settings, and more. A GitHub Wiki explaining how to set up a Xanthos run, and the required project level settings of the configuration file is available on the Xanthos GitHub website.¹ A list of available components with references to the algorithms from which they are derived is described in Table 1; though, the GitHub Wiki details each component’s configuration settings and variable descriptions for all additional model components.² The following is a simple example of how to call and run Xanthos in a Python script after it has been setup:

from xanthos import Xanthos
 
def run(ini):
 
    # instantiate model
    xth = Xanthos(ini)
 
    # run intended configuration
    xth.execute()
 
    return xth
 
if __name__ == “__main__”:
 
    # full path to parameterized config file
    ini = ‘<the directory path to your example
          directory>/pm_abcd_mrtm.ini’
 
    # run the model
    xth = run(ini)

Calling the execute() method after instantiating the Xanthos class will start a run and initialize the logger. The user will be updated as the model progresses through each step and as outputs are generated. Table 2 describes the expected outputs of a Xanthos run using the default core configuration and the accessible water, hydropower, diagnostics, and time series plots post-processing modules.

Xanthos 2 provides an extensible framework to interchange or add additional PET, runoff, and routing components of the core monthly water balance module (Figure 1). Post-processing modules (e.g., accessible water, hydropower potential, etc.) can also be added to create output products. A complete workflow for integrating a new component into Xanthos is provided in detail in an associated GitHub Wiki.³

Calibration module

The new default configuration of Xanthos contains the abcd water balance module to generate runoff as interpreted by Liu et al. [13]. The abcd module is driven by five aptly-named parameters: a which controls the amount of runoff that occurs when soils are under-saturated; b which controls the saturation level of the soil; c which defines the degree of recharge to groundwater; d which controls the rate of groundwater discharge; and m for snowpack accumulation and snowmelt estimates which was added by Martinez and Gupta [22]. The performance of the abcd module is influenced by per-basin a, b, c, d, m parameters which need to be calibrated based on the chosen climate forcing, PET, and runoff routines.

To accommodate the need for recalibration depending on experimental design, we chose to include a preconfigured calibration module in Xanthos 2 that uses SciPy’s differential evolution (DE) optimization function [23] based off of the algorithm presented in Storn and Price [21]. The DE method is useful for global optimization problems and is a stochastic population-based optimization method [23]. The objective function provided in Xanthos 2 evaluates the Kling-Gupta efficiency (KGE) which is a goodness-of-fit measure between simulated and observed runoff [24]; however, alternate methods could be utilized.

Figure 2 demonstrates the optimization module’s ability to calibrate Xanthos 2 runoff to the complex Variable Infiltration Capacity (VIC) model’s monthly runoff projections [25] when forced by WATer and global Change (WATCH) [26] climate data for years 1971–1991. The resulting median KGE for all basins was a respectable 0.9 which is an improvement to the calibration results of 0.79 generated by Liu et al. [13] when using MATLAB’s built-in genetic algorithm (GA) [27]. A tutorial describing how to setup and use the calibration module in Xanthos can be viewed on our GitHub repository.³

Installation

Xanthos can be installed using the following steps:

1. This repository uses the Git Large File Storage (LFS) extension (see https://git-lfs.github.com/ for details). Please install GitLFS and run the following command before cloning if you do not already have Git LFS initialized: git lfs install.
2. Clone Xanthos into your desired location git clone https://github.com/JGCRI/xanthos.git. Some Windows users have had better luck with git lfs clone https://github.com/JGCRI/xanthos.git.
3. Make sure that setuptools is installed for your Python version. This is what will be used to support the installation of the Xanthos package.
4. From the directory you cloned Xanthos into run python setup.py install. This will install Xanthos as a Python package on your machine and install the needed dependencies. If installing in a high-performance computing environment, a community user advised that it is best to install the anaconda environment before running the installation command. HPC environments may also require the use of the --user flag in the install command to avoid permissions errors.
5. Setup your configuration file (.ini). Examples are located in the “example” directory. Be sure to change the root directory to the directory that holds your data (use the “xanthos/example” directory as an example).
6. If running Xanthos from an IDE: Be sure to include the path to your config file. See the “xanthos/example/example.py” script as a reference.
7. If running Xanthos from terminal: Run model.py found in xanthos/xanthos/model.py, which passes the full path to the config file as the only argument. (e.g., python model.py <dirpath>/config.ini).

Quality control

Xanthos has been functionally tested on Linux, Mac OSX, and Windows to ensure model reusability. Xanthos has a built-in diagnostics module that compares model outputs to expected output from other mainstream hydrologic models when forced by the same climate assumptions. The calibration module output has also been evaluated as described in the “Calibration module” section of this paper. Exception handling is present throughout the model to ensure data consistency and provide informed feedback to the user for cases where an assumption has been violated. Extensive tests are built-in that validate the configuration file, and the contents thereof, that is provided by the user. Both expected inputs and outputs for each component have been provided as a baseline for comparability if the user decides to extend or alter the code for an intended purpose.

Operating system

Linux, Mac OSX, Windows 7 and 2012 server.

Programming language

Python 2.7, Python 3

Additional system requirements

We recommend a minimum RAM of 8GB due to routinely processing large datasets.

Dependencies

The following Python 3 packages are required for Xanthos:

• numpy >= 1.11
• scipy >= 0.18
• matplotlib>=1.3.1,<3.0
• pandas >= 0.19
• configobj >= 5.0.6
• joblib >= 0.11
• setuptools >= 24.2.0

Software location

Language

English