RF Antenna Parameters

A collection of utilities to help convert RF engineering/communications terms into radio astronomy terms. This module is geared toward taking antenna parameters in dBi or dBd and converting them into meaningful RA gains in K/Jy and then using those to get a system equivalent flux density.

New in version 1.0.3.

lsl.misc.rfutils.Jy_to_dBm(flux, bandwidth, gain)

Convert a flux density in Jy into a received signal strength in dBm under the assumptions of:

  • signal bandwidth in Hz

  • antenna gain in K/Jy

lsl.misc.rfutils.calculate_effective_area(gain)

Given the gain of an antenna in K/Jy, calculate the effective collecting area in square meters.

lsl.misc.rfutils.calculate_sefd(Tsys, gain=None, area=None, efficiency=None)

Given a variety of parameters, calculate the system equivalent flux density in Jy for an antenna. The parameters are:

  • Tsys - system temperature in K - required

  • gain - antenna gain in K/Jy - optional

  • area - antenna collecting area in m^2 - optional

  • efficiency - aperture efficiency - optional

Of the optional parameters either ‘gain’ needs to be supplied or both ‘area’ and ‘efficiency’.

lsl.misc.rfutils.dBd_to_dBi(dBd)

Convert an antenna gain in dBb (gain relative to the maximum gain of a half-wave dipole) into a gain in dBi (gain relative to an isotropic antenna).

lsl.misc.rfutils.dBd_to_dBi(dBd)

Convert an antenna gain in dBb (gain relative to the maximum gain of a half-wave dipole) into a gain in dBi (gain relative to an isotropic antenna).

lsl.misc.rfutils.dBd_to_gain(dBd, frequency)

Convert an antenna gain in dBd (gain relative to the maximum gain of a half-wave dipole) at a particular frequency in Hz into a gain in K/Jy

lsl.misc.rfutils.dBi_to_gain(dBi, frequency)

Convert an antenna gain in dBi (gain relative to an isotropic antenna) at a particular frequency in Hz into a gain in K/Jy.

lsl.misc.rfutils.dBm_to_Jy(dBm, bandwidth, gain)

Convert a received signal strength in dBm into a flux density in Jy under the assumptions of:

  • signal bandwidth in Hz

  • antenna gain in K/Jy

lsl.misc.rfutils.gain_to_dBd(gain, frequency)

Convert an antenna gain in K/Jy at a particular frequency in Hz into a gain in dBd (gain relative to the maximum gain of a half-wave dipole).

lsl.misc.rfutils.gain_to_dBi(gain, frequency)

Convert an antenna gain in K/Jy at a particular frequency in Hz into a gain in dBi (gain relative to an isotropic antenna).

Simulated Stand Response

This module contains a set of convenience functions to parse the output of NEC2, modify the input (.nec) file, and rerun NEC as necessary. NEC2 is the Numerical Electromagnetics Code, developed at LLNL. The version of NEC2 this code currently assumes is here.

Several NEC files are included with the LSL distribution for modeling the dipoles. See the README.NEC file included in the LSL data directory for more information about what is included.

class lsl.sim.necutils.NECImpedance(necname)

NECImpedance: Python class to read an array of impedance values from a NEC2 .out file The .nec file should loop over a range of frequencies with an FR card like this:

FR 0 91 0 0 10.0 1.0

The RP card should be minimal to keep the runtime and output file size from growing huge. For example:

RP 0,91,1,1000,0.,0.,1.0,1.0

class lsl.sim.necutils.NECPattern(necname, freq, rerun=True)

NECPattern: Python class to read the pattern from a NEC2 .out file. Note that the .nec file should have an RP or EX card to run over the full pattern, like this:

RP 0,91,360,1000,0.,0.,1.0,1.0,0.

The FR card should be a simple single frequency run:

FR 0,1,0,0,74.0,1

Changed in version 1.2.0: Added a new “antenna_pat_complex attribute to store the complex antenna pattern

lsl.sim.necutils.calculate_ime(necname, myfreqs=None, zpre=100)

Compute the impedance mismatch efficiency (IME), for a given NEC run and write out the results in a file. Assumes a default preamplifier input impedance of 100 ohms, unless overridden by the zpre keyword argument. Returns the frequencies calculated by NEC, unless myfreqs is set, in which case it interpolates onto that frequency grid.

lsl.sim.necutils.change_nec_freq(necname, freq)

Modify the FR card in a NEC input file to run at freq.

lsl.sim.necutils.close_to(x, y, epsilon=0.005)

Return True if two numbers are within a specified fractional, not absolute, tolerance of each other. Tolerance epsilon is a keyword parameter with a default of 0.005.

lsl.sim.necutils.open_and_get_nec_freq(fname)

Open a NEC output file and return a tuple containing the open file object and the first frequency found in the file (MHz).

lsl.sim.necutils.which_nec4()

Return the path to the nec4d executable if it can be found in the current path. None otherwise. This is useful for making sure that NEC is installed before trying to run something.

Ionospheric and Geomagnetic Field Models

New in version 1.1.0.

A collection of utilities for retrieving parameters that may be relevant for ionospheric corrections.

lsl.misc.ionosphere.compute_magnetic_declination(Bn, Be, Bz)

Given the topocentric output of get_magnetic_field(), compute and return the magnetic declination (deviation between magnetic north and true north) in degrees.

Note

The declination is poorly defined (NaN) around the magnetic poles where the horizontal field strength is less than 100 nT.

lsl.misc.ionosphere.compute_magnetic_inclination(Bn, Be, Bz)

