Basic usage¶
Welcome to the basic usage notebook of pySWAP package. Here we will go through the basics of how a SWAP model is constructed in pySWAP, load one of the test case models and explore it a bit.
import pyswap as psp
psp.log.set_log_level("WARNING")
pySWAP is an object-oriented library, which means that we try to split and encapsulate distinct parts of the SWAP model setup as objects. These objects need to be defined by the user at the initial stage and then can later be easily manipulated, copied and compared. Below is an example of the Meteorological settings object:
Hupselbrook testcase¶
A lot of the model settings still need to be explicitly written out. There is, however, an ongoing effort to reduce to minimum the amount of code that has to be written for the initial model. If you are interested how the Hupselbrook model is implemented in pySWAP, take a look at file hupselbrook.py in testcase module.
Let's load the model and check the metadata.
ml = psp.testcase.get("hupselbrook")
Model object has a method run, which runs the model and captures the results into a Result object. The only argument that needs to be passed is the path to where the temporary directory can be created.
print(ml.swp)
PROJECT = 'psp test - hupselbrook'
SWWBA = 0
SWEND = 0
SWVAP = 1
SWBAL = 0
SWBLC = 1
SWSBA = 1
SWATE = 0
SWBMA = 0
SWDRF = 0
SWSWB = 0
SWINI = 0
SWINC = 1
SWCRP = 0
SWSTR = 0
SWIRG = 0
SWCSV = 1
SWCSV_TZ = 0
PATHWORK = './'
PATHATM = './'
PATHCROP = './'
PATHDRAIN = './'
SWSCRE = 0
SWERROR = 1
TSTART = 2002-01-01
TEND = 2004-12-31
NPRINTDAY = 1
SWMONTH = 1
SWYRVAR = 0
DATEFIX = 31 12
OUTFIL = 'result'
SWHEADER = 0
INLIST_CSV = 'rain,irrig,interc,runoff,drainage,dstor,epot,eact,tpot,tact,qbottom,gwl'
SWAFO = 0
SWAUN = 0
SWDISCRVERT = 0
LAT = 52.00
SWETR = 0
SWDIVIDE = 1
SWRAIN = 0
SWETSINE = 0
METFIL = '283.met'
ALT = 10.00
ALTW = 10.00
ANGSTROMA = 0.25
ANGSTROMB = 0.50
SWMETDETAIL = 0
SWCROP = 1
RDS = 200.0
CROPSTART CROPEND CROPFIL CROPTYPE
2002-05-01 2002-10-15 'maizes' 1
2003-05-10 2003-09-29 'potatod' 2
2004-01-01 2004-12-31 'grassd' 3
SWIRFIX = 1
SWIRGFIL = 0
IRGFIL = 'swap'
IRDATE IRDEPTH IRCONC IRTYPE
2002-01-05 5.0 1000.0 1
SWINCO = 2
GWLI = -75.00
SWPONDMX = 0
SWRUNON = 0
RSRO = 0.500
RSROEXP = 1.00
PONDMX = 0.20
SWCFBS = 0
SWREDU = 1
CFEVAPPOND = 1.25
RSOIL = 30.00
COFREDBL = 0.35
RSIGNI = 0.50
SWSOPHY = 0
SWHYST = 0
SWMACRO = 0
TAU = 0.20
ISUBLAY ISOILLAY HSUBLAY HCOMP NCOMP
1 1 10.0 1.0 10
2 1 20.0 5.0 4
3 2 30.0 5.0 6
4 2 140.0 10.0 14
ORES OSAT ALFA NPAR KSATFIT LEXP ALFAW H_ENPR KSATEXM BDENS
0.01 0.42 0.0276 1.491 12.52 -1.060 0.0542 0.0 12.52 1315.0
0.02 0.38 0.0213 1.951 12.68 0.168 0.0426 0.0 12.68 1315.0
SWSNOW = 0
SWFROST = 0
SWKMEAN = 1
SWKIMPL = 0
DTMIN = 1e-06
DTMAX = 0.04
GWLCONV = 100.0
CRITDEVH1CP = 0.01
CRITDEVH2CP = 0.1
CRITDEVPONDDT = 0.0001
MAXIT = 30
MAXBACKTR = 3
SWDRA = 1
DRFIL = 'swap'
SWBBCFILE = 0
SWBOTB = 6
SWHEA = 0
SWSOLU = 0
result = ml.run()
Warning from module Readswap : simulation with additonal Ksat value (Ksatexm)
From now on, we can use Result object's attributes and computed fields to access the results. The .csv, for example, is already loaded as DataFrame.
result.output.keys()
dict_keys(['csv', 'blc', 'vap', 'inc'])
result.yearly_summary
| RAIN | IRRIG | INTERC | RUNOFF | EPOT | EACT | DRAINAGE | QBOTTOM | GWL | TPOT | TACT | DSTOR | |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| DATETIME | ||||||||||||
| 2002-12-31 | 84.18 | 0.5 | 3.74188 | 0.0 | 33.10679 | 16.68715 | 22.11357 | 0.0 | -1107.65824 | 38.71198 | 38.17328 | 3.96418 |
| 2003-12-31 | 71.98 | 0.0 | 2.05788 | 0.0 | 35.99241 | 17.17961 | 26.44815 | 0.0 | -1154.37603 | 29.41787 | 29.21504 | -2.92064 |
| 2004-12-31 | 80.55 | 0.0 | 4.91521 | 0.0 | 29.89227 | 17.88916 | 24.76607 | 0.0 | -1036.76085 | 32.57266 | 32.56927 | 0.41030 |
print(result.blc_summary)
* Project: psp test - hupselbrook
* File content: detailed overview of water balance components (cm)
* File name: ./result.blc
* Model version: Swap 4.2.0
* Generated at: 2025-02-17 18:26:18
Period : 2002-01-01 until 2002-12-31
Depth soil profile : 200.00 cm
=================================================+=================================================
INPUT | OUTPUT
PLANT SNOW POND SOIL | PLANT SNOW POND SOIL
=================================================+=================================================
Initially Present 0.00 0.00 71.60 | Finally present 0.00 0.00 75.56
Gross Rainfall 84.18 |
Nett Rainfall 0.00 80.44 | Nett Rainfall 80.44
Gross Irrigation 0.50 |
Nett Irrigation 0.50 | Nett Irrigation 0.50
| Interception 3.74
Snowfall 0.00 |
Snowmelt 0.00 | Snowmelt 0.00
| Sublimation 0.00
SSDI 0.00 | Plant Transpiration 38.17
| Soil Evaporation 16.69
Runon 0.00 | Runoff 0.00
Inundation 0.00 |
Infiltr. Soil Surf. 72.17 | Infiltr. Soil Surf. 72.17
Exfiltr. Soil Surf. 7.92 | Exfiltr. Soil Surf. 7.92
Infiltr. subsurf. | Drainage
- system 1 0.00 | - system 1 22.11
Upward seepage 0.00 | Downward seepage 0.00
=================================================+=================================================
Sum 84.68 0.00 88.85 143.76 | Sum 84.68 0.00 88.85 143.76
=================================================+=================================================
Storage Change 0.00 0.00 3.96
Balance Deviation 0.00 0.00 0.00 -0.00
===================================================================================================
Period : 2003-01-01 until 2003-12-31
Depth soil profile : 200.00 cm
=================================================+=================================================
INPUT | OUTPUT
PLANT SNOW POND SOIL | PLANT SNOW POND SOIL
=================================================+=================================================
Initially Present 0.00 0.00 75.56 | Finally present 0.00 0.00 72.64
Gross Rainfall 71.98 |
Nett Rainfall 0.00 69.92 | Nett Rainfall 69.92
Gross Irrigation 0.00 |
Nett Irrigation 0.00 | Nett Irrigation 0.00
| Interception 2.06
Snowfall 0.00 |
Snowmelt 0.00 | Snowmelt 0.00
| Sublimation 0.00
SSDI 0.00 | Plant Transpiration 29.22
| Soil Evaporation 17.18
Runon 0.00 | Runoff 0.00
Inundation 0.00 |
Infiltr. Soil Surf. 62.17 | Infiltr. Soil Surf. 62.17
Exfiltr. Soil Surf. 9.42 | Exfiltr. Soil Surf. 9.42
Infiltr. subsurf. | Drainage
- system 1 0.00 | - system 1 26.45
Upward seepage 0.00 | Downward seepage 0.00
=================================================+=================================================
Sum 71.98 0.00 79.35 137.73 | Sum 71.98 0.00 79.35 137.73
=================================================+=================================================
Storage Change 0.00 0.00 -2.92
Balance Deviation -0.00 0.00 0.00 -0.00
===================================================================================================
Period : 2004-01-01 until 2004-12-31
Depth soil profile : 200.00 cm
=================================================+=================================================
INPUT | OUTPUT
PLANT SNOW POND SOIL | PLANT SNOW POND SOIL
=================================================+=================================================
Initially Present 0.00 0.00 72.64 | Finally present 0.00 0.00 73.05
Gross Rainfall 80.55 |
Nett Rainfall 0.00 75.63 | Nett Rainfall 75.63
Gross Irrigation 0.00 |
Nett Irrigation 0.00 | Nett Irrigation 0.00
| Interception 4.92
Snowfall 0.00 |
Snowmelt 0.00 | Snowmelt 0.00
| Sublimation 0.00
SSDI 0.00 | Plant Transpiration 32.57
| Soil Evaporation 17.89
Runon 0.00 | Runoff 0.00
Inundation 0.00 |
Infiltr. Soil Surf. 67.29 | Infiltr. Soil Surf. 67.29
Exfiltr. Soil Surf. 9.55 | Exfiltr. Soil Surf. 9.55
Infiltr. subsurf. | Drainage
- system 1 0.00 | - system 1 24.77
Upward seepage 0.00 | Downward seepage 0.00
=================================================+=================================================
Sum 80.55 0.00 85.18 139.93 | Sum 80.55 0.00 85.18 139.93
=================================================+=================================================
Storage Change 0.00 0.00 0.41
Balance Deviation 0.00 0.00 0.00 0.00
===================================================================================================
None
result.csv[["RAIN", "IRRIG", "INTERC"]].plot()
<Axes: xlabel='DATETIME'>
Alternative way to load a model¶
Since pyswap 0.2.0, it is possible to load an entire model from the classic ascii configuration files. In order to do that, you need to create the swp and other relevant files separately and then put them together in a model. You can see it in the tutorial on loading classic SWAP model.
Changing the model settings¶
Assume you would like to add another file extension to be generated, or make any other change for that matter. The best way to achieve this is to create a copy of a component you want to alter, and then update the model with that new component, saving it's copy.
# updated general settings including inlist_csv_tz
ml.generalsettings.extensions = [*ml.generalsettings.extensions, "csv_tz"]
ml.generalsettings.inlist_csv_tz = ["WC"]
result2 = ml.run()
Warning from module Readswap : simulation with additonal Ksat value (Ksatexm)
from pyswap.core.plot import water_content
wc_df = result2.csv_tz.reset_index()
water_content(wc_df, "DEPTH", "DATE", "WC")
Alternative way to setup the model¶
Initially it was only possible to directly assign generated model components to the Model object attributes. Since the newest release (February 2025) it is possible to set up and run the model by loading the plain text files used traditionally to set up the model. See this notebook to see how to do it!