WaterSip: Difference between revisions

Revision as of 15:02, 8 November 2016

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.

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

- [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

- [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

- [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

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

@@ Line 15: / Line 15: @@
 *Lagranto: options specific to runs using Lagranto trajectories
-'''[Case]'''
+====Parameter set [Case]====
-- caseName (string): identifier for the run, prepended to all output files
+- '''caseName (string):''' identifier for the run, prepended to all output files
 <code>caseName = global_201002_final_relativex</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.
-- 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>
-- outputDir (string): path where the output files will be created.
+- '''outputDir (string):''' path where the output files will be created.
 <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.
+- '''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.
 <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.
+- '''endDate (date string):''' final date of the run, fixed format YYYYMMDD-HHMMSS. End date is earliest date of the run.
 <code>endDate = 20100211-000000</code>
-- timeStep (integer): time step in hours between particles or trajectory output times. (typical values 6, 3, or 1 (hours))
+- '''timeStep (integer):''' time step in hours between particles or trajectory output times. (typical values 6, 3, or 1 (hours))
 <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.
+- '''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.
 <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.
+- '''minTrajPoints (integer):''' minimum length of trajectories to be included in analysis. Parameter is only relevant for Lagranto simulations with uneven trajectory length.
 <code>minTrajPoints = 0</code>
-- sectorizeRegion (integer): region set used to divide moisture sources into different sectors (see [[Sectorization]])
+- '''sectorizeRegion (integer):''' region set used to divide moisture sources into different sectors (see [[Sectorization]])
 <code>sectorizeRegion = 0</code>
-- filterBoxFile (string): path to the text file describing geographic boxes used to filter air parcels during transport (see [[Box filters]]).
+- '''filterBoxFile (string):''' path to the text file describing geographic boxes used to filter air parcels during transport (see [[Box filters]]).
 <code>filterBoxFile = /home/hso039/progs/WaterSip_tool/BOX_FILTERS_SiebenHengste</code>
-- filterIndex (integer): used line from the filterBoxFile to select/deselect trajectories
+- '''filterIndex (integer):''' used line from the filterBoxFile to select/deselect trajectories
 <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.
+- '''orographyFile (string):''' path to the orography file used to select arrival based on underying topography, using the ETOPO2 topography. File in netcdf format.
 <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.
+- '''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.
 <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
+- '''maskFile (string):''' path to file with an arrival selection
 <code>maskFile = " "</code>
-- useMask (boolean): use mask file (0=no, 1=yes).
+- '''useMask (boolean):''' use mask file (0=no, 1=yes).
 <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.)
+- '''ompThreads (integer):''' number of threads to be used with OpenMP parallelisation if compiled with flag -fopenmp (1=no parallelisation, >1 parallelisation activated.)
 <code>ompThreads = 1</code>
-- showStats (boolean): print statistics about particle processing to the command line (0=off, 1=on).
+- '''showStats (boolean):''' print statistics about particle processing to the command line (0=off, 1=on).
 <code>showStats = 0</code>
-**[Grids]**
+====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 (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
+- '''arrivalGridMaxLon (float):''' maximum longitude of arrival (target region) grid box
 <code>arrivalGridMaxLon = 180</code>
-- arrivalGridMinLat (float): minimum latitude of arrival (target region) grid box
+- '''arrivalGridMinLat (float):''' minimum latitude of arrival (target region) grid box
 <code>arrivalGridMinLat = -90</code>
-- arrivalGridMaxLat (float): minimum latitude of arrival (target region) grid box
+- '''arrivalGridMaxLat (float):''' minimum latitude of arrival (target region) grid box
 <code>arrivalGridMaxLat = 90</code>
-- arrivalGridDx (float): longitude increment of arrival (target region) grid
+- '''arrivalGridDx (float):''' longitude increment of arrival (target region) grid
 <code>arrivalGridDx = 1</code>
-- arrivalGridDy (float): latitude increment of arrival (target region) grid
+- '''arrivalGridDy (float):''' latitude increment of arrival (target region) grid
 <code>arrivalGridDy = 1</code>
-- arrivalGridRadius (float): gridding radius for information from arriving trajectories
+- '''arrivalGridRadius (float):''' gridding radius for information from arriving trajectories
 <code>arrivalGridRadius = 200</code>
-- sourceGridMinLon (float): minimum longitude of moisture source grid box
+- '''sourceGridMinLon (float):''' minimum longitude of moisture source grid box
 <code>sourceGridMinLon = -180</code>
-- sourceGridMaxLon (float): maximum longitude of moisture source grid box
+- '''sourceGridMaxLon (float):''' maximum longitude of moisture source grid box
 <code>sourceGridMaxLon = 180</code>
-- sourceGridMinLat (float): minimum latitude of moisture source grid box
+- '''sourceGridMinLat (float):''' minimum latitude of moisture source grid box
 <code>sourceGridMinLat = -90</code>
-- sourceGridMaxLat (float): maximum latitude of moisture source grid box
+- '''sourceGridMaxLat (float):''' maximum latitude of moisture source grid box
 <code>sourceGridMaxLat = 90</code>
-- sourceGridDx (float): longitude increment of moisture source grid box
+- '''sourceGridDx (float):''' longitude increment of moisture source grid box
 <code>sourceGridDx = 1</code>
-- sourceGridDy (float): latitude increment of moisture source grid box
+- '''sourceGridDy (float):''' latitude increment of moisture source grid box
 <code>sourceGridDy = 1</code>
-- sourceGridRadius (float): longitude increment of moisture source grid box
+- '''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)
+- '''griddingType (integer):''' select [[gridding algorithm]] (1: fast and simple gridding, 2: improved but slower gridding)
 <code>griddingType = 2</code>
 **[Diagnostics]**
-- uptakeThreshold (float):
+- '''uptakeThreshold (float):'''
 <code>uptakeThreshold = 0.05</code>
-- precipThreshold (float):
+- '''precipThreshold (float):'''
 <code>precipThreshold = 0.05</code>
-- blhScale (float):
+- '''blhScale (float):'''
 <code>blhScale = 1.5</code>
-- arrivalPrecipMin (float):
+- '''arrivalPrecipMin (float):'''
 <code>arrivalPrecipMin = 0.05</code>
-- arrivalPrecipMax (float):
+- '''arrivalPrecipMax (float):'''
 <code>arrivalPrecipMax = 1.0</code>
-- arrivalRHMin (float):
+- '''arrivalRHMin (float):'''
 <code>arrivalRHMin = 80</code>
-- arrivalRHMax (float):
+- '''arrivalRHMax (float):'''
 <code>arrivalRHMax = 110</code>
-- arrivalOroMin (float):
+- '''arrivalOroMin (float):'''
 <code>arrivalOroMin = -100</code>
-- arrivalOroMax (float):
+- '''arrivalOroMax (float):'''
 <code>arrivalOroMax = 12000</code>
-- arrivalAltMin (float):
+- '''arrivalAltMin (float):'''
 <code>arrivalAltMin = -100</code>
-- arrivalAltMax (float):
+- '''arrivalAltMax (float):'''
 <code>arrivalAltMax = 12000</code>
-- analyzeVapour (boolean):
+- '''analyzeVapour (boolean):'''
 <code>analyzeVapour = 0</code>
-- assignToUptake (boolean):
+- '''assignToUptake (boolean):'''
 <code>assignToUptake = 0</code>
-- forwardProjectionMode (integer):
+- '''forwardProjectionMode (integer):'''
 <code>forwardProjectionMode = 3</code>
-- relativeThreshold (boolean):
+- '''relativeThreshold (boolean):'''
 <code>relativeThreshold = 1</code>
 **[Output]**
-- stepFile (boolean): write parameters on grid and series files for each time step
+- '''stepFile (boolean):''' write parameters on grid and series files for each time step
 <code>stepFile = 1</code>
-- dayFile (boolean): write parameters on grid and series files averaged/accumulated for each day
+- '''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
+- '''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
+- '''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
+- '''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
+- '''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.
+- '''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)
+- '''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)
+- '''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).
+- '''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>