-----------------------------------------------------------------------------
             INFORMATION ON THE COSMO-DE LIGHTNING PACKAGE
-----------------------------------------------------------------------------
                     
                    by J. Dahl, 26 January 2010 

-----------------------------------------------------------------------------
 Introduction
-----------------------------------------------------------------------------

This README file describes some details about the implementation of the new
lightning package.  
The source code is heavily commented already but additional details about the 
reasoning behind the routine are found in the PhD dissertation 
(Dahl, 2010, LMU). 

This directory contains all files that were modified, as well as post-processing
software.  The COSMO-version used for the original implementation was 4.6.
It is recommended to adjust the files (except SRC_LIGHTNING.F90 
and DATA_LIGHTNING.F90) of your COSMO version manually, rather than replacing 
the files with those in this directory.  The locations where changes were made 
are marked with the tag "DAHL".

-----------------------------------------------------------------------------
 Section 1.1:  A few details about SRC_LIGHTNING.F90
-----------------------------------------------------------------------------

INPUT:

Via USE-Statements, data-field variables (e.g., the prognostic 
variables), model-configuration variables, etc. are made available
in the lightning module.

The fields actually needed for the lightning-rate calculations are the
following mass fractions

 qc: cloud water
 qi: cloud ice
 qs: snow
 qg: graupel.

Also, the air density, rho, and the vertical velocity, w, are used.

OUTPUT:

Information about the lightning rate, the position, and some more parameters
of every thunderstorm cell may optionally be written in the standard output 
file (if the logical variable VERBOSE == .TRUE.).

In addition, the location and the time of each discharge is written in an 
ASCII list.  The target directory is specified in the last section of 
the subroutine DISTRIBUTE_FLASHES (part of SRC_LIGHTNING.F90).
A separate text file is created for every call (i.e., for every 15 minutes in
the default setting).  The time is in seconds from initialization and the
locations are in degrees (lon, lat), but in relation to the origin of the
rotated COSMO-DE coordinate system.

NOTE:

This code is written for application on a vector computer with a domain
decomposition that allows loops in a certain direction to be as long as
possible - this is realized in a decomposition in only one direction
(in this case, north-south).  This degree of parallelization
has been adopted in the lightning routines.

-----------------------------------------------------------------------------
 Section 1.2: Activation of the lightning scheme
-----------------------------------------------------------------------------

There are three adjustable namelist parameters.  These are contained in the
shell script RUN_COSMO, section PHYCTL.

1) LIGHTNING:

  .TRUE. : Lightning scheme called
  .FALSE.: Lightning scheme not called 

2) ITYPE_LIGHT: Determines which parameterization is called:

  itype_light == 1: Scheme based on E-field build-up rate and field-
                    neutralization efficiency (dahl_2010).

  itype_light == 2: PR92 parameterization, based on updraft speed
                    GT 2 m/s to determine the cell depths (pr92_updraft)

  itype_light == 3: PR92 parameterization, based on cloud-water/ice
                    content to determine the cell depths (pr92_cwi)

  itype_light == 4: Yoshida et al. (2009) scheme based on
                    f ~ P relationship (ymuk_2009).

  itype_light == 5: Grewe et al. (2001) scheme
                    which is a re-formulated version of PR92 (getal_2001).

3) HINCLIGHT: Time interval in hours between two calls of the lightning scheme.
              Recommended (and default) value is 15 minutes,
              i.e., HINCLIGHT=0.25.

-----------------------------------------------------------------------------
 Section 2.1: Necessary adjustments to the COSMO source code
-----------------------------------------------------------------------------

The changes that need to be made are:

1) Copy the source-code files SRC_LIGHTNING.F90 and DATA_LIGHTNING.F90
   in the SRC-directory.

2) Include these modules in MAKEFILE.  This needs to be done in the
   declaration and dependencies sections for both modules:
   * data_lightning.o
   * src_lightning.o
  
   Also:
 
   * In the ORGANIZE_DIAGNOSTICS dependencies, SRC_LIGHTNING.O needs to be added
   * In the ORGANIZE_PHYSICS dependencies, SRC_LIGHTNING.O needs to be added

3) In the module DATA_RUNCONTROL, the new namelist parameters, LIGHTNING, 
   ITYPE_LIGHT, and HINCLIGHT need to be added.

4) In the module ORGANIZE_PHYSICS, the relevant namelist parameters are 
   retrieved.  The new namelist parameters need to be added.  
  
5) In the module ORGANIZE_DIAGNOSTICS, a new section (3.4) was added where the
   call to the module procedure ORGANIZE_LIGHTNING is performed.  The new
   namelist parameters are obtained via the USE statement.

6) In the shell script, RUN_COSMO, the three new namelist parameters need
   to be added to the physics-control (PHYCTL) section.

-----------------------------------------------------------------------------
 Section 3.1: Post-Processing
-----------------------------------------------------------------------------

A post-processing software is required to sort the flashes w.r.t. the time of
occurrence and to transform the coordinates to geographical ones.

This is done by the IDL-routine CONVERT_COSMO.PRO (also attached in this
directory).  This routine accepts the COSMO-DE output files containing
the lightning data as input.  The result is one ASCII file which has
the standard LINET format, so that it may be further processed with
the same software that is used for LINET data.

-----------------------------------------------------------------------------
