gfi - User contributions [en]

The GFI computing system

2026-03-23T10:35:47Z

Hso039:

The Geophysical Institute uses a department compute server cluster named "cyclone". Cyclone consists of three separate compute nodes organized in a cluster which access the same centralized network storage. Two of the nodes are for regular computational tasks, and one is set up with a GPU to enable use for machine learning (ML) applications. The new cyclones replace the older system '"cyclone.hpc.uib.no", acquired in Summer 2018, which at the time of writing this documentation is still accessible as well (14.03.2026).

The server cluster is maintained by [https://www.uib.no/en/brita UiB ITA] and compute resources are located in [https://nrec.no NREC] as virtual servers, currently running Linux, Rocky 8

All users of the cyclones should subscribe to the mailing list [linux@gfi.uib.no] to receive updates about maintenance downtime etc.

Please notify the UiB support [https://hjelp.uib.no https://hjelp.uib.no] in any case of problems or questions. And please be accurate to mark your support request with some ref. to "Group of scientific computing" - and with all necessary details for UiB support to decode your issue description.

In the following, you will find:

==Users and intended use==

The intended users at GFI for the cyclones are:

* MSc students for course and thesis work.

* PhD students and PostDocs for scientific work.

* all other researchers and technical staff for data analysis, data storage, and routine computations.
The cyclone compute system has been set up to enable users to perform smaller-scale data analysis work in a low-threshold environment. This means that there is no queue system for resource allocation. Users can use the system interactively, running applications with a GUI, or via Linux shell etc.

All users share the same resources, without having to deal with a queue system. This requires users to excert discipline when using resources to prevent system instability due to too heavy load.

Common use cases include data analysis connected to the shared data files in the storage environment, model simulations lasting up to several days, and tests of larger-scale computations before taking those to the national computation infrastructures NRIS.

==Requirements==

Users should be able to use the system in interactive use (click and point, typing) and in batch use (using shell scripts). Typical tasks are data analysis, plotting. GFI will also run routine data processing of observations and forecasts on this system.

Therefore, we required the system to be or have

* low threshold access (easy to use)

* interactive use

* safe usage (against unintentional overuse)

* optimized for serial I/O (as is typical for post-processing tasks)

* single-node parallelization jobs

* lifetime of 5-7 years

== System characteristics and good user practice ==

The system has been created as a low threshold, multi-user system. Resources are limited, and shared among all users. This implies that users need to have an overview over which resources they are using.

Users are expected to read and relate to the "MOTD" message at ssh-login. This monitors computer load and memory consumption. Please follow server load during login period - top/htop and free ('free -h -t') utilities. Do not initiate another heavy compute process on multiple cores if the compute node already runs heavy on load or memory consumption, then rather check the alternate server.

The system characteristics, and the good user practice that follows along with these, are as follows:

* There is (currently) no queue system on any of the "cyclones". Computational tasks are started immediately.

* Computational tasks will be terminated if users log out. To keep jobs running while logged out, start jobs in the background using the linux commands 'tmux', 'screen' or 'nohup'.

* There is a resource limitation per user. Each session can use up to 8 out of the 64 CPU cores. In addition, each session can allocate up to 120 GB of memory. This is meant to prevent individual users from accidentally bringing down the system.

* Software packages are activated using <nowiki>'''</nowiki>module load<nowiki>'''</nowiki> command. Use 'module spider <software>' to find available software. The available software stack is identical on all cyclones.

* Users have access to a home directory, a work storage, and long-term project and shared resource storage. The same storage environment is connected to all of the cyclones. Use the work storage for all non-permanent input/output. Files on the work environment are deleted after 60 days. Use NIRD for long-term storage of larger output.

* The system is maintained by the experts from UiB's HPC group. There is bi-weekly maintenance planned, typically on Wednesdays. Sometimes this will involve a reboot of the system. Plan longer jobs so that they don't get interrupted or interfere with maintenance scheduling.
* Subscribe to the mailing list [linux@gfi.uib.no](<nowiki>mailto:linux@gfi.uib.no</nowiki>) to receive updates about problems and maintenance

== Storage environment ==

GFI&SKD have a disposal of approx 450TB network storage quotas from UiB ITA(May 2024). This storage is all organized via ITA standard NetApp solution and distributed towards cyclones servers, GFI&SKD Windows clients, MacOS clients and Linux clients. The storage is also available for GFI&SKD users connecting from UiB-vpn.

*The GFI&SKD storage is organized into larger shared areas for model data, more limited group and project areas, areas for individual users and common areas for short time storage. The different storage areas are in general maintained via ITA backup procedures and governed by group or individual storage quotas.

* GFI&SKD storage is organized in two main folders:
Linux: /Data/gfi - Win11/Mac: \\klient.uib.no\felles\matnat\gfi and

Linux: /Data/skd - Win11/Mac: \\klient.uib.no\felles\matnat\skd

== Computational resources ==

The compute system is separated into three separate nodes. Two nodes (cyclone1 and cyclone2) are dedicated to computing tasks without GPU use. A third node is dedicated for GPU applications (cyclone 3). In detail, the specifications of the 3 compute nodes are:

'''Cyclone 1 - CPU applications (cyclone1.gfi.uib.no):'''

AMD EPYC Processor, 64 physical cores and 512 GB memory per node, 2.3 GHz - no GPU

'''Cyclone 2 - CPU applications (cyclone2.gfi.uib.no):'''

AMD EPYC Processor, 64 physical cores and 512 GB memory per node, 2.3 GHz - no GPU

'''Cyclone 3 - GPU applications (cyclone3.gfi.uib.no):'''

Intel CPU, 16 physical cores, 128 GB memory

1 NVIDIA GPU, L40S-24Q, 24 GB GPU memory

== GPU acceleration ==

One of the cyclones (cyclone3) is equipped with an advanced Graphics Processing Units (GPUs) of type NVIDIA L40S-24Q, and is reserved for GPU application usage only. The GPU is shared between all users on the system.

The GPU usage can be monitored using the command: "nvidia-smi".

Programming on this GPU is done using CUDA.

Modules are available for programming with CUDA.

Python users can load module PyTorch

The GFI computing system

2026-03-23T10:32:57Z

Hso039: spelling errors

The Geophysical Institute uses a department compute server cluster named "cyclone". Cyclone consists of three separate compute nodes organized in a cluster which access the same centralized network storage. Two of the nodes are for regular computational tasks, and one is set up with a GPU to enable use for machine learning (ML) applications. The new cyclones replace the older system '"cyclone.hpc.uib.no", acquired in Summer 2018, which at the time of writing this documentation is still accessible as well (14.03.2026).

The server cluster is maintained by [https://www.uib.no/en/brita UiB ITA] and compute resources are located in [https://nrec.no NREC] as virtual servers, currently running Linux, Rocky 8

All users of the cyclones should subscribe to the mailing list [linux@gfi.uib.no] to receive updates about maintenance downtime etc.

Please notify the UiB support [https://hjelp.uib.no https://hjelp.uib.no] in any case of problems or questions. And please be accurate to mark your support request with some ref. to "Group of scientific computing" - and with all necessary details for UiB support to decode your issue description.

In the following, you will find:

==Users and intended use==

The intended users at GFI for the cyclones are:

* MSc students for course and thesis work.

* PhD students and PostDocs for scientific work.

* all other researchers and technical staff for data analysis, data storage, and routine computations.
The cyclone compute system has been set up to enable users to perform smaller-scale data analysis work in a low-threshold environment. This means that there is now queue system for resource allocation. Users can use the system interactively, running applications with a GUI, or via Linux shell etc.

All users share the same resources, without having to deal with a queue system. This requires users to excert discipline when using resources to prevent system instability due to too heavy load.

Common use cases include data analysis connected to the shared data files in the storage environment, model simulations lasting up to several days, and tests of larger-scale computations before taking those to the national computation infrastructures NRIS.

==Requirements==

Users should be able to use the system in interactive use (click and point, typing) and in batch use (using shell scripts). Typical tasks are data analysis, plotting. GFI will also run routine data processing of observations and forecasts on this system.

Therefore, we required the system to be or have

* low threshold access (easy to use)

* interactive use

* safe usage (against unintentional overuse)

* optimized for serial I/O (as is typical for post-processing tasks)

* single-node parallelization jobs

* lifetime of 5-7 years

== System characteristics and good user practice ==

The system has been created as a low threshold, multi-user system. Resources are limited, and shared among all users. This implies that users need to have an overview over which resources they are using.

Users are expected to read and relate to the "MOTD" message at ssh-login. This monitor computer load and memory consumption. Please follow server load during login period - top/htop and free ('free -h -t') utilities. Do not initiate another heavy compute process on multiple cores if the compute node already runs heavy on load or memory consumption, then rather check the alternate server.

The system characteristics, and the good user practice that follows along with these, are as follows:

* There is (currently) no queue system on any of the "cyclones". Computational tasks are started immediately.

* Computational tasks will be terminated if users log out. To keep jobs running while logged out, start jobs in the background using the linux commands 'tmux', 'screen' or 'nohup'.

* There is resource limitation per user. Each session can use up to 8 out of the 64 CPU cores. In addition, each session can allocate up to 120 GB of memory. This is meant to prevent individual users from accidentally bringing down the system.

* Software packages are activated using <nowiki>'''</nowiki>module load<nowiki>'''</nowiki> command. Use 'module spider <software>' to find available software. The available software stack is identical on all cyclones.

* Users have access to a home directory, a work storage, and long-term project and shared resource storage. The same storage environments is connected to all of the cyclones. Use the work storage for all non-permanent input/output. Files on the work environment are deleted after 60 days. Use NIRD for long-term storage of larger output.

* The system is maintained by the experts from UiB's HPC group. There is bi-weekly maintenance planned, typically on Wednesdays. Sometimes this will involve a reboot of the system. Plan longer jobs that they don't get interrupted or interfere with maintenance scheduling.
* Subscribe to the mailing list [linux@gfi.uib.no](<nowiki>mailto:linux@gfi.uib.no</nowiki>) to receive updates about problems and maintenance

== Storage environment ==

GFI&SKD have a disposal of approx 450TB network storage quotas from UiB ITA(May 2024). This storage is all organized via ITA standard NetApp solution and distributed towards cyclones servers, GFI&SKD Windows clients, Macos clients and Linux clients. The storage is also available for GFI&SKD users connecting from UiB-vpn.

*The GFI&SKD storage is organized into larger shared areas for model data, more limited group and project areas, areas for individual users and common areas for short time storage. The different storage areas are in general maintained via ITA backup procedures and governed by group or individual storage quotas.

* GFI&SKD storage is organized in two main folders:
Linux: /Data/gfi - Win11/Mac: \\klient.uib.no\felles\matnat\gfi and

Linux: /Data/skd - Win11/Mac: \\klient.uib.no\felles\matnat\skd

== Computational resources ==

The compute system is separated into three separate nodes. Two nodes (cyclone1 and cyclone2) are dedicated to computing tasks without GPU use. A third node is dedicated for GPU applications (cyclone 3). In detail, the specifications of the 3 compute nodes are:

'''Cyclone 1 - CPU applications (cyclone1.gfi.uib.no):'''

AMD EPYC Processor, 64 physical cores and 512 GB memory per node, 2.3 GHz - no GPU

'''Cyclone 2 - CPU applications (cyclone2.gfi.uib.no):'''

AMD EPYC Processor, 64 physical cores and 512 GB memory per node, 2.3 GHz - no GPU

'''Cyclone 3 - GPU applications (cyclone3.gfi.uib.no):'''

Intel CPU, 16 physical cores, 128 GB memory

1 NVIDIA GPU, L40S-24Q, 24 GB GPU memory

== GPU acceleration ==

One of the cyclones (cyclone3) is equipped with an advanced Graphics Processing Units (GPUs) of type NVIDIA L40S-24Q, and is reserved for GPU application usage only. The GPU is shared between all users on the system.

The GPU usage can be monitored using the command: "nvidia-smi".

Programming on this GPU is done using CUDA.

Modules are available for programming with CUDA.

Python users can load module PyTorch

Using cyclone

2024-11-06T10:50:01Z

Hso039: updates to new storage locations

== Connection and first steps ==

Use ssh to connect
<pre>ssh -Y <username>@cyclone.hpc.uib.no</pre>
or just simply:
<pre>ssh -Y cyclone.hpc.uib.no</pre>
if you're connecting from a computer where you are logged in under the same name. When you are connecting for the first time, you will be asked to verify a signature. Reply "yes" to this question.

=== Home directories ===

<code>cyclone.hpc.uib.no</code> shares home directories with the new hexagon cluster. These home directories are separate from your standard UiB home directory. The contents of your home directories will not be synced, so you will manually need to transfer your scripts to the new system.

Please be aware that your local home directory is not expected to exceed 30GB at any time - even in periods when sys.adms. do not practice quotas. If you need to store larger amount of data, please plan for using the GFI&SKD storage - also decribed in this wiki.

To monitor your home directory size, you can use these commands from cyclone command shell:

<code>du -sh ~/ </code>

Or to include more details on both dot files/directories and non-hidden home directory subfolders:

<code>cd; du -sh .[^.]* *</code>

Monitoring your homefolder quota, you can run the following command:

<code>lfs quota -hp $(id -u) /shared/ </code>

or just

<code>lfs quota -hp $(id -u) $HOME </code>

=== How to access software ===

In contrast to the old skd-cyclone, most scientific software is only available through software modules. Modules need to be loaded manually before the respective software can be used. We use software modules, because they provide are a clean and handy way to offer conflicting software or software versions: Instead of updating software and potentially breaking user scripts and programs new software is then made available in parallel to those that require it.

=== Start-up scripts ===

It might be handy to automatically load modules for software that you use frequently every time you login to cyclone. To accomplish that for bash, there are two relevant files, <code>$HOME/.bashrc</code> and <code>$HOME/.bash_profile</code> . <code>.bash_profile</code> should contain things that need to be defined at login time only, like <code>PATH</code> and other environment variables, startup programs, etc. You just need things once, not in every shell you open. In most cases, you also need the things from <code>.bashrc</code> in your login shell. That's why <code>.bash_profile</code> sources <code>.bashrc</code> as well, but .bashrc doesn't usually source <code>.bash_profile</code>. In contrast, <code>.bashrc</code> should typically contain things you want to set in every shell you open, like aliases, functions, etc. These are per shell session items that are not inherited from environment ([https://unix.stackexchange.com/questions/346336/why-have-both-bash-profile-and-bashrc source and detailed explanation]).

==== An example <code>.bash_profile</code> for inspiration ====

<pre>module load cdo/1.6.9
module load ncarg/6.3.0-login

alias rm="rm -i"
alias cp="cp -i"
alias erai="cd /Data/skd/share/Reanalysis/ERA_INTERIM/6HOURLY/"

if [ -f ~/.bashrc ]; then
. ~/.bashrc
fi</pre>

==== An example <code>.bash_profile</code> for inspiration ====

<pre>alias rm="rm -i"
alias cp="cp -i"
alias erai="cd /Data/skd/share/Reanalysis/ERA_INTERIM/6HOURLY/"</pre>

== Available software ==

Below is a list of frequently used software and which module to load on the new cyclone. Relevant module names are printed like for <code>matlab/2015b</code>. Modules can be loaded by <code>module load <module name></code>, and unloaded <code>module unload <module name></code>. [[Using modules on cyclone|More details on the module system]].

To list all available modules, use the command
<pre>module avail</pre>

Hexagon-specific modules are now no longer listed and available on cyclone. All packages listed with this command should work, so please report to <code>support@hpc.uib.no</code> if they do not.

=== Data analysis and plotting ===

* CDO
*: <code>CDO</code>, <code>CDO/1.9.5-foss-2018b</code>
* Dynlib
*: See temporary solution for python. Requires in addition <code>OpenBLAS/0.3.1-GCC-7.3.0-2.30</code> and <code>ScaLAPACK/2.0.2-gompi-2018b-OpenBLAS-0.3.1</code>.
* ghostview
*: ''<no module required>''
* grads
*: ''<no module required>''
* Matlab
*: <code>Matlab</code>, <code>Matlab/2018a</code>, <code>Matlab/2012a</code>
* ncdump and other netCDF utilities
*: <code>netCDF</code>, <code>netCDF/4.6.1-foss-2018b</code>
* NCL
*: <code>NCL</code>, <code>NCL/6.5.0</code>
* nco
*: <code>NCO</code>, <code>NCO/4.7.4-foss-2018b</code>
* ncview
*: <code>ncview</code>, <code>ncview/2.1.7-foss-2018b</code>. Load only when needed! The package is currently known to break some GUI programs like gedit and gvim.
* python, plus selection of scientific packages
*: ''First'' choose and load the python module for the python version that you want to use, either <code>Python/2.7.15-foss-2018b</code> for python 2.7.15, or <code>Python/3.7.0-foss-2018b</code> for python 3.7.0.
*: ''Then'', as a temporary solution, many scientific python packages are installed in the following virtual environments:
*: <code>source /Data/gfi/users/local/share/virtualenv/dynpie2/bin/activate</code> for python 2.7.15.
*: <code>source /Data/gfi/users/local/share/virtualenv/dynpie3-2021a/bin/activate</code> for python 3.7.0.
*: For the pygrib module, <code>ecCodes/2.7.3-foss-2018b</code> is required in addition.
* R
*: ''<no module required>''

=== Text editors ===

* emacs
*: Is installed globally, but requires <code>util-linux/2.32-GCCcore-7.3.0</code> to work.
* gedit
*: ''<no module required>''
* gvim
*: ''<no module required>''
* vi(m)
*: ''<no module required>''

=== Compilers and libraries ===

* blas
*: <code>OpenBLAS/0.3.1-GCC-7.3.0-2.30</code>. '''Note''': The library is called <code>libopenblas</code>, so you'll need to compile with <code>-lopenblas</code>.
* eccodes (replacement for grib_api)
*: <code>ecCodes/2.7.3-foss-2018b</code>
* gcc, gfortran
*: <code>GCC</code>, <code>GCC/7.3.0-2.30</code>
* grib_api
*: <code>grib_api/1.24.0-foss-2018b</code>
* HDF5 libraries
*: <code>HDF5/1.10.2-foss-2018b</code>
* lapack
*: <code>ScaLAPACK/2.0.2-gompi-2018b-OpenBLAS-0.3.1</code>. '''Note''': The library is called <code>libscalapack</code>, so you'll need to compile with <code>-lscalapack</code>.
* MPI
*: <code>OpenMPI/3.1.1-GCC-7.3.0-2.30</code>
* netcdf
*: For C-libaries: <code>netCDF/4.6.1-foss-2018b</code>,
*: For Fortran-libraries <code>netCDF-Fortran/4.4.4-foss-2018b</code>, compile with option <code>-I/shared/apps/netCDF-Fortran/4.4.4-foss-2018b/include</code>
* proj
*: <code>PROJ/5.0.0-foss-2018b</code>

=== Jupyter & Jupyterhub ===

Here is a step by step guide to setup and use Jupyter based on the <code>dynpie3</code> environment.

[[File:Get started cyclone.pdf|thumb|Step by step guide for Jupyter on cyclone]]

== Accessing the data from your own machines ==

Note: From your personal machines you will need to be connected to the UiB VPN to be able to mount the following network drives.

On MacOS you can mount folders through <code>Finder > Go > Connect to Server ...</code>. In the dialogue window that pops up, enter
<pre>smb://uib.no;<user name>@klient.uib.no/FELLES/MATNAT/GFI</pre>
as the '''Server Address'''. You might want to replace <code>gfi</code> by <code>skd</code> to access the skd disks if that is your primary affiliation.
On Ubuntu this is very similar: <code>Files > Go > Enter Location ...</code>. Enter the address: <pre>smb://uib.no;<user name>@klient.uib.no/FELLES/MATNAT/GFI</pre> and enter your password in the next pop-up window, while keeping "UiB" in the "Domain" field.
Alternatively you can mount the network drive with sshfs to a dedicated directory using <code>sshfs</code> (install with <code>sudo apt install sshfs</code>):
<pre>mkdir ~/cyclone_gfi
From UiB network: sshfs -o follow_symlinks <user name>@cyclone.hpc.uib.no:/gfi/ ~/cyclone_gfi/
From ext. networks: sshfs -o follow_symlinks <user name>@sync.uib.no:/gfi/ ~/cyclone_gfi/
Unmount with: fusermount -u ~/cyclone_gfi</pre>
On Windows you can mount by navigating to <code>File Explorer > Map network drive</code> and enter <code>\\leo.hpc.uib.no\gfi</code>. Make sure to enable <code>Connect using different credentials</code> and fill in <code><user name>@uib.no</code> and your PW.

== Displaying GUIs on your screen ==

The ssh-login command at the top of this wiki enables trusted X11 forwarding (the <code>-Y</code> option), which allows you to display Graphical User Interfaces (GUIs) on your screen. This way you may be able to run software on a high performance system in a more userfriendly way than by just operating via the terminal. To make this work properly you may have to edit the ssh configuration file (<code>/etc/ssh/ssh_config</code> on linux systems) by adding or uncommenting the following two lines:

<pre>X11Forwarding yes
ForwardX11Trusted yes</pre>

Editing this file requires superuser priviliges so you may have to ask the IT department for support. For Mac the solution should be pretty similar, windows requires additional software like PuTTY (for establishing an ssh-connection) and an XServer (e.g. VcXsrv).

WaterSip

2022-03-07T11:10:29Z

Hso039:

===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 [[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]].

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

====Creating mask files====

WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.

The procedure described here uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.

Required python packages [tested version]: numpy [1.19.1], shapely [1.6.4.post1], netCDF4 [1.5.3] and if loading from a csv, pandas [1.1.3]

Optional packages (for plotting): matplotlib [3.3.1], cartopy [0.16.0]

[[File:watersip_mask-guide_cut.png|400px]]
Figure: Example for Scandinavia

''Basic principle:''

Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed).
This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points).
After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.

<pre>
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.
</pre>

''Input:''

list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.

global meshgrid with a given resolution

''Output:''

Boolean mask of False and True in the shape of the meshgrid lat-lon

After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:

<pre>
cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
</pre>

For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to
[[https://gist.github.com/pelson/9785576]]

[[MaskCode|Python program code available here|]]

=== 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:

*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: <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>

----

====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: <code>uptakeThreshold = 0.2</code>

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

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

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

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

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

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

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

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

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

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

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

;analyzeVapour (boolean)
: Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters also need modification. Typically, one will set the <code>precipitation threshold</code> to a small or even positive number, and the <code>arrivalRHMin</code> to 0 and <code>arrivalRHMax</code> to 110 to include all arriving trajectories. It is often preferrable then to set the <code>arrivalAltMax</code> to values of around 1000m for surface station measurements, for example. If <code>analyzeVapour</code> is 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. Example: <code>analyzeVapour = 1</code>

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

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

----

====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: <code>stepFile = 1</code>

;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>

;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>

;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>

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

;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</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>

;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>

;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <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). Example: <code>saveMean = 0</code>

----

====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: <code>sourcesBoundaryLayer = 1</code>

;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: <code>sourcesFreeTroposphere = 1</code>

;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: <code>evaporationMinusPrecipitation = 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>

;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.

;partMass (float)
: atmospheric mass represented by each particle in kilogramms. The value for partMass depends on how the trajectories are arriving. They should be arriving on a regular starting grid (fixed horizontal distance), and fixed vertical distance (in delta p). Then one can calculate the value for partMass as dx*dy*dp with dx and dy in km, and dp in Pa. Internally, this number will then be multiplied with 1e6/g to obtain kg. (In a later version, this will change this so one directly specifies the partMass in kg). Example: <code>partMass = 1.01943e+12</code>

----

===Full example for a FLEXPART run input file:===

<pre>
[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
</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*.

The moisture sources are contained in the variables "moisture_uptakes_boundary_layer" and "moisture_uptakes_free_troposphere". The "moisture_transport" variable is a gridded map of the water vapour traced to the target region, and can help you identify transport pathways (weighted by humidity). The "trajectory_location" is a gridded map of all trajectory points, regardless of the air parcel humidity. In most current analyses, it is recommended to sum the two moisture_uptake_xx variables, except when one wants to distinguish the influence from convection on the moisture source diagnostic.

{| class="wikitable"
! 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*.

{| class="wikitable"
! 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:

{| class="wikitable"
! 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.

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

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

{| class="wikitable"
! 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*

{| class="wikitable"
! 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.

{| class="wikitable"
! 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.

FaVaCal - FARLAB water vapour isotope calibration processor

2021-02-09T20:39:38Z

Hso039: Created page with "<h3>FaVaCal (FARLAB Vapour Calibration Routines) Documentation</h3> Version 1.1 (24.08.2019) '''Harald Sodemann, Geophysical Institute, University of Bergen, Norway''' <h4..."

<h3>FaVaCal (FARLAB Vapour Calibration Routines) Documentation</h3>

Version 1.1 (24.08.2019)

'''Harald Sodemann, Geophysical Institute, University of Bergen, Norway'''

<h4> Purpose </h4>

FaVaCal has been created to provide a standard routine for the calibration of water vapour measurements from Picarro L2130-i/L2140-i analyzers in use at FARLAB. The primary application is to indentify calibrations obtained from the SDM module. However, it is also possible to perform calibration with other methods. There is support for manual injections into the Picarro Vapourizer, or for self-defined calibrations obtained by other means.

FaVaCal provides an overview of the data processing as HTML report, including quality flags and instrument parameters. The main result are data files with calibrated measurements in netCDF format. The data files contain quality flags and provide different averaging times.

FaVaCal consists of a set of routines written in Matlab. It should be straightforward to translate these routines into other languages, such as python, if necessary.

----

<h4> Installation </h4>

The FaVaCal code is hosted at the [git.app.uib.no:farlab-codes/farlab_vapour.git FaVaCal git repository]. Download or clone to a local directory to use FaVaCal.

On the GFI linux system, FaVaCal is installed at <code>/Data/gfi/scratch/metdata/scripts/FARLAB/matlab</code>

----

<h4> Files and structure </h4>

FaVaCal is operated by defining a run file that creates a set of matlab variables (structures), and then calls the main FaVaCal routine. The name of this routine can be chosen by the user. Typical names in use at FARLAB are e.g. <code>FaVaCal_SNOWPACE_Finse_run01.m</code>.

The files included in FaVaCal are:

; FaVaCal_report.m : Create the output directory, call required subroutines in sequence, and produce the HTML report.

; FaVaCal_calibrations.m : Identify calibrations from SDM or manual injections, quality control, plot, and save as structure in file <run>_calibrations.mat

; FaVaCal_calibrate.m : Perform quality control of vapour data, calibration, time averaging, daily and overview plots, and netCDF output.

; FARLAB_standards.m : A file containing information about the available calibration standards. This file is shared with the FLIIMP project.

; FARLAB_vapour_data.m : Routine to read in vapour data for a given time range. The vapour data are in raw netCDF format, which is obtained from a python conversion routine <code>FARLAB_Picarro_dat2nc.py</code>.

----

<h4> Usage </h4>

FaVaCal consists of a set of routines written in Matlab. Before running the calibration, the user needs to create a run file that defines a set of matlab variables. These matlab variables contain all the settings required to perform the calibration, as explained below.

----

<h4> General working principle </h4>

FaVaCal then proceeds to identify the calibrations from the raw data files, performs quality control of the identified calibrations, and creates overview figures for each calibration. The result of the calibrations is saved as a matlab file in the output folder, named <code>FARLAB_HKDS2038_calibrations.mat</code>.

Thereafter, the vapour data are calibrated one day at a time. For each day, the nearest 2 (default value) valid calibrations are identified, averaged, and used for calibration. Quality codes, flagging and filtering is performed on the native time resolution data (see below). The data is then averaged to 1s, 10s, 30s, 1min and 1h time resolution, and all resolutions are saved into one netCDF data file. Overview plots of the calibrated data and instrument parameters are created for each day and the entire calibration period.

Finally, a HTML report is created that summarizes the calibration run, and includes the overview figures and a table of all calibrations (see below). Additionally, a method description is included, as well as recommendations for acknowledgements in scientific publications.

----

<h4> Calibration period identification </h4>

The entire calibration period was first processed for calibration periods with the SDM. The SDM was equipped with two bags, one each filled with standard DI ( -7.78 permil δ18O and δD -50.38 permil) and GSM1 (-33.07 permil in δ18O and -262.95 permil in δD). Typically, standards were applied to the analyzer 1-2 times in a 24 h period. Dry air was supplied from a synthetic air cylinder, or from a drierite patron.

Calibration periods were identified for each day as periods when the valve mask switches to 6, which is the case during SDM calibration. Then for each calibration period, the median value of humidity, δ18O and δD are obtained. To identify bursting bubbles and other variations that are generally due to deficiencies of the SDM vapour stream generator, values where that deviate by more than 0.5 permil in δ18O or 4.0 permil in δD are discarded. The remaining data for each period are then averaged and the standard deviation calculated. Each calibration is then assigned with quality flags according to the following criteria:

* Unknown standard, bit 1, value 1: Median value can not be matched with an expected value for a standard.
* Humidity range, bit 2, value 2: Humidity below 17000 ppmv or above 23000 ppmv.
* Humidity variation, bit 3, value 4: Standard deviation of humidity larger than 500 ppmv.
* Isotope variation, bit 4, value 8: Isotope variability above 0.5 permil for δ18O or above 5.0 permil for δD.
* Bubble bursting, bit 5, value 16: Humidity disturbances with max(H2O) exceeding 23000 ppmv.
* Low data fraction, bit 6, value 32: More than 60.0&perc; of data removed from calibration period.

----

<h4> Quality flags and data calibration </h4>

Next, the vapour measurements are calibrated using calibrations of sufficient quality. For each calendar day in the period, data was calibrated using the two nearest available calibrations with sufficient quality within the entire calibration period. Sufficient quality is defined as quality flags 1, 2 and 6 not set. Quality flags 3, 4 and 5 increase uncertainty, but do not invalidate a calibration period. Calibration of offset and slope onto the VSMOW2-SLAP2 scale with FARLAB laboratory standards DI and GSM1 follows the recommendations of IAEA (2010).

For quality control of the vapour data, time periods of instrument parameter ranges outside of specifications are flagged and, if applicable, deleted. Each data point is assigned a vapour quality flag according to the following criteria:

* Calibration period, bit 1, value 1: ValveMask is 0, flagged but not deleted.
* Low humidity, bit 2, value 2: Mixing ratio of H2O below 200 ppmv.
* Spike in δ18O, bit 3, value 4: deviation of δ18O to previous value exceeds 400.0 permil.
* Spike in d-excess, bit 4, value 8: deviation of d-excess to previous value exceeds 100.0 permil.
* Low cavity temperature, bit 5, value 16: Cavity temperature below 79.9 deg C (typically during warmup). 1500s after a low cavity temperature event are removed to allow for instrument stabilisation.
* Specified event, bit 6, value 32: Event specified in event list occurred.

Thereafter, calibrated data are averaged over specific time periods, using a running averaging window of 1s, 10s, 1min, 10min and 1h. Averaged values of the isotope parameters and key instrument parameters are then written to a netCDF file.

----

<h4> Input file format</h4>

The input file format consists of 3 sets of variable definitions as matlab structures. These are explained in detail below.

<h5>Run settings</h5>

The run settings cover a identifying name (project), time period (startdate, enddate), the instrument serial number (instrument), input path for the raw files (inpath), the output path directory (outpath). Furthermore, the date of report generation (reportDate), the name and contact email of the operator (person who performs calibration: operator, operatorContact) and the customer (owner of the dataset: customer, contact) are provided.

<pre style="background-color: Gainsboro">
% run settings
settings.project='IGP2018_ship';
settings.startdate=datenum('2018-02-25');
settings.enddate=datenum('2018-03-22');
settings.instrument='HKDS2038';
settings.outpath='/Data/gfi/projects/farlab/Instruments/calibrated';
settings.inpath='/Data/gfi/scratch/metdata/FARLAB/%s/raw';
settings.reportDate=now;
settings.operator='Harald Sodemann';
settings.operatorContact='harald.sodemann@uib.no';
settings.customer='Harald Sodemann';
settings.contact='harald.sodemann@uib.no';
</pre>

The calibration settings control how the calibration is performed. The calibration routine automatically searches for either SDM calibrations or manual injections, using the Picarro's ValveMode flag. The standards used for each calibration (standardNames) are identified automatically from the definitions for different laboratory standard calibrations, set in the file FARLAB_standard.m (calset). The latest FARLAB calibration is currently 3. For each day, a given number of nearest calibrations is selected and averaged during calibration (ncals). If calibrations need to be specified manually, the automatic identification needs to be deactivated (replace=-1). In that case, additional calibration information can be provided that is included at the beginning of section 4 of the calibration report.

<pre style="background-color: Gainsboro">
% calibration settings
settings.calset=4; % which FARLAB calibration set to load (4: Iceland standards)
settings.standardNames={'GV';'NEEM'};
settings.ncals=4; % number of calibrations required for processing
settings.replace=-1; % replace exisiting calibrations file or use existing one, -1 for manual mode
% additional text for calibration method section
settings.calinfo='Calibration was performed using manual injections of standard liquids. The description below needs to be considered as of similar principle, but regarding manual injections'
</pre>

The automatic detection of calibrations, and quality control of the these, is controlled by a set of calibration parameters. This is organised as a sub-structure of the structure settings. 6 quality flags are set.

# unknown standard, automatic standard name detection failed
# mean humidity outside the specified range (qmin,qmax)
# humidity standard deviation above threshold (qstd)
# isotope parameter standard deviation above threshold (O18std, H2std)
# humidity maximum above threshold (bubble detection, qmax)
# deleted fraction above threshold (delfrac)

A quality flag of either 1,2 or 5 being set will result in not using the calibration run for data calibration. The minimum duration for SDM calibrations is typically 600s, whereas manual injections have a minimum length of 180s (minlen).

<pre style="background-color: Gainsboro">
% parameters to flag/quality code during calibration detection
settings.calparams.qmin=15000;
settings.calparams.qmax=25000;
settings.calparams.qstd=500;
settings.calparams.O18std=0.5;
settings.calparams.H2std=5.0;
settings.calparams.delfrac=60.0;
settings.calparams.minlen=180; % minimum length of a calibration
</pre>

A different set of quality flags is defined for the data outside calibration periods. 5 quality flags are set during this processing step:

# Calibration period (from automatic calibration identification)
# Low humidity (qmin)
# Spike in O-18 during a measuring interval (O18spike)
# Spike in d-excess during a measuring interval (dspike)
# Low cavity temperature (ctlow). A time period is removed after the temperature low to remove the overshoot heating (ctcut).
# Event period (see below)

<pre style="background-color: Gainsboro">
% parameters to flag/quality code during data processing
settings.qcparams.qmin=200;
settings.qcparams.O18spike=400;
settings.qcparams.dspike=100;
settings.qcparams.ctlow=79.5;
settings.qcparams.ctcut=750;
</pre>

<h5>Calibrations (Optional section)</h5>

Alternatively to the automatic identification of calibration periods, manual calibrations can be specified. In this case, the parameter settings.replace must be set to -1, and settings.calibrations must be defined as exemplified below. It can be useful to manually specify calibrations to test the effect of calibration parameters, or if a bubbler or other external device is used in the calibration process.

In the example below, 2 calibration runs are specified (run), with two different standards each (standard), with specified time segments (starts,ends), and quality codes (quality). The mean and standard deviations of humidity (H2O, H2O_SD), of O-18 (d18O, d18O_SD), of dD (dD, dD_SD) and d-excess (d, d_SD) are specified for each segment. The minimum and maximum water concentration (minH2O, maxH2O), a minimum humidity (dryValue) and the deleted data fraction are also specified manually (delFrac). Even if there is no figure for the calibration periods (figstr is set to empty), the parameter must be provided.

<pre style="background-color: Gainsboro">
% manually create calibrations
settings.calibrations=[];
settings.calibrations.starts=[datenum(2018,3,22,14,42,56),datenum(2018,3,22,15,3,3),datenum(2018,3,22,21,25,28),datenum(2018,3,22,21,45,34)];
settings.calibrations.ends=[datenum(2018,3,22,15,2,0),datenum(2018,3,22,15,23,6),datenum(2018,3,22,21,45,28),datenum(2018,3,22,22,5,34)];
settings.calibrations.run=[1 2 1 2];
settings.calibrations.standard=[1 1 2 2];
settings.calibrations.quality=[0 0 0 0];
settings.calibrations.H2O=[24800 24965 25510 25037];
settings.calibrations.H2O_SD=[157 151 164 165];
settings.calibrations.dD=[-266.301 -266.641 -45.354 -45.106];
settings.calibrations.dD_SD=[0.658 0.625 0.776 0.700];
settings.calibrations.d18O=[-36.202 -36.208 -10.928 -10.902];
settings.calibrations.d18O_SD=[0.124 0.103 0.134 0.140];
settings.calibrations.d=[23.315 23.279 41.07 42.110 ];
settings.calibrations.d_SD=[1 1 1 1];
settings.calibrations.minH2O=[24800 24965 25510 25037];
settings.calibrations.maxH2O=[24800 24965 25510 25037];
settings.calibrations.dryValue=[0 0 0 0];
settings.calibrations.delFrac=[0 0 0 0];
settings.calibrations.figstr=cell(4,1);
</pre>

<h5>Event specification</h5>

Special event periods can be specified, that are either only indicated in the calibration plots (mode 0), or that lead to the deletion of the respective data period from the calibrated files (mode -1). Each event consists of a start date, end date, description string, and the mode identifier. Events are included with the parameter settings.event. The events are included as an own quality flag, and listed with numbers in the data report (Table 2) and respective overview figures (Fig. 1 and 2).

<pre style="background-color: Gainsboro">
% create special events to note (mode 0) or to delete (mode -1)
event{1}={datenum(2018,2,25,0,0,0),datenum(2018,2,25,20,30,0),'Instrument installed',0};
event{2}={datenum(2018,2,26,14,0,0),datenum(2018,2,26,15,30,0),'Dry air',-1};
event{3}={datenum(2018,2,26,18,10,0),datenum(2018,2,26,20,45,0),'Dry air',-1};
event{4}={datenum(2018,2,27,11,20,0),datenum(2018,2,27,11,45,0),'Dry air',-1};
event{5}={datenum(2018,2,27,12,10,0),datenum(2018,2,27,13,10,0),'Dry air',-1};
event{6}={datenum(2018,2,28,19,10,0),datenum(2018,2,28,19,40,0),'Dry air',-1};
event{7}={datenum(2018,3,6,23,0,0),datenum(2018,3,6,23,15,0),'Dry air',-1};
event{8}={datenum(2018,3,9,16,0,0),datenum(2018,3,9,17,0,0),'Breathing test?',0};
event{9}={datenum(2018,3,22,12,10,0),datenum(2018,3,22,13,0,0),'Dry air',-1};
event{10}={datenum(2018,3,22,10,0,0),datenum(2018,3,22,11,0,0),'Breathing test',0};
event{11}={datenum(2018,3,22,23,0,0),datenum(2018,3,22,23,59,59),'Instrument deinstalled',-1};
settings.event=event;
</pre>

<h5>Metadata for netCDF files</h5>

The metadata to be included in each daily netCDF data file includes essential parameters for ownership, contact, location, time period, instrumentation, reference, and further comments, as exemplified below.

<pre style="background-color: Gainsboro">
% provide metadata as parameter
metadata.email='harald.sodemann@uib.no';
metadata.contact='Harald Sodemann';
metadata.version='1.0';
metadata.latitude='66.38 deg N';
metadata.longitude='5.33 deg W';
metadata.elevation='34.0 m a.s.l.';
metadata.location_name='R/V Alliance, Measurement container, boat deck';
metadata.created=datestr(now);
metadata.serial_number=settings.instrument;
metadata.instrument='Picarro L2140-i';
metadata.institution='Geophysical Institute, University of Bergen, Norway';
metadata.title='IGP campaign 2018, stable isotope measurements of water vapour on R/V Alliance';
metadata.comment='Picarro L2140-i installed in met container with heated inlet 3m above';
metadata.references='Renfrew et al., 2019, BAMS';
</pre>

The final statement in the run file must be the call to the FaVaCal_report() routine.

<pre style="background-color: Gainsboro">
% call the calibration routine with all parameters
FARLAB_vapour_dataset(settings,metadata);
</pre>

<h4> Report and output directory </h4>

FaVaCal summarizes the calibration result in a comprehensive calibration report. The report is rendered from the figures and data produced during calibration identification and the data calibration. The sections and figures of the report are:

# Summary
# Calibrated data
#* Figure 1: Overview over measurement period (1 minute averages)
#* Figure 2: Daily overview figures showing 10 second averages (black) with standard deviation (grey)).
# Acknowledgement section for publications
# Method description for publications
# Instrument stability
#* Figure 3: Overview over instrument status during entire calibration period.
# Calibration overview
#* Table 1: Calibrations summary.
# Preprocessing and corrections
#* Table 2: Event log.
# Appendix: Figures for all calibrations
#* Figure 6: Details for each calibration.

The report is located as index.html in the FaVaCal output directory. The output directory is placed at the location specified in the run settings file. In addition, there is a folder for the calibrated netCDF data files, and the figures produced during the calibration run.

<pre style="background-color: Gainsboro">
INTAROS2018-HKDS2038_20180731_20190823
calibrations.mat - matlab data file with identified or specified calibrations
img - folder with image files in png format
index.html - report in HTML format
calibrated - folder with calibrated data files in netCDF format
</pre>

----

<h4> Output netCDF file format</h4>

FaVaCal produces netCDF data files with the calibrated data. The metadata are included from the specifications in the run setup file, according to user input. In addition, information about the chosen calibrations and processing is included. Variables in the data files include the raw data (if requested), as well as various time resolutions. Only a few essential instrument parameters (Cavity temperature, Cavity pressure, Warm box temperature) are included from the raw data files. The quality flag is retained at the native time resolution.

----

<h4>Metadata</h4>

<pre style="background-color: Gainsboro">
// global attributes:
:email = "harald.sodemann@uib.no" ;
:contact = "Harald Sodemann" ;
:version = "1.0" ;
:latitude = "60.38 deg N" ;
:longitude = "5.33 deg E" ;
:elevation = "34.0 m a.s.l." ;
:location_name = "KV Svalbard" ;
:created = "23-Aug-2019 13:49:34" ;
:serial_number = "HKDS2038" ;
:instrument = "Picarro L2140-i" ;
:institution = "Geophysical Institute, University of Bergen, Norway" ;
:title = "Stable isotope measurements of water vapour in Bergen" ;
:comment = "Picarro L2140-i installed on board KV Svalbard during the INTAROS cruise" ;
:references = "" ;
:calibration\ standard\ 1 = "DI (d18O: -7.33 permil, dD: -49.95 permil)" ;
:calibration\ 1\ for\ standard\ 1 = "31-Jul-2018 10:28:16 (d18O: -7.38 permil, dD: -49.80 permil)" ;
:calibration\ 2\ for\ standard\ 1 = "02-Aug-2018 06:32:46 (d18O: -7.28 permil, dD: -50.10 permil)" ;
:calibration\ standard\ 2 = "GSM1 (d18O: -32.43 permil, dD: -263.49 permil)" ;
:calibration\ 1\ for\ standard\ 2 = "31-Jul-2018 09:47:50 (d18O: -32.45 permil, dD:-263.50 permil)" ;
:calibration\ 2\ for\ standard\ 2 = "02-Aug-2018 05:52:22 (d18O: -32.41 permil, dD:-263.48 permil)" ;
</pre>

<h5>Water isotope variables</h5>

<pre style="background-color: Gainsboro">
netcdf FARLAB_HKDS2038_cal_V1_20180731 {
dimensions:
time_1s = 219764 ;
time_10s = 8640 ;
time_1min = 1440 ;
time_10min = 144 ;
time_1h = 24 ;
variables:
double time_1s(time_1s) ;
time_1s:units = "days since 0001-01-01 00:00:00" ;
time_1s:long_name = "time_1s" ;
float delta_18O_1s(time_1s) ;
delta_18O_1s:units = "permil" ;
delta_18O_1s:_FillValue = -999.99f ;
delta_18O_1s:long\ name = "Oxygen-18" ;
float delta_D_1s(time_1s) ;
delta_D_1s:units = "permil" ;
delta_D_1s:missing_data = -999.99f ;
delta_D_1s:long\ name = "Deuterium" ;
float d_1s(time_1s) ;
d_1s:units = "permil" ;
d_1s:_FillValue = -999.99f ;
d_1s:long\ name = "Deuterium excess" ;
float q_1s(time_1s) ;
q_1s:units = "g kg-1" ;
q_1s:_FillValue = -999.99f ;
q_1s:long\ name = "Specific humidity" ;
double time_10s(time_10s) ;
time_10s:units = "days since 0001-01-01 00:00:00" ;
time_10s:long_name = "time_10s" ;
float delta_18O_10s(time_10s) ;
delta_18O_10s:units = "permil" ;
delta_18O_10s:_FillValue = -999.99f ;
delta_18O_10s:long\ name = "Oxygen-18" ;
float delta_D_10s(time_10s) ;
delta_D_10s:units = "permil" ;
delta_D_10s:missing_data = -999.99f ;
delta_D_10s:long\ name = "Deuterium" ;
float d_10s(time_10s) ;
d_10s:units = "permil" ;
d_10s:_FillValue = -999.99f ;
d_10s:long\ name = "Deuterium excess" ;
float q_10s(time_10s) ;
q_10s:units = "g kg-1" ;
q_10s:_FillValue = -999.99f ;
q_10s:long\ name = "Specific humidity" ;
float delta_18O_10s_SD(time_10s) ;
delta_18O_10s_SD:units = "permil" ;
delta_18O_10s_SD:_FillValue = -999.99f ;
delta_18O_10s_SD:long\ name = "standard deviation of Oxygen-18" ;
float delta_D_10s_SD(time_10s) ;
delta_D_10s_SD:units = "permil" ;
delta_D_10s_SD:_FillValue = -999.99f ;
delta_D_10s_SD:long\ name = "standard deviation of Deuterium" ;
float d_10s_SD(time_10s) ;
d_10s_SD:units = "permil" ;
d_10s_SD:_FillValue = -999.99f ;
d_10s_SD:long\ name = "standard deviation of Deuterium excess" ;
float q_10s_SD(time_10s) ;
q_10s_SD:units = "g kg-1" ;
q_10s_SD:long\ name = "standard deviation of specific humidity" ;
q_10s_SD:_FillValue = -999.99f ;
double time_1min(time_1min) ;
time_1min:units = "days since 0001-01-01 00:00:00" ;
time_1min:long_name = "time_1min" ;
float delta_18O_1min(time_1min) ;
delta_18O_1min:units = "permil" ;
delta_18O_1min:_FillValue = -999.99f ;
delta_18O_1min:long\ name = "Oxygen-18" ;
float delta_D_1min(time_1min) ;
delta_D_1min:units = "permil" ;
delta_D_1min:missing_data = -999.99f ;
delta_D_1min:long\ name = "Deuterium" ;
float d_1min(time_1min) ;
d_1min:units = "permil" ;
d_1min:_FillValue = -999.99f ;
d_1min:long\ name = "Deuterium excess" ;
float q_1min(time_1min) ;
q_1min:units = "g kg-1" ;
q_1min:_FillValue = -999.99f ;
q_1min:long\ name = "Specific humidity" ;
float delta_18O_1min_SD(time_1min) ;
delta_18O_1min_SD:units = "permil" ;
delta_18O_1min_SD:_FillValue = -999.99f ;
delta_18O_1min_SD:long\ name = "standard deviation of Oxygen-18" ;
float delta_D_1min_SD(time_1min) ;
delta_D_1min_SD:units = "permil" ;
delta_D_1min_SD:_FillValue = -999.99f ;
delta_D_1min_SD:long\ name = "standard deviation of Deuterium" ;
float d_1min_SD(time_1min) ;
d_1min_SD:units = "permil" ;
d_1min_SD:_FillValue = -999.99f ;
d_1min_SD:long\ name = "standard deviation of Deuterium excess" ;
float q_1min_SD(time_1min) ;
q_1min_SD:units = "g kg-1" ;
q_1min_SD:long\ name = "standard deviation of specific humidity" ;
q_1min_SD:_FillValue = -999.99f ;
double time_10min(time_10min) ;
time_10min:units = "days since 0001-01-01 00:00:00" ;
time_10min:long_name = "time_10min" ;
float delta_18O_10min(time_10min) ;
delta_18O_10min:units = "permil" ;
delta_18O_10min:_FillValue = -999.99f ;
delta_18O_10min:long\ name = "Oxygen-18" ;
float delta_D_10min(time_10min) ;
delta_D_10min:units = "permil" ;
delta_D_10min:missing_data = -999.99f ;
delta_D_10min:long\ name = "Deuterium" ;
float d_10min(time_10min) ;
d_10min:units = "permil" ;
d_10min:_FillValue = -999.99f ;
d_10min:long\ name = "Deuterium excess" ;
float q_10min(time_10min) ;
q_10min:units = "g kg-1" ;
q_10min:_FillValue = -999.99f ;
q_10min:long\ name = "Specific humidity" ;
float delta_18O_10min_SD(time_10min) ;
delta_18O_10min_SD:units = "permil" ;
delta_18O_10min_SD:_FillValue = -999.99f ;
delta_18O_10min_SD:long\ name = "standard deviation of Oxygen-18" ;
float delta_D_10min_SD(time_10min) ;
delta_D_10min_SD:units = "permil" ;
delta_D_10min_SD:_FillValue = -999.99f ;
delta_D_10min_SD:long\ name = "standard deviation of Deuterium" ;
float d_10min_SD(time_10min) ;
d_10min_SD:units = "permil" ;
d_10min_SD:_FillValue = -999.99f ;
d_10min_SD:long\ name = "standard deviation of Deuterium excess" ;
float q_10min_SD(time_10min) ;
q_10min_SD:units = "g kg-1" ;
q_10min_SD:long\ name = "standard deviation of specific humidity" ;
q_10min_SD:_FillValue = -999.99f ;
double time_1h(time_1h) ;
time_1h:units = "days since 0001-01-01 00:00:00" ;
time_1h:long_name = "time_1h" ;
float delta_18O_1h(time_1h) ;
delta_18O_1h:units = "permil" ;
delta_18O_1h:_FillValue = -999.99f ;
delta_18O_1h:long\ name = "Oxygen-18" ;
float delta_D_1h(time_1h) ;
delta_D_1h:units = "permil" ;
delta_D_1h:missing_data = -999.99f ;
delta_D_1h:long\ name = "Deuterium" ;
float d_1h(time_1h) ;
d_1h:units = "permil" ;
d_1h:_FillValue = -999.99f ;
d_1h:long\ name = "Deuterium excess" ;
float q_1h(time_1h) ;
q_1h:units = "g kg-1" ;
q_1h:_FillValue = -999.99f ;
q_1h:long\ name = "Specific humidity" ;
float delta_18O_1h_SD(time_1h) ;
delta_18O_1h_SD:units = "permil" ;
delta_18O_1h_SD:_FillValue = -999.99f ;
delta_18O_1h_SD:long\ name = "standard deviation of Oxygen-18" ;
float delta_D_1h_SD(time_1h) ;
delta_D_1h_SD:units = "permil" ;
delta_D_1h_SD:_FillValue = -999.99f ;
delta_D_1h_SD:long\ name = "standard deviation of Deuterium" ;
float d_1h_SD(time_1h) ;
d_1h_SD:units = "permil" ;
d_1h_SD:_FillValue = -999.99f ;
d_1h_SD:long\ name = "standard deviation of Deuterium excess" ;
float q_1h_SD(time_1h) ;
q_1h_SD:units = "g kg-1" ;
q_1h_SD:long\ name = "standard deviation of specific humidity" ;
q_1h_SD:_FillValue = -999.99f ;
</pre>

<h5>Instrument parameters</h5>

<pre style="background-color: Gainsboro">
float Tc_1s(time_1s) ;
Tc_1s:units = "deg C" ;
Tc_1s:_FillValue = -999.99f ;
Tc_1s:long\ name = "Cavity temperature" ;
float pc_1s(time_1s) ;
pc_1s:units = "Torr" ;
pc_1s:_FillValue = -999.99f ;
pc_1s:long\ name = "Cavity pressure" ;
float Twb_1s(time_1s) ;
Twb_1s:units = "deg C" ;
Twb_1s:_FillValue = -999.99f ;
Twb_1s:long\ name = "Warm box temperature" ;
float flag_1s(time_1s) ;
flag_1s:units = "1" ;
flag_1s:_FillValue = -999.99f ;
flag_1s:long\ name = "Quality flag" ;
</pre>

Rayleigh model

2021-01-26T20:26:40Z

Hso039:

The Rayleigh distillation model describes the evolution of a multiple-phase system in which one phase is continuously removed to the other phase through fractional distillation. Despite its simplicity, it is a powerful framework to describe in particular the isotopic enrichment or depletion as material moves between reservoirs in an equilibrium fractionation process.

== Model description ==

The system applying the Rayleigh equation is often an open system, from which the newly formed phase is immediately removed. For example, the evaporation of natural water bodies, and the formation of precipitation that immediately leaves the system, can be regarded as examples for open systems. However, with some modifications, Rayleigh models can be also applied to other systems. One such system is a closed system (or two-phase equilibrium model; Gat, (1996)), where the material removed from one reservoir accumulates in a second reservoir in such a manner that isotopic equilibrium is maintained between the two reservoirs. An example for this would be the condensation of vapour to droplets in a cloud, without formation and removal of precipitation.

The isotopic enrichment or depletion by the Rayleigh process for both open and closed systems can be mathematically obtained by different approaches (Fig. 1). The Rayleigh equations that are used to describe the isotopic evolution of the remaining reservoir under different conditions are summarized in Table 1. The isotope ratio of the accumulated removal can be derived using mass conservation of rare isotopes remaining in the reservoir, and the removed component:

<math> fR_\text{remain} + (1-f)R_\text{remove,acc} = R_0 </math>.

In the case of condensation involving both liquid and solid phases, the accumulation is a combination of the removed mass fraction of both phases. First, following the equation above, the total liquid removal is calculated as

<math> R_\text{l,acc} = (R_0-fR_v)/(1-f) </math>.

Then, we consider a separated Rayleigh process by only taking into account of the ongoing formation of the solid phase. Following the same reasoning as above, the isotope ratio of the accumulated solid removal is calculated by

<math> f_iR_\text{i,v} + (1-f_i)R_\text{i,acc} = R_\text{v0} </math>,

where <math>R_\text{v0}</math> and <math>R_\text{i,v}</math> are the isotope ratio of the remaining vapour at the start and the calculating point of the solid condensation stage, respectively, and <math>f_i</math> the fraction of remaining vapour within the solid condensation stage. Finally and again, using mass conservation of the rare isotopes, we obtain the isotope ratio of the total accumulation of the removal by <math> (1-ff_i)R_\text{acc} = (1-f)R_\text{l,acc} + f(1-f_i)R_\text{i,acc} </math>. Corresponding examples of the calculated isotopic evolution profiles are shown in Fig. 2.

[[File:Rayleigh_model_box_sketch_v2.png|thumb|800px|'''''Figure 1''''' Schematic presentation of the mathematical approaches of the Rayleigh model in open system '''(a, b)''' and closed system '''(c)'''. Adapted from Gat ''et al'' (2001). '''(a)''' From a reservoir containing ''N'' abundant isotopologues (e.g. H<sub>2</sub><sup>16</sup>O) and ''N<sub>i</sub>'' rare isotopologues (e.g. H<sub>2</sub><sup>18</sup>O or HD<sup>16</sup>O) small amounts of both species, ''dN'' and ''dN<sub>i</sub>'' respectively, are being removed under equilibrium fractionation conditions: <math> dN_i/dN = αR </math>.
'''(b)''' The changing isotopic composition of the reservoir is calculated from a mass balance consideration for the rare isotopologues: <math> RN = (R-dR)(N-dN) + αRdN </math>.
'''(c)''' In closed system, the changing isotopic composition of the reservoir can be calculated from a mass balance consideration for the rare isotopologues: <math> R_0N_0 = R(N_0-dN) + αRdN </math>, with the remaining fraction <math> f = (N_0-dN)/N_0 </math>.]]

[[File:Rayleigh_model_plot_v2_CG.png|thumb|800px|'''''Figure 2''''' Isotopic change during '''(a), (c)''' Rayleigh evaporation, and '''(b), (d)''' Rayleigh condensation. Rayleigh evaporation occurs here at 20 °C (thus a constant fractionation factor) for initial liquid compositions of δ<sup>18</sup>O = -10 ‰ and δD = -70 ‰ (''d'' = 10 ‰), in open system with unsaturated (RH = 75 %; black) or saturated (grey) environment, and closed system (blue). In addition, the result of C--G evaporation model (i.e. open system including feedback from a "free atmosphere" which has fixed isotope compositions of δ<sup>18</sup>O = -13 ‰ and δD = -94 ‰ (''d'' = 10 ‰) and a fixed relative humidity (RH = 75 %)) is also presented (red). Rayleigh condensation occurs here under continuous cooling (thus also a contentiously changing fractionation factor) from T = 20 °C and RH = 75 %. The initial vapour compositions are δ<sup>18</sup>O = -13 ‰ and δD = -94 ‰ (''d'' = 10 ‰). For the condensation to ice below 0 °C, two cases are presented. The saturation case (grey) is a classical Rayleigh process where ice crystals from from vapour under equilibrium conditions, using the saturation pressure over ice (''e<sub>i</sub>''). The supersaturation case (black) takes into account the supersaturation over ice, where the ambient vapour pressure is ''e<sub>v</sub> = S<sub>i</sub>*e<sub>i</sub>''. ''S<sub>i</sub>'' is the defined saturation ratio, as ''e<sub>v</sub>/e<sub>i</sub>'', and here takes the form ''S<sub>i</sub> = 1-0.004T'' after Risi ''et al'' (2010a). In this case, the fractionation factor combining equilibrium and kinetic effects given by Jouzel & Merlivat (1984) is used. The equations used in this figure can be found in Table 1.]]

{| class="wikitable"
|+ ''Table 1'' Rayleigh equations to calculate isotopic evolution of the remaining reservoir under different conditions. The transport resistance is here assumed to be purely due to diffusion (i.e. <math>\rho \propto D^{-1} </math>).
|-
! scope="col"|
! scope="col"| Conditions
! scope="col" colspan="2"| Equation (''R'' and ''δ'' notation)
! scope="col"| Fractionation factor used
|-
! scope="row" rowspan="4"| Evaporation
| open system saturated
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> α = \alpha_{vl}<1 </math>
|-
| open system undersaturated
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> \alpha = \frac{1}{\alpha_k \alpha_{lv}} </math>, where <math> \alpha_{lv}>1 </math>, and <math> \alpha_k = \frac{D}{D'}(1-h)+h > 1 </math>, with <math> h = \frac{e_v}{e_l} </math>
|-
| closed system
| <math> R = \frac{R_0}{f+\alpha(1-f)} </math>
| <math> \delta = \frac{1+\delta_0}{f+\alpha(1-f)}-1 </math>
| <math> α = \alpha_{vl}<1 </math>
|-
| C--G model
| <math> R = R_0f^{\alpha-1} </math>
| <math> \delta = (1+\delta_0)f^{\alpha-1}-1 </math>
| <math> \alpha = \frac{\alpha_{vl}-h\frac{R_a}{R_l}}{(1-h)\frac{D}{D'}} </math>, where <math> \alpha_{vl} < 1 </math>
|-
! scope="row" rowspan="2"| Condensation
| saturation over ice
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> α = \alpha_{sv}>1 </math>
|-
| supersaturation over ice
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> \alpha = \alpha_k \alpha_{sv} </math>, where <math> \alpha_{sv}>1 </math>, and <math> \alpha_k = \frac{S_i}{\alpha_s \frac{D}{D'}(S_i-1)+1} < 1 </math>, with <math> S_i = \frac{e_v}{e_i} </math>
|-
|}

----

== Model codes in MATLAB ==

=== Rayleigh evaporation ===

<pre>
% rayleigh_evaporation.m
%--------------------------------
% Description:
% simple Rayleigh evaporation model, after Stern and Blisniuk, 2002
%--------------------------------
% input variables: T0 (Kelvin), d18O0 (permil), d2H0 (permil);
% system: closed system = 0, open system = 1, C--G model = 2;
% optional: relative humidity (default = 1), d18Oa (permil), d2Ha (permil)
% run example: rayleigh_evaporation(20+273.15,-10,-70,1,0.75)
% rayleigh_evaporation(20+273.15,-10,-70,1)
% rayleigh_evaporation(20+273.15,-10,-70,2)
%--------------------------------
% HS, Do 12 Dez 2013 15:43:28 CET
% YW, structured and included the case of kinetic effect
% and the case of C--G model, 29 Aug 2020
%--------------------------------

function data = rayleigh_evaporation(T0,d18O0,d2H0,system,h,d18Oa,d2Ha)

% %% dubugging
% T0 = 20+273.15;
% d18O0 = -10; % close to Bergen precipitation average
% d2H0 = -70;
% system = 1;
% h = 0.75;

%% fractionation factors
%--------------------------------
% Majoube, M., 1971a: Fractionnement en oxyg`ene-18 entre la glace et la vapeur d’eau. J.
% Chim. Phys., 68, 625–636.

% Majoube, M., 1971b: Fractionnement en oxyg`ene 18 et deut ́erium entre l’eau et sa vapeur. J. Chim.
% Phys., 68, 1423–1436.

% Merlivat, L. and G. Nief, 1967: Fractionnement isotopique lors des changements d‘ ́etat
% solide-vapeur et liquide-vapeur de l’eau `a des temp ́eratures inf ́erieures a ` 0 ◦ C. Tellus,
% 19, 122–127.
%--------------------------------
function d = a2H(T) % T in K
d = 1/exp(24.844e3/(T^2)-76.248/T+52.612e-3); % Majoube 1971b, R_vapour/R_liquid < 1
end

function d = a18O(T) % T in K
d = 1/exp(1137/(T^2)-0.4156/T-0.0020667); % Majoube 1971b, R_vapour/R_liquid < 1
end

%% initialization
% isotope ratios of VSMOW reference water
R2std = 155.76e-6;
R18std = 2005.20e-6;
% initial isotope ratio
R18O0 = (d18O0/1000+1)*R18std;
R2H0 = (d2H0/1000+1)*R2std;
% relative humidity
if ~exist('h','var')
h = 1;
end
% isotope composition of "free atmosphere"
% if not existing, default it to the equilibrium vapour of global average precipitation
if ~exist('d18Oa','var')
d18Oa = -13;
end
if ~exist('d2Ha','var')
d2Ha = -94;
end
R18Oa = (d18Oa/1000+1)*R18std;
R2Ha = (d2Ha/1000+1)*R2std;

% % ouput variables
% data.T = [];
% data.f = [];
% data.d18Ov = [];
% data.d18Ol = [];
% data.d2Hv = [];
% data.d2Hl = [];
% data.dxsv = [];
% data.dxsl = [];
% data.d18Ov_acc = [];
% data.d2Hv_acc = [];
% data.dxsv_acc = [];

%% Rayleigh evaporation process: (0) in closed system (material maintained under two-phase equilibrium)
% i.e., the material removed stays in the closed system and stays in equilibrium with the reservoir
if system == 0
fprintf('Rayleigh evaporation process: in an closed system (material maintained under two-phase equilibrium) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
i = 1; % iteration steps
for f = 1:-0.02:0 % remaining liquid fraction
% isotope ratio of remaining liquid
R18Ol = R18O0/(a18O(T0) - f*(a18O(T0)-1)); % Gat1996
R2Hl = R2H0/(a2H(T0) - f*(a2H(T0)-1)); % Gat1996
% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*a18O(T0)-1)*1000;
d2Hv = ((d2Hl/1000+1)*a2H(T0)-1)*1000;
dxsv = d2Hv-8*d18Ov;
% (3) delta value of the accumulated removed vapour
d18Ov_acc = d18Ov;
d2Hv_acc = d2Hv;
dxsv_acc = dxsv;

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;
end
end

%% Rayleigh evaporation process: (1) in an open system (material is immediately removed)
if system == 1
fprintf('Rayleigh evaporation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
i = 1; % iteration steps
n = 1; % turbulent exponent in D^n, [0 1], controls the ratio of diffusive transport over turbulent transport of water molecules (Pfahl and Wernli, 2009)
for f = 1:-0.02:0 % remaining liquid fraction

% modified Rayleigh evaporation model including kinectic effct
% during the vapour formation at undersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
D18 = 0.9723; % D'/D
D2 = 0.9755; % D'/D
ak_18O = 1/(1/D18^n*(1-h)+h);
ak_2H = 1/(1/D2^n*(1-h)+h);
aeff_18O = a18O(T0) * ak_18O;
aeff_2H = a2H(T0) * ak_2H;

% isotope ratio of remaining liquid
R18Ol = R18O0*f^(aeff_18O-1);
R2Hl = R2H0*f^(aeff_2H-1);
% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*aeff_18O-1)*1000;
d2Hv = ((d2Hl/1000+1)*aeff_2H-1)*1000;
dxsv = d2Hv-8*d18Ov;

% (3) isotope ratio of the accumulated removed vapour
R18Ov_acc = R18O0*(1-f^aeff_18O)/(1-f); % Mook 2001, Page 38
R2Hv_acc = R2H0*(1-f^aeff_2H)/(1-f);
% delta value of the accumulated removed vapour
d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
dxsv_acc = d2Hv_acc-8*d18Ov_acc;
% % (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% % mass conservation of rare isotopes between the reservoir and formed removal: f*Rl+(1-f)*Rv_acc=R0,
% % after rearranging, we have: Rv_acc=(R0-f*Rl)/(1-f)
% R18Ov_acc2 = (R18O0-f*R18Ol)/(1-f);
% R2Hv_acc2 = (R2H0-f*R2Hl)/(1-f);
% data.d18Ov_acc2(i) = (R18Ov_acc2/R18std-1)*1000;
% data.d2Hv_acc2(i) = (R2Hv_acc2/R2std-1)*1000;
% data.dxsv_acc2(i) = data.d2Hv_acc2(i)-8*data.d18Ov_acc2(i);

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;
end
end

%% Rayleigh evaporation process: (2) in a "free atmosphere" of fixed humidity and isotope composition (C--G model)
if system == 2
fprintf('Rayleigh evaporation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
% turbulent exponent in D^n, [0 1], controls the ratio of diffusive transport over turbulent transport of water molecules (Pfahl and Wernli, 2009)
% n~0.5 for an open water body under natural conditions, n~0.58 for a falling raindrop (Stewart1975), n~1 for soils and leaves
n = 1;
df = 0.02;
i = 1; % iteration steps

for f = 1:-df:0 % remaining liquid fraction

% modified Rayleigh evaporation model including kinectic effct
% during the vapour formation at undersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
D18 = 0.9723; % D'/D
D2 = 0.9755; % D'/D
if i==1
aeff_18O = (a18O(T0) - h*R18Oa/R18O0) / ((1-h)*1/D18^n);
aeff_2H = (a2H(T0) - h*R2Ha/R2H0) / ((1-h)*1/D2^n);
% isotope ratio of remaining liquid
f1 = 1;
R18Ol = R18O0*f1^(aeff_18O-1);
R2Hl = R2H0*f1^(aeff_2H-1);
else
aeff_18O = (a18O(T0) - h*R18Oa/data.R18Ol(i-1)) / ((1-h)*1/D18^n);
aeff_2H = (a2H(T0) - h*R2Ha/data.R2Hl(i-1)) / ((1-h)*1/D2^n);
% isotope ratio of remaining liquid
f1 = 1-df; % fraction remaining relative to previous stage
R18Ol = data.R18Ol(i-1)*f1^(aeff_18O-1);
R2Hl = data.R2Hl(i-1)*f1^(aeff_2H-1);
end

% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*aeff_18O-1)*1000;
d2Hv = ((d2Hl/1000+1)*aeff_2H-1)*1000;
dxsv = d2Hv-8*d18Ov;

% % (3) isotope ratio of the accumulated removed vapour
% R18Ov_acc = R18O0*(1-f^aeff_18O)/(1-f); % Mook 2001, Page 38
% R2Hv_acc = R2H0*(1-f^aeff_2H)/(1-f);
% % delta value of the accumulated removed vapour
% d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
% d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
% dxsv_acc = d2Hv_acc-8*d18Ov_acc;
% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% mass conservation of rare isotopes between the reservoir and formed removal: f*Rl+(1-f)*Rv_acc=R0,
% after rearranging, we have: Rv_acc=(R0-f*Rl)/(1-f)
R18Ov_acc = (R18O0-f*R18Ol)/(1-f);
R2Hv_acc = (R2H0-f*R2Hl)/(1-f);
% delta value of the accumulated removed vapour
d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
dxsv_acc = d2Hv_acc-8*d18Ov_acc;

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;

end
end

end
% fin
</pre>

=== Rayleigh condensation ===

<pre>
% rayleigh_condensation.m
%--------------------------------
% Description:
% - simple Rayleigh condensation model, after Stern and Blisniuk, 2002
% - temperature dependent fractionation factor varies at each step during cooling process
% (1) isobaric cooling: e.g., air parcel advects to cold regions
% (2) or pseudoadiabatic cooling: e.g., updraft or lift of surface air parcel
% - therefore, the isotope ratio is calculated as: R(n+1) = R(n)(q(n+1)/q(n))^(a-1)
%--------------------------------
% input variables: T0 (Kelvin), RH0 (%), d18O0 (permil), d2H0 (permil),
% sice: saturation conditions over ice when temperature <0 degree
% > 1: using the constant supersaturation given as sice;
% = 1: meaning alpha_k = 1, thus no supersaturation;
% = 0: using formula Si = 1-0.004*T (in Celsius)
% run example: rayleigh_condensation(20+273.15,0.75,-13,-94,0)
% rayleigh_condensation(20+273.15,0.75,-13,-94,1)
% rayleigh_condensation(20+273.15,0.75,-13,-94,1.2)
%--------------------------------
% HS, Do 12 Dez 2013 15:43:28 CET
% YW, structured and included kinetic effect, 29 Aug 2020
%--------------------------------
% YW, 26 Mar 2020
% limitation:
% Rayleigh condensation model only reflects the process of water vapor removing
% and ignores: mixing of air masses, cloud water-vapor isotope exchange,
% subcloud droplet evaporation, and radiative cooling or heating.
%--------------------------------

function data = rayleigh_condensation(T0,RH0,d18O0,d2H0,sice)

% %% for debugging
% T0 = 20+273.15;
% RH0 = 0.75; % Craig-Gordon, 1965 (Fig. 15)
% d18O0 = -13;
% d2H0 = -94;
% sice = 0;

% RH0 = 0.91; % 20161207 AR event at Bergen
% d18O0 = -12.5;
% d2H0 = -100;

%% functions adopted
% fractionation factors
%--------------------------------
% Majoube, M., 1971a: Fractionnement en oxyg`ene-18 entre la glace et la vapeur d’eau. J.
% Chim. Phys., 68, 625–636.

% Majoube, M., 1971b: Fractionnement en oxyg`ene 18 et deut ́erium entre l’eau et sa vapeur. J. Chim.
% Phys., 68, 1423–1436.

% Merlivat, L. and G. Nief, 1967: Fractionnement isotopique lors des changements d‘ ́etat
% solide-vapeur et liquide-vapeur de l’eau `a des temp ́eratures inf ́erieures a ` 0 °C. Tellus,
% 19, 122–127.
%--------------------------------
function d = a2H(T) % T in Kelvin
if T >= 273.15 % above 0 celsius
d = exp(24.844e3/(T^2)-76.248/T+52.612e-3); % Majoube 1971b, R_liquid/R_vapour > 1
else
d = exp(16289./T.^2 - 0.0945); % Merlivat & Nief 1967, R_solid/R_vapour > 1
end
end

function d = a18O(T) % T in Kelvin
if T >= 273.15 % above 0 celsius
d = exp(1137/(T^2)-0.4156/T-0.0020667); % Majoube 1971b, R_liquid/R_vapour > 1
else
d = exp(11.839./T - 0.028224); % Majoube 1971a, R_solid/R_vapour > 1
end
end

% supersaturation with respect to ice
% Si = 1 − λT, with λ = 0.004. From Graf 2017 dissertation, page 53, Fig 3.1
% (as in Risi et al., 2010b, after Jouzel and Merlivat 1984.)
% Risi, C., S. Bony, F. Vimeux, and J. Jouzel, 2010b: Water-stable isotopes in the LMDZ4
% general circulation model: Model evaluation for present-day and past climates and
% applications to climatic interpretations of tropical isotopic records.
% sice: > 1: using the constant supersaturation given here;
% = 1: meaning alpha_k = 1, thus no supersaturation;
% = 0: using formula Si = 1-0.004*T (in Celsius)
function s = si(T)
if sice >= 1
s = sice;
else % elseif sice == 0
s = 1-0.004*(T-273.15);
end
end

% vapour saturation pressure
function es = esat(T) % T in Kelvin
if T >= 273.15
% es = 611*exp((17.27*T)/(273+T)); % T in celsius
es = 611*exp(17.27*(T-273.15)/T); % T in Kelvin
else
% Saturation vapour pressure over ice (Murphy and Koop, 2005) for T > 110 K:
es_ice = exp(9.550426 - 5723.265/T + 3.53068*log(T) - 0.00728332*T);
% the actual saturation vapour pressure
es = es_ice * si(T);
end
end

% saturated vapour mixing ratio
function ws = wsat(es,p)
ws = 0.622*es/(p-es);
end

% pressure at height of z
function p = pressure(z)
p0 = 101325; % Pa
z0 = 8000; % m scale height
p = p0*exp(-z/z0);
end

% moist adiabatic lapse rate [Curry and Webster,1999] (cited after Stern and Blisniuk, 2002)
function lr = gamma(ws,T) % T in Kelvin
% physical constants
g = 9.80665; % m/s^2 the gravitational acceleration
Cpd = 1.00464e3; % J/kg/K the specific heat capacity of dry air at constant pressure
L = 2.5104e6; % J/kg the latent heat of vaporization or sublimation
Rd = 287.04; % J/kg/K the specific gas constant for dry air
lr = g/Cpd*(1+L*ws/Rd/T)/(1+0.622*L*L*ws/Rd/Cpd/T/T); % [°C/m]
end

%% initialization
% isotope ratios of VSMOW reference water
R2std = 155.76e-6;
R18std = 2005.20e-6;
% initial isotope ratio
R18O0 = (d18O0/1000+1)*R18std;
R2H0 = (d2H0/1000+1)*R2std;
dxs0 = R2H0-8*R18O0;

% initial conditions
f = 1.0; % remaining vapour fractionation
z = 0.0; % elevation
p = pressure(z);
w0 = RH0*wsat(esat(T0),p); % kg/kg
% convert water mixing ratio unit
md = 28.97; % [g/mol] dry air molar mass
mv = 18.02; % [g/mol] water vapour molar mass
wconc0 = w0*md/mv*1e6; % [kg/kg] --> [ppmv]
rh = RH0;
dt = 0.5; % temperature step
T = T0+dt;

%% for the circumstance of isobaric cooling
%% (1) cool to saturation
fprintf('Rayleigh condensation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' T (°C) d18Ov d2Hv dxsv rh f WConc[ppmv] \n');
n = 1; % iteration number
while rh < 0.99
T = T-dt; % decrease temperature by dt °C at each iteration
ws = wsat(esat(T),p); % saturated water mixing ratio at each iteration
rh = w0/ws; % RH at each iteration
wconc = wconc0; % [kg/kg] --> [ppmv]

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18O0,d2H0,dxs0,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18O0;
data.R2H(n) = R2H0;
data.d18O(n) = d18O0;
data.dD(n) = d2H0;
data.dxs(n) = d2H0-8*d18O0;
data.d18Oc(n) = NaN; % condensate
data.d2Hc(n) = NaN;
data.dxsc(n) = NaN;
data.d18O_acc(n) = NaN; % accumulated condensate (liquid+solid)
data.d2H_acc(n) = NaN;
data.dxs_acc(n) = NaN;

% iterate to next step
n = n+1;
end

fprintf('Reached saturation now\n');

ws0 = w0;

%% (2) continue to cool and form liquid condensate
while T > 273.15 % isobaric cooling with condensation to 0 °C
T = T-dt; % decrease temperature by dt °C at each iteration
ws = wsat(esat(T),p); % saturated water mixing ratio at each iteration
wconc = ws*md/mv*1e6; % [kg/kg] --> [ppmv]
f = ws/ws0;

if n == 1
f1 = ws/ws0;
% isotope ratio of remaining vapour
R18Ov = R18O0*f1^(a18O(T)-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = R2H0*f1^(a2H(T)-1);
else
f1 = wconc/data.Wconc(n-1); % q(n)/q(n-1)
% isotope ratio of remaining vapour
R18Ov = data.R18O(n-1)*f1^(a18O(T)-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = data.R2H(n-1)*f1^(a2H(T)-1);
end

% (1) delta value of remaining vapour
d18Ov = (R18Ov/R18std-1)*1000;
d2Hv = (R2Hv/R2std-1)*1000;
dxsv = d2Hv - 8*d18Ov;

% (2) delta value of the instantaneously removed condensate (in equilibrium with the current remaining vapour)
d18Oc = ((d18Ov/1000+1)*a18O(T)-1)*1000;
d2Hc = ((d2Hv/1000+1)*a2H(T)-1)*1000;
dxsc = d2Hc-8*d18Oc;

% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% mass conservation of rare isotopes between the reservoir and formed removal: f*Rv + (1-f)*Rl_acc = R0,
% after rearranging, we have: Rl_acc = (R0-f*Rv)/(1-f)
R18Ol_acc = (R18O0-f*R18Ov)/(1-f);
R2Hl_acc = (R2H0-f*R2Hv)/(1-f);
d18Ol_acc = (R18Ol_acc/R18std-1)*1000;
d2Hl_acc = (R2Hl_acc/R2std-1)*1000;
dxsl_acc = d2Hl_acc-8*d18Ol_acc;

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18Ov,d2Hv,dxsv,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18Ov;
data.R2H(n) = R2Hv;
data.d18O(n) = d18Ov;
data.dD(n) = d2Hv;
data.dxs(n) = dxsv;
data.rh(n) = rh;
data.d18Oc(n) = d18Oc;
data.d2Hc(n) = d2Hc;
data.dxsc(n) = dxsc;
data.d18O_acc(n) = d18Ol_acc;
data.d2H_acc(n) = d2Hl_acc;
data.dxs_acc(n) = dxsl_acc;

% iterate to next step
n = n+1;
end

fprintf('Have cooled to 0 celcius now \n');

ws0_ice = ws;
R18O0 = R18Ov;
R2H0 = R2Hv;
f0 = f;

%% (3) continue to cool and form solid condensate
% considering mixed-phase cloud: subsaturated over liquid droplets and supersaturated over ice crystals

% closure assumption: liquid droplets --> evaporate to vapour --> deposite on ice crystals
% therefore: when T<0 celsius, the reduced fraction of vapour is due to its deposit on ice crystals with a fractionation
% factor alpha_eff = alpha_eq*alpha_k taking into account the kinetic effct under the supersaturation condition.
% i.e.: we start a new Rayleigh condensation model starting with the remaining vapour
% after the liquid condensation stage above, and use the new factionation factor alpha_eff

while T > -60+273.15
T = T-dt;
ws = wsat(esat(T),p);
wconc = ws*md/mv*1e6; % [kg/kg] --> [ppmv]
f = ws/ws0; % the total fraction of remaining vapour through all stages
fi = ws/ws0_ice; % the fraction of remaing vapour in the ice condensation stage only

% modified Rayleigh condensation model including kinectic effct
% during the ice formation at supersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
ak_18O = si(T)/(a18O(T)*1/0.9723*(si(T)-1) + 1);
ak_2H = si(T)/(a2H(T)*1/0.9755*(si(T)-1) + 1);
aeff_18O = a18O(T) * ak_18O;
aeff_2H = a2H(T) * ak_2H;

if n == 1
f1 = ws/ws0;
% isotope ratio of remaining vapour
R18Ov = R18O0*f1^(aeff_18O-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = R2H0*f1^(aeff_2H-1);
else
f1 = wconc/data.Wconc(n-1); % q(n)/q(n-1)
% isotope ratio of remaining vapour
R18Ov = data.R18O(n-1)*f1^(aeff_18O-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1), and Jouzel and Merlivat, 1984
R2Hv = data.R2H(n-1)*f1^(aeff_2H-1);
end

% (1) delta value of remaining vapour
d18Ov = (R18Ov/R18std-1)*1000;
d2Hv = (R2Hv/R2std-1)*1000;
dxsv = d2Hv - 8*d18Ov;

% (2) delta value of the instantaneously removed condensate (in equilibrium with the current remaining vapour)
d18Oc = ((d18Ov/1000+1)*aeff_18O-1)*1000;
d2Hc = ((d2Hv/1000+1)*aeff_2H-1)*1000;
dxsc = d2Hc-8*d18Oc;

% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% (i) mass conservation of rare isotopes between the reservoir and formed removal:
% fi*Rv + (1-fi)*Ri_acc = Rv0,
% where fi is the fraction of remaining vapour in the ice condensation stage, and
% Rv0 is the isotope ratio of the remaining vapour after liquid condensation stage
% after rearranging, we have: Ri_acc = (Rv0-fi*Rv)/(1-fi)
R18Oi_acc = (R18O0-fi*R18Ov)/(1-fi);
R2Hi_acc = (R2H0-fi*R2H0)/(1-fi);
% d18Oi_acc = (R18Oi_acc/R18std-1)*1000;
% d2Hi_acc = (R2Hi_acc/R2std-1)*1000;
% dxsi_acc = d2Hi_acc-8*d18Oi_acc;
% (ii) the total accumulation is sum of the liquid (1-f0) and solid condensate (f0*(1-fi))
% (1-f0*fi)*R_acc = (1-f0)*Rl_acc + (f0*(1-fi))*Ri_acc
R18O_acc = ((1-f0)*R18Ol_acc + (f0*(1-fi))*R18Oi_acc)/(1-f0*fi);
R2H_acc = ((1-f0)*R2Hl_acc + (f0*(1-fi))*R2Hi_acc)/(1-f0*fi);
d18O_acc = (R18O_acc/R18std-1)*1000;
d2H_acc = (R2H_acc/R2std-1)*1000;
dxs_acc = d2H_acc-8*d18O_acc;

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18Ov,d2Hv,dxsv,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18Ov;
data.R2H(n) = R2Hv;
data.d18O(n) = d18Ov;
data.dD(n) = d2Hv;
data.dxs(n) = dxsv;
data.rh(n) = rh;
data.d18Oc(n) = d18Oc;
data.d2Hc(n) = d2Hc;
data.dxsc(n) = dxsc;
data.d18O_acc(n) = d18O_acc;
data.d2H_acc(n) = d2H_acc;
data.dxs_acc(n) = dxs_acc;

% iterate to next step
n = n+1;
end

%% for the circumstance of pseudoadiabatic cooling
% - establish the relationship between T and z
z = 0;
p = pressure(z);
n = 1;
for T = T0:-dt:-60+273.15
data.T(n) = T;
data.z(n) = z;
data.p(n) = p;
% the elevation change
ws = wsat(esat(T),p);
lr = gamma(ws,T); % lapse rate
dz = dt/lr; % dt = lr*dz
% the new elevation and pressure
z = z+dz;
p = pressure(z);
data.lr(n) = lr;

% iterate to next step
n = n+1;
end

end
% fin
</pre>

== Example of usage ==

'''1. Generate the desired data sets'''

<pre>
%% create data sets
% Rayleigh evaporation
T0 = 20+273.15;
d18O0 = -10; % close to Bergen precipitation average
d2H0 = -70;
h = 0.75; % relative humidity
de_ok = rayleigh_evaporation(T0,d18O0,d2H0,1,h); % in an open system, unsaturated (including kinetic effect)
de_oe = rayleigh_evaporation(T0,d18O0,d2H0,1); % in an open system, saturated (equilibrium)
de_cl = rayleigh_evaporation(T0,d18O0,d2H0,0); % in a closed system
de_CG = rayleigh_evaporation(T0,d18O0,d2H0,2,h); % C--G model

% Rayleigh condensation
T0 = 20+273.15;
RH0 = 0.75; % Craig-Gordon, 1965 (Fig. 15)
d18O0 = -13;
d2H0 = -94;
% > 1: using the constant supersaturation given as sice;
% = 1:
% = 0:
dc_ln = rayleigh_condensation(T0,RH0,d18O0,d2H0,0); % using linear formula Si = 1-0.004*T (in Celsius)
dc_no = rayleigh_condensation(T0,RH0,d18O0,d2H0,1); % meaning alpha_k = 1, thus no supersaturation, e = e_ice
dc_11 = rayleigh_condensation(T0,RH0,d18O0,d2H0,1.1); % using the constant supersaturation as given
</pre>

'''2. Plot Rayleigh evaporation and condensation profiles.'''

As an example, Fig. 2 is created using the data sets generated from the above step and using the plotting codes from below.

<pre>
%% plot Rayleigh evaporation and condensation model
fs = 14;

clear h
figure
set(gcf,'color','white','position',[0 0 1200 1150],'PaperPositionMode','auto');
% left_color = [0 0 0]; % black
% right_color = [0 0.4470 0.7410]; % blueish % blue [0 0 1];
% set(gcf,'defaultAxesColorOrder',[left_color; right_color]);

% Rayleigh evaporation
h(1) = subplot(2,2,1);
% set(h(1),'Position', [0.1 0.56 0.38 0.38]);
hold on
pe(1) = plot(de_ok.f,de_ok.d18Ol,'k-','linewidth',2);
pe(2) = plot(de_ok.f,de_ok.d18Ov,'k--','linewidth',2);
pe(3) = plot(de_ok.f,de_ok.d18Ov_acc,'k:','linewidth',2);
pe(4) = plot(de_oe.f,de_oe.d18Ol,'-','color',[0.6 0.6 0.6],'linewidth',2); %'color',[0.3010 0.7450 0.9330],
pe(5) = plot(de_oe.f,de_oe.d18Ov,'--','color',[0.6 0.6 0.6],'linewidth',2);
pe(6) = plot(de_oe.f,de_oe.d18Ov_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
pe(7) = plot(de_cl.f,de_cl.d18Ol,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(8) = plot(de_cl.f,de_cl.d18Ov,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(9) = plot(de_cl.f,de_cl.d18Ov_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(10) = plot(de_CG.f,de_CG.d18Ol,'-','color',[0.8500 0.3250 0.0980],'linewidth',2);
pe(11) = plot(de_CG.f,de_CG.d18Ov,'--','color',[0.8500 0.3250 0.0980],'linewidth',2);
pe(12) = plot(de_CG.f,de_CG.d18Ov_acc,':','color',[0.8500 0.3250 0.0980],'linewidth',2);
ylim(h(1),[-30 40]);
xlabel('Residual water fraction','fontsize',fs);
ylabel(['\delta^{18}O / ',char(8240)],'fontsize',fs);
lgd1 = legend(h(1),pe(1:3),'residual water','instant vapour','total vapour removed','Location','northwest');
lgd1_pos = lgd1.Position;
lgd1.FontSize = fs;
% lgd1.Visible = 'off';
% 2nd axes
a2 = axes('position',get(h(1),'position'),'visible','off'); % create the same axes but set it invisible
% lgd2 = legend(a2,pe(4:6),'residual water','instant vapour','total vapour removed','Location','northwest');
% lgd2.FontSize = fs;
lgd2 = legend(a2,pe(4:6),'','','','location','northwest','box','off');
lgd2_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.58 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd2,'box','off','Position',lgd2_pos);
% 3rd axes
a3 = axes('position',get(gca,'position'),'visible','off'); % create the same axes but set it invisible
lgd3 = legend(a3,pe(7:9),'','','','location','northwest','box','off');
lgd3_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.79 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd3,'box','off','Position',lgd3_pos);
% % 4th axes
a4 = axes('position',get(gca,'position'),'visible','off'); % create the same axes but set it invisible
lgd4 = legend(a4,pe(10:12),'','','','location','northwest','box','off');
lgd4_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.88 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd4,'box','off','Position',lgd4_pos);
% add text
text(h(1),0.41,8.5,'open','FontSize',fs,'Rotation',30)
text(h(1),0.30,13.2,'(unsaturated)','FontSize',fs,'Rotation',53)
text(h(1),0.60,-3,'open','FontSize',fs,'Rotation',15,'color',[0.6 0.6 0.6])
text(h(1),0.48,-0.5,'(saturated)','FontSize',fs,'Rotation',20,'color',[0.6 0.6 0.6])
text(h(1),0.75,-10,'closed','FontSize',fs,'Rotation',7,'Color',[0.3010 0.7450 0.9330])
text(h(1),0.8,1.5,'C-G model','color',[0.8500 0.3250 0.0980],'FontSize',fs,'Rotation',15)

h(3) = subplot(2,2,3);
% set(h(3),'Position', [0.1 0.1 0.38 0.38]);
hold on
plot(de_ok.f,de_ok.dxsl,'k-','linewidth',2)
plot(de_ok.f,de_ok.dxsv,'k--','linewidth',2)
plot(de_ok.f,de_ok.dxsv_acc,'k:','linewidth',2)
plot(de_oe.f,de_oe.dxsl,'-','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_oe.f,de_oe.dxsv,'--','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_oe.f,de_oe.dxsv_acc,':','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_cl.f,de_cl.dxsl,'-','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_cl.f,de_cl.dxsv,'--','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_cl.f,de_cl.dxsv_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_CG.f,de_CG.dxsl,'-','color',[0.8500 0.3250 0.0980],'linewidth',2)
plot(de_CG.f,de_CG.dxsv,'--','color',[0.8500 0.3250 0.0980],'linewidth',2)
plot(de_CG.f,de_CG.dxsv_acc,':','color',[0.8500 0.3250 0.0980],'linewidth',2)
ylim(h(3),[-60 70]);
set(h(3),'ytick',-60:20:65);
xlabel('Residual water fraction','fontsize',fs);
ylabel(['\itd / ',char(8240)],'fontsize',fs);

% Rayleigh condensation
h(4) = subplot(2,2,4);
% set(h(4),'Position', [0.56 0.1 0.38 0.38]);
hold on
pc(4) = plot(dc_no.Wconc,dc_no.dxsc,'-','color',[0.6 0.6 0.6],'linewidth',2);
pc(5) = plot(dc_no.Wconc,dc_no.dxs,'--','color',[0.6 0.6 0.6],'linewidth',2);
pc(6) = plot(dc_no.Wconc,dc_no.dxs_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
ylim(gca,[-20 50]);
xlabel('Water mixing ratio / ppmv','fontsize',fs);
set(gca,'XTick',2000:3000:16000);
ylabel(['\itd / ',char(8240)],'fontsize',fs);
% 2nd axis
ax1_pos = get(gca,'position'); % position of first axes
axes('Position',ax1_pos,'XAxisLocation','top','YAxisLocation','right','Color','none','YTickLabel','','FontSize',fs,'TickDir','out');
hold on
pc(1) = plot(dc_ln.f,dc_ln.dxsc,'k-','linewidth',2); % [0.3010 0.7450 0.9330]
pc(2) = plot(dc_ln.f,dc_ln.dxs,'k--','linewidth',2);
pc(3) = plot(dc_ln.f,dc_ln.dxs_acc,'k:','linewidth',2);
% pc(7) = plot(dc_11.f,dc_11.dxsc,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(8) = plot(dc_11.f,dc_11.dxs,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(9) = plot(dc_11.f,dc_11.dxs_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
ylim(gca,[-20 50]);
xlabel('Residual vapour fraction','fontsize',fs);
% 3rd axis
axes('Position',ax1_pos+[0 0 0 -ax1_pos(4)],'XAxisLocation','top','YColor','w','YTick',[],'Color','none','TickDir','out','FontSize',fs);
hold on
pc(7) = plot(dc_ln.Wconc,20*ones(size(dc_ln.Wconc)),'k-'); % [0.3010 0.7450 0.9330]
ylim(gca,[-20 50]);
xlabel('T / °C','fontsize',fs);
set(gca,'XTick',[dc_ln.Wconc(81) dc_ln.Wconc(61:-10:11)],'XTickLabel',[-20 -10:5:15])

h(2) = subplot(2,2,2);
% set(h(2),'Position', [0.56 0.56 0.38 0.38]);
hold on
pc(4) = plot(dc_no.Wconc,dc_no.d18Oc,'-','color',[0.6 0.6 0.6],'linewidth',2); % [0 0.4470 0.7410]
pc(5) = plot(dc_no.Wconc,dc_no.d18O,'--','color',[0.6 0.6 0.6],'linewidth',2);
pc(6) = plot(dc_no.Wconc,dc_no.d18O_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
ylim(h(2),[-60 -2]);
xlabel('Water mixing ratio / ppmv','fontsize',fs);
set(gca,'XTick',2000:3000:16000);
ylabel(['\delta^{18}O / ',char(8240)],'fontsize',fs);
% 2nd axis
ax1_pos = get(gca,'position'); % position of first axes
axes('Position',ax1_pos,'XAxisLocation','top','YAxisLocation','right','Color','none','YTickLabel','','FontSize',fs,'TickDir','out');
hold on
pc(1) = plot(dc_ln.f,dc_ln.d18Oc,'k-','linewidth',2); % [0.3010 0.7450 0.9330]
pc(2) = plot(dc_ln.f,dc_ln.d18O,'k--','linewidth',2);
pc(3) = plot(dc_ln.f,dc_ln.d18O_acc,'k:','linewidth',2);
% pc(7) = plot(dc_11.f,dc_11.d18Oc,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(8) = plot(dc_11.f,dc_11.d18O,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(9) = plot(dc_11.f,dc_11.d18O_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
ylim(gca,[-60 -2]);
xlabel('Residual vapour fraction','fontsize',fs);
lg = legend(h(2),pc(1:3),'instant liquid/ice','residual vapour','total liquid/ice removed');
% lg = legend(h(2),pc(4:6),'instant liquid/ice','residual vapour','total liquid/ice removed');
set(lg,'Position',[0.69 0.66 0.20 0.06],'FontSize',fs);
lg_pos = lg.Position;
% 3rd axis
axes('Position',ax1_pos+[0 -ax1_pos(4)*0.2 0 -ax1_pos(4)*0.8],'XAxisLocation','top','YColor','w','YTick',[],'Color','none');
hold on
pc(7) = plot(dc_ln.Wconc,-2+zeros(size(dc_ln.d18Oc)),'k-'); % [0.3010 0.7450 0.9330]
ylim(gca,[-60 -2]);
xlabel('T / °C','fontsize',fs);
set(gca,'XTick',[dc_ln.Wconc(81) dc_ln.Wconc(61:-10:11)],'XTickLabel',[-20 -10:5:15],'FontSize',fs,'TickDir','out');
lg2 = legend(gca,pc(4:6),'','','','location','east','box','off');
lg2_pos = lg_pos+[-lg_pos(3)*0.405 +lg_pos(4)*0.02 0 lg_pos(4)*0.117]; % move the 2nd legend to the desired position
set(lg2,'box','off','Position',lg2_pos);
% add text
text(h(2),1300,-36,'super','FontSize',fs,'Rotation',65)
text(h(2),2150,-27.5,'saturation','FontSize',fs,'Rotation',50)
text(h(2),1200,-25,'saturation','FontSize',fs,'Rotation',50,'Color',0.6*[1 1 1])

set([h(1) h(3)],'XDir','reverse','box','on');
set(h(:),'color','none','FontSize',fs,'tickdir','out'); % ,'YAxisLocation','left','ticklength',[0 0],'ygrid','on','xgrid','on'

annotation('textbox',[0.05 0.96 0.02 0.02],'String','(a)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.49 0.96 0.02 0.02],'String','(b)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.05 0.48 0.02 0.02],'String','(c)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.49 0.48 0.02 0.02],'String','(d)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');

% print('-depsc','-r300','/scratch/home/figs/thesis/Rayleigh_model_plot');
% print('-dpng','-r300','/scratch/home/figs/thesis/Rayleigh_model_plot');
</pre>

Rayleigh model

2021-01-26T20:25:44Z

Hso039:

The Rayleigh distillation model describes the evolution of a multiple-phase system in which one phase is continuously removed to the other phase through fractional distillation. Despite its simplicity, it is a powerful framework to describe in particular the isotopic enrichment or depletion as material moves between reservoirs in an equilibrium fractionation process.

== Model description ==

The system applying the Rayleigh equation is often an open system, from which the newly formed phase is immediately removed. For example, the evaporation of natural water bodies, and the formation of precipitation that immediately leaves the system, can be regarded as examples for open systems. However, with some modifications, Rayleigh models can be also applied to other systems. One such system is a closed system (or two-phase equilibrium model; Gat, (1996)), where the material removed from one reservoir accumulates in a second reservoir in such a manner that isotopic equilibrium is maintained between the two reservoirs. An example for this would be the condensation of vapour to droplets in a cloud, without formation and removal of precipitation.

The isotopic enrichment or depletion by the Rayleigh process for both open and closed systems can be mathematically obtained by different approaches (Fig. 1). The Rayleigh equations that are used to describe the isotopic evolution of the remaining reservoir under different conditions are summarized in Table 1. The isotope ratio of the accumulated removal can be derived using mass conservation of rare isotopes remaining in the reservoir, and the removed component:

<math> fR_\text{remain} + (1-f)R_\text{remove,acc} = R_0 </math>.

In the case of condensation involving both liquid and solid phases, the accumulation is a combination of the removed mass fraction of both phases. First, following the equation above, the total liquid removal is calculated as

<math> R_\text{l,acc} = (R_0-fR_v)/(1-f) </math>.

Then, we consider a separated Rayleigh process by only taking into account of the ongoing formation of the solid phase. Following the same reasoning as above, the isotope ratio of the accumulated solid removal is calculated by

<math> f_iR_\text{i,v} + (1-f_i)R_\text{i,acc} = R_\text{v0} </math>,

where <math>R_\text{v0}</math> and <math>R_\text{i,v}</math> are the isotope ratio of the remaining vapour at the start and the calculating point of the solid condensation stage, respectively, and <math>f_i</math> the fraction of remaining vapour within the solid condensation stage. Finally and again, using mass conservation of the rare isotopes, we obtain the isotope ratio of the total accumulation of the removal by <math> (1-ff_i)R_\text{acc} = (1-f)R_\text{l,acc} + f(1-f_i)R_\text{i,acc} </math>. Corresponding examples of the calculated isotopic evolution profiles are shown in Fig. 2.

[[File:Rayleigh_model_box_sketch_v2.png|thumb|800px|'''''Figure 1''''' Schematic presentation of the mathematical approaches of the Rayleigh model in open system '''(a, b)''' and closed system '''(c)'''. Adapted from Gat ''et al'' (2001).
'''(a)''' From a reservoir containing ''N'' abundant isotopologues (e.g. H<sub>2</sub><sup>16</sup>O) and ''N<sub>i</sub>'' rare isotopologues (e.g. H<sub>2</sub><sup>18</sup>O or HD<sup>16</sup>O) small amounts of both species, ''dN'' and ''dN<sub>i</sub>'' respectively, are being removed under equilibrium fractionation conditions: <math> dN_i/dN = αR </math>.
'''(b)''' The changing isotopic composition of the reservoir is calculated from a mass balance consideration for the rare isotopologues: <math> RN = (R-dR)(N-dN) + αRdN </math>.
'''(c)''' In closed system, the changing isotopic composition of the reservoir can be calculated from a mass balance consideration for the rare isotopologues: <math> R_0N_0 = R(N_0-dN) + αRdN </math>, with the remaining fraction <math> f = (N_0-dN)/N_0 </math>.]]

[[File:Rayleigh_model_plot_v2_CG.png|thumb|800px|'''''Figure 2''''' Isotopic change during '''(a), (c)''' Rayleigh evaporation, and '''(b), (d)''' Rayleigh condensation.

Rayleigh evaporation occurs here at 20 °C (thus a constant fractionation factor) for initial liquid compositions of δ<sup>18</sup>O = -10 ‰ and δD = -70 ‰ (''d'' = 10 ‰), in open system with unsaturated (RH = 75 %; black) or saturated (grey) environment, and closed system (blue). In addition, the result of C--G evaporation model (i.e. open system including feedback from a "free atmosphere" which has fixed isotope compositions of δ<sup>18</sup>O = -13 ‰ and δD = -94 ‰ (''d'' = 10 ‰) and a fixed relative humidity (RH = 75 %)) is also presented (red).

Rayleigh condensation occurs here under continuous cooling (thus also a contentiously changing fractionation factor) from T = 20 °C and RH = 75 %. The initial vapour compositions are δ<sup>18</sup>O = -13 ‰ and δD = -94 ‰ (''d'' = 10 ‰). For the condensation to ice below 0 °C, two cases are presented. The saturation case (grey) is a classical Rayleigh process where ice crystals from from vapour under equilibrium conditions, using the saturation pressure over ice (''e<sub>i</sub>''). The supersaturation case (black) takes into account the supersaturation over ice, where the ambient vapour pressure is ''e<sub>v</sub> = S<sub>i</sub>*e<sub>i</sub>''. ''S<sub>i</sub>'' is the defined saturation ratio, as ''e<sub>v</sub>/e<sub>i</sub>'', and here takes the form ''S<sub>i</sub> = 1-0.004T'' after Risi ''et al'' (2010a). In this case, the fractionation factor combining equilibrium and kinetic effects given by Jouzel & Merlivat (1984) is used.

The equations used in this figure can be found in Table 1.]]

{| class="wikitable"
|+ ''Table 1'' Rayleigh equations to calculate isotopic evolution of the remaining reservoir under different conditions. The transport resistance is here assumed to be purely due to diffusion (i.e. <math>\rho \propto D^{-1} </math>).
|-
! scope="col"|
! scope="col"| Conditions
! scope="col" colspan="2"| Equation (''R'' and ''δ'' notation)
! scope="col"| Fractionation factor used
|-
! scope="row" rowspan="4"| Evaporation
| open system saturated
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> α = \alpha_{vl}<1 </math>
|-
| open system undersaturated
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> \alpha = \frac{1}{\alpha_k \alpha_{lv}} </math>, where <math> \alpha_{lv}>1 </math>, and <math> \alpha_k = \frac{D}{D'}(1-h)+h > 1 </math>, with <math> h = \frac{e_v}{e_l} </math>
|-
| closed system
| <math> R = \frac{R_0}{f+\alpha(1-f)} </math>
| <math> \delta = \frac{1+\delta_0}{f+\alpha(1-f)}-1 </math>
| <math> α = \alpha_{vl}<1 </math>
|-
| C--G model
| <math> R = R_0f^{\alpha-1} </math>
| <math> \delta = (1+\delta_0)f^{\alpha-1}-1 </math>
| <math> \alpha = \frac{\alpha_{vl}-h\frac{R_a}{R_l}}{(1-h)\frac{D}{D'}} </math>, where <math> \alpha_{vl} < 1 </math>
|-
! scope="row" rowspan="2"| Condensation
| saturation over ice
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> α = \alpha_{sv}>1 </math>
|-
| supersaturation over ice
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> \alpha = \alpha_k \alpha_{sv} </math>, where <math> \alpha_{sv}>1 </math>, and <math> \alpha_k = \frac{S_i}{\alpha_s \frac{D}{D'}(S_i-1)+1} < 1 </math>, with <math> S_i = \frac{e_v}{e_i} </math>
|-
|}

----

== Model codes in MATLAB ==

=== Rayleigh evaporation ===

<pre>
% rayleigh_evaporation.m
%--------------------------------
% Description:
% simple Rayleigh evaporation model, after Stern and Blisniuk, 2002
%--------------------------------
% input variables: T0 (Kelvin), d18O0 (permil), d2H0 (permil);
% system: closed system = 0, open system = 1, C--G model = 2;
% optional: relative humidity (default = 1), d18Oa (permil), d2Ha (permil)
% run example: rayleigh_evaporation(20+273.15,-10,-70,1,0.75)
% rayleigh_evaporation(20+273.15,-10,-70,1)
% rayleigh_evaporation(20+273.15,-10,-70,2)
%--------------------------------
% HS, Do 12 Dez 2013 15:43:28 CET
% YW, structured and included the case of kinetic effect
% and the case of C--G model, 29 Aug 2020
%--------------------------------

function data = rayleigh_evaporation(T0,d18O0,d2H0,system,h,d18Oa,d2Ha)

% %% dubugging
% T0 = 20+273.15;
% d18O0 = -10; % close to Bergen precipitation average
% d2H0 = -70;
% system = 1;
% h = 0.75;

%% fractionation factors
%--------------------------------
% Majoube, M., 1971a: Fractionnement en oxyg`ene-18 entre la glace et la vapeur d’eau. J.
% Chim. Phys., 68, 625–636.

% Majoube, M., 1971b: Fractionnement en oxyg`ene 18 et deut ́erium entre l’eau et sa vapeur. J. Chim.
% Phys., 68, 1423–1436.

% Merlivat, L. and G. Nief, 1967: Fractionnement isotopique lors des changements d‘ ́etat
% solide-vapeur et liquide-vapeur de l’eau `a des temp ́eratures inf ́erieures a ` 0 ◦ C. Tellus,
% 19, 122–127.
%--------------------------------
function d = a2H(T) % T in K
d = 1/exp(24.844e3/(T^2)-76.248/T+52.612e-3); % Majoube 1971b, R_vapour/R_liquid < 1
end

function d = a18O(T) % T in K
d = 1/exp(1137/(T^2)-0.4156/T-0.0020667); % Majoube 1971b, R_vapour/R_liquid < 1
end

%% initialization
% isotope ratios of VSMOW reference water
R2std = 155.76e-6;
R18std = 2005.20e-6;
% initial isotope ratio
R18O0 = (d18O0/1000+1)*R18std;
R2H0 = (d2H0/1000+1)*R2std;
% relative humidity
if ~exist('h','var')
h = 1;
end
% isotope composition of "free atmosphere"
% if not existing, default it to the equilibrium vapour of global average precipitation
if ~exist('d18Oa','var')
d18Oa = -13;
end
if ~exist('d2Ha','var')
d2Ha = -94;
end
R18Oa = (d18Oa/1000+1)*R18std;
R2Ha = (d2Ha/1000+1)*R2std;

% % ouput variables
% data.T = [];
% data.f = [];
% data.d18Ov = [];
% data.d18Ol = [];
% data.d2Hv = [];
% data.d2Hl = [];
% data.dxsv = [];
% data.dxsl = [];
% data.d18Ov_acc = [];
% data.d2Hv_acc = [];
% data.dxsv_acc = [];

%% Rayleigh evaporation process: (0) in closed system (material maintained under two-phase equilibrium)
% i.e., the material removed stays in the closed system and stays in equilibrium with the reservoir
if system == 0
fprintf('Rayleigh evaporation process: in an closed system (material maintained under two-phase equilibrium) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
i = 1; % iteration steps
for f = 1:-0.02:0 % remaining liquid fraction
% isotope ratio of remaining liquid
R18Ol = R18O0/(a18O(T0) - f*(a18O(T0)-1)); % Gat1996
R2Hl = R2H0/(a2H(T0) - f*(a2H(T0)-1)); % Gat1996
% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*a18O(T0)-1)*1000;
d2Hv = ((d2Hl/1000+1)*a2H(T0)-1)*1000;
dxsv = d2Hv-8*d18Ov;
% (3) delta value of the accumulated removed vapour
d18Ov_acc = d18Ov;
d2Hv_acc = d2Hv;
dxsv_acc = dxsv;

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;
end
end

%% Rayleigh evaporation process: (1) in an open system (material is immediately removed)
if system == 1
fprintf('Rayleigh evaporation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
i = 1; % iteration steps
n = 1; % turbulent exponent in D^n, [0 1], controls the ratio of diffusive transport over turbulent transport of water molecules (Pfahl and Wernli, 2009)
for f = 1:-0.02:0 % remaining liquid fraction

% modified Rayleigh evaporation model including kinectic effct
% during the vapour formation at undersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
D18 = 0.9723; % D'/D
D2 = 0.9755; % D'/D
ak_18O = 1/(1/D18^n*(1-h)+h);
ak_2H = 1/(1/D2^n*(1-h)+h);
aeff_18O = a18O(T0) * ak_18O;
aeff_2H = a2H(T0) * ak_2H;

% isotope ratio of remaining liquid
R18Ol = R18O0*f^(aeff_18O-1);
R2Hl = R2H0*f^(aeff_2H-1);
% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*aeff_18O-1)*1000;
d2Hv = ((d2Hl/1000+1)*aeff_2H-1)*1000;
dxsv = d2Hv-8*d18Ov;

% (3) isotope ratio of the accumulated removed vapour
R18Ov_acc = R18O0*(1-f^aeff_18O)/(1-f); % Mook 2001, Page 38
R2Hv_acc = R2H0*(1-f^aeff_2H)/(1-f);
% delta value of the accumulated removed vapour
d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
dxsv_acc = d2Hv_acc-8*d18Ov_acc;
% % (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% % mass conservation of rare isotopes between the reservoir and formed removal: f*Rl+(1-f)*Rv_acc=R0,
% % after rearranging, we have: Rv_acc=(R0-f*Rl)/(1-f)
% R18Ov_acc2 = (R18O0-f*R18Ol)/(1-f);
% R2Hv_acc2 = (R2H0-f*R2Hl)/(1-f);
% data.d18Ov_acc2(i) = (R18Ov_acc2/R18std-1)*1000;
% data.d2Hv_acc2(i) = (R2Hv_acc2/R2std-1)*1000;
% data.dxsv_acc2(i) = data.d2Hv_acc2(i)-8*data.d18Ov_acc2(i);

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;
end
end

%% Rayleigh evaporation process: (2) in a "free atmosphere" of fixed humidity and isotope composition (C--G model)
if system == 2
fprintf('Rayleigh evaporation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
% turbulent exponent in D^n, [0 1], controls the ratio of diffusive transport over turbulent transport of water molecules (Pfahl and Wernli, 2009)
% n~0.5 for an open water body under natural conditions, n~0.58 for a falling raindrop (Stewart1975), n~1 for soils and leaves
n = 1;
df = 0.02;
i = 1; % iteration steps

for f = 1:-df:0 % remaining liquid fraction

% modified Rayleigh evaporation model including kinectic effct
% during the vapour formation at undersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
D18 = 0.9723; % D'/D
D2 = 0.9755; % D'/D
if i==1
aeff_18O = (a18O(T0) - h*R18Oa/R18O0) / ((1-h)*1/D18^n);
aeff_2H = (a2H(T0) - h*R2Ha/R2H0) / ((1-h)*1/D2^n);
% isotope ratio of remaining liquid
f1 = 1;
R18Ol = R18O0*f1^(aeff_18O-1);
R2Hl = R2H0*f1^(aeff_2H-1);
else
aeff_18O = (a18O(T0) - h*R18Oa/data.R18Ol(i-1)) / ((1-h)*1/D18^n);
aeff_2H = (a2H(T0) - h*R2Ha/data.R2Hl(i-1)) / ((1-h)*1/D2^n);
% isotope ratio of remaining liquid
f1 = 1-df; % fraction remaining relative to previous stage
R18Ol = data.R18Ol(i-1)*f1^(aeff_18O-1);
R2Hl = data.R2Hl(i-1)*f1^(aeff_2H-1);
end

% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*aeff_18O-1)*1000;
d2Hv = ((d2Hl/1000+1)*aeff_2H-1)*1000;
dxsv = d2Hv-8*d18Ov;

% % (3) isotope ratio of the accumulated removed vapour
% R18Ov_acc = R18O0*(1-f^aeff_18O)/(1-f); % Mook 2001, Page 38
% R2Hv_acc = R2H0*(1-f^aeff_2H)/(1-f);
% % delta value of the accumulated removed vapour
% d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
% d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
% dxsv_acc = d2Hv_acc-8*d18Ov_acc;
% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% mass conservation of rare isotopes between the reservoir and formed removal: f*Rl+(1-f)*Rv_acc=R0,
% after rearranging, we have: Rv_acc=(R0-f*Rl)/(1-f)
R18Ov_acc = (R18O0-f*R18Ol)/(1-f);
R2Hv_acc = (R2H0-f*R2Hl)/(1-f);
% delta value of the accumulated removed vapour
d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
dxsv_acc = d2Hv_acc-8*d18Ov_acc;

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;

end
end

end
% fin
</pre>

=== Rayleigh condensation ===

<pre>
% rayleigh_condensation.m
%--------------------------------
% Description:
% - simple Rayleigh condensation model, after Stern and Blisniuk, 2002
% - temperature dependent fractionation factor varies at each step during cooling process
% (1) isobaric cooling: e.g., air parcel advects to cold regions
% (2) or pseudoadiabatic cooling: e.g., updraft or lift of surface air parcel
% - therefore, the isotope ratio is calculated as: R(n+1) = R(n)(q(n+1)/q(n))^(a-1)
%--------------------------------
% input variables: T0 (Kelvin), RH0 (%), d18O0 (permil), d2H0 (permil),
% sice: saturation conditions over ice when temperature <0 degree
% > 1: using the constant supersaturation given as sice;
% = 1: meaning alpha_k = 1, thus no supersaturation;
% = 0: using formula Si = 1-0.004*T (in Celsius)
% run example: rayleigh_condensation(20+273.15,0.75,-13,-94,0)
% rayleigh_condensation(20+273.15,0.75,-13,-94,1)
% rayleigh_condensation(20+273.15,0.75,-13,-94,1.2)
%--------------------------------
% HS, Do 12 Dez 2013 15:43:28 CET
% YW, structured and included kinetic effect, 29 Aug 2020
%--------------------------------
% YW, 26 Mar 2020
% limitation:
% Rayleigh condensation model only reflects the process of water vapor removing
% and ignores: mixing of air masses, cloud water-vapor isotope exchange,
% subcloud droplet evaporation, and radiative cooling or heating.
%--------------------------------

function data = rayleigh_condensation(T0,RH0,d18O0,d2H0,sice)

% %% for debugging
% T0 = 20+273.15;
% RH0 = 0.75; % Craig-Gordon, 1965 (Fig. 15)
% d18O0 = -13;
% d2H0 = -94;
% sice = 0;

% RH0 = 0.91; % 20161207 AR event at Bergen
% d18O0 = -12.5;
% d2H0 = -100;

%% functions adopted
% fractionation factors
%--------------------------------
% Majoube, M., 1971a: Fractionnement en oxyg`ene-18 entre la glace et la vapeur d’eau. J.
% Chim. Phys., 68, 625–636.

% Majoube, M., 1971b: Fractionnement en oxyg`ene 18 et deut ́erium entre l’eau et sa vapeur. J. Chim.
% Phys., 68, 1423–1436.

% Merlivat, L. and G. Nief, 1967: Fractionnement isotopique lors des changements d‘ ́etat
% solide-vapeur et liquide-vapeur de l’eau `a des temp ́eratures inf ́erieures a ` 0 °C. Tellus,
% 19, 122–127.
%--------------------------------
function d = a2H(T) % T in Kelvin
if T >= 273.15 % above 0 celsius
d = exp(24.844e3/(T^2)-76.248/T+52.612e-3); % Majoube 1971b, R_liquid/R_vapour > 1
else
d = exp(16289./T.^2 - 0.0945); % Merlivat & Nief 1967, R_solid/R_vapour > 1
end
end

function d = a18O(T) % T in Kelvin
if T >= 273.15 % above 0 celsius
d = exp(1137/(T^2)-0.4156/T-0.0020667); % Majoube 1971b, R_liquid/R_vapour > 1
else
d = exp(11.839./T - 0.028224); % Majoube 1971a, R_solid/R_vapour > 1
end
end

% supersaturation with respect to ice
% Si = 1 − λT, with λ = 0.004. From Graf 2017 dissertation, page 53, Fig 3.1
% (as in Risi et al., 2010b, after Jouzel and Merlivat 1984.)
% Risi, C., S. Bony, F. Vimeux, and J. Jouzel, 2010b: Water-stable isotopes in the LMDZ4
% general circulation model: Model evaluation for present-day and past climates and
% applications to climatic interpretations of tropical isotopic records.
% sice: > 1: using the constant supersaturation given here;
% = 1: meaning alpha_k = 1, thus no supersaturation;
% = 0: using formula Si = 1-0.004*T (in Celsius)
function s = si(T)
if sice >= 1
s = sice;
else % elseif sice == 0
s = 1-0.004*(T-273.15);
end
end

% vapour saturation pressure
function es = esat(T) % T in Kelvin
if T >= 273.15
% es = 611*exp((17.27*T)/(273+T)); % T in celsius
es = 611*exp(17.27*(T-273.15)/T); % T in Kelvin
else
% Saturation vapour pressure over ice (Murphy and Koop, 2005) for T > 110 K:
es_ice = exp(9.550426 - 5723.265/T + 3.53068*log(T) - 0.00728332*T);
% the actual saturation vapour pressure
es = es_ice * si(T);
end
end

% saturated vapour mixing ratio
function ws = wsat(es,p)
ws = 0.622*es/(p-es);
end

% pressure at height of z
function p = pressure(z)
p0 = 101325; % Pa
z0 = 8000; % m scale height
p = p0*exp(-z/z0);
end

% moist adiabatic lapse rate [Curry and Webster,1999] (cited after Stern and Blisniuk, 2002)
function lr = gamma(ws,T) % T in Kelvin
% physical constants
g = 9.80665; % m/s^2 the gravitational acceleration
Cpd = 1.00464e3; % J/kg/K the specific heat capacity of dry air at constant pressure
L = 2.5104e6; % J/kg the latent heat of vaporization or sublimation
Rd = 287.04; % J/kg/K the specific gas constant for dry air
lr = g/Cpd*(1+L*ws/Rd/T)/(1+0.622*L*L*ws/Rd/Cpd/T/T); % [°C/m]
end

%% initialization
% isotope ratios of VSMOW reference water
R2std = 155.76e-6;
R18std = 2005.20e-6;
% initial isotope ratio
R18O0 = (d18O0/1000+1)*R18std;
R2H0 = (d2H0/1000+1)*R2std;
dxs0 = R2H0-8*R18O0;

% initial conditions
f = 1.0; % remaining vapour fractionation
z = 0.0; % elevation
p = pressure(z);
w0 = RH0*wsat(esat(T0),p); % kg/kg
% convert water mixing ratio unit
md = 28.97; % [g/mol] dry air molar mass
mv = 18.02; % [g/mol] water vapour molar mass
wconc0 = w0*md/mv*1e6; % [kg/kg] --> [ppmv]
rh = RH0;
dt = 0.5; % temperature step
T = T0+dt;

%% for the circumstance of isobaric cooling
%% (1) cool to saturation
fprintf('Rayleigh condensation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' T (°C) d18Ov d2Hv dxsv rh f WConc[ppmv] \n');
n = 1; % iteration number
while rh < 0.99
T = T-dt; % decrease temperature by dt °C at each iteration
ws = wsat(esat(T),p); % saturated water mixing ratio at each iteration
rh = w0/ws; % RH at each iteration
wconc = wconc0; % [kg/kg] --> [ppmv]

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18O0,d2H0,dxs0,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18O0;
data.R2H(n) = R2H0;
data.d18O(n) = d18O0;
data.dD(n) = d2H0;
data.dxs(n) = d2H0-8*d18O0;
data.d18Oc(n) = NaN; % condensate
data.d2Hc(n) = NaN;
data.dxsc(n) = NaN;
data.d18O_acc(n) = NaN; % accumulated condensate (liquid+solid)
data.d2H_acc(n) = NaN;
data.dxs_acc(n) = NaN;

% iterate to next step
n = n+1;
end

fprintf('Reached saturation now\n');

ws0 = w0;

%% (2) continue to cool and form liquid condensate
while T > 273.15 % isobaric cooling with condensation to 0 °C
T = T-dt; % decrease temperature by dt °C at each iteration
ws = wsat(esat(T),p); % saturated water mixing ratio at each iteration
wconc = ws*md/mv*1e6; % [kg/kg] --> [ppmv]
f = ws/ws0;

if n == 1
f1 = ws/ws0;
% isotope ratio of remaining vapour
R18Ov = R18O0*f1^(a18O(T)-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = R2H0*f1^(a2H(T)-1);
else
f1 = wconc/data.Wconc(n-1); % q(n)/q(n-1)
% isotope ratio of remaining vapour
R18Ov = data.R18O(n-1)*f1^(a18O(T)-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = data.R2H(n-1)*f1^(a2H(T)-1);
end

% (1) delta value of remaining vapour
d18Ov = (R18Ov/R18std-1)*1000;
d2Hv = (R2Hv/R2std-1)*1000;
dxsv = d2Hv - 8*d18Ov;

% (2) delta value of the instantaneously removed condensate (in equilibrium with the current remaining vapour)
d18Oc = ((d18Ov/1000+1)*a18O(T)-1)*1000;
d2Hc = ((d2Hv/1000+1)*a2H(T)-1)*1000;
dxsc = d2Hc-8*d18Oc;

% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% mass conservation of rare isotopes between the reservoir and formed removal: f*Rv + (1-f)*Rl_acc = R0,
% after rearranging, we have: Rl_acc = (R0-f*Rv)/(1-f)
R18Ol_acc = (R18O0-f*R18Ov)/(1-f);
R2Hl_acc = (R2H0-f*R2Hv)/(1-f);
d18Ol_acc = (R18Ol_acc/R18std-1)*1000;
d2Hl_acc = (R2Hl_acc/R2std-1)*1000;
dxsl_acc = d2Hl_acc-8*d18Ol_acc;

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18Ov,d2Hv,dxsv,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18Ov;
data.R2H(n) = R2Hv;
data.d18O(n) = d18Ov;
data.dD(n) = d2Hv;
data.dxs(n) = dxsv;
data.rh(n) = rh;
data.d18Oc(n) = d18Oc;
data.d2Hc(n) = d2Hc;
data.dxsc(n) = dxsc;
data.d18O_acc(n) = d18Ol_acc;
data.d2H_acc(n) = d2Hl_acc;
data.dxs_acc(n) = dxsl_acc;

% iterate to next step
n = n+1;
end

fprintf('Have cooled to 0 celcius now \n');

ws0_ice = ws;
R18O0 = R18Ov;
R2H0 = R2Hv;
f0 = f;

%% (3) continue to cool and form solid condensate
% considering mixed-phase cloud: subsaturated over liquid droplets and supersaturated over ice crystals

% closure assumption: liquid droplets --> evaporate to vapour --> deposite on ice crystals
% therefore: when T<0 celsius, the reduced fraction of vapour is due to its deposit on ice crystals with a fractionation
% factor alpha_eff = alpha_eq*alpha_k taking into account the kinetic effct under the supersaturation condition.
% i.e.: we start a new Rayleigh condensation model starting with the remaining vapour
% after the liquid condensation stage above, and use the new factionation factor alpha_eff

while T > -60+273.15
T = T-dt;
ws = wsat(esat(T),p);
wconc = ws*md/mv*1e6; % [kg/kg] --> [ppmv]
f = ws/ws0; % the total fraction of remaining vapour through all stages
fi = ws/ws0_ice; % the fraction of remaing vapour in the ice condensation stage only

% modified Rayleigh condensation model including kinectic effct
% during the ice formation at supersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
ak_18O = si(T)/(a18O(T)*1/0.9723*(si(T)-1) + 1);
ak_2H = si(T)/(a2H(T)*1/0.9755*(si(T)-1) + 1);
aeff_18O = a18O(T) * ak_18O;
aeff_2H = a2H(T) * ak_2H;

if n == 1
f1 = ws/ws0;
% isotope ratio of remaining vapour
R18Ov = R18O0*f1^(aeff_18O-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = R2H0*f1^(aeff_2H-1);
else
f1 = wconc/data.Wconc(n-1); % q(n)/q(n-1)
% isotope ratio of remaining vapour
R18Ov = data.R18O(n-1)*f1^(aeff_18O-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1), and Jouzel and Merlivat, 1984
R2Hv = data.R2H(n-1)*f1^(aeff_2H-1);
end

% (1) delta value of remaining vapour
d18Ov = (R18Ov/R18std-1)*1000;
d2Hv = (R2Hv/R2std-1)*1000;
dxsv = d2Hv - 8*d18Ov;

% (2) delta value of the instantaneously removed condensate (in equilibrium with the current remaining vapour)
d18Oc = ((d18Ov/1000+1)*aeff_18O-1)*1000;
d2Hc = ((d2Hv/1000+1)*aeff_2H-1)*1000;
dxsc = d2Hc-8*d18Oc;

% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% (i) mass conservation of rare isotopes between the reservoir and formed removal:
% fi*Rv + (1-fi)*Ri_acc = Rv0,
% where fi is the fraction of remaining vapour in the ice condensation stage, and
% Rv0 is the isotope ratio of the remaining vapour after liquid condensation stage
% after rearranging, we have: Ri_acc = (Rv0-fi*Rv)/(1-fi)
R18Oi_acc = (R18O0-fi*R18Ov)/(1-fi);
R2Hi_acc = (R2H0-fi*R2H0)/(1-fi);
% d18Oi_acc = (R18Oi_acc/R18std-1)*1000;
% d2Hi_acc = (R2Hi_acc/R2std-1)*1000;
% dxsi_acc = d2Hi_acc-8*d18Oi_acc;
% (ii) the total accumulation is sum of the liquid (1-f0) and solid condensate (f0*(1-fi))
% (1-f0*fi)*R_acc = (1-f0)*Rl_acc + (f0*(1-fi))*Ri_acc
R18O_acc = ((1-f0)*R18Ol_acc + (f0*(1-fi))*R18Oi_acc)/(1-f0*fi);
R2H_acc = ((1-f0)*R2Hl_acc + (f0*(1-fi))*R2Hi_acc)/(1-f0*fi);
d18O_acc = (R18O_acc/R18std-1)*1000;
d2H_acc = (R2H_acc/R2std-1)*1000;
dxs_acc = d2H_acc-8*d18O_acc;

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18Ov,d2Hv,dxsv,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18Ov;
data.R2H(n) = R2Hv;
data.d18O(n) = d18Ov;
data.dD(n) = d2Hv;
data.dxs(n) = dxsv;
data.rh(n) = rh;
data.d18Oc(n) = d18Oc;
data.d2Hc(n) = d2Hc;
data.dxsc(n) = dxsc;
data.d18O_acc(n) = d18O_acc;
data.d2H_acc(n) = d2H_acc;
data.dxs_acc(n) = dxs_acc;

% iterate to next step
n = n+1;
end

%% for the circumstance of pseudoadiabatic cooling
% - establish the relationship between T and z
z = 0;
p = pressure(z);
n = 1;
for T = T0:-dt:-60+273.15
data.T(n) = T;
data.z(n) = z;
data.p(n) = p;
% the elevation change
ws = wsat(esat(T),p);
lr = gamma(ws,T); % lapse rate
dz = dt/lr; % dt = lr*dz
% the new elevation and pressure
z = z+dz;
p = pressure(z);
data.lr(n) = lr;

% iterate to next step
n = n+1;
end

end
% fin
</pre>

== Example of usage ==

'''1. Generate the desired data sets'''

<pre>
%% create data sets
% Rayleigh evaporation
T0 = 20+273.15;
d18O0 = -10; % close to Bergen precipitation average
d2H0 = -70;
h = 0.75; % relative humidity
de_ok = rayleigh_evaporation(T0,d18O0,d2H0,1,h); % in an open system, unsaturated (including kinetic effect)
de_oe = rayleigh_evaporation(T0,d18O0,d2H0,1); % in an open system, saturated (equilibrium)
de_cl = rayleigh_evaporation(T0,d18O0,d2H0,0); % in a closed system
de_CG = rayleigh_evaporation(T0,d18O0,d2H0,2,h); % C--G model

% Rayleigh condensation
T0 = 20+273.15;
RH0 = 0.75; % Craig-Gordon, 1965 (Fig. 15)
d18O0 = -13;
d2H0 = -94;
% > 1: using the constant supersaturation given as sice;
% = 1:
% = 0:
dc_ln = rayleigh_condensation(T0,RH0,d18O0,d2H0,0); % using linear formula Si = 1-0.004*T (in Celsius)
dc_no = rayleigh_condensation(T0,RH0,d18O0,d2H0,1); % meaning alpha_k = 1, thus no supersaturation, e = e_ice
dc_11 = rayleigh_condensation(T0,RH0,d18O0,d2H0,1.1); % using the constant supersaturation as given
</pre>

'''2. Plot Rayleigh evaporation and condensation profiles.'''

As an example, Fig. 2 is created using the data sets generated from the above step and using the plotting codes from below.

<pre>
%% plot Rayleigh evaporation and condensation model
fs = 14;

clear h
figure
set(gcf,'color','white','position',[0 0 1200 1150],'PaperPositionMode','auto');
% left_color = [0 0 0]; % black
% right_color = [0 0.4470 0.7410]; % blueish % blue [0 0 1];
% set(gcf,'defaultAxesColorOrder',[left_color; right_color]);

% Rayleigh evaporation
h(1) = subplot(2,2,1);
% set(h(1),'Position', [0.1 0.56 0.38 0.38]);
hold on
pe(1) = plot(de_ok.f,de_ok.d18Ol,'k-','linewidth',2);
pe(2) = plot(de_ok.f,de_ok.d18Ov,'k--','linewidth',2);
pe(3) = plot(de_ok.f,de_ok.d18Ov_acc,'k:','linewidth',2);
pe(4) = plot(de_oe.f,de_oe.d18Ol,'-','color',[0.6 0.6 0.6],'linewidth',2); %'color',[0.3010 0.7450 0.9330],
pe(5) = plot(de_oe.f,de_oe.d18Ov,'--','color',[0.6 0.6 0.6],'linewidth',2);
pe(6) = plot(de_oe.f,de_oe.d18Ov_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
pe(7) = plot(de_cl.f,de_cl.d18Ol,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(8) = plot(de_cl.f,de_cl.d18Ov,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(9) = plot(de_cl.f,de_cl.d18Ov_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(10) = plot(de_CG.f,de_CG.d18Ol,'-','color',[0.8500 0.3250 0.0980],'linewidth',2);
pe(11) = plot(de_CG.f,de_CG.d18Ov,'--','color',[0.8500 0.3250 0.0980],'linewidth',2);
pe(12) = plot(de_CG.f,de_CG.d18Ov_acc,':','color',[0.8500 0.3250 0.0980],'linewidth',2);
ylim(h(1),[-30 40]);
xlabel('Residual water fraction','fontsize',fs);
ylabel(['\delta^{18}O / ',char(8240)],'fontsize',fs);
lgd1 = legend(h(1),pe(1:3),'residual water','instant vapour','total vapour removed','Location','northwest');
lgd1_pos = lgd1.Position;
lgd1.FontSize = fs;
% lgd1.Visible = 'off';
% 2nd axes
a2 = axes('position',get(h(1),'position'),'visible','off'); % create the same axes but set it invisible
% lgd2 = legend(a2,pe(4:6),'residual water','instant vapour','total vapour removed','Location','northwest');
% lgd2.FontSize = fs;
lgd2 = legend(a2,pe(4:6),'','','','location','northwest','box','off');
lgd2_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.58 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd2,'box','off','Position',lgd2_pos);
% 3rd axes
a3 = axes('position',get(gca,'position'),'visible','off'); % create the same axes but set it invisible
lgd3 = legend(a3,pe(7:9),'','','','location','northwest','box','off');
lgd3_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.79 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd3,'box','off','Position',lgd3_pos);
% % 4th axes
a4 = axes('position',get(gca,'position'),'visible','off'); % create the same axes but set it invisible
lgd4 = legend(a4,pe(10:12),'','','','location','northwest','box','off');
lgd4_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.88 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd4,'box','off','Position',lgd4_pos);
% add text
text(h(1),0.41,8.5,'open','FontSize',fs,'Rotation',30)
text(h(1),0.30,13.2,'(unsaturated)','FontSize',fs,'Rotation',53)
text(h(1),0.60,-3,'open','FontSize',fs,'Rotation',15,'color',[0.6 0.6 0.6])
text(h(1),0.48,-0.5,'(saturated)','FontSize',fs,'Rotation',20,'color',[0.6 0.6 0.6])
text(h(1),0.75,-10,'closed','FontSize',fs,'Rotation',7,'Color',[0.3010 0.7450 0.9330])
text(h(1),0.8,1.5,'C-G model','color',[0.8500 0.3250 0.0980],'FontSize',fs,'Rotation',15)

h(3) = subplot(2,2,3);
% set(h(3),'Position', [0.1 0.1 0.38 0.38]);
hold on
plot(de_ok.f,de_ok.dxsl,'k-','linewidth',2)
plot(de_ok.f,de_ok.dxsv,'k--','linewidth',2)
plot(de_ok.f,de_ok.dxsv_acc,'k:','linewidth',2)
plot(de_oe.f,de_oe.dxsl,'-','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_oe.f,de_oe.dxsv,'--','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_oe.f,de_oe.dxsv_acc,':','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_cl.f,de_cl.dxsl,'-','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_cl.f,de_cl.dxsv,'--','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_cl.f,de_cl.dxsv_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_CG.f,de_CG.dxsl,'-','color',[0.8500 0.3250 0.0980],'linewidth',2)
plot(de_CG.f,de_CG.dxsv,'--','color',[0.8500 0.3250 0.0980],'linewidth',2)
plot(de_CG.f,de_CG.dxsv_acc,':','color',[0.8500 0.3250 0.0980],'linewidth',2)
ylim(h(3),[-60 70]);
set(h(3),'ytick',-60:20:65);
xlabel('Residual water fraction','fontsize',fs);
ylabel(['\itd / ',char(8240)],'fontsize',fs);

% Rayleigh condensation
h(4) = subplot(2,2,4);
% set(h(4),'Position', [0.56 0.1 0.38 0.38]);
hold on
pc(4) = plot(dc_no.Wconc,dc_no.dxsc,'-','color',[0.6 0.6 0.6],'linewidth',2);
pc(5) = plot(dc_no.Wconc,dc_no.dxs,'--','color',[0.6 0.6 0.6],'linewidth',2);
pc(6) = plot(dc_no.Wconc,dc_no.dxs_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
ylim(gca,[-20 50]);
xlabel('Water mixing ratio / ppmv','fontsize',fs);
set(gca,'XTick',2000:3000:16000);
ylabel(['\itd / ',char(8240)],'fontsize',fs);
% 2nd axis
ax1_pos = get(gca,'position'); % position of first axes
axes('Position',ax1_pos,'XAxisLocation','top','YAxisLocation','right','Color','none','YTickLabel','','FontSize',fs,'TickDir','out');
hold on
pc(1) = plot(dc_ln.f,dc_ln.dxsc,'k-','linewidth',2); % [0.3010 0.7450 0.9330]
pc(2) = plot(dc_ln.f,dc_ln.dxs,'k--','linewidth',2);
pc(3) = plot(dc_ln.f,dc_ln.dxs_acc,'k:','linewidth',2);
% pc(7) = plot(dc_11.f,dc_11.dxsc,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(8) = plot(dc_11.f,dc_11.dxs,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(9) = plot(dc_11.f,dc_11.dxs_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
ylim(gca,[-20 50]);
xlabel('Residual vapour fraction','fontsize',fs);
% 3rd axis
axes('Position',ax1_pos+[0 0 0 -ax1_pos(4)],'XAxisLocation','top','YColor','w','YTick',[],'Color','none','TickDir','out','FontSize',fs);
hold on
pc(7) = plot(dc_ln.Wconc,20*ones(size(dc_ln.Wconc)),'k-'); % [0.3010 0.7450 0.9330]
ylim(gca,[-20 50]);
xlabel('T / °C','fontsize',fs);
set(gca,'XTick',[dc_ln.Wconc(81) dc_ln.Wconc(61:-10:11)],'XTickLabel',[-20 -10:5:15])

h(2) = subplot(2,2,2);
% set(h(2),'Position', [0.56 0.56 0.38 0.38]);
hold on
pc(4) = plot(dc_no.Wconc,dc_no.d18Oc,'-','color',[0.6 0.6 0.6],'linewidth',2); % [0 0.4470 0.7410]
pc(5) = plot(dc_no.Wconc,dc_no.d18O,'--','color',[0.6 0.6 0.6],'linewidth',2);
pc(6) = plot(dc_no.Wconc,dc_no.d18O_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
ylim(h(2),[-60 -2]);
xlabel('Water mixing ratio / ppmv','fontsize',fs);
set(gca,'XTick',2000:3000:16000);
ylabel(['\delta^{18}O / ',char(8240)],'fontsize',fs);
% 2nd axis
ax1_pos = get(gca,'position'); % position of first axes
axes('Position',ax1_pos,'XAxisLocation','top','YAxisLocation','right','Color','none','YTickLabel','','FontSize',fs,'TickDir','out');
hold on
pc(1) = plot(dc_ln.f,dc_ln.d18Oc,'k-','linewidth',2); % [0.3010 0.7450 0.9330]
pc(2) = plot(dc_ln.f,dc_ln.d18O,'k--','linewidth',2);
pc(3) = plot(dc_ln.f,dc_ln.d18O_acc,'k:','linewidth',2);
% pc(7) = plot(dc_11.f,dc_11.d18Oc,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(8) = plot(dc_11.f,dc_11.d18O,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(9) = plot(dc_11.f,dc_11.d18O_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
ylim(gca,[-60 -2]);
xlabel('Residual vapour fraction','fontsize',fs);
lg = legend(h(2),pc(1:3),'instant liquid/ice','residual vapour','total liquid/ice removed');
% lg = legend(h(2),pc(4:6),'instant liquid/ice','residual vapour','total liquid/ice removed');
set(lg,'Position',[0.69 0.66 0.20 0.06],'FontSize',fs);
lg_pos = lg.Position;
% 3rd axis
axes('Position',ax1_pos+[0 -ax1_pos(4)*0.2 0 -ax1_pos(4)*0.8],'XAxisLocation','top','YColor','w','YTick',[],'Color','none');
hold on
pc(7) = plot(dc_ln.Wconc,-2+zeros(size(dc_ln.d18Oc)),'k-'); % [0.3010 0.7450 0.9330]
ylim(gca,[-60 -2]);
xlabel('T / °C','fontsize',fs);
set(gca,'XTick',[dc_ln.Wconc(81) dc_ln.Wconc(61:-10:11)],'XTickLabel',[-20 -10:5:15],'FontSize',fs,'TickDir','out');
lg2 = legend(gca,pc(4:6),'','','','location','east','box','off');
lg2_pos = lg_pos+[-lg_pos(3)*0.405 +lg_pos(4)*0.02 0 lg_pos(4)*0.117]; % move the 2nd legend to the desired position
set(lg2,'box','off','Position',lg2_pos);
% add text
text(h(2),1300,-36,'super','FontSize',fs,'Rotation',65)
text(h(2),2150,-27.5,'saturation','FontSize',fs,'Rotation',50)
text(h(2),1200,-25,'saturation','FontSize',fs,'Rotation',50,'Color',0.6*[1 1 1])

set([h(1) h(3)],'XDir','reverse','box','on');
set(h(:),'color','none','FontSize',fs,'tickdir','out'); % ,'YAxisLocation','left','ticklength',[0 0],'ygrid','on','xgrid','on'

annotation('textbox',[0.05 0.96 0.02 0.02],'String','(a)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.49 0.96 0.02 0.02],'String','(b)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.05 0.48 0.02 0.02],'String','(c)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.49 0.48 0.02 0.02],'String','(d)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');

% print('-depsc','-r300','/scratch/home/figs/thesis/Rayleigh_model_plot');
% print('-dpng','-r300','/scratch/home/figs/thesis/Rayleigh_model_plot');
</pre>

Rayleigh model

2021-01-26T20:25:00Z

Hso039:

The Rayleigh distillation model describes the evolution of a multiple-phase system in which one phase is continuously removed to the other phase through fractional distillation. Despite its simplicity, it is a powerful framework to describe in particular the isotopic enrichment or depletion as material moves between reservoirs in an equilibrium fractionation process.

== Model description ==

The system applying the Rayleigh equation is often an open system, from which the newly formed phase is immediately removed. For example, the evaporation of natural water bodies, and the formation of precipitation that immediately leaves the system, can be regarded as examples for open systems. However, with some modifications, Rayleigh models can be also applied to other systems. One such system is a closed system (or two-phase equilibrium model; Gat, (1996)), where the material removed from one reservoir accumulates in a second reservoir in such a manner that isotopic equilibrium is maintained between the two reservoirs. An example for this would be the condensation of vapour to droplets in a cloud, without formation and removal of precipitation.

The isotopic enrichment or depletion by the Rayleigh process for both open and closed systems can be mathematically obtained by different approaches (Fig. 1). The Rayleigh equations that are used to describe the isotopic evolution of the remaining reservoir under different conditions are summarized in Table 1. The isotope ratio of the accumulated removal can be derived using mass conservation of rare isotopes remaining in the reservoir, and the removed component:

<math> fR_\text{remain} + (1-f)R_\text{remove,acc} = R_0 </math>.

In the case of condensation involving both liquid and solid phases, the accumulation is a combination of the removed mass fraction of both phases. First, following the equation above, the total liquid removal is calculated as

<math> R_\text{l,acc} = (R_0-fR_v)/(1-f) </math>.

Then, we consider a separated Rayleigh process by only taking into account of the ongoing formation of the solid phase. Following the same reasoning as above, the isotope ratio of the accumulated solid removal is calculated by

<math> f_iR_\text{i,v} + (1-f_i)R_\text{i,acc} = R_\text{v0} </math>,

where <math>R_\text{v0}</math> and <math>R_\text{i,v}</math> are the isotope ratio of the remaining vapour at the start and the calculating point of the solid condensation stage, respectively, and <math>f_i</math> the fraction of remaining vapour within the solid condensation stage. Finally and again, using mass conservation of the rare isotopes, we obtain the isotope ratio of the total accumulation of the removal by <math> (1-ff_i)R_\text{acc} = (1-f)R_\text{l,acc} + f(1-f_i)R_\text{i,acc} </math>. Corresponding examples of the calculated isotopic evolution profiles are shown in Fig. 2.

{| class="wikitable"
|+ ''Table 1'' Rayleigh equations to calculate isotopic evolution of the remaining reservoir under different conditions. The transport resistance is here assumed to be purely due to diffusion (i.e. <math>\rho \propto D^{-1} </math>).
|-
! scope="col"|
! scope="col"| Conditions
! scope="col" colspan="2"| Equation (''R'' and ''δ'' notation)
! scope="col"| Fractionation factor used
|-
! scope="row" rowspan="4"| Evaporation
| open system saturated
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> α = \alpha_{vl}<1 </math>
|-
| open system undersaturated
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> \alpha = \frac{1}{\alpha_k \alpha_{lv}} </math>, where <math> \alpha_{lv}>1 </math>, and <math> \alpha_k = \frac{D}{D'}(1-h)+h > 1 </math>, with <math> h = \frac{e_v}{e_l} </math>
|-
| closed system
| <math> R = \frac{R_0}{f+\alpha(1-f)} </math>
| <math> \delta = \frac{1+\delta_0}{f+\alpha(1-f)}-1 </math>
| <math> α = \alpha_{vl}<1 </math>
|-
| C--G model
| <math> R = R_0f^{\alpha-1} </math>
| <math> \delta = (1+\delta_0)f^{\alpha-1}-1 </math>
| <math> \alpha = \frac{\alpha_{vl}-h\frac{R_a}{R_l}}{(1-h)\frac{D}{D'}} </math>, where <math> \alpha_{vl} < 1 </math>
|-
! scope="row" rowspan="2"| Condensation
| saturation over ice
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> α = \alpha_{sv}>1 </math>
|-
| supersaturation over ice
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> \alpha = \alpha_k \alpha_{sv} </math>, where <math> \alpha_{sv}>1 </math>, and <math> \alpha_k = \frac{S_i}{\alpha_s \frac{D}{D'}(S_i-1)+1} < 1 </math>, with <math> S_i = \frac{e_v}{e_i} </math>
|-
|}

[[File:Rayleigh_model_box_sketch_v2.png|thumb|800px|'''''Figure 1''''' Schematic presentation of the mathematical approaches of the Rayleigh model in open system '''(a, b)''' and closed system '''(c)'''. Adapted from Gat ''et al'' (2001).
'''(a)''' From a reservoir containing ''N'' abundant isotopologues (e.g. H<sub>2</sub><sup>16</sup>O) and ''N<sub>i</sub>'' rare isotopologues (e.g. H<sub>2</sub><sup>18</sup>O or HD<sup>16</sup>O) small amounts of both species, ''dN'' and ''dN<sub>i</sub>'' respectively, are being removed under equilibrium fractionation conditions: <math> dN_i/dN = αR </math>.
'''(b)''' The changing isotopic composition of the reservoir is calculated from a mass balance consideration for the rare isotopologues: <math> RN = (R-dR)(N-dN) + αRdN </math>.
'''(c)''' In closed system, the changing isotopic composition of the reservoir can be calculated from a mass balance consideration for the rare isotopologues: <math> R_0N_0 = R(N_0-dN) + αRdN </math>, with the remaining fraction <math> f = (N_0-dN)/N_0 </math>.]]

[[File:Rayleigh_model_plot_v2_CG.png|thumb|800px|'''''Figure 2''''' Isotopic change during '''(a), (c)''' Rayleigh evaporation, and '''(b), (d)''' Rayleigh condensation.

Rayleigh evaporation occurs here at 20 °C (thus a constant fractionation factor) for initial liquid compositions of δ<sup>18</sup>O = -10 ‰ and δD = -70 ‰ (''d'' = 10 ‰), in open system with unsaturated (RH = 75 %; black) or saturated (grey) environment, and closed system (blue). In addition, the result of C--G evaporation model (i.e. open system including feedback from a "free atmosphere" which has fixed isotope compositions of δ<sup>18</sup>O = -13 ‰ and δD = -94 ‰ (''d'' = 10 ‰) and a fixed relative humidity (RH = 75 %)) is also presented (red).

Rayleigh condensation occurs here under continuous cooling (thus also a contentiously changing fractionation factor) from T = 20 °C and RH = 75 %. The initial vapour compositions are δ<sup>18</sup>O = -13 ‰ and δD = -94 ‰ (''d'' = 10 ‰). For the condensation to ice below 0 °C, two cases are presented. The saturation case (grey) is a classical Rayleigh process where ice crystals from from vapour under equilibrium conditions, using the saturation pressure over ice (''e<sub>i</sub>''). The supersaturation case (black) takes into account the supersaturation over ice, where the ambient vapour pressure is ''e<sub>v</sub> = S<sub>i</sub>*e<sub>i</sub>''. ''S<sub>i</sub>'' is the defined saturation ratio, as ''e<sub>v</sub>/e<sub>i</sub>'', and here takes the form ''S<sub>i</sub> = 1-0.004T'' after Risi ''et al'' (2010a). In this case, the fractionation factor combining equilibrium and kinetic effects given by Jouzel & Merlivat (1984) is used.

The equations used in this figure can be found in Table 1.]]

----

== Model codes in MATLAB ==

=== Rayleigh evaporation ===

<pre>
% rayleigh_evaporation.m
%--------------------------------
% Description:
% simple Rayleigh evaporation model, after Stern and Blisniuk, 2002
%--------------------------------
% input variables: T0 (Kelvin), d18O0 (permil), d2H0 (permil);
% system: closed system = 0, open system = 1, C--G model = 2;
% optional: relative humidity (default = 1), d18Oa (permil), d2Ha (permil)
% run example: rayleigh_evaporation(20+273.15,-10,-70,1,0.75)
% rayleigh_evaporation(20+273.15,-10,-70,1)
% rayleigh_evaporation(20+273.15,-10,-70,2)
%--------------------------------
% HS, Do 12 Dez 2013 15:43:28 CET
% YW, structured and included the case of kinetic effect
% and the case of C--G model, 29 Aug 2020
%--------------------------------

function data = rayleigh_evaporation(T0,d18O0,d2H0,system,h,d18Oa,d2Ha)

% %% dubugging
% T0 = 20+273.15;
% d18O0 = -10; % close to Bergen precipitation average
% d2H0 = -70;
% system = 1;
% h = 0.75;

%% fractionation factors
%--------------------------------
% Majoube, M., 1971a: Fractionnement en oxyg`ene-18 entre la glace et la vapeur d’eau. J.
% Chim. Phys., 68, 625–636.

% Majoube, M., 1971b: Fractionnement en oxyg`ene 18 et deut ́erium entre l’eau et sa vapeur. J. Chim.
% Phys., 68, 1423–1436.

% Merlivat, L. and G. Nief, 1967: Fractionnement isotopique lors des changements d‘ ́etat
% solide-vapeur et liquide-vapeur de l’eau `a des temp ́eratures inf ́erieures a ` 0 ◦ C. Tellus,
% 19, 122–127.
%--------------------------------
function d = a2H(T) % T in K
d = 1/exp(24.844e3/(T^2)-76.248/T+52.612e-3); % Majoube 1971b, R_vapour/R_liquid < 1
end

function d = a18O(T) % T in K
d = 1/exp(1137/(T^2)-0.4156/T-0.0020667); % Majoube 1971b, R_vapour/R_liquid < 1
end

%% initialization
% isotope ratios of VSMOW reference water
R2std = 155.76e-6;
R18std = 2005.20e-6;
% initial isotope ratio
R18O0 = (d18O0/1000+1)*R18std;
R2H0 = (d2H0/1000+1)*R2std;
% relative humidity
if ~exist('h','var')
h = 1;
end
% isotope composition of "free atmosphere"
% if not existing, default it to the equilibrium vapour of global average precipitation
if ~exist('d18Oa','var')
d18Oa = -13;
end
if ~exist('d2Ha','var')
d2Ha = -94;
end
R18Oa = (d18Oa/1000+1)*R18std;
R2Ha = (d2Ha/1000+1)*R2std;

% % ouput variables
% data.T = [];
% data.f = [];
% data.d18Ov = [];
% data.d18Ol = [];
% data.d2Hv = [];
% data.d2Hl = [];
% data.dxsv = [];
% data.dxsl = [];
% data.d18Ov_acc = [];
% data.d2Hv_acc = [];
% data.dxsv_acc = [];

%% Rayleigh evaporation process: (0) in closed system (material maintained under two-phase equilibrium)
% i.e., the material removed stays in the closed system and stays in equilibrium with the reservoir
if system == 0
fprintf('Rayleigh evaporation process: in an closed system (material maintained under two-phase equilibrium) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
i = 1; % iteration steps
for f = 1:-0.02:0 % remaining liquid fraction
% isotope ratio of remaining liquid
R18Ol = R18O0/(a18O(T0) - f*(a18O(T0)-1)); % Gat1996
R2Hl = R2H0/(a2H(T0) - f*(a2H(T0)-1)); % Gat1996
% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*a18O(T0)-1)*1000;
d2Hv = ((d2Hl/1000+1)*a2H(T0)-1)*1000;
dxsv = d2Hv-8*d18Ov;
% (3) delta value of the accumulated removed vapour
d18Ov_acc = d18Ov;
d2Hv_acc = d2Hv;
dxsv_acc = dxsv;

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;
end
end

%% Rayleigh evaporation process: (1) in an open system (material is immediately removed)
if system == 1
fprintf('Rayleigh evaporation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
i = 1; % iteration steps
n = 1; % turbulent exponent in D^n, [0 1], controls the ratio of diffusive transport over turbulent transport of water molecules (Pfahl and Wernli, 2009)
for f = 1:-0.02:0 % remaining liquid fraction

% modified Rayleigh evaporation model including kinectic effct
% during the vapour formation at undersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
D18 = 0.9723; % D'/D
D2 = 0.9755; % D'/D
ak_18O = 1/(1/D18^n*(1-h)+h);
ak_2H = 1/(1/D2^n*(1-h)+h);
aeff_18O = a18O(T0) * ak_18O;
aeff_2H = a2H(T0) * ak_2H;

% isotope ratio of remaining liquid
R18Ol = R18O0*f^(aeff_18O-1);
R2Hl = R2H0*f^(aeff_2H-1);
% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*aeff_18O-1)*1000;
d2Hv = ((d2Hl/1000+1)*aeff_2H-1)*1000;
dxsv = d2Hv-8*d18Ov;

% (3) isotope ratio of the accumulated removed vapour
R18Ov_acc = R18O0*(1-f^aeff_18O)/(1-f); % Mook 2001, Page 38
R2Hv_acc = R2H0*(1-f^aeff_2H)/(1-f);
% delta value of the accumulated removed vapour
d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
dxsv_acc = d2Hv_acc-8*d18Ov_acc;
% % (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% % mass conservation of rare isotopes between the reservoir and formed removal: f*Rl+(1-f)*Rv_acc=R0,
% % after rearranging, we have: Rv_acc=(R0-f*Rl)/(1-f)
% R18Ov_acc2 = (R18O0-f*R18Ol)/(1-f);
% R2Hv_acc2 = (R2H0-f*R2Hl)/(1-f);
% data.d18Ov_acc2(i) = (R18Ov_acc2/R18std-1)*1000;
% data.d2Hv_acc2(i) = (R2Hv_acc2/R2std-1)*1000;
% data.dxsv_acc2(i) = data.d2Hv_acc2(i)-8*data.d18Ov_acc2(i);

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;
end
end

%% Rayleigh evaporation process: (2) in a "free atmosphere" of fixed humidity and isotope composition (C--G model)
if system == 2
fprintf('Rayleigh evaporation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
% turbulent exponent in D^n, [0 1], controls the ratio of diffusive transport over turbulent transport of water molecules (Pfahl and Wernli, 2009)
% n~0.5 for an open water body under natural conditions, n~0.58 for a falling raindrop (Stewart1975), n~1 for soils and leaves
n = 1;
df = 0.02;
i = 1; % iteration steps

for f = 1:-df:0 % remaining liquid fraction

% modified Rayleigh evaporation model including kinectic effct
% during the vapour formation at undersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
D18 = 0.9723; % D'/D
D2 = 0.9755; % D'/D
if i==1
aeff_18O = (a18O(T0) - h*R18Oa/R18O0) / ((1-h)*1/D18^n);
aeff_2H = (a2H(T0) - h*R2Ha/R2H0) / ((1-h)*1/D2^n);
% isotope ratio of remaining liquid
f1 = 1;
R18Ol = R18O0*f1^(aeff_18O-1);
R2Hl = R2H0*f1^(aeff_2H-1);
else
aeff_18O = (a18O(T0) - h*R18Oa/data.R18Ol(i-1)) / ((1-h)*1/D18^n);
aeff_2H = (a2H(T0) - h*R2Ha/data.R2Hl(i-1)) / ((1-h)*1/D2^n);
% isotope ratio of remaining liquid
f1 = 1-df; % fraction remaining relative to previous stage
R18Ol = data.R18Ol(i-1)*f1^(aeff_18O-1);
R2Hl = data.R2Hl(i-1)*f1^(aeff_2H-1);
end

% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*aeff_18O-1)*1000;
d2Hv = ((d2Hl/1000+1)*aeff_2H-1)*1000;
dxsv = d2Hv-8*d18Ov;

% % (3) isotope ratio of the accumulated removed vapour
% R18Ov_acc = R18O0*(1-f^aeff_18O)/(1-f); % Mook 2001, Page 38
% R2Hv_acc = R2H0*(1-f^aeff_2H)/(1-f);
% % delta value of the accumulated removed vapour
% d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
% d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
% dxsv_acc = d2Hv_acc-8*d18Ov_acc;
% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% mass conservation of rare isotopes between the reservoir and formed removal: f*Rl+(1-f)*Rv_acc=R0,
% after rearranging, we have: Rv_acc=(R0-f*Rl)/(1-f)
R18Ov_acc = (R18O0-f*R18Ol)/(1-f);
R2Hv_acc = (R2H0-f*R2Hl)/(1-f);
% delta value of the accumulated removed vapour
d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
dxsv_acc = d2Hv_acc-8*d18Ov_acc;

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;

end
end

end
% fin
</pre>

=== Rayleigh condensation ===

<pre>
% rayleigh_condensation.m
%--------------------------------
% Description:
% - simple Rayleigh condensation model, after Stern and Blisniuk, 2002
% - temperature dependent fractionation factor varies at each step during cooling process
% (1) isobaric cooling: e.g., air parcel advects to cold regions
% (2) or pseudoadiabatic cooling: e.g., updraft or lift of surface air parcel
% - therefore, the isotope ratio is calculated as: R(n+1) = R(n)(q(n+1)/q(n))^(a-1)
%--------------------------------
% input variables: T0 (Kelvin), RH0 (%), d18O0 (permil), d2H0 (permil),
% sice: saturation conditions over ice when temperature <0 degree
% > 1: using the constant supersaturation given as sice;
% = 1: meaning alpha_k = 1, thus no supersaturation;
% = 0: using formula Si = 1-0.004*T (in Celsius)
% run example: rayleigh_condensation(20+273.15,0.75,-13,-94,0)
% rayleigh_condensation(20+273.15,0.75,-13,-94,1)
% rayleigh_condensation(20+273.15,0.75,-13,-94,1.2)
%--------------------------------
% HS, Do 12 Dez 2013 15:43:28 CET
% YW, structured and included kinetic effect, 29 Aug 2020
%--------------------------------
% YW, 26 Mar 2020
% limitation:
% Rayleigh condensation model only reflects the process of water vapor removing
% and ignores: mixing of air masses, cloud water-vapor isotope exchange,
% subcloud droplet evaporation, and radiative cooling or heating.
%--------------------------------

function data = rayleigh_condensation(T0,RH0,d18O0,d2H0,sice)

% %% for debugging
% T0 = 20+273.15;
% RH0 = 0.75; % Craig-Gordon, 1965 (Fig. 15)
% d18O0 = -13;
% d2H0 = -94;
% sice = 0;

% RH0 = 0.91; % 20161207 AR event at Bergen
% d18O0 = -12.5;
% d2H0 = -100;

%% functions adopted
% fractionation factors
%--------------------------------
% Majoube, M., 1971a: Fractionnement en oxyg`ene-18 entre la glace et la vapeur d’eau. J.
% Chim. Phys., 68, 625–636.

% Majoube, M., 1971b: Fractionnement en oxyg`ene 18 et deut ́erium entre l’eau et sa vapeur. J. Chim.
% Phys., 68, 1423–1436.

% Merlivat, L. and G. Nief, 1967: Fractionnement isotopique lors des changements d‘ ́etat
% solide-vapeur et liquide-vapeur de l’eau `a des temp ́eratures inf ́erieures a ` 0 °C. Tellus,
% 19, 122–127.
%--------------------------------
function d = a2H(T) % T in Kelvin
if T >= 273.15 % above 0 celsius
d = exp(24.844e3/(T^2)-76.248/T+52.612e-3); % Majoube 1971b, R_liquid/R_vapour > 1
else
d = exp(16289./T.^2 - 0.0945); % Merlivat & Nief 1967, R_solid/R_vapour > 1
end
end

function d = a18O(T) % T in Kelvin
if T >= 273.15 % above 0 celsius
d = exp(1137/(T^2)-0.4156/T-0.0020667); % Majoube 1971b, R_liquid/R_vapour > 1
else
d = exp(11.839./T - 0.028224); % Majoube 1971a, R_solid/R_vapour > 1
end
end

% supersaturation with respect to ice
% Si = 1 − λT, with λ = 0.004. From Graf 2017 dissertation, page 53, Fig 3.1
% (as in Risi et al., 2010b, after Jouzel and Merlivat 1984.)
% Risi, C., S. Bony, F. Vimeux, and J. Jouzel, 2010b: Water-stable isotopes in the LMDZ4
% general circulation model: Model evaluation for present-day and past climates and
% applications to climatic interpretations of tropical isotopic records.
% sice: > 1: using the constant supersaturation given here;
% = 1: meaning alpha_k = 1, thus no supersaturation;
% = 0: using formula Si = 1-0.004*T (in Celsius)
function s = si(T)
if sice >= 1
s = sice;
else % elseif sice == 0
s = 1-0.004*(T-273.15);
end
end

% vapour saturation pressure
function es = esat(T) % T in Kelvin
if T >= 273.15
% es = 611*exp((17.27*T)/(273+T)); % T in celsius
es = 611*exp(17.27*(T-273.15)/T); % T in Kelvin
else
% Saturation vapour pressure over ice (Murphy and Koop, 2005) for T > 110 K:
es_ice = exp(9.550426 - 5723.265/T + 3.53068*log(T) - 0.00728332*T);
% the actual saturation vapour pressure
es = es_ice * si(T);
end
end

% saturated vapour mixing ratio
function ws = wsat(es,p)
ws = 0.622*es/(p-es);
end

% pressure at height of z
function p = pressure(z)
p0 = 101325; % Pa
z0 = 8000; % m scale height
p = p0*exp(-z/z0);
end

% moist adiabatic lapse rate [Curry and Webster,1999] (cited after Stern and Blisniuk, 2002)
function lr = gamma(ws,T) % T in Kelvin
% physical constants
g = 9.80665; % m/s^2 the gravitational acceleration
Cpd = 1.00464e3; % J/kg/K the specific heat capacity of dry air at constant pressure
L = 2.5104e6; % J/kg the latent heat of vaporization or sublimation
Rd = 287.04; % J/kg/K the specific gas constant for dry air
lr = g/Cpd*(1+L*ws/Rd/T)/(1+0.622*L*L*ws/Rd/Cpd/T/T); % [°C/m]
end

%% initialization
% isotope ratios of VSMOW reference water
R2std = 155.76e-6;
R18std = 2005.20e-6;
% initial isotope ratio
R18O0 = (d18O0/1000+1)*R18std;
R2H0 = (d2H0/1000+1)*R2std;
dxs0 = R2H0-8*R18O0;

% initial conditions
f = 1.0; % remaining vapour fractionation
z = 0.0; % elevation
p = pressure(z);
w0 = RH0*wsat(esat(T0),p); % kg/kg
% convert water mixing ratio unit
md = 28.97; % [g/mol] dry air molar mass
mv = 18.02; % [g/mol] water vapour molar mass
wconc0 = w0*md/mv*1e6; % [kg/kg] --> [ppmv]
rh = RH0;
dt = 0.5; % temperature step
T = T0+dt;

%% for the circumstance of isobaric cooling
%% (1) cool to saturation
fprintf('Rayleigh condensation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' T (°C) d18Ov d2Hv dxsv rh f WConc[ppmv] \n');
n = 1; % iteration number
while rh < 0.99
T = T-dt; % decrease temperature by dt °C at each iteration
ws = wsat(esat(T),p); % saturated water mixing ratio at each iteration
rh = w0/ws; % RH at each iteration
wconc = wconc0; % [kg/kg] --> [ppmv]

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18O0,d2H0,dxs0,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18O0;
data.R2H(n) = R2H0;
data.d18O(n) = d18O0;
data.dD(n) = d2H0;
data.dxs(n) = d2H0-8*d18O0;
data.d18Oc(n) = NaN; % condensate
data.d2Hc(n) = NaN;
data.dxsc(n) = NaN;
data.d18O_acc(n) = NaN; % accumulated condensate (liquid+solid)
data.d2H_acc(n) = NaN;
data.dxs_acc(n) = NaN;

% iterate to next step
n = n+1;
end

fprintf('Reached saturation now\n');

ws0 = w0;

%% (2) continue to cool and form liquid condensate
while T > 273.15 % isobaric cooling with condensation to 0 °C
T = T-dt; % decrease temperature by dt °C at each iteration
ws = wsat(esat(T),p); % saturated water mixing ratio at each iteration
wconc = ws*md/mv*1e6; % [kg/kg] --> [ppmv]
f = ws/ws0;

if n == 1
f1 = ws/ws0;
% isotope ratio of remaining vapour
R18Ov = R18O0*f1^(a18O(T)-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = R2H0*f1^(a2H(T)-1);
else
f1 = wconc/data.Wconc(n-1); % q(n)/q(n-1)
% isotope ratio of remaining vapour
R18Ov = data.R18O(n-1)*f1^(a18O(T)-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = data.R2H(n-1)*f1^(a2H(T)-1);
end

% (1) delta value of remaining vapour
d18Ov = (R18Ov/R18std-1)*1000;
d2Hv = (R2Hv/R2std-1)*1000;
dxsv = d2Hv - 8*d18Ov;

% (2) delta value of the instantaneously removed condensate (in equilibrium with the current remaining vapour)
d18Oc = ((d18Ov/1000+1)*a18O(T)-1)*1000;
d2Hc = ((d2Hv/1000+1)*a2H(T)-1)*1000;
dxsc = d2Hc-8*d18Oc;

% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% mass conservation of rare isotopes between the reservoir and formed removal: f*Rv + (1-f)*Rl_acc = R0,
% after rearranging, we have: Rl_acc = (R0-f*Rv)/(1-f)
R18Ol_acc = (R18O0-f*R18Ov)/(1-f);
R2Hl_acc = (R2H0-f*R2Hv)/(1-f);
d18Ol_acc = (R18Ol_acc/R18std-1)*1000;
d2Hl_acc = (R2Hl_acc/R2std-1)*1000;
dxsl_acc = d2Hl_acc-8*d18Ol_acc;

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18Ov,d2Hv,dxsv,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18Ov;
data.R2H(n) = R2Hv;
data.d18O(n) = d18Ov;
data.dD(n) = d2Hv;
data.dxs(n) = dxsv;
data.rh(n) = rh;
data.d18Oc(n) = d18Oc;
data.d2Hc(n) = d2Hc;
data.dxsc(n) = dxsc;
data.d18O_acc(n) = d18Ol_acc;
data.d2H_acc(n) = d2Hl_acc;
data.dxs_acc(n) = dxsl_acc;

% iterate to next step
n = n+1;
end

fprintf('Have cooled to 0 celcius now \n');

ws0_ice = ws;
R18O0 = R18Ov;
R2H0 = R2Hv;
f0 = f;

%% (3) continue to cool and form solid condensate
% considering mixed-phase cloud: subsaturated over liquid droplets and supersaturated over ice crystals

% closure assumption: liquid droplets --> evaporate to vapour --> deposite on ice crystals
% therefore: when T<0 celsius, the reduced fraction of vapour is due to its deposit on ice crystals with a fractionation
% factor alpha_eff = alpha_eq*alpha_k taking into account the kinetic effct under the supersaturation condition.
% i.e.: we start a new Rayleigh condensation model starting with the remaining vapour
% after the liquid condensation stage above, and use the new factionation factor alpha_eff

while T > -60+273.15
T = T-dt;
ws = wsat(esat(T),p);
wconc = ws*md/mv*1e6; % [kg/kg] --> [ppmv]
f = ws/ws0; % the total fraction of remaining vapour through all stages
fi = ws/ws0_ice; % the fraction of remaing vapour in the ice condensation stage only

% modified Rayleigh condensation model including kinectic effct
% during the ice formation at supersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
ak_18O = si(T)/(a18O(T)*1/0.9723*(si(T)-1) + 1);
ak_2H = si(T)/(a2H(T)*1/0.9755*(si(T)-1) + 1);
aeff_18O = a18O(T) * ak_18O;
aeff_2H = a2H(T) * ak_2H;

if n == 1
f1 = ws/ws0;
% isotope ratio of remaining vapour
R18Ov = R18O0*f1^(aeff_18O-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = R2H0*f1^(aeff_2H-1);
else
f1 = wconc/data.Wconc(n-1); % q(n)/q(n-1)
% isotope ratio of remaining vapour
R18Ov = data.R18O(n-1)*f1^(aeff_18O-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1), and Jouzel and Merlivat, 1984
R2Hv = data.R2H(n-1)*f1^(aeff_2H-1);
end

% (1) delta value of remaining vapour
d18Ov = (R18Ov/R18std-1)*1000;
d2Hv = (R2Hv/R2std-1)*1000;
dxsv = d2Hv - 8*d18Ov;

% (2) delta value of the instantaneously removed condensate (in equilibrium with the current remaining vapour)
d18Oc = ((d18Ov/1000+1)*aeff_18O-1)*1000;
d2Hc = ((d2Hv/1000+1)*aeff_2H-1)*1000;
dxsc = d2Hc-8*d18Oc;

% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% (i) mass conservation of rare isotopes between the reservoir and formed removal:
% fi*Rv + (1-fi)*Ri_acc = Rv0,
% where fi is the fraction of remaining vapour in the ice condensation stage, and
% Rv0 is the isotope ratio of the remaining vapour after liquid condensation stage
% after rearranging, we have: Ri_acc = (Rv0-fi*Rv)/(1-fi)
R18Oi_acc = (R18O0-fi*R18Ov)/(1-fi);
R2Hi_acc = (R2H0-fi*R2H0)/(1-fi);
% d18Oi_acc = (R18Oi_acc/R18std-1)*1000;
% d2Hi_acc = (R2Hi_acc/R2std-1)*1000;
% dxsi_acc = d2Hi_acc-8*d18Oi_acc;
% (ii) the total accumulation is sum of the liquid (1-f0) and solid condensate (f0*(1-fi))
% (1-f0*fi)*R_acc = (1-f0)*Rl_acc + (f0*(1-fi))*Ri_acc
R18O_acc = ((1-f0)*R18Ol_acc + (f0*(1-fi))*R18Oi_acc)/(1-f0*fi);
R2H_acc = ((1-f0)*R2Hl_acc + (f0*(1-fi))*R2Hi_acc)/(1-f0*fi);
d18O_acc = (R18O_acc/R18std-1)*1000;
d2H_acc = (R2H_acc/R2std-1)*1000;
dxs_acc = d2H_acc-8*d18O_acc;

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18Ov,d2Hv,dxsv,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18Ov;
data.R2H(n) = R2Hv;
data.d18O(n) = d18Ov;
data.dD(n) = d2Hv;
data.dxs(n) = dxsv;
data.rh(n) = rh;
data.d18Oc(n) = d18Oc;
data.d2Hc(n) = d2Hc;
data.dxsc(n) = dxsc;
data.d18O_acc(n) = d18O_acc;
data.d2H_acc(n) = d2H_acc;
data.dxs_acc(n) = dxs_acc;

% iterate to next step
n = n+1;
end

%% for the circumstance of pseudoadiabatic cooling
% - establish the relationship between T and z
z = 0;
p = pressure(z);
n = 1;
for T = T0:-dt:-60+273.15
data.T(n) = T;
data.z(n) = z;
data.p(n) = p;
% the elevation change
ws = wsat(esat(T),p);
lr = gamma(ws,T); % lapse rate
dz = dt/lr; % dt = lr*dz
% the new elevation and pressure
z = z+dz;
p = pressure(z);
data.lr(n) = lr;

% iterate to next step
n = n+1;
end

end
% fin
</pre>

== Example of usage ==

'''1. Generate the desired data sets'''

<pre>
%% create data sets
% Rayleigh evaporation
T0 = 20+273.15;
d18O0 = -10; % close to Bergen precipitation average
d2H0 = -70;
h = 0.75; % relative humidity
de_ok = rayleigh_evaporation(T0,d18O0,d2H0,1,h); % in an open system, unsaturated (including kinetic effect)
de_oe = rayleigh_evaporation(T0,d18O0,d2H0,1); % in an open system, saturated (equilibrium)
de_cl = rayleigh_evaporation(T0,d18O0,d2H0,0); % in a closed system
de_CG = rayleigh_evaporation(T0,d18O0,d2H0,2,h); % C--G model

% Rayleigh condensation
T0 = 20+273.15;
RH0 = 0.75; % Craig-Gordon, 1965 (Fig. 15)
d18O0 = -13;
d2H0 = -94;
% > 1: using the constant supersaturation given as sice;
% = 1:
% = 0:
dc_ln = rayleigh_condensation(T0,RH0,d18O0,d2H0,0); % using linear formula Si = 1-0.004*T (in Celsius)
dc_no = rayleigh_condensation(T0,RH0,d18O0,d2H0,1); % meaning alpha_k = 1, thus no supersaturation, e = e_ice
dc_11 = rayleigh_condensation(T0,RH0,d18O0,d2H0,1.1); % using the constant supersaturation as given
</pre>

'''2. Plot Rayleigh evaporation and condensation profiles.'''

As an example, Fig. 2 is created using the data sets generated from the above step and using the plotting codes from below.

<pre>
%% plot Rayleigh evaporation and condensation model
fs = 14;

clear h
figure
set(gcf,'color','white','position',[0 0 1200 1150],'PaperPositionMode','auto');
% left_color = [0 0 0]; % black
% right_color = [0 0.4470 0.7410]; % blueish % blue [0 0 1];
% set(gcf,'defaultAxesColorOrder',[left_color; right_color]);

% Rayleigh evaporation
h(1) = subplot(2,2,1);
% set(h(1),'Position', [0.1 0.56 0.38 0.38]);
hold on
pe(1) = plot(de_ok.f,de_ok.d18Ol,'k-','linewidth',2);
pe(2) = plot(de_ok.f,de_ok.d18Ov,'k--','linewidth',2);
pe(3) = plot(de_ok.f,de_ok.d18Ov_acc,'k:','linewidth',2);
pe(4) = plot(de_oe.f,de_oe.d18Ol,'-','color',[0.6 0.6 0.6],'linewidth',2); %'color',[0.3010 0.7450 0.9330],
pe(5) = plot(de_oe.f,de_oe.d18Ov,'--','color',[0.6 0.6 0.6],'linewidth',2);
pe(6) = plot(de_oe.f,de_oe.d18Ov_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
pe(7) = plot(de_cl.f,de_cl.d18Ol,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(8) = plot(de_cl.f,de_cl.d18Ov,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(9) = plot(de_cl.f,de_cl.d18Ov_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(10) = plot(de_CG.f,de_CG.d18Ol,'-','color',[0.8500 0.3250 0.0980],'linewidth',2);
pe(11) = plot(de_CG.f,de_CG.d18Ov,'--','color',[0.8500 0.3250 0.0980],'linewidth',2);
pe(12) = plot(de_CG.f,de_CG.d18Ov_acc,':','color',[0.8500 0.3250 0.0980],'linewidth',2);
ylim(h(1),[-30 40]);
xlabel('Residual water fraction','fontsize',fs);
ylabel(['\delta^{18}O / ',char(8240)],'fontsize',fs);
lgd1 = legend(h(1),pe(1:3),'residual water','instant vapour','total vapour removed','Location','northwest');
lgd1_pos = lgd1.Position;
lgd1.FontSize = fs;
% lgd1.Visible = 'off';
% 2nd axes
a2 = axes('position',get(h(1),'position'),'visible','off'); % create the same axes but set it invisible
% lgd2 = legend(a2,pe(4:6),'residual water','instant vapour','total vapour removed','Location','northwest');
% lgd2.FontSize = fs;
lgd2 = legend(a2,pe(4:6),'','','','location','northwest','box','off');
lgd2_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.58 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd2,'box','off','Position',lgd2_pos);
% 3rd axes
a3 = axes('position',get(gca,'position'),'visible','off'); % create the same axes but set it invisible
lgd3 = legend(a3,pe(7:9),'','','','location','northwest','box','off');
lgd3_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.79 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd3,'box','off','Position',lgd3_pos);
% % 4th axes
a4 = axes('position',get(gca,'position'),'visible','off'); % create the same axes but set it invisible
lgd4 = legend(a4,pe(10:12),'','','','location','northwest','box','off');
lgd4_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.88 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd4,'box','off','Position',lgd4_pos);
% add text
text(h(1),0.41,8.5,'open','FontSize',fs,'Rotation',30)
text(h(1),0.30,13.2,'(unsaturated)','FontSize',fs,'Rotation',53)
text(h(1),0.60,-3,'open','FontSize',fs,'Rotation',15,'color',[0.6 0.6 0.6])
text(h(1),0.48,-0.5,'(saturated)','FontSize',fs,'Rotation',20,'color',[0.6 0.6 0.6])
text(h(1),0.75,-10,'closed','FontSize',fs,'Rotation',7,'Color',[0.3010 0.7450 0.9330])
text(h(1),0.8,1.5,'C-G model','color',[0.8500 0.3250 0.0980],'FontSize',fs,'Rotation',15)

h(3) = subplot(2,2,3);
% set(h(3),'Position', [0.1 0.1 0.38 0.38]);
hold on
plot(de_ok.f,de_ok.dxsl,'k-','linewidth',2)
plot(de_ok.f,de_ok.dxsv,'k--','linewidth',2)
plot(de_ok.f,de_ok.dxsv_acc,'k:','linewidth',2)
plot(de_oe.f,de_oe.dxsl,'-','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_oe.f,de_oe.dxsv,'--','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_oe.f,de_oe.dxsv_acc,':','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_cl.f,de_cl.dxsl,'-','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_cl.f,de_cl.dxsv,'--','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_cl.f,de_cl.dxsv_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_CG.f,de_CG.dxsl,'-','color',[0.8500 0.3250 0.0980],'linewidth',2)
plot(de_CG.f,de_CG.dxsv,'--','color',[0.8500 0.3250 0.0980],'linewidth',2)
plot(de_CG.f,de_CG.dxsv_acc,':','color',[0.8500 0.3250 0.0980],'linewidth',2)
ylim(h(3),[-60 70]);
set(h(3),'ytick',-60:20:65);
xlabel('Residual water fraction','fontsize',fs);
ylabel(['\itd / ',char(8240)],'fontsize',fs);

% Rayleigh condensation
h(4) = subplot(2,2,4);
% set(h(4),'Position', [0.56 0.1 0.38 0.38]);
hold on
pc(4) = plot(dc_no.Wconc,dc_no.dxsc,'-','color',[0.6 0.6 0.6],'linewidth',2);
pc(5) = plot(dc_no.Wconc,dc_no.dxs,'--','color',[0.6 0.6 0.6],'linewidth',2);
pc(6) = plot(dc_no.Wconc,dc_no.dxs_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
ylim(gca,[-20 50]);
xlabel('Water mixing ratio / ppmv','fontsize',fs);
set(gca,'XTick',2000:3000:16000);
ylabel(['\itd / ',char(8240)],'fontsize',fs);
% 2nd axis
ax1_pos = get(gca,'position'); % position of first axes
axes('Position',ax1_pos,'XAxisLocation','top','YAxisLocation','right','Color','none','YTickLabel','','FontSize',fs,'TickDir','out');
hold on
pc(1) = plot(dc_ln.f,dc_ln.dxsc,'k-','linewidth',2); % [0.3010 0.7450 0.9330]
pc(2) = plot(dc_ln.f,dc_ln.dxs,'k--','linewidth',2);
pc(3) = plot(dc_ln.f,dc_ln.dxs_acc,'k:','linewidth',2);
% pc(7) = plot(dc_11.f,dc_11.dxsc,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(8) = plot(dc_11.f,dc_11.dxs,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(9) = plot(dc_11.f,dc_11.dxs_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
ylim(gca,[-20 50]);
xlabel('Residual vapour fraction','fontsize',fs);
% 3rd axis
axes('Position',ax1_pos+[0 0 0 -ax1_pos(4)],'XAxisLocation','top','YColor','w','YTick',[],'Color','none','TickDir','out','FontSize',fs);
hold on
pc(7) = plot(dc_ln.Wconc,20*ones(size(dc_ln.Wconc)),'k-'); % [0.3010 0.7450 0.9330]
ylim(gca,[-20 50]);
xlabel('T / °C','fontsize',fs);
set(gca,'XTick',[dc_ln.Wconc(81) dc_ln.Wconc(61:-10:11)],'XTickLabel',[-20 -10:5:15])

h(2) = subplot(2,2,2);
% set(h(2),'Position', [0.56 0.56 0.38 0.38]);
hold on
pc(4) = plot(dc_no.Wconc,dc_no.d18Oc,'-','color',[0.6 0.6 0.6],'linewidth',2); % [0 0.4470 0.7410]
pc(5) = plot(dc_no.Wconc,dc_no.d18O,'--','color',[0.6 0.6 0.6],'linewidth',2);
pc(6) = plot(dc_no.Wconc,dc_no.d18O_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
ylim(h(2),[-60 -2]);
xlabel('Water mixing ratio / ppmv','fontsize',fs);
set(gca,'XTick',2000:3000:16000);
ylabel(['\delta^{18}O / ',char(8240)],'fontsize',fs);
% 2nd axis
ax1_pos = get(gca,'position'); % position of first axes
axes('Position',ax1_pos,'XAxisLocation','top','YAxisLocation','right','Color','none','YTickLabel','','FontSize',fs,'TickDir','out');
hold on
pc(1) = plot(dc_ln.f,dc_ln.d18Oc,'k-','linewidth',2); % [0.3010 0.7450 0.9330]
pc(2) = plot(dc_ln.f,dc_ln.d18O,'k--','linewidth',2);
pc(3) = plot(dc_ln.f,dc_ln.d18O_acc,'k:','linewidth',2);
% pc(7) = plot(dc_11.f,dc_11.d18Oc,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(8) = plot(dc_11.f,dc_11.d18O,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(9) = plot(dc_11.f,dc_11.d18O_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
ylim(gca,[-60 -2]);
xlabel('Residual vapour fraction','fontsize',fs);
lg = legend(h(2),pc(1:3),'instant liquid/ice','residual vapour','total liquid/ice removed');
% lg = legend(h(2),pc(4:6),'instant liquid/ice','residual vapour','total liquid/ice removed');
set(lg,'Position',[0.69 0.66 0.20 0.06],'FontSize',fs);
lg_pos = lg.Position;
% 3rd axis
axes('Position',ax1_pos+[0 -ax1_pos(4)*0.2 0 -ax1_pos(4)*0.8],'XAxisLocation','top','YColor','w','YTick',[],'Color','none');
hold on
pc(7) = plot(dc_ln.Wconc,-2+zeros(size(dc_ln.d18Oc)),'k-'); % [0.3010 0.7450 0.9330]
ylim(gca,[-60 -2]);
xlabel('T / °C','fontsize',fs);
set(gca,'XTick',[dc_ln.Wconc(81) dc_ln.Wconc(61:-10:11)],'XTickLabel',[-20 -10:5:15],'FontSize',fs,'TickDir','out');
lg2 = legend(gca,pc(4:6),'','','','location','east','box','off');
lg2_pos = lg_pos+[-lg_pos(3)*0.405 +lg_pos(4)*0.02 0 lg_pos(4)*0.117]; % move the 2nd legend to the desired position
set(lg2,'box','off','Position',lg2_pos);
% add text
text(h(2),1300,-36,'super','FontSize',fs,'Rotation',65)
text(h(2),2150,-27.5,'saturation','FontSize',fs,'Rotation',50)
text(h(2),1200,-25,'saturation','FontSize',fs,'Rotation',50,'Color',0.6*[1 1 1])

set([h(1) h(3)],'XDir','reverse','box','on');
set(h(:),'color','none','FontSize',fs,'tickdir','out'); % ,'YAxisLocation','left','ticklength',[0 0],'ygrid','on','xgrid','on'

annotation('textbox',[0.05 0.96 0.02 0.02],'String','(a)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.49 0.96 0.02 0.02],'String','(b)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.05 0.48 0.02 0.02],'String','(c)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.49 0.48 0.02 0.02],'String','(d)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');

% print('-depsc','-r300','/scratch/home/figs/thesis/Rayleigh_model_plot');
% print('-dpng','-r300','/scratch/home/figs/thesis/Rayleigh_model_plot');
</pre>

Rayleigh model

2021-01-26T20:23:55Z

Hso039:

The Rayleigh distillation model describes the evolution of a multiple-phase system in which one phase is continuously removed to the other phase through fractional distillation. Despite its simplicity, it is a powerful framework to describe in particular the isotopic enrichment or depletion as material moves between reservoirs in an equilibrium fractionation process.

== Model description ==

The system applying the Rayleigh equation is often an open system, from which the newly formed phase is immediately removed. For example, the evaporation of natural water bodies, and the formation of precipitation that immediately leaves the system, can be regarded as examples for open systems. However, with some modifications, Rayleigh models can be also applied to other systems. One such system is a closed system (or two-phase equilibrium model; Gat, (1996)), where the material removed from one reservoir accumulates in a second reservoir in such a manner that isotopic equilibrium is maintained between the two reservoirs. An example for this would be the condensation of vapour to droplets in a cloud, without formation and removal of precipitation.

The isotopic enrichment or depletion by the Rayleigh process for both open and closed systems can be mathematically obtained by different approaches (Fig. 1). The Rayleigh equations that are used to describe the isotopic evolution of the remaining reservoir under different conditions are summarized in Table 1. The isotope ratio of the accumulated removal can be derived using mass conservation of rare isotopes remaining in the reservoir, and the removed component:

<math> fR_\text{remain} + (1-f)R_\text{remove,acc} = R_0 </math>.

In the case of condensation involving both liquid and solid phases, the accumulation is a combination of the removed mass fraction of both phases. First, following the equation above, the total liquid removal is calculated as

<math> R_\text{l,acc} = (R_0-fR_v)/(1-f) </math>.

Then, we consider a separated Rayleigh process by only taking into account of the ongoing formation of the solid phase. Following the same reasoning as above, the isotope ratio of the accumulated solid removal is calculated by

<math> f_iR_\text{i,v} + (1-f_i)R_\text{i,acc} = R_\text{v0} </math>,

where <math>R_\text{v0}</math> and <math>R_\text{i,v}</math> are the isotope ratio of the remaining vapour at the start and the calculating point of the solid condensation stage, respectively, and <math>f_i</math> the fraction of remaining vapour within the solid condensation stage. Finally and again, using mass conservation of the rare isotopes, we obtain the isotope ratio of the total accumulation of the removal by <math> (1-ff_i)R_\text{acc} = (1-f)R_\text{l,acc} + f(1-f_i)R_\text{i,acc} </math>. Corresponding examples of the calculated isotopic evolution profiles are shown in Fig. 2.

{| class="wikitable"
|+ ''Table 1'' Rayleigh equations to calculate isotopic evolution of the remaining reservoir under different conditions. The transport resistance is here assumed to be purely due to diffusion (i.e. <math>\rho \propto D^{-1} </math>).
|-
! scope="col"|
! scope="col"| Conditions
! scope="col" colspan="2"| Equation (''R'' and ''δ'' notation)
! scope="col"| Fractionation factor used
|-
! scope="row" rowspan="4"| Evaporation
| open system saturated
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> α = \alpha_{vl}<1 </math>
|-
| open system undersaturated
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> \alpha = \frac{1}{\alpha_k \alpha_{lv}} </math>, where <math> \alpha_{lv}>1 </math>, and <math> \alpha_k = \frac{D}{D'}(1-h)+h > 1 </math>, with <math> h = \frac{e_v}{e_l} </math>
|-
| closed system
| <math> R = \frac{R_0}{f+\alpha(1-f)} </math>
| <math> \delta = \frac{1+\delta_0}{f+\alpha(1-f)}-1 </math>
| <math> α = \alpha_{vl}<1 </math>
|-
| C--G model
| <math> R = R_0f^{\alpha-1} </math>
| <math> \delta = (1+\delta_0)f^{\alpha-1}-1 </math>
| <math> \alpha = \frac{\alpha_{vl}-h\frac{R_a}{R_l}}{(1-h)\frac{D}{D'}} </math>, where <math> \alpha_{vl} < 1 </math>
|-
! scope="row" rowspan="2"| Condensation
| saturation over ice
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> α = \alpha_{sv}>1 </math>
|-
| supersaturation over ice
| <math> R = R_0f^{α-1} </math>
| <math> δ = (1+δ_0)f^{α-1}-1 </math>
| <math> \alpha = \alpha_k \alpha_{sv} </math>, where <math> \alpha_{sv}>1 </math>, and <math> \alpha_k = \frac{S_i}{\alpha_s \frac{D}{D'}(S_i-1)+1} < 1 </math>, with <math> S_i = \frac{e_v}{e_i} </math>
|-
|}

[[File:Rayleigh_model_box_sketch_v2.png|thumb|800px|'''''Figure 1''''' Schematic presentation of the mathematical approaches of the Rayleigh model in open system '''(a, b)''' and closed system '''(c)'''. Adapted from Gat ''et al'' (2001).
'''(a)''' From a reservoir containing ''N'' abundant isotopologues (e.g. H<sub>2</sub><sup>16</sup>O) and ''N<sub>i</sub>'' rare isotopologues (e.g. H<sub>2</sub><sup>18</sup>O or HD<sup>16</sup>O) small amounts of both species, ''dN'' and ''dN<sub>i</sub>'' respectively, are being removed under equilibrium fractionation conditions: <math> dN_i/dN = αR </math>.
'''(b)''' The changing isotopic composition of the reservoir is calculated from a mass balance consideration for the rare isotopologues: <math> RN = (R-dR)(N-dN) + αRdN </math>.
'''(c)''' In closed system, the changing isotopic composition of the reservoir can be calculated from a mass balance consideration for the rare isotopologues: <math> R_0N_0 = R(N_0-dN) + αRdN </math>, with the remaining fraction <math> f = (N_0-dN)/N_0 </math>.]]

[[File:Rayleigh_model_plot_v2_CG.png|thumb|800px|'''''Figure 2''''' Isotopic change during '''(a), (c)''' Rayleigh evaporation, and '''(b), (d)''' Rayleigh condensation.

Rayleigh evaporation occurs here at 20 °C (thus a constant fractionation factor) for initial liquid compositions of δ<sup>18</sup>O = -10 ‰ and δD = -70 ‰ (''d'' = 10 ‰), in open system with unsaturated (RH = 75 %; black) or saturated (grey) environment, and closed system (blue). In addition, the result of C--G evaporation model (i.e. open system including feedback from a "free atmosphere" which has fixed isotope compositions of δ<sup>18</sup>O = -13 ‰ and δD = -94 ‰ (''d'' = 10 ‰) and a fixed relative humidity (RH = 75 %)) is also presented (red).

Rayleigh condensation occurs here under continuous cooling (thus also a contentiously changing fractionation factor) from T = 20 °C and RH = 75 %. The initial vapour compositions are δ<sup>18</sup>O = -13 ‰ and δD = -94 ‰ (''d'' = 10 ‰). For the condensation to ice below 0 °C, two cases are presented. The saturation case (grey) is a classical Rayleigh process where ice crystals from from vapour under equilibrium conditions, using the saturation pressure over ice (''e<sub>i</sub>''). The supersaturation case (black) takes into account the supersaturation over ice, where the ambient vapour pressure is ''e<sub>v</sub> = S<sub>i</sub>*e<sub>i</sub>''. ''S<sub>i</sub>'' is the defined saturation ratio, as ''e<sub>v</sub>/e<sub>i</sub>'', and here takes the form ''S<sub>i</sub> = 1-0.004T'' after Risi ''et al'' (2010a). In this case, the fractionation factor combining equilibrium and kinetic effects given by Jouzel & Merlivat (1984) is used.

The equations used in this figure can be found in Table 1.]]

== Model codes in MATLAB ==

=== Rayleigh evaporation ===

<pre>
% rayleigh_evaporation.m
%--------------------------------
% Description:
% simple Rayleigh evaporation model, after Stern and Blisniuk, 2002
%--------------------------------
% input variables: T0 (Kelvin), d18O0 (permil), d2H0 (permil);
% system: closed system = 0, open system = 1, C--G model = 2;
% optional: relative humidity (default = 1), d18Oa (permil), d2Ha (permil)
% run example: rayleigh_evaporation(20+273.15,-10,-70,1,0.75)
% rayleigh_evaporation(20+273.15,-10,-70,1)
% rayleigh_evaporation(20+273.15,-10,-70,2)
%--------------------------------
% HS, Do 12 Dez 2013 15:43:28 CET
% YW, structured and included the case of kinetic effect
% and the case of C--G model, 29 Aug 2020
%--------------------------------

function data = rayleigh_evaporation(T0,d18O0,d2H0,system,h,d18Oa,d2Ha)

% %% dubugging
% T0 = 20+273.15;
% d18O0 = -10; % close to Bergen precipitation average
% d2H0 = -70;
% system = 1;
% h = 0.75;

%% fractionation factors
%--------------------------------
% Majoube, M., 1971a: Fractionnement en oxyg`ene-18 entre la glace et la vapeur d’eau. J.
% Chim. Phys., 68, 625–636.

% Majoube, M., 1971b: Fractionnement en oxyg`ene 18 et deut ́erium entre l’eau et sa vapeur. J. Chim.
% Phys., 68, 1423–1436.

% Merlivat, L. and G. Nief, 1967: Fractionnement isotopique lors des changements d‘ ́etat
% solide-vapeur et liquide-vapeur de l’eau `a des temp ́eratures inf ́erieures a ` 0 ◦ C. Tellus,
% 19, 122–127.
%--------------------------------
function d = a2H(T) % T in K
d = 1/exp(24.844e3/(T^2)-76.248/T+52.612e-3); % Majoube 1971b, R_vapour/R_liquid < 1
end

function d = a18O(T) % T in K
d = 1/exp(1137/(T^2)-0.4156/T-0.0020667); % Majoube 1971b, R_vapour/R_liquid < 1
end

%% initialization
% isotope ratios of VSMOW reference water
R2std = 155.76e-6;
R18std = 2005.20e-6;
% initial isotope ratio
R18O0 = (d18O0/1000+1)*R18std;
R2H0 = (d2H0/1000+1)*R2std;
% relative humidity
if ~exist('h','var')
h = 1;
end
% isotope composition of "free atmosphere"
% if not existing, default it to the equilibrium vapour of global average precipitation
if ~exist('d18Oa','var')
d18Oa = -13;
end
if ~exist('d2Ha','var')
d2Ha = -94;
end
R18Oa = (d18Oa/1000+1)*R18std;
R2Ha = (d2Ha/1000+1)*R2std;

% % ouput variables
% data.T = [];
% data.f = [];
% data.d18Ov = [];
% data.d18Ol = [];
% data.d2Hv = [];
% data.d2Hl = [];
% data.dxsv = [];
% data.dxsl = [];
% data.d18Ov_acc = [];
% data.d2Hv_acc = [];
% data.dxsv_acc = [];

%% Rayleigh evaporation process: (0) in closed system (material maintained under two-phase equilibrium)
% i.e., the material removed stays in the closed system and stays in equilibrium with the reservoir
if system == 0
fprintf('Rayleigh evaporation process: in an closed system (material maintained under two-phase equilibrium) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
i = 1; % iteration steps
for f = 1:-0.02:0 % remaining liquid fraction
% isotope ratio of remaining liquid
R18Ol = R18O0/(a18O(T0) - f*(a18O(T0)-1)); % Gat1996
R2Hl = R2H0/(a2H(T0) - f*(a2H(T0)-1)); % Gat1996
% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*a18O(T0)-1)*1000;
d2Hv = ((d2Hl/1000+1)*a2H(T0)-1)*1000;
dxsv = d2Hv-8*d18Ov;
% (3) delta value of the accumulated removed vapour
d18Ov_acc = d18Ov;
d2Hv_acc = d2Hv;
dxsv_acc = dxsv;

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;
end
end

%% Rayleigh evaporation process: (1) in an open system (material is immediately removed)
if system == 1
fprintf('Rayleigh evaporation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
i = 1; % iteration steps
n = 1; % turbulent exponent in D^n, [0 1], controls the ratio of diffusive transport over turbulent transport of water molecules (Pfahl and Wernli, 2009)
for f = 1:-0.02:0 % remaining liquid fraction

% modified Rayleigh evaporation model including kinectic effct
% during the vapour formation at undersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
D18 = 0.9723; % D'/D
D2 = 0.9755; % D'/D
ak_18O = 1/(1/D18^n*(1-h)+h);
ak_2H = 1/(1/D2^n*(1-h)+h);
aeff_18O = a18O(T0) * ak_18O;
aeff_2H = a2H(T0) * ak_2H;

% isotope ratio of remaining liquid
R18Ol = R18O0*f^(aeff_18O-1);
R2Hl = R2H0*f^(aeff_2H-1);
% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*aeff_18O-1)*1000;
d2Hv = ((d2Hl/1000+1)*aeff_2H-1)*1000;
dxsv = d2Hv-8*d18Ov;

% (3) isotope ratio of the accumulated removed vapour
R18Ov_acc = R18O0*(1-f^aeff_18O)/(1-f); % Mook 2001, Page 38
R2Hv_acc = R2H0*(1-f^aeff_2H)/(1-f);
% delta value of the accumulated removed vapour
d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
dxsv_acc = d2Hv_acc-8*d18Ov_acc;
% % (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% % mass conservation of rare isotopes between the reservoir and formed removal: f*Rl+(1-f)*Rv_acc=R0,
% % after rearranging, we have: Rv_acc=(R0-f*Rl)/(1-f)
% R18Ov_acc2 = (R18O0-f*R18Ol)/(1-f);
% R2Hv_acc2 = (R2H0-f*R2Hl)/(1-f);
% data.d18Ov_acc2(i) = (R18Ov_acc2/R18std-1)*1000;
% data.d2Hv_acc2(i) = (R2Hv_acc2/R2std-1)*1000;
% data.dxsv_acc2(i) = data.d2Hv_acc2(i)-8*data.d18Ov_acc2(i);

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;
end
end

%% Rayleigh evaporation process: (2) in a "free atmosphere" of fixed humidity and isotope composition (C--G model)
if system == 2
fprintf('Rayleigh evaporation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' f d18Ol d18Ov d2Hl d2Hv dxsl dxsv d18Ov_acc dxsv_acc \n');
% turbulent exponent in D^n, [0 1], controls the ratio of diffusive transport over turbulent transport of water molecules (Pfahl and Wernli, 2009)
% n~0.5 for an open water body under natural conditions, n~0.58 for a falling raindrop (Stewart1975), n~1 for soils and leaves
n = 1;
df = 0.02;
i = 1; % iteration steps

for f = 1:-df:0 % remaining liquid fraction

% modified Rayleigh evaporation model including kinectic effct
% during the vapour formation at undersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
D18 = 0.9723; % D'/D
D2 = 0.9755; % D'/D
if i==1
aeff_18O = (a18O(T0) - h*R18Oa/R18O0) / ((1-h)*1/D18^n);
aeff_2H = (a2H(T0) - h*R2Ha/R2H0) / ((1-h)*1/D2^n);
% isotope ratio of remaining liquid
f1 = 1;
R18Ol = R18O0*f1^(aeff_18O-1);
R2Hl = R2H0*f1^(aeff_2H-1);
else
aeff_18O = (a18O(T0) - h*R18Oa/data.R18Ol(i-1)) / ((1-h)*1/D18^n);
aeff_2H = (a2H(T0) - h*R2Ha/data.R2Hl(i-1)) / ((1-h)*1/D2^n);
% isotope ratio of remaining liquid
f1 = 1-df; % fraction remaining relative to previous stage
R18Ol = data.R18Ol(i-1)*f1^(aeff_18O-1);
R2Hl = data.R2Hl(i-1)*f1^(aeff_2H-1);
end

% (1) delta value of remaining liquid
d18Ol = (R18Ol/R18std-1)*1000;
d2Hl = (R2Hl/R2std-1)*1000;
dxsl = d2Hl-8*d18Ol;

% (2) delta value of the instantaneously removed vapour (in equilibrium with the current remaining liquid)
d18Ov = ((d18Ol/1000+1)*aeff_18O-1)*1000;
d2Hv = ((d2Hl/1000+1)*aeff_2H-1)*1000;
dxsv = d2Hv-8*d18Ov;

% % (3) isotope ratio of the accumulated removed vapour
% R18Ov_acc = R18O0*(1-f^aeff_18O)/(1-f); % Mook 2001, Page 38
% R2Hv_acc = R2H0*(1-f^aeff_2H)/(1-f);
% % delta value of the accumulated removed vapour
% d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
% d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
% dxsv_acc = d2Hv_acc-8*d18Ov_acc;
% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% mass conservation of rare isotopes between the reservoir and formed removal: f*Rl+(1-f)*Rv_acc=R0,
% after rearranging, we have: Rv_acc=(R0-f*Rl)/(1-f)
R18Ov_acc = (R18O0-f*R18Ol)/(1-f);
R2Hv_acc = (R2H0-f*R2Hl)/(1-f);
% delta value of the accumulated removed vapour
d18Ov_acc = (R18Ov_acc/R18std-1)*1000;
d2Hv_acc = (R2Hv_acc/R2std-1)*1000;
dxsv_acc = d2Hv_acc-8*d18Ov_acc;

fprintf('%8.4f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f\n',f,d18Ol,d18Ov,d2Hl,d2Hv,dxsl,dxsv,d18Ov_acc,dxsv_acc);

% assign to output
data.T(i) = T0;
data.f(i) = f;
data.R18Ol(i) = R18Ol;
data.d18Ol(i) = d18Ol;
data.d18Ov(i) = d18Ov;
data.R2Hl(i) = R2Hl;
data.d2Hl(i) = d2Hl;
data.d2Hv(i) = d2Hv;
data.dxsl(i) = dxsl;
data.dxsv(i) = dxsv;
data.d18Ov_acc(i) = d18Ov_acc;
data.d2Hv_acc(i) = d2Hv_acc;
data.dxsv_acc(i) = dxsv_acc;

% iterate to next step
i = i+1;

end
end

end
% fin
</pre>

=== Rayleigh condensation ===

<pre>
% rayleigh_condensation.m
%--------------------------------
% Description:
% - simple Rayleigh condensation model, after Stern and Blisniuk, 2002
% - temperature dependent fractionation factor varies at each step during cooling process
% (1) isobaric cooling: e.g., air parcel advects to cold regions
% (2) or pseudoadiabatic cooling: e.g., updraft or lift of surface air parcel
% - therefore, the isotope ratio is calculated as: R(n+1) = R(n)(q(n+1)/q(n))^(a-1)
%--------------------------------
% input variables: T0 (Kelvin), RH0 (%), d18O0 (permil), d2H0 (permil),
% sice: saturation conditions over ice when temperature <0 degree
% > 1: using the constant supersaturation given as sice;
% = 1: meaning alpha_k = 1, thus no supersaturation;
% = 0: using formula Si = 1-0.004*T (in Celsius)
% run example: rayleigh_condensation(20+273.15,0.75,-13,-94,0)
% rayleigh_condensation(20+273.15,0.75,-13,-94,1)
% rayleigh_condensation(20+273.15,0.75,-13,-94,1.2)
%--------------------------------
% HS, Do 12 Dez 2013 15:43:28 CET
% YW, structured and included kinetic effect, 29 Aug 2020
%--------------------------------
% YW, 26 Mar 2020
% limitation:
% Rayleigh condensation model only reflects the process of water vapor removing
% and ignores: mixing of air masses, cloud water-vapor isotope exchange,
% subcloud droplet evaporation, and radiative cooling or heating.
%--------------------------------

function data = rayleigh_condensation(T0,RH0,d18O0,d2H0,sice)

% %% for debugging
% T0 = 20+273.15;
% RH0 = 0.75; % Craig-Gordon, 1965 (Fig. 15)
% d18O0 = -13;
% d2H0 = -94;
% sice = 0;

% RH0 = 0.91; % 20161207 AR event at Bergen
% d18O0 = -12.5;
% d2H0 = -100;

%% functions adopted
% fractionation factors
%--------------------------------
% Majoube, M., 1971a: Fractionnement en oxyg`ene-18 entre la glace et la vapeur d’eau. J.
% Chim. Phys., 68, 625–636.

% Majoube, M., 1971b: Fractionnement en oxyg`ene 18 et deut ́erium entre l’eau et sa vapeur. J. Chim.
% Phys., 68, 1423–1436.

% Merlivat, L. and G. Nief, 1967: Fractionnement isotopique lors des changements d‘ ́etat
% solide-vapeur et liquide-vapeur de l’eau `a des temp ́eratures inf ́erieures a ` 0 °C. Tellus,
% 19, 122–127.
%--------------------------------
function d = a2H(T) % T in Kelvin
if T >= 273.15 % above 0 celsius
d = exp(24.844e3/(T^2)-76.248/T+52.612e-3); % Majoube 1971b, R_liquid/R_vapour > 1
else
d = exp(16289./T.^2 - 0.0945); % Merlivat & Nief 1967, R_solid/R_vapour > 1
end
end

function d = a18O(T) % T in Kelvin
if T >= 273.15 % above 0 celsius
d = exp(1137/(T^2)-0.4156/T-0.0020667); % Majoube 1971b, R_liquid/R_vapour > 1
else
d = exp(11.839./T - 0.028224); % Majoube 1971a, R_solid/R_vapour > 1
end
end

% supersaturation with respect to ice
% Si = 1 − λT, with λ = 0.004. From Graf 2017 dissertation, page 53, Fig 3.1
% (as in Risi et al., 2010b, after Jouzel and Merlivat 1984.)
% Risi, C., S. Bony, F. Vimeux, and J. Jouzel, 2010b: Water-stable isotopes in the LMDZ4
% general circulation model: Model evaluation for present-day and past climates and
% applications to climatic interpretations of tropical isotopic records.
% sice: > 1: using the constant supersaturation given here;
% = 1: meaning alpha_k = 1, thus no supersaturation;
% = 0: using formula Si = 1-0.004*T (in Celsius)
function s = si(T)
if sice >= 1
s = sice;
else % elseif sice == 0
s = 1-0.004*(T-273.15);
end
end

% vapour saturation pressure
function es = esat(T) % T in Kelvin
if T >= 273.15
% es = 611*exp((17.27*T)/(273+T)); % T in celsius
es = 611*exp(17.27*(T-273.15)/T); % T in Kelvin
else
% Saturation vapour pressure over ice (Murphy and Koop, 2005) for T > 110 K:
es_ice = exp(9.550426 - 5723.265/T + 3.53068*log(T) - 0.00728332*T);
% the actual saturation vapour pressure
es = es_ice * si(T);
end
end

% saturated vapour mixing ratio
function ws = wsat(es,p)
ws = 0.622*es/(p-es);
end

% pressure at height of z
function p = pressure(z)
p0 = 101325; % Pa
z0 = 8000; % m scale height
p = p0*exp(-z/z0);
end

% moist adiabatic lapse rate [Curry and Webster,1999] (cited after Stern and Blisniuk, 2002)
function lr = gamma(ws,T) % T in Kelvin
% physical constants
g = 9.80665; % m/s^2 the gravitational acceleration
Cpd = 1.00464e3; % J/kg/K the specific heat capacity of dry air at constant pressure
L = 2.5104e6; % J/kg the latent heat of vaporization or sublimation
Rd = 287.04; % J/kg/K the specific gas constant for dry air
lr = g/Cpd*(1+L*ws/Rd/T)/(1+0.622*L*L*ws/Rd/Cpd/T/T); % [°C/m]
end

%% initialization
% isotope ratios of VSMOW reference water
R2std = 155.76e-6;
R18std = 2005.20e-6;
% initial isotope ratio
R18O0 = (d18O0/1000+1)*R18std;
R2H0 = (d2H0/1000+1)*R2std;
dxs0 = R2H0-8*R18O0;

% initial conditions
f = 1.0; % remaining vapour fractionation
z = 0.0; % elevation
p = pressure(z);
w0 = RH0*wsat(esat(T0),p); % kg/kg
% convert water mixing ratio unit
md = 28.97; % [g/mol] dry air molar mass
mv = 18.02; % [g/mol] water vapour molar mass
wconc0 = w0*md/mv*1e6; % [kg/kg] --> [ppmv]
rh = RH0;
dt = 0.5; % temperature step
T = T0+dt;

%% for the circumstance of isobaric cooling
%% (1) cool to saturation
fprintf('Rayleigh condensation process: in an open system (material is immediately removed) \n');
fprintf('T0 = %6.2f K (%4.2f °C) \n', T0, T0-273.15);
fprintf(' T (°C) d18Ov d2Hv dxsv rh f WConc[ppmv] \n');
n = 1; % iteration number
while rh < 0.99
T = T-dt; % decrease temperature by dt °C at each iteration
ws = wsat(esat(T),p); % saturated water mixing ratio at each iteration
rh = w0/ws; % RH at each iteration
wconc = wconc0; % [kg/kg] --> [ppmv]

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18O0,d2H0,dxs0,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18O0;
data.R2H(n) = R2H0;
data.d18O(n) = d18O0;
data.dD(n) = d2H0;
data.dxs(n) = d2H0-8*d18O0;
data.d18Oc(n) = NaN; % condensate
data.d2Hc(n) = NaN;
data.dxsc(n) = NaN;
data.d18O_acc(n) = NaN; % accumulated condensate (liquid+solid)
data.d2H_acc(n) = NaN;
data.dxs_acc(n) = NaN;

% iterate to next step
n = n+1;
end

fprintf('Reached saturation now\n');

ws0 = w0;

%% (2) continue to cool and form liquid condensate
while T > 273.15 % isobaric cooling with condensation to 0 °C
T = T-dt; % decrease temperature by dt °C at each iteration
ws = wsat(esat(T),p); % saturated water mixing ratio at each iteration
wconc = ws*md/mv*1e6; % [kg/kg] --> [ppmv]
f = ws/ws0;

if n == 1
f1 = ws/ws0;
% isotope ratio of remaining vapour
R18Ov = R18O0*f1^(a18O(T)-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = R2H0*f1^(a2H(T)-1);
else
f1 = wconc/data.Wconc(n-1); % q(n)/q(n-1)
% isotope ratio of remaining vapour
R18Ov = data.R18O(n-1)*f1^(a18O(T)-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = data.R2H(n-1)*f1^(a2H(T)-1);
end

% (1) delta value of remaining vapour
d18Ov = (R18Ov/R18std-1)*1000;
d2Hv = (R2Hv/R2std-1)*1000;
dxsv = d2Hv - 8*d18Ov;

% (2) delta value of the instantaneously removed condensate (in equilibrium with the current remaining vapour)
d18Oc = ((d18Ov/1000+1)*a18O(T)-1)*1000;
d2Hc = ((d2Hv/1000+1)*a2H(T)-1)*1000;
dxsc = d2Hc-8*d18Oc;

% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% mass conservation of rare isotopes between the reservoir and formed removal: f*Rv + (1-f)*Rl_acc = R0,
% after rearranging, we have: Rl_acc = (R0-f*Rv)/(1-f)
R18Ol_acc = (R18O0-f*R18Ov)/(1-f);
R2Hl_acc = (R2H0-f*R2Hv)/(1-f);
d18Ol_acc = (R18Ol_acc/R18std-1)*1000;
d2Hl_acc = (R2Hl_acc/R2std-1)*1000;
dxsl_acc = d2Hl_acc-8*d18Ol_acc;

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18Ov,d2Hv,dxsv,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18Ov;
data.R2H(n) = R2Hv;
data.d18O(n) = d18Ov;
data.dD(n) = d2Hv;
data.dxs(n) = dxsv;
data.rh(n) = rh;
data.d18Oc(n) = d18Oc;
data.d2Hc(n) = d2Hc;
data.dxsc(n) = dxsc;
data.d18O_acc(n) = d18Ol_acc;
data.d2H_acc(n) = d2Hl_acc;
data.dxs_acc(n) = dxsl_acc;

% iterate to next step
n = n+1;
end

fprintf('Have cooled to 0 celcius now \n');

ws0_ice = ws;
R18O0 = R18Ov;
R2H0 = R2Hv;
f0 = f;

%% (3) continue to cool and form solid condensate
% considering mixed-phase cloud: subsaturated over liquid droplets and supersaturated over ice crystals

% closure assumption: liquid droplets --> evaporate to vapour --> deposite on ice crystals
% therefore: when T<0 celsius, the reduced fraction of vapour is due to its deposit on ice crystals with a fractionation
% factor alpha_eff = alpha_eq*alpha_k taking into account the kinetic effct under the supersaturation condition.
% i.e.: we start a new Rayleigh condensation model starting with the remaining vapour
% after the liquid condensation stage above, and use the new factionation factor alpha_eff

while T > -60+273.15
T = T-dt;
ws = wsat(esat(T),p);
wconc = ws*md/mv*1e6; % [kg/kg] --> [ppmv]
f = ws/ws0; % the total fraction of remaining vapour through all stages
fi = ws/ws0_ice; % the fraction of remaing vapour in the ice condensation stage only

% modified Rayleigh condensation model including kinectic effct
% during the ice formation at supersaturated conditions (Jouzel and Merlivat 1984)
% Diffusivities D adopted from Merlivat 1978:
% D_H18O/D_H16O = 0.9723 ± 0.0007
% D_HD16O/D_H216O = 0.9755 ± 0.0009
ak_18O = si(T)/(a18O(T)*1/0.9723*(si(T)-1) + 1);
ak_2H = si(T)/(a2H(T)*1/0.9755*(si(T)-1) + 1);
aeff_18O = a18O(T) * ak_18O;
aeff_2H = a2H(T) * ak_2H;

if n == 1
f1 = ws/ws0;
% isotope ratio of remaining vapour
R18Ov = R18O0*f1^(aeff_18O-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1)
R2Hv = R2H0*f1^(aeff_2H-1);
else
f1 = wconc/data.Wconc(n-1); % q(n)/q(n-1)
% isotope ratio of remaining vapour
R18Ov = data.R18O(n-1)*f1^(aeff_18O-1); % R(n) = R(n-1)(q(n)/q(n-1))^(a-1), and Jouzel and Merlivat, 1984
R2Hv = data.R2H(n-1)*f1^(aeff_2H-1);
end

% (1) delta value of remaining vapour
d18Ov = (R18Ov/R18std-1)*1000;
d2Hv = (R2Hv/R2std-1)*1000;
dxsv = d2Hv - 8*d18Ov;

% (2) delta value of the instantaneously removed condensate (in equilibrium with the current remaining vapour)
d18Oc = ((d18Ov/1000+1)*aeff_18O-1)*1000;
d2Hc = ((d2Hv/1000+1)*aeff_2H-1)*1000;
dxsc = d2Hc-8*d18Oc;

% (3) Calculating the isotope ratio of the accumulated removal using mass conservation approach
% (i) mass conservation of rare isotopes between the reservoir and formed removal:
% fi*Rv + (1-fi)*Ri_acc = Rv0,
% where fi is the fraction of remaining vapour in the ice condensation stage, and
% Rv0 is the isotope ratio of the remaining vapour after liquid condensation stage
% after rearranging, we have: Ri_acc = (Rv0-fi*Rv)/(1-fi)
R18Oi_acc = (R18O0-fi*R18Ov)/(1-fi);
R2Hi_acc = (R2H0-fi*R2H0)/(1-fi);
% d18Oi_acc = (R18Oi_acc/R18std-1)*1000;
% d2Hi_acc = (R2Hi_acc/R2std-1)*1000;
% dxsi_acc = d2Hi_acc-8*d18Oi_acc;
% (ii) the total accumulation is sum of the liquid (1-f0) and solid condensate (f0*(1-fi))
% (1-f0*fi)*R_acc = (1-f0)*Rl_acc + (f0*(1-fi))*Ri_acc
R18O_acc = ((1-f0)*R18Ol_acc + (f0*(1-fi))*R18Oi_acc)/(1-f0*fi);
R2H_acc = ((1-f0)*R2Hl_acc + (f0*(1-fi))*R2Hi_acc)/(1-f0*fi);
d18O_acc = (R18O_acc/R18std-1)*1000;
d2H_acc = (R2H_acc/R2std-1)*1000;
dxs_acc = d2H_acc-8*d18O_acc;

fprintf('%8.2f %8.2f %8.2f %8.2f %8.2f %8.2f %8.2f \n',T-273.15,d18Ov,d2Hv,dxsv,rh,f,wconc);

% assign to output
data.T(n) = T;
data.f(n) = f;
data.rh(n) = rh;
data.Wconc(n) = wconc;
data.R18O(n) = R18Ov;
data.R2H(n) = R2Hv;
data.d18O(n) = d18Ov;
data.dD(n) = d2Hv;
data.dxs(n) = dxsv;
data.rh(n) = rh;
data.d18Oc(n) = d18Oc;
data.d2Hc(n) = d2Hc;
data.dxsc(n) = dxsc;
data.d18O_acc(n) = d18O_acc;
data.d2H_acc(n) = d2H_acc;
data.dxs_acc(n) = dxs_acc;

% iterate to next step
n = n+1;
end

%% for the circumstance of pseudoadiabatic cooling
% - establish the relationship between T and z
z = 0;
p = pressure(z);
n = 1;
for T = T0:-dt:-60+273.15
data.T(n) = T;
data.z(n) = z;
data.p(n) = p;
% the elevation change
ws = wsat(esat(T),p);
lr = gamma(ws,T); % lapse rate
dz = dt/lr; % dt = lr*dz
% the new elevation and pressure
z = z+dz;
p = pressure(z);
data.lr(n) = lr;

% iterate to next step
n = n+1;
end

end
% fin
</pre>

== Example of usage ==

'''1. Generate the desired data sets'''

<pre>
%% create data sets
% Rayleigh evaporation
T0 = 20+273.15;
d18O0 = -10; % close to Bergen precipitation average
d2H0 = -70;
h = 0.75; % relative humidity
de_ok = rayleigh_evaporation(T0,d18O0,d2H0,1,h); % in an open system, unsaturated (including kinetic effect)
de_oe = rayleigh_evaporation(T0,d18O0,d2H0,1); % in an open system, saturated (equilibrium)
de_cl = rayleigh_evaporation(T0,d18O0,d2H0,0); % in a closed system
de_CG = rayleigh_evaporation(T0,d18O0,d2H0,2,h); % C--G model

% Rayleigh condensation
T0 = 20+273.15;
RH0 = 0.75; % Craig-Gordon, 1965 (Fig. 15)
d18O0 = -13;
d2H0 = -94;
% > 1: using the constant supersaturation given as sice;
% = 1:
% = 0:
dc_ln = rayleigh_condensation(T0,RH0,d18O0,d2H0,0); % using linear formula Si = 1-0.004*T (in Celsius)
dc_no = rayleigh_condensation(T0,RH0,d18O0,d2H0,1); % meaning alpha_k = 1, thus no supersaturation, e = e_ice
dc_11 = rayleigh_condensation(T0,RH0,d18O0,d2H0,1.1); % using the constant supersaturation as given
</pre>

'''2. Plot Rayleigh evaporation and condensation profiles.'''

As an example, Fig. 2 is created using the data sets generated from the above step and using the plotting codes from below.

<pre>
%% plot Rayleigh evaporation and condensation model
fs = 14;

clear h
figure
set(gcf,'color','white','position',[0 0 1200 1150],'PaperPositionMode','auto');
% left_color = [0 0 0]; % black
% right_color = [0 0.4470 0.7410]; % blueish % blue [0 0 1];
% set(gcf,'defaultAxesColorOrder',[left_color; right_color]);

% Rayleigh evaporation
h(1) = subplot(2,2,1);
% set(h(1),'Position', [0.1 0.56 0.38 0.38]);
hold on
pe(1) = plot(de_ok.f,de_ok.d18Ol,'k-','linewidth',2);
pe(2) = plot(de_ok.f,de_ok.d18Ov,'k--','linewidth',2);
pe(3) = plot(de_ok.f,de_ok.d18Ov_acc,'k:','linewidth',2);
pe(4) = plot(de_oe.f,de_oe.d18Ol,'-','color',[0.6 0.6 0.6],'linewidth',2); %'color',[0.3010 0.7450 0.9330],
pe(5) = plot(de_oe.f,de_oe.d18Ov,'--','color',[0.6 0.6 0.6],'linewidth',2);
pe(6) = plot(de_oe.f,de_oe.d18Ov_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
pe(7) = plot(de_cl.f,de_cl.d18Ol,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(8) = plot(de_cl.f,de_cl.d18Ov,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(9) = plot(de_cl.f,de_cl.d18Ov_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
pe(10) = plot(de_CG.f,de_CG.d18Ol,'-','color',[0.8500 0.3250 0.0980],'linewidth',2);
pe(11) = plot(de_CG.f,de_CG.d18Ov,'--','color',[0.8500 0.3250 0.0980],'linewidth',2);
pe(12) = plot(de_CG.f,de_CG.d18Ov_acc,':','color',[0.8500 0.3250 0.0980],'linewidth',2);
ylim(h(1),[-30 40]);
xlabel('Residual water fraction','fontsize',fs);
ylabel(['\delta^{18}O / ',char(8240)],'fontsize',fs);
lgd1 = legend(h(1),pe(1:3),'residual water','instant vapour','total vapour removed','Location','northwest');
lgd1_pos = lgd1.Position;
lgd1.FontSize = fs;
% lgd1.Visible = 'off';
% 2nd axes
a2 = axes('position',get(h(1),'position'),'visible','off'); % create the same axes but set it invisible
% lgd2 = legend(a2,pe(4:6),'residual water','instant vapour','total vapour removed','Location','northwest');
% lgd2.FontSize = fs;
lgd2 = legend(a2,pe(4:6),'','','','location','northwest','box','off');
lgd2_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.58 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd2,'box','off','Position',lgd2_pos);
% 3rd axes
a3 = axes('position',get(gca,'position'),'visible','off'); % create the same axes but set it invisible
lgd3 = legend(a3,pe(7:9),'','','','location','northwest','box','off');
lgd3_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.79 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd3,'box','off','Position',lgd3_pos);
% % 4th axes
a4 = axes('position',get(gca,'position'),'visible','off'); % create the same axes but set it invisible
lgd4 = legend(a4,pe(10:12),'','','','location','northwest','box','off');
lgd4_pos = lgd1_pos+[-lgd1_pos(3)*0.304 -lgd1_pos(4)*0.88 0 lgd1_pos(4)*0.5]; % move the 2nd legend to the desired position
set(lgd4,'box','off','Position',lgd4_pos);
% add text
text(h(1),0.41,8.5,'open','FontSize',fs,'Rotation',30)
text(h(1),0.30,13.2,'(unsaturated)','FontSize',fs,'Rotation',53)
text(h(1),0.60,-3,'open','FontSize',fs,'Rotation',15,'color',[0.6 0.6 0.6])
text(h(1),0.48,-0.5,'(saturated)','FontSize',fs,'Rotation',20,'color',[0.6 0.6 0.6])
text(h(1),0.75,-10,'closed','FontSize',fs,'Rotation',7,'Color',[0.3010 0.7450 0.9330])
text(h(1),0.8,1.5,'C-G model','color',[0.8500 0.3250 0.0980],'FontSize',fs,'Rotation',15)

h(3) = subplot(2,2,3);
% set(h(3),'Position', [0.1 0.1 0.38 0.38]);
hold on
plot(de_ok.f,de_ok.dxsl,'k-','linewidth',2)
plot(de_ok.f,de_ok.dxsv,'k--','linewidth',2)
plot(de_ok.f,de_ok.dxsv_acc,'k:','linewidth',2)
plot(de_oe.f,de_oe.dxsl,'-','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_oe.f,de_oe.dxsv,'--','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_oe.f,de_oe.dxsv_acc,':','color',[0.6 0.6 0.6],'linewidth',2)
plot(de_cl.f,de_cl.dxsl,'-','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_cl.f,de_cl.dxsv,'--','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_cl.f,de_cl.dxsv_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2)
plot(de_CG.f,de_CG.dxsl,'-','color',[0.8500 0.3250 0.0980],'linewidth',2)
plot(de_CG.f,de_CG.dxsv,'--','color',[0.8500 0.3250 0.0980],'linewidth',2)
plot(de_CG.f,de_CG.dxsv_acc,':','color',[0.8500 0.3250 0.0980],'linewidth',2)
ylim(h(3),[-60 70]);
set(h(3),'ytick',-60:20:65);
xlabel('Residual water fraction','fontsize',fs);
ylabel(['\itd / ',char(8240)],'fontsize',fs);

% Rayleigh condensation
h(4) = subplot(2,2,4);
% set(h(4),'Position', [0.56 0.1 0.38 0.38]);
hold on
pc(4) = plot(dc_no.Wconc,dc_no.dxsc,'-','color',[0.6 0.6 0.6],'linewidth',2);
pc(5) = plot(dc_no.Wconc,dc_no.dxs,'--','color',[0.6 0.6 0.6],'linewidth',2);
pc(6) = plot(dc_no.Wconc,dc_no.dxs_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
ylim(gca,[-20 50]);
xlabel('Water mixing ratio / ppmv','fontsize',fs);
set(gca,'XTick',2000:3000:16000);
ylabel(['\itd / ',char(8240)],'fontsize',fs);
% 2nd axis
ax1_pos = get(gca,'position'); % position of first axes
axes('Position',ax1_pos,'XAxisLocation','top','YAxisLocation','right','Color','none','YTickLabel','','FontSize',fs,'TickDir','out');
hold on
pc(1) = plot(dc_ln.f,dc_ln.dxsc,'k-','linewidth',2); % [0.3010 0.7450 0.9330]
pc(2) = plot(dc_ln.f,dc_ln.dxs,'k--','linewidth',2);
pc(3) = plot(dc_ln.f,dc_ln.dxs_acc,'k:','linewidth',2);
% pc(7) = plot(dc_11.f,dc_11.dxsc,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(8) = plot(dc_11.f,dc_11.dxs,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(9) = plot(dc_11.f,dc_11.dxs_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
ylim(gca,[-20 50]);
xlabel('Residual vapour fraction','fontsize',fs);
% 3rd axis
axes('Position',ax1_pos+[0 0 0 -ax1_pos(4)],'XAxisLocation','top','YColor','w','YTick',[],'Color','none','TickDir','out','FontSize',fs);
hold on
pc(7) = plot(dc_ln.Wconc,20*ones(size(dc_ln.Wconc)),'k-'); % [0.3010 0.7450 0.9330]
ylim(gca,[-20 50]);
xlabel('T / °C','fontsize',fs);
set(gca,'XTick',[dc_ln.Wconc(81) dc_ln.Wconc(61:-10:11)],'XTickLabel',[-20 -10:5:15])

h(2) = subplot(2,2,2);
% set(h(2),'Position', [0.56 0.56 0.38 0.38]);
hold on
pc(4) = plot(dc_no.Wconc,dc_no.d18Oc,'-','color',[0.6 0.6 0.6],'linewidth',2); % [0 0.4470 0.7410]
pc(5) = plot(dc_no.Wconc,dc_no.d18O,'--','color',[0.6 0.6 0.6],'linewidth',2);
pc(6) = plot(dc_no.Wconc,dc_no.d18O_acc,':','color',[0.6 0.6 0.6],'linewidth',2);
ylim(h(2),[-60 -2]);
xlabel('Water mixing ratio / ppmv','fontsize',fs);
set(gca,'XTick',2000:3000:16000);
ylabel(['\delta^{18}O / ',char(8240)],'fontsize',fs);
% 2nd axis
ax1_pos = get(gca,'position'); % position of first axes
axes('Position',ax1_pos,'XAxisLocation','top','YAxisLocation','right','Color','none','YTickLabel','','FontSize',fs,'TickDir','out');
hold on
pc(1) = plot(dc_ln.f,dc_ln.d18Oc,'k-','linewidth',2); % [0.3010 0.7450 0.9330]
pc(2) = plot(dc_ln.f,dc_ln.d18O,'k--','linewidth',2);
pc(3) = plot(dc_ln.f,dc_ln.d18O_acc,'k:','linewidth',2);
% pc(7) = plot(dc_11.f,dc_11.d18Oc,'-','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(8) = plot(dc_11.f,dc_11.d18O,'--','color',[0.3010 0.7450 0.9330],'linewidth',2);
% pc(9) = plot(dc_11.f,dc_11.d18O_acc,':','color',[0.3010 0.7450 0.9330],'linewidth',2);
ylim(gca,[-60 -2]);
xlabel('Residual vapour fraction','fontsize',fs);
lg = legend(h(2),pc(1:3),'instant liquid/ice','residual vapour','total liquid/ice removed');
% lg = legend(h(2),pc(4:6),'instant liquid/ice','residual vapour','total liquid/ice removed');
set(lg,'Position',[0.69 0.66 0.20 0.06],'FontSize',fs);
lg_pos = lg.Position;
% 3rd axis
axes('Position',ax1_pos+[0 -ax1_pos(4)*0.2 0 -ax1_pos(4)*0.8],'XAxisLocation','top','YColor','w','YTick',[],'Color','none');
hold on
pc(7) = plot(dc_ln.Wconc,-2+zeros(size(dc_ln.d18Oc)),'k-'); % [0.3010 0.7450 0.9330]
ylim(gca,[-60 -2]);
xlabel('T / °C','fontsize',fs);
set(gca,'XTick',[dc_ln.Wconc(81) dc_ln.Wconc(61:-10:11)],'XTickLabel',[-20 -10:5:15],'FontSize',fs,'TickDir','out');
lg2 = legend(gca,pc(4:6),'','','','location','east','box','off');
lg2_pos = lg_pos+[-lg_pos(3)*0.405 +lg_pos(4)*0.02 0 lg_pos(4)*0.117]; % move the 2nd legend to the desired position
set(lg2,'box','off','Position',lg2_pos);
% add text
text(h(2),1300,-36,'super','FontSize',fs,'Rotation',65)
text(h(2),2150,-27.5,'saturation','FontSize',fs,'Rotation',50)
text(h(2),1200,-25,'saturation','FontSize',fs,'Rotation',50,'Color',0.6*[1 1 1])

set([h(1) h(3)],'XDir','reverse','box','on');
set(h(:),'color','none','FontSize',fs,'tickdir','out'); % ,'YAxisLocation','left','ticklength',[0 0],'ygrid','on','xgrid','on'

annotation('textbox',[0.05 0.96 0.02 0.02],'String','(a)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.49 0.96 0.02 0.02],'String','(b)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.05 0.48 0.02 0.02],'String','(c)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');
annotation('textbox',[0.49 0.48 0.02 0.02],'String','(d)','FitBoxToText','on','FontSize',fs+6,'LineStyle','none');

% print('-depsc','-r300','/scratch/home/figs/thesis/Rayleigh_model_plot');
% print('-dpng','-r300','/scratch/home/figs/thesis/Rayleigh_model_plot');
</pre>

WaterSip

2021-01-15T08:43:25Z

Hso039:

===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 [[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]].

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

====Creating mask files====

WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.

The procedure described here uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.

Required python packages [tested version]: numpy [1.19.1], shapely [1.6.4.post1], netCDF4 [1.5.3] and if loading from a csv, pandas [1.1.3]

Optional packages (for plotting): matplotlib [3.3.1], cartopy [0.16.0]

[[File:watersip_mask-guide_cut.png|400px]]
Figure: Example for Scandinavia

''Basic principle:''

Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed).
This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points).
After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.

<pre>
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.
</pre>

''Input:''

list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.

global meshgrid with a given resolution

''Output:''

Boolean mask of False and True in the shape of the meshgrid lat-lon

After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:

<pre>
cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
</pre>

For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to
[[https://gist.github.com/pelson/9785576]]

[[MaskCode|Python program code available here|]]

=== 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:

*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: <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>

----

====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: <code>uptakeThreshold = 0.2</code>

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

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

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

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

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

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

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

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

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

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

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

;analyzeVapour (boolean)
: Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters also need modification. Typically, one will set the <code>precipitation threshold</code> to a small or even positive number, and the <code>arrivalRHMin</code> to 0 and <code>arrivalRHMax</code> to 110 to include all arriving trajectories. It is often preferrable then to set the <code>arrivalAltMax</code> to values of around 1000m for surface station measurements, for example. If <code>analyzeVapour</code> is 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. Example: <code>analyzeVapour = 1</code>

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

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

----

====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: <code>stepFile = 1</code>

;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>

;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>

;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>

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

;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</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>

;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>

;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <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). Example: <code>saveMean = 0</code>

----

====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: <code>sourcesBoundaryLayer = 1</code>

;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: <code>sourcesFreeTroposphere = 1</code>

;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: <code>evaporationMinusPrecipitation = 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>

;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>
[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
</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*.

{| class="wikitable"
! 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*.

{| class="wikitable"
! 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:

{| class="wikitable"
! 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.

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

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

{| class="wikitable"
! 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*

{| class="wikitable"
! 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.

{| class="wikitable"
! 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.

File:Watersip mask-guide cut.png

2021-01-15T08:42:58Z

Hso039: File uploaded with MsUpload

File uploaded with MsUpload

WaterSip

2021-01-15T08:41:50Z

Hso039:

===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 [[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]].

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

====Creating mask files====

WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.

The procedure described here uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.

Required python packages [tested version]: numpy [1.19.1], shapely [1.6.4.post1], netCDF4 [1.5.3] and if loading from a csv, pandas [1.1.3]

Optional packages (for plotting): matplotlib [3.3.1], cartopy [0.16.0]

[[File:watersip_mask-guide.png|300px]]
Figure: Example for Scandinavia

''Basic principle:''

Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed).
This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points).
After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.

<pre>
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.
</pre>

''Input:''

list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.

global meshgrid with a given resolution

''Output:''

Boolean mask of False and True in the shape of the meshgrid lat-lon

After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:

<pre>
cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
</pre>

For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to
[[https://gist.github.com/pelson/9785576]]

[[MaskCode|Python program code available here|]]

=== 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:

*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: <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>

----

====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: <code>uptakeThreshold = 0.2</code>

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

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

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

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

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

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

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

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

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

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

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

;analyzeVapour (boolean)
: Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters also need modification. Typically, one will set the <code>precipitation threshold</code> to a small or even positive number, and the <code>arrivalRHMin</code> to 0 and <code>arrivalRHMax</code> to 110 to include all arriving trajectories. It is often preferrable then to set the <code>arrivalAltMax</code> to values of around 1000m for surface station measurements, for example. If <code>analyzeVapour</code> is 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. Example: <code>analyzeVapour = 1</code>

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

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

----

====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: <code>stepFile = 1</code>

;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>

;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>

;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>

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

;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</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>

;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>

;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <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). Example: <code>saveMean = 0</code>

----

====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: <code>sourcesBoundaryLayer = 1</code>

;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: <code>sourcesFreeTroposphere = 1</code>

;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: <code>evaporationMinusPrecipitation = 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>

;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>
[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
</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*.

{| class="wikitable"
! 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*.

{| class="wikitable"
! 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:

{| class="wikitable"
! 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.

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

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

{| class="wikitable"
! 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*

{| class="wikitable"
! 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.

{| class="wikitable"
! 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.

MaskCode

2021-01-15T08:40:35Z

Hso039: Created page with "<pre> #!/usr/bin/env python3 # -*- coding: utf-8 -*- """ Created on Mon Jan 11 16:54:46 2021 @author: mika """ #mask creation: import numpy as np import shapely as shp #no ca..."

<pre>
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""
Created on Mon Jan 11 16:54:46 2021

@author: mika
"""
#mask creation:
import numpy as np
import shapely as shp #no canonical shortname
import shapely.vectorized #vectorized version has to be loaded in separately
import pandas as pd #optional, only for loading in coordinates from csv

#netcdf file creation:
import netCDF4 as nc4

#plotting:
import matplotlib.pyplot as plt
import matplotlib.colors as mcolors
import cartopy.crs as ccrs
import cartopy.feature as cfeature
import matplotlib.patches as mpatches #for artificial legends
import matplotlib.lines as mlines #for artificial legends

#unsure:
#from cartopy import config
#import copy #from python, but because of cmap copying

#if warning due to cartopy and matplotlib versions clashing:
#whether you have this problem and need this will depend on your specific cartopy and matplotlib versions
from matplotlib.axes import Axes
from cartopy.mpl.geoaxes import GeoAxes
GeoAxes._pcolormesh_patched = Axes.pcolormesh

# %% setup global grid and polygon

#global grid, points to check for:

res=0.25 # resolution in degrees
global_lats=np.arange(-90,90+res,res)
global_lons=np.arange(-180,180+res,res)
x, y = np.meshgrid(global_lons,global_lats) #creates meshgrid of size lats*lons

# the polygon, our mask:
#df=pd.read_csv('coords_scandinavia.csv')
#coordinates=list(zip(df.lon,df.lat))

#if not loading in a csv-file. coordinates needs to be a python LIST of TUPLE pairs of (lon,lat) (x,y)
coordinates=\
[(31.25, 69.75), (23.75, 66.0), (20.0, 62.0), (20.0, 55.25), (15.0, 54.75),(13.0, 55.0),
(12.0, 54.5), (10.75, 54.0), (8.75, 54.0), (8.5, 54.4), (4.0, 54.5), (4.0, 72.0), (31.0, 72.0)]

nodes=coordinates.copy() #needs to be copy or otherwise appends updates with the appending below
nodes.append(coordinates[0]) #polygon needs to be closed, so first point is endpointt

#create polygon:
geom=shp.geometry.Polygon(nodes)

# %% calcuate boolean mask:
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator. if either of the elements are true, result is true. if both are false, false.

# %% super quick plotting for checking

#matplotlibs imshow is by far the quickest for such dense plotting (1M points if res=0.25
#quicklook plot, NOT in geographical projection
#imshow uses ij indexing, so we use the origin argument

fig, ax = plt.subplots(3, 1, figsize=(14,25))
cmap='bwr'
ax[0].imshow(mask_inner,origin='lower',cmap=cmap)
ax[1].imshow(mask_edge,origin='lower',cmap=cmap)
ax[2].imshow(mask_full,origin='lower',cmap=cmap)

ax[0].set_title('inner mask')
ax[1].set_title('edge mask')
ax[2].set_title('combined mask')

# for ax in axs.ravel():
# ax.grid(b=True,which='major',axis='x',color='k',alpha=0.4,linestyle='--')
# ax.set_xticks(months)
# ax.set_xticklabels([x[0:3] for x in monthnames],rotation=90,ha='center')

# %% geographical global map:

dataproj=ccrs.PlateCarree()
mapproj=ccrs.PlateCarree() #regular, fine for global

fig, ax = plt.subplots(1, 1, subplot_kw=dict(projection=mapproj), figsize=(14,14))
ax.set_global()
#ax.set_extent((3,27,53,73),crs=dataproj) #fine for scandinavia
ax.coastlines('10m') #choices 110m, 50m and 10m. m does not mean meter, but 1:Xmillion.
ax.add_feature(cfeature.BORDERS, linestyle=':')
ax.gridlines(color='k',alpha=0.3,linestyle=':')
pixelplot=ax.pcolormesh(global_lons,global_lats,mask_full,transform=dataproj,cmap='bwr')
ax.set_title('global map proj \n full mask')

# %% zoom-in geographical map standard projection

#we find coordinates to zoom by based on polygon bounds:
minlon,maxlon,minlat,maxlat=geom.bounds
zoomin=geom.bounds
pad=2 #padding in degrees, adjust as needed

dataproj=ccrs.PlateCarree()
mapproj=ccrs.PlateCarree() #regular, fine for global

fig, ax = plt.subplots(1, 1, subplot_kw=dict(projection=mapproj), figsize=(14,14))
#ax.set_global()
ax.set_extent((minlon-pad, maxlon+pad, minlat-pad, maxlat+pad),crs=dataproj)
ax.coastlines('10m') #choices 110m, 50m and 10m. m does not mean meter, but 1:Xmillion.
ax.add_feature(cfeature.BORDERS, linestyle=':')
ax.gridlines(color='k',alpha=0.3,linestyle=':')
pixelplot=ax.pcolormesh(global_lons,global_lats,mask_full,transform=dataproj,cmap='bwr')
ax.set_title('zoom-in standard map proj \n full mask')

#as you will see, this is not very good unless global mask or close to equator

# %% closeup-geograpical, better projection choice

#when switching to LambertConformal projection, or others, it can no longer handle a input data set that is global.
#it will simply plot nothing. Known bug/undesired behavoir in cartopy from cyclic points and transformations, or something like that
#we will therefore make a subset of the data based

minlon,maxlon,minlat,maxlat=geom.bounds
zoomin=geom.bounds
pad=5 #padding in degrees

#xs and ys to subset data with
xss1=np.where(global_lons==(minlon-pad))[0][0]
xss2=np.where(global_lons==(maxlon+pad))[0][0]
yss1=np.where(global_lats==(minlat-pad))[0][0]
yss2=np.where(global_lats==(maxlat+pad))[0][0]
mask_inner_subset=mask_inner[yss1:yss2+1,xss1:xss2+1]
mask_edge_subset=mask_edge[yss1:yss2+1,xss1:xss2+1]

dataproj=ccrs.PlateCarree()
#mapproj=ccrs.PlateCarree()
#this specific mapproj and settings are nice for Scandinavia, specifically.
#test different projections/settings to fit your mask

mapproj=ccrs.LambertConformal(central_longitude=8, central_latitude=60,
false_easting=0.0, false_northing=0.0, secant_latitudes=None,
standard_parallels=None, globe=None, cutoff=-30)

fig, ax = plt.subplots(1, 1, subplot_kw=dict(projection=mapproj), figsize=(14,14))
#ax1.set_global()
ax.set_extent((3,27,53,73),crs=dataproj) #fine for scandinavia
ax.coastlines('10m') #choices 110m, 50m and 10m. m does not mean meter, but 1:Xmillion.
ax.add_feature(cfeature.BORDERS, linestyle=':')
ax.gridlines(color='k',alpha=0.3,linestyle=':')

#matplotlib.colors.to_rgba(c, alpha=None)

alpha=0.3
edgeplot=ax.pcolormesh(global_lons[xss1:xss2+1],global_lats[yss1:yss2+1],mask_inner_subset,
transform=dataproj,cmap='Reds',shading='auto',edgecolor='lightgrey',alpha=alpha,label='_inner')

innerplot=ax.pcolormesh(global_lons[xss1:xss2+1],global_lats[yss1:yss2+1],mask_edge_subset,
transform=dataproj,cmap='Blues',shading='auto',edgecolor='lightgrey',alpha=alpha,label='_edge')

xs=[x[0] for x in coordinates]
ys=[y[1] for y in coordinates]
nodesplot=ax.scatter(xs,ys,s=50,c='yellow',transform=dataproj,marker='o',label='_nodes')

pathplot=ax.add_geometries([geom],dataproj,facecolor='none', edgecolor='green',label='_path')

ax.set_title('better projection zoom in \n inner, edge, nodes and path')

# #make artifical legend elements:
# note: the hidden _labels in the plots are because else it makes plotting really, really show as it checks for a label first

red_patch = mpatches.Patch(color=mcolors.to_rgba('red',alpha=alpha), label='inner points')
blue_patch = mpatches.Patch(color=mcolors.to_rgba('blue',alpha=alpha), label='edge points')
yellow_dots = mlines.Line2D([],[],color='yellow',marker='o',linestyle=None, label='nodes')
black_line = mlines.Line2D([],[],color='green',marker=None,linestyle='-', label='path')

ax.legend(handles=[red_patch,blue_patch,yellow_dots,black_line],loc='upper right')

# %% make netcdf file

#outcommented now. only comment in when making.
#remember you cannot change in an already created netcdf file, so make sure you create a new one first

# homemade_mask=nc4.Dataset('homemade_mask.nc','w',format='NETCDF4')

# lon = homemade_mask.createDimension("lon", global_lons.size)
# lon = homemade_mask.createVariable("lon", "f8",("lon"), zlib=True)
# lon[:]=global_lons #put data in

# lon.units="degrees_east"
# lon.standard_name="longitude"
# lon.long_name="longitude"

# lat = homemade_mask.createDimension("lat", global_lats.size)
# lat = homemade_mask.createVariable("lat", "f8",("lat"), zlib=True)
# lat[:]=global_lats #put data in

# lat.units="degrees_north"
# lat.standard_name="laitude"
# lat.long_name="laitude"

# time = homemade_mask.createDimension("time",None)
# time = homemade_mask.createVariable("time", "f8", ("time"), zlib=True)

# tunits='days since 0001-01-01'
# calendar='standard'
# time.units=tunits
# time.calendar=calendar
# time.standard_name="time"
# time[:]=0 #it needs atleast one time to work with watersip

# mask = homemade_mask.createVariable("mask", "f8", ("time","lat","lon"), zlib=True)
# mask[0,:,:]=mask_full #put the mask data in
# mask.units="mm/day"
# mask.xmin=-180
# mask.xmax=180
# mask.xstag=180
# mask.ymin=-90
# mask.ymax=90
# mask.ystag=90

# # time = mob_flux.createDimension("time",None)

# # times = mob_flux.createVariable("time","f8",("time"),zlib=True)

# # times.units = tunits
# # times.calendar = calendar
# # dates=fluxdata_5s.index.to_pydatetime()
# # times[:] = nc4.date2num(dates, units=tunits, calendar=calendar)

# homemade_mask.close() #remember to close the file

# %% OUTSIDE PYTHON

"""
in a terminal, navigate to where you newly created mask file is
then use
"cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
"
"""
</pre>

WaterSip

2021-01-15T08:40:03Z

Hso039:

===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 [[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]].

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

====Creating mask files====

WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.

The procedure described here uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.

Required python packages [tested version]: numpy [1.19.1], shapely [1.6.4.post1], netCDF4 [1.5.3] and if loading from a csv, pandas [1.1.3]

Optional packages (for plotting): matplotlib [3.3.1], cartopy [0.16.0]

[[File:watersip_mask-guide.png|600px]]
Figure: Example for Scandinavia

''Basic principle:''

Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed).
This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points).
After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.

<pre>
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.
</pre>

''Input:''

list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.

global meshgrid with a given resolution

''Output:''

Boolean mask of False and True in the shape of the meshgrid lat-lon

After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:

<pre>
cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
</pre>

For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to
[[https://gist.github.com/pelson/9785576]]

[[MaskCode|Python program code available here|]]

=== 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:

*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: <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>

----

====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: <code>uptakeThreshold = 0.2</code>

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

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

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

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

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

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

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

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

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

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

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

;analyzeVapour (boolean)
: Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters also need modification. Typically, one will set the <code>precipitation threshold</code> to a small or even positive number, and the <code>arrivalRHMin</code> to 0 and <code>arrivalRHMax</code> to 110 to include all arriving trajectories. It is often preferrable then to set the <code>arrivalAltMax</code> to values of around 1000m for surface station measurements, for example. If <code>analyzeVapour</code> is 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. Example: <code>analyzeVapour = 1</code>

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

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

----

====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: <code>stepFile = 1</code>

;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>

;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>

;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>

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

;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</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>

;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>

;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <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). Example: <code>saveMean = 0</code>

----

====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: <code>sourcesBoundaryLayer = 1</code>

;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: <code>sourcesFreeTroposphere = 1</code>

;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: <code>evaporationMinusPrecipitation = 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>

;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>
[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
</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*.

{| class="wikitable"
! 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*.

{| class="wikitable"
! 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:

{| class="wikitable"
! 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.

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

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

{| class="wikitable"
! 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*

{| class="wikitable"
! 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.

{| class="wikitable"
! 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.

WaterSip

2021-01-15T08:35:17Z

Hso039:

===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 [[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]].

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

====Creating mask files====

WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.

The procedure described here uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.

Required python packages [tested version]: numpy [1.19.1], shapely [1.6.4.post1], netCDF4 [1.5.3] and if loading from a csv, pandas [1.1.3]

Optional packages (for plotting): matplotlib [3.3.1], cartopy [0.16.0]

[[File:watersip_mask-guide.png]]
Figure: Example for Scandinavia

''Basic principle:''

Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed).
This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points).
After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.

<pre>
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.
</pre>

''Input:''

list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.

global meshgrid with a given resolution

''Output:''

Boolean mask of False and True in the shape of the meshgrid lat-lon

After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:

<pre>
cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
</pre>

For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to
[[https://gist.github.com/pelson/9785576]]

[Program code available here]

=== 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:

*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: <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>

----

====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: <code>uptakeThreshold = 0.2</code>

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

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

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

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

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

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

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

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

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

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

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

;analyzeVapour (boolean)
: Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters also need modification. Typically, one will set the <code>precipitation threshold</code> to a small or even positive number, and the <code>arrivalRHMin</code> to 0 and <code>arrivalRHMax</code> to 110 to include all arriving trajectories. It is often preferrable then to set the <code>arrivalAltMax</code> to values of around 1000m for surface station measurements, for example. If <code>analyzeVapour</code> is 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. Example: <code>analyzeVapour = 1</code>

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

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

----

====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: <code>stepFile = 1</code>

;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>

;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>

;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>

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

;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</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>

;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>

;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <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). Example: <code>saveMean = 0</code>

----

====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: <code>sourcesBoundaryLayer = 1</code>

;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: <code>sourcesFreeTroposphere = 1</code>

;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: <code>evaporationMinusPrecipitation = 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>

;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>
[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
</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*.

{| class="wikitable"
! 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*.

{| class="wikitable"
! 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:

{| class="wikitable"
! 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.

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

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

{| class="wikitable"
! 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*

{| class="wikitable"
! 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.

{| class="wikitable"
! 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.

WaterSip

2021-01-15T08:33:13Z

Hso039:

===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 [[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]].

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

====Creating mask files====

WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.

The procedure described here uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.

Required python packages [tested version]: numpy [1.19.1], shapely [1.6.4.post1], netCDF4 [1.5.3] and if loading from a csv, pandas [1.1.3]

Optional packages (for plotting): matplotlib [3.3.1], cartopy [0.16.0]

[[File:watersip_mask-guide.png|400px]]
Figure: Example for Scandinavia

''Basic principle:''

Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed).
This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points).
After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.

<pre>
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.
</pre>

''Input:''

list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.

global meshgrid with a given resolution

''Output:''

Boolean mask of False and True in the shape of the meshgrid lat-lon

After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:

<pre>
cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
</pre>

For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to
[[https://gist.github.com/pelson/9785576]]

=== 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:

*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: <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>

----

====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: <code>uptakeThreshold = 0.2</code>

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

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

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

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

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

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

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

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

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

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

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

;analyzeVapour (boolean)
: Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters also need modification. Typically, one will set the <code>precipitation threshold</code> to a small or even positive number, and the <code>arrivalRHMin</code> to 0 and <code>arrivalRHMax</code> to 110 to include all arriving trajectories. It is often preferrable then to set the <code>arrivalAltMax</code> to values of around 1000m for surface station measurements, for example. If <code>analyzeVapour</code> is 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. Example: <code>analyzeVapour = 1</code>

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

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

----

====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: <code>stepFile = 1</code>

;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>

;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>

;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>

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

;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</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>

;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>

;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <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). Example: <code>saveMean = 0</code>

----

====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: <code>sourcesBoundaryLayer = 1</code>

;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: <code>sourcesFreeTroposphere = 1</code>

;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: <code>evaporationMinusPrecipitation = 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>

;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>
[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
</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*.

{| class="wikitable"
! 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*.

{| class="wikitable"
! 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:

{| class="wikitable"
! 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.

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

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

{| class="wikitable"
! 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*

{| class="wikitable"
! 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.

{| class="wikitable"
! 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.

File:Watersip mask-guide.png

2021-01-15T08:32:11Z

Hso039: Hso039 uploaded a new version of File:Watersip mask-guide.png

File uploaded with MsUpload

WaterSip

2021-01-15T08:30:44Z

Hso039:

===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 [[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]].

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

====Creating mask files====

WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.

The procedure described here uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.

Required python packages [tested version]: numpy [1.19.1], shapely [1.6.4.post1], netCDF4 [1.5.3] and if loading from a csv, pandas [1.1.3]

Optional packages (for plotting): matplotlib [3.3.1], cartopy [0.16.0]

''Basic principle:''

Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed).
This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points).
After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.

<pre>
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.
</pre>

''Input:''

list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.

global meshgrid with a given resolution

''Output:''

Boolean mask of False and True in the shape of the meshgrid lat-lon

After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:

<pre>
cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
</pre>

For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to
[[https://gist.github.com/pelson/9785576]]

[[File:watersip_mask-guide.png|400px]]

=== 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:

*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: <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>

----

====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: <code>uptakeThreshold = 0.2</code>

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

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

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

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

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

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

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

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

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

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

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

;analyzeVapour (boolean)
: Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters also need modification. Typically, one will set the <code>precipitation threshold</code> to a small or even positive number, and the <code>arrivalRHMin</code> to 0 and <code>arrivalRHMax</code> to 110 to include all arriving trajectories. It is often preferrable then to set the <code>arrivalAltMax</code> to values of around 1000m for surface station measurements, for example. If <code>analyzeVapour</code> is 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. Example: <code>analyzeVapour = 1</code>

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

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

----

====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: <code>stepFile = 1</code>

;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>

;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>

;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>

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

;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</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>

;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>

;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <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). Example: <code>saveMean = 0</code>

----

====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: <code>sourcesBoundaryLayer = 1</code>

;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: <code>sourcesFreeTroposphere = 1</code>

;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: <code>evaporationMinusPrecipitation = 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>

;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>
[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
</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*.

{| class="wikitable"
! 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*.

{| class="wikitable"
! 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:

{| class="wikitable"
! 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.

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

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

{| class="wikitable"
! 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*

{| class="wikitable"
! 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.

{| class="wikitable"
! 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.

File:Watersip mask-guide.png

2021-01-15T08:30:27Z

Hso039: File uploaded with MsUpload

File uploaded with MsUpload

WaterSip

2021-01-15T08:27:19Z

Hso039:

===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 [[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]].

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

====Creating mask files====

WaterSip allows to define target regions not only by coordinates, but also by mask files. This is a short introduction to creating a mask for use with WaterSip.

The procedure described here uses python to create the netcdf file with the mask, and CDO to change the netcdf file format such that it can be read in by watersip.

<pre>
Python packages required [tested version]:
numpy [1.19.1], shapely [1.6.4.post1] and if loading from a csv, pandas [1.1.3])
netCDF4 [1.5.3]
optionally:
matplotlib [3.3.1], cartopy [0.16.0]
</pre>

''Basic principle:''

Using shapely’s .contains and .touches methods on a polygon with a point in vectorized version (taking a list of points instead of just one point for speed).
This enables more interactive editing on a grid spacing of 0.25x0.25 degree (1M grid points).
After calculation, the script performs a boolean OR operation on the two masks to get the combined of inner and edge points.

<pre>
mask_inner=shapely.vectorized.contains(geom, x, y) # - for interior points
mask_edge=shapely.vectorized.touches(geom, x, y) #- for edge points
mask_full=mask_inner|mask_edge # | is boolean OR bitwise (elementwise) operator.
</pre>

''Input:''

list of coordinates of pairs of lat, lon defining the nodes of the polygon mask.

global meshgrid with a given resolution

''Output:''

Boolean mask of False and True in the shape of the meshgrid lat-lon

After using python script, convert to a netCDF format readable by WaterSip by using the command below in a terminal where you newly created mask file:

<pre>
cdo -f nc2 copy mask-from-python.nc mask-to-watersip.nc
</pre>

For reference, and instructions on how to load political, and other, geometries straight from NaturalEarth dataset, go to
[[https://gist.github.com/pelson/9785576]]

=== 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:

*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: <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>

----

====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: <code>uptakeThreshold = 0.2</code>

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

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

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

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

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

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

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

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

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

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

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

;analyzeVapour (boolean)
: Parameter allowing to analyze vapour origin instead of precipitation origin. Setting this parameter to true considers all air parcels during arrival, not just the ones that precipitate according to the precipitation threshold. If set to true, the <code>precipitationThreshold</code> and <code>arrivalRHMin/Max</code> parameters also need modification. Typically, one will set the <code>precipitation threshold</code> to a small or even positive number, and the <code>arrivalRHMin</code> to 0 and <code>arrivalRHMax</code> to 110 to include all arriving trajectories. It is often preferrable then to set the <code>arrivalAltMax</code> to values of around 1000m for surface station measurements, for example. If <code>analyzeVapour</code> is 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. Example: <code>analyzeVapour = 1</code>

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

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

----

====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: <code>stepFile = 1</code>

;dayFile (boolean)
: write parameters on grid and series files averaged/accumulated for each day. Example: <code>dayFile = 1</code>

;monthFile (boolean)
: write parameters on grid and series files averaged/accumulated for each month. Example: <code>monthFile = 1</code>

;yearFile (boolean)
: write parameters on grid and series files averaged/accumulated for each year. Example: <code>yearFile = 1</code>

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

;staticFields (boolean)
: write static fields (land-sea mask and topography) onto grid files. Example: <code>staticFields = 1</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>

;skipTraj (boolean)
: write every nth trajectory to reduce traj file size (1:disabled, >=2: stride size). Example: <code>skipTraj = 1</code>

;saveHistogram (boolean)
: write histogram for selected parameters to a [[#Histogram files]] (0: disabled, 1:enabled). Example: <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). Example: <code>saveMean = 0</code>

----

====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: <code>sourcesBoundaryLayer = 1</code>

;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: <code>sourcesFreeTroposphere = 1</code>

;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: <code>evaporationMinusPrecipitation = 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>

;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>
[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
</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*.

{| class="wikitable"
! 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*.

{| class="wikitable"
! 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:

{| class="wikitable"
! 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.

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

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

{| class="wikitable"
! 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*

{| class="wikitable"
! 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.

{| class="wikitable"
! 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.

FLIIMP - FARLAB liquid water isotope measurements processor

2020-10-28T14:46:00Z

Hso039:

'''Installation'''

Get the current code from the [https://git.app.uib.no/farlab-codes/fliimp FLIIMP git repository]

(optional) copy the script FLIIMP.sh to your computer to start FLIIMP with a double click. Path settings need to be adjusted to your computer.

'''Running interactively'''

A. run the script

FLIIMP.m

with matlab

-or-

B. double-click the script

FLIIMP.sh

'''Running in batch mode'''

edit the file

batch_FLIIMP_example.m

to process a set of files. The example is using calls to the routine FLIIMP_batch.m

For further details, see the comments within the files.

== Detailed user instructions: ==

[https://vimeo.com/450466002 Watch the video walk-through here]

'''USING FLIIMP:'''

FLIIMP has 3 windows, that have to be completed in a fixed sequence.

'''1. Path settings, instrument and time'''

FLIIMP reads in the injection files from an instrument for a particular time, time range, or day. The Input file path for all injection files is specified in the first entry field.

FLIIMP creates a report on the calibrated data in HTML format within a new subfolder. The base output file path where the new output folder will be created is specified in the second entry field.

The instrument on which the liquid samples were measured is chosen from the pulldown list "Instrument".

Next, either a time range or specific files are selected. If choosing time range, only a date in format YYYYMMDD_HHMMSS needs to be given. If a range is given, all files that fall within the time period will be loaded. If only one date is given, either all files from that day (YYYYMMDD) or if a specific date with HHMMSS is given, that specific time will be looked for. The search path for files is combined from the input file path, the instrument, and the time range, for example

HKDS2038/IsotopeData/HKDS2038_IsoWater_20180912_120312.csv

At any point, the settings can be saved to a .mat file, or loaded from a previous run. The settings are saved and loaded across all three steps of the calibration, not for each step separately.

The button "Next >" advances to the second step. After clicking, please check the matlab command window for error messages or warnings.

Path settings are saved automatically to the file "FLIIMP_settings.mat" in your home directory ($HOME on linux/mac systems).

![FLiiMP_1](uploads/965cac19a14e7a9464ca2682c80fc74c/FLiiMP_1.png)

'''2. Sample screening and selection'''

In the second step, the data files for the selected period are loaded, and displayed for screening and selection. The table shows each identified sample by its "Identifier 1" value, them mean H2O concentration (in ppmv), and the standard deviation based on all samples.

The figure panels to the right show box-and-whisker plots of H2O vs. Injection number (top) and a selected isotope parameter from the Parameter drop-down below vs. Injection nr.

Clicking on a list item will display the injections of a sample. Using the checkmark "Exclude sample from processing" it is possible to disregard the currently selected sample from analysis. When the tickbox is checked, a "X" will appear in the list in front of an excluded sample.

Using the buttons "Exclude all" and "Include all", it is possible to set all samples in the list as excluded/included.

In the Injections line below, it is possible to exclude specific injections from the processing. If no sample is to be excluded, a value "-1" is displayed in the text entry box. To exclude injections 3 and 4 of the current sample, enter 3 and 4 separated by a space character in the input box. After choosing a different sample in the list, and combing back to the sample with excluded injections, these will be marked in red in the graphic display panels.

Manually excluded samples and injections are listed in the FLIIMP report in the section "Pre-processing".

![FLIIMP_2](uploads/0e50e2fd3cdb0e030f09cdf006fa2739/FLIIMP_2.png)

'''3. Run parameters and calibration settings'''

In the third step, the run parameters and calibration settings are entered. Each FARLAB project has a unique id that is entered in the first input field. The accounting can either be internal, collaborator, or external, which will influence the analysis cost (not considered in the report at present).

The report date defaults to the current date (format YYYYMMDD), but can be set to any other date. This date will be appended to the output directory name. The checkbox "Detailed report" determines whether additional analysis information is included in the report. For normal customers that are not part of FARLAB, the checkbox "Detailed report" should not be checked, as FARLAB-internal information about the instruments and processing are included in the detailed report.

Often, a project contains several runs/batches. The serial number or identifier of a run is entered in the field "Run ID" (for example "run01" and so on).

The next two lines should contain a name and email of the customer, and of the operator at FARLAB who can be contacted by the customer in case of questions.

Processing at FARLAB is based on local laboratory standards, that were calibrated on the VSMOW2-SLAP2 scale at several instances. The most current instance (run 3) is the default setting, for comparison purposes an older calibration run of the lab standards may be chosen. The delta values of the calibration standards are included in the report.

The calibration type can be either 1-point or 2-point linear. The third option, 3-point is not yet implemented. Using 1-point will use an average of the standard measurements in the beginning and end of a run. Using 2-point linear will linearly interpolate between the standard measurements in the beginning and end of a run. The option 2-point linear is recommended.

The input field "Calibration standards" should contain the chosen pair of calibration standards for slope and offset calibration. The first standard will be the offset correction, the first and second will be used in the slope correction. Standard names should appear as they are listed in the table visible in step 2. If more than 2 standards were measured, that are not used in the calibration, these names should be listed after the first two standards. If not included here, additional standard measurements will be treated as samples.

The field "Drift standard" contains the name of a standard that was repeatedly measured during the run but not used in calibration. It is displayed in a separate section in the report. The fields "Calibration standards" and "Drift standard" must not be empty. If no drift standard was in included in a run, use one of the calibration standards here.

The field "Averaging injections" sets how many of the last injections will be used in the averaging step. A number of 3 or 4 is currently recommended (without memory correction). The checkbox "include 17-O excess" needs to be checked for runs that are intended for 17-O excess analysis.

Pressing the button "Calibrate" that will start to produce the output report in HTML format. Watch the matlab command line window for progress, error messages and warnings.

Remember, settings across all three steps can be saved and loaded at any time using the buttons "Save" and "Load".

![FLIIMP_3](uploads/68266f681b7e2f2f21789771bcee76bc/FLIIMP_3.png)

==Detailed description of calibration procedure==

'''1. Identification of standards'''

- Calibration standards

- Drift standards

'''2. Calibration'''

- Using IAEA procedures

'''3. Instrument characteristics'''

- Cavity temperature, cavity pressure, warm-box temperature, DAS temperature

'''4. Quality flags'''

- Humidity variation

- Isotope variation

- Temperature variation

- Quality flags

'''5. Sample report'''

'''Reference'''

IAEA, 20xx

ERA5 reanalysis data

2020-10-26T21:40:26Z

Hso039:

Documentation of the ERA5 archive at GFI

GFI is building up an archive of ERA5 reanalysis data on the local linux system cyclone.hpc.uib.no. ERA5 supersedes the ERA-Interim reanalysis data, which ended in August 2019. More information about the ERA5 reanalysis data set is available [https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5 at ECMWF's ERA5 websites].

The ERA5 data files are available in a CF-compatible netCDF format on cyclone.hpc.uib.no and other computers that mount the UiB linux system at

/Data/gfi/share/era5

At GFI, we share the data format with the [https://iac.ethz.ch/group/atmospheric-dynamics.html Atmospheric Dynamics group at IAC, ETH Zürich, Switzerland]; the [https://www.imk-tro.kit.edu/7425.php LSDP group at Karlsruhe Institute of Technology, Germany]; and the [https://www.weizmann.ac.il/EPS/raveh-rubin/ Dynamical Meteorology Group, Weizmann Institute of Science, Rehovot, Israel]. The data are organised as follows

ml/ 3-hourly data on a regular 0.5 deg lat-lon grid, with model-level and pressure level files (see below)
pl/ pressure level data at different resolutions than 0.5x0.5 deg (not yet processed)

Data files are contained in subdirectories for each year and month:

ml/yyyy/mm/[B|H|P|Z]yyyymmdd_hh

where yyyy is the year, mm the two-digit month, dd the two-digit day, and hh the two-digit hours, and Bxxx, Hxxx, Pxxx, Zxxx are different file types, as described in the table below.

Until now, the years 1999-2018 have been retrieved, the period will successively be extended back to 1979, and forward in time.

The data files contain the following variables:

{| class="wikitable"
!colspan="6"|ERA5 data files
|-
|File name
|colspan="2"|Pyyyymmdd_hh
|colspan="1"|Zyyyymmdd_hh
|colspan="1"|Hyyyymmdd_hh
|colspan="1"|Byyyymmdd_hh
|-
|Leveltype
|Model level
|Surface
|Pressure
|Pressure
|Surface
|-
|Variables
|T, Q, U, V, OMEGA, LWC, IWC, RWC, SWC
|LSP, CP, SF, SSHF, SLHF, BLH, TCC, U10M, V10M, MSL, PS, SSTK
|Z, T, Q, U, V
|Z
|PS, MSL, TCC, U10M, V10M, SSTK, CI, D2M, T2M, TCW, TCWV, VIWVD, E, MN2T, MX2T, SI, TTR, TTRC, WG10, LSP, CP, SF, SSHF, SLHF, BLH
|-
|Levels
|40-137
| -
|900, 850, 800, 700, 600, 500, 400, 300, 250, 200, 100 hPa
|1000, 975, 950, 925, 900, 875, 850, 825, 800, 775, 750, 700, 650, 600, 550, 500, 450, 400, 350, 300, 250, 225, 200, 175, 150, 125, 100, 70, 50, 30, 20, 10, 70, 5, 3, 2, 1 hPa
| -
|-
|Times available
|colspan="5"|00, 03, 06, 09, 12, 15, 18, 21 UTC
|}

Note that the variables LSP, CP, SF, SSHF, SLHF, and BLH are derived as prognostic variables from the short-range forecast. Data valid at 00, 03, 06, 09 UTC are 06, 09, 12, 15 h forecast of the 18 UTC forecast of the previous day. Accordingly, data valid at 12, 15, 18, 21 UTC are 06, 09, 12, 15 h forecast of the 06 UTC forecast. The prognostic variables are accumulated over the previous 1 h.

Please see [https://confluence.ecmwf.int//display/CKB/ERA5+data+documentation#ERA5datadocumentation-Parameterlistings ECMWF ERA5 data documentation] for parameter abbreviations.

'''Conditions of use:''' When using the ERA5 data from this archive please make sure to reference "[https://cds.climate.copernicus.eu/cdsapp#!/home Copernicus Climate Change Service (C3S) (2017): ERA5: Fifth generation of ECMWF atmospheric reanalyses of the global climate. Copernicus Climate Change Service Climate Data Store (CDS)], date of citation" and acknowledge "ECMWF for providing ERA-5 data“. Also, please acknowledge "Michael Sprenger (ETH Zurich)“ for the support in providing the data.

ERA5 reanalysis data

2020-10-26T21:40:01Z

Hso039:

Documentation of the ERA5 archive at GFI

GFI is building up an archive of ERA5 reanalysis data on the local linux system cyclone.hpc.uib.no. ERA5 supersedes the ERA-Interim reanalysis data, which ended in August 2019. More information about the ERA5 reanalysis data set is available [https://www.ecmwf.int/en/forecasts/datasets/reanalysis-datasets/era5 at ECMWF's ERA5 websites].

The ERA5 data files are available in a CF-compatible netCDF format on cyclone.hpc.uib.no and other computers that mount the UiB linux system at

/Data/gfi/share/era5

At GFI, we share the data format with the [https://iac.ethz.ch/group/atmospheric-dynamics.html Atmospheric Dynamics group at IAC, ETH Zürich, Switzerland]; the [https://www.imk-tro.kit.edu/7425.php LSDP group at Karlsruhe Institute of Technology, Germany]; and the [https://www.weizmann.ac.il/EPS/raveh-rubin/ Dynamical Meteorology Group, Weizmann Institute of Science, Rehovot, Israel]. The data are organised as follows

ml/ 3-hourly data on a regular 0.5 deg latitude-longitude grid, including model-level files and pressure level files (see below)
pl/ pressure level data at different resolutions than 0.5x0.5 deg (not yet processed)

Data files are contained in subdirectories for each year and month:

ml/yyyy/mm/[B|H|P|Z]yyyymmdd_hh

where yyyy is the year, mm the two-digit month, dd the two-digit day, and hh the two-digit hours, and Bxxx, Hxxx, Pxxx, Zxxx are different file types, as described in the table below.

Until now, the years 1999-2018 have been retrieved, the period will successively be extended back to 1979, and forward in time.

The data files contain the following variables:

{| class="wikitable"
!colspan="6"|ERA5 data files
|-
|File name
|colspan="2"|Pyyyymmdd_hh
|colspan="1"|Zyyyymmdd_hh
|colspan="1"|Hyyyymmdd_hh
|colspan="1"|Byyyymmdd_hh
|-
|Leveltype
|Model level
|Surface
|Pressure
|Pressure
|Surface
|-
|Variables
|T, Q, U, V, OMEGA, LWC, IWC, RWC, SWC
|LSP, CP, SF, SSHF, SLHF, BLH, TCC, U10M, V10M, MSL, PS, SSTK
|Z, T, Q, U, V
|Z
|PS, MSL, TCC, U10M, V10M, SSTK, CI, D2M, T2M, TCW, TCWV, VIWVD, E, MN2T, MX2T, SI, TTR, TTRC, WG10, LSP, CP, SF, SSHF, SLHF, BLH
|-
|Levels
|40-137
| -
|900, 850, 800, 700, 600, 500, 400, 300, 250, 200, 100 hPa
|1000, 975, 950, 925, 900, 875, 850, 825, 800, 775, 750, 700, 650, 600, 550, 500, 450, 400, 350, 300, 250, 225, 200, 175, 150, 125, 100, 70, 50, 30, 20, 10, 70, 5, 3, 2, 1 hPa
| -
|-
|Times available
|colspan="5"|00, 03, 06, 09, 12, 15, 18, 21 UTC
|}

Note that the variables LSP, CP, SF, SSHF, SLHF, and BLH are derived as prognostic variables from the short-range forecast. Data valid at 00, 03, 06, 09 UTC are 06, 09, 12, 15 h forecast of the 18 UTC forecast of the previous day. Accordingly, data valid at 12, 15, 18, 21 UTC are 06, 09, 12, 15 h forecast of the 06 UTC forecast. The prognostic variables are accumulated over the previous 1 h.

Please see [https://confluence.ecmwf.int//display/CKB/ERA5+data+documentation#ERA5datadocumentation-Parameterlistings ECMWF ERA5 data documentation] for parameter abbreviations.

'''Conditions of use:''' When using the ERA5 data from this archive please make sure to reference "[https://cds.climate.copernicus.eu/cdsapp#!/home Copernicus Climate Change Service (C3S) (2017): ERA5: Fifth generation of ECMWF atmospheric reanalyses of the global climate. Copernicus Climate Change Service Climate Data Store (CDS)], date of citation" and acknowledge "ECMWF for providing ERA-5 data“. Also, please acknowledge "Michael Sprenger (ETH Zurich)“ for the support in providing the data.

FLIIMP - FARLAB liquid water isotope measurements processor

2020-09-18T07:33:43Z

Hso039:

'''Installation'''

Get the current code from the [https://git.app.uib.no/farlab-codes/fliimp FLIIMP git repository]

(optional) copy the script FLIIMP.sh to your computer to start FLIIMP with a double click. Path settings need to be adjusted to your computer.

'''Running interactively'''

A. run the script

FLIIMP.m

with matlab

-or-

B. double-click the script

FLIIMP.sh

'''Running in batch mode'''

edit the file

batch_FLIIMP_example.m

to process a set of files. The example is using calls to the routine FLIIMP_batch.m

For further details, see the comments within the files.

== Detailed user instructions: ==

[https://vimeo.com/450466002 Watch the video walk-through here]

'''USING FLIIMP:'''

FLIIMP has 3 windows, that have to be completed in a fixed sequence.

'''1. Path settings, instrument and time'''

FLIIMP reads in the injection files from an instrument for a particular time, time range, or day. The Input file path for all injection files is specified in the first entry field.

FLIIMP creates a report on the calibrated data in HTML format within a new subfolder. The base output file path where the new output folder will be created is specified in the second entry field.

The instrument on which the liquid samples were measured is chosen from the pulldown list "Instrument".

Next, either a time range or specific files are selected. If choosing time range, only a date in format YYYYMMDD_HHMMSS needs to be given. If a range is given, all files that fall within the time period will be loaded. If only one date is given, either all files from that day (YYYYMMDD) or if a specific date with HHMMSS is given, that specific time will be looked for. The search path for files is combined from the input file path, the instrument, and the time range, for example

HKDS2038/IsotopeData/HKDS2038_IsoWater_20180912_120312.csv

At any point, the settings can be saved to a .mat file, or loaded from a previous run. The settings are saved and loaded across all three steps of the calibration, not for each step separately.

The button "Next >" advances to the second step. After clicking, please check the matlab command window for error messages or warnings.

Path settings are saved automatically to the file "FLIIMP_settings.mat" in the local directory where FLIIMP.m is located.

![FLiiMP_1](uploads/965cac19a14e7a9464ca2682c80fc74c/FLiiMP_1.png)

'''2. Sample screening and selection'''

In the second step, the data files for the selected period are loaded, and displayed for screening and selection. The table shows each identified sample by its "Identifier 1" value, them mean H2O concentration (in ppmv), and the standard deviation based on all samples.

The figure panels to the right show box-and-whisker plots of H2O vs. Injection number (top) and a selected isotope parameter from the Parameter drop-down below vs. Injection nr.

Clicking on a list item will display the injections of a sample. Using the checkmark "Exclude sample from processing" it is possible to disregard the currently selected sample from analysis. When the tickbox is checked, a "X" will appear in the list in front of an excluded sample.

Using the buttons "Exclude all" and "Include all", it is possible to set all samples in the list as excluded/included.

In the Injections line below, it is possible to exclude specific injections from the processing. If no sample is to be excluded, a value "-1" is displayed in the text entry box. To exclude injections 3 and 4 of the current sample, enter 3 and 4 separated by a space character in the input box. After choosing a different sample in the list, and combing back to the sample with excluded injections, these will be marked in red in the graphic display panels.

Manually excluded samples and injections are listed in the FLIIMP report in the section "Pre-processing".

![FLIIMP_2](uploads/0e50e2fd3cdb0e030f09cdf006fa2739/FLIIMP_2.png)

'''3. Run parameters and calibration settings'''

In the third step, the run parameters and calibration settings are entered. Each FARLAB project has a unique id that is entered in the first input field. The accounting can either be internal, collaborator, or external, which will influence the analysis cost (not considered in the report at present).

The report date defaults to the current date (format YYYYMMDD), but can be set to any other date. This date will be appended to the output directory name. The checkbox "Detailed report" determines whether additional analysis information is included in the report. For normal customers that are not part of FARLAB, the checkbox "Detailed report" should not be checked, as FARLAB-internal information about the instruments and processing are included in the detailed report.

Often, a project contains several runs/batches. The serial number or identifier of a run is entered in the field "Run ID" (for example "run01" and so on).

The next two lines should contain a name and email of the customer, and of the operator at FARLAB who can be contacted by the customer in case of questions.

Processing at FARLAB is based on local laboratory standards, that were calibrated on the VSMOW2-SLAP2 scale at several instances. The most current instance (run 3) is the default setting, for comparison purposes an older calibration run of the lab standards may be chosen. The delta values of the calibration standards are included in the report.

The calibration type can be either 1-point or 2-point linear. The third option, 3-point is not yet implemented. Using 1-point will use an average of the standard measurements in the beginning and end of a run. Using 2-point linear will linearly interpolate between the standard measurements in the beginning and end of a run. The option 2-point linear is recommended.

The input field "Calibration standards" should contain the chosen pair of calibration standards for slope and offset calibration. The first standard will be the offset correction, the first and second will be used in the slope correction. Standard names should appear as they are listed in the table visible in step 2. If more than 2 standards were measured, that are not used in the calibration, these names should be listed after the first two standards. If not included here, additional standard measurements will be treated as samples.

The field "Drift standard" contains the name of a standard that was repeatedly measured during the run but not used in calibration. It is displayed in a separate section in the report. The fields "Calibration standards" and "Drift standard" must not be empty. If no drift standard was in included in a run, use one of the calibration standards here.

The field "Averaging injections" sets how many of the last injections will be used in the averaging step. A number of 3 or 4 is currently recommended (without memory correction). The checkbox "include 17-O excess" needs to be checked for runs that are intended for 17-O excess analysis.

Pressing the button "Calibrate" that will start to produce the output report in HTML format. Watch the matlab command line window for progress, error messages and warnings.

Remember, settings across all three steps can be saved and loaded at any time using the buttons "Save" and "Load".

![FLIIMP_3](uploads/68266f681b7e2f2f21789771bcee76bc/FLIIMP_3.png)

==Detailed description of calibration procedure==

'''1. Identification of standards'''

- Calibration standards

- Drift standards

'''2. Calibration'''

- Using IAEA procedures

'''3. Instrument characteristics'''

- Cavity temperature, cavity pressure, warm-box temperature, DAS temperature

'''4. Quality flags'''

- Humidity variation

- Isotope variation

- Temperature variation

- Quality flags

'''5. Sample report'''

'''Reference'''

IAEA, 20xx

FLIIMP - FARLAB liquid water isotope measurements processor

2020-09-18T07:32:45Z

Hso039:

==FLIIMP - FARLAB Liquid Injection Isotope Measurement Processor==

'''Installation'''

Get the current code from the [https://git.app.uib.no/farlab-codes/fliimp FLIIMP git repository]

(optional) copy the script FLIIMP.sh to your computer to start FLIIMP with a double click. Path settings need to be adjusted to your computer.

'''Running interactively'''

A. run the script

FLIIMP.m

with matlab

-or-

B. double-click the script

FLIIMP.sh

'''Running in batch mode'''

edit the file

batch_FLIIMP_example.m

to process a set of files. The example is using calls to the routine FLIIMP_batch.m

For further details, see the comments within the files.

== Detailed user instructions: ==

'''USING FLIIMP:'''

FLIIMP has 3 windows, that have to be completed in a fixed sequence.

'''1. Path settings, instrument and time'''

FLIIMP reads in the injection files from an instrument for a particular time, time range, or day. The Input file path for all injection files is specified in the first entry field.

FLIIMP creates a report on the calibrated data in HTML format within a new subfolder. The base output file path where the new output folder will be created is specified in the second entry field.

The instrument on which the liquid samples were measured is chosen from the pulldown list "Instrument".

Next, either a time range or specific files are selected. If choosing time range, only a date in format YYYYMMDD_HHMMSS needs to be given. If a range is given, all files that fall within the time period will be loaded. If only one date is given, either all files from that day (YYYYMMDD) or if a specific date with HHMMSS is given, that specific time will be looked for. The search path for files is combined from the input file path, the instrument, and the time range, for example

HKDS2038/IsotopeData/HKDS2038_IsoWater_20180912_120312.csv

At any point, the settings can be saved to a .mat file, or loaded from a previous run. The settings are saved and loaded across all three steps of the calibration, not for each step separately.

The button "Next >" advances to the second step. After clicking, please check the matlab command window for error messages or warnings.

Path settings are saved automatically to the file "FLIIMP_settings.mat" in the local directory where FLIIMP.m is located.

![FLiiMP_1](uploads/965cac19a14e7a9464ca2682c80fc74c/FLiiMP_1.png)

'''2. Sample screening and selection'''

In the second step, the data files for the selected period are loaded, and displayed for screening and selection. The table shows each identified sample by its "Identifier 1" value, them mean H2O concentration (in ppmv), and the standard deviation based on all samples.

The figure panels to the right show box-and-whisker plots of H2O vs. Injection number (top) and a selected isotope parameter from the Parameter drop-down below vs. Injection nr.

Clicking on a list item will display the injections of a sample. Using the checkmark "Exclude sample from processing" it is possible to disregard the currently selected sample from analysis. When the tickbox is checked, a "X" will appear in the list in front of an excluded sample.

Using the buttons "Exclude all" and "Include all", it is possible to set all samples in the list as excluded/included.

In the Injections line below, it is possible to exclude specific injections from the processing. If no sample is to be excluded, a value "-1" is displayed in the text entry box. To exclude injections 3 and 4 of the current sample, enter 3 and 4 separated by a space character in the input box. After choosing a different sample in the list, and combing back to the sample with excluded injections, these will be marked in red in the graphic display panels.

Manually excluded samples and injections are listed in the FLIIMP report in the section "Pre-processing".

![FLIIMP_2](uploads/0e50e2fd3cdb0e030f09cdf006fa2739/FLIIMP_2.png)

'''3. Run parameters and calibration settings'''

In the third step, the run parameters and calibration settings are entered. Each FARLAB project has a unique id that is entered in the first input field. The accounting can either be internal, collaborator, or external, which will influence the analysis cost (not considered in the report at present).

The report date defaults to the current date (format YYYYMMDD), but can be set to any other date. This date will be appended to the output directory name. The checkbox "Detailed report" determines whether additional analysis information is included in the report. For normal customers that are not part of FARLAB, the checkbox "Detailed report" should not be checked, as FARLAB-internal information about the instruments and processing are included in the detailed report.

Often, a project contains several runs/batches. The serial number or identifier of a run is entered in the field "Run ID" (for example "run01" and so on).

The next two lines should contain a name and email of the customer, and of the operator at FARLAB who can be contacted by the customer in case of questions.

Processing at FARLAB is based on local laboratory standards, that were calibrated on the VSMOW2-SLAP2 scale at several instances. The most current instance (run 3) is the default setting, for comparison purposes an older calibration run of the lab standards may be chosen. The delta values of the calibration standards are included in the report.

The calibration type can be either 1-point or 2-point linear. The third option, 3-point is not yet implemented. Using 1-point will use an average of the standard measurements in the beginning and end of a run. Using 2-point linear will linearly interpolate between the standard measurements in the beginning and end of a run. The option 2-point linear is recommended.

The input field "Calibration standards" should contain the chosen pair of calibration standards for slope and offset calibration. The first standard will be the offset correction, the first and second will be used in the slope correction. Standard names should appear as they are listed in the table visible in step 2. If more than 2 standards were measured, that are not used in the calibration, these names should be listed after the first two standards. If not included here, additional standard measurements will be treated as samples.

The field "Drift standard" contains the name of a standard that was repeatedly measured during the run but not used in calibration. It is displayed in a separate section in the report. The fields "Calibration standards" and "Drift standard" must not be empty. If no drift standard was in included in a run, use one of the calibration standards here.

The field "Averaging injections" sets how many of the last injections will be used in the averaging step. A number of 3 or 4 is currently recommended (without memory correction). The checkbox "include 17-O excess" needs to be checked for runs that are intended for 17-O excess analysis.

Pressing the button "Calibrate" that will start to produce the output report in HTML format. Watch the matlab command line window for progress, error messages and warnings.

Remember, settings across all three steps can be saved and loaded at any time using the buttons "Save" and "Load".

![FLIIMP_3](uploads/68266f681b7e2f2f21789771bcee76bc/FLIIMP_3.png)

==Detailed description of calibration procedure==

'''1. Identification of standards'''

- Calibration standards

- Drift standards

'''2. Calibration'''

- Using IAEA procedures

'''3. Instrument characteristics'''

- Cavity temperature, cavity pressure, warm-box temperature, DAS temperature

'''4. Quality flags'''

- Humidity variation

- Isotope variation

- Temperature variation

- Quality flags

'''5. Sample report'''

'''Reference'''

IAEA, 20xx

FLIIMP - FARLAB liquid water isotope measurements processor

2020-09-18T07:32:04Z

Hso039:

==FLIIMP - FARLAB Liquid Injection Isotope Measurement Processor==

'''Installation'''

Get the current code from the [https://git.app.uib.no/farlab-codes/fliimp FLIIMP git repository]

(optional) copy the script FLIIMP.sh to your computer to start FLIIMP with a double click. Path settings need to be adjusted to your computer.

'''Running interactively'''

A. run the script FLIIMP.m with matlab

-or-

B. double-click the script FLIIMP.sh

'''Running in batch mode'''

edit the file

batch_FLIIMP_example.m

to process a set of files. The example is using calls to the routine FLIIMP_batch.m

For further details, see the comments within the files.

== Detailed user instructions: ==

'''USING FLIIMP:'''

FLIIMP has 3 windows, that have to be completed in a fixed sequence.

'''1. Path settings, instrument and time'''

FLIIMP reads in the injection files from an instrument for a particular time, time range, or day. The Input file path for all injection files is specified in the first entry field.

FLIIMP creates a report on the calibrated data in HTML format within a new subfolder. The base output file path where the new output folder will be created is specified in the second entry field.

The instrument on which the liquid samples were measured is chosen from the pulldown list "Instrument".

Next, either a time range or specific files are selected. If choosing time range, only a date in format YYYYMMDD_HHMMSS needs to be given. If a range is given, all files that fall within the time period will be loaded. If only one date is given, either all files from that day (YYYYMMDD) or if a specific date with HHMMSS is given, that specific time will be looked for. The search path for files is combined from the input file path, the instrument, and the time range, for example

HKDS2038/IsotopeData/HKDS2038_IsoWater_20180912_120312.csv

At any point, the settings can be saved to a .mat file, or loaded from a previous run. The settings are saved and loaded across all three steps of the calibration, not for each step separately.

The button "Next >" advances to the second step. After clicking, please check the matlab command window for error messages or warnings.

Path settings are saved automatically to the file "FLIIMP_settings.mat" in the local directory where FLIIMP.m is located.

![FLiiMP_1](uploads/965cac19a14e7a9464ca2682c80fc74c/FLiiMP_1.png)

'''2. Sample screening and selection'''

In the second step, the data files for the selected period are loaded, and displayed for screening and selection. The table shows each identified sample by its "Identifier 1" value, them mean H2O concentration (in ppmv), and the standard deviation based on all samples.

The figure panels to the right show box-and-whisker plots of H2O vs. Injection number (top) and a selected isotope parameter from the Parameter drop-down below vs. Injection nr.

Clicking on a list item will display the injections of a sample. Using the checkmark "Exclude sample from processing" it is possible to disregard the currently selected sample from analysis. When the tickbox is checked, a "X" will appear in the list in front of an excluded sample.

Using the buttons "Exclude all" and "Include all", it is possible to set all samples in the list as excluded/included.

In the Injections line below, it is possible to exclude specific injections from the processing. If no sample is to be excluded, a value "-1" is displayed in the text entry box. To exclude injections 3 and 4 of the current sample, enter 3 and 4 separated by a space character in the input box. After choosing a different sample in the list, and combing back to the sample with excluded injections, these will be marked in red in the graphic display panels.

Manually excluded samples and injections are listed in the FLIIMP report in the section "Pre-processing".

![FLIIMP_2](uploads/0e50e2fd3cdb0e030f09cdf006fa2739/FLIIMP_2.png)

'''3. Run parameters and calibration settings'''

In the third step, the run parameters and calibration settings are entered. Each FARLAB project has a unique id that is entered in the first input field. The accounting can either be internal, collaborator, or external, which will influence the analysis cost (not considered in the report at present).

The report date defaults to the current date (format YYYYMMDD), but can be set to any other date. This date will be appended to the output directory name. The checkbox "Detailed report" determines whether additional analysis information is included in the report. For normal customers that are not part of FARLAB, the checkbox "Detailed report" should not be checked, as FARLAB-internal information about the instruments and processing are included in the detailed report.

Often, a project contains several runs/batches. The serial number or identifier of a run is entered in the field "Run ID" (for example "run01" and so on).

The next two lines should contain a name and email of the customer, and of the operator at FARLAB who can be contacted by the customer in case of questions.

Processing at FARLAB is based on local laboratory standards, that were calibrated on the VSMOW2-SLAP2 scale at several instances. The most current instance (run 3) is the default setting, for comparison purposes an older calibration run of the lab standards may be chosen. The delta values of the calibration standards are included in the report.

The calibration type can be either 1-point or 2-point linear. The third option, 3-point is not yet implemented. Using 1-point will use an average of the standard measurements in the beginning and end of a run. Using 2-point linear will linearly interpolate between the standard measurements in the beginning and end of a run. The option 2-point linear is recommended.

The input field "Calibration standards" should contain the chosen pair of calibration standards for slope and offset calibration. The first standard will be the offset correction, the first and second will be used in the slope correction. Standard names should appear as they are listed in the table visible in step 2. If more than 2 standards were measured, that are not used in the calibration, these names should be listed after the first two standards. If not included here, additional standard measurements will be treated as samples.

The field "Drift standard" contains the name of a standard that was repeatedly measured during the run but not used in calibration. It is displayed in a separate section in the report. The fields "Calibration standards" and "Drift standard" must not be empty. If no drift standard was in included in a run, use one of the calibration standards here.

The field "Averaging injections" sets how many of the last injections will be used in the averaging step. A number of 3 or 4 is currently recommended (without memory correction). The checkbox "include 17-O excess" needs to be checked for runs that are intended for 17-O excess analysis.

Pressing the button "Calibrate" that will start to produce the output report in HTML format. Watch the matlab command line window for progress, error messages and warnings.

Remember, settings across all three steps can be saved and loaded at any time using the buttons "Save" and "Load".

![FLIIMP_3](uploads/68266f681b7e2f2f21789771bcee76bc/FLIIMP_3.png)

==Detailed description of calibration procedure==

'''1. Identification of standards'''

- Calibration standards

- Drift standards

'''2. Calibration'''

- Using IAEA procedures

'''3. Instrument characteristics'''

- Cavity temperature, cavity pressure, warm-box temperature, DAS temperature

'''4. Quality flags'''

- Humidity variation

- Isotope variation

- Temperature variation

- Quality flags

'''5. Sample report'''

'''Reference'''

IAEA, 20xx

FLIIMP - FARLAB liquid water isotope measurements processor

2020-09-18T07:24:51Z

Hso039:

'''FLIIMP - FARLAB Liquid Injection Isotope Measurement Processor'''

Get the current code from the [https://git.app.uib.no/farlab-codes/fliimp FLIIMP git repository]

'''USING FLIIMP:'''

FLIIMP has 3 windows, that have to be completed in a fixed sequence.

'''1. Path settings, instrument and time'''

FLIIMP reads in the injection files from an instrument for a particular time, time range, or day. The Input file path for all injection files is specified in the first entry field.

FLIIMP creates a report on the calibrated data in HTML format within a new subfolder. The base output file path where the new output folder will be created is specified in the second entry field.

The instrument on which the liquid samples were measured is chosen from the pulldown list "Instrument".

Next, either a time range or specific files are selected. If choosing time range, only a date in format YYYYMMDD_HHMMSS needs to be given. If a range is given, all files that fall within the time period will be loaded. If only one date is given, either all files from that day (YYYYMMDD) or if a specific date with HHMMSS is given, that specific time will be looked for. The search path for files is combined from the input file path, the instrument, and the time range, for example

HKDS2038/IsotopeData/HKDS2038_IsoWater_20180912_120312.csv

At any point, the settings can be saved to a .mat file, or loaded from a previous run. The settings are saved and loaded across all three steps of the calibration, not for each step separately.

The button "Next >" advances to the second step. After clicking, please check the matlab command window for error messages or warnings.

Path settings are saved automatically to the file "FLIIMP_settings.mat" in the local directory where FLIIMP.m is located.

![FLiiMP_1](uploads/965cac19a14e7a9464ca2682c80fc74c/FLiiMP_1.png)

'''2. Sample screening and selection'''

In the second step, the data files for the selected period are loaded, and displayed for screening and selection. The table shows each identified sample by its "Identifier 1" value, them mean H2O concentration (in ppmv), and the standard deviation based on all samples.

The figure panels to the right show box-and-whisker plots of H2O vs. Injection number (top) and a selected isotope parameter from the Parameter drop-down below vs. Injection nr.

Clicking on a list item will display the injections of a sample. Using the checkmark "Exclude sample from processing" it is possible to disregard the currently selected sample from analysis. When the tickbox is checked, a "X" will appear in the list in front of an excluded sample.

Using the buttons "Exclude all" and "Include all", it is possible to set all samples in the list as excluded/included.

In the Injections line below, it is possible to exclude specific injections from the processing. If no sample is to be excluded, a value "-1" is displayed in the text entry box. To exclude injections 3 and 4 of the current sample, enter 3 and 4 separated by a space character in the input box. After choosing a different sample in the list, and combing back to the sample with excluded injections, these will be marked in red in the graphic display panels.

Manually excluded samples and injections are listed in the FLIIMP report in the section "Pre-processing".

![FLIIMP_2](uploads/0e50e2fd3cdb0e030f09cdf006fa2739/FLIIMP_2.png)

'''3. Run parameters and calibration settings'''

In the third step, the run parameters and calibration settings are entered. Each FARLAB project has a unique id that is entered in the first input field. The accounting can either be internal, collaborator, or external, which will influence the analysis cost (not considered in the report at present).

The report date defaults to the current date (format YYYYMMDD), but can be set to any other date. This date will be appended to the output directory name. The checkbox "Detailed report" determines whether additional analysis information is included in the report. For normal customers that are not part of FARLAB, the checkbox "Detailed report" should not be checked, as FARLAB-internal information about the instruments and processing are included in the detailed report.

Often, a project contains several runs/batches. The serial number or identifier of a run is entered in the field "Run ID" (for example "run01" and so on).

The next two lines should contain a name and email of the customer, and of the operator at FARLAB who can be contacted by the customer in case of questions.

Processing at FARLAB is based on local laboratory standards, that were calibrated on the VSMOW2-SLAP2 scale at several instances. The most current instance (run 3) is the default setting, for comparison purposes an older calibration run of the lab standards may be chosen. The delta values of the calibration standards are included in the report.

The calibration type can be either 1-point or 2-point linear. The third option, 3-point is not yet implemented. Using 1-point will use an average of the standard measurements in the beginning and end of a run. Using 2-point linear will linearly interpolate between the standard measurements in the beginning and end of a run. The option 2-point linear is recommended.

The input field "Calibration standards" should contain the chosen pair of calibration standards for slope and offset calibration. The first standard will be the offset correction, the first and second will be used in the slope correction. Standard names should appear as they are listed in the table visible in step 2. If more than 2 standards were measured, that are not used in the calibration, these names should be listed after the first two standards. If not included here, additional standard measurements will be treated as samples.

The field "Drift standard" contains the name of a standard that was repeatedly measured during the run but not used in calibration. It is displayed in a separate section in the report. The fields "Calibration standards" and "Drift standard" must not be empty. If no drift standard was in included in a run, use one of the calibration standards here.

The field "Averaging injections" sets how many of the last injections will be used in the averaging step. A number of 3 or 4 is currently recommended (without memory correction). The checkbox "include 17-O excess" needs to be checked for runs that are intended for 17-O excess analysis.

Pressing the button "Calibrate" that will start to produce the output report in HTML format. Watch the matlab command line window for progress, error messages and warnings.

Remember, settings across all three steps can be saved and loaded at any time using the buttons "Save" and "Load".

![FLIIMP_3](uploads/68266f681b7e2f2f21789771bcee76bc/FLIIMP_3.png)

'''Detailed description of calibration procedure'''

'''1. Identification of standards'''

- Calibration standards

- Drift standards

'''2. Calibration'''

- Using IAEA procedures

'''3. Instrument characteristics'''

- Cavity temperature, cavity pressure, warm-box temperature, DAS temperature

'''4. Quality flags'''

- Humidity variation

- Isotope variation

- Temperature variation

- Quality flags

'''5. Sample report'''

'''Reference'''

IAEA, 20xx

FLIIMP - FARLAB liquid water isotope measurements processor

2020-09-18T07:23:22Z

Hso039:

# FLIIMP - FARLAB Liquid Injection Isotope Measurement Processor

'''USING FLIIMP:'''

FLIIMP has 3 windows, that have to be completed in a fixed sequence.

'''1. Path settings, instrument and time'''

FLIIMP reads in the injection files from an instrument for a particular time, time range, or day. The Input file path for all injection files is specified in the first entry field.

FLIIMP creates a report on the calibrated data in HTML format within a new subfolder. The base output file path where the new output folder will be created is specified in the second entry field.

The instrument on which the liquid samples were measured is chosen from the pulldown list "Instrument".

Next, either a time range or specific files are selected. If choosing time range, only a date in format YYYYMMDD_HHMMSS needs to be given. If a range is given, all files that fall within the time period will be loaded. If only one date is given, either all files from that day (YYYYMMDD) or if a specific date with HHMMSS is given, that specific time will be looked for. The search path for files is combined from the input file path, the instrument, and the time range, for example

HKDS2038/IsotopeData/HKDS2038_IsoWater_20180912_120312.csv

At any point, the settings can be saved to a .mat file, or loaded from a previous run. The settings are saved and loaded across all three steps of the calibration, not for each step separately.

The button "Next >" advances to the second step. After clicking, please check the matlab command window for error messages or warnings.

Path settings are saved automatically to the file "FLIIMP_settings.mat" in the local directory where FLIIMP.m is located.

![FLiiMP_1](uploads/965cac19a14e7a9464ca2682c80fc74c/FLiiMP_1.png)

'''2. Sample screening and selection'''

In the second step, the data files for the selected period are loaded, and displayed for screening and selection. The table shows each identified sample by its "Identifier 1" value, them mean H2O concentration (in ppmv), and the standard deviation based on all samples.

The figure panels to the right show box-and-whisker plots of H2O vs. Injection number (top) and a selected isotope parameter from the Parameter drop-down below vs. Injection nr.

Clicking on a list item will display the injections of a sample. Using the checkmark "Exclude sample from processing" it is possible to disregard the currently selected sample from analysis. When the tickbox is checked, a "X" will appear in the list in front of an excluded sample.

Using the buttons "Exclude all" and "Include all", it is possible to set all samples in the list as excluded/included.

In the Injections line below, it is possible to exclude specific injections from the processing. If no sample is to be excluded, a value "-1" is displayed in the text entry box. To exclude injections 3 and 4 of the current sample, enter 3 and 4 separated by a space character in the input box. After choosing a different sample in the list, and combing back to the sample with excluded injections, these will be marked in red in the graphic display panels.

Manually excluded samples and injections are listed in the FLIIMP report in the section "Pre-processing".

![FLIIMP_2](uploads/0e50e2fd3cdb0e030f09cdf006fa2739/FLIIMP_2.png)

'''3. Run parameters and calibration settings'''

In the third step, the run parameters and calibration settings are entered. Each FARLAB project has a unique id that is entered in the first input field. The accounting can either be internal, collaborator, or external, which will influence the analysis cost (not considered in the report at present).

The report date defaults to the current date (format YYYYMMDD), but can be set to any other date. This date will be appended to the output directory name. The checkbox "Detailed report" determines whether additional analysis information is included in the report. For normal customers that are not part of FARLAB, the checkbox "Detailed report" should not be checked, as FARLAB-internal information about the instruments and processing are included in the detailed report.

Often, a project contains several runs/batches. The serial number or identifier of a run is entered in the field "Run ID" (for example "run01" and so on).

The next two lines should contain a name and email of the customer, and of the operator at FARLAB who can be contacted by the customer in case of questions.

Processing at FARLAB is based on local laboratory standards, that were calibrated on the VSMOW2-SLAP2 scale at several instances. The most current instance (run 3) is the default setting, for comparison purposes an older calibration run of the lab standards may be chosen. The delta values of the calibration standards are included in the report.

The calibration type can be either 1-point or 2-point linear. The third option, 3-point is not yet implemented. Using 1-point will use an average of the standard measurements in the beginning and end of a run. Using 2-point linear will linearly interpolate between the standard measurements in the beginning and end of a run. The option 2-point linear is recommended.

The input field "Calibration standards" should contain the chosen pair of calibration standards for slope and offset calibration. The first standard will be the offset correction, the first and second will be used in the slope correction. Standard names should appear as they are listed in the table visible in step 2. If more than 2 standards were measured, that are not used in the calibration, these names should be listed after the first two standards. If not included here, additional standard measurements will be treated as samples.

The field "Drift standard" contains the name of a standard that was repeatedly measured during the run but not used in calibration. It is displayed in a separate section in the report. The fields "Calibration standards" and "Drift standard" must not be empty. If no drift standard was in included in a run, use one of the calibration standards here.

The field "Averaging injections" sets how many of the last injections will be used in the averaging step. A number of 3 or 4 is currently recommended (without memory correction). The checkbox "include 17-O excess" needs to be checked for runs that are intended for 17-O excess analysis.

Pressing the button "Calibrate" that will start to produce the output report in HTML format. Watch the matlab command line window for progress, error messages and warnings.

Remember, settings across all three steps can be saved and loaded at any time using the buttons "Save" and "Load".

![FLIIMP_3](uploads/68266f681b7e2f2f21789771bcee76bc/FLIIMP_3.png)

'''Detailed description of calibration procedure'''

'''1. Identification of standards'''

- Calibration standards

- Drift standards

'''2. Calibration'''

- Using IAEA procedures

'''3. Instrument characteristics'''

- Cavity temperature, cavity pressure, warm-box temperature, DAS temperature

'''4. Quality flags'''

- Humidity variation

- Isotope variation

- Temperature variation

- Quality flags

'''5. Sample report'''

'''Reference'''

IAEA, 20xx

FLIIMP - FARLAB liquid water isotope measurements processor

2020-09-18T07:21:53Z

Hso039: Created page with "# FLIIMP - FARLAB Liquid Injection Isotope Measurement Processor ## USING FLIIMP: FLIIMP has 3 windows, that have to be completed in a fixed sequence. ### 1. Path settings,..."

# FLIIMP - FARLAB Liquid Injection Isotope Measurement Processor

## USING FLIIMP:

FLIIMP has 3 windows, that have to be completed in a fixed sequence.

### 1. Path settings, instrument and time

FLIIMP reads in the injection files from an instrument for a particular time, time range, or day. The Input file path for all injection files is specified in the first entry field.

FLIIMP creates a report on the calibrated data in HTML format within a new subfolder. The base output file path where the new output folder will be created is specified in the second entry field.

The instrument on which the liquid samples were measured is chosen from the pulldown list "Instrument".

Next, either a time range or specific files are selected. If choosing time range, only a date in format YYYYMMDD_HHMMSS needs to be given. If a range is given, all files that fall within the time period will be loaded. If only one date is given, either all files from that day (YYYYMMDD) or if a specific date with HHMMSS is given, that specific time will be looked for. The search path for files is combined from the input file path, the instrument, and the time range, for example

HKDS2038/IsotopeData/HKDS2038_IsoWater_20180912_120312.csv

At any point, the settings can be saved to a .mat file, or loaded from a previous run. The settings are saved and loaded across all three steps of the calibration, not for each step separately.

The button "Next >" advances to the second step. After clicking, please check the matlab command window for error messages or warnings.

Path settings are saved automatically to the file "FLIIMP_settings.mat" in the local directory where FLIIMP.m is located.

![FLiiMP_1](uploads/965cac19a14e7a9464ca2682c80fc74c/FLiiMP_1.png)

### 2. Sample screening and selection

In the second step, the data files for the selected period are loaded, and displayed for screening and selection. The table shows each identified sample by its "Identifier 1" value, them mean H2O concentration (in ppmv), and the standard deviation based on all samples.

The figure panels to the right show box-and-whisker plots of H2O vs. Injection number (top) and a selected isotope parameter from the Parameter drop-down below vs. Injection nr.

Clicking on a list item will display the injections of a sample. Using the checkmark "Exclude sample from processing" it is possible to disregard the currently selected sample from analysis. When the tickbox is checked, a "X" will appear in the list in front of an excluded sample.

Using the buttons "Exclude all" and "Include all", it is possible to set all samples in the list as excluded/included.

In the Injections line below, it is possible to exclude specific injections from the processing. If no sample is to be excluded, a value "-1" is displayed in the text entry box. To exclude injections 3 and 4 of the current sample, enter 3 and 4 separated by a space character in the input box. After choosing a different sample in the list, and combing back to the sample with excluded injections, these will be marked in red in the graphic display panels.

Manually excluded samples and injections are listed in the FLIIMP report in the section "Pre-processing".

![FLIIMP_2](uploads/0e50e2fd3cdb0e030f09cdf006fa2739/FLIIMP_2.png)

### 3. Run parameters and calibration settings

In the third step, the run parameters and calibration settings are entered. Each FARLAB project has a unique id that is entered in the first input field. The accounting can either be internal, collaborator, or external, which will influence the analysis cost (not considered in the report at present).

The report date defaults to the current date (format YYYYMMDD), but can be set to any other date. This date will be appended to the output directory name. The checkbox "Detailed report" determines whether additional analysis information is included in the report. For normal customers that are not part of FARLAB, the checkbox "Detailed report" should not be checked, as FARLAB-internal information about the instruments and processing are included in the detailed report.

Often, a project contains several runs/batches. The serial number or identifier of a run is entered in the field "Run ID" (for example "run01" and so on).

The next two lines should contain a name and email of the customer, and of the operator at FARLAB who can be contacted by the customer in case of questions.

Processing at FARLAB is based on local laboratory standards, that were calibrated on the VSMOW2-SLAP2 scale at several instances. The most current instance (run 3) is the default setting, for comparison purposes an older calibration run of the lab standards may be chosen. The delta values of the calibration standards are included in the report.

The calibration type can be either 1-point or 2-point linear. The third option, 3-point is not yet implemented. Using 1-point will use an average of the standard measurements in the beginning and end of a run. Using 2-point linear will linearly interpolate between the standard measurements in the beginning and end of a run. The option 2-point linear is recommended.

The input field "Calibration standards" should contain the chosen pair of calibration standards for slope and offset calibration. The first standard will be the offset correction, the first and second will be used in the slope correction. Standard names should appear as they are listed in the table visible in step 2. If more than 2 standards were measured, that are not used in the calibration, these names should be listed after the first two standards. If not included here, additional standard measurements will be treated as samples.

The field "Drift standard" contains the name of a standard that was repeatedly measured during the run but not used in calibration. It is displayed in a separate section in the report. The fields "Calibration standards" and "Drift standard" must not be empty. If no drift standard was in included in a run, use one of the calibration standards here.

The field "Averaging injections" sets how many of the last injections will be used in the averaging step. A number of 3 or 4 is currently recommended (without memory correction). The checkbox "include 17-O excess" needs to be checked for runs that are intended for 17-O excess analysis.

Pressing the button "Calibrate" that will start to produce the output report in HTML format. Watch the matlab command line window for progress, error messages and warnings.

Remember, settings across all three steps can be saved and loaded at any time using the buttons "Save" and "Load".

![FLIIMP_3](uploads/68266f681b7e2f2f21789771bcee76bc/FLIIMP_3.png)

## Detailed description of calibration procedure

### 1. Identification of standards

- Calibration standards

- Drift standards

### 2. Calibration

- Using IAEA procedures

### 3. Instrument characteristics

- Cavity temperature, cavity pressure, warm-box temperature, DAS temperature

### 4. Quality flags

- Humidity variation

- Isotope variation

- Temperature variation

- Quality flags

### 5. Sample report

## Reference

IAEA, 20xx

Main Page

2020-09-18T07:20:46Z

Hso039:

== Geophysical Institute ==

[[File:GFI.jpg]]

==[[Teaching]]==

==Research and PhD/Postdoc Groups==
===[[Meteorology]]===
===[[ResClim Bergen subgroup]]===
===[[Physical Oceanography group]]===

==Observations==
===[[ITAS Automatic Weather Stations]]===
===[[MRR Micro Rain Radar]]===
===[[TPS-3100 Hotplate pluviometer]]===
===[[Parsivel2 Disdrometer]]===
===[[HOBO rain gauges]]===
===[[EasyLog temperature logger]]===
===[[iMet UAV sonde package]]===
===[[Kristine Bonnevie shiplog data]]===
===[[Joining several data files with CDO and IsoFuse]]===

==Shared data sets==
===[[ERA5 reanalysis data]]===

==IT (Hardware and Software)==
===[[The GFI computing system]]===
===[[Using cyclone]]===
===[[Using modules on cyclone]]===
===[[Best practices when using cyclone]]===
===[[Bedymo]]===
===[[Dynlib]]===
===[[Forecast plotting]]===
===[[Git]]===
===[[NCL]]===
===[[Python]]===
===[[WRF]]===
===[[OpenIFS]]===
===[[GFI&SKD Storage]]===
===(outdated) [[Using the queue system on skd-cyclone]]===

==IsoMet Tools==
===[[FLEXPART]]===
===[[Lagranto]]===
===[[WaterSip]]===
===[[Flextract]]===
===[[Joining several data files with CDO and IsoFuse|IsoFuse]]===
===[[Rayleigh model]]===
===[[FLIIMP - FARLAB liquid water isotope measurements processor]]===
===[[FaVaCal - FARLAB water vapour isotope calibration processor]]===

==Social Activities and Groups==
===[[Football]]===
===[[Gale Brewing Club]]===
===[[Geosupen]]===
===[[GFI-social]]===
===[[Kakeklubben]]===
===[[Music]]===
===[[PhD Forum]]===
===[[Schafkopf]]===
===[[Volleyball]]===

[[Category:IT]]

IMet UAV sonde package

2020-06-21T05:39:29Z

Hso039:

The Meteorology group has 2 UAV measurement sondes of type iMet XQ2 ([https://www.intermetsystems.com/products/imet-xq2-uav-sensor see Intermet Systems website]).

[[File:XQ2_for_publication.jpg|400px]]

Figure (c) Intermet systems

'''Measurement capability'''

Measurement features in the second-generation sensor include

- atmospheric pressure,

- air temperature

- relative humidity,

- GPS coordinates,

This is packaged into a small housing, with rechargeable battery and data logger. The sonde can be run on battery power or powered by micro-USB cable.
Battery capacity five hours.

The sensor information is detailed on the corresponding [https://www.intermetsystems.com/ee/pdf/202021_iMet-XQ2_171207.pdf data sheet]

'''Data format and processing'''

The log from the imet can either be acquired in csv format from the software when connected to a computer via USB cable, or from reading the output with another serial port logging program.

Routines for data processing are available on the [https://git.app.uib.no/uib-gfi/gfi_instruments/-/tree/master/iMet GFI git repository], including a simple plotting routine in matlab. The code in its current version is cloned on the cyclone compute system at location <code>/Data/gfi/scratch/metdata/scripts/gfi_instuments/imet</code>.

IMet UAV sonde package

2020-06-21T05:37:39Z

Hso039:

The Meteorology group has 2 UAV measurement sondes of type iMet XQ2 ([https://www.intermetsystems.com/products/imet-xq2-uav-sensor see Intermet Systems website]).

[[File:XQ2_for_publication.jpg|400px]]

Figure (c) Intermet systems

Measurement features in the second-generation sensor include

- atmospheric pressure,

- air temperature

- relative humidity,

- GPS coordinates,

This is packaged into a small housing, with rechargeable battery and data logger. The sonde can be run on battery power or powered by micro-USB cable.
Battery capacity five hours.

The sensor information is detailed on the corresponding [https://www.intermetsystems.com/ee/pdf/202021_iMet-XQ2_171207.pdf data sheet]

Routines for data processing are available on the [https://git.app.uib.no/uib-gfi/gfi_instruments/-/tree/master/iMet GFI git repository], including a simple plotting routine in matlab. The code in its current version is cloned on the cyclone compute system at location <code>/Data/gfi/scratch/metdata/scripts/gfi_instuments/imet</code>.

IMet UAV sonde package

2020-06-21T05:37:19Z

Hso039:

The Meteorology group has 2 UAV measurement sondes of type iMet XQ2 ([https://www.intermetsystems.com/products/imet-xq2-uav-sensor see Intermet Systems website]).

[[File:XQ2_for_publication.jpg|400px]]

Figure (c) Intermet systems

Measurement features in the second-generation sensor include

- atmospheric pressure,

- air temperature

- relative humidity,

- GPS coordinates,

This is packaged into a small housing, with rechargeable battery and data logger. The sonde can be run on battery power or powered by micro-USB cable.
Battery capacity five hours.

The sensor information is detailed on the corresponding [https://www.intermetsystems.com/ee/pdf/202021_iMet-XQ2_171207.pdf data sheet]

Routines for data processing are available on the [https://git.app.uib.no/uib-gfi/gfi_instruments/-/tree/master/iMet GFI git repository], including a simple plotting routine in matlab. The code in its current version is cloned on cyclone at location <code>//Data/gfi/scratch/metdata/scripts/gfi_instuments/imet</code>.

IMet UAV sonde package

2020-06-21T05:33:39Z

Hso039:

File:XQ2 for publication.jpg

2020-06-21T05:33:10Z

Hso039: File uploaded with MsUpload

File uploaded with MsUpload

IMet UAV sonde package

2020-06-21T05:32:34Z

Hso039: Created page with "The Meteorology group has 2 UAV measurement sondes of type iMet XQ2 ([https://www.intermetsystems.com/products/imet-xq2-uav-sensor see Intermet Systems website]). Measurement..."

The Meteorology group has 2 UAV measurement sondes of type iMet XQ2 ([https://www.intermetsystems.com/products/imet-xq2-uav-sensor see Intermet Systems website]).

Measurement features in the second-generation sensor include

- atmospheric pressure,

- air temperature

- relative humidity,

- GPS coordinates,

This is packaged into a small housing, with rechargeable battery and data logger. The sonde can be run on battery power or powered by micro-USB cable.
Battery capacity five hours.

The sensor information is detailed on the corresponding [https://www.intermetsystems.com/ee/pdf/202021_iMet-XQ2_171207.pdf data sheet]

Main Page

2020-06-21T05:27:00Z

Hso039: /* Observations */

== Geophysical Institute ==

[[File:GFI.jpg]]

==[[Teaching]]==

==Research and PhD/Postdoc Groups==
===[[Meteorology]]===
===[[ResClim Bergen subgroup]]===
===[[Physical Oceanography group]]===

==Observations==
===[[ITAS Automatic Weather Stations]]===
===[[MRR Micro Rain Radar]]===
===[[TPS-3100 Hotplate pluviometer]]===
===[[Parsivel2 Disdrometer]]===
===[[HOBO rain gauges]]===
===[[EasyLog temperature logger]]===
===[[iMet UAV sonde package]]===
===[[Kristine Bonnevie shiplog data]]===
===[[Joining several data files with CDO and IsoFuse]]===

==Shared data sets==
===[[ERA5 reanalysis data]]===

==IT (Hardware and Software)==
===[[The GFI computing system]]===
===[[Using cyclone]]===
===[[Using modules on cyclone]]===
===[[Best practices when using cyclone]]===
===[[Bedymo]]===
===[[Dynlib]]===
===[[Forecast plotting]]===
===[[Git]]===
===[[NCL]]===
===[[Python]]===
===[[WRF]]===
===[[OpenIFS]]===
===[[GFI&SKD Storage]]===
===(outdated) [[Using the queue system on skd-cyclone]]===

==IsoMet Tools==
===[[FLEXPART]]===
===[[Lagranto]]===
===[[WaterSip]]===
===[[Flextract]]===
===[[Joining several data files with CDO and IsoFuse|IsoFuse]]===

==Social Activities and Groups==
===[[Football]]===
===[[Gale Brewing Club]]===
===[[Geosupen]]===
===[[GFI-social]]===
===[[Kakeklubben]]===
===[[Music]]===
===[[PhD Forum]]===
===[[Schafkopf]]===
===[[Volleyball]]===

[[Category:IT]]

MRR Micro Rain Radar

2020-04-28T07:59:14Z

Hso039:

The MRR (Micro Rain Radar, Metek GmbH, Germany) is installed on the GFI rooftop and delivers vertical precipitation profiles and droplet size distributions every 10s.

Data files for the period Oct 2015 - Mar 2020 are available on the GFI linux file system in <code>/Data/gfi/scratch/metdata/MRR</code>

Routines for reading data files are available on the GFI linux file system in <code>/Data/gfi/scratch/metdata/scripts/MRR</code>

The instrument characteristics, data processing, and data availability and archiving are described in the document attached below.

[[:File:Data_management_MRR_202004.pdf|MRR-2 instrument description and data management]] (Updated April 2020)]]

MRR Micro Rain Radar

2020-04-28T07:58:43Z

Hso039:

MRR Micro Rain Radar

2020-04-28T07:48:38Z

Hso039:

File:Data management MRR 202004.pdf

2020-04-28T07:48:26Z

Hso039: File uploaded with MsUpload

File uploaded with MsUpload

Flextract

2020-04-23T18:23:06Z

Hso039:

== Flextract reference ==

'''AUTHORS:'''

Alexander Läderach, Harald Sodemann

'''PURPOSE:'''

Extract trajectories from FLEXPART particle binary format and convert them to text-based LAGRANTO lsl file format.

'''USAGE:'''

./flextract <settings-file>

'''AVAILABLE DATA:'''

5 mio. global FLEXPART-trajectories covering 1979-01-02 00:00 to 2019-08-30 15:00 UTC.
Stored at <code>Data/gfi/met/flexpart/erainterim/global/global_corr/</code> (input-path).

'''NOTE:'''

The minimal timestep for the trajectories to be extracted is 6 hours, for some periods 3 hours may work as well, check files in input path beforehand. The timesteps 00 06 12 18 are given by the ERA-interim reanalysis and the 03 09 15 21 timesteps are given by the forecasts of the model used to produce ERA-interim.

'''GET STARTED:'''

1. Create a link to the flextract executable, located on cyclone to your working directory:

<pre>
ln -s /Data/gfi/projects/isomet/progs/flextract/flextract .
</pre>

Note the 'dot' in the end of the command, for the current location. This will

2. Create a settings.txt-file with the following structure:

<pre>
# --------------------------------------------------------- #
# Settings to extract FLEXPART trajectories from database #
# NOTE: All lines beginning with # and empty ones ignored #
# --------------------------------------------------------- #
# Path to the FLEXPART trajectory files (Input)
/Data/gfi/met/flexpart/erainterim/global/global_corr/

# Path to store trajectories in LAGRANTO-format (Output)
/Data/gfi/work/<USERNAME>/

# Begin time (Year Month Day Hour Min Sec)
# NOTE First date for which trajectories are calculated
2018 1 1 0 0 0

# End time (Year Month Day Hour Min Sec)
# NOTE Last date for which trajectories are calculated
2018 1 3 0 0 0

# Timestep (hours)
# NOTE always positive
6

# Trajectory length (hours)
# NOTE positive for forward trajectories, negative for backward
72

# Only consider each nth-particle only (1=each of the 5mio. particles)
# NOTE: could lead to huge output if too small
1

# Target area (minlon maxlon minlat maxlat)
5.0 17.1 43.4 49.0
</pre>

3. Run the flextract program, providing the settings file as argument:

<pre>
./flextract ./settings.txt
</pre>

While calculating the trajectories, a percent number will indicate progress of the extraction. The lsl trajectory files will be created in the location specified in the settings.txt file.

4. Read/plot trajectories from the files in lsl format using matlab routines located in <code>/Data/gfi/projects/isomet/matlab</code>:

<pre>
- read_lsl.m
- traj_filter.m
- traj_plot.m
- traj_plot_vert.m
</pre>

Flextract

2020-04-23T18:21:54Z

Hso039:

== Flextract reference ==

'''AUTHORS:'''

Alexander Läderach, Harald Sodemann

'''PURPOSE:'''

Extract trajectories from FLEXPART particle binary format and convert them to text-based LAGRANTO lsl file format.

'''USAGE:'''

./flextract <settings-file>

'''AVAILABLE DATA:'''

5 mio. global FLEXPART-trajectories covering 1979-01-02 00:00 to 2019-08-30 15:00 UTC.
Stored at <code>Data/gfi/met/flexpart/erainterim/global/global_corr/</code> (input-path).

'''NOTE:'''

The minimal timestep for the trajectories to be extracted is 3 hours. The timesteps 00 06 12 18 are given by the ERA-interim reanalysis and the 03 09 15 21 timesteps are given by the forecasts of the model used to produce ERA-interim.

'''GET STARTED:'''

1. Create a link to the flextract executable, located on cyclone to your working directory:

<pre>
ln -s /Data/gfi/projects/isomet/progs/flextract/flextract .
</pre>

Note the 'dot' in the end of the command, for the current location. This will

2. Create a settings-file with the following structure:

<pre>
# --------------------------------------------------------- #
# Settings to extract FLEXPART trajectories from database #
# NOTE: All lines beginning with # and empty ones ignored #
# --------------------------------------------------------- #
# Path to the FLEXPART trajectory files (Input)
/Data/gfi/met/flexpart/erainterim/global/global_corr/

# Path to store trajectories in LAGRANTO-format (Output)
/Data/gfi/work/<USERNAME>/

# Begin time (Year Month Day Hour Min Sec)
# NOTE First date for which trajectories are calculated
2018 1 1 0 0 0

# End time (Year Month Day Hour Min Sec)
# NOTE Last date for which trajectories are calculated
2018 1 3 0 0 0

# Timestep (hours)
# NOTE always positive
6

# Trajectory length (hours)
# NOTE positive for forward trajectories, negative for backward
72

# Only consider each nth-particle only (1=each of the 5mio. particles)
# NOTE: could lead to huge output if too small
1

# Target area (minlon maxlon minlat maxlat)
5.0 17.1 43.4 49.0
</pre>

3. Run the flextract program, providing the settings file as argument:

<pre>
./flextract ./settings.txt
</pre>

While calculating the trajectories, a percent number will indicate progress of the extraction. The lsl trajectory files will be created in the location specified in the settings.txt file.

4. Read/plot trajectories from the files in lsl format using matlab routines located in <code>/Data/gfi/projects/isomet/matlab</code>:

<pre>
- read_lsl.m
- traj_filter.m
- traj_plot.m
- traj_plot_vert.m
</pre>

Main Page

2020-04-23T14:27:39Z

Hso039:

== Geophysical Institute ==

[[File:GFI.jpg]]

==[[Teaching]]==

==Research and PhD/Postdoc Groups==
===[[Meteorology]]===
===[[ResClim Bergen subgroup]]===
===[[Physical Oceanography group]]===

==Observations==
===[[ITAS Automatic Weather Stations]]===
===[[MRR Micro Rain Radar]]===
===[[TPS-3100 Hotplate pluviometer]]===
===[[Parsivel2 Disdrometer]]===
===[[HOBO rain gauges]]===
===[[EasyLog temperature logger]]===
===[[Kristine Bonnevie shiplog data]]===
===[[Joining several data files with CDO and IsoFuse]]===

==Shared data sets==
===[[ERA5 reanalysis data]]===

==IT (Hardware and Software)==
===[[The GFI computing system]]===
===[[Using cyclone]]===
===[[Using modules on cyclone]]===
===[[Bedymo]]===
===[[Dynlib]]===
===[[Forecast plotting]]===
===[[Git]]===
===[[NCL]]===
===[[Python]]===
===[[WRF]]===
===[[OpenIFS]]===
===[[GFI&SKD Storage]]===
===(outdated) [[Using the queue system on skd-cyclone]]===

==IsoMet Tools==
===[[FLEXPART]]===
===[[Lagranto]]===
===[[WaterSip]]===
===[[Flextract]]===
===[[Joining several data files with CDO and IsoFuse|IsoFuse]]===

==Social Activities and Groups==
===[[Football]]===
===[[Gale Brewing Club]]===
===[[Geosupen]]===
===[[GFI-social]]===
===[[Kakeklubben]]===
===[[Music]]===
===[[PhD Forum]]===
===[[Schafkopf]]===
===[[Volleyball]]===

[[Category:IT]]

Main Page

2020-04-23T14:27:17Z

Hso039:

== Geophysical Institute ==

[[File:GFI.jpg]]

==[[Teaching]]==

==Research and PhD/Postdoc Groups==
===[[Meteorology]]===
===[[ResClim Bergen subgroup]]===
===[[Physical Oceanography group]]===

==Observations==
===[[ITAS Automatic Weather Stations]]===
===[[MRR Micro Rain Radar]]===
===[[TPS-3100 Hotplate pluviometer]]===
===[[Parsivel2 Disdrometer]]===
===[[HOBO rain gauges]]===
===[[EasyLog temperature logger]]===
===[[Kristine Bonnevie shiplog data]]===
===[[Joining several data files with CDO and IsoFuse]]===

==Shared data sets==
===[[ERA5 reanalysis data]]===

==IT (Hardware and Software)==
===[[The GFI computing system]]===
===[[Using cyclone]]===
===[[Using modules on cyclone]]===
===[[Bedymo]]===
===[[Dynlib]]===
===[[Forecast plotting]]===
===[[Git]]===
===[[NCL]]===
===[[Python]]===
===[[WRF]]===
===[[OpenIFS]]===
===[[GFI&SKD Storage]]===
===(outdated) [[Using the queue system on skd-cyclone]]===

==IsoMet Tools==
===[[FLEXPART]]===
===[[Lagranto]]===
===[[WaterSip]]===
===[[Flextract]]===
===[[IsoFuse|Joining several data files with CDO and IsoFuse]]===

==Social Activities and Groups==
===[[Football]]===
===[[Gale Brewing Club]]===
===[[Geosupen]]===
===[[GFI-social]]===
===[[Kakeklubben]]===
===[[Music]]===
===[[PhD Forum]]===
===[[Schafkopf]]===
===[[Volleyball]]===

[[Category:IT]]

Flextract

2020-04-21T21:09:25Z

Hso039: Created page with "== Flextract reference == '''AUTHORS:''' Alexander Läderach, Harald Sodemann '''PURPOSE:''' Extract trajectories from FLEXPART particle binary format and convert them to..."

== Flextract reference ==

'''AUTHORS:'''

Alexander Läderach, Harald Sodemann

'''PURPOSE:'''

Extract trajectories from FLEXPART particle binary format and convert them to LAGRANTO-format.

'''AVAILABLE DATA:'''

5 mio. global FLEXPART-trajectories covering 1979-01-02 00:00 to 2019-08-30 15:00 UTC.
Stored at <code>Data/gfi/met/flexpart/erainterim/global/global_corr/</code> (input-path).

'''GET STARTED:'''

Create a settings-file with the following structure:

<pre>
# --------------------------------------------------------- #
# Settings to extract FLEXPART trajectories from database #
# NOTE: All lines beginning with # and empty ones ignored #
# --------------------------------------------------------- #
# Path to the FLEXPART trajectory files (Input)
/Data/gfi/met/flexpart/erainterim/global/global_corr/

# Path to store trajectories in LAGRANTO-format (Output)
/Data/gfi/work/<USERNAME>/

# Begin time (Year Month Day Hour Min Sec)
# NOTE First date for which trajectories are calculated
2000 1 1 0 0 0

# End time (Year Month Day Hour Min Sec)
# NOTE Last date for which trajectories are calculated
2000 1 2 0 0 0

# Timestep (hours)
# NOTE always positive
6

# Trajectory length (hours)
# NOTE positive for forward trajectories, negative for backward
24

# Only consider each nth-particle only (1=each of the 5mio. particles)
# NOTE: could lead to huge output if too small
10

# Target area (minlon maxlon minlat maxlat)
5 17 43 49
</pre>

'''USAGE:'''

./flextract <settings-file>

'''NOTE:'''

The minimal timestep for the trajectories to be extracted is 3 hours. The timesteps 00 06 12 18 are given by the ERA-interim reanalysis and the 03 09 15 21 timesteps are given by the forecasts of the model used to produce ERA-interim.

Main Page

2020-04-21T21:09:08Z

Hso039:

== Geophysical Institute ==

[[File:GFI.jpg]]

==[[Teaching]]==

==Research and PhD/Postdoc Groups==
===[[Meteorology]]===
===[[ResClim Bergen subgroup]]===
===[[Physical Oceanography group]]===

==Observations==
===[[ITAS Automatic Weather Stations]]===
===[[MRR Micro Rain Radar]]===
===[[TPS-3100 Hotplate pluviometer]]===
===[[Parsivel2 Disdrometer]]===
===[[HOBO rain gauges]]===
===[[EasyLog temperature logger]]===
===[[Kristine Bonnevie shiplog data]]===
===[[Joining several data files with CDO and IsoFuse]]===

==Shared data sets==
===[[ERA5 reanalysis data]]===

==IT (Hardware and Software)==
===[[The GFI computing system]]===
===[[Using cyclone]]===
===[[Using modules on cyclone]]===
===[[Bedymo]]===
===[[Dynlib]]===
===[[Forecast plotting]]===
===[[Git]]===
===[[NCL]]===
===[[Python]]===
===[[WRF]]===
===[[OpenIFS]]===
===[[GFI&SKD Storage]]===
===(outdated) [[Using the queue system on skd-cyclone]]===

==IsoMet Tools==
===[[FLEXPART]]===
===[[Lagranto]]===
===[[WaterSip]]===
===[[Flextract]]===

==Social Activities and Groups==
===[[Football]]===
===[[Gale Brewing Club]]===
===[[Geosupen]]===
===[[GFI-social]]===
===[[Kakeklubben]]===
===[[Music]]===
===[[PhD Forum]]===
===[[Schafkopf]]===
===[[Volleyball]]===

[[Category:IT]]

IsoMet Tools

2020-04-21T21:08:17Z

Hso039:

Main Page

2020-04-21T21:07:53Z

Hso039:

== Geophysical Institute ==

[[File:GFI.jpg]]

==[[Teaching]]==

==Research and PhD/Postdoc Groups==
===[[Meteorology]]===
===[[ResClim Bergen subgroup]]===
===[[Physical Oceanography group]]===

==Observations==
===[[ITAS Automatic Weather Stations]]===
===[[MRR Micro Rain Radar]]===
===[[TPS-3100 Hotplate pluviometer]]===
===[[Parsivel2 Disdrometer]]===
===[[HOBO rain gauges]]===
===[[EasyLog temperature logger]]===
===[[Kristine Bonnevie shiplog data]]===
===[[Joining several data files with CDO and IsoFuse]]===

==Shared data sets==
===[[ERA5 reanalysis data]]===

==IT (Hardware and Software)==
===[[The GFI computing system]]===
===[[Using cyclone]]===
===[[Using modules on cyclone]]===
===[[Bedymo]]===
===[[Dynlib]]===
===[[Forecast plotting]]===
===[[Git]]===
===[[NCL]]===
===[[Python]]===
===[[WRF]]===
===[[OpenIFS]]===
===[[GFI&SKD Storage]]===
===(outdated) [[Using the queue system on skd-cyclone]]===

==IsoMet Tools==
===[[FLEXPART]]===
===[[Lagranto]]===
===[[WaterSip]]===
===[[IsoMet Tools|Flextract]]===

==Social Activities and Groups==
===[[Football]]===
===[[Gale Brewing Club]]===
===[[Geosupen]]===
===[[GFI-social]]===
===[[Kakeklubben]]===
===[[Music]]===
===[[PhD Forum]]===
===[[Schafkopf]]===
===[[Volleyball]]===

[[Category:IT]]

Main Page

2020-04-21T21:07:25Z

Hso039:

== Geophysical Institute ==

[[File:GFI.jpg]]

==[[Teaching]]==

==Research and PhD/Postdoc Groups==
===[[Meteorology]]===
===[[ResClim Bergen subgroup]]===
===[[Physical Oceanography group]]===

==Observations==
===[[ITAS Automatic Weather Stations]]===
===[[MRR Micro Rain Radar]]===
===[[TPS-3100 Hotplate pluviometer]]===
===[[Parsivel2 Disdrometer]]===
===[[HOBO rain gauges]]===
===[[EasyLog temperature logger]]===
===[[Kristine Bonnevie shiplog data]]===
===[[Joining several data files with CDO and IsoFuse]]===

==Shared data sets==
===[[ERA5 reanalysis data]]===

==IT (Hardware and Software)==
===[[The GFI computing system]]===
===[[Using cyclone]]===
===[[Using modules on cyclone]]===
===[[Bedymo]]===
===[[Dynlib]]===
===[[Forecast plotting]]===
===[[Git]]===
===[[NCL]]===
===[[Python]]===
===[[WRF]]===
===[[OpenIFS]]===
===[[GFI&SKD Storage]]===
===(outdated) [[Using the queue system on skd-cyclone]]===

==IsoMet Tools==
===[[FLEXPART]]===
===[[Lagranto]]===
===[[WaterSip]]===
===[[Flextract|IsoMet Tools]]===

==Social Activities and Groups==
===[[Football]]===
===[[Gale Brewing Club]]===
===[[Geosupen]]===
===[[GFI-social]]===
===[[Kakeklubben]]===
===[[Music]]===
===[[PhD Forum]]===
===[[Schafkopf]]===
===[[Volleyball]]===

[[Category:IT]]