Revision 8f6d75bb3c08fc5e4a089c52076e9533eca10fe6 authored by Karl Wette on 04 October 2020, 05:16:11 UTC, committed by Karl Wette on 04 October 2020, 05:16:11 UTC
1 parent f5b90ce
README.md
# 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`
Computing file changes ...