Python Bindings

Python

Python3 bindings are available to interface to the xcloc library. Unless the library path is explicitly specified then it is important to understand that Python will scrape the system's load library path, LD_LIBRARY_PATH, in attempt to find the xcloc shared library. After the library is obtained a ctypes interface is used to directly call xcloc.

Getting Started

After installing xcloc and setting the LD_LIBRARY_PATH in one's bashrc, e.g,.

LD_LIBRARY_PATH=${LD_LIBRARY_PATH}:/path/to/xcloc/lib

one can should now be ready to use the Python bindings.

TODO: There is currently no setup.py!

An Example

Python is by far the easiest way to learn how to use xcloc. Here, a 2D earthquake location example presented. In principle, there are only ? steps.

Initialize xcloc

The first task is to initialize the xcloc Python class. This can be done by

 from xcloc import xcloc
 xcloc = xcloc()
 xcloc.initialize(dt, npts, ngrd, nsignals=nsignals)

where dt is the the sampling period in seconds, npts is the number of points in the input signals, nsignals defines the number signals, and ngrd defines the number of grid points in the resulting image. In this case, there will be (nsignals*(nsignals - 1))/2 correlation pairs. It is also possible to specify a table of correlation pairs.

Initialization should be done only once at program startup as initialization is a fairly expensive task. If, for whatever reason, the initialization parameters must be changed it is recommended to call xcloc.finalize() and re-initialize.

Set the travel time fields

After xcloc has been initialized one needs to set the travel time fields that will be used in correlation. All travel time fields must be set prior to migrating and internal checking will prevent program failure by requiring the max differential travel time not exceed the length of the correlograms.

for i in range(nsignals):
    xcloc.setTable(i, t)

where i is the signal number and t is the travel times from the receiver to all [ngrd] grid points. One should only need to set the travel time tables once.

Set the signals

After xcloc has been initialized and the travel time tables set the algorithm is in a position to begin processing windows of data. One can set the signals in a window that will be cross-correlated and whose correlograms will subsequently be migrated by

xcloc.setSignals(signalMatrix)

where signalMatrix is a [nsignals x npts] matrix of signals. Note, if there is a data drop-out or loss of telemetry it is simpler to set the dead trace to a value of 0 rather than re-initialize xcloc.

Process the data window

Now that the signals for this data window are set

xcloc.compute()

will

1. Compute the phase-correlograms.
2. Compute the envelopes of the phase-correlograms.
3. Migrate the envelope of the phase-correlograms.

Get the result

The diffraction stack migration image of the correlograms can be obtained by

image = xcloc.getImage()

However, in some instances this image may be extraneous and the maximum (most likely grid index corresponding to an earthquake) can be extracted with

maxIndex, maxValue = xcloc.getImageMax()

Freeing the module

After the processing is complete for all time windows one should free the memory and reset xcloc by specifying

xcloc.finalize()