Conversions (pycraf.conversions)#
Introduction#
The conversions sub-package contains various functions to convert
and calculate power flux densities, electrical field strengths, transmitted
and received powers from each other. Routines that link antenna areas and
gains are also present. With the free_space_loss function
one can determine the free-space loss for a given frequency and distance
between transmitter (Tx) and receiver (Rx). Furthermore, several useful
Decibel units are defined (see Reference/API).
Getting Started#
Using the conversions package is really simple:
>>> from pycraf import conversions as cnv
>>> from astropy import units as u
>>> A_eff = 10 * u.m ** 2 # effective area
>>> A_geom = 20 * u.m ** 2 # geometric area
>>> eta_a = 50 * u.percent # antenna efficiency
>>> print('A_eff = {0.value:.1f} {0.unit}'.format(
... cnv.eff_from_geom_area(A_geom, eta_a))
... )
A_eff = 10.0 m2
>>> print('A_geom = {0.value:.1f} {0.unit}'.format(
... cnv.geom_from_eff_area(A_eff, eta_a))
... )
A_geom = 20.0 m2
Because all function parameters and return values are Astropy Quantities
(see Quantity), unit conversion is automatically performed:
>>> cnv.eff_from_geom_area(10 * u.m ** 2, 50 * u.percent)
<Quantity 5.0 m2>
>>> cnv.eff_from_geom_area(10 * u.m ** 2, 0.5 * cnv.dimless)
<Quantity 5.0 m2>
>>> cnv.eff_from_geom_area(1 * u.km ** 2, 10 * u.percent)
<Quantity 100000.0 m2>
Warning
It is not possible to omit the unit, even if a quantity is dimensionless!
pycraf would raise an exception if one tried:
>>> cnv.eff_from_geom_area(10 * u.m ** 2, 0.5)
Traceback (most recent call last):
...
TypeError: Argument 'eta_a' to function 'eff_from_geom_area' has no
'unit' attribute. You may want to pass in an astropy Quantity instead.
Note
A Jupyter tutorial notebook about the conversions package is
provided in the pycraf repository on GitHub.
Using pycraf.conversions#
Decibel units#
In the conversions module, several Decibel units are defined
that often occur in spectrum-management tasks. Examples are the
\(\mathrm{dB}\) unit or \(\mathrm{dBm}\equiv\mathrm{dB[mW]}\). In
Python these are defined with the help of the units package, e.g.:
>>> from astropy import units as u
>>> dB_W = u.dB(u.W)
>>> dB_W_m2_Hz = u.dB(u.W / u.m ** 2 / u.Hz)
>>> dB_uV_m = u.dB(u.uV ** 2 / u.m ** 2)
Note
The \(\mathrm{dB}[\mu\mathrm{V}^2 / \mathrm{m}^2]\) unit is a bit special. Engineers will usually call this symbol \(\mathrm{dB}[\mu\mathrm{V} / \mathrm{m}]\), but strictly speaking it is the power of the electrical field which is referred to, which means that the amplitude of the E-field has to be squared.
In fact, if one would omit the squaring from the definition, the unit
would not work in the equations, because the units framework
would notice an inconsistency of the units.
Working with the Decibel units is easy:
>>> from pycraf import conversions as cnv
>>> power = 1 * cnv.dB_W
>>> power
<Decibel 1.0 dB(W)>
>>> power.to(u.W)
<Quantity 1.2589254117941673 W>
>>> print(power.to(u.W))
1.2589254117941673 W
Often, one wants to do some formatting in the print function, which works as usual:
>>> print('{:.1f}'.format(power.to(u.W)))
1.3 W
Astropy units provide even some additional formatting options:
>>> print('{0.value:.1f} {0.unit}'.format(power.to(u.W)))
1.3 W
>>> print('{0.value:.1f} {0.unit:FITS}'.format(1 * u.m / u.s))
1.0 m s-1
Warning
Under some circumstances, the automatic conversion from the Decibel
to the associated linear unit can fail. This may get fixed in a future
version of Astropy. It helps to construct the Quantities via
multiplication, avoiding the Quantity constructor, i.e.,
1 * cnv.dB instead of u.Quantity(1, cnv.dB).
Conversion formulae#
For a complete list of the functions provided in the conversions
package, see the Reference/API section below. All functions expect
the parameters to have appropriate units, and will return a
Quantity, i.e. a value with a unit. This makes it sometimes
a bit verbose to write code, but has the invaluable advantage that one
avoids mistakes in the calculations that come from using the wrong units.
For example, in the various ITU-R Recommendations, the described algorithms often assume the quantities to be in a certain unit. In pycraf all functions are defined in a way, that input parameters are first converted to the correct unit before feeding the values into the ITU-R algorithms.
The following quantities are of interest in compatibility studies:
Distance between transmitter and receiver: \(d\)
Frequency of radiation: \(f\)
Wavelength of radiation: \(\lambda = \frac{c}{f}\)
Geometric antenna area: \(A_\mathrm{geom}\)
Effective antenna area: \(A_\mathrm{eff} = \eta_\mathrm{A} A_\mathrm{geom}\); isotropic loss-less antenna: \(A_\mathrm{eff} = \frac{\lambda^2}{4\pi}\)
Antenna efficiency: \(\eta_\mathrm{A}\)
Antenna temperature: \(T_\mathrm{A}=\Gamma S_\nu\)
Antenna sensitivity: \(\Gamma=\frac{A_\mathrm{eff}}{2k_\mathrm{B}}\)
Transmitter/receiver gain, \(G_\mathrm{tx}\), \(G_\mathrm{rx}\): \(A_\mathrm{eff} = G\frac{\lambda^2}{4\pi}\)
Pointing flux: \(\vec S = \vec E \times \vec H\)
Power flux density: \(S\equiv\vert \vec S \vert = \sqrt{\frac{\varepsilon_0}{\mu_0}} \vert \vec E \vert^2 = \frac{E^2}{R_0}\) with \(R_0 \equiv \sqrt{\frac{\varepsilon_0}{\mu_0}} = 376.73~\Omega\)
Spectral power flux density, \(S_\nu\), with: \(S=\int \mathrm{d}\nu\,S_\nu\)
Transmitted power, \(P_\mathrm{tx}\), with \(S = G_\mathrm{tx}\frac{P_\mathrm{tx}}{4\pi d^2}\)
Received power, \(P_\mathrm{rx} = S\cdot A_\mathrm{eff}^\mathrm{rx} = S\cdot G_\mathrm{rx}\frac{\lambda^2}{4\pi} = G_\mathrm{tx}\frac{P_\mathrm{tx}}{4\pi d^2} \cdot G_\mathrm{rx}\frac{\lambda^2}{4\pi} = G_\mathrm{tx} G_\mathrm{rx} P_\mathrm{tx} L_\mathrm{fs}\)
Received spectral power, \(P_\mathrm{rx,\nu} = \frac{P_\mathrm{rx}}{\Delta\nu}=2 k_\mathrm{B}T_\mathrm{A}\)
Signal bandwidth, \(\Delta \nu\)
Free-space loss: \(L_\mathrm{fs} = \frac{c^2}{16\pi^2}\frac{1}{d^2f^2} = \frac{\lambda^2}{16\pi^2 d^2}\)
A few examples:
>>> from pycraf import conversions as cnv
>>> from astropy import units as u
>>> frequency = 10 * u.GHz
>>> S = 10 * u.Jy * u.MHz
>>> E_rx = -30 * cnv.dB_uV_m
>>> distance = 10 * u.km
>>> G_tx = 20 * cnv.dBi
>>> G_rx = 10 * cnv.dBi
>>> P_rx = -10 * cnv.dBm
>>> P_tx = 20 * cnv.dBm
>>> cnv.efield_from_powerflux(S).to(cnv.dB_uV_m)
<Decibel -44.23969433034762 dB(uV2 / m2)>
>>> cnv.powerflux_from_efield(E_rx).to(cnv.dB_W_m2)
<Decibel -175.7603056696524 dB(W / m2)>
>>> cnv.ptx_from_powerflux(S, distance, G_tx).to(cnv.dB_W)
<Decibel -119.00790135977903 dB(W)>
>>> cnv.powerflux_from_ptx(P_tx, distance, G_tx).to(cnv.dB_W_m2)
<Decibel -80.99209864022097 dB(W / m2)>
>>> cnv.prx_from_powerflux(S, frequency, G_rx).to(cnv.dB_W)
<Decibel -221.4556845816624 dB(W)>
>>> cnv.powerflux_from_prx(P_rx, frequency, G_rx).to(cnv.dB_W_m2)
<Decibel -8.544315418337588 dB(W / m2)>
>>> cnv.free_space_loss(distance, frequency)
<Decibel -132.44778322188336 dB>
>>> cnv.prx_from_ptx(P_tx, G_tx, G_rx, distance, frequency).to(cnv.dB_W)
<Decibel -112.44778322188337 dB(W)>
>>> cnv.ptx_from_prx(P_rx, G_tx, G_rx, distance, frequency).to(cnv.dB_W)
<Decibel 62.44778322188338 dB(W)>
See Also#
Astropy Units and Quantities package, which is used extensively in pycraf.
Reference/API#
Contains functions to convert power flux densities, field strengths, transmitted and received powers at certain distances and frequencies into each other. Furthermore, some convenience decibel-Scales are defined.
The following Decibel units are available:
Unit |
Alias |
Definition |
|---|---|---|
\(1\) |
dimless |
u.dimensionless_unscaled |
\(\mathrm{dB},~\mathrm{dBi},~\mathrm{dBc}\) |
dB, dBi, dBc |
u.dB(dimless) |
\(\mathrm{dB}[\mathrm{W}]\) |
dB_W |
u.dB(u.W) |
\(\mathrm{dB}[\mathrm{W} / \mathrm{Hz}]\) |
dB_W_Hz |
u.dB(u.W / u.Hz) |
\(\mathrm{dB}[\mathrm{W} / \mathrm{m}^2]\) |
dB_W_m2 |
u.dB(u.W / u.m ** 2) |
\(\mathrm{dB}[\mathrm{W} / \mathrm{m}^2 / \mathrm{Hz}]\) |
dB_W_m2_Hz |
u.dB(u.W / u.m ** 2 / u.Hz) |
\(\mathrm{dB}[\mathrm{Jy} \cdot \mathrm{Hz}]\) |
dB_Jy_Hz |
u.dB(u.Jy * u.Hz) |
\(\mathrm{dB}[\mathrm{mW}]\) |
dBm = dB_mW |
u.dB(u.mW) |
\(\mathrm{dB}[\mathrm{mW} / \mathrm{MHz}]\) |
dBm_MHz |
u.dB(u.mW / u.MHz) |
\(\mathrm{dB}[\mu\mathrm{V}^2 / \mathrm{m}^2]\) |
dB_uV_m |
u.dB(u.uV ** 2 / u.m ** 2) |
\(\mathrm{dB}[1 / \mathrm{m}]\) |
dB_1_m |
u.dB(1 / u.m) |
u = astropy.units
|
Antenna factor from antenna gain, given frequency and impedance. |
|
Effective antenna area from antenna gain, given frequency. |
|
Effective antenna area from antenna sensitivity ("Kelvins-per-Jansky"). |
|
Effective antenna area from geometric area, given antenna efficiency. |
|
|
|
E-field strength from power flux density. |
|
E-field strength measured at distance from transmitter power. |
|
Antenna efficiency from geometric and effective antenna areas. |
|
Free-space loss of a propagating radio wave. |
|
Antenna gain from antenna factor, given frequency and impedance. |
|
Antenna gain from effective antenna area, given frequency. |
|
Antenna sensitivity ("Kelvins-per-Jansky") from effective antenna area. |
|
Geometric antenna area from effective area, given antenna efficiency. |
|
Effective antenna area of the ideal (loss-less) isotropic antenna. |
|
Power flux density from E-field strength. |
|
Power flux density from received power. |
|
Power flux density from transmitter power. |
|
Spectral power flux density from antenna temperature, given effective antenna area. |
|
Received power from power flux density. |
|
Received power from transmitted power. |
|
Received spectral power from antenna temperature. |
|
Transmitter power from E-field strength measured at distance. |
|
Transmitter power from power flux density. |
|
Transmitted power from received power. |
|
Antenna temperature from spectral power flux density, given effective antenna area. |
|
Antenna temperature from received spectral power. |