lalsuite 7.26.2.dev20251218__cp314-cp314t-manylinux_2_28_x86_64.whl

lalburst/timeslides.py

@@ -0,0 +1,236 @@
+# Copyright (C) 2006--2018  Kipp Cannon
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 2 of the License, or (at your
+# option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+
+
+#
+# =============================================================================
+#
+#                                   Preamble
+#
+# =============================================================================
+#
+
+
+import itertools
+from tqdm import tqdm
+
+
+from . import offsetvector
+
+
+__author__ = "Kipp Cannon <kipp.cannon@ligo.org>"
+from .git_version import date as __date__
+from .git_version import version as __version__
+
+
+#
+# =============================================================================
+#
+#                             Command Line Parsing
+#
+# =============================================================================
+#
+
+
+def parse_slidespec(slidespec):
+	"""
+	Accepts a string in the format
+	instrument=first:last:step[,first:last:step]...  and returns the
+	tuple (instrument, [offset1, offset2, ....]) where the offsets are
+	the sorted list of unique numbers described by the ranges.  A range
+	with a positive step describes the offsets (first + n * step) where
+	n is an integer such that first <= offset <= last.  A range with a
+	negative step describes the offsets (first + n * step) where n is
+	an integer such that last <= offset <= first.
+
+	Example:
+
+	>>> parse_slidespec("H1=-5:+5:0.5")
+	('H1', [-5.0, -4.5, -4.0, -3.5, -3.0, -2.5, -2.0, -1.5, -1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0])
+	>>> parse_slidespec("H1=+5:-5:-0.5")
+	('H1', [-5.0, -4.5, -4.0, -3.5, -3.0, -2.5, -2.0, -1.5, -1.0, -0.5, 0.0, 0.5, 1.0, 1.5, 2.0, 2.5, 3.0, 3.5, 4.0, 4.5, 5.0])
+	>>> parse_slidespec("H1=-5:+5:8")
+	('H1', [-5.0, 3.0])
+	"""
+	try:
+		instrument, rangespec = slidespec.split("=")
+	except ValueError:
+		raise ValueError("cannot parse time slide '%s'" % slidespec)
+	offsets = set()
+	for rng in [s.strip() for s in rangespec.split(",")]:
+		try:
+			first, last, step = map(float, rng.split(":"))
+		except ValueError:
+			raise ValueError("malformed range '%s' in '%s'" % (rng, rangespec))
+		if step == 0:
+			if first != last:
+				raise ValueError("divide by zero in range '%s'" % rng)
+			offsets.add(first)
+			continue
+		elif last > first if step < 0 else last < first:
+			raise ValueError("step has wrong sign in range '%s'" % rng)
+
+		for i in itertools.count():
+			x = first + i * step
+			if not min(first, last) <= x <= max(first, last):
+				break
+			offsets.add(x)
+	return instrument.strip(), sorted(offsets)
+
+
+def parse_slides(slides):
+	"""
+	Accepts a list of strings of the format understood by
+	parse_slidespec(), and returns a dictionary mapping instrument
+	names to sorted lists of unique offsets.
+
+	Example:
+
+	>>> parse_slides(["H1=-1:+1:+1", "H2=-1:+1:+1", "L1=0:0:0"])
+	{'H2': [-1.0, 0.0, 1.0], 'H1': [-1.0, 0.0, 1.0], 'L1': [0.0]}
+	"""
+	d = {}
+	# store the offsets for each instrument as sets to uniquify the
+	# numbers
+	for slidespec in slides:
+		instrument, offsets = parse_slidespec(slidespec)
+		try:
+			d[instrument] |= set(offsets)
+		except KeyError:
+			d[instrument] = set(offsets)
+	# convert offsets back to sorted lists
+	return dict((instrument, sorted(offsets)) for instrument, offsets in d.items())
+
+
+def parse_inspiral_num_slides_slidespec(slidespec):
+	"""
+	Accepts a string in the format
+	count:instrument=offset[,instrument=offset...] and returns the
+	tuple (count, {instrument: offset, ...})
+
+	Example:
+
+	>>> parse_inspiral_num_slides_slidespec("3:H1=0,H2=5,L1=10")
+	(3, offsetvector({'H2': 5.0, 'H1': 0.0, 'L1': 10.0}))
+	"""
+	count, offsets = slidespec.strip().split(":")
+	offsetvect = offsetvector.offsetvector((instrument.strip(), float(offset)) for instrument, offset in (token.strip().split("=") for token in offsets.strip().split(",")))
+	return int(count), offsetvect
+
+
+#
+# =============================================================================
+#
+#                              Build Time Slides
+#
+# =============================================================================
+#
+
+
+def SlidesIter(slides):
+	"""
+	Accepts a dictionary mapping instrument --> list-of-offsets (for
+	example, as returned by parse_slides()), and iterates over the
+	cartesian (outer) product of the offset lists, yielding all
+	possible N-way instrument --> offset mappings.
+
+	Example:
+
+	>>> slides = {"H1": [-1, 0, 1], "H2": [-1, 0, 1], "L1": [0]}
+	>>> list(SlidesIter(slides))
+	[offsetvector({'H2': -1, 'H1': -1, 'L1': 0}), offsetvector({'H2': -1, 'H1': 0, 'L1': 0}), offsetvector({'H2': -1, 'H1': 1, 'L1': 0}), offsetvector({'H2': 0, 'H1': -1, 'L1': 0}), offsetvector({'H2': 0, 'H1': 0, 'L1': 0}), offsetvector({'H2': 0, 'H1': 1, 'L1': 0}), offsetvector({'H2': 1, 'H1': -1, 'L1': 0}), offsetvector({'H2': 1, 'H1': 0, 'L1': 0}), offsetvector({'H2': 1, 'H1': 1, 'L1': 0})]
+	"""
+	if not slides:
+		# things get a little odd in the even that no
+		# instrument/offset-list pairs are given. instead of
+		# yielding an empty sequence, itertools.product(*()) yields
+		# a sequence containing a single empty tuple, so instead of
+		# yielding no offsetvectors this function yields one empty
+		# one.  that's not what calling codes generally expect the
+		# response to be so we trap the case and return an empty
+		# sequence
+		return
+	instruments = slides.keys()
+	for slide in itertools.product(*slides.values()):
+		yield offsetvector.offsetvector(zip(instruments, slide))
+
+
+def Inspiral_Num_Slides_Iter(count, offsets):
+	"""
+	This generator yields a sequence of time slide dictionaries in the
+	style of lalapps_thinca's time slides.  Each resulting dictionary
+	maps instrument to offset.  The input is a count of time slides (an
+	integer), and a dictionary mapping instrument to offset.  The
+	output dictionaries describe time slides that are integer multiples
+	of the input time shifts.
+
+	Example:
+
+	>>> list(Inspiral_Num_Slides_Iter(3, {"H1": 0.0, "H2": 5.0,"L1": 10.0}))
+	[offsetvector({'H2': -15.0, 'H1': -0.0, 'L1': -30.0}), offsetvector({'H2': -10.0, 'H1': -0.0, 'L1': -20.0}), offsetvector({'H2': -5.0, 'H1': -0.0, 'L1': -10.0}), offsetvector({'H2': 0.0, 'H1': 0.0, 'L1': 0.0}), offsetvector({'H2': 5.0, 'H1': 0.0, 'L1': 10.0}), offsetvector({'H2': 10.0, 'H1': 0.0, 'L1': 20.0}), offsetvector({'H2': 15.0, 'H1': 0.0, 'L1': 30.0})]
+
+	The output time slides are all integer multiples of the input time
+	shift vector in the range [-count, +count], and are returned in
+	increasing order of mupltiplier.
+	"""
+	offsets = offsets.items()
+	for n in range(-count, +count + 1):
+		yield offsetvector.offsetvector((instrument, offset * n) for instrument, offset in offsets)
+
+
+def vacuum(time_slides, verbose = False):
+	"""
+	Given a dictionary mapping time slide ID to offsetvector, for
+	example as returned by the .as_dict() method of the TimeSlideTable
+	class in ligolw.lsctables, construct and return a mapping
+	indicating time slide equivalences.  This can be used to delete
+	redundant time slides from a time slide table, and then also used
+	via the .applyKeyMapping() method of ligolw.table.Table instances
+	to update cross references (for example in the coinc_event table).
+
+	Example:
+
+	>>> slides = {0: offsetvector({"H1": 0, "H2": 0}), 1: offsetvector({"H1": 10, "H2": 10}), 2: offsetvector({"H1": 0, "H2": 10})}
+	>>> vacuum(slides)
+	{1: 0}
+
+	indicating that time slide ID 1 describes a time slide that is
+	equivalent to time slide ID 0.  The calling code could use this
+	information to delete time slide ID 1 from the time_slide table,
+	and replace references to that ID in other tables with references
+	to time slide ID 0.
+	"""
+	# convert offsets to deltas
+	time_slides = dict((time_slide_id, offsetvect.deltas) for time_slide_id, offsetvect in time_slides.items())
+	with tqdm(total = len(time_slides), disable = not verbose) as progressbar:
+		# old --> new mapping
+		mapping = {}
+		# while there are time slide offset dictionaries remaining
+		while time_slides:
+			# pick an ID/offset dictionary pair at random
+			id1, deltas1 = time_slides.popitem()
+			# for every other ID/offset dictionary pair in the
+			# time slides, if the relative offset dictionaries
+			# are equivalent record in the old --> new mapping
+			ids_to_delete = [id2 for id2, deltas2 in time_slides.items() if deltas2 == deltas1]
+			for id2 in ids_to_delete:
+				mapping[id2] = id1
+				time_slides.pop(id2)
+			# number of offset vectors removed from time_slides
+			# in this iteration
+			progressbar.update(1 + len(ids_to_delete))
+	# done
+	return mapping

lalframe/__init__.py

@@ -0,0 +1,7 @@
+# Import SWIG wrappings, if available
+from ._lalframe_swig import *
+
+__version__ = "3.0.7.1"
+
+## \addtogroup lalframe_python
+"""This package provides Python wrappings and extensions to LALFrame"""

lalframe/_lalframe_swig.py

@@ -0,0 +1,14 @@
+# This file was automatically generated by SWIG (https://www.swig.org).
+# Version 4.3.1
+#
+# Do not make changes to this file unless you know what you are doing - modify
+# the SWIG interface file instead.
+
+from sys import version_info as _swig_python_version_info
+import lal
+
+# Pull in all the attributes from the low-level C/C++ module
+if __package__ or "." in __name__:
+    from ._lalframe import *
+else:
+    from _lalframe import *

lalframe/frread.py

@@ -0,0 +1,324 @@
+# Copyright (C) 2013 Duncan Macleod
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with with program; see the file COPYING. If not, write to the
+# Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+# MA  02110-1301  USA
+
+"""Wrappings of the LALFrame input methods for reading GWF files
+
+This module provides the read_timeseries function, the primary method
+by which users can load TimeSeries data from a variety of sources,
+including:
+    - a Gravitational-Wave Frame file (.gwf file extension)
+    - a LAL-format cache file (.lcf or .cache file extension)
+    - a LAL-format cache object (either XLALCache() or glue.lal.Cache [1]
+
+[1] https://www.lsc-group.phys.uwm.edu/daswg/projects/glue/doc/glue.lal.Cache-class.html
+"""
+
+import os
+import re
+
+import lal
+from lal import utils as lalutils
+
+try:
+    from glue import lal as gcache
+except ImportError:
+    _HAS_GLUE = False
+else:
+    _HAS_GLUE = True
+
+import lalframe
+from . import git_version
+__author__ = "Duncan Macleod <duncan.macleod@ligo.org>"
+__version__ = git_version.id
+__date__ = git_version.date
+
+__all__ = ['read_timeseries']
+
+
+def read_timeseries(source, channel, start=None, duration=None,
+                    datatype=None, verbose=False):
+    r"""Read a TimeSeries of channel data from a source.
+
+    Acceptable sources are:
+        - a .gwf-format framefile (string ending in '.gwf')
+        - a LAL-format cache file (string ending in '.lcf' or '.cache')
+        - a lal.Cache object (either from SWIG-LAL or GLUE)
+
+    @param source
+        input source, see above for details
+    @param channel
+        string name of channel, e.g. 'L1:LDAS-STRAIN', or a list of channel
+        names
+    @param start
+        LIGOTimeGPS start time for output TimeSeries
+    @param duration
+        float duration (seconds) for output TimeSeries
+    @param datatype
+        datatype, either an integer from the LALTYPECODE, a string
+        matchine the corresponding type, or a numpy dtype
+    @param verbose
+        print verbose output, default: False
+
+    @returns a TimeSeries of the imported data
+
+    Example 1, reading from a frame file:
+
+    \code
+    >>> out = read_timeseries('L-R-1061499968-32.gwf', 'L1:PSL-ISS_PDB_OUT_DQ')
+    >>> print(type(out))
+    <type 'REAL4TimeSeries'>
+    >>> print(out.name, float(out.epoch), out.deltaT)
+    ('L1:PSL-ISS_PDB_OUT_DQ', 1061499968.0, 3.0517578125e-05)
+    \endcode
+
+    Example 2, reading from a cache:
+
+    \code
+    >>> import lal
+    >>> cache = lal.CacheGlob('/scratch/ER4/L0/L1/L-R-10614', 'L-R-1061499968*')
+    >>> out = frread.read_timeseries(cache, 'L1:PSL-ISS_PDB_OUT_DQ')
+    >>> print(out.name, float(out.epoch), out.deltaT)
+    ('L1:PSL-ISS_PDB_OUT_DQ', 1061499968.0, 3.0517578125e-05)
+    \endcode
+
+    Example 3, restricting data input:
+
+    \code
+    >>> out = read_timeseries('L-R-1061499968-32.gwf', 'L1:PSL-ISS_PDB_OUT_DQ',
+                              start=1061499970, duration=10)
+    >>> print(out.name, float(out.epoch), out.data.length)
+    ('L1:PSL-ISS_PDB_OUT_DQ', 1061499970.0, 327680)
+    \endcode
+
+    Example 4, specifying data type:
+
+    \code
+    >>> out = read_timeseries('L-R-1061499968-32.gwf',
+                              'L1:PSL-ODC_CHANNEL_OUT_DQ')
+    >>> print(type(out), out.data.data[:4])
+    (<type 'REAL4TimeSeries'>,
+     array([ 4259839.,  4259839.,  4259839.,  4259839.], dtype=float32))
+    >>> out = read_timeseries('L-R-1061499968-32.gwf',
+                              'L1:PSL-ODC_CHANNEL_OUT_DQ', datatype='int8')
+    >>> print(type(out), out.data.data[:4])
+    (<type 'INT8TimeSeries'>, array([4259839, 4259839, 4259839, 4259839]))
+    \endcode
+
+    """
+    # parse channels
+    if isinstance(channel, str):
+        channels = [channel]
+    else:
+        channels = list(channel)
+
+    # read cache file
+    if (isinstance(source, str) and
+          re.search(r'(.lcf|.cache)\Z', source)):
+        source = lal.CacheImport(os.path.expanduser(source))
+    # convert GLUE cache file
+    if _HAS_GLUE and isinstance(source, gcache.Cache):
+        source = lalutils.lalcache_from_gluecache(source)
+
+    # read from single frame
+    if isinstance(source, str) and source.endswith('.gwf'):
+        out = _ts_from_frame_file(source, channels, start=start,
+                                  duration=duration, datatype=datatype,
+                                  verbose=verbose)
+    # read from XLALCache
+    elif isinstance(source, lal.Cache):
+        out = _ts_from_cache(source, channels, start=start,
+                             duration=duration, datatype=datatype,
+                             verbose=verbose)
+    # otherwise barf
+    else:
+        raise ValueError("Cannot interpret source '%s'." % source)
+
+    # return
+    if isinstance(channel, str):
+        return out[0]
+    else:
+        return out
+
+
+def _ts_from_cache(cache, channels, start=None, duration=None, datatype=None,
+                   verbose=False):
+    """Read a TimeSeries of channel data from a LAL Cache object
+
+    @param cache
+        XLALCache() containing list of GWF file paths
+    @param channels
+        list of channel names
+    @param start
+        LIGOTimeGPS start time for output TimeSeries
+    @param duration
+        float duration (seconds) for output TimeSeries
+    @param datatype
+        datatype, either an integer from the LALTYPECODE, a string
+        matchine the corresponding type, or a numpy dtype
+    @param verbose UNDOCUMENTED
+
+    @returns a TimeSeries of the imported data
+    """
+    # open the cache into a stream
+    stream = lalframe.FrStreamCacheOpen(cache)
+    # read the stream
+    return _ts_from_stream(stream, channels, start=start, duration=duration,
+                           datatype=datatype, verbose=verbose)
+
+
+def _ts_from_frame_file(framefile, channels, start=None, duration=None,
+                        datatype=None, verbose=False):
+    """Read a TimeSeries of channel data from a GWF-format framefile
+
+    @param framefile
+        path to GWF-format framefile to read
+    @param channels
+        list of channel names
+    @param start
+        LIGOTimeGPS start time for output TimeSeries
+    @param duration
+        float duration (seconds) for output TimeSeries
+    @param datatype
+        datatype, either an integer from the LALTYPECODE, a string
+        matchine the corresponding type, or a numpy dtype
+    @param verbose
+        print verbose output, default: False
+
+    @returns a TimeSeries of the imported data
+    """
+    # open the file into a stream
+    framefile = os.path.abspath(framefile)
+    stream = lalframe.FrStreamOpen('', framefile)
+    # read the stream
+    return _ts_from_stream(stream, channels, start=start, duration=duration,
+                           datatype=datatype, verbose=verbose)
+
+
+def _ts_from_stream(stream, channels, start=None, duration=None, datatype=None,
+                    verbose=False):
+    """Read a TimeSeries of channel data from an open FrStream
+
+    @param stream
+        XLALFrStream() of data from which to read
+    @param channels
+        list of channel names
+    @param start
+        LIGOTimeGPS start time for output TimeSeries
+    @param duration
+        float duration (seconds) for output TimeSeries
+    @param datatype
+        datatype, either an integer from the LALTYPECODE, a string
+        matchine the corresponding type, or a numpy dtype
+    @param verbose
+        print verbose output, default: False
+
+    @returns a TimeSeries of the imported data
+    """
+    # set verbosity
+    lalframe.FrStreamSetMode(
+        stream,
+        verbose and lalframe.FR_STREAM_VERBOSE_MODE
+        or lalframe.FR_STREAM_DEFAULT_MODE,
+    )
+    # determine default start time and duration
+    epoch = lal.LIGOTimeGPS(stream.epoch)
+    if start is None:
+        start = epoch
+    if not duration:
+        startoffset = float(start - epoch)
+        duration = float(get_stream_duration(stream)) - startoffset
+
+    out = []
+    for channel in channels:
+        out.append(read_channel_from_stream(stream, channel, start, duration,
+                                            datatype=datatype))
+        lalframe.FrStreamSeek(stream, epoch)
+    return out
+
+
+def read_channel_from_stream(stream, channel, start, duration, datatype=None):
+    """Read the TimeSeries of a single channel from an open stream
+    """
+    # get series type
+    frdatatype = lalframe.FrStreamGetTimeSeriesType(channel, stream)
+    if datatype is None:
+        datatype = frdatatype
+    else:
+        datatype = lalutils.get_lal_type(datatype)
+
+    # read original data
+    read = getattr(lalframe, 'FrStreamRead%sTimeSeries'
+                             % lalutils.get_lal_type_str(frdatatype))
+    origin = read(stream, channel, start, duration, 0)
+    # format to output data-type if required
+    if datatype == frdatatype:
+        return origin
+    if datatype != frdatatype:
+        create = lalutils.func_factory(
+            'create', '%stimeseries' % lalutils.get_lal_type_str(datatype))
+        series = create(channel, start, origin.f0, origin.deltaT,
+                        origin.sampleUnits, origin.data.length)
+        series.data.data = origin.data.data.astype(
+                               lalutils.get_numpy_type(datatype))
+        return series
+
+
+def get_stream_length(stream, channel):
+    """Find the number of samples represented in a frame stream
+
+    @param stream
+        XLALFrStream() of data to measure
+    @param channel
+        string name of channel to measure
+
+    @returns the integer length of the data for this channel
+    """
+    epoch = lal.LIGOTimeGPS(stream.epoch.gpsSeconds,
+                            stream.epoch.gpsNanoSeconds)
+    # loop over each file in the stream cache and query its vector length
+    nfile = stream.cache.length
+    length = 0
+    for i in range(nfile):
+        for j in range(lalframe.FrFileQueryNFrame(stream.file)):
+            length += lalframe.FrFileQueryChanVectorLength(stream.file,
+                                                           channel,0)
+            lalframe.FrStreamNext(stream)
+    # rewind the stream and return
+    lalframe.FrStreamSeek(stream, epoch)
+    return length
+
+
+def get_stream_duration(stream):
+    """Find the duration of time stored in a frame stream
+
+    @param stream
+        XLALFrStream() of data to measure
+
+    @returns the float duration (seconds) of the data for this channel
+    """
+    epoch = lal.LIGOTimeGPS(stream.epoch.gpsSeconds,
+                            stream.epoch.gpsNanoSeconds)
+    # loop over each file in the stream cache and query its duration
+    nfile = stream.cache.length
+    duration = 0
+    for i in range(nfile):
+        for j in range(lalframe.FrFileQueryNFrame(stream.file)):
+            duration += lalframe.FrFileQueryDt(stream.file, 0)
+            lalframe.FrStreamNext(stream)
+    # rewind stream and return
+    lalframe.FrStreamSeek(stream, epoch)
+    return duration

lalframe/git_version.py

@@ -0,0 +1,64 @@
+# -*- coding: utf-8 -*-
+# git_version.py - vcs information module
+#
+# Copyright (C) 2010 Nickolas Fotopoulos
+# Copyright (C) 2012-2013 Adam Mercer
+# Copyright (C) 2016 Leo Singer
+#
+# This program is free software; you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 2 of the License, or (at
+# your option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+# General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with with program; see the file COPYING. If not, write to the
+# Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,
+# MA 02110-1301 USA
+
+id = "e59d1f0003d2358dd49b9795073624fdcf1ce0a8"
+date = "2025-12-17 15:00:18 +0000"
+branch = "None"
+tag = "None"
+if tag == "None":
+    tag = None
+author = "Karl Wette <karl.wette@ligo.org>"
+builder = "Unknown User <>"
+committer = "Karl Wette <karl.wette@ligo.org>"
+status = "CLEAN: All modifications committed"
+version = id
+verbose_msg = """Branch: None
+Tag: None
+Id: e59d1f0003d2358dd49b9795073624fdcf1ce0a8
+
+Builder: Unknown User <>
+Repository status: CLEAN: All modifications committed"""
+
+import warnings
+
+class VersionMismatchError(ValueError):
+    pass
+
+def check_match(foreign_id, onmismatch="raise"):
+    """
+    If foreign_id != id, perform an action specified by the onmismatch
+    kwarg. This can be useful for validating input files.
+
+    onmismatch actions:
+      "raise": raise a VersionMismatchError, stating both versions involved
+      "warn": emit a warning, stating both versions involved
+    """
+    if onmismatch not in ("raise", "warn"):
+        raise ValueError(onmismatch + " is an unrecognized value of onmismatch")
+    if foreign_id == "e59d1f0003d2358dd49b9795073624fdcf1ce0a8":
+        return
+    msg = "Program id (e59d1f0003d2358dd49b9795073624fdcf1ce0a8) does not match given id (%s)." % foreign_id
+    if onmismatch == "raise":
+        raise VersionMismatchError(msg)
+
+    # in the backtrace, show calling code
+    warnings.warn(msg, UserWarning)

lalframe/utils/__init__.py

@@ -0,0 +1,25 @@
+# Copyright (C) 2013 Duncan Macleod
+#
+# This program is free software; you can redistribute it and/or modify it
+# under the terms of the GNU General Public License as published by the
+# Free Software Foundation; either version 3 of the License, or (at your
+# option) any later version.
+#
+# This program is distributed in the hope that it will be useful, but
+# WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
+# Public License for more details.
+#
+# You should have received a copy of the GNU General Public License along
+# with this program; if not, write to the Free Software Foundation, Inc.,
+# 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301, USA.
+
+"""Frame I/O utilities
+"""
+
+from .. import git_version
+__author__ = "Duncan Macleod <duncan.macleod@ligo.org>"
+__version__ = git_version.id
+__date__ = git_version.date
+
+from .frtools import *