Tutorial 1: Setting up a Xanthos run

Set up configuration file

An example configuration file set to the default Penman-Monteith/ABCD/MRTM configuration is included here: examples/pm_abcd_mrtm.ini. The configuration parameters associated with each PET, runoff, and routing model option can be reviewed here: Available modules. To get started with the default configuration, set the following configuration variables to your local preferences:

In [PROJECT]...
RootDir = <the directory holding your input and output directories>

In [Runoff][abcd]...
TempMinFile = <the directory holding your example directory>/example/input/climate/tasmin_watch_monthly_degc_1991_2001.npy
PrecipitationFile = <the directory holding your example directory>/example/input/climate/pr_gpcc_watch_monthly_mmpermth_1991_2001.npy

In [Calibrate]...
observed =  <the directory holding your example directory>/example/input/calibration/vic_watch_basin_km3_1971_2001_monthly.csv
calib_out_dir = <a local directory of your choosing>

Required Project Level Configuration settings

Config tag:

[Project]

Variable	Description	Required
ProjectName	Name of the project that defines the name of the output directory; no spaces.	True
RootDir	Full path to the directory containing the input and output directories for the project.	True
InputFolder	Input directory name contained in the RootDir.	True
OutputFolder	Output directory name contained in the RootDir.	True
RefDir	Directory name where the reference data is contained in the input directory.	True
pet_dir	Directory name where the root PET module directories are kept in the inputs directory.	True
RunoffDir	Directory name where the root runoff module directories are kept in the inputs directory.	True
RoutingDir	Directory name where the root routing module directories are kept in the inputs directory.	True
DiagDir	Directory name where the diagnostics directory is contained in the input directory.	True
AccWatDir	Directory name where the accessible water input file directory is contained.	True
HydActDir	Directory name where the hydropower potential input file directory is contained.	True
HistFlag	If True, channel storage and soil moisture files are saved; if False, channel storage and soil moisture files are loaded when using the GWAM runoff module.	True
n_basin	The number of basins in the input data; integer.	True
StartYear	Start year of the run as an integer in YYYY format.	True
EndYear	End year of the run as an integer in YYYY format.	True
output_vars	Which variables to output, any of: 'pet' (potential evapotranspiration), 'aet' (actual evapotranspiration), 'q' (runoff), 'soilmoisture' (soil moisture), 'avgchflow' (average channel flow).	True
OutputFormat	The format to save the outputs in; 0 = NetCDF Classic, 1 = CSV, 2 = Matlab, 3 = Parquet.	True
OutputUnit	The unit to save the runoff outputs in; 0 = mm/time, 1 = km3/time, where time is either month or year.	True
OutputInYear	0 = output in month; 1 = aggregate into annual result.	True
AggregateRunoffBasin	Create output file that has runoff aggregated by basin. 0 = False, 1 = True.	True
AggregateRunoffCountry	Create output file that has runoff aggregated by country. 0 = False, 1 = True.	True
AggregateRunoffGCAMRegion	Create output file that has runoff aggregated by GCAM region. 0 = False, 1 = True.	True
PerformDiagnostics	1 = perform diagnostics, 0 = pass.	True
CreateTimeSeriesPlot	1 = create plots, 0 = pass.	True
CalculateAccessibleWater	1 = calculate accessible water, 0 = pass.	True
CalculateHydropowerPotential	1 = calculate hydropower potential, 0 = pass.	True
CalculateHydropowerActual	1 = calculate hydropower actual, 0 = pass.	True
Calibrate	1 = run ABCD runoff calibration module, 0 = pass.	True

Set up example.py

Change path to configuration file to your location and run!

from xanthos.model 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)