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.
Starting the WaterSip diagnostic
The current version of WaterSip is V3.0.0. It is advised to create a link to the binary file of WaterSip in you /home/$USER/bin or project directory:
mkdir ~/bin ln -s /Data/gfi/met_backup/progs/WaterSip_tool/WaterSip3 ~/bin
~/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):
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.
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 the queue (this is imperative for all runs except for short tests), the following wrapper script can be used to start a run using 4 cores for parallel processing:
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
- caseName (string): identifier for the run, prepended to all output files
caseName = global_201002_final_relativex
- 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.
inputDir = /Volumes/Data/global/shortposit_%s
- outputDir (string): path where the output files will be created.
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.
startDate = 20100228-180000
- endDate (date string): final date of the run, fixed format YYYYMMDD-HHMMSS. End date is earliest date of the run.
endDate = 20100211-000000
- timeStep (integer): time step in hours between particles or trajectory output times. (typical values 6, 3, or 1 (hours))
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.
trajPoints = 21
- minTrajPoints (integer): minimum length of trajectories to be included in analysis. Parameter is only relevant for Lagranto simulations with uneven trajectory length.
minTrajPoints = 0
- sectorizeRegion (integer): region set used to divide moisture sources into different sectors (see Sectorization)
sectorizeRegion = 0
- filterBoxFile (string): path to the text file describing geographic boxes used to filter air parcels during transport (see Box filters).
filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste
- filterIndex (integer): used line from the filterBoxFile to select/deselect trajectories
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.
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.
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
maskFile = " "
- useMask (boolean): use mask file (0=no, 1=yes).
useMask = 0
- ompThreads (integer): number of threads to be used with OpenMP parallelisation if compiled with flag -fopenmp (1=no parallelisation, >1 parallelisation activated.)
ompThreads = 1
- showStats (boolean): print statistics about particle processing to the command line (0=off, 1=on).
showStats = 0
Parameter set Grids
- 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.
arrivalGridMinLon = -180
- arrivalGridMaxLon (float): maximum longitude of arrival (target region) grid box
arrivalGridMaxLon = 180
- arrivalGridMinLat (float): minimum latitude of arrival (target region) grid box
arrivalGridMinLat = -90
- arrivalGridMaxLat (float): minimum latitude of arrival (target region) grid box
arrivalGridMaxLat = 90
- arrivalGridDx (float): longitude increment of arrival (target region) grid
arrivalGridDx = 1
- arrivalGridDy (float): latitude increment of arrival (target region) grid
arrivalGridDy = 1
- arrivalGridRadius (float): gridding radius for information from arriving trajectories
arrivalGridRadius = 200
- sourceGridMinLon (float): minimum longitude of moisture source grid box
sourceGridMinLon = -180
- sourceGridMaxLon (float): maximum longitude of moisture source grid box
sourceGridMaxLon = 180
- sourceGridMinLat (float): minimum latitude of moisture source grid box
sourceGridMinLat = -90
- sourceGridMaxLat (float): maximum latitude of moisture source grid box
sourceGridMaxLat = 90
- sourceGridDx (float): longitude increment of moisture source grid box
sourceGridDx = 1
- sourceGridDy (float): latitude increment of moisture source grid box
sourceGridDy = 1
- sourceGridRadius (float): longitude increment of moisture source grid box
sourceGridRadius = 200
- griddingType (integer): select gridding algorithm (1: fast and simple gridding, 2: improved but slower gridding)
griddingType = 2
Parameter set Diagnostics
- uptakeThreshold (float):
uptakeThreshold = 0.05
- precipThreshold (float):
precipThreshold = 0.05
- blhScale (float):
blhScale = 1.5
- arrivalPrecipMin (float):
arrivalPrecipMin = 0.05
- arrivalPrecipMax (float):
arrivalPrecipMax = 1.0
- arrivalRHMin (float):
arrivalRHMin = 80
- arrivalRHMax (float):
arrivalRHMax = 110
- arrivalOroMin (float):
arrivalOroMin = -100
- arrivalOroMax (float):
arrivalOroMax = 12000
- arrivalAltMin (float):
arrivalAltMin = -100
- arrivalAltMax (float):
arrivalAltMax = 12000
- analyzeVapour (boolean):
analyzeVapour = 0
- assignToUptake (boolean):
assignToUptake = 0
- forwardProjectionMode (integer):
forwardProjectionMode = 3
- relativeThreshold (boolean):
relativeThreshold = 1
Parameter set Output
- stepFile (boolean): write parameters on grid and series files for each time step
stepFile = 1
- dayFile (boolean): write parameters on grid and series files averaged/accumulated for each day
dayFile = 1
- monthFile (boolean): write parameters on grid and series files averaged/accumulated for each month
monthFile = 1
- yearFile (boolean): write parameters on grid and series files averaged/accumulated for each year
yearFile = 1
- allFile (boolean): write parameters on grid and series files averaged/accumulated for all time steps
allFile = 1
- staticFields (boolean): write static fields (land-sea mask and topography) onto grid files
staticFields = 1
- saveTraj (integer): write particle trajectories to traj files at each time step (1) or each month (2). Option 0 disables trajectory output.
saveTraj = 0
- skipTraj (boolean): write every nth trajectory to reduce traj file size (0 or 1:disabled, >=2: stride size)
skipTraj = 0
- saveHistogram (boolean): write histogram for selected parameters to a histogram file (0: disabled, 1:enabled)
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).
saveMean = 0
Parameter set 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
Parameter set Flexpart
- 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 data short format
inputFormat = 3
- maxPart (integer): number of particles contained in a single FLEXPART partposit or shortposit file
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.
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).
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).
allowReenter = 1
Full example for a FLEXPART run input file:
[Case] caseName = global_201002_final_relativex inputDir = /Volumes/Data_B/flexpart/global/shortposit_%s outputDir=/Volumes/Data_B/watersip/global_201002_V3/ startDate = 20100228-180000 endDate = 20100211-000000 timeStep = 6 sectorizeRegion = 0 filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste filterIndex = -1 orographyFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/WaterSip_tool/etopo5.nc" lsmFile = "/Users/hso039/Library/Mobile Documents/com~apple~CloudDocs/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