search

changliao1025 / swaty

Other
10 stars 1 forks source link

readme

Overview

SWATy is a Python package to support the Soil & Water Assessment Tool (SWAT) model simulation and calibration.

Currently, it does not build a SWAT model from scratch. Instead, it relies on an existing SWAT model that is often created by the ArcSWAT tool (https://swat.tamu.edu/software/arcswat/).

Once provided the existing SWAT model along with several outputs from the ArcSWAT tool, modelers can use SWATy to custmize the SWAT for different purposes/applications:

Installation

Currently, SWATy is only available through the PyPI. It would be available on the Conda platform soon.

SWATy depends on several Python packages, it is recommended to install these packages through Conda before installing SWATy in the correct order.

To avoid package conflict, it is also recommended to install SWATy in a new Conda environment using the following steps:

  1. conda create --name swaty python=3.8

  2. conda activate swaty

  3. conda install -c conda-forge numpy

  4. conda install -c conda-forge matplotlib

  5. conda install -c conda-forge pyearth

  6. pip install swaty

Usage

The notebook.py (https://github.com/changliao1025/swaty/blob/master/tests/example/notebook.py) and swat.ipynb files provide some quick start points to run the example either within a Python environment or a Jupter Notebook.

Below is some details of running the example using a pure Python environment.

SWATy uses the Object-oriented programming (OOP) approach to manage a SWAT model case, which is fully defined by the swatcase class (https://github.com/changliao1025/swaty/blob/master/swaty/classes/pycase.py)

To initialize a swatcase object, SWATy used a JSON file as configuration file which contains all the required information. Currently, the exmaple provides two options to either generate a JSON file on-the-fly or read an existing JSON file. Such a template JSON file is provided here: https://github.com/changliao1025/swaty/blob/master/tests/configurations/template.json

Below are some key content description in the template JSON file:

A swatcase object is often initialized by either 

oSwat = swaty_generate_template_configuration_file(sFilename_configuration_in, sWorkspace_input,sWorkspace_output, sPath_bin, iFlag_standalone_in=1, iCase_index_in=3, sDate_in='20220308')

or

oSwat = swaty_read_model_configuration_file(sFilename_configuration_in, iFlag_standalone_in=1,iCase_index_in=2,sDate_in='20220308', sWorkspace_input_in=sWorkspace_input, sWorkspace_output_in=sWorkspace_output)

After that, modelers can carry a SWAT simulation in the following steps:

The setup function

  1. Untar/copy the existing SWAT files into the simulation folder, output files are excluded.

  2. Generate the look-up table of HRU using the ArcSWAT reports.

  3. Replace the SWAT parameters for HRU, sub-basin, and watershed levels, if their corresponding flags are turned on.

  4. Copy the binary SWAT file to the simulation folder, update file permission.

  5. Generate both the bash and slurm job files, which can be used to run the SWAT simulation.

    oSwat.setup()

def setup(self):
    """
    Set up a SWAT case
    """
    self.copy_TxtInOut_files()
    self.swaty_prepare_watershed_configuration()      
    if (self.iFlag_replace_parameter == 1):
        self.swaty_prepare_watershed_parameter_file()
        self.swaty_write_watershed_input_file()    
        self.swaty_prepare_subbasin_parameter_file()
        self.swaty_write_subbasin_input_file()      
        self.swaty_prepare_hru_parameter_file()
        self.swaty_write_hru_input_file()        
    else:
        pass

    self.swaty_copy_executable_file()
    sFilename_bash = self.swaty_prepare_simulation_bash_file()
    sFilename_job = self.swaty_prepare_simulation_job_file() 
    return

The run function

The run function can run the SWAT simulation as a subprocess or submit the slurm job file.

oSwat.run()

The analyze function

After the simulation is finished, this function can

  1. extract river discharge and convert it other formats
oSwat.analyze()

The evaluate function

The evaluate function can be used to compare simulated variables with observations.

oSwat.evaluate()

Through the SWATy package, the whole SWAT simulation process can be automated. For example, modelers can launch multiple SWAT simulations with different parameters to conduct a simple sensitivity test.

Besides, SWATy can be linked to the PyPEST package to conduct model calibration using the PEST software.

Acknowledgement

This research was supported by several funding sources:

This contribution originates from an effort of hydrology-based design of geomorphic evapotranspiration covers for reclamation of mine land at Pacific Northwest National Laboratory (PNNL).

Contact

Please contact Chang Liao (changliao.climate@gmail.com) if you have any questions.