Overview
========

This is a small C library for constructing initial data data for
Teukolsky/time-asymmetric waves (see https://doi.org/10.1103/PhysRevLett.127.011104) to
be used in 3+1 general relativity simulations.

See the author's PhD thesis for more information.

If you use this code in your research that leads to a publication, please cite
our paper:
  Universality of Curvature Invariants in Critical Vacuum Gravitational Collapse
  https://doi.org/10.1103/PhysRevLett.127.011104

If you modify the code, we ask that you share your changes with the author (e.g.
via email).

Building and installation
=========================

The library requires LAPACKE (the C interface to LAPACK) and libthreadpool [1]
(thread pool utility library) to be present where the compiler and linker can
find them. A C99-compliant compiler and a POSIX environment are expected.

Simply running 'make' will then build the shared library libteukolskydata.so.
The shared library and the teukolsky_data.h header must be copied to where the
linker and C compiler, respectively, will find them (typically /usr/local/lib
and /usr/local/include).

[1] git://git.khirnov.net/threadpool_omp.git

Usage
=====

The public C API is described in the teukolsky_data.h header.

A simplistic Python wrapper using ctypes is also provided. It contains a single
public class that takes the C context options as keyword arguments and solves
the equation on initialization. The instance methods then allow to evaluate the
solution where needed.

The following python scripts are bundled:
- teukolsky.py
  Solves the constraints and prints the residuald and spectral coefficients
- find_bound.py
  Locates A_max using bisection

Licence
=======

This library is free software, available under GNU GPLv3 (see the LICENCE file
for full licence text).