WaterSip: Difference between revisions

From gfi
No edit summary
(53 intermediate revisions by the same user not shown)
Line 1: Line 1:
====About WaterSip====
===About WaterSip===


WaterSip is a diagnostic software tool that identifies source, transport and arrival properties of atmospheric water vapour. It implements the moisture source diagnostic of Sodemann et al. (2008) for input data from either FLEXPART particle output or Lagranto trajectories.
WaterSip is a diagnostic software tool that identifies source, transport and arrival properties of atmospheric water vapour based on airmass backward trajectories. As a prerequisite, the backward trajectories for the analysis are to be obtained from a trajectory calculation tool, such as FLEXPART [[http://www.flexpart.eu]] or Lagranto [[http://www.lagranto.iac.ethz.ch]]. Moisture sources are then identified from changes in specific humidity interpolated to the air parcel trajectory per time step. The changes in specific humidity at each time step are set in relation with the current humidity of the air parcel. This allows to estimate the quantitative contribution of moisture to the air parcel at a specific location, a so-called moisture accounting. WaterSip identifies and aggregates further properties of the moisture source and during the moisture transport, such as temperature, pressure, latitude etc. The moisture source diagnostic is described in detail in [[Sodemann et al. (2008)]]. Publications using the WaterSip diagnostic are listed in section [[Bibliography]].


==== Input file options ====
===Working principle===
 
Explanation from Sodemann et al. 2008a
 
Image from Läderach and Sodemann, 2016 or Sodemann et al., 2008a
 
Moisture source information
 
- Accounted fraction fa, fb, fa+fb
- adding below and above boundary layer or not, when
- choosing threshold values for Arctic and other regions
- identifying moisture transport
 
Arrival information and Lagrangian forward projections
 
- arrival parameters
- transport parameters
- source parameters
- averaging by contribution and amount
 
Series information
 
- sectorization (Sodemann and Zubler, 2010; definition table, code changes)
- weighted averaging: The averaging over time steps, as required by different grid files, is done by weighting each time step contribution with the corresponding precipitation estimate, and deviding by the total precipitation.
 
Averaged properties
 
- histogram example and modification (code below)
 
Trajectories
 
- plotting/reading example (code below)
 
Uncertainties
 
===Example setups===
 
Three examples with different purposes
 
====Water vapour====
 
- considerations and parameters
 
====Extratropical precipitation====
 
- considerations and parameters
====High latitude precipitation====
 
- considerations and parameters
 
===Version history===
 
Version 2.1
 
Version 2.2
 
Version 2.3
 
Version 2.4
 
Version 2.5
 
Version 2.8
 
Version 2.8.1
 
Version 2.9
 
Version 2.9.1
 
Version 2.9.2
 
Version 2.9.3
 
Version 2.9.4
 
Version 3.0.8
 
Version 3.1
 
The current version of WaterSip is V3.1.0.
 
===Running the WaterSip diagnostic===
 
It is advised to create a link to the binary file of WaterSip in your /home/$USER/bin or project directory:
 
<pre>
mkdir ~/bin
ln -s /Data/gfi/projects/isomet/progs/WaterSip_tool/WaterSip3 ~/bin
</pre>
 
Adding <code>~/bin</code> to your path will make execution of WaterSip more comfortable. To start a diagnostic run, WaterSip needs to be called from the command line. This version reads one single input file during startup which contains all parameter settings required to execute a run (the examples below assume that you are in a working directory and WaterSip3 is at a location in your $PATH environment variable):
 
<pre>
module load netCDF-C++
WaterSip3 <WATERSIP_parameter_file>
</pre>
 
Note that the UiB hpc environment requires the above 'module load' command to be executed first.
 
On cyclone.hpc.uib.no, a run script is available that makes repeated similar runs easier to manage. Only essential parameters have to be changed, such as the target coordinates and case name. These will then be replaced on a template INPUT_WATERSIP file, and then WaterSip will be started. The script and an input file template can be copied like this:
 
<pre>
cp /Data/gfi/projects/isomet/projects/watersip/Bergen_iso/run_watersip_template_Bergen_2018.sh .
cp /Data/gfi/projects/isomet/projects/watersip/Bergen_iso/INPUT_WATERSIP_template_Bergen_2018 .
</pre>
 
====Input file conversion from V2====
 
The input file format, described below, is quite different in V3 than in previous versions. To facilite transition from V2.x input files, there is an option execute WaterSip3 with the option -c to convert to the new V3 input file format:
 
<pre>
WaterSip3 -c <WATERSIP_V2_parameter_file>
</pre>
 
This will create a new file named <WATERSIP_V2_parameter_file>V3 at the current directory. It is recommended to double check and edit the settings in the converted file before starting a simulation.
 
====Parallelization====
 
WaterSip3 has been parallelized with OpenMP, which can significantly speed up calculation time. The number of processors to be used is specified in the input file (see below).
 
If WaterSip3 is to be executed on a queue system (not applicable to cyclone.hpc.uib.no), the following wrapper script can be used to start a run using 4 cores for parallel processing:
 
<pre>
# start with sbatch NAME_OF_THIS_FILE directly on machine
 
#SBATCH --job-name=WaterSip3
#SBATCH --workdir=/tmp/
#SBATCH --partition=priority
#SBATCH --output=WaterSip_job.%j.out
#SBATCH --error=WaterSip_job.%j.err
#SBATCH --mail-type=END
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4
 
srun ./WaterSip3 INPUT_WATERSIP_global_1993
</pre>
 
=== Input file options ===


The WaterSip input file is a text file with options that are specified for different option groups. Option groups are identified by square brackets (e.g. <code>[Case]</code>). There are 7 option groups which can appear in random order in the input file:
The WaterSip input file is a text file with options that are specified for different option groups. Option groups are identified by square brackets (e.g. <code>[Case]</code>). There are 7 option groups which can appear in random order in the input file:
Line 16: Line 155:


====Parameter set Case====
====Parameter set Case====
- '''caseName (string):''' identifier for the run, prepended to all output files


<code>caseName = global_201002_final_relativex</code>
The settings in this parameter category describe the basic conditions of the diagnostic run.
 
;caseName (string)
: identifier for the run, prepended to all output files. Example: <code>caseName = global_201002_relative</code>
 
;inputDir (string)
: search path of the input files. The inputDir string ends with a placeholder for the files to be read in. For FLEXPART this will be either shortposit_ or partposit_. For Lagranto this will commonly be lsl_. The %s placeholder is completed by the currently read in date at runtime. Example: <code>inputDir = /Volumes/Data/global/shortposit_%s</code>
 
;outputDir (string)
: path where the output files will be created. Example: <code>outputDir = /Volumes/Data/global/output/</code>
 
;startDate (date string)
: inital date of the run, fixed format YYYYMMDD-HHMMSS. Start date is latest date of the run which moves backward in time. Example: <code>startDate = 20100228-180000</code>
 
;endDate (date string)
: final date of the run, fixed format YYYYMMDD-HHMMSS. End date is earliest date of the run. Example: <code>endDate = 20100211-000000</code>
 
;timeStep (integer)
: time step in hours between particles or trajectory output times. (typical values 6, 3, or 1 (hours)). Example: <code>timeStep = 6</code>
 
;trajPoints (integer)
: number of trajectory points to be considered in a trajectory. For 5-day trajectories with a 6 hour time step, 5x4+1=21 trajPoints should be selected. Example: <code>trajPoints = 21</code>
 
;minTrajPoints (integer)
: minimum length of trajectories to be included in analysis. Parameter is only relevant for Lagranto simulations with uneven trajectory length. Example: <code>minTrajPoints = 0</code>
 
;sectorizeRegion (integer)
: region set used to divide moisture sources into different sectors (see [[#sectorization]]). Example: <code>sectorizeRegion = 0</code>
 
;filterBoxFile (string)
: path to the text file describing geographic boxes used to filter air parcels during transport (see [[#box filters]]). Example: <code>filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste</code>
 
;filterIndex (integer)
: used line from the filterBoxFile to select/deselect trajectories. Example: <code>filterIndex = -1</code>
 
;orographyFile (string)
: path to the orography file used to select arrival based on underying topography, using the ETOPO2 topography. File in netcdf format. Example: <code>orographyFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/etopo5.nc"</code>
 
;lsmFile (string)
: path to the file with global land-sea-mask, currently from ERA-Interim data. Domain must be global but is in principle arbitrary. File in netcdf format. Example: <code>lsmFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/ERA_sea_mask_inv.nc"</code>
 
;maskFile (string)
: path to file with an arrival selection. Example: <code>maskFile = " "</code>
 
;useMask (boolean)
: use mask file (0=no, 1=yes). Example: <code>useMask = 0</code>
 
;ompThreads (integer)
: number of threads to be used with OpenMP parallelisation if compiled with flag -fopenmp (1=no parallelisation, >1 parallelisation activated.). Example: <code>ompThreads = 1</code>
 
;showStats (boolean)
: print statistics about particle processing to the command line (0=off, 1=on). Example: <code>showStats = 0</code>
 
----
 
====Parameter set Grids====
 
The parameters in this category specify the different output grids and the gridding method
 
;arrivalGridMinLon (float)
: minimum longitude of arrival (target region) grid box. Trajectories are traced backward from the arrival grid. Integrated source, transport and arrival parameters are put on the arrival grid, weighted by precipitation or water vapour of arriving air parcels. Example: <code>arrivalGridMinLon = -180</code>
 
;arrivalGridMaxLon (float)
: maximum longitude of arrival (target region) grid box. Example: <code>arrivalgridmaxlon = 180</code>
 
;arrivalGridMinLat (float)
: minimum latitude of arrival (target region) grid box. Example: <code>arrivalGridMinLat = -90</code>
 
;arrivalGridMaxLat (float)
: minimum latitude of arrival (target region) grid box. Example: <code>arrivalGridMaxLat = 90</code>
 
;arrivalGridDx (float)
: longitude increment of arrival (target region) grid. Example: <code>arrivalGridDx = 1</code>
 
;arrivalGridDy (float)
: latitude increment of arrival (target region) grid. Example: <code>arrivalGridDy = 1</code>
 
;arrivalGridRadius (float)
: gridding radius for information from arriving trajectories. Example: <code>arrivalGridRadius = 200</code>
 
;sourceGridMinLon (float)
: minimum longitude of moisture source grid box. Example: <code>sourceGridMinLon = -180</code>
 
;sourceGridMaxLon (float)
: maximum longitude of moisture source grid box. Example: <code>sourceGridMaxLon = 180</code>
 
;sourceGridMinLat (float)
: minimum latitude of moisture source grid box. Example: <code>sourceGridMinLat = -90</code>
 
;sourceGridMaxLat (float)
: maximum latitude of moisture source grid box. Example: <code>sourceGridMaxLat = 90</code>
 
;sourceGridDx (float)
: longitude increment of moisture source grid box. Example: <code>sourceGridDx = 1</code>
 
;sourceGridDy (float)
: latitude increment of moisture source grid box. Example: <code>sourceGridDy = 1</code>
 
;sourceGridRadius (float)
: longitude increment of moisture source grid box. Example: <code>sourceGridRadius = 200</code>
 
;griddingType (integer)
: select [[#gridding algorithm]] (1: fast and simple gridding, 2: improved but slower gridding). Example: <code>griddingType = 2</code>


- '''inputDir (string):''' search path of the input files. The inputDir string ends with a placeholder for the files to be read in. For FLEXPART this will be either shortposit_ or partposit_. For Lagranto this will commonly be lsl_. The %s placeholder is completed by the currently read in date at runtime.
----


<code>inputDir = /Volumes/Data/global/shortposit_%s</code>
====Parameter set Diagnostics====


- '''outputDir (string):''' path where the output files will be created.
The parameters in this category control the way how the diagnostic works, and which trajectories should be considered in the run.


<code>outputDir = /Volumes/Data/global/output/</code>
;uptakeThreshold (float)
: Threshold value for specific humidity increases per time step in air parcels to be considered as due to physical processes (evaporation), in g per kg. If the parameter reativeThresholds is set to true, the uptakeThreshold is specified as percent increase relative to the current specific humidity of an air parcel. Value is positive because of an air-parcel relative perspective. Default absolute values are 0.1 to 0.2 for 3h and 6h time steps. Example: <code>uptakeThreshold = 0.2</code>


- '''startDate (date string):''' inital date of the run, fixed format YYYYMMDD-HHMMSS. Start date is latest date of the run which moves backward in time.
;precipThreshold (float)
: Threshold value for specific humidity decreases per time step in air parcels to be considered as due to physical processes (precipitation), in g per kg. Value is negative because of an air-parcel relative perspective. If the parameter reativeThresholds is set to true, the precipThreshold is specified as percent decrease relative to the current specific humidity of an air parcel. Then the value is negative. Default absolute values are -0.1 to -0.2 for 3h and 6h time steps. Example: <code>precipThreshold = -0.2</code>


<code>startDate = 20100228-180000</code>
;relativeThreshold (boolean)
: determines whether absolute threshold values or relative threshold values are specified (0: absolute, 1: relative threshold values). Example: <code>relativeThreshold = 1</code>


- '''endDate (date string):''' final date of the run, fixed format YYYYMMDD-HHMMSS. End date is earliest date of the run.
;arrivalPrecipMin (float)
: Threshold value to consider precipitation events with a specific humidity decrease larger than the value given by <code>arrivalPrecipMin</code>. Units are g per kg when relativeThresholds is set to false, and fractional specific humidity decrease otherwise. For consistency, it is recommended to set the values for <code>precipitationThreshold</code> and <code>arrivalPrecipMin</code> to the same number. Example: <code>arrivalPrecipMin = -0.2</code>


<code>endDate = 20100211-000000</code>
;arrivalPrecipMax (float)
: Threshold value to consider precipitation events with a specific humidity decrease of up to the value given by <code>arrivalprecipMin</code>. Units are g per kg when relativeThresholds is set to false, and fractional specific humidity decrease otherwise. To include all precipitation events with a 6h time step, a value of -100.0 or lower can be chosen if <code>relativeThresholds</code> is set to false, or a value of 1.0 otherwise. The combination of the <code>arrivalPrecipMin/Max</code> parameters allows to focus on heavy and weak precipitation events only. Example: <code>arrivalPrecipMax = -100.0</code>


- '''timeStep (integer):''' time step in hours between particles or trajectory output times. (typical values 6, 3, or 1 (hours))
;arrivalRHMin (float)
: Threshold value to consider precipitation events when relative humidity at the arrival location is larger than the value given by . Example: <code>arrivalRHMin</code>. Units are %. Large-scale condensation can be assumed to occur above 80% relative humidity, to include convective cloud processes a lower threshold value may be required. Example: <code>arrivalRHMin = 80</code>


<code>timeStep = 6</code>
;arrivalRHMax (float)
: Threshold value to consider precipitation events when relative humidity at the arrival location is less than the value given by . Example: <code>arrivalRHMax</code>. Units are %. This parameter in combination with <code>arrivalRHMin</code> can be used to focus on condensation/no condensation cases when the parameter <code>analyzeVapour</code> is set to true. Example: <code>arrivalRHMax = 110</code>


- '''trajPoints (integer):''' number of trajectory points to be considered in a trajectory. For 5-day trajectories with a 6 hour time step, 5x4+1=21 trajPoints should be selected.
;arrivalOroMin (float)
: Threshold value to consider only arrival locations where the ETOPO2 topography exceeds the given value (in m). Use negative value to include all global locations, including ocean areas, Bangladesh and Death Valley. Example: <code>arrivalOroMin = -100</code>


<code>trajPoints = 21</code>
;arrivalOroMax (float)
: Threshold value to consider only arrival locations where the ETOPO2 topography does not exceed the given value (in m). In combination with . Example: <code>arrivalOroMin</code>, regions with a complex shape but common elevation can be selected easily. Example: <code>arrivalOroMax = 12000</code>


- '''minTrajPoints (integer):''' minimum length of trajectories to be included in analysis. Parameter is only relevant for Lagranto simulations with uneven trajectory length.
;arrivalAltMin (float)
: Threshold value to consider only arrival locations where the air parcels are above at the given altitude (in m above sea level). Example: <code>arrivalAltMin = -100</code>


<code>minTrajPoints = 0</code>
;arrivalAltMax (float)
: Threshold value to consider only arrival locations where the air parcels are below the given altitude (in m above sea level). The parameters <code>arrivalAltMin/Max</code> can be used to conduct vertically stratified analyses.Example: <code>arrivalAltMax = 12000</code>


- '''sectorizeRegion (integer):''' region set used to divide moisture sources into different sectors (see [[Sectorization]])
;blhScale (float)
: Scaling factor to decide for air parcels to be close enough to the boundary layer to consider moisture increases to evaporation to be likely due to surface evaporation below. A factor of 1.5 will assign all moisture increases within 1.5x the current boundary layer height to the category 'moisture sources boundary-layer', all others to the category 'moisture sources free troposphere'. Default value is 1.5. Example: <code>blhScale = 1.5</code>


<code>sectorizeRegion = 0</code>
;analyzeVapour (boolean)
: Parameter allowing to consider all air parcels that precipitate according to the . Example: <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters (0: false), or all parameters irrespective of arrival precipitation (1: true). If set to false, the weighting of source, transport and arrival properties is done using the precipitation estimate calculated from the specific humidity change during arrival. Otherwise, the weight is provided by the arrival specific humidity. When analyzeVapour is set to true, many more particles are considered, and the <code>arrivalRHMin/Max</code> parameters may need adjustment. Example: <code>analyzeVapour = 0</code>


- '''filterBoxFile (string):''' path to the text file describing geographic boxes used to filter air parcels during transport (see [[Box filters]]).
;assignToUptake (boolean)
: Parameter determining the assignment of moisture uptake events to arrival time (0: disabled) or to uptake time step grid (1: enabled). The effect of this parameter will most clearly be visible on stepwise and daily output files. It can be used to relate evaporation events to the concurrent meteorological situation. Example: <code>assignToUptake = 0</code>


<code>filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste</code>
;forwardProjectionMode (integer)
: Parameter determining how the Lagrangian forward projection of [[#moisture source and moisture transport properties]] are calculated (1: only consider boundary-layer moisture uptakes, 2: only consider free-troposphere uptakes, 3: consider both uptakes in combination). The default value is 3 (both, boundary layer and free-troposphere uptakes). Example: <code>forwardProjectionMode = 3</code>


- '''filterIndex (integer):''' used line from the filterBoxFile to select/deselect trajectories
----


<code>filterIndex = -1</code>
====Parameter set Output====


- '''orographyFile (string):''' path to the orography file used to select arrival based on underying topography, using the ETOPO2 topography. File in netcdf format.
The parameters in this category determine which output files should be created.


<code>orographyFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/etopo5.nc"</code>
;stepFile (boolean)
: write parameters on [[#Grid files]] and [[#Series files]] for each time step. Example: <code>stepFile = 1</code>


- '''lsmFile (string):''' path to the file with global land-sea-mask, currently from ERA-Interim data. Domain must be global but is in principle arbitrary. File in netcdf format.
;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>


<code>lsmFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/ERA_sea_mask_inv.nc"</code>
;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>


- '''maskFile (string):''' path to file with an arrival selection
;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>


<code>maskFile = " "</code>
;allFile (boolean)
: write parameters on grid and series files averaged/accumulated for all time steps. Example: <code>allFile = 1</code>


- '''useMask (boolean):''' use mask file (0=no, 1=yes).
;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</code>


<code>useMask = 0</code>
;saveTraj (integer)
: write particle trajectories to [[#Trajectory files]] at each time step (1) or each month (2). Option 0 disables trajectory output. Example: <code>saveTraj = 0</code>


- '''ompThreads (integer):''' number of threads to be used with OpenMP parallelisation if compiled with flag -fopenmp (1=no parallelisation, >1 parallelisation activated.)
;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>


<code>ompThreads = 1</code>
;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <code>saveHistogram = 0</code>


- '''showStats (boolean):''' print statistics about particle processing to the command line (0=off, 1=on).
;saveMean (boolean)
: write means, minimum, maximum and standard deviation to [[#Mean file]]. This is duplicate information with the series files but available for historical reasons. The option will be removed in a forthcoming version (0: disabled, 1:enabled). Example: <code>saveMean = 0</code>


<code>showStats = 0</code>
----


====Parameter set [Grids]====
====Parameter set Variables====
- '''arrivalGridMinLon (float):''' minimum longitude of arrival (target region) grid box. Trajectories are traced backward from the arrival grid. Integrated source, transport and arrival parameters are put on the arrival grid, weighted by precipitation or water vapour of arriving air parcels.
<code>arrivalGridMinLon = -180</code>
- '''arrivalGridMaxLon (float):''' maximum longitude of arrival (target region) grid box
<code>arrivalGridMaxLon = 180</code>
- '''arrivalGridMinLat (float):''' minimum latitude of arrival (target region) grid box
<code>arrivalGridMinLat = -90</code>
- '''arrivalGridMaxLat (float):''' minimum latitude of arrival (target region) grid box
<code>arrivalGridMaxLat = 90</code>
- '''arrivalGridDx (float):''' longitude increment of arrival (target region) grid
<code>arrivalGridDx = 1</code>
- '''arrivalGridDy (float):''' latitude increment of arrival (target region) grid
<code>arrivalGridDy = 1</code>
- '''arrivalGridRadius (float):''' gridding radius for information from arriving trajectories
<code>arrivalGridRadius = 200</code>
- '''sourceGridMinLon (float):''' minimum longitude of moisture source grid box
<code>sourceGridMinLon = -180</code>
- '''sourceGridMaxLon (float):''' maximum longitude of moisture source grid box
<code>sourceGridMaxLon = 180</code>
- '''sourceGridMinLat (float):''' minimum latitude of moisture source grid box
<code>sourceGridMinLat = -90</code>
- '''sourceGridMaxLat (float):''' maximum latitude of moisture source grid box
<code>sourceGridMaxLat = 90</code>
- '''sourceGridDx (float):''' longitude increment of moisture source grid box
<code>sourceGridDx = 1</code>
- '''sourceGridDy (float):''' latitude increment of moisture source grid box
<code>sourceGridDy = 1</code>
- '''sourceGridRadius (float):''' longitude increment of moisture source grid box
<code>sourceGridRadius = 200</code>
- '''griddingType (integer):''' select [[gridding algorithm]] (1: fast and simple gridding, 2: improved but slower gridding)
<code>griddingType = 2</code>


**[Diagnostics]**
The parameters in this category allow to include or exclude specific variables from the output files. Setting the output for unused variables to 0 (disabled) will speed up computation time, reduce the memory footprint, and reduce the output file size. Only parameters that are really required from a run should therefore selected as enabled.
- '''uptakeThreshold (float):'''
<code>uptakeThreshold = 0.05</code>
- '''precipThreshold (float):'''
<code>precipThreshold = 0.05</code>
- '''blhScale (float):'''
<code>blhScale = 1.5</code>
- '''arrivalPrecipMin (float):'''
<code>arrivalPrecipMin = 0.05</code>
- '''arrivalPrecipMax (float):'''
<code>arrivalPrecipMax = 1.0</code>
- '''arrivalRHMin (float):'''
<code>arrivalRHMin = 80</code>
- '''arrivalRHMax (float):'''
<code>arrivalRHMax = 110</code>
- '''arrivalOroMin (float):'''
<code>arrivalOroMin = -100</code>
- '''arrivalOroMax (float):'''
<code>arrivalOroMax = 12000</code>
- '''arrivalAltMin (float):'''
<code>arrivalAltMin = -100</code>
- '''arrivalAltMax (float):'''
<code>arrivalAltMax = 12000</code>
- '''analyzeVapour (boolean):'''
<code>analyzeVapour = 0</code>
- '''assignToUptake (boolean):'''
<code>assignToUptake = 0</code>
- '''forwardProjectionMode (integer):'''
<code>forwardProjectionMode = 3</code>
- '''relativeThreshold (boolean):'''
<code>relativeThreshold = 1</code>


**[Output]**
;sourcesBoundaryLayer (boolean)
- '''stepFile (boolean):''' write parameters on grid and series files for each time step
: write accounted moisture uptakes in the boundary layer to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: <code>sourcesBoundaryLayer = 1</code>
<code>stepFile = 1</code>
- '''dayFile (boolean):''' write parameters on grid and series files averaged/accumulated for each day
<code>dayFile = 1</code>
- '''monthFile (boolean):''' write parameters on grid and series files averaged/accumulated for each month
<code>monthFile = 1</code>
- '''yearFile (boolean):''' write parameters on grid and series files averaged/accumulated for each year
<code>yearFile = 1</code>
- '''allFile (boolean):''' write parameters on grid and series files averaged/accumulated for all time steps
<code>allFile = 1</code>
- '''staticFields (boolean):''' write static fields (land-sea mask and topography) onto grid files
<code>staticFields = 1</code>
- '''saveTraj (integer):''' write particle trajectories to [[traj files]] at each time step (1) or each month (2). Option 0 disables trajectory output.
<code>saveTraj = 0</code>
- '''skipTraj (boolean):''' write every nth trajectory to reduce traj file size (0 or 1:disabled, >=2: stride size)
<code>skipTraj = 0</code>
- '''saveHistogram (boolean):''' write histogram for selected parameters to a [[histogram file]] (0: disabled, 1:enabled)
<code>saveHistogram = 0</code>
- '''saveMean (boolean):''' write means, minimum, maximum and standard deviation to [[mean file]]. This is duplicate information with the series files but available for historical reasons. The option will be removed in a forthcoming version (0: disabled, 1:enabled).
<code>saveMean = 0</code>


**[Variables]**
;sourcesFreeTroposphere (boolean)
<code>sourcesBoundaryLayer = 1</code>
: write accounted moisture uptakes in the free troposphere to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: <code>sourcesFreeTroposphere = 1</code>
<code>sourcesFreeTroposphere = 1</code>
<code>evaporationMinusPrecipitation = 1</code>
<code>moistureTransport = 1</code>
<code>trajectoryLocations = 1</code>
<code>precipitationEstimate = 1</code>
<code>sourceLongitude = 1</code>
<code>sourceLatitude = 1</code>
<code>convectionCount = 0</code>
<code>convectionHeight = 0</code>
<code>landFraction = 1</code>
<code>boundaryLayerFraction = 1</code>
<code>freeTroposphereFraction = 1</code>
<code>combinedFraction = 0</code>
<code>transportTime = 1</code>
<code>sourceSkinTemperature = 1</code>
<code>sourceSpecificHumidity = 0</code>
<code>transportDistance = 1</code>
<code>sourceDistance = 1</code>
<code>source2mTemperature = 0</code>
<code>sourceDeuteriumExcess = 1</code>
<code>transportTemperature = 1</code>
<code>transportPressure = 1</code>
<code>condensationTemperature = 1</code>
<code>arrivalTemperature = 1</code>
<code>arrivalPressure = 1</code>
<code>arrival2mTemperature = 0</code>
<code>arrivalSkinTemperature = 1</code>


**[Flexpart]**
;evaporationMinusPrecipitation (boolean)
<code>inputFormat = 3</code>
: write unweighted evaporation minus precipitation along entire trajectory length to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: <code>evaporationMinusPrecipitation = 1</code>
<code>maxPart = 5000000</code>
<code>partMass = 1.01943e+12</code>
<code>partStride = 10</code>
<code>allowReenter = 1</code>


;moistureTransport (boolean)
: write weighted moisture transport along trajectories to grid and series output files (0: disabled, 1: enabled). Units are mm. Example: <code>moistureTransport = 1</code>


Full example for a FLEXPART run input file:
;trajectoryLocations (boolean)
: write trajectory locations to grid and series output files (0: disabled, 1: enabled). Units are counts per km<sup>2</sup>. Example: <code>trajectoryLocations = 1</code>
 
;precipitationEstimate (boolean)
: write precipitation estimate at arrival to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: <code>precipitationEstimate = 1</code>
 
;sourceLongitude (boolean)
: write weighted moisture source longitude projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are degrees longitude. Example: <code>sourceLongitude = 1</code>
 
;sourceLatitude (boolean)
: write moisture source latitude projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are degrees latitude. Example: <code>sourceLatitude = 1</code>
 
;convectionCount (boolean)
: write convection count projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are counts per km<sup>2</sup>. Convection count can be written to the FLEXPART particle files with a special version of FLEXPART_WATER. convectionCount is not on the ERA-Interim climatology run. The counter is increased each time the particles passes the convection scheme upwards. Example: <code>convectionCount = 0</code>
 
;convectionHeight (boolean)
: write convection height projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Convection height can be written to the FLEXPART particle files with a special version of FLEXPART_WATER. convectionHeight is not on the ERA-Interim climatology run. The value gives an average height of vertical displacement when the particles passes the convection scheme. Example: <code>convectionHeight = 0</code>
 
;landFraction (boolean)
: write fraction of moisture sources over land projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: <code>landFraction = 1</code>
 
;boundaryLayerFraction (boolean)
: write accounted fraction of boundary layer uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: <code>boundaryLayerFraction = 1</code>
 
;freeTroposphereFraction (boolean)
: write accounted fraction of free troposphere uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: <code>freeTroposphereFraction = 1</code>
 
;combinedFraction (boolean)
: write accounted fraction of boundary layer and free troposphere uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). This is the sum of the two previous variables. Example: <code>combinedFraction = 0</code>
 
;transportTime (boolean)
: write moisture transport time projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are hours. Example: <code>transportTime = 1</code>
 
;sourceSkinTemperature (boolean)
: write skin temperature at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that skin temperature is a variable on the particle or trajectory files. Example: <code>sourceSkinTemperature = 1</code>
 
;sourceSpecificHumidity (boolean)
: write surface specific humidity at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are g per kg. Requires that source specific humidity is a variable on the particle or trajectory files. Example: <code>sourceSpecificHumidity = 0</code>
 
;transportDistance (boolean)
: write transport distance projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Transport distance is the length of the actual travel path along the trajectories from moisture source to the arrival region. Example: <code>transportDistance = 1</code>
 
;sourceDistance (boolean)
: write source distance projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Source distance is the shortest distance between the moisture source and the arrival region. Example: <code>sourceDistance = 1</code>
 
;source2mTemperature (boolean)
: write 2m temperature at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Example: <code>source2mTemperature = 0</code>
 
;sourceDeuteriumExcess (boolean)
: write deuterium excess projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are permil. Deuterium excess is calculated from the relative humidity with respect to SST and the relationship from Pfahl and Sodemann (2014). Requires that source specific humidity is a variable on the particle or trajectory files. Example: <code>sourceDeuteriumExcess = 1</code>
 
;transportTemperature (boolean)
: write moisture-weighted temperature during transport projected to arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Example: <code>transportTemperature = 1</code>
 
;transportPressure (boolean)
: write moisture-weighted pressure during transport projected to arrival region to grid and series output files (0: disabled, 1: enabled). Units are hPa. Example: <code>transportPressure = 1</code>
 
;condensationTemperature (boolean)
: write moisture-weighted temperatures where RH<sub>liquid</sub> exceeds 80% to grid and series output files (0: disabled, 1: enabled). Units are K. Example: <code>condensationTemperature = 1</code>
 
;arrivalTemperature (boolean)
: write temperature during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Example: <code>arrivalTemperature = 1</code>
 
;arrivalPressure (boolean)
: write pressure during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are hPa. Example: <code>arrivalPressure = 1</code>
 
;arrival2mTemperature (boolean)
: write temperature at 2m during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that 2m temperature is a variable on the particle or trajectory files. Example: <code>arrival2mTemperature = 0</code>
 
;arrivalSkinTemperature (boolean)
: write skin temperature during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that skin temperature is a variable on the particle or trajectory files. Example: <code>arrivalSkinTemperature = 1</code>
 
----
 
====Parameter set Flexpart====
 
The parameters in this category describe the properties specific to FLEXPART input files.
 
;inputFormat (integer)
: file format of FLEXPART particle position output files. 0: regional long output format, 1: global analysis data output format, 2: regional short format, 3: global reanalysis/NorESM data short format, 4: global reanalysis data long format, 5 regional reanalysis/NorESM data short format. Example: <code>inputFormat = 3</code>
 
;maxPart (integer)
: number of particles contained in a single FLEXPART partposit or shortposit file. Example: <code>maxPart = 5000000</code>
 
;partMass (float)
: atmospheric mass represented by each particle in kilogramms. Parameter is written out by specific version of FLEXPART to create WaterSip output data. Example: <code>partMass = 1.01943e+12</code>
 
;partStride (integer)
: number of particles to skip during processing to speed up calculations (1: use every particle, >=2: use every 2nd particle, etc). Example: <code>partStride = 10</code>
 
;allowReenter (boolean): needs to be enabled for global simulations, and disabled for regional domain-filling runs to avoid double accounting of air parcels (0: disabled, 1: enabled). Example: <code>allowReenter = 1</code>
 
----
 
====Parameter set Lagranto====
 
The parameters in this category describe the properties specific to FLEXPART input files.
 
----
 
===Full example for a FLEXPART run input file:===


<pre>
<pre>
[Case]
[Case]
caseName = global_201002_final_relativex
caseName = global_201002_final_relativex
inputDir = /Volumes/Data_B/flexpart/global/shortposit_%s
inputDir = /home/data/flexpart/global/shortposit_%s
outputDir=/Volumes/Data_B/watersip/global_201002_V3/
outputDir=/home/data/watersip/global_201002_V3/
startDate = 20100228-180000
startDate = 20100228-180000
endDate = 20100211-000000
endDate = 20100211-000000
timeStep = 6
timeStep = 6
sectorizeRegion = 0
sectorizeRegion = 0
filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste
filterBoxFile = /home/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste
filterIndex = -1
filterIndex = -1
orographyFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/etopo5.nc"
orographyFile = "/home/projects/WaterSip_tool/etopo5.nc"
lsmFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/ERA_sea_mask_inv.nc"
lsmFile = "/home/projects/WaterSip_tool/ERA_sea_mask_inv.nc"
maskFile = " "
maskFile = " "
useMask = 0
useMask = 0
Line 313: Line 570:
allowReenter = 1
allowReenter = 1
</pre>
</pre>
===Output file formats===
The results from the WaterSip diagnostic are written to a set of output files in different format. The main output files are created in netCDF with detailed metadata information, including the parameter settings of the run for automated documentation. The creation of different output files can be adapted by parameter settings in parameter set *Output* and the contained variables with settings in parameter set *Variables*. Spatial fields at different time intervals are written to so-called grid files in [[netCDF]] format, time series of averaged quantities at different time intervals are written to so-called Series files in netCDF format, histograms of selected quantities identified during the processing for each time step and each trajectory are written to Histogram files in ASCII format, and trajectories are written to Trajectory files in either the binary format traj or the Lagranto ASCII format. Earlier versions than V3 reported output in so-called Mean files in an ASCII format. That format is documented here but no longer in use in current versions of WaterSip.
The time unit has changed in Version 3.1. Previously, the unit was set to "days since 0000-01-02 00:00:00" to allow matlab-compatible values for time that could directly be utilized with the datenum() commands. In order to confirm to netCDF-CF standards, where no calendar year 0000 exists, the time unit is now "days since 0001-01-01 00:00:00". This provides the ability to open and visualize netCDF output files directly with tools such as ncview and panoply. To convert the time values into a matlab datenum compatible value, the following commands have to be used:
<pre>
ncid=netcdf.open(filename,"noclobber");
tim=(float)netcdf.getVar(ncid,"time");
tim=tim-datenum(1,0,1);
datestr(tim)
</pre>
The table below summarizes the available output files:
{| class="wikitable"
! Name !! Content !! Format !! Filename
|-
| Grid files || Spatial properties of moisture sources and arrival regios || netCDF || CASE_grd_all/year/month/day/step.nc
|-
| Series files || Mean/min/max/std of regionally and globally averaged moisture source and arrival region properties || netCDF || CASE_ser_all/year/month/day/step.nc
|-
| Histogram files || Histograms of quantities identified for each timestep along each trajectory || ASCII || CASE_hst_steps
|-
| Trajectory files || Trajectories for identified precipitation events || ASCII/binary traj || CASE_DATE.traj/CASE_DATE_lsl
|}
====Grid files====
Grid file variables are separated into immediate source and transport variables, typically on a coarser, global grid, and arrival and forward-projected variables on the (typically finer-scale) arrival grid. The grid settings are determined by the corresponding parameters in parameter set *Grid*. All variables are of type float, and the fill value (netCDF property _FillValue) is -999.99. The averaging over time steps, as required by different grid files, is done by weighting each time step contribution with the corresponding precipitation estimate, and dividing by the total precipitation (as described above).
**Moisture source and transport properties**
Variables related to immediate moisture source and transport properties (not forward projected) have dimension of variables time, global_latitude, global_longitude, as defined by input file parameters *sourceGridMinLon,sourceGridMaxLon, sourceGridMinLat, sourceGridMaxLat, sourceGridDx, sourceGridDy, sourceGridRadius*.
| Name | Symbol | Units | Description |
|:--|:--|:--|:--|
| moisture_uptakes_boundary_layer | E_s^BL | mm (step)h^-1 or mm 24h^-1 | text |
| moisture_uptakes_free_troposphere | E_s^FT | mm (step)h^-1 or mm 24h^-1 | text |
| evaporation_minus_precipitation | E-P | mm (step)h^-1 or mm 24h^-1 | text |
| moisture_transport | Q_t | mm |  text |
| trajectory_location | N_t | counts km^-2 | text |
**Arrival properties and Lagrangian forward projections**
The variables contained in these files have the dimensions time (days since 0001-01-01 00:00:00), latitude (degrees_north), and longitude (degrees_east) as defined by input file parameters *arrivalGridMinLon, arrivalGridMaxLon, arrivalGridMinLat, arrivalGridMaxLat, arrivalGridDx, arrivalGridDy, arrival | source | text |GridRadius*.
| Name | Symbol | Unit | Property | Description |
|:--|:--|:--|:--|:--|
| precipitation_estimate | PE | mm day^-1 or mm step^-1 | arrival | precipitation at arrival location estimated from change in specific humidity during last time step |
| arrival_temperature | T_a | K | arrival | PE-weighted temperature at trajectory location and elevation during arrival |
| arrival_pressure | p_a | hPa | arrival | PE-weighted pressure at trajectory location and elevation during arrival |
| arrival_skin_temperature | SKT_a | K | arrival | PE-weighted SKT below trajectory location during arrival |
| accounted_fraction_boundary_layer | f_BL | fraction | arrival | fractional contribution of BL moisture sources to PE |
| accounted_fraction_free_troposphere | f_FT | fraction | arrival | fractional contribution of FT moisture sources to PE |
| precipitation_lifetime | \tau_t | h | transport | contribution and precipitation-weighted precipitation life time |
| transport_distance | \Delta_t | km | transport | contribution and precipitation-weighted transport distance along trajectory |
| moisture_transport_temperature | T_t | K | transport | contribution and precipitation-weighted temperature during moisture transport |
| moisture_transport_pressure | p_t | hPa | transport | contribution and precipitation-weighted pressure during moisture transport |
| condensation_temperature | T_c | K | transport | contribution and precipitation-weighted temperature when RH>80% during transport |
| source_longitude | \lambda_s | degrees_east | source | contribution and precipitation-weighted latitude of the moisture source |
| source_latitude | \phi_s | degrees_north | source | contribution and precipitation-weighted longitude of the moisture source |
| land_fraction | f_l | fraction | source | contribution and precipitation-weighted fraction of moisture sources over land |
| source_skin_temperature | SKT_s | K | source | contribution and precipitation-weighted SKT at the moisture source |
| source_distance | \Delta_s | km | source | contribution and precipitation-weighted direct distance between the moisture source and arrival location |
| deuterium_excess | d_s | permil | source | contribution and precipitation-weighted estimate of deuterium excess at the source from RH and T using the Pfahl and Sodemann (2013) relation |
**Global attributes**
The netCDF grid files contain a range of essential parameters as global attributes. These parameters allow to fully characterise the result of the WaterSip run as required for the interpretation of the results. A number of run parameters are omitted, that concern logistical settings, or that are self-evident from the content of the the output files. The table below gives an example for a WaterSip run:
| Parameter | Example | Type |
|:--|:--|:--|
| startDate | "2010-02-28 00:00:00 +0000"| string |
| endingDate | "2010-01-11 00:00:00 +0000"| string |
| analysisRegion | "NEEM"| string |
| maxPart | 5000001 | int |
| caseName | "global_201002_V3_stride"| string |
| trajPoints | 61 | int |
| timeStep | 6 | in float |
| partMass | 2.03885996E12 |  float |
| dryLevel | 0.01 | float |
| blhScale | 1.5 |  float |
| rhMin | 80.0 |  float |
| rhMax | 110.0 |  float |
| uptakeThreshold | 0.2 |  float |
| precipThreshold | -0.2 | float |
| arrPrecipMin | -0.2 | float |
| arrPrecipMax | -120.0 | float |
| arrOroMin | 0.0 | float |
| arrOroMax | 9000.0 | float |
| arrAltMin | 0.0 | float |
| arrAltMax | 9000.0 | float |
| anaVapour | 0 | int |
| filterIndex | -1 | int |
====Series files====
The netCDF series files contain two sets of information. The so-called sectorization output provides time series of the moisture source information seperated into relative contributions from predefined geographical areas. Furthermore, the series files contains weighted averages and further statistical properties of all quantities in the grid files.
**Sectorisation output**
A set of sectorisations is chosen by the parameter *sectorizeRegion*. The currently available options are listed in the table below. New sectorisations can be defined by changing the code in routine <code>Sectors.cpp/Sectors.h</code>. This requires defining a new name and new decision tree that provides a unique number for any lat/lon value between -180E to 180E and -90 to 90N. See comments in the code.
For each of the predefined areas, the relative contributions are subdivided into land and sea covered areas. Time series of the contributions are of dimension time and sector. Thereby, the sector numbers correspond to the sector numbers defined in the program code. The area of the sectors is calculated automatically within WaterSip. As noted above for the grid files, the time unit has been changed starting from Version 3.1.
| Variable | Symbol | Unit | Description |
|:--|:--|:--|:--|
| time | t | days since 0001-01-01 00:00:00 |
| sector | s | sector number |
| sector_area | A_s | km^2 |
| land_fraction_moisture_uptakes_boundary_layer | f_l^BL | percent |
| sea_fraction_moisture_uptakes_boundary_layer | f_s^BL | percent |
| land_fraction_moisture_uptakes_free_troposphere | f_l^FT | percent |
| sea_fraction_moisture_uptakes_free_troposphere | f_s^FT | percent |
| land_fraction_trajectory_location | f_l^N | percent |
| sea_fraction_trajectory_location | f_s^N | percent |
| land_fraction_moisture_transport | f_l^Q | percent |
| sea_fraction_moisture_transport | f_s^Q | percent |
| land_fraction_evaporation_minus_precipitation | f_l^EP | percent |
| sea_fraction_evaporation_minus_precipitation | f_s^EP | percent |
**Time-series output**
For immediate quantities, a time series of the total field sum is recorded in the series file. In order to obtain an area average, one needs to divide the sum by the surface of the earth (x km^2). The unit for moisture uptakes, E-P and precipitation estimate is mm step^-1 for step series files, and mm 24h^-1 for all other averaging series files. In addition to sums, the files contain time series of the minimum, maximum and standard deviation of the grid field at each time instance. For all forward-projected and arrival quantities, the average rather than the sum is calculated on the arrival grid locations. When averaging from step output to larger time intervals, the quantities are weighted with the corresponding PE at each grid point.
In addition, series files contain the same set of global attributes as described in Grid files to enable interpretation without additional documentation of the run setup.
*Immediate quantities*
| Variable | Symbol | Unit |
|:--|:--|:--|
| moisture_uptakes_boundary_layer_min | x | mm (step or 24h)^-1 |
| moisture_uptakes_boundary_layer_sum | x | mm (step or 24h)^-1 |
| moisture_uptakes_boundary_layer_max | x | mm (step or 24h)^-1 |
| moisture_uptakes_free_troposphere_min | x | mm (step or 24h)^-1 |
| moisture_uptakes_free_troposphere_sum | x | mm (step or 24h)^-1 |
| moisture_uptakes_free_troposphere_max | x | mm (step or 24h)^-1 |
| evaporation_minus_precipitation_min | x | mm (step or 24h)^-1 |
| evaporation_minus_precipitation_sum | x | mm (step or 24h)^-1 |
| evaporation_minus_precipitation_max | x | mm (step or 24h)^-1 |
| moisture_transport_min | x | mm |
| moisture_transport_sum | x | mm |
| moisture_transport_max | x | mm |
| trajectory_location_min | x | counts km^-2 |
| trajectory_location_sum | x | counts km^-2 |
| trajectory_location_max | x | counts km^-2 |
| precipitation_estimate_min | x | mm (step or 24h)^-1 |
| precipitation_estimate_sum | x | mm (step or 24h)^-1 |
| precipitation_estimate_max | x | mm (step or 24h)^-1 |
*Arrival and forward-projected quantities*
| Variable | Symbol | Unit |
|:--|:--|:--|
| source_longitude_min | x | degrees_east |
| source_longitude_avg | x | degrees_east |
| source_longitude_max | x | degrees_east |
| source_latitude_min | x | degrees_north |
| source_latitude_avg | x | degrees_north |
| source_latitude_max | x | degrees_north |
| land_fraction_min | x | fraction |
| land_fraction_avg | x | fraction |
| land_fraction_max | x | fraction |
| accounted_fraction_boundary_layer_min | x | fraction |
| accounted_fraction_boundary_layer_avg | x | fraction |
| accounted_fraction_boundary_layer_max | x | fraction |
| accounted_fraction_free_troposphere_min | x | fraction |
| accounted_fraction_free_troposphere_avg | x | fraction |
| accounted_fraction_free_troposphere_max | x | fraction |
| transport_time_min | x | hours_before_arrival |
| transport_time_avg | x | hours_before_arrival |
| transport_time_max | x | hours_before_arrival |
| source_skin_temperature_min | x | K |
| source_skin_temperature_avg | x | K |
| source_skin_temperature_max | x | K |
| transport_distance_min | x | km |
| transport_distance_avg | x | km |
| transport_distance_max | x | km |
| source_distance_min | x | km |
| source_distance_avg | x | km |
| source_distance_max | x | km |
| deuterium_excess_min | x | permil |
| deuterium_excess_avg | x | permil |
| deuterium_excess_max | x | permil |
| moisture_transport_temperature_min | x | K |
| moisture_transport_temperature_avg | x | K |
| moisture_transport_temperature_max | x | K |
| moisture_transport_pressure_min | x | hPa |
| moisture_transport_pressure_avg | x | hPa |
| moisture_transport_pressure_max | x | hPa |
| condensation_temperature_min | x | K |
| condensation_temperature_avg | x | K |
| condensation_temperature_max | x | K |
| arrival_temperature_min | x | K |
| arrival_temperature_avg | x | K |
| arrival_temperature_max | x | K |
| arrival_pressure_min | x | hPa |
| arrival_pressure_avg | x | hPa |
| arrival_pressure_max | x | hPa |
| arrival_skin_temperature_min | x | K |
| arrival_skin_temperature_avg | x | K |
| arrival_skin_temperature_max | x | K |
====Histogram files====
* Bounds freq (1 to n categories), (1 to m variables)
* Main variables time, dq, conv
* where to implement
<pre>
20.71  46.56  8.1351e+05  -1.0000e+00
21.22  45.90  1.1314e+06  -1.0000e+00
22.03  45.24  4.1929e+05  -1.0000e+00
21.19  45.35  1.0639e+06  -1.0000e+00
20.71  46.50  5.0963e+05  -1.0000e+00
21.07  47.51  2.8182e+05  -1.0000e+00
21.71  48.67  9.3088e+05  -1.0000e+00
22.14  51.47  2.3634e+05  -1.0000e+00
22.14  52.49  8.0048e+05  -1.0000e+00
22.34  53.76  7.3297e+05  -1.0000e+00
23.17  54.41  4.1516e+05  -1.0000e+00
23.56  54.54  2.7414e+05  -1.0000e+00
24.39  54.55  5.0017e+05  -1.0000e+00
26.89  54.42  2.8215e+05  -1.0000e+00
28.18  54.40  3.9987e+05  -1.0000e+00
29.80  54.25  3.6020e+05  -1.0000e+00
</pre>
====Trajectory files====
**LSL format**
* As documented elsewhere
* only some variables
* Code location
<pre>
example
</pre>
**Traj format**
* Binary format, only some variables
* Code location
* reading in and plotting traj files
<pre>
example
</pre>
====Mean file====
Legacy format, global_201002_V3_avg_steps
<pre>
20100228_00 13795.603  0.001 7994.128  0.001 722561152.000 1977998.875  -0.081  -3.124    0.007  -0.080  -1.347  0.003  0.181  0.000  0.001  0.711  0.006  0.001  0.242  0.000  0.001 -999.990 -999.990 -999.990  -83.283 -340.404    0.153  288.231  242.846    0.050 -999.990 -999.990 -999.990  2828.54    120.41      7.50
</pre>
===Annotated bibliography===
There are to date (Oct 2019) 25 publications involving the WaterSip method in one way or another. The versatility of WaterSip ranges from weather events to climatological studies, and from process understanding to paleoclimate proxy interpretation. This documentation can only provide initial guidance in applying WaterSip to new research plans. The annotated bibliography below provides an overview over the relevant studies, ordered by topic and the respective climatic zone.
| Topic | Time perspective | Climate zone | Region | Reference |
|:--|:--|
| Method description | - | High latitudes | Greenland | Sodemann et al., 2008a |
| Precipitation extremes | Climatology | Subtropics | Mediterranean | Winschall et al., 2014a |
| Method evaluation | Weather event | Subtropics | Mediterranean | Winschall et al., 2014b |
| Lifetime of precipitation | Climatology | Global | Global | Läderach and Sodemann, 2016 |
| Climate proxy interpretation | Climatology | High latitudes | Greenland | Sodemann et al., 2008b |
| Climate characteristics | Climatology | Mid latitudes | Europe | Sodemann and Zubler, 2010 |
| Climate proxy interpretation | Climatology | Tropics | Belize | Kenneth et al.,  |
| Climate proxy interpretation | Climatology | Mid latitudes | China | Baker et al., Luetscher et al.  |
===References===
* Thurnherr, I., Kozachek, A., Graf, P., Weng, Y., Bolshiyanov, D., Landwehr, S., Pfahl, S., Schmale, J., Sodemann, H., Steen-Larsen, H. C., Toffoli, A., Wernli, H., and Aemisegger, F., 2019: Meridional and vertical variations of the water vapour isotopic composition in the marine boundary layer over the Atlantic and Southern Ocean, Atmos. Chem. Phys. Discuss., doi: 10.5194/acp-2019-782.
* Fremme, A. and Sodemann, H., 2019: The role of land and ocean evaporation on the variability of precipitation in the Yangtze River valley, Hydrol. Earth Syst. Sci., 23, 2525–2540, doi: 10.5194/hess-23-2525-2019.
* Huang, R, Zhu, H, Liang, E., Grießinger, J, Wernicke, J., Yu, W., Hochreuther, P., Risi, C., Zeng, Y., Fremme, A., Sodemann, H., Bräuning, A., 2019: Temperature signals in tree-ring oxygen isotope series from the northern slope of the Himalaya, EPSL 506: 455-465.
* Buizert, Christo; Sigl, Michael; Severi, Mirko; Markle, Bradley; Wettstein, Justin; McConnell, J; Pedro, Joel; Sodemann, H.; Goto-Azuma, Kumiko; Kawamura, Kenji; Fujita, Shuji; Motoyama, Hideaki; Hirabayashi, Motohiro; Uemura, Ryu; Stenni, Barbara; Parrenin, Frederic; He, Feng; Fudge, T.J.; Steig, Eric J., 2018: Abrupt ice-age shifts in southern westerly winds and Antarctic climate forced from the north, Nature 563: 681-685.
* Bohlinger, P., Sorteberg, A., Liu, C., Rasmussen, R., Sodemann, H., Ogawa, F., 2018: Multiscale characteristics of an extreme precipitation event over Nepal. QJRMS:1-18, doi:10.1002/qj.3418.
* Bohlinger, P., Sorteberg, A., and Sodemann, H., 2017: Synoptic conditions and moisture sources actuating extreme precipitation in Nepal. Journal of Geophysical Research: Atmospheres, 122, 12,653–12,671. https://doi.org/10.1002/2017JD027543.
* Blazina, T., A. Läderach, G. D. Jones, H. Sodemann, H. Wernli, J. W. Kirchner and L. H. E. Winkel, 2016: Marine primary productivity as a potential source of selenium and other trace elements in atmospheric deposition, Environ. Sci. Technol. 2017, 51, 108−118, doi: 10.1021/acs.est.6b03063.
* Läderach, A. andSodemann, H., 2016: A revised picture of the atmospheric moisture residence time, Geophys. Res. Lett., 43, doi:10.1002/2015GL067449.
* Baker, A., Sodemann, H., Baldini, J. U. L., Breitenbach, S. F. M., Johnson, K. R., van Hunen, J., and Pingzhong, Z., 2015: Seasonality of westerly moisture transport in the East Asian Summer Monsoon and its implications for interpreting precipitation d18O, J. Geophys. Res., 120,  doi:10.1002/2014JD022919.
* Steen-Larsen, H. C., Sveinbjörnsdottir, A. E., Jonsson, T., Ritter, F., Bonne, J.-L., Masson-Delmotte, V., Sodemann, H., Blunier, T., Dahl-Jensen, D., Vinther, B. M., 2015: Moisture sources and synoptic to seasonal variability of North Atlantic water vapor isotopic composition, J. Geophys. Res., 120, 5757–5774, doi:10.1002/ 2015JD023234.
* Bonne, J.-L., Steen-Larsen, H. C., Risi, C., Werner, M., Sodemann, H., Lacour, J.-L., Fettweis, X., Cesana, G., Delmotte, M., Cattani, O., Vallelonga, P., Kjær, H. A., Clerbaux, C., Sveinbjörnsdóttir, A. E., and Masson-Delmotte, V., 2015: The summer 2012 Greenland heat wave: In situ and remote sensing observations of water vapor isotopic composition during an atmospheric river event, J. Geophys. Res., 120, 2970-2989, doi:10.1002/2014JD022602.
* Luetscher, M., Boch, R., Sodemann, H., Spoetl, C., Cheng, H., Edwards, R. L., Frisia, S., Hof, F., Mueller, W., 2015: North Atlantic storm track changes during the Last Glacial Maximum recorded by Alpine speleothems, Nature Comm. 6: 6344, doi:10.1038/ncomms7344.
* Winschall, A., Sodemann, H.,Pfahl, S. and Wernli, H., 2014: How important is intensified evaporation for Mediterranean precipitation extremes?, J. Geophys. Res., 119: 5240–5256, doi:10.1002/2013JD021175
* Winschall, A., Pfahl, S., Sodemann, H.and Wernli, H.. 2014. Comparison of Eulerian and Lagrangian moisture source diagnostics - the flood event in eastern Europe in May 2010, Atmos. Chem. Phys. 14: 6605–6619, doi:10.5194/acp-14-6605-2014.
* Aemisegger, F., Pfahl, S., Sodemann, H., Lehner, I., Seneviratne, S. I., and Wernli, H., 2014: Deuterium excess as a proxy for continental moisture recycling and plant transpiration, Atmos. Chem. Phys., 14: 4029–4054, doi:10.5194/acp-14-4029-2014.
* Bonne, J. L., Masson-Delmotte, V., Cattani, O., Delmotte, M., Risi, C., Sodemann, H., and Steen-Larsen, H. C., 2014:The isotopic composition of water vapour and precipitation in Ivittuut, southern Greenland, Atmos. Chem. Phys. 14: 4419–4439, doi:10.5194/acp-14-4419-2014.
* Wang, Y., Sodemann, H., Hou, S., Masson-Delmotte, V. Jouzel, J. and Pang, H., 2013: Snow accumulation and its moisture origin over Dome Argus, Antarctica. Clim. Dyn., 40:731-742, doi: 10.1007/s00382-012-1398-9.
* Martius, O., Sodemann, H., Joos, H., Pfahl, S., Winschall, A., Croci-Maspoli, M., Graf, M., Madonna, E., Mueller, B., Schemm, S., Sedlacek, J., Sprenger, M. and Wernli, H., 2012: The role of upper-level dynamics and surface processes for the Pakistan flood in July 2010. Quart. J. Royal Meteorol. Soc., published online, doi: 10.1002/qj.2082.
* Kennett, D. J., Breitenbach, S. F. M., Aquino, V. V., Asmerom, Y., Awe, J., Baldini, J. U. L., Bartlein, P., Culleton, B. J., Ebert, C., Jazwa, C., Macri, M. J., Marwan, N., Polyak, V., Prufer, K. M., Ridley, H. E., Sodemann, H., Winterhalder, B. and Haug, G. H., 2012: Development and Disintegration of Maya Political Systems in Response to Climate Change. Science, 338: 788-791, doi: 10.1126/science.1226299.
* Winkler, R., Landais, A., Sodemann, H., Dümbgen, L., Priéa, F., Masson-Delmotte, V., Stenni, B., and Jouzel, J., 2012: Deglaciation records of 17O-excess in East Antarctica: reliable reconstruction of oceanic relative humidity from coastal sites. Clim. Past 8, 1-16.
* Masson-Delmotte, V., Buiron, D., Ekaykin, A., Frezzotti, M., Gallée, H., Jouzel, J., Krinner, G., Landais, A., Motoyama, A., Oerter, H., Pol, K., Pollard, D., Ritz, C., Schlosser, E., Sime, L. C., Sodemann, H., Stenni, B., Uemura R., and Vimeux, F., 2011: A comparison of the present and last interglacial periods in six Antarctic ice cores Clim. Past, 7, 397-423.
* Sodemann, H.and Zubler, E., 2010: Seasonality and inter-annual variability of the moisture sources for Alpine precipitation during 1995-2002, Int. J. Climatol., 30: 947-961, doi:10.1002/joc.1932.
* Sodemann, H., and Stohl, A., 2009: Asymmetries in the moisture origin of Antarctic precipitation, Geophys. Res. Lett., 36, L22803, doi:10.1029/2009GL040242.
* Sodemann, H., Masson-Delmotte, V., Schwierz, C., Vinther, B. M. and Wernli, H., 2008: Inter-annual variability of Greenland winter precipitation sources. Part II: Effects of North Atlantic Oscillation variability on stable isotopes in precipitation, J. Geophys. Res., 113, D12111, doi:10.1029/2007JD009416.
* Sodemann, H., Schwierz, C., and Wernli, H., 2008: Inter-annual variability of Greenland winter precipitation sources. Lagrangian moisture diagnostic and North Atlantic Oscillation influence, J. Geophys. Res.,113, D03107, doi:10.1029/2007JD008503.

Revision as of 21:21, 12 October 2019

About WaterSip

WaterSip is a diagnostic software tool that identifies source, transport and arrival properties of atmospheric water vapour based on airmass backward trajectories. As a prerequisite, the backward trajectories for the analysis are to be obtained from a trajectory calculation tool, such as FLEXPART [[1]] or Lagranto [[2]]. Moisture sources are then identified from changes in specific humidity interpolated to the air parcel trajectory per time step. The changes in specific humidity at each time step are set in relation with the current humidity of the air parcel. This allows to estimate the quantitative contribution of moisture to the air parcel at a specific location, a so-called moisture accounting. WaterSip identifies and aggregates further properties of the moisture source and during the moisture transport, such as temperature, pressure, latitude etc. The moisture source diagnostic is described in detail in Sodemann et al. (2008). Publications using the WaterSip diagnostic are listed in section Bibliography.

Working principle

Explanation from Sodemann et al. 2008a

Image from Läderach and Sodemann, 2016 or Sodemann et al., 2008a

Moisture source information

- Accounted fraction fa, fb, fa+fb - adding below and above boundary layer or not, when - choosing threshold values for Arctic and other regions - identifying moisture transport

Arrival information and Lagrangian forward projections

- arrival parameters - transport parameters - source parameters - averaging by contribution and amount

Series information

- sectorization (Sodemann and Zubler, 2010; definition table, code changes) - weighted averaging: The averaging over time steps, as required by different grid files, is done by weighting each time step contribution with the corresponding precipitation estimate, and deviding by the total precipitation.

Averaged properties

- histogram example and modification (code below)

Trajectories

- plotting/reading example (code below)

Uncertainties

Example setups

Three examples with different purposes

Water vapour

- considerations and parameters

Extratropical precipitation

- considerations and parameters

High latitude precipitation

- considerations and parameters

Version history

Version 2.1

Version 2.2

Version 2.3

Version 2.4

Version 2.5

Version 2.8

Version 2.8.1

Version 2.9

Version 2.9.1

Version 2.9.2

Version 2.9.3

Version 2.9.4

Version 3.0.8

Version 3.1

The current version of WaterSip is V3.1.0.

Running the WaterSip diagnostic

It is advised to create a link to the binary file of WaterSip in your /home/$USER/bin or project directory:

mkdir ~/bin
ln -s /Data/gfi/projects/isomet/progs/WaterSip_tool/WaterSip3 ~/bin

Adding ~/bin to your path will make execution of WaterSip more comfortable. To start a diagnostic run, WaterSip needs to be called from the command line. This version reads one single input file during startup which contains all parameter settings required to execute a run (the examples below assume that you are in a working directory and WaterSip3 is at a location in your $PATH environment variable):

module load netCDF-C++
WaterSip3 <WATERSIP_parameter_file>

Note that the UiB hpc environment requires the above 'module load' command to be executed first.

On cyclone.hpc.uib.no, a run script is available that makes repeated similar runs easier to manage. Only essential parameters have to be changed, such as the target coordinates and case name. These will then be replaced on a template INPUT_WATERSIP file, and then WaterSip will be started. The script and an input file template can be copied like this:

cp /Data/gfi/projects/isomet/projects/watersip/Bergen_iso/run_watersip_template_Bergen_2018.sh .
cp /Data/gfi/projects/isomet/projects/watersip/Bergen_iso/INPUT_WATERSIP_template_Bergen_2018 .

Input file conversion from V2

The input file format, described below, is quite different in V3 than in previous versions. To facilite transition from V2.x input files, there is an option execute WaterSip3 with the option -c to convert to the new V3 input file format:

WaterSip3 -c <WATERSIP_V2_parameter_file>

This will create a new file named <WATERSIP_V2_parameter_file>V3 at the current directory. It is recommended to double check and edit the settings in the converted file before starting a simulation.

Parallelization

WaterSip3 has been parallelized with OpenMP, which can significantly speed up calculation time. The number of processors to be used is specified in the input file (see below).

If WaterSip3 is to be executed on a queue system (not applicable to cyclone.hpc.uib.no), the following wrapper script can be used to start a run using 4 cores for parallel processing:

# start with sbatch NAME_OF_THIS_FILE directly on machine

#SBATCH --job-name=WaterSip3
#SBATCH --workdir=/tmp/
#SBATCH --partition=priority
#SBATCH --output=WaterSip_job.%j.out
#SBATCH --error=WaterSip_job.%j.err
#SBATCH --mail-type=END
#SBATCH --ntasks=1
#SBATCH --cpus-per-task=4

srun ./WaterSip3 INPUT_WATERSIP_global_1993

Input file options

The WaterSip input file is a text file with options that are specified for different option groups. Option groups are identified by square brackets (e.g. [Case]). There are 7 option groups which can appear in random order in the input file:

  • Case: general settings related to the case to be extracted
  • Grids: specification of different output grids
  • Diagnostrics: parameters of the moisture diagnostic
  • Output: general output settings
  • Variables: selection of output variables
  • Flexpart: options specific to runs using FLEXPART particle output
  • Lagranto: options specific to runs using Lagranto trajectories

Parameter set Case

The settings in this parameter category describe the basic conditions of the diagnostic run.

caseName (string)
identifier for the run, prepended to all output files. Example: caseName = global_201002_relative
inputDir (string)
search path of the input files. The inputDir string ends with a placeholder for the files to be read in. For FLEXPART this will be either shortposit_ or partposit_. For Lagranto this will commonly be lsl_. The %s placeholder is completed by the currently read in date at runtime. Example: inputDir = /Volumes/Data/global/shortposit_%s
outputDir (string)
path where the output files will be created. Example: outputDir = /Volumes/Data/global/output/
startDate (date string)
inital date of the run, fixed format YYYYMMDD-HHMMSS. Start date is latest date of the run which moves backward in time. Example: startDate = 20100228-180000
endDate (date string)
final date of the run, fixed format YYYYMMDD-HHMMSS. End date is earliest date of the run. Example: endDate = 20100211-000000
timeStep (integer)
time step in hours between particles or trajectory output times. (typical values 6, 3, or 1 (hours)). Example: timeStep = 6
trajPoints (integer)
number of trajectory points to be considered in a trajectory. For 5-day trajectories with a 6 hour time step, 5x4+1=21 trajPoints should be selected. Example: trajPoints = 21
minTrajPoints (integer)
minimum length of trajectories to be included in analysis. Parameter is only relevant for Lagranto simulations with uneven trajectory length. Example: minTrajPoints = 0
sectorizeRegion (integer)
region set used to divide moisture sources into different sectors (see #sectorization). Example: sectorizeRegion = 0
filterBoxFile (string)
path to the text file describing geographic boxes used to filter air parcels during transport (see #box filters). Example: filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste
filterIndex (integer)
used line from the filterBoxFile to select/deselect trajectories. Example: filterIndex = -1
orographyFile (string)
path to the orography file used to select arrival based on underying topography, using the ETOPO2 topography. File in netcdf format. Example: orographyFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/etopo5.nc"
lsmFile (string)
path to the file with global land-sea-mask, currently from ERA-Interim data. Domain must be global but is in principle arbitrary. File in netcdf format. Example: lsmFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/ERA_sea_mask_inv.nc"
maskFile (string)
path to file with an arrival selection. Example: maskFile = " "
useMask (boolean)
use mask file (0=no, 1=yes). Example: useMask = 0
ompThreads (integer)
number of threads to be used with OpenMP parallelisation if compiled with flag -fopenmp (1=no parallelisation, >1 parallelisation activated.). Example: ompThreads = 1
showStats (boolean)
print statistics about particle processing to the command line (0=off, 1=on). Example: showStats = 0

Parameter set Grids

The parameters in this category specify the different output grids and the gridding method

arrivalGridMinLon (float)
minimum longitude of arrival (target region) grid box. Trajectories are traced backward from the arrival grid. Integrated source, transport and arrival parameters are put on the arrival grid, weighted by precipitation or water vapour of arriving air parcels. Example: arrivalGridMinLon = -180
arrivalGridMaxLon (float)
maximum longitude of arrival (target region) grid box. Example: arrivalgridmaxlon = 180
arrivalGridMinLat (float)
minimum latitude of arrival (target region) grid box. Example: arrivalGridMinLat = -90
arrivalGridMaxLat (float)
minimum latitude of arrival (target region) grid box. Example: arrivalGridMaxLat = 90
arrivalGridDx (float)
longitude increment of arrival (target region) grid. Example: arrivalGridDx = 1
arrivalGridDy (float)
latitude increment of arrival (target region) grid. Example: arrivalGridDy = 1
arrivalGridRadius (float)
gridding radius for information from arriving trajectories. Example: arrivalGridRadius = 200
sourceGridMinLon (float)
minimum longitude of moisture source grid box. Example: sourceGridMinLon = -180
sourceGridMaxLon (float)
maximum longitude of moisture source grid box. Example: sourceGridMaxLon = 180
sourceGridMinLat (float)
minimum latitude of moisture source grid box. Example: sourceGridMinLat = -90
sourceGridMaxLat (float)
maximum latitude of moisture source grid box. Example: sourceGridMaxLat = 90
sourceGridDx (float)
longitude increment of moisture source grid box. Example: sourceGridDx = 1
sourceGridDy (float)
latitude increment of moisture source grid box. Example: sourceGridDy = 1
sourceGridRadius (float)
longitude increment of moisture source grid box. Example: sourceGridRadius = 200
griddingType (integer)
select #gridding algorithm (1: fast and simple gridding, 2: improved but slower gridding). Example: griddingType = 2

Parameter set Diagnostics

The parameters in this category control the way how the diagnostic works, and which trajectories should be considered in the run.

uptakeThreshold (float)
Threshold value for specific humidity increases per time step in air parcels to be considered as due to physical processes (evaporation), in g per kg. If the parameter reativeThresholds is set to true, the uptakeThreshold is specified as percent increase relative to the current specific humidity of an air parcel. Value is positive because of an air-parcel relative perspective. Default absolute values are 0.1 to 0.2 for 3h and 6h time steps. Example: uptakeThreshold = 0.2
precipThreshold (float)
Threshold value for specific humidity decreases per time step in air parcels to be considered as due to physical processes (precipitation), in g per kg. Value is negative because of an air-parcel relative perspective. If the parameter reativeThresholds is set to true, the precipThreshold is specified as percent decrease relative to the current specific humidity of an air parcel. Then the value is negative. Default absolute values are -0.1 to -0.2 for 3h and 6h time steps. Example: precipThreshold = -0.2
relativeThreshold (boolean)
determines whether absolute threshold values or relative threshold values are specified (0: absolute, 1: relative threshold values). Example: relativeThreshold = 1
arrivalPrecipMin (float)
Threshold value to consider precipitation events with a specific humidity decrease larger than the value given by arrivalPrecipMin. Units are g per kg when relativeThresholds is set to false, and fractional specific humidity decrease otherwise. For consistency, it is recommended to set the values for precipitationThreshold and arrivalPrecipMin to the same number. Example: arrivalPrecipMin = -0.2
arrivalPrecipMax (float)
Threshold value to consider precipitation events with a specific humidity decrease of up to the value given by arrivalprecipMin. Units are g per kg when relativeThresholds is set to false, and fractional specific humidity decrease otherwise. To include all precipitation events with a 6h time step, a value of -100.0 or lower can be chosen if relativeThresholds is set to false, or a value of 1.0 otherwise. The combination of the arrivalPrecipMin/Max parameters allows to focus on heavy and weak precipitation events only. Example: arrivalPrecipMax = -100.0
arrivalRHMin (float)
Threshold value to consider precipitation events when relative humidity at the arrival location is larger than the value given by . Example: arrivalRHMin. Units are %. Large-scale condensation can be assumed to occur above 80% relative humidity, to include convective cloud processes a lower threshold value may be required. Example: arrivalRHMin = 80
arrivalRHMax (float)
Threshold value to consider precipitation events when relative humidity at the arrival location is less than the value given by . Example: arrivalRHMax. Units are %. This parameter in combination with arrivalRHMin can be used to focus on condensation/no condensation cases when the parameter analyzeVapour is set to true. Example: arrivalRHMax = 110
arrivalOroMin (float)
Threshold value to consider only arrival locations where the ETOPO2 topography exceeds the given value (in m). Use negative value to include all global locations, including ocean areas, Bangladesh and Death Valley. Example: arrivalOroMin = -100
arrivalOroMax (float)
Threshold value to consider only arrival locations where the ETOPO2 topography does not exceed the given value (in m). In combination with . Example: arrivalOroMin, regions with a complex shape but common elevation can be selected easily. Example: arrivalOroMax = 12000
arrivalAltMin (float)
Threshold value to consider only arrival locations where the air parcels are above at the given altitude (in m above sea level). Example: arrivalAltMin = -100
arrivalAltMax (float)
Threshold value to consider only arrival locations where the air parcels are below the given altitude (in m above sea level). The parameters arrivalAltMin/Max can be used to conduct vertically stratified analyses.Example: arrivalAltMax = 12000
blhScale (float)
Scaling factor to decide for air parcels to be close enough to the boundary layer to consider moisture increases to evaporation to be likely due to surface evaporation below. A factor of 1.5 will assign all moisture increases within 1.5x the current boundary layer height to the category 'moisture sources boundary-layer', all others to the category 'moisture sources free troposphere'. Default value is 1.5. Example: blhScale = 1.5
analyzeVapour (boolean)
Parameter allowing to consider all air parcels that precipitate according to the . Example: precipitationThreshold and arrivalRHMin/Max parameters (0: false), or all parameters irrespective of arrival precipitation (1: true). If set to false, the weighting of source, transport and arrival properties is done using the precipitation estimate calculated from the specific humidity change during arrival. Otherwise, the weight is provided by the arrival specific humidity. When analyzeVapour is set to true, many more particles are considered, and the arrivalRHMin/Max parameters may need adjustment. Example: analyzeVapour = 0
assignToUptake (boolean)
Parameter determining the assignment of moisture uptake events to arrival time (0: disabled) or to uptake time step grid (1: enabled). The effect of this parameter will most clearly be visible on stepwise and daily output files. It can be used to relate evaporation events to the concurrent meteorological situation. Example: assignToUptake = 0
forwardProjectionMode (integer)
Parameter determining how the Lagrangian forward projection of #moisture source and moisture transport properties are calculated (1: only consider boundary-layer moisture uptakes, 2: only consider free-troposphere uptakes, 3: consider both uptakes in combination). The default value is 3 (both, boundary layer and free-troposphere uptakes). Example: forwardProjectionMode = 3

Parameter set Output

The parameters in this category determine which output files should be created.

stepFile (boolean)
write parameters on #Grid files and #Series files for each time step. Example: stepFile = 1
dayFile (boolean)
write parameters on grid and series files averaged/accumulated for each day. Example: dayFile = 1
monthFile (boolean)
write parameters on grid and series files averaged/accumulated for each month. Example: monthFile = 1
yearFile (boolean)
write parameters on grid and series files averaged/accumulated for each year. Example: yearFile = 1
allFile (boolean)
write parameters on grid and series files averaged/accumulated for all time steps. Example: allFile = 1
staticFields (boolean)
write static fields (land-sea mask and topography) onto grid files. Example: staticFields = 1
saveTraj (integer)
write particle trajectories to #Trajectory files at each time step (1) or each month (2). Option 0 disables trajectory output. Example: saveTraj = 0
skipTraj (boolean)
write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: skipTraj = 1
saveHistogram (boolean)
write histogram for selected parameters to a #Histogram files (0: disabled, 1:enabled). Example: saveHistogram = 0
saveMean (boolean)
write means, minimum, maximum and standard deviation to #Mean file. This is duplicate information with the series files but available for historical reasons. The option will be removed in a forthcoming version (0: disabled, 1:enabled). Example: saveMean = 0

Parameter set Variables

The parameters in this category allow to include or exclude specific variables from the output files. Setting the output for unused variables to 0 (disabled) will speed up computation time, reduce the memory footprint, and reduce the output file size. Only parameters that are really required from a run should therefore selected as enabled.

sourcesBoundaryLayer (boolean)
write accounted moisture uptakes in the boundary layer to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: sourcesBoundaryLayer = 1
sourcesFreeTroposphere (boolean)
write accounted moisture uptakes in the free troposphere to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: sourcesFreeTroposphere = 1
evaporationMinusPrecipitation (boolean)
write unweighted evaporation minus precipitation along entire trajectory length to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: evaporationMinusPrecipitation = 1
moistureTransport (boolean)
write weighted moisture transport along trajectories to grid and series output files (0: disabled, 1: enabled). Units are mm. Example: moistureTransport = 1
trajectoryLocations (boolean)
write trajectory locations to grid and series output files (0: disabled, 1: enabled). Units are counts per km2. Example: trajectoryLocations = 1
precipitationEstimate (boolean)
write precipitation estimate at arrival to grid and series output files (0: disabled, 1: enabled). Units are mm per time step for step files, and mm per day on all other files. Example: precipitationEstimate = 1
sourceLongitude (boolean)
write weighted moisture source longitude projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are degrees longitude. Example: sourceLongitude = 1
sourceLatitude (boolean)
write moisture source latitude projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are degrees latitude. Example: sourceLatitude = 1
convectionCount (boolean)
write convection count projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are counts per km2. Convection count can be written to the FLEXPART particle files with a special version of FLEXPART_WATER. convectionCount is not on the ERA-Interim climatology run. The counter is increased each time the particles passes the convection scheme upwards. Example: convectionCount = 0
convectionHeight (boolean)
write convection height projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Convection height can be written to the FLEXPART particle files with a special version of FLEXPART_WATER. convectionHeight is not on the ERA-Interim climatology run. The value gives an average height of vertical displacement when the particles passes the convection scheme. Example: convectionHeight = 0
landFraction (boolean)
write fraction of moisture sources over land projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: landFraction = 1
boundaryLayerFraction (boolean)
write accounted fraction of boundary layer uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: boundaryLayerFraction = 1
freeTroposphereFraction (boolean)
write accounted fraction of free troposphere uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Example: freeTroposphereFraction = 1
combinedFraction (boolean)
write accounted fraction of boundary layer and free troposphere uptakes projected to the arrival region to grid and series output files (0: disabled, 1: enabled). This is the sum of the two previous variables. Example: combinedFraction = 0
transportTime (boolean)
write moisture transport time projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are hours. Example: transportTime = 1
sourceSkinTemperature (boolean)
write skin temperature at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that skin temperature is a variable on the particle or trajectory files. Example: sourceSkinTemperature = 1
sourceSpecificHumidity (boolean)
write surface specific humidity at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are g per kg. Requires that source specific humidity is a variable on the particle or trajectory files. Example: sourceSpecificHumidity = 0
transportDistance (boolean)
write transport distance projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Transport distance is the length of the actual travel path along the trajectories from moisture source to the arrival region. Example: transportDistance = 1
sourceDistance (boolean)
write source distance projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are km. Source distance is the shortest distance between the moisture source and the arrival region. Example: sourceDistance = 1
source2mTemperature (boolean)
write 2m temperature at the moisture source projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Example: source2mTemperature = 0
sourceDeuteriumExcess (boolean)
write deuterium excess projected to the arrival region to grid and series output files (0: disabled, 1: enabled). Units are permil. Deuterium excess is calculated from the relative humidity with respect to SST and the relationship from Pfahl and Sodemann (2014). Requires that source specific humidity is a variable on the particle or trajectory files. Example: sourceDeuteriumExcess = 1
transportTemperature (boolean)
write moisture-weighted temperature during transport projected to arrival region to grid and series output files (0: disabled, 1: enabled). Units are K. Example: transportTemperature = 1
transportPressure (boolean)
write moisture-weighted pressure during transport projected to arrival region to grid and series output files (0: disabled, 1: enabled). Units are hPa. Example: transportPressure = 1
condensationTemperature (boolean)
write moisture-weighted temperatures where RHliquid exceeds 80% to grid and series output files (0: disabled, 1: enabled). Units are K. Example: condensationTemperature = 1
arrivalTemperature (boolean)
write temperature during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Example: arrivalTemperature = 1
arrivalPressure (boolean)
write pressure during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are hPa. Example: arrivalPressure = 1
arrival2mTemperature (boolean)
write temperature at 2m during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that 2m temperature is a variable on the particle or trajectory files. Example: arrival2mTemperature = 0
arrivalSkinTemperature (boolean)
write skin temperature during moisture arrival to grid and series output files (0: disabled, 1: enabled). Units are K. Requires that skin temperature is a variable on the particle or trajectory files. Example: arrivalSkinTemperature = 1

Parameter set Flexpart

The parameters in this category describe the properties specific to FLEXPART input files.

inputFormat (integer)
file format of FLEXPART particle position output files. 0: regional long output format, 1: global analysis data output format, 2: regional short format, 3: global reanalysis/NorESM data short format, 4: global reanalysis data long format, 5 regional reanalysis/NorESM data short format. Example: inputFormat = 3
maxPart (integer)
number of particles contained in a single FLEXPART partposit or shortposit file. Example: maxPart = 5000000
partMass (float)
atmospheric mass represented by each particle in kilogramms. Parameter is written out by specific version of FLEXPART to create WaterSip output data. Example: partMass = 1.01943e+12
partStride (integer)
number of particles to skip during processing to speed up calculations (1: use every particle, >=2: use every 2nd particle, etc). Example: partStride = 10
allowReenter (boolean)
needs to be enabled for global simulations, and disabled for regional domain-filling runs to avoid double accounting of air parcels (0: disabled, 1: enabled). Example: allowReenter = 1

Parameter set Lagranto

The parameters in this category describe the properties specific to FLEXPART input files.


Full example for a FLEXPART run input file:

[Case]
caseName = global_201002_final_relativex
inputDir = /home/data/flexpart/global/shortposit_%s
outputDir=/home/data/watersip/global_201002_V3/
startDate = 20100228-180000
endDate = 20100211-000000
timeStep = 6
sectorizeRegion = 0
filterBoxFile = /home/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste
filterIndex = -1
orographyFile = "/home/projects/WaterSip_tool/etopo5.nc"
lsmFile = "/home/projects/WaterSip_tool/ERA_sea_mask_inv.nc"
maskFile = " "
useMask = 0
trajPoints = 41
minTrajPoints = 0
ompThreads = 1
showStats = 0

[Grids]
arrivalGridMinLon = -180
arrivalGridMaxLon = 180
arrivalGridMinLat = -90
arrivalGridMaxLat = 90
arrivalGridDx = 1
arrivalGridDy = 1
arrivalGridRadius = 200
sourceGridMinLon = -180
sourceGridMaxLon = 180
sourceGridMinLat = -90
sourceGridMaxLat = 90
sourceGridDx = 1
sourceGridDy = 1
sourceGridRadius = 200
griddingType = 2

[Diagnostics]
uptakeThreshold = 0.05
precipThreshold = 0.05
blhScale = 1.5
arrivalPrecipMin = 0.05
arrivalPrecipMax = 1.0
arrivalRHMin = 80
arrivalRHMax = 110
arrivalOroMin = -100
arrivalOroMax = 12000
arrivalAltMin = -100
arrivalAltMax = 12000
analyzeVapour = 0
assignToUptake = 0
forwardProjectionMode = 3
relativeThreshold = 1

[Output]
stepFile = 1
dayFile = 1
monthFile = 1
yearFile = 1
allFile = 1
staticFields = 1
saveTraj = 0
skipTraj = 0
saveHistogram = 0
saveMean = 0

[Variables]
sourcesBoundaryLayer = 1
sourcesFreeTroposphere = 1
evaporationMinusPrecipitation = 1
moistureTransport = 1
trajectoryLocations = 1
precipitationEstimate = 1
sourceLongitude = 1
sourceLatitude = 1
convectionCount = 0
convectionHeight = 0
landFraction = 1
boundaryLayerFraction = 1
freeTroposphereFraction = 1
combinedFraction = 0
transportTime = 1
sourceSkinTemperature = 1
sourceSpecificHumidity = 0
transportDistance = 1
sourceDistance = 1
source2mTemperature = 0
sourceDeuteriumExcess = 1
transportTemperature = 1
transportPressure = 1
condensationTemperature = 1
arrivalTemperature = 1
arrivalPressure = 1
arrival2mTemperature = 0
arrivalSkinTemperature = 1

[Flexpart]
inputFormat = 3
maxPart = 5000000
partMass = 1.01943e+12
partStride = 10
allowReenter = 1

Output file formats

The results from the WaterSip diagnostic are written to a set of output files in different format. The main output files are created in netCDF with detailed metadata information, including the parameter settings of the run for automated documentation. The creation of different output files can be adapted by parameter settings in parameter set *Output* and the contained variables with settings in parameter set *Variables*. Spatial fields at different time intervals are written to so-called grid files in netCDF format, time series of averaged quantities at different time intervals are written to so-called Series files in netCDF format, histograms of selected quantities identified during the processing for each time step and each trajectory are written to Histogram files in ASCII format, and trajectories are written to Trajectory files in either the binary format traj or the Lagranto ASCII format. Earlier versions than V3 reported output in so-called Mean files in an ASCII format. That format is documented here but no longer in use in current versions of WaterSip.

The time unit has changed in Version 3.1. Previously, the unit was set to "days since 0000-01-02 00:00:00" to allow matlab-compatible values for time that could directly be utilized with the datenum() commands. In order to confirm to netCDF-CF standards, where no calendar year 0000 exists, the time unit is now "days since 0001-01-01 00:00:00". This provides the ability to open and visualize netCDF output files directly with tools such as ncview and panoply. To convert the time values into a matlab datenum compatible value, the following commands have to be used:

ncid=netcdf.open(filename,"noclobber");
tim=(float)netcdf.getVar(ncid,"time");
tim=tim-datenum(1,0,1);
datestr(tim)

The table below summarizes the available output files:

Name Content Format Filename
Grid files Spatial properties of moisture sources and arrival regios netCDF CASE_grd_all/year/month/day/step.nc
Series files Mean/min/max/std of regionally and globally averaged moisture source and arrival region properties netCDF CASE_ser_all/year/month/day/step.nc
Histogram files Histograms of quantities identified for each timestep along each trajectory ASCII CASE_hst_steps
Trajectory files Trajectories for identified precipitation events ASCII/binary traj CASE_DATE.traj/CASE_DATE_lsl

Grid files

Grid file variables are separated into immediate source and transport variables, typically on a coarser, global grid, and arrival and forward-projected variables on the (typically finer-scale) arrival grid. The grid settings are determined by the corresponding parameters in parameter set *Grid*. All variables are of type float, and the fill value (netCDF property _FillValue) is -999.99. The averaging over time steps, as required by different grid files, is done by weighting each time step contribution with the corresponding precipitation estimate, and dividing by the total precipitation (as described above).

    • Moisture source and transport properties**

Variables related to immediate moisture source and transport properties (not forward projected) have dimension of variables time, global_latitude, global_longitude, as defined by input file parameters *sourceGridMinLon,sourceGridMaxLon, sourceGridMinLat, sourceGridMaxLat, sourceGridDx, sourceGridDy, sourceGridRadius*.

| Name | Symbol | Units | Description | |:--|:--|:--|:--| | moisture_uptakes_boundary_layer | E_s^BL | mm (step)h^-1 or mm 24h^-1 | text | | moisture_uptakes_free_troposphere | E_s^FT | mm (step)h^-1 or mm 24h^-1 | text | | evaporation_minus_precipitation | E-P | mm (step)h^-1 or mm 24h^-1 | text | | moisture_transport | Q_t | mm | text | | trajectory_location | N_t | counts km^-2 | text |

    • Arrival properties and Lagrangian forward projections**

The variables contained in these files have the dimensions time (days since 0001-01-01 00:00:00), latitude (degrees_north), and longitude (degrees_east) as defined by input file parameters *arrivalGridMinLon, arrivalGridMaxLon, arrivalGridMinLat, arrivalGridMaxLat, arrivalGridDx, arrivalGridDy, arrival | source | text |GridRadius*.

| Name | Symbol | Unit | Property | Description | |:--|:--|:--|:--|:--| | precipitation_estimate | PE | mm day^-1 or mm step^-1 | arrival | precipitation at arrival location estimated from change in specific humidity during last time step | | arrival_temperature | T_a | K | arrival | PE-weighted temperature at trajectory location and elevation during arrival | | arrival_pressure | p_a | hPa | arrival | PE-weighted pressure at trajectory location and elevation during arrival | | arrival_skin_temperature | SKT_a | K | arrival | PE-weighted SKT below trajectory location during arrival | | accounted_fraction_boundary_layer | f_BL | fraction | arrival | fractional contribution of BL moisture sources to PE | | accounted_fraction_free_troposphere | f_FT | fraction | arrival | fractional contribution of FT moisture sources to PE | | precipitation_lifetime | \tau_t | h | transport | contribution and precipitation-weighted precipitation life time | | transport_distance | \Delta_t | km | transport | contribution and precipitation-weighted transport distance along trajectory | | moisture_transport_temperature | T_t | K | transport | contribution and precipitation-weighted temperature during moisture transport | | moisture_transport_pressure | p_t | hPa | transport | contribution and precipitation-weighted pressure during moisture transport | | condensation_temperature | T_c | K | transport | contribution and precipitation-weighted temperature when RH>80% during transport | | source_longitude | \lambda_s | degrees_east | source | contribution and precipitation-weighted latitude of the moisture source | | source_latitude | \phi_s | degrees_north | source | contribution and precipitation-weighted longitude of the moisture source | | land_fraction | f_l | fraction | source | contribution and precipitation-weighted fraction of moisture sources over land | | source_skin_temperature | SKT_s | K | source | contribution and precipitation-weighted SKT at the moisture source | | source_distance | \Delta_s | km | source | contribution and precipitation-weighted direct distance between the moisture source and arrival location | | deuterium_excess | d_s | permil | source | contribution and precipitation-weighted estimate of deuterium excess at the source from RH and T using the Pfahl and Sodemann (2013) relation |

    • Global attributes**

The netCDF grid files contain a range of essential parameters as global attributes. These parameters allow to fully characterise the result of the WaterSip run as required for the interpretation of the results. A number of run parameters are omitted, that concern logistical settings, or that are self-evident from the content of the the output files. The table below gives an example for a WaterSip run:

| Parameter | Example | Type | |:--|:--|:--| | startDate | "2010-02-28 00:00:00 +0000"| string | | endingDate | "2010-01-11 00:00:00 +0000"| string | | analysisRegion | "NEEM"| string | | maxPart | 5000001 | int | | caseName | "global_201002_V3_stride"| string | | trajPoints | 61 | int | | timeStep | 6 | in float | | partMass | 2.03885996E12 | float | | dryLevel | 0.01 | float | | blhScale | 1.5 | float | | rhMin | 80.0 | float | | rhMax | 110.0 | float | | uptakeThreshold | 0.2 | float | | precipThreshold | -0.2 | float | | arrPrecipMin | -0.2 | float | | arrPrecipMax | -120.0 | float | | arrOroMin | 0.0 | float | | arrOroMax | 9000.0 | float | | arrAltMin | 0.0 | float | | arrAltMax | 9000.0 | float | | anaVapour | 0 | int | | filterIndex | -1 | int |

Series files

The netCDF series files contain two sets of information. The so-called sectorization output provides time series of the moisture source information seperated into relative contributions from predefined geographical areas. Furthermore, the series files contains weighted averages and further statistical properties of all quantities in the grid files.

    • Sectorisation output**

A set of sectorisations is chosen by the parameter *sectorizeRegion*. The currently available options are listed in the table below. New sectorisations can be defined by changing the code in routine Sectors.cpp/Sectors.h. This requires defining a new name and new decision tree that provides a unique number for any lat/lon value between -180E to 180E and -90 to 90N. See comments in the code.

For each of the predefined areas, the relative contributions are subdivided into land and sea covered areas. Time series of the contributions are of dimension time and sector. Thereby, the sector numbers correspond to the sector numbers defined in the program code. The area of the sectors is calculated automatically within WaterSip. As noted above for the grid files, the time unit has been changed starting from Version 3.1.

| Variable | Symbol | Unit | Description | |:--|:--|:--|:--| | time | t | days since 0001-01-01 00:00:00 | | sector | s | sector number | | sector_area | A_s | km^2 | | land_fraction_moisture_uptakes_boundary_layer | f_l^BL | percent | | sea_fraction_moisture_uptakes_boundary_layer | f_s^BL | percent | | land_fraction_moisture_uptakes_free_troposphere | f_l^FT | percent | | sea_fraction_moisture_uptakes_free_troposphere | f_s^FT | percent | | land_fraction_trajectory_location | f_l^N | percent | | sea_fraction_trajectory_location | f_s^N | percent | | land_fraction_moisture_transport | f_l^Q | percent | | sea_fraction_moisture_transport | f_s^Q | percent | | land_fraction_evaporation_minus_precipitation | f_l^EP | percent | | sea_fraction_evaporation_minus_precipitation | f_s^EP | percent |

    • Time-series output**

For immediate quantities, a time series of the total field sum is recorded in the series file. In order to obtain an area average, one needs to divide the sum by the surface of the earth (x km^2). The unit for moisture uptakes, E-P and precipitation estimate is mm step^-1 for step series files, and mm 24h^-1 for all other averaging series files. In addition to sums, the files contain time series of the minimum, maximum and standard deviation of the grid field at each time instance. For all forward-projected and arrival quantities, the average rather than the sum is calculated on the arrival grid locations. When averaging from step output to larger time intervals, the quantities are weighted with the corresponding PE at each grid point.

In addition, series files contain the same set of global attributes as described in Grid files to enable interpretation without additional documentation of the run setup.

  • Immediate quantities*

| Variable | Symbol | Unit | |:--|:--|:--| | moisture_uptakes_boundary_layer_min | x | mm (step or 24h)^-1 | | moisture_uptakes_boundary_layer_sum | x | mm (step or 24h)^-1 | | moisture_uptakes_boundary_layer_max | x | mm (step or 24h)^-1 | | moisture_uptakes_free_troposphere_min | x | mm (step or 24h)^-1 | | moisture_uptakes_free_troposphere_sum | x | mm (step or 24h)^-1 | | moisture_uptakes_free_troposphere_max | x | mm (step or 24h)^-1 | | evaporation_minus_precipitation_min | x | mm (step or 24h)^-1 | | evaporation_minus_precipitation_sum | x | mm (step or 24h)^-1 | | evaporation_minus_precipitation_max | x | mm (step or 24h)^-1 | | moisture_transport_min | x | mm | | moisture_transport_sum | x | mm | | moisture_transport_max | x | mm | | trajectory_location_min | x | counts km^-2 | | trajectory_location_sum | x | counts km^-2 | | trajectory_location_max | x | counts km^-2 | | precipitation_estimate_min | x | mm (step or 24h)^-1 | | precipitation_estimate_sum | x | mm (step or 24h)^-1 | | precipitation_estimate_max | x | mm (step or 24h)^-1 |

  • Arrival and forward-projected quantities*

| Variable | Symbol | Unit | |:--|:--|:--| | source_longitude_min | x | degrees_east | | source_longitude_avg | x | degrees_east | | source_longitude_max | x | degrees_east | | source_latitude_min | x | degrees_north | | source_latitude_avg | x | degrees_north | | source_latitude_max | x | degrees_north | | land_fraction_min | x | fraction | | land_fraction_avg | x | fraction | | land_fraction_max | x | fraction | | accounted_fraction_boundary_layer_min | x | fraction | | accounted_fraction_boundary_layer_avg | x | fraction | | accounted_fraction_boundary_layer_max | x | fraction | | accounted_fraction_free_troposphere_min | x | fraction | | accounted_fraction_free_troposphere_avg | x | fraction | | accounted_fraction_free_troposphere_max | x | fraction | | transport_time_min | x | hours_before_arrival | | transport_time_avg | x | hours_before_arrival | | transport_time_max | x | hours_before_arrival | | source_skin_temperature_min | x | K | | source_skin_temperature_avg | x | K | | source_skin_temperature_max | x | K | | transport_distance_min | x | km | | transport_distance_avg | x | km | | transport_distance_max | x | km | | source_distance_min | x | km | | source_distance_avg | x | km | | source_distance_max | x | km | | deuterium_excess_min | x | permil | | deuterium_excess_avg | x | permil | | deuterium_excess_max | x | permil | | moisture_transport_temperature_min | x | K | | moisture_transport_temperature_avg | x | K | | moisture_transport_temperature_max | x | K | | moisture_transport_pressure_min | x | hPa | | moisture_transport_pressure_avg | x | hPa | | moisture_transport_pressure_max | x | hPa | | condensation_temperature_min | x | K | | condensation_temperature_avg | x | K | | condensation_temperature_max | x | K | | arrival_temperature_min | x | K | | arrival_temperature_avg | x | K | | arrival_temperature_max | x | K | | arrival_pressure_min | x | hPa | | arrival_pressure_avg | x | hPa | | arrival_pressure_max | x | hPa | | arrival_skin_temperature_min | x | K | | arrival_skin_temperature_avg | x | K | | arrival_skin_temperature_max | x | K |

Histogram files

  • Bounds freq (1 to n categories), (1 to m variables)
  • Main variables time, dq, conv
  • where to implement
20.71   46.56   8.1351e+05  -1.0000e+00
21.22   45.90   1.1314e+06  -1.0000e+00
22.03   45.24   4.1929e+05  -1.0000e+00
21.19   45.35   1.0639e+06  -1.0000e+00
20.71   46.50   5.0963e+05  -1.0000e+00
21.07   47.51   2.8182e+05  -1.0000e+00
21.71   48.67   9.3088e+05  -1.0000e+00
22.14   51.47   2.3634e+05  -1.0000e+00
22.14   52.49   8.0048e+05  -1.0000e+00
22.34   53.76   7.3297e+05  -1.0000e+00
23.17   54.41   4.1516e+05  -1.0000e+00
23.56   54.54   2.7414e+05  -1.0000e+00
24.39   54.55   5.0017e+05  -1.0000e+00
26.89   54.42   2.8215e+05  -1.0000e+00
28.18   54.40   3.9987e+05  -1.0000e+00
29.80   54.25   3.6020e+05  -1.0000e+00

Trajectory files

    • LSL format**
  • As documented elsewhere
  • only some variables
  • Code location
example
    • Traj format**
  • Binary format, only some variables
  • Code location
  • reading in and plotting traj files
example

Mean file

Legacy format, global_201002_V3_avg_steps

20100228_00 13795.603  0.001 7994.128  0.001 722561152.000 1977998.875   -0.081   -3.124    0.007  -0.080  -1.347   0.003   0.181   0.000   0.001   0.711   0.006   0.001   0.242   0.000   0.001 -999.990 -999.990 -999.990  -83.283 -340.404    0.153  288.231  242.846    0.050 -999.990 -999.990 -999.990   2828.54    120.41      7.50

Annotated bibliography

There are to date (Oct 2019) 25 publications involving the WaterSip method in one way or another. The versatility of WaterSip ranges from weather events to climatological studies, and from process understanding to paleoclimate proxy interpretation. This documentation can only provide initial guidance in applying WaterSip to new research plans. The annotated bibliography below provides an overview over the relevant studies, ordered by topic and the respective climatic zone.

| Topic | Time perspective | Climate zone | Region | Reference | |:--|:--| | Method description | - | High latitudes | Greenland | Sodemann et al., 2008a | | Precipitation extremes | Climatology | Subtropics | Mediterranean | Winschall et al., 2014a | | Method evaluation | Weather event | Subtropics | Mediterranean | Winschall et al., 2014b | | Lifetime of precipitation | Climatology | Global | Global | Läderach and Sodemann, 2016 | | Climate proxy interpretation | Climatology | High latitudes | Greenland | Sodemann et al., 2008b | | Climate characteristics | Climatology | Mid latitudes | Europe | Sodemann and Zubler, 2010 | | Climate proxy interpretation | Climatology | Tropics | Belize | Kenneth et al., | | Climate proxy interpretation | Climatology | Mid latitudes | China | Baker et al., Luetscher et al. |

References

  • Thurnherr, I., Kozachek, A., Graf, P., Weng, Y., Bolshiyanov, D., Landwehr, S., Pfahl, S., Schmale, J., Sodemann, H., Steen-Larsen, H. C., Toffoli, A., Wernli, H., and Aemisegger, F., 2019: Meridional and vertical variations of the water vapour isotopic composition in the marine boundary layer over the Atlantic and Southern Ocean, Atmos. Chem. Phys. Discuss., doi: 10.5194/acp-2019-782.
  • Fremme, A. and Sodemann, H., 2019: The role of land and ocean evaporation on the variability of precipitation in the Yangtze River valley, Hydrol. Earth Syst. Sci., 23, 2525–2540, doi: 10.5194/hess-23-2525-2019.
  • Huang, R, Zhu, H, Liang, E., Grießinger, J, Wernicke, J., Yu, W., Hochreuther, P., Risi, C., Zeng, Y., Fremme, A., Sodemann, H., Bräuning, A., 2019: Temperature signals in tree-ring oxygen isotope series from the northern slope of the Himalaya, EPSL 506: 455-465.
  • Buizert, Christo; Sigl, Michael; Severi, Mirko; Markle, Bradley; Wettstein, Justin; McConnell, J; Pedro, Joel; Sodemann, H.; Goto-Azuma, Kumiko; Kawamura, Kenji; Fujita, Shuji; Motoyama, Hideaki; Hirabayashi, Motohiro; Uemura, Ryu; Stenni, Barbara; Parrenin, Frederic; He, Feng; Fudge, T.J.; Steig, Eric J., 2018: Abrupt ice-age shifts in southern westerly winds and Antarctic climate forced from the north, Nature 563: 681-685.
  • Bohlinger, P., Sorteberg, A., Liu, C., Rasmussen, R., Sodemann, H., Ogawa, F., 2018: Multiscale characteristics of an extreme precipitation event over Nepal. QJRMS:1-18, doi:10.1002/qj.3418.
  • Bohlinger, P., Sorteberg, A., and Sodemann, H., 2017: Synoptic conditions and moisture sources actuating extreme precipitation in Nepal. Journal of Geophysical Research: Atmospheres, 122, 12,653–12,671. https://doi.org/10.1002/2017JD027543.
  • Blazina, T., A. Läderach, G. D. Jones, H. Sodemann, H. Wernli, J. W. Kirchner and L. H. E. Winkel, 2016: Marine primary productivity as a potential source of selenium and other trace elements in atmospheric deposition, Environ. Sci. Technol. 2017, 51, 108−118, doi: 10.1021/acs.est.6b03063.
  • Läderach, A. andSodemann, H., 2016: A revised picture of the atmospheric moisture residence time, Geophys. Res. Lett., 43, doi:10.1002/2015GL067449.
  • Baker, A., Sodemann, H., Baldini, J. U. L., Breitenbach, S. F. M., Johnson, K. R., van Hunen, J., and Pingzhong, Z., 2015: Seasonality of westerly moisture transport in the East Asian Summer Monsoon and its implications for interpreting precipitation d18O, J. Geophys. Res., 120, doi:10.1002/2014JD022919.
  • Steen-Larsen, H. C., Sveinbjörnsdottir, A. E., Jonsson, T., Ritter, F., Bonne, J.-L., Masson-Delmotte, V., Sodemann, H., Blunier, T., Dahl-Jensen, D., Vinther, B. M., 2015: Moisture sources and synoptic to seasonal variability of North Atlantic water vapor isotopic composition, J. Geophys. Res., 120, 5757–5774, doi:10.1002/ 2015JD023234.
  • Bonne, J.-L., Steen-Larsen, H. C., Risi, C., Werner, M., Sodemann, H., Lacour, J.-L., Fettweis, X., Cesana, G., Delmotte, M., Cattani, O., Vallelonga, P., Kjær, H. A., Clerbaux, C., Sveinbjörnsdóttir, A. E., and Masson-Delmotte, V., 2015: The summer 2012 Greenland heat wave: In situ and remote sensing observations of water vapor isotopic composition during an atmospheric river event, J. Geophys. Res., 120, 2970-2989, doi:10.1002/2014JD022602.
  • Luetscher, M., Boch, R., Sodemann, H., Spoetl, C., Cheng, H., Edwards, R. L., Frisia, S., Hof, F., Mueller, W., 2015: North Atlantic storm track changes during the Last Glacial Maximum recorded by Alpine speleothems, Nature Comm. 6: 6344, doi:10.1038/ncomms7344.
  • Winschall, A., Sodemann, H.,Pfahl, S. and Wernli, H., 2014: How important is intensified evaporation for Mediterranean precipitation extremes?, J. Geophys. Res., 119: 5240–5256, doi:10.1002/2013JD021175
  • Winschall, A., Pfahl, S., Sodemann, H.and Wernli, H.. 2014. Comparison of Eulerian and Lagrangian moisture source diagnostics - the flood event in eastern Europe in May 2010, Atmos. Chem. Phys. 14: 6605–6619, doi:10.5194/acp-14-6605-2014.
  • Aemisegger, F., Pfahl, S., Sodemann, H., Lehner, I., Seneviratne, S. I., and Wernli, H., 2014: Deuterium excess as a proxy for continental moisture recycling and plant transpiration, Atmos. Chem. Phys., 14: 4029–4054, doi:10.5194/acp-14-4029-2014.
  • Bonne, J. L., Masson-Delmotte, V., Cattani, O., Delmotte, M., Risi, C., Sodemann, H., and Steen-Larsen, H. C., 2014:The isotopic composition of water vapour and precipitation in Ivittuut, southern Greenland, Atmos. Chem. Phys. 14: 4419–4439, doi:10.5194/acp-14-4419-2014.
  • Wang, Y., Sodemann, H., Hou, S., Masson-Delmotte, V. Jouzel, J. and Pang, H., 2013: Snow accumulation and its moisture origin over Dome Argus, Antarctica. Clim. Dyn., 40:731-742, doi: 10.1007/s00382-012-1398-9.
  • Martius, O., Sodemann, H., Joos, H., Pfahl, S., Winschall, A., Croci-Maspoli, M., Graf, M., Madonna, E., Mueller, B., Schemm, S., Sedlacek, J., Sprenger, M. and Wernli, H., 2012: The role of upper-level dynamics and surface processes for the Pakistan flood in July 2010. Quart. J. Royal Meteorol. Soc., published online, doi: 10.1002/qj.2082.
  • Kennett, D. J., Breitenbach, S. F. M., Aquino, V. V., Asmerom, Y., Awe, J., Baldini, J. U. L., Bartlein, P., Culleton, B. J., Ebert, C., Jazwa, C., Macri, M. J., Marwan, N., Polyak, V., Prufer, K. M., Ridley, H. E., Sodemann, H., Winterhalder, B. and Haug, G. H., 2012: Development and Disintegration of Maya Political Systems in Response to Climate Change. Science, 338: 788-791, doi: 10.1126/science.1226299.
  • Winkler, R., Landais, A., Sodemann, H., Dümbgen, L., Priéa, F., Masson-Delmotte, V., Stenni, B., and Jouzel, J., 2012: Deglaciation records of 17O-excess in East Antarctica: reliable reconstruction of oceanic relative humidity from coastal sites. Clim. Past 8, 1-16.
  • Masson-Delmotte, V., Buiron, D., Ekaykin, A., Frezzotti, M., Gallée, H., Jouzel, J., Krinner, G., Landais, A., Motoyama, A., Oerter, H., Pol, K., Pollard, D., Ritz, C., Schlosser, E., Sime, L. C., Sodemann, H., Stenni, B., Uemura R., and Vimeux, F., 2011: A comparison of the present and last interglacial periods in six Antarctic ice cores Clim. Past, 7, 397-423.
  • Sodemann, H.and Zubler, E., 2010: Seasonality and inter-annual variability of the moisture sources for Alpine precipitation during 1995-2002, Int. J. Climatol., 30: 947-961, doi:10.1002/joc.1932.
  • Sodemann, H., and Stohl, A., 2009: Asymmetries in the moisture origin of Antarctic precipitation, Geophys. Res. Lett., 36, L22803, doi:10.1029/2009GL040242.
  • Sodemann, H., Masson-Delmotte, V., Schwierz, C., Vinther, B. M. and Wernli, H., 2008: Inter-annual variability of Greenland winter precipitation sources. Part II: Effects of North Atlantic Oscillation variability on stable isotopes in precipitation, J. Geophys. Res., 113, D12111, doi:10.1029/2007JD009416.
  • Sodemann, H., Schwierz, C., and Wernli, H., 2008: Inter-annual variability of Greenland winter precipitation sources. Lagrangian moisture diagnostic and North Atlantic Oscillation influence, J. Geophys. Res.,113, D03107, doi:10.1029/2007JD008503.