This resource contains the Python version of the Layered Green & Ampt with Redistribution (LGAR) model at the time of publication of the LGAR paper: "Layered Green and Ampt Infiltration With Redistribution", La Follette et al. 2023. While LGAR was initially developed in Python, we no longer maintain the Python version of LGAR; development and maintenance have switched to C. LGAR as implemented in C can be found here: https://github.com/NOAA-OWP/LGAR-C . We recommend the use of the C version. LGAR as implemented in Python can also be found on github: https://github.com/NOAA-OWP/LGAR-Py/tree/LGAR-Py_public .

##Description
LGAR is a model which partitions precipitation into infiltration and runoff, and is designed for use in arid or semi arid climates. LGAR's main selling point is that it closely mimics precipitation partitioning results as simulated by the Richards equation (RE), without the inherent reliability and stability challenges the RE poses. Therefore, this model is useful when accurate, stable precipitation partitioning simulations are desired in arid or semi arid areas. LGAR as implemented in Python is BMI compatible. LGAR has been converted to C as well; we recommend the use of the C version ( https://github.com/NOAA-OWP/LGAR-C ) as the Python version is no longer maintained.

## Config file contents

The contents of the first two blocks of the config file for a model run are described here.

First block:

time_step: this is the model time step, expressed in hours. It defaults to a value of 300/3600, or 5 minutes expressed in hours.

initial_psi: this is the uniform capillary head throughout the model domain expressed in mm. Note that LGAR uses absolute values for capillary head, such that a value of 20000 mm for initial_psi physically represents soil with a capillary head of -20000 mm.

verbose: this can be True or False, where no output is printed to the screen during a model run if it is False.

length_of_simulation: This is the length of the simulation, in time steps.

closed_form_capillary_drive_term: set to True or False. This determines if the capillary drive term G is calculated with the numeric integral of hydraulic conductivity with respect to capillary head, or if the equivalence relations between van Genuchten and Brooks - Corey hydraulic models is used to achieve an approximate, closed form equation for G. Setting this value to True generally significantly increases the speed while insignificantly altering model results.

Second block:

output_file_name_fluxes: this will be the path and name of the output file which contains the fluxes for each time step of the simulation

params_file: this is the path and name of the parameters file

forcing_data_file: this is the forcing data file that is in the correct format for LGAR-Py

## parameter_files

Each parameter file, in the parameter_files folder, only has to be edited in the first block, which contains options related to soil hydraulic parameters, number of layers, maximum ponded head, and options related to the PET -> AET correction.

## forcing_data_files

This folder contains sub folders for each model run. All that is necessary to run LGAR is correctly formatted forcing data as a .csv. Raw USDA SCAN data and notebooks that convert these raw data to the format usable by LGAR are also provided. Currently, it is necessary that the forcing data resolution is the same as time_step as specified in the config file.

## other useful files

LGAR also requires the files LGAR_compute.py, test_env.py, and BMI_base_class.py, to be in the same directory.

The Jupyter notebooks (in vis_files) are useful for visualization of results. HYDRUS_files contains HYDRUS-1D model runs which are set up to simulate the same soil hydraulic conditions and forcing data as various LGAR runs.

## Running the model

In order to run LGAR, ensure that the correct config file is indicated in test_env.py, and then navigate in a terminal to the directory containing test_env.py and enter "python test_env.py".

## How to test the software

In the outputs folder, there are 6 complete simulation outputs, including 3 simulations of USDA SCAN sites, and 3 simulations with synthetically generated forcing datasets. All of the files necessary to run these simulations are also included. In order to check if LGAR is working properly for you, you can run these simulations and compare your results agains the outputs stored in this repo.

## Limitations

LGAR is designed for arid and semi arid areas only. Essentially, LGAR should not be used for groundwater simulations, and should only be used in semi arid or arid areas. Please see "Layered Green and Ampt Infiltration With Redistribution" (La Follette et al., 2023) for more details.