##############################
quickbeam.py - python interface to the quickbeam radar simulator
Version 0.1

Edward Gryspeerdt, Universität Leipzig and Imperial College London
June 2016 - September 2022
##############################


1. Introduction
---------------
This is a python interface to the quickbeam radar simulator (v1.1a) by
John Haynes.

Not all features are implemented yet, inparticular monodisperse
droplet spectra and some of the readin functions.  However, many of
these functions are now superceeded by the python interface.  Several
of the functions in use are just f2py wrappers around the quickbeam
code itself, with the main rewrite being the radar_simulator.f90 code
and the data access functions.


2. Installation
---------------
After cloning the code directory, run

pip install . 

in the root directory.

pip install -e .

Will install so that you can modify the code in place (similar to
`python setup.py develop`)


3. Testing
----------
Testing is limited at the moment.  One thing that you can do it run

python example/testplot.py

in the main quickbeam directory and make sure that it looks similar to
the example plot sample/example.png


4. Usage
--------
Much of the design is the same as quickbeam itself.  The simulator is
run from the Quickbeam class, which does much of the setup upon
initialisation (reading in the mie tables etc.).  Details can be
changed in this instance (such as the hydrometeor data) and the
simulator is run by calling the 'radarsim' method, returning the
effective and attenuation corrected Z.

It is recommended that you read the quickbeam user guide before using
this python wrapper, as many of the details are the same.

Example (using quickbeam example data):

import pyQuickBeam
qb = pyQuickBeam.Quickbeam()
reflectivity = qb.radarsim()

The structure of the Quickbeam object is

Quickbeam
- settings - dictionary of the radar simulator settings
|             used to be in settings.dat
- met      - dictionary of meteorological data.  Requires
|             four keys, all with shape (ngate, nprofiles)
|             Temperature (K)
|             Pressure (mb)
|             Height (km)
|             RH (%)
- hclass   - list of hydrometeor data.  Each entry is a
             dictionary of the hydrometor parameters.
             The data for each class is now included in
             an entry with the key 'data', with shape
             (ngate, nprofiles)

The output is returned from the 'radarsim' call, there is no longer
an output file.

The settings are
{
'freq': radar frequency
'surface_radar': surface (1) or spaceborne (0) radar
'use_mie_table': use pre-computed mie data (1)
'use_gas_abs': calculate gas absorption (1)
'do_ray': Perform rayleigh calculations (1)
'k2': k2 value as default (-1)
'hydro_file': hydrometeor data file (if using text file)
                  load into Quickbeam instance with read_hydrodata()
                  make sure to call read_class first if updating
                  hydrometor properties
'hclass_file': hydrometeor class data
                  load into Quickbeam instance with read_hclass()
'mie_table_name': location of the pre-computed mie data.  Changing this
                    is not recommened as some assumptions on the table
                    structure are made in the code
} 

For each hydrometeor type, the dictionary in hclass is
'id': id number
'type': size distribution function (-1 to ignore this class)
'col':
'phase': Liquid (0) or Ice (1)
'cp': TOCHECK - it looks like we only accept input hydrometeors in g/kg (WRF output) 
'dmin', 'dmax': Max and min of the size distribution,
                    currently ignored
'apm', 'bpm': For calculating the density-size relationship
'rho': Density (if using constant density
'p1', 'p2', 'p3': Parameters for size distribution
'name': Name of class (not required)
'data': Hydrometeor concentration (g/ m3)