SWAT+ Editor Documentation

SWAT+ Editor Documentation Texas A&M AgriLife Research and the USDA-ARS Feb 26, 2019 User Docs 1 SWAT+ Resources 3 2 Contents: 5 2.1 Get Started Using SWAT+ Editor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 2.2 How to Use SQLite . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 2.3 SWAT+ Editor Design . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 2.4 Database Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 2.5 Release Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25 i ii SWAT+ Editor Documentation Desktop interface to SWAT+ allowing the user to import a project from GIS, modify SWAT+ input, write the text files, and run the model. User Docs 1 SWAT+ Editor Documentation 2 User Docs CHAPTER 1 SWAT+ Resources • SWAT+ Editor source code repository • SWAT+ source code repository maintained by Blackland 3 SWAT+ Editor Documentation 4 Chapter 1. SWAT+ Resources CHAPTER 2 Contents: 2.1 Get Started Using SWAT+ Editor SWAT+ Editor is still in the early phases of testing and development, so please proceed with caution. 2.1.1 What you’ll need • QSWAT+ • SWAT+ Databases • SWAT+ Editor Download from the SWAT website 2.1.2 Step 1: Set up your project in QSWAT+ First get your project set up in QSWAT+. After your project is set up, create a back up copy; SWAT+ Editor manipu- lates the database, so during these early stages it is good to have a copy of your project before opening it in the editor so that you may start over if needed. To open SWAT+ Editor, click the button for Step 3: Edit Inputs and Run SWAT from QSWAT+. 5 SWAT+ Editor Documentation 2.1.3 Step 2: Watch the MP4 video Please watch the guide video before launching SWAT+ Editor. This video will quickly walk you through the steps needed to bring your QSWAT+ project into the editor, as well as show you how to catch and report errors. 2.1.4 Current functionality available in SWAT+ Editor • Import weather generator data, add/edit/delete them • Import weather stations using SWAT2012 or SWAT+ formats, add/edit/delete them • Edit simulation times and print settings • Add/edit/delete channels, aquifers, reservoirs, as well as some routing unit and hru files • Write SWAT+ input files • Run SWAT+ • Import output files to SQLite for use in QSWAT+ visualizer 2.1.5 Help If you encounter an error, please follow the steps at the end of the guide video for capturing them fully. Contact Jaclyn by email or report the issue to the SWAT+ Editor issue tracker. Note: Subscribe to our mailing list to be notified of new releases 6 Chapter 2. Contents: SWAT+ Editor Documentation 2.2 How to Use SQLite As mentioned in the SWAT+ Editor Design doc, SWAT+ Editor uses uses a SQLite database to hold model input data to allow easy manipulation by the user. The database is structured to closely resemble the SWAT+ ASCII text files in order to keep a clean link between the model and editor. 2.2.1 Opening the SQLite Database We recommend users stick to the SWAT+ Editor program provided to browse and edit SWAT+ input data. However, if you need to access the database, we recommend using: • SQLite Studio There are many other alternatives out there. A few of them are: • DB Browser for SQLite • SQLite Manager, Firefox Add-On 2.2.2 Understanding Table Relationships SWAT+ contains many links between files, and the database follows suit by creating foreign key relationships where applicable. In the SWAT+ text files, you will see links reference object names. In the database however, these are done with an integer id. Luckily, relational databases make it easy to view the referenced row. In SQLite Studio, simply right-click a foreign key id in a row of data, and select “Go to referenced row in table ...” as shown in the image below. This will open the referenced row of data in a new tab. Results in: 2.2. How to Use SQLite 7 SWAT+ Editor Documentation 2.3 SWAT+ Editor Design SWAT+ Editor is a program that allows users to modify SWAT+ inputs easily without having to touch the SWAT+ input text files directly. The editor will import a watershed created in QSWAT+ or ArcSWAT+, or allow the user to create a SWAT+ project from scratch. The user may write input files and run the SWAT+ model through the editor. 2.3.1 Technologies The following software is used to create and build SWAT+ Editor: • Node.js 8.x • Electron 1.8.x • Vue.js 2.x • Bootstrap 4 • Python 3.x • PyInstaller • SQLite • Peewee ORM • Git repository hosted on Bitbucket • Read the Docs 2.3.2 Database Design SWAT+ Editor uses a SQLite database to hold model input data to allow easy manipulation by the user. The database is structured to closely resemble the SWAT+ ASCII text files in order to keep a clean link between the model and editor. The following conventions are used in the project database: • The table names will match the text file names, replacing any “.” or “-“ with an underscore “_”. • The table column names will match the model’s variable names. All names use lowercase and underscores. • Any text file with a variable number of repetitive columns will use a related table in the database. For example, many of the connection files contain a variable number of repeated outflow connection columns (obtyp_out, obtyno_out, hytyp_out, frac_out). In the database, we represent these in a separate table, basically transposing a potentially long horizontal file to columns. • All tables will use a numeric “id” as the primary key, and foreign key relationships will use these integer ids instead of a text name. This will allow for easier modification of these object names by the user and help keep the database size down for large projects. A separate SQLite database containing common datasets and input metadata will be provided with SWAT+ Edi- tor. (This is a replacement for the SWAT2012.mdb packaged with SWAT2012 versions of ArcSWAT, QSWAT, and SWATeditor.) In addition, reformatted SSURGO and STATSGO soils databases will be available for download. The structure of the soils database has been split into two tables: a soil table and soil_layer table. Similarly, the global weather weather generator database will be available for download in SQLite format. The struc- ture of the wgn database has been split into two tables: a wgn table and wgn_monthly_value table. A tool will be provided to convert old soils and wgn tables to the new format. 8 Chapter 2. Contents: SWAT+ Editor Documentation 2.3.3 SWAT+ Documentation SWAT+ is the latest version of the SWAT model, which is a command line executable written in Fortran. It uses several ASCII text files as inputs to the model. The documentation for these files is still under development. • SWAT+ code repository on Bitbucket 2.4 Database Documentation 2.4.1 Project Database The project database in SWAT+ Editor is made in SQLite. SWAT+ Editor uses the Peewee ORM (object-relational mapping) to represent and work with the tables in Python. The use of an ORM provides a layer of abstraction and portability in hopes of streamlining future SWAT+ development projects. Download a SQLite file containing the project table structure. Note: This page is incomplete and under development. Foreign Keys Relationships are defined in a Peewee ORM python class as a ForeignKeyField. In the python class, the field will be named after the object it is referencing. In the database, this name will automatically be appended by the referencing table’s column name, which is usually id. For example, we have two tables representing soils: soils (soils_sol) and layers (soils_sol_layer). The layer table has a foreign key to the main soils table, so we know to which soil the layer belongs. In the python class, this field is named soil, and in the database it is called soil_id. See the Soils module for reference. Modules and Tables A Python module is created for each input classification, based on the SWAT+ file.cio input file: • Simulation • Climate • Connect •