Detailed Description

Time-of-arrival triangulator.

See section 6.6.4 of "Gravitational-Wave Physics and Astronomy" by Creighton and Anderson.

An instance of this class is a function-like object that accepts a tuple of event arival times and returns a tuple providing information derived by solving for the maximum-likelihood source location assuming Gaussian-distributed timing errors.

Definition at line 1999 of file snglcoinc.py.

Inherits object.

Public Member Functions
def	__init__ (self, rs, sigmas, v=lal.C_SI)
	Create and initialize a triangulator object. More...

def	__call__ (self, ts)
	Triangulate the direction to the source of a signal based on a tuple of times when the signal was observed. More...

Static Public Member Functions
def	dir2coord (n, gps)
	This transforms from propagation direction vector to right ascension and declination source co-ordinates. More...

Data Fields
	rs

	sigmas

	v

	R

	VT

	singular

	max_dt

Constructor & Destructor Documentation

◆ init()

def lalburst.snglcoinc.TOATriangulator.__init__	(	self,
		rs,
		sigmas,
		v = `lal.C_SI`
	)

Create and initialize a triangulator object.

rs is a sequence of location 3-vectors, sigmas is a sequence of the timing uncertainties for those locations. Both sequences must be in the same order — the first sigma in the sequence is interpreted as belonging to the first location 3-vector — and, of course, they must be the same length.

v is the speed at which the wave carrying the signals travels. The rs 3-vectors carry units of distance, the sigmas carry units of time, v carries units of distance/time. What units are used for the three is arbitrary, but they must be mutually consistent. The default value for v in c, the speed of light, in metres/second, therefore the location 3-vectors should be given in metres and the sigmas should be given in seconds unless a value for v is provided with different units.

Example:

‍from numpy import array triangulator = TOATriangulator([ ... array([-2161414.92636, -3834695.17889, 4600350.22664]), ... array([ -74276.0447238, -5496283.71971 , 3224257.01744 ]), ... array([ 4546374.099 , 842989.697626, 4378576.96241 ]) ... ], [ ... 0.005, ... 0.005, ... 0.005 ... ]) ...

This creates a TOATriangulator instance configured for the LIGO Hanford, LIGO Livingston and Virgo antennas with 5 ms time-of-arrival uncertainties at each location.

Note: rs and sigmas may be iterated over multiple times.

Definition at line 2041 of file snglcoinc.py.

Member Function Documentation

◆ call()

def lalburst.snglcoinc.TOATriangulator.__call__	(	self,
		ts
	)

Triangulate the direction to the source of a signal based on a tuple of times when the signal was observed.

ts is a sequence of signal arrival times. One arrival time must be provided for each of the observation locations provided when the instance was created, and the units of the arrival times must be the same as the units used for the sequence of sigmas.

The return value is a tuple of information derived by solving for the maximum-likelihood source location assuming Gaussian-distributed timing errors. The return value is

   (n, toa, chi2 / DOF, dt)

where n is a unit 3-vector pointing from the co-ordinate origin towards the source of the signal, toa is the time-of-arrival of the signal at the co-ordinate origin, chi2 / DOF is the \chi^{2} per degree-of-freedom from to the arrival time residuals, and dt is the root-sum-square of the arrival time residuals.

Example:

‍from numpy import array from numpy import testing triangulator = TOATriangulator([ ... array([-2161414.92636, -3834695.17889, 4600350.22664]), ... array([ -74276.0447238, -5496283.71971 , 3224257.01744 ]), ... array([ 4546374.099 , 842989.697626, 4378576.96241 ]) ... ], [ ... 0.005, ... 0.005, ... 0.005 ... ]) ... n, toa, chi2_per_dof, dt = triangulator([ ... 794546669.429688, ... 794546669.41333, ... 794546669.431885 ... ]) ... n array([[-0.45605637, 0.75800934, 0.46629865], [-0.45605637, 0.75800934, 0.46629865]]) testing.assert_approx_equal(toa, 794546669.4269662) testing.assert_approx_equal(chi2_per_dof, 0.47941941158371465) testing.assert_approx_equal(dt, 0.005996370224459011)

NOTE: if len(rs) >= 4, n is a 1x3 array. if len(rs) == 3, n is a 2x3 array. if len(rs) == 2, n is None. NOTE: n is not the source direction but the propagation direction of GW. Therefore, if you want source direction, you have to multiply -1. NOTE: n is represented by earth fixed coordinate, not celestial coordinate. Up to your purpose, you should transform \phi -> RA. To do it, you can use dir2coord.

Definition at line 2129 of file snglcoinc.py.

◆ dir2coord()

def lalburst.snglcoinc.TOATriangulator.dir2coord	(	n,
		gps
	)

static

This transforms from propagation direction vector to right ascension and declination source co-ordinates.

The input is the propagation vector, n, in Earth fixed co-ordinates (x axis through Greenwich merdian and equator, z axis through North Pole), and the time. n does not need to be a unit vector. The return value is the (ra, dec) pair, in radians. NOTE: right ascension is not necessarily in [0, 2\pi).

Definition at line 2269 of file snglcoinc.py.

Field Documentation

◆ rs

lalburst.snglcoinc.TOATriangulator.rs

Definition at line 2045 of file snglcoinc.py.

◆ sigmas

lalburst.snglcoinc.TOATriangulator.sigmas

Definition at line 2046 of file snglcoinc.py.

◆ v

lalburst.snglcoinc.TOATriangulator.v

Definition at line 2047 of file snglcoinc.py.

◆ R

lalburst.snglcoinc.TOATriangulator.R

Definition at line 2053 of file snglcoinc.py.

◆ VT

lalburst.snglcoinc.TOATriangulator.VT

Definition at line 2058 of file snglcoinc.py.

◆ singular

lalburst.snglcoinc.TOATriangulator.singular

Definition at line 2063 of file snglcoinc.py.

◆ max_dt

lalburst.snglcoinc.TOATriangulator.max_dt

Definition at line 2066 of file snglcoinc.py.