Given the topocentric output of get_magnetic_field(), compute and return the magnetic inclination or magnetic dip (angle between the magnetic field and the horizontal) in degrees.

lsl.misc.ionosphere.get_ionospheric_pierce_point(site, az, el, height=450000.0, verbose=False)

Given a site and a pointing direction (azimuth and elevation in degrees), compute the location of the ionospheric pierce point. Since the height assumed for the ionosphere is model-dependent the ‘height’ keyword sets the elevation to use in meters. Returns a three-element tuple of latitude (degrees, North is positive), longitude (degrees, East is positive), and elevation (meters).

lsl.misc.ionosphere.get_magnetic_field(lat, lng, elev, mjd=None, ecef=False)

Given a geodetic location described by a latitude in degrees (North positive), a longitude in degrees (West negative), an elevation in meters and an MJD value, compute the Earth’s magnetic field in that location and return a three-element tuple of the magnetic field’s components in nT. By default these are in topocentric coordinates of (North, East, Up). To return values in ECEF, set the ‘ecef’ keyword to True. If the MJD file is None, the current time is used.

Note

The convention used for the topocentric coordinates differs from what the IGRF uses in the sense that the zenith direction points up rather than down.

lsl.misc.ionosphere.get_tec_value(mjd, lat=None, lng=None, include_rms=False, timeout=120, type='IGS')

Given an MJD value and, optionally, a latitude and longitude in degrees, compute the TEC value in TECU above that location using data from the IGS or CODE (depending on the value of the ‘type’ keyword). If the ‘include_rms’ keyword is set to True, also return the RMS in the TEC value.

Conversion Helper Functions for argparse

New in version 1.2.4.

Module that provides argparse-compatible conversion functions for a variety of value formats, including:

  • positive integers,

  • ephem.hours instances, and

  • lists of integers from a comma-separated list.

New in version 1.2.4.

lsl.misc.parser.csv_baseline_list(string)

Convert a comma-separated list of baslines pairs into a list of baseline pairs. Baseline pairs are defined as ‘antenna1-antenna2’ where ‘antenna1’ and ‘antenna2’ are both integers or ranges denoted by the ‘~’ character.

lsl.misc.parser.csv_degrees_list(string)

Convert a comma-separated list of ‘sDD[:MM[:SS.[SSS]]]’ string into a list of ephem.degrees instances.

lsl.misc.parser.csv_hostname_list(string)

Convert a comma-separated list of IPv4 addresses/hostnames into a list IPv4 addresses/hostnames. This function support indexing with the ‘~’ character so long as:

  • the character is in any one of the IPv4 bytes or

  • the character is at the end of a hostname which ends with a number

lsl.misc.parser.csv_hours_list(string)

Convert a comma-separated list of ‘HH[:MM[:SS.[SSS]]]’ string into a list of ephem.hours instances.

lsl.misc.parser.csv_int_list(string)

Convert a comma-separated list of integers into a list of integers. This function also allows for ranges to be specifed using the ‘~’ character. This formatting converts ‘start~stop’ to ‘range(start, stop+1)’.

lsl.misc.parser.date(string)

Convert a data as either a YYYY[-/]MM[-/]DD or MJD string into a YYYY/MM/DD string.

lsl.misc.parser.degrees(string)

Convert a ‘sDD[:MM[:SS[.SSS]]]’ string into an ephem.degrees instance.

lsl.misc.parser.frequency(string)

Convert a frequency to a float Hz value. This function accepts a variety of string formats:

  • pure float values are intepreted to be in MHz (45.0 -> 45e6)

  • number/unit pairs are allowed so long as they are in:

    • [prefix]m, A, or ang for wavelength and

    • [prefix]Hz for frequency

lsl.misc.parser.frequency_range(string)

Convert a frequency to a float Hz value. This function accepts a variety of string formats:

  • a ‘number~number’ is interpretted as a range in MHz

  • a ‘number/unit~number/unit’ is converted to a range in Hz

Note

For ranges, a two-element list is returned where the first value is less than the second.

lsl.misc.parser.hours(string)

Convert a ‘HH[:MM[:SS[.SSS]]]’ string into an ephem.hours instance.

lsl.misc.parser.mjd(string)

Convert a data as either a YYYY[-/]MM[-/]DD or MJD string into an integer MJD.

lsl.misc.parser.mpm(string)

Covnert a time as HH:MM:SS[.SSS] or MPM string into an MPM integer.

lsl.misc.parser.positive_float(string)

Convert a string to a positive (>0.0) float.

lsl.misc.parser.positive_int(string)

Convert a string to a positive (>0) integer.

lsl.misc.parser.positive_or_zero_float(string)

Convert a string to a positive (>=0.0) float.

lsl.misc.parser.positive_or_zero_int(string)

Convert a string to a positive (>=0) integer.

lsl.misc.parser.time(string)

Covnert a time as HH:MM:SS[.SSS] or MPM string into a HH:MM:SS.SSSSSS string.

lsl.misc.parser.wavelength(string)

Convert a wavelength to a float m value. This function accepts a variety of string formats:

  • pure float values are intepreted to be in m (45.0 -> 45.0)

  • number/unit pairs are allowed so long as they are in:

    • [prefix]m, AA, or Angstrom for wavelength and

    • [prefix]Hz for frequency

lsl.misc.parser.wavelength_range(string)

Convert a wavelength to a float m value. This function accepts a variety of string formats:

  • a ‘number~number’ is interpretted as a range in m

  • a ‘number/unit~number/unit’ is converted to a range in m

Note

For ranges, a two-element list is returned where the first value is less than the second.