-------------------------------------
-------------------------------------
Content:
-------------------------------------
- src (dir containing source fortran code)
  - raincell (contains code for IRT see Moseley2016,2019)
    - ... 
  - cp (contains fortran source code for cold pool tracking)
    - cp_parameters.f90 (module containing paramters)
    - tracer_tracking.f90 (main code for CP tracking)

- bin (executable and binary files)
  - raincell
    - ...
  - cp
    - tracer_tracking.x
    - cp_parameters.o
    - cp_parameters.mod
  - fill_tracks.ncl (fills missing timesteps in raincelltracking)
  - merger.py (determines when CP starts after precip track start)
  - cut.bsh (postprocessing for raincell ASCII files)

- job (create trackiong jobs)
  - run_raintrack.job (conducts the tracking job)
  - namelist.tmp (template for the namelist.dat)
  - namelist.dat (produced by run_raintrack.job)

- compile.job (compiles the sourcecode from IRT and CP)

-------------------------------------------------------------
-------------------------------------
Compilation:
-------------------------------------
compile.job rc   compiles the IRT from src/raincell/*
compile.job cp   compiles the CP tracking from src/cp/*
compile.job rcnc compiles the IRT version which can handle netcdf 

------------------------------------------------------------
-------------------------------------
Required data:
-------------------------------------
- 2D precipitation field or similiar  2D field for cell tracking
  (see IRT for details)
- 2D-field of horizontal wind components for tracer advection
  (all timesteps in one file, input_u.srv, input_v.srv)
- So far the CP tracking only handles circular boundary conditions 

-------------------------------------------------------------
-------------------------------------
Run:
-------------------------------------
Preparation: Precipitation and wind data must be in the right format. 
See Required data
2D Divergence must be calculated from horizontal wind field

Use run script job/run_raintrack.job:

Making directory strcuture, preparing and running the IRT and preparing
and running the CP tracking can all be made with the run-script 
run_raintrack.job in job directory. 
Required input: 

  for namelist files:
  general: 
  - OUT                          path where output shell be stored
  - domsizex                     domainsize of modeldata      
  - domsizey
  - dt                           temporal resolution of model output data
  - res                          horizontal res. ...

  IRT: 
  - cutoff                       threshold for object identification
  - mincellsize                  min cell size
 
  CP tracking:
  - tracer                       number of tracer per CP
  - age                          maximum age of CPs
  - lformat                      srv or nc format of input data. nc requires separate compiliation 
                                 IRT for nc with ./compile rcnc

  for data preparation and directory structure:
  - FIN                          path for input data (divergence, precitation)
  - INv                          path for wind input data
  - INu
  - JOBNAME                      define jobname
  - lvl                          model level of wind data, if more than one level
                                 is present. lowest level should be chosen if no
                                 other purpose of tracking
  - lirt                         define tasks of the job "run" does the full job

------------------------------------------------------------
-------------------------------------
Programs:
Preparation from raincell to CP
-------------------------------------
.........................
cut.bsh
........................
prepares the ASCII output from raincell tracking for CP tracking
separates header from body

.........................
fill_tracks.ncl
........................
netcdf mask file for precip. tracks contains timesteps only when precipitation 
objects are present. fill_tracks.ncl adds missing timesteps with default value 0

.........................
merger.py
.........................
identifies 
-spliting events,
-time when to start CP, 
-merger and  following track ID of the smaller part of the merger
therefore IRT ASCII-files are read, CPs are started when average divergence 
value of rain track object exceeds a given threshold. 
Average divergence and ID of following object are stored in Objects file.
information if merger or splitter is given in headerfile.txt
attribution of objects Id to track ID is given in body of track file
ASCII output:
track ID, track ID merger, time when tarck starts, time when tracers to be placed 

track ID merger: either same as track ID for events starting and terminating without
spliting or merging; 0 starting as spliting, everything marked with 0 is ignored by
CP tracking; 0 when divergence threshold is never exceeded in this track; number of
larger track this track merges into. 

-------------------------------------
Programs:
CP Tracking
-------------------------------------
.........................
tracer_tracking.x
........................
  - creates random numbers of domainsize: selects every gridpoint once in 
    random order, output as x/y saved as randomgrdpts_xysize. Time consuming
    function. When tracking is done multiple times for randomgrdpts_xysize 
    can be read instead of vreating random order again. 
  - opens files: 
    input
    - mergingCPs.txt (gives when to start CP after precip start,
      0 when precip track starts as a merger 
    - irt_tracks_mask.srv (get position of precip tracks)
    - input_u.srv + input_v.srv (wind field for advection)

    output
    - termination.txt (Size of CP before they terminate)
  - loops trough all timesteps and opens required files (wind velocity, 
    precipitation track, COGs, ...) 
  - fnc neigh2: selects outer grid cells of precipitation track object,
    stores selected grid points in random order (not more than tracers to
    be placed) 
  - fnc set_tracer2: places tracer, stores it in traced(internal tracer ID,
    CP ID, information) infomormation can be position (x/y), age, etc. 
  - fnc update_newtracer: advects newly set tracer only 
  - fnc velocity_interpol: interpolates velocity field from staggered grid 
    to tracer positions (stored in traced(:,:,13:14)
  - fnc geometry: calculates radial coordinates of tracer position relative
    to its COG
  - fnc radvel: calculates radial velocity component of tracer  
  - fnc sort: sorts tracer by its angle (radial coordinates)
  - fnc setongrid: stores tracer on x times y grid and get objects
      - fnc filltracer: identifies outlines of cold pools by connecting 
        tracer and by filling up gridpoints between tracers
      - fnc getobj: fill outlines of CP to get CP objects
  - retrieve size of CP from objects and sum up size
    for merging CPs. (needed to determine termination)
  - fnc write_output
  - terminate CP: terminate CPs that reduce too drastically in size
  - fnc update_tracer: update tracer position by advection and overwrite 
    varible tarced where all information are saved

.........................
cut.bsh
........................
prepares the ASCII output from raincell tracking for CP tracking
separates header from body

.........................
fill
........................