lalsuite 7.26.2.dev20251210__cp312-cp312-macosx_12_0_arm64.whl

lalburst/date.py

@@ -0,0 +1,118 @@
+# Copyright (C) 2006,2007,2009,2015-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
+#
+# =============================================================================
+#
+
+
+"""
+This module provides a few time-related utilities that have been used in
+burst searches in the past.
+"""
+
+
+import math
+
+
+import lal
+
+
+__author__ = "Kipp Cannon <kipp.cannon@ligo.org>"
+from .git_version import date as __date__
+from .git_version import version as __version__
+
+
+#
+# =============================================================================
+#
+#                              Function Wrappers
+#
+# =============================================================================
+#
+
+
+def XLALTimeDelayFromEarthCenter(pos, ra, dec, gps):
+	return lal.ArrivalTimeDiff(pos, (0.0, 0.0, 0.0), ra, dec, gps)
+
+
+#
+# =============================================================================
+#
+#                               Time Generators
+#
+# =============================================================================
+#
+
+
+def utc_midnight(gps):
+	"""
+	Truncate a LIGOTimeGPS to UTC midnight.
+	"""
+	# convert to UTC (as list so we can edit it)
+	tm = list(lal.GPSToUTC(int(gps)))
+
+	# truncate to midnight
+	tm[3] = 0       # hours
+	tm[4] = 0       # minutes
+	tm[5] = 0       # seconds
+
+	# convert back to LIGOTimeGPS
+	return lal.LIGOTimeGPS(lal.UTCToGPS(tuple(tm)))
+
+
+def UTCMidnights(start, end):
+	"""
+	Iterator for generating LIGOTimeGPS objects for UTC midnights.
+	"""
+	# 86402 == more seconds than there are in 1 day, but less than
+	# there are in 2 days.  Can 1 day have more than 1 leap second?  If
+	# so, this constant should be increased.
+	midnight = utc_midnight(start)
+	if midnight < start:
+		midnight = utc_midnight(midnight + 86402)
+	while midnight < end:
+		yield midnight
+		midnight = utc_midnight(midnight + 86402)
+
+
+def gmst_0h(gps):
+	"""
+	Truncate a LIGOTimeGPS to Greenwich mean sidereal 0 rad.
+	"""
+	gmst = lal.GreenwichMeanSiderealTime(gps)
+	residual = gmst % (2.0 * math.pi)
+	if residual:
+		gmst -= residual
+	return lal.GreenwichMeanSiderealTimeToGPS(gmst)
+
+
+def GMST_0hs(start, end):
+	"""
+	Iterator for generating LIGOTimeGPS objects for Greenwich Mean
+	Sidereal 0h.
+	"""
+	midnight = gmst_0h(start)
+	if midnight < start:
+		midnight = gmst_0h(midnight + 86402)
+	while midnight < end:
+		yield midnight
+		midnight = gmst_0h(midnight + 86402)

lalburst/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 = "eeff03c6df54cc1b9aa861018eac9ca5072a0a77"
+date = "2025-12-4 04:45: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: eeff03c6df54cc1b9aa861018eac9ca5072a0a77
+
+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 == "eeff03c6df54cc1b9aa861018eac9ca5072a0a77":
+        return
+    msg = "Program id (eeff03c6df54cc1b9aa861018eac9ca5072a0a77) does not match given id (%s)." % foreign_id
+    if onmismatch == "raise":
+        raise VersionMismatchError(msg)
+
+    # in the backtrace, show calling code
+    warnings.warn(msg, UserWarning)

lalburst/offsetvector.py

