lalsuite 7.26.2.dev20260106__cp314-cp314-macosx_13_0_x86_64.whl

lalburst/burca.py

@@ -0,0 +1,315 @@
+# Copyright (C) 2006--2011,2013,2015--2019,2021  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
+#
+# =============================================================================
+#
+
+
+from bisect import bisect_left, bisect_right
+import itertools
+import math
+import sys
+
+
+from igwn_ligolw import lsctables
+from igwn_segments import PosInfinity
+from . import snglcoinc
+
+
+__author__ = "Kipp Cannon <kipp.cannon@ligo.org>"
+from .git_version import date as __date__
+from .git_version import version as __version__
+
+
+#
+# =============================================================================
+#
+#                          CoincTables Customizations
+#
+# =============================================================================
+#
+
+
+#
+# For use with excess power.
+#
+
+
+ExcessPowerBBCoincDef = lsctables.CoincDef(search = "excesspower", search_coinc_type = 0, description = "sngl_burst<-->sngl_burst coincidences")
+
+
+class ExcessPowerCoincTables(snglcoinc.CoincTables):
+	def __init__(self, xmldoc):
+		super(ExcessPowerCoincTables, self).__init__(xmldoc)
+
+		# find the multi_burst table or create one if not found
+		try:
+			self.multibursttable = lsctables.MultiBurstTable.get_table(xmldoc)
+		except ValueError:
+			self.multibursttable = lsctables.MultiBurstTable.new(("process_id", "duration", "central_freq", "bandwidth", "snr", "confidence", "amplitude", "coinc_event_id"))
+			xmldoc.childNodes[0].appendChild(self.multibursttable)
+
+	def make_multi_burst(self, process_id, coinc_event_id, events, offset_vector):
+		multiburst = self.multibursttable.RowType(
+			process_id = process_id,
+			coinc_event_id = coinc_event_id,
+			# populate the false alarm rate with none.
+			false_alarm_rate = None
+		)
+
+		# snr = root sum of ms_snr squares
+
+		multiburst.snr = math.sqrt(sum(event.ms_snr**2.0 for event in events))
+
+		# peak time = ms_snr squared weighted average of peak times
+		# (no attempt to account for inter-site delays).
+		# LIGOTimeGPS objects don't like being multiplied by
+		# things, so the first event's peak time is used as a
+		# reference epoch.
+
+		t = events[0].peak + offset_vector[events[0].ifo]
+		multiburst.peak = t + sum(event.ms_snr**2.0 * float(event.peak + offset_vector[event.ifo] - t) for event in events) / multiburst.snr**2.0
+
+		# duration = ms_snr squared weighted average of durations
+
+		multiburst.duration = sum(event.ms_snr**2.0 * event.duration for event in events) / multiburst.snr**2.0
+
+		# central_freq = ms_snr squared weighted average of peak
+		# frequencies
+
+		multiburst.central_freq = sum(event.ms_snr**2.0 * event.peak_frequency for event in events) / multiburst.snr**2.0
+
+		# bandwidth = ms_snr squared weighted average of bandwidths
+
+		multiburst.bandwidth = sum(event.ms_snr**2.0 * event.bandwidth for event in events) / multiburst.snr**2.0
+
+		# confidence = minimum of confidences
+
+		multiburst.confidence = min(event.confidence for event in events)
+
+		# "amplitude" = h_rss of event with highest confidence
+
+		multiburst.amplitude = max(events, key = lambda event: event.ms_confidence).ms_hrss
+
+		# done
+
+		return multiburst
+
+	def coinc_rows(self, process_id, time_slide_id, events, table_name):
+		coinc, coincmaps = super(ExcessPowerCoincTables, self).coinc_rows(process_id, time_slide_id, events, table_name)
+		coinc.insts = (event.ifo for event in events)
+		return coinc, coincmaps, self.make_multi_burst(process_id, coinc.coinc_event_id, events, self.time_slide_index[time_slide_id])
+
+	def append_coinc(self, coinc, coincmaps, multiburst):
+		coinc = super(ExcessPowerCoincTables, self).append_coinc(coinc, coincmaps)
+		multiburst.coinc_event_id = coinc.coinc_event_id
+		self.multibursttable.append(multiburst)
+		return coinc
+
+
+#
+# For use with string cusp
+#
+
+
+StringCuspBBCoincDef = lsctables.CoincDef(search = "StringCusp", search_coinc_type = 0, description = "sngl_burst<-->sngl_burst coincidences")
+
+
+class StringCuspCoincTables(snglcoinc.CoincTables):
+	def coinc_rows(self, process_id, time_slide_id, events, table_name):
+		coinc, coincmaps = super(StringCuspCoincTables, self).coinc_rows(process_id, time_slide_id, events, table_name)
+		coinc.insts = (event.ifo for event in events)
+		return coinc, coincmaps
+
+
+#
+# =============================================================================
+#
+#                            Coincidence Generators
+#
+# =============================================================================
+#
+
+
+#
+# For use with excess power coincidence test
+#
+
+
+class ep_coincgen_doubles(snglcoinc.coincgen_doubles):
+	class singlesqueue(snglcoinc.coincgen_doubles.singlesqueue):
+		@staticmethod
+		def event_time(event):
+			return event.peak
+
+
+	class get_coincs(object):
+		@staticmethod
+		def max_edge_peak_delta(events):
+			# the largest difference between any event's peak
+			# time and either its start or stop times
+			if not events:
+				return 0.0
+			return max(max(float(event.peak - event.start), float(event.start + event.duration - event.peak)) for event in events)
+
+		@staticmethod
+		def comparefunc(a, offseta, b, coinc_window):
+			if abs(a.central_freq - b.central_freq) > (a.bandwidth + b.bandwidth) / 2:
+				return True
+
+			astart = a.start + offseta
+			bstart = b.start
+			if astart > bstart + b.duration + coinc_window:
+				# a starts after the end of b
+				return True
+
+			if bstart > astart + a.duration + coinc_window:
+				# b starts after the end of a
+				return True
+
+			# time-frequency times intersect
+			return False
+
+		def __init__(self, events):
+			self.events = events
+			self.times = tuple(map(ep_coincgen_doubles.singlesqueue.event_time, events))
+			# for this instance, replace the method with the
+			# pre-computed value
+			self.max_edge_peak_delta = self.max_edge_peak_delta(events)
+
+		def __call__(self, event_a, offset_a, coinc_window):
+			# event_a's peak time
+			peak = event_a.peak
+
+			# difference between event_a's peak and start times
+			dt = float(peak - event_a.start)
+
+			# largest difference between event_a's peak time
+			# and either its start or stop times
+			dt = max(dt, event_a.duration - dt)
+
+			# add our own max_edge_peak_delta and the light
+			# travel time between the two instruments (when
+			# done, if event_a's peak time differs by more than
+			# this much from the peak time of an event in this
+			# list then it is *impossible* for them to be
+			# coincident)
+			dt += self.max_edge_peak_delta + coinc_window
+
+			# apply time shift
+			peak += offset_a
+
+			# extract the subset of events from this list that
+			# pass coincidence with event_a (use bisection
+			# searches for the minimum and maximum allowed peak
+			# times to quickly identify a subset of the full
+			# list)
+			return [event_b for event_b in self.events[bisect_left(self.times, peak - dt) : bisect_right(self.times, peak + dt)] if not self.comparefunc(event_a, offset_a, event_b, coinc_window)]
+
+
+
+#
+# For use with string coincidence test
+#
+
+
+class string_coincgen_doubles(ep_coincgen_doubles):
+	class get_coincs(object):
+		def __init__(self, events):
+			self.events = events
+			self.times = tuple(map(string_coincgen_doubles.singlesqueue.event_time, events))
+
+		def __call__(self, event_a, offset_a, coinc_window):
+			peak = event_a.peak + offset_a
+			template_id = event_a.template_id
+			return [event for event in self.events[bisect_left(self.times, peak - coinc_window) : bisect_right(self.times, peak + coinc_window)] if event.template_id == template_id]
+
+
+#
+# =============================================================================
+#
+#                                 Library API
+#
+# =============================================================================
+#
+
+
+def burca(
+	xmldoc,
+	process_id,
+	coincgen_doubles,
+	CoincTables,
+	coinc_definer_row,
+	delta_t,
+	ntuple_comparefunc = lambda events, offset_vector: False,
+	min_instruments = 2,
+	incremental = True,
+	verbose = False
+):
+	#
+	# prepare the coincidence table interface.
+	#
+
+	if verbose:
+		print("indexing ...", file=sys.stderr)
+	coinc_tables = CoincTables(xmldoc, coinc_definer_row)
+
+	#
+	# construct offset vector assembly graph
+	#
+
+	time_slide_graph = snglcoinc.TimeSlideGraph(coincgen_doubles, coinc_tables.time_slide_index, delta_t, min_instruments = min_instruments, verbose = verbose)
+
+	#
+	# collect events.
+	#
+
+	sngl_burst_table = lsctables.SnglBurstTable.get_table(xmldoc)
+	if not incremental:
+		# normal version:  push everything into the graph, then
+		# pull out all coincs in one operation below using the
+		# final flush
+		for instrument, events in itertools.groupby(sorted(sngl_burst_table, key = lambda row: row.ifo), lambda event: event.ifo):
+			time_slide_graph.push(instrument, tuple(events), PosInfinity)
+	else:
+		# slower diagnostic version.  simulate an online
+		# incremental analysis by pushing events into the graph in
+		# time order and collecting candidates as we go.  we still
+		# do the final flush operation below.
+		for instrument, events in itertools.groupby(sorted(sngl_burst_table, key = lambda row: (row.peak, row.ifo)), lambda event: event.ifo):
+			events = tuple(events)
+			if time_slide_graph.push(instrument, events, max(event.peak for event in events)):
+				for node, events in time_slide_graph.pull(coinc_sieve = ntuple_comparefunc):
+					coinc_tables.append_coinc(*coinc_tables.coinc_rows(process_id, node.time_slide_id, events, "sngl_burst"))
+
+	#
+	# retrieve all remaining coincidences.
+	#
+
+	for node, events in time_slide_graph.pull(coinc_sieve = ntuple_comparefunc, flush = True):
+		coinc_tables.append_coinc(*coinc_tables.coinc_rows(process_id, node.time_slide_id, events, "sngl_burst"))
+
+	#
+	# done
+	#
+
+	return xmldoc

