# SWIGLAL: Python and Octave interfaces to LALSuite

SWIGLAL is a collection of scripts used to build [Python][python] and
[Octave][octave] interfaces to the [LALSuite][lalsuite] gravitational-wave data
analysis libraries, written in C.

This repository was extracted from the LALSuite development history, in order to
illustrate the history of the development of SWIGLAL. The tagged versions of
SWIGLAL correspond to versions of the LAL library, a key component of LALSuite
that provides core routines, including SWIGLAL.

## Building

SWIGLAL is fully integrated to LALSuite, and as such cannot be built directly
from this repository. Instructions for obtaining the Python and Octave interfaces,
either through pre-built packages or by building from source, are linked to from
the main [LALSuite][lalsuite] development repository.

## Operation

SWIGLAL is primarily based on [SWIG][swig], a tool which generates wrapper code
for the public constants, functions, and classes exported by the LALSuite C
header files.  The generated wrapper code (C for Python, C++ for Octave) is then
compiled to create a dynamically loadable modules, which can then be accessed by
e.g. using `import` for Python. This enables LALSuite constants, functions, and
classes to be used directly from Python and Octave.

The SWIGLAL scripts build upon the basic wrappers generated by SWIG in the
following respects:

  * SWIGLAL passes the LALSuite C header files through SWIG twice. The first
    pass uses the SWIG `-xml` mode to generate an XML syntax tree describing the
    public constants, functions, and classes exported by LALSuite; in essence,
    SWIG is used as a C header parser. Information from the XML syntax tree is
    used by the script `generate_swig_iface.py` to automate further annotation
    of the LALSuite C header files, which are then passed through SWIG a second
    time, using either its `-python` or `-octave` mode to generate Python or
    Octave wrappers respectively.

  * SWIGLAL provides header files, written in C with SWIG preprocessor
    directives, which contain code to further integrate the wrappers with
    LALSuite. The header `SWIGCommon.i` provide common definitions, while the
    headers `SWIGOctave.i` and `SWIGPython.i` provide definitions specific to
    Python and Octave. The headers `SWIGLALAlpha.i` and `SWIGLALOmega.i` provide
    definitions specific to the LAL library.

SWIGLAL includes extensive tests of the Python and Octave wrappers, provided by
the files `SWIGLALTest.h`, `SWIGTest.c`, `SWIGTestLALPython`, and
`SWIGTestLALOctave.m`.

## Documentation

SWIGLAL is documented as part of LALSuite. The [LALSuite Doxygen
documentation][swiglaldoc] provides detailed documentation of the definitions
provided by `SWIGCommon.i`, `SWIGLALAlpha.i`, and `SWIGLALOmega.i`.

## Support

SWIGLAL is supported as part of LALSuite. The [LALSuite contributing
guide][lalsuitectrb] provides information on reporting issues.

[lalsuite]:     https://doi.org/10.7935/GT1W-FZ16
[lalsuitectrb]: https://git.ligo.org/lscsoft/lalsuite/blob/master/CONTRIBUTING.md
[octave]:       https://www.gnu.org/software/octave/
[python]:       https://www.python.org/
[swig]:         http://www.swig.org/
[swiglaldoc]:   https://lscsoft.docs.ligo.org/lalsuite/lal/group__lal__swig.html

## License

The files in this repository are dual-licensed under the GPL 2.0 license (or any
later version), and the MIT (Expat) license. You can choose between one of them
if you use the files in this repository.

`SPDX-License-Identifier: GPL-2.0-or-later OR MIT`