@@ -0,0 +1,278 @@
+# Copyright (C) 2010--2013,2015,2016,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
+
+
+__author__ = "Kipp Cannon <kipp.cannon@ligo.org>"
+from .git_version import date as __date__
+from .git_version import version as __version__
+
+
+#
+# =============================================================================
+#
+#                                Offset Vector
+#
+# =============================================================================
+#
+
+
+class offsetvector(dict):
+	"""
+	Subclass of the dict built-in type for storing mappings of
+	instrument to time offset.
+
+	Examples:
+
+	>>> x = offsetvector({"H1": 0, "L1": 10, "V1": 20})
+	>>> x["H1"]
+	0
+	>>> not any(x.values())	# check for "zero-lag"
+	False
+	"""
+	@property
+	def refkey(self):
+		"""
+		= min(self)
+
+		Raises ValueError if the offsetvector is empty.
+		"""
+		# min() emits ValueError when the list is empty, but it
+		# might also emit a ValueError if the comparison operations
+		# inside it fail, so we can't simply wrap it in a
+		# try/except pair or we might mask genuine failures
+		if not self:
+			raise ValueError("offsetvector is empty")
+		return min(self)
+
+	@property
+	def deltas(self):
+		"""
+		Dictionary of relative offsets.  The keys in the result are
+		pairs of keys from the offset vector, (a, b), and the
+		values are the relative offsets, (offset[b] - offset[a]).
+		Raises ValueError if the offsetvector is empty (WARNING:
+		this behaviour might change in the future).
+
+		Example:
+
+		>>> x = offsetvector({"H1": 0, "L1": 10, "V1": 20})
+		>>> assert x.deltas == {('H1', 'L1'): 10, ('H1', 'V1'): 20, ('H1', 'H1'): 0}
+		>>> y = offsetvector({'H1': 100, 'L1': 110, 'V1': 120})
+		>>> y.deltas == x.deltas
+		True
+
+		Note that the result always includes a "dummy" entry,
+		giving the relative offset of self.refkey with respect to
+		itself, which is always 0.
+
+		See also .fromdeltas().
+
+		BUGS:  I think the keys in each tuple should be reversed.
+		I can't remember why I put them in the way they are.
+		Expect them to change in the future.
+		"""
+		# FIXME:  instead of raising ValueError when the
+		# offsetvector is empty this should return an empty
+		# dictionary.  the inverse, .fromdeltas() accepts
+		# empty dictionaries
+		# NOTE:  the arithmetic used to construct the offsets
+		# *must* match the arithmetic used by
+		# time_slide_component_vectors() so that the results of the
+		# two functions can be compared to each other without worry
+		# of floating-point round off confusing things.
+		refkey = self.refkey
+		refoffset = self[refkey]
+		return dict(((refkey, key), self[key] - refoffset) for key in self)
+
+	def __str__(self, compact = False):
+		"""
+		Return a human-readable string representation of an offset
+		vector.
+
+		Example:
+
+		>>> a = offsetvector({"H1": -10.1234567, "L1": 0.125})
+		>>> str(a)
+		'H1 = -10.1234567 s, L1 = +0.125 s'
+		>>> a.__str__(compact = True)
+		'H1=-10.123,L1=0.125'
+		"""
+		if compact:
+			return ",".join(("%s=%.5g" % x) for x in sorted(self.items()))
+		return ", ".join(("%s = %+.16g s" % x) for x in sorted(self.items()))
+
+	def __repr__(self):
+		"""
+		Return a string representation of the offset vector.
+		Running eval() on the result reconstructs the offsetvector.
+
+		Example:
+
+		>>> a = offsetvector({"H1": -10.1234567, "L1": 0.1})
+		>>> b = eval(repr(a))
+		>>> b == a
+		True
+		>>> b is a
+		False
+		>>> c = offsetvector({"H1": -10.1234567})
+		>>> repr(c)
+		"offsetvector({'H1': -10.1234567})"
+		"""
+		return "%s(%s)" % (self.__class__.__name__, dict.__repr__(self))
+
+	def __abs__(self):
+		"""
+		Returns max(offset) - min(offset).
+
+		Example:
+
+		>>> abs(offsetvector({"H1": 0.0, "H2": 0.0, "L1": 0.0}))
+		0.0
+		>>> abs(offsetvector({"H1": 10.0, "H2": 10.0, "L1": 10.0}))
+		0.0
+		>>> abs(offsetvector({'H1': 10.0, 'L1': 0.0, 'V1': -10.0}))
+		20.0
+		"""
+		return max(self.values()) - min(self.values())
+
+	def contains(self, other):
+		"""
+		Returns True if offset vector other can be found in self,
+		False otherwise.  An offset vector is "found in" another
+		offset vector if the latter contains all of the former's
+		instruments and the relative offsets among those
+		instruments are equal (the absolute offsets need not be).
+
+		Example:
+
+		>>> a = offsetvector({"H1": 10, "L1": 20, "V1": 30})
+		>>> b = offsetvector({"H1": 20, "V1": 40})
+		>>> a.contains(b)
+		True
+
+		Note the distinction between this and the "in" operator:
+
+		>>> "H1" in a
+		True
+		"""
+		return offsetvector((key, offset) for key, offset in self.items() if key in other).deltas == other.deltas
+
+	def normalize(self, **kwargs):
+		"""
+		Adjust the offsetvector so that a particular instrument has
+		the desired offset.  All other instruments have their
+		offsets adjusted so that the relative offsets are
+		preserved.  The instrument to noramlize, and the offset one
+		wishes it to have, are provided as a key-word argument.
+		The return value is the time slide dictionary, which is
+		modified in place.
+
+		If more than one key-word argument is provided the keys are
+		sorted and considered in order until a key is found that is
+		in the offset vector.  The offset vector is normalized to
+		that value.  This function is a no-op if no key-word
+		argument is found that applies.
+
+		Example:
+
+		>>> a = offsetvector({"H1": -10, "H2": -10, "L1": -10})
+		>>> assert a.normalize(L1 = 0) == offsetvector({'H2': 0, 'H1': 0, 'L1': 0})
+		>>> a = offsetvector({"H1": -10, "H2": -10})
+		>>> assert a.normalize(L1 = 0, H2 = 5) == offsetvector({'H2': 5, 'H1': 5})
+		"""
+		# FIXME:  should it be performed in place?  if it should
+		# be, the should there be no return value?
+		for key, offset in sorted(kwargs.items()):
+			if key in self:
+				delta = offset - self[key]
+				for key in self.keys():
+					self[key] += delta
+				break
+		return self
+
+	@classmethod
+	def fromdeltas(cls, deltas):
+		"""
+		Construct an offsetvector from a dictionary of offset
+		deltas as returned by the .deltas attribute.
+
+		Example:
+
+		>>> x = offsetvector({"H1": 0, "L1": 10, "V1": 20})
+		>>> y = offsetvector.fromdeltas(x.deltas)
+		>>> y == x
+		True
+
+		See also .deltas, .fromkeys()
+		"""
+		return cls((key, value) for (refkey, key), value in deltas.items())
+
+
+#
+# =============================================================================
+#
+#                                  Utilities
+#
+# =============================================================================
+#
+
+
+def component_offsetvectors(offsetvectors, n):
+	"""
+	Given an iterable of offset vectors, return the shortest list of
+	the unique n-instrument offset vectors from which all the vectors
+	in the input iterable can be constructed.  This can be used to
+	determine the minimal set of n-instrument coincs required to
+	construct all of the coincs for all of the requested instrument and
+	offset combinations in a set of offset vectors.
+
+	It is assumed that the coincs for the vector {"H1": 0, "H2": 10,
+	"L1": 20} can be constructed from the coincs for the vectors {"H1":
+	0, "H2": 10} and {"H2": 0, "L1": 10}, that is only the relative
+	offsets are significant in determining if two events are
+	coincident, not the absolute offsets.
+	"""
+	#
+	# collect unique instrument set / deltas combinations
+	#
+
+	delta_sets = {}
+	for vect in offsetvectors:
+		for instruments in itertools.combinations(sorted(vect), n):
+			# NOTE:  the arithmetic used to construct the
+			# offsets *must* match the arithmetic used by
+			# offsetvector.deltas so that the results of the
+			# two can be compared to each other without worry
+			# of floating-point round off confusing things.
+			delta_sets.setdefault(instruments, set()).add(tuple(vect[instrument] - vect[instruments[0]] for instrument in instruments))
+
+	#
+	# translate into a list of normalized n-instrument offset vectors
+	#
+
+	return [offsetvector(zip(instruments, deltas)) for instruments, delta_set in delta_sets.items() for deltas in delta_set]

lalburst/packing.py

@@ -0,0 +1,170 @@
+# Copyright (C) 2006,2016,2017,2020  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
+#
+# =============================================================================
+#
+
+
+"""
+This module provides bin packing utilities.
+"""
+
+
+__author__ = "Kipp Cannon <kipp.cannon@ligo.org>"
+from .git_version import date as __date__
+from .git_version import version as __version__
+
+
+#
+# =============================================================================
+#
+#                                     Bins
+#
+# =============================================================================
+#
+
+
+# FIXME:  this should probably be a subclass of list, but no doubt that will
+# break things so make this change some time it's convenient.
+
+
+class Bin(object):
+	"""
+	Bin object for use in packing algorithm implementations.  A Bin
+	instance has two attributes:  size, which is the total "size" of
+	the contents of the Bin, and objects, which is a list of the Bins
+	contents.
+
+	Example:
+
+	>>> strings = Bin()
+	>>> s = "hello"
+	>>> strings.add(s, len(s))
+	>>> s.objects
+	['hello']
+	>>> s.size
+	5
+	"""
+	def __init__(self):
+		"""
+		Initialize a new Bin instance.
+		"""
+		self.objects = []
+		self.size = 0
+
+	def add(self, obj, size):
+		"""
+		Add the object, whose size is as given, to the bin.
+		"""
+		self.objects.append(obj)
+		self.size += size
+		return self
+
+	def __iadd__(self, other):
+		"""
+		Add the contents of another Bin object to this one.
+		"""
+		self.objects.extend(other.objects)
+		self.size += other.size
+		return self
+
+	#
+	# Compare two Bin objects by their sizes.
+	#
+
+	def __lt__(self, other):
+		return self.size < other.size
+
+	def __le__(self, other):
+		return self.size <= other.size
+
+	def __eq__(self, other):
+		return self.size == other.size
+
+	def __ne__(self, other):
+		return self.size != other.size
+
+	def __ge__(self, other):
+		return self.size >= other.size
+
+	def __gt__(self, other):
+		return self.size > other.size
+
+	def __repr__(self):
+		"""
+		A representation of the Bin object.
+		"""
+		return "Bin(size=%s, %s)" % (str(self.size), str(self.objects))
+
+	__str__ = __repr__
+
+
+#
+# =============================================================================
+#
+#                              Packing Algorithms
+#
+# =============================================================================
+#
+
+
+# FIXME:  this should probably also be a subclass of list.
+
+class Packer(object):
+	"""
+	Parent class for packing algorithms.  Specific packing algorithms
+	should sub-class this, providing implementations of the pack() and
+	packlist() methods.
+	"""
+	def __init__(self, bins):
+		"""
+		Set the list of bins on which we shall operate
+		"""
+		self.bins = bins
+
+	def pack(self, size, obj):
+		"""
+		Pack an object of given size into the bins.
+		"""
+		raise NotImplementedError
+
+	def packlist(self, size_object_pairs):
+		"""
+		Pack a list of (size, object) tuples into the bins.
+
+		Default implementation invokes self.pack() on each pair in
+		the the order given.
+		"""
+		for size, obj in size_object_pairs:
+			self.pack(size, obj)
+
+
+class BiggestIntoEmptiest(Packer):
+	"""
+	Packs the biggest object into the emptiest bin.
+	"""
+	def pack(self, size, obj):
+		min(self.bins).add(obj, size)
+
+	def packlist(self, size_object_pairs):
+		for size, obj in sorted(size_object_pairs, reverse = True):
+			self.pack(size, obj)