lalburst/burca_tailor.py

@@ -0,0 +1,349 @@
+# Copyright (C) 2007--2021  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 copy
+import itertools
+import math
+import sys
+
+
+import lal
+from lal import rate
+
+
+from igwn_ligolw import ligolw
+from igwn_ligolw import lsctables
+from igwn_ligolw import utils as ligolw_utils
+from igwn_ligolw.utils import process as ligolw_process
+from igwn_ligolw.utils import search_summary as ligolw_search_summary
+from . import snglcoinc
+from .SimBurstUtils import MW_CENTER_J2000_RA_RAD, MW_CENTER_J2000_DEC_RAD
+
+
+__author__ = "Kipp Cannon <kipp.cannon@ligo.org>"
+from .git_version import date as __date__
+from .git_version import version as __version__
+
+
+#
+# =============================================================================
+#
+#                Excess Power Specific Parameter Distributions
+#
+# =============================================================================
+#
+
+
+class LnLRDensity(snglcoinc.LnLRDensity):
+	def __init__(self, instruments):
+		self.densities = {}
+		for pair in intertools.combinations(sorted(instruments), 2):
+			# FIXME:  hard-coded for directional search
+			#dt = 0.02 + snglcoinc.light_travel_time(*pair)
+			dt = 0.02
+			self.densities["%s_%s_dt" % pair] = rate.BinnedLnDPF(rate.NDBins((rate.ATanBins(-dt, +dt, 12001), rate.LinearBins(0.0, 2 * math.pi, 61))))
+			self.densities["%s_%s_dband" % pair] = rate.BinnedLnDPF(rate.NDBins((rate.LinearBins(-2.0, +2.0, 12001), rate.LinearBins(0.0, 2 * math.pi, 61))))
+			self.densities["%s_%s_ddur" % pair] = rate.BinnedLnDPF(rate.NDBins((rate.LinearBins(-2.0, +2.0, 12001), rate.LinearBins(0.0, 2 * math.pi, 61))))
+			self.densities["%s_%s_df" % pair] = rate.BinnedLnDPF(rate.NDBins((rate.LinearBins(-2.0, +2.0, 12001), rate.LinearBins(0.0, 2 * math.pi, 61))))
+			self.densities["%s_%s_dh" % pair] = rate.BinnedLnDPF(rate.NDBins((rate.LinearBins(-2.0, +2.0, 12001), rate.LinearBins(0.0, 2 * math.pi, 61))))
+
+	def __call__(self, **params):
+		try:
+			interps = self.interps
+		except AttributeError:
+			self.mkinterps()
+			interps = self.interps
+		return sum(interps[param](value) for param, value in params.items())
+
+	def __iadd__(self, other):
+		if type(self) != type(other) or set(self.densities) != set(other.densities):
+			raise TypeError("cannot add %s and %s" % (type(self), type(other)))
+		for key, pdf in self.densities.items():
+			pdf += other.densities[key]
+		del self.interps
+		return self
+
+	def increment(self, params, weight = 1.0):
+		for param, value in params.items():
+			self.densities[param].count[value] += weight
+
+	def copy(self):
+		new = type(self)([])
+		for key, pdf in self.densities.items():
+			new.densities[key] = pdf.copy()
+		return new
+
+	def mkinterps(self):
+		self.interps = dict((key, pdf.mkinterp()) for key, pdf in self.densities.items())
+
+	def finish(self):
+		for key, pdf in self.densities.items():
+			rate.filter_array(pdf.array, rate.gaussian_window(11, 5))
+			pdf.normalize()
+		self.mkinterps()
+
+	def to_xml(self, name):
+		xml = super(LnLRDensity, self).to_xml(name)
+		instruments =  set(key.split("_", 2)[0] for key in self.densities if key.endswith("_dt"))
+		instruments |= set(key.split("_", 2)[1] for key in self.densities if key.endswith("_dt"))
+		xml.appendChild(ligolw.Param.from_pyvalue("instruments", lsctables.instrumentsproperty.set(instruments)))
+		for key, pdf in self.densities.items():
+			xml.appendChild(pdf.to_xml(key))
+		return xml
+
+	@classmethod
+	def from_xml(cls, xml, name):
+		xml = cls.get_xml_root(xml, name)
+		self = cls(lsctables.instrumentsproperty.get(ligolw.Param.get_param(xml, "instruments").value))
+		for key in self.densities:
+			self.densities[key] = rate.BinnedLnPDF.from_xml(xml, key)
+		return self
+
+
+class BurcaCoincParamsDistributions(snglcoinc.LnLikelihoodRatioMixin):
+	ligo_lw_name_suffix = "excesspower_coincparamsdistributions"
+
+	def __init__(self, instruments):
+		self.numerator = LnLRDensity(instruments)
+		self.denominator = LnLRDensity(instruments)
+		self.candidates = LnLRDensity(instruments)
+
+	def __iadd__(self, other):
+		if type(self) != type(other):
+			raise TypeError(other)
+		self.numerator += other.numerator
+		self.denominator += other.denominator
+		self.candidates += other.candidates
+		return self
+
+	def copy(self):
+		new = type(self)([])
+		new.numerator = self.numerator.copy()
+		new.denominator = self.denominator.copy()
+		new.candidates = self.candidates.copy()
+		return new
+
+	def finish(self):
+		self.numerator.finish()
+		self.denominator.finish()
+		self.candidates.finish()
+
+	@classmethod
+	def get_xml_root(cls, xml, name):
+		name = "%s:%s" % (name, cls.ligo_lw_name_suffix)
+		xml = [elem for elem in xml.getElementsByTagName(ligolw.LIGO_LW.tagName) if elem.hasAttribute("Name") and elem.Name == name]
+		if len(xml) != 1:
+			raise ValueError("XML tree must contain exactly one %s element named %s" % (ligolw.LIGO_LW.tagName, name))
+		return xml[0]
+
+	@classmethod
+	def from_xml(cls, xml, name):
+		xml = cls.get_xml_root(xml, name)
+		self = cls([])
+		self.numerator = LnLRDensity.from_xml(xml, "numerator")
+		self.denominator = LnLRDensity.from_xml(xml, "denominator")
+		self.candidates = LnLRDensity.from_xml(xml, "candidates")
+
+	def to_xml(self, name):
+		xml = ligolw.LIGO_LW({"Name": "%s:%s" % (name, self.ligo_lw_name_suffix)})
+		xml.appendChild(self.numerator.to_xml("numerator"))
+		xml.appendChild(self.denominator.to_xml("denominator"))
+		xml.appendChild(self.candidates.to_xml("candidates"))
+		return xml
+
+	@classmethod
+	def from_filenames(cls, filenames, name, verbose = False):
+		"""
+		Convenience function to deserialize
+		CoincParamsDistributions objects from a collection of XML
+		files and return their sum.  The return value is a
+		two-element tuple.  The first element is the deserialized
+		and summed CoincParamsDistributions object, the second is a
+		segmentlistdict indicating the interval of time spanned by
+		the out segments in the search_summary rows matching the
+		process IDs that were attached to the
+		CoincParamsDistributions objects in the XML.
+		"""
+		self = None
+		for n, filename in enumerate(filenames, 1):
+			if verbose:
+				print("%d/%d:" % (n, len(filenames)), end=' ', file=sys.stderr)
+			xmldoc = ligolw_utils.load_filename(filename, verbose = verbose)
+			if self is None:
+				self = cls.from_xml(xmldoc, name)
+				seglists = lsctables.SearchSummaryTable.get_table(xmldoc).get_out_segmentlistdict(set([self.process_id])).coalesce()
+			else:
+				other = cls.from_xml(xmldoc, name)
+				self += other
+				seglists |= lsctables.SearchSummaryTable.get_table(xmldoc).get_out_segmentlistdict(set([other.process_id])).coalesce()
+				del other
+			xmldoc.unlink()
+		return self, seglists
+
+
+#
+# All sky version
+#
+
+
+class EPAllSkyCoincParamsDistributions(BurcaCoincParamsDistributions):
+	def ln_lr_from_triggers(self, events, offsetvector):
+		#
+		# check for coincs that have been vetoed entirely
+		#
+
+		if len(events) < 2:
+			return None
+
+		params = {}
+
+		# the "time" is the ms_snr squared weighted average of the
+		# peak times neglecting light-travel times.  because
+		# LIGOTimeGPS objects have overflow problems in this sort
+		# of a calculation, the first event's peak time is used as
+		# an epoch and the calculations are done w.r.t. that time.
+
+		# FIXME: this time is available as the peak_time in the
+		# multi_burst table, and it should be retrieved from that
+		# table instead of being recomputed
+		events = tuple(events)
+		t = events[0].peak
+		t += sum(float(event.peak - t) * event.ms_snr**2.0 for event in events) / sum(event.ms_snr**2.0 for event in events)
+		gmst = lal.GreenwichMeanSiderealTime(t) % (2 * math.pi)
+
+		for event1, event2 in itertools.combinations(sorted(events, key = lambda x: x.ifo), 2):
+			if event1.ifo == event2.ifo:
+				# a coincidence is parameterized only by
+				# inter-instrument deltas
+				continue
+
+			prefix = "%s_%s_" % (event1.ifo, event2.ifo)
+
+			# in each of the following, if the list of events contains
+			# more than one event from a given instrument, the smallest
+			# deltas are recorded
+
+			dt = float(event1.peak + offsetvector[event1.ifo] - event2.peak - offsetvector[event2.ifo])
+			name = "%sdt" % prefix
+			if name not in params or abs(params[name][0]) > abs(dt):
+				#params[name] = (dt,)
+				params[name] = (dt, gmst)
+
+			df = (event1.peak_frequency - event2.peak_frequency) / ((event1.peak_frequency + event2.peak_frequency) / 2)
+			name = "%sdf" % prefix
+			if name not in params or abs(params[name][0]) > abs(df):
+				#params[name] = (df,)
+				params[name] = (df, gmst)
+
+			dh = (event1.ms_hrss - event2.ms_hrss) / ((event1.ms_hrss + event2.ms_hrss) / 2)
+			name = "%sdh" % prefix
+			if name not in params or abs(params[name][0]) > abs(dh):
+				#params[name] = (dh,)
+				params[name] = (dh, gmst)
+
+			dband = (event1.ms_bandwidth - event2.ms_bandwidth) / ((event1.ms_bandwidth + event2.ms_bandwidth) / 2)
+			name = "%sdband" % prefix
+			if name not in params or abs(params[name][0]) > abs(dband):
+				#params[name] = (dband,)
+				params[name] = (dband, gmst)
+
+			ddur = (event1.ms_duration - event2.ms_duration) / ((event1.ms_duration + event2.ms_duration) / 2)
+			name = "%sddur" % prefix
+			if name not in params or abs(params[name][0]) > abs(ddur):
+				#params[name] = (ddur,)
+				params[name] = (ddur, gmst)
+
+		return self(**params)
+
+
+#
+# Galactic core coinc params
+#
+
+
+def delay_and_amplitude_correct(event, ra, dec):
+	# retrieve station metadata
+
+	detector = lal.cached_detector_by_prefix[event.ifo]
+
+	# delay-correct the event to the geocentre
+
+	delay = lal.TimeDelayFromEarthCenter(detector.location, ra, dec, event.peak)
+	event.peak -= delay
+	event.period = event.period.shift(-delay)
+	try:
+		event.ms_peak -= delay
+	except AttributeError:
+		pass
+	try:
+		event.ms_period = event.ms_period.shift(-delay)
+	except AttributeError:
+		pass
+
+	# amplitude-correct the event using the polarization-averaged
+	# antenna response
+
+	fp, fc = lal.ComputeDetAMResponse(detector.response, ra, dec, 0, lal.GreenwichMeanSiderealTime(event.peak))
+	mean_response = math.sqrt(fp**2 + fc**2)
+	event.amplitude /= mean_response
+	event.ms_hrss /= mean_response
+
+	# done
+
+	return event
+
+
+class EPGalacticCoreCoincParamsDistributions(BurcaCoincParamsDistributions):
+	def ln_lr_from_triggers(self, events, offsetvector):
+		ra, dec = MW_CENTER_J2000_RA_RAD, MW_CENTER_J2000_DEC_RAD
+		return EPAllSkyCoincParamsDistributions.coinc_params([delay_and_amplitude_correct(copy.copy(event), ra, dec) for event in events], offsetvector)
+
+
+#
+# =============================================================================
+#
+#                                     I/O
+#
+# =============================================================================
+#
+
+
+process_program_name = "lalburst_power_meas_likelihood"
+
+
+def gen_likelihood_control(coinc_params_distributions, seglists, name = process_program_name, comment = ""):
+	xmldoc = ligolw.Document()
+	node = xmldoc.appendChild(ligolw.LIGO_LW())
+
+	process = ligolw_process.register_to_xmldoc(xmldoc, program = process_program_name, paramdict = {}, version = __version__, cvs_repository = "lscsoft", cvs_entry_time = __date__, comment = comment)
+	coinc_params_distributions.process_id = process.process_id
+	ligolw_search_summary.append_search_summary(xmldoc, process, ifos = seglists.keys(), inseg = seglists.extent_all(), outseg = seglists.extent_all())
+
+	node.appendChild(coinc_params_distributions.to_xml(name))
+
+	process.set_end_time_now()
+
+	return xmldoc