Changes between Initial Version and Version 2 of Ticket #169

01/03/18 23:19:24 (19 months ago)


  • Ticket #169 – Description

    initial v2  
    1 As of CF 1.7, it appears that there is no specific support in CF for complex numbers.
     1== Motivation ==
    3 For radar analysis and research, complex numbers are used for both raw  IQ (in-phase and quadrature) data, and for spectra and covariances.
     3The ongoing development of the CfRadial convention, aimed at representing radar and lidar data in CF NetCDF, has highlighted the need to properly represent complex numbers in CF.
     4The intention with this proposal is to obtain agreement on adopting a complex number convention that (a) respects the CF approach, (b) satisfies the requirements of the radar and lidar research community and (c) provide a general solution so that complex numbers from any discipline can be accurately and simply represented.
    5 Therefore we are submitting a proposal for the addition of support for complex numbers.
     6== The nature of complex numbers ==
     8A complex number can be expressed in the form P = X + iY, where X and Y are real numbers, and i is the square root of -1. For the complex number P = X + iY, X is called the real part, and Y is called the imaginary part.
     10Complex numbers can also be represented in a polar or exponential forms.
     12The relationship between the Cartesian form and the polar form is:
     14         P = X + iY = R(cos(theta) + isin(theta))
     16where R is the distance from the origin to the point P, and theta is the angle between the X axis and the line OP, measured counterclockwise.
     18== Representing complex numbers as 2 reals ==
     20The above discussion demonstrates that no matter which form you choose to use, a complex number requires the storage of two real numbers, as well as a clear description of which form you are using.
     21It seems reasonable to determine the form being used by inspecting
     22the units attribute.
     24== Use of complex numbers in radar data ==
     26At the most raw level, radars generate time series of I (in-phase) and Q (quadrature) signals. These two signal components are considered to comprise a complex number.
     28Additionally, the spectra of radar signals are stored as complex numbers.
     30Because of the very large dynamic range of radar signals (up to 10 orders of magnitude), these complex numbers are often stored as power, in log units, and phase, in degrees.
     32== Storing complex numbers in NetCDF ==
     34Because complex numbers must be represented by 2 real numbers, a complex variable will have one extra dimension, of size 2.
     36We propose that this dimension should be the last of the dimensions used for a variable – i.e. the 2 parts of the number are stored immediately one after the other in the array.
     38So, for example, a radar variable holding complex data for an I/Q time series could be represented as follows
     42time = 3000 ;
     43range = 996 ;
     44complex = 2;
     45float IQ(time, range, complex) ;
     46   IQ:is_complex = “true” ;
     47   IQ:long_name = "time_series_inphase_and_quadrature" ;
     48   IQ:standard_name = "radar_time_series_inphase_and_quadrature" ;
     49   IQ:units = "volt" ;
     50   IQ:_FillValue = -9999F ;
     51   IQ:coordinates = "time range" ;
     54== Attribute indicating variable is complex ==
     56As indicated in the example above, we propose that the string attribute:
     60is_complex = "true";
     64be attached to any variable that holds complex numbers.
     66== Units attribute for real/imaginary form ==
     68If the complex number is stored using real and imaginary parts, the units of both parts will be the same.
     70This is true for the example above, where we have:
     73IQ:units = "volts";
     76== Units attribute for polar form ==
     78If the polar or exponential form is used, the units of the two parts will not be the same.
     80We could use a single units string attribute, but make it comma-delimited to separate the units for the 2 parts.
     82For example:
     85IQ:units = "dBm,degree";
     88Or we could have 2 separate units attributes:
     90For example:
     93IQ:units_first_part = "dBm";
     94IQ:units_second_part = "degree";
    7100The full proposal is attached.