-
Notifications
You must be signed in to change notification settings - Fork 1
Home
pyradsim is a weather radar simulator written in Python 3.4 and based on the pytmatrix library by Jussi Leinonen.
It allows computation of various polarimetric variables inside discrete boxes with user-defined configurations. Integration in space over multiple boxes as well sensitivity analysis is also possible.
First of all you need to make sure that you have version 3.4 (or later) of Python installed.
sudo apt-get install python3 python3-dev python3-pip
You can then clone the library by using
git clone git@gitlab.epfl.ch:wolfensb/pyradsim.git
Alternatively you can download the compressed folder under the Files tab of the GitLab project.
Then cd to the downloaded folder, make sure that you are in the same directory as setup.py and install the library with
sudo python3 setup.py install
All dependencies should be installed automatically if they are missing
To run, two files need to be created and given as input to the simulator. The first one, which I call "box file" describes all boxes and their content (temperature, hydrometeors, position, etc), the other one which I call "config file" describes all simulation-related parameters that are independent of the boxes and their content.
Both file types make use of the very simple and convenient YAML serialization language.
An arbitrary number of boxes and their specifications can be defined within a single file thanks to the YAML serialization language. A box can contain a mixture of an arbitrary number of hydrometeors
This section will focus on the general structure of a box file. The allowed input types for all parameters will be described in the next section.
box_1: # Name of the box
hydrometeors:
rain:
dielectric_constant: water
canting_angle_std: 15
psd: 1000**(-0.5*D)
psd_range: [0.1,10]
aspect_ratio: Thurai_2007
snow:
dielectric_constant: 1.23+0.0015j
canting_angle_std: 30
psd: ['NormalizedGammaPSD',1000,0.5,4]
psd_range: [0.1,20]
aspect_ratio: 0.89*D**0.08
geometry:
elevation_angle: 10
azimuth: 0
position: [0,0,0]
size: [1,1,1]
atmosphere:
T: 298
P: 1018 # Not used currently...
radar:
frequency: 5.6 # In GHZ
weight: 1
In this example we create a box with name box_1.
In the hydrometeors section, a mixture of of two hydrometeors rain and snow is defined. For each of these hydrometeors we define separately their particle size distribution (psd), the range of considered diameters (psd_range), the standard deviation of their canting angle distribution (canting_angle_std), their dielectric constant (dielectric_constant) as well as their aspect ratio model (aspect_ratio).
In the geometry section are defined: the elevation angle Θ of the box with respect to the radar position (elevation_angle), the azimuth angle Φ of the box with respect to the radar position (azimuth), the size of the box (size) and the 3D position of the box (position), assuming that the radar position is [0,0,0].
In the atmosphere section are defined: the air temperature withing the box (T) and the pressure within the box (P).
Finally in the radar section, currently only the radar frequency (in GHz) (frequency) can be defined.
Additional boxes can be defined in the same way, with different names, in the rest of the file.
Note that in the YAML structure, consistency of indentation is crucial. You can use any number of spaces as indentation but you need to be consistent throughout the levels. Also, you always need to leave a space after the double colon.
IMPORTANT: you do not need to define all parameters. You can actually skip them all if you like, as default values are provided (more on that later). HOWEVER you need to provide at least the information contained in the example below. The double brackets {} need to be used when no parameter is given at all for a given section.
minimal_box:
hydrometeors:
rain: {}
geometry: {}
atmosphere: {}
radar: {}
| Name | Description | Allowed forms | Default value |
|---|---|---|---|
| permittivity | Permittivity model of the hydrometeor | Complex number: for example 8.58+1.69j or A user-defined function of D (diam.), T (temp.) and F (freq.): for example 8.58exp(-0.7D)+1.69jabs(T-298) ) or A supported keyword (currently only ice and water) or A mixture model defined by a list of two lists, the first list contains the volumetric fraction (either a constant or a user-defined function of D and T) and the second the permittivites of the mixture components: for example 0.95,0.5],[1+0j,8.58+1.69j or [[exp(-2D) 1-exp(-2D)],[1.02D+0.00015*F,water]] |
8.58+1.69j (permittivity of pure water at 10°C) |
| canting_angle_std | Standard deviation of the distribution of canting angles in degrees among the hydrometeor population. The distribution is assumed to be gaussian with zero mean | Any real number | 10° |
| psd | Particle size distribution model of the hydrometeor population defined in mm^-1 m^3 | A user defined function of D and/or T: for example 1000exp(-5D) or an exponential model with N0 and lambda parameters: [ExponentialPSD,80000,3.54] or a normalized gamma model with Nw, D0 and mu parameters: for example [NormalizedGammaPSD,1000,2.0,4] or an unnormalized gamma model with N0, lambda and mu parameters: for example [UnnormalizedGammaPSD,2000,3.4,2.] or the standard COSMO PSD for graupel with parameter Qg: the spec. water content (in kg/kg) of graupel, for example ['COSMO_1mom_graupel',0.001] or the standard COSMO PSD for snow with parameter Qs: the spec. water content (in kg/kg) of snow and T: the temperature (in K), for example ['COSMO_1mom_snow',0.001,270] or the standard COSMO PSD for rain with parameter Qr: the spec. water content (in kg/kg) of rain, for example ['COSMO_1mom_rain',0.001] |
Marshall-Palmer exponential drop size distribution |
| aspect_ratio | The horizontal-to-rotational axis ratio model of the hydrometeor population | Any real number or A user-defined function of D: for example (0.89*D^(0.02)) or One of the provided models (Thurai_2007, Ansager_1999 or Brandes_2002) |
0.9 |
| elevation_angle | Elevation angle Θ with respect to the ground of the radar beam crossing through the center of the box | Any positive number | Computed from the specified box position (assuming radar is at the origin) |
| azimuth | Azimuth angle Φ with respect to the north of the radar beam crossing through the center of the box | Any positive number | Computed from the specified box position (assuming radar is at the origin) |
| position | 3D position (x,y and z) of the center of the box | A tuple or list of length 3: for example [5.4,9.2,0.5] | [1,1,1] |
| size | Size of the box in every direction (x,y and z) | A tuple or list of length 3: for example [50,40,10] | [1,1,1] |
| temperature | The temperature of the air within the box in K | Any positive number | 283 K |
| pressure | The pressure of the air within the box in hPa | Any positive number | 1015 hPa |
| frequency | The frequency of the operating radar in GhZ | Any positive number | 5.6 GhZ (C-band) |
| weight | The weight of the box when integrating the polarimetric variables over all boxes | Any positive number | 1 |
The configuration file is also written in YAML but is much simpler. At the moment, it has only two parameter nbins_d, which defines the number of diameters bins to be used when integrating the scattering properties over a psd model and sens_analysis which defines the type of sensitivity analysis, either serial which means that all parameters will be varied sequentially and parallel which means that all parameters will be varied in parallel (more on that later).
So an example of file should simply look like this.
nbins_d: 1024 # or any other positive integer
sens_analysis: serial # serial or parallel
More options will be added in the future of course.
As hinted previously, this tool also allows to perform sensitivity analysis in a simple way. By sensitivity analysis, we mean varying one or several parameters, independently or not and compute the polarimetric variables for every possible set of values.
To perform a sensivity analysis, simply add %sens(rel_min,rel_max,n_pts) after any key of your box file. The three required parameters are:
| Parameter | Description |
|---|---|
| rel_min | Defines the lower bound of the range of values to be tested. It is given relative to the value defined in the box. |
| rel_max | Defines the upper bound of the range of values to be tested. It is given relative to the value defined in the box. For example if the given temperature within the box is 298 K and rel_min = 0.7 and rel_max = 1.1, this would mean that the temperature will vary between 208 K and 323 K. |
| n_pts | Defines the number of sampling values to be tested within the range defined by rel_min and rel_max, the sampled values will be spaced uniformly in the defined range. |
As explained previously two types of sensitivity analysis are possible. The type of sensitivity analysis can be defined in the configuration file.
serial
In this case, all parameters will be changed sequentially, the interaction between parameters will not be tested. For example if the key %sens is defined for both the aspect-ratio model and the temperature (with n_points = 10 and n_points = 20 respectively), the sensitivity analysis will be performed first on the aspect-ratio model while keeping the temperature constant (at its original value defined in the box file) and then on the temperature while keeping the original aspect-ratio model. This would give a total of 10 + 20 = 30 simulations.
This type of sensitivity analysis is much faster but does not take into account interactions between parameters.
parallel
In this case, all parameters will be canged in parallel. For example if as befire the key %sens is defined for both the aspect-ratio model and the temperature, all possible combinations of temperature and aspect-ratio model will be tested. This would give a total of 10 x 20 = 200 simulations.
This type of sensitivity analysis is much slower but does ake into account interactions between parameters.
Once you have created your boxes and configuration files, computing the corresponding polarimetric radar signature is quite straightforward. A minimal working example is given below.
import pyradsim as prs
s = prs.Simulator('boxes_test.yml','configuration.yml') # Create Simulator instance, with the box and config filepaths as inputs
pol_vars_all_boxes = s.get_pol_vars()
pol_vars_integrated = s.get_integrated_pol_vars()
The function get_pol_vars returns the polarimetric variables inside every defined box without integration in the form of a dictionary, where every key corresponds to a box. The function get_integrated_pol_vars returns the polarimetric variables integrated over all boxes using their defined weights as ponderation.
Note that the output of these functions will be different depending whether you have specified %sens flags in your boxes file. If no %sens flags have been defined the function get_pol_vars, the polarimetric variables will be scalars, otherwise they will be custom arrays. These custom arrays behave like normal numpy arrays but have an additional
All classes in the library have appropriate print functions, for example printing a Simulation instance will return something in the likes of
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
BOX: box_1
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
Hydrometeors
-------------------
{
"Hydrometeor name": "rain",
"PSD": {
"PSD type": "ExponentialPSD",
"Function": "8000 * np.exp(-3.54*D)",
"Dmin": "0.1",
"Dmax": "10"
},
"Aspect ratio": "lambda D:(D>0)*0.9",
"Canting angle std": 10,
"Permittitivity": "lambda T, F, D:(D>0)*(8.587137578613968+1.6977965395728176j)"
}
{
"Hydrometeor name": "snow",
"PSD": {
"PSD type": "NormalizedGammaPSD",
"Function": "1 * 3.06097762128 * (D/1)**1 * np.exp(-4.67 * D)",
"Dmin": "0.1",
"Dmax": "20"
},
"Aspect ratio": "lambda D:(D>0)*0.9",
"Canting angle std": 40,
"Permittitivity": "lambda T, F, D:(D>0)*(8.587137578613968+1.6977965395728176j)"
}
Radar
-------------------
{
"frequency": 5.6
}
Geometry
-------------------
{
"elevation_angle": 10,
"azimuth": 150,
"position": [
180,
50,
0
],
"size": [
1,
1,
1
]
}
Atmosphere
-------------------
{
"T": 298,
"P": 1018
}
Weight
-------------------
1