EOB Tidal Waveforms (C++ Implementation)
========================================

This module provides an interface to the TEOBResumS (Tidal Effective-One-Body Resummed) model, a high-performance C++ implementation of the Bernuzzi EOB formalism for generating tidal gravitational-wave waveforms. Compared to the MATLAB-based ``EOBTidalExternal`` module, this implementation offers faster generation times without requiring MATLAB.

Requirements
------------

1. **TEOBResumS Executable**: The compiled ``TEOBResumS.x`` binary must be present in the EOB base directory.
2. **Environment Variables**:
    - ``EOB_C_BASE``: Path to the directory containing the TEOBResumS executable and source code.
    - ``EOB_C_ARCHIVE``: Path to the directory where generated waveforms are archived.
    - ``EOB_C_ARCHIVE_NMAX``: Maximum number of parallel archive directories.

Comparison with EOBTidalExternal
--------------------------------

This module serves the same purpose as ``EOBTidalExternal`` but uses a different backend:

+---------------------------+---------------------------+
| Feature                   | EOBTidalExternalC (C++)   |
+===========================+===========================+
| Speed                     | Faster                    |
| Dependencies              | C++ compiler              |
| Spin support              | Aligned spins (chi1z,    |
|                           | chi2z)                    |
| MATLAB required           | No                        |
| Parameter file format     | ``.par``                  |
| Output format             | ``hlm_insp.dat``          |
+---------------------------+---------------------------+

Core Functionality: WaveformModeCatalog
---------------------------------------

The ``WaveformModeCatalog`` class provides the same interface as its MATLAB counterpart, loading and managing tidal harmonic modes generated by the TEOBResumS code.

Initialization
^^^^^^^^^^^^^

During initialization, the class:
1. Generates a parameter file (``my.par``) with waveform settings.
2. Invokes ``TEOBResumS.x`` with the parameter file.
3. Reads the resulting ``hlm_insp.dat`` file containing all harmonic modes.
4. Applies interpolation using ``scipy.interpolate.UnivariateSpline``.
5. Cleans up temporary files after loading.

Parameter File Generation
^^^^^^^^^^^^^^^^^^^^^^^^^

The module automatically creates a ``.par`` file with the following key parameters:

- **Mtot**: Total mass in solar masses
- **q**: Mass ratio $q = m_1 / m_2$
- **chi1, chi2**: Spin parameters (aligned component)
- **LambdaAl2, LambdaBl2**: Tidal lambda parameters for each body
- **f_min**: Minimum frequency
- **tidal**: Set to 1 to enable tidal calculations
- **Yagi_fit**: Enables the Yagi et al. tidal fitting formulas

Key Methods
^^^^^^^^^^^

The interface mirrors ``EOBTidalExternal``:

- ``hlmoft(...)``: Generates time-domain modes $h_{lm}(t)$ with physical units.
- ``hlmoff(...)``: Fourier transforms the modes to frequency domain.
- ``real_hoft(...)``: Projects modes onto detector strain.
- ``conj_hlmoff(...)``: Computes the Fourier transform of the complex conjugate (used in certain likelihood evaluations).

Tidal Mode Support
------------------

The C++ implementation supports the same harmonic modes as the MATLAB version:

- $(2, \pm 2), (2, \pm 1)$
- $(3, \pm 3), (3, \pm 2), (3, \pm 1)$

Workflow Summary
----------------

1. **Parameter Input**: Pass a parameter object with $m_1, m_2, \chi_1, \chi_2, \lambda_1, \lambda_2$.
2. **C++ Execution**: The module writes a ``.par`` file and calls ``TEOBResumS.x``.
3. **Data Extraction**: Reads ``hlm_insp.dat`` containing amplitude and phase for all modes.
4. **Interpolation**: Creates spline interpolators for amplitude and phase.
5. **Projection**: Combines modes into detector-specific strain for likelihood evaluation.