Utility functions#

A selection of general utility functions.

CHECKPOINT_EXIT_CODE = 77#: exit code to return when checkpointing

EPHEMERIS_CACHE_DIR = '/home/docs/.cache/cwinpy'#: the location for caching ephemeris files

LAL_BINARY_MODELS = ['BT', 'BT1P', 'BT2P', 'BTX', 'ELL1', 'DD', 'DDS', 'MSS', 'T2']#: the current TEMPO-compatible binary system model types provided in LALSuite

LAL_EPHEMERIS_TYPES = ['DE200', 'DE405', 'DE421', 'DE430']#: the current solar system ephemeris types in LALSuite

class MuteStream(stream=None)#

Bases: object

Class used to mute the output from a stream, e.g., stderr or stdout.

This is heavily based on the StackOverflow answer at https://stackoverflow.com/a/29834357/1862861, but only mutes and doesn’t capture the output from the given stream.

Parameters:: stream – The stream to be muted. Defaults to sys.stderr.

start()#: Start capturing the stream data.

stop()#: Stop capturing the stream data.

TEMPO2_GW_ALIASES = {'G1': 'GEO600', 'GEO_600': 'GEO600', 'H1': 'HANFORD', 'H2': 'HANFORD', 'K1': 'KAGRA', 'KAGRA': 'KAGRA', 'L1': 'LIVINGSTON', 'LHO_2k': 'HANFORD', 'LHO_4k': 'HANFORD', 'LLO_4k': 'LIVINGSTON', 'V1': 'VIRGO', 'VIRGO': 'VIRGO'}#: aliases between GW detector prefixes and TEMPO2 observatory names

allzero(array)#

Check if an array is all zeros. See https://stackoverflow.com/a/53474543/1862861.

Parameters:: array (array_like) – A numpy.ndarray to check.
Returns:: True if all zero, False otherwise.
Return type:: bool

check_for_tempo2()#: Check whether the libstempo package (v2.4.2 or greater), and therefore also TEMPO2, is available.

convert_dict_values_if_possible(dic)#: Taken from bilby_pipe.utils.convert_dict_values_if_possible from the bilby_pipe package.

convert_string_to_dict(string, key=None)#

Convert a string repr of a string to a python dictionary. This is based on bilby_pipe.utils.convert_string_to_dict from the bilby_pipe package.

Parameters:

string (str) – The string to convert
key (str (None)) – A key, used for debugging

draw_ra_dec(n=1, eqhemi=None, eclhemi=None)#

Draw right ascension and declination values uniformly on the sky or uniformly from a single equatorial or ecliptic hemisphere.

Parameters:

n (int) – The number of points to draw on the sky.
eqhemi (str) – A string that this either “north” or “south” to restrict drawn points to a single equatorial hemisphere.
eclhemi (str) – A string that this either “north” or “south” to restrict drawn points to a single ecliptic hemisphere.

Returns:

radec – A tuple containing the pair of values (ra then dec) or a pair of NumPy arrays containing the values.

Return type:

tuple

ellipticity_to_q22(epsilon, units=False)#

Convert the fiducial ellipticity \(\varepsilon\) to the mass quadrupole \(Q_{22}\) (in units of kg m²) via (see, e.g., Equation A3 of [1]):

\[Q_{22} = \varepsilon I_{38} \sqrt{\frac{15}{8\pi}},\]

where \(I_{38} = 10^{38}\) kg m² is the canonical moment of inertia of the star.

Parameters:

epsilon (float, array_like) – A value, or array of values, of the mass quadrupole.
units (bool) – If True add units to the output.

Returns:

q22 – A value, or array of values, of the mass quadrupole.

Return type:

float, array_like

gcd_array(denominators)#: Function to calculate the greatest common divisor of a list of values.

get_psr_name(psr)#

Get the pulsar name from the Tempo(2)-style parameter files by trying the keys “PSRJ”, “PSRB”, “PSR”, and “NAME” in that order of precedence.

Parameters:: psr (PulsarParameter) – A PulsarParameters object
Returns:: name – The string containing the name or None if not found.
Return type:: str

initialise_ephemeris(ephem='DE405', units='TCB', earthfile=None, sunfile=None, ssonly=False, timeonly=False, filenames=False)#

Read and return solar system ephemeris and time coordinate data. If files are provided these will be used and read. If not provided then, using supplied ephem and units values, it will first attempt to find files locally (either in your current path or in a path supplied by a LAL_DATA_PATH environment variable), and if not present will then attempt to download the files from a repository.

To do: Add the ability to create ephemeris files using astropy.

Parameters:

earthfile (str) – A file containing the Earth’s position/velocity ephemeris
sunfile (str) – A file containing the Sun’s position/velocity ephemeris
ephem (str) – The JPL ephemeris name, e.g., DE405
units (str) – The time coordinate system, which can be either “TDB” or “TCB” (TCB is the default).
ssonly (bool) – If True only return the initialised solar system ephemeris data. Default is False.
timeonly (bool) – If True only return the initialised time correction ephemeris data. Default is False.
filenames (bool) – If True return the paths to the ephemeris files. Default is False.

Returns:

The LAL EphemerisData object and TimeCorrectionData object.

Return type:

edat, sdat, filenames

int_to_alpha(pos, case='upper')#

For an integer number generate a corresponding alphabetical string following the mapping: 1 -> “A”, 2 -> “B”, …, 27 -> “AA”, 28 -> “AB”, …

Parameters:

pos (int) – A positive integer greater than 0.
case (str) – Set whether to use upper or lower case. Default is “upper”.

Returns:

alpha – The alphabetical equivalent

Return type:

str

is_par_file(parfile)#

Check if a TEMPO-style pulsar parameter file is valid.

Parameters:: parfile (str) – The path to a file.
Returns:: ispar – Returns True is if it is a valid parameter file.
Return type:: bool

is_valid_psr_name(name: str, allowed_names: list = ['psr', 'pulsar', 'hwinj', 'crab', 'vela']) → bool#

Check if a string seems like it contains a valid pulsar name. If the string starts with a “B” or “J” followed by 4 numbers (less than 2400), then a “+” or “-”, followed by 2 numbers (less than 90), it is considered a valid. Otherwise, if it contains one of the user defined allowed names it is considered valid.

Parameters:

name (str) – The string to check for pulsar name-likeness. If a non-string type is passed the function will return False rather than raise a TypeError.
allowed_names (list) – A list of allowed strings that are also considered value is the name contains them in a case insensitive way.

lalinference_to_bilby_result(postfile)#

Convert LALInference-derived pulsar posterior samples file, as created by lalpulsar_parameter_estimation_nested, into a bilby.core.result.Result object.

Parameters:: postfile (str) – The path to a posterior samples file.
Returns:: The results as a bilby.core.result.Result object
Return type:: result

logfactorial(n)#

The natural logarithm of the factorial of an integer using the fact that

\[\ln{(n!)} = \ln{\left(\Gamma (n+1)\right)}\]

Parameters:: n (int) – An integer for which the natural logarithm of its factorial is required.
Returns:
Return type:: float

overlap(pos1, pos2, f0, T, t0=1000000000, dt=60, det='H1')#

Calculate the overlap (normalised cross-correlation) between a heterodyned signal at one position and a signal re-heterodyned assuming a different position. This will assume a circularly polarised signal

Parameters:

pos1 (SkyCoord) – The sky position, as an astropy.coordinates.SkyCoord object, of the heterodyned signal.
pos2 (SkyCoord) – Another position at which the signal has been re-heterodyned.
f0 (int, float) – The signal frequency
T (int, float) – The signal duration (seconds)
t0 (int, float) – The GPS start time of the signal (default is 1000000000)
dt (int, float) – The time steps over which to calculate the signal.
det (str) – A detector name, e.g., “H1” (the default).

Returns:

overlap – The fractional overlap between the two models.

Return type:

float

parse_args(input_args, parser)#

Parse an argument list using parser generated by create_parser(). This function is based on the bilby_pipe.utils.parse_args function from the bilby_pipe package.

Parameters:

input_args (list) – A list of arguments

Returns:

args (argparse.Namespace) – A simple object storing the input arguments
unknown_args (list) – A list of any arguments in input_args unknown by the parser

q22_to_ellipticity(q22)#

Convert mass quadrupole \(Q_{22}\) (in units of kg m²) to fidicual ellipticity via (see, e.g., Equation A3 of [1]):

\[\varepsilon = \frac{Q_{22}}{I_{38}}\sqrt{\frac{8\pi}{15}},\]

where \(I_{38} = 10^{38}\) kg m² is the canonical moment of inertia of the star.

Parameters:: q22 (float, array_like) – A value, or array of values, of the mass quadrupole.
Returns:: ellipticity – A value, or array of values, of the fiducial ellipticity.
Return type:: float, array_like

relative_topdir(path, reference)#: Returns the top-level directory name of a path relative to a reference.

string_to_int_float(s)#: Taken from bilby_pipe.utils.string_to_int_float from the bilby_pipe package.

strip_quotes(string)#: Taken from bilby_pipe.utils.strip_quotes from the bilby_pipe package.

Utility functions#

Utility references#