feat: add transplanted 1D quadrature maps, docs, tests

doc/quadrature.rst

@@ -25,6 +25,120 @@ Clenshaw-Curtis and Fejér quadrature in one dimension
     :members:
     :show-inheritance:
 
+.. _quadrature-transplanted-1d:
+
+Transplanted quadrature in one dimension
+----------------------------------------
+
+The transplanted maps implemented here include the Hale-Trefethen
+conformal-map family and the Kosloff-Tal-Ezer map.
+
+Given a base rule :math:`(s_i, w_i^{(s)})` on :math:`[-1,1]`, transplanted quadrature
+uses a map :math:`x=g(s)` to build
+
+.. math::
+
+    x_i = g(s_i), \qquad \tilde w_i = w_i^{(s)} g'(s_i),
+
+so that
+
+.. math::
+
+    \int_{-1}^1 f(x)\,dx = \int_{-1}^1 f(g(s))\,g'(s)\,ds
+    \approx \sum_i \tilde w_i f(x_i).
+
+Map functions
+~~~~~~~~~~~~~
+
+.. currentmodule:: modepy.quadrature.transplanted
+
+Identity map
+^^^^^^^^^^^^
+
+Use ``map_name="identity"`` for the unmodified base rule.
+
+.. autofunction:: map_identity
+
+Sausage polynomial maps
+^^^^^^^^^^^^^^^^^^^^^^^
+
+Use ``map_name="sausage"`` with odd ``sausage_degree`` (for example
+``sausage_degree=5``, ``9``, ``17``) for odd-degree normalized polynomial
+truncations of :math:`\arcsin`.
+
+.. autofunction:: map_sausage
+
+Kosloff-Tal-Ezer map
+^^^^^^^^^^^^^^^^^^^^
+
+Use ``map_name="kte"`` (or ``"kosloff_tal_ezer"``).
+
+* ``kte_rho`` (``>1``) sets the default parameterization
+  :math:`\alpha = 2/(\rho + \rho^{-1})`.
+* ``kte_alpha`` explicitly sets :math:`\alpha` (must satisfy ``0<alpha<1``)
+  and overrides ``kte_rho``.
+
+.. autofunction:: map_kosloff_tal_ezer
+
+Strip conformal map
+^^^^^^^^^^^^^^^^^^^
+
+Use ``map_name="strip"`` with ``strip_rho > 1``.
+
+.. note::
+
+    The strip map requires interior nodes (``abs(s)<1``), so endpoint rules
+    (for example Gauss-Lobatto or Clenshaw-Curtis) are not valid with
+    ``map_name="strip"``.
+
+.. autofunction:: map_strip
+
+Map dispatcher
+^^^^^^^^^^^^^^
+
+.. autofunction:: map_trefethen_transplant
+
+Quadrature wrappers
+~~~~~~~~~~~~~~~~~~~
+
+.. currentmodule:: modepy
+
+.. autofunction:: transplanted_1d_quadrature
+
+.. autofunction:: transplanted_legendre_gauss_quadrature
+
+Example
+~~~~~~~
+
+.. code-block:: python
+
+    import modepy as mp
+
+    q_kte = mp.transplanted_legendre_gauss_quadrature(
+        20,
+        map_name="kte",
+        kte_rho=1.4,
+        force_dim_axis=True,
+    )
+
+    q_sausage = mp.transplanted_legendre_gauss_quadrature(
+        20,
+        map_name="sausage",
+        sausage_degree=9,
+        force_dim_axis=True,
+    )
+
+References
+~~~~~~~~~~
+
+* N. Hale and L. N. Trefethen, *New Quadrature Formulas from Conformal
+  Maps*, *SIAM Journal on Numerical Analysis* 46(2), 930-948 (2008),
+  `doi:10.1137/07068607X <https://doi.org/10.1137/07068607X>`__.
+* D. Kosloff and H. Tal-Ezer, *A Modified Chebyshev Pseudospectral Method
+  with an :math:`O(N^{-1})` Time Step Restriction*,
+  *Journal of Computational Physics* 104(2), 457-469 (1993),
+  `doi:10.1006/jcph.1993.1044 <https://doi.org/10.1006/jcph.1993.1044>`__.
+
 Quadratures on the simplex
 --------------------------
 

modepy/__init__.py

@@ -88,6 +88,10 @@
     LegendreGaussQuadrature,
 )
 from modepy.quadrature.jaskowiec_sukumar import JaskowiecSukumarQuadrature
+from modepy.quadrature.transplanted import (
+    transplanted_1d_quadrature,
+    transplanted_legendre_gauss_quadrature,
+)
 from modepy.quadrature.vioreanu_rokhlin import VioreanuRokhlinSimplexQuadrature
 from modepy.quadrature.witherden_vincent import WitherdenVincentQuadrature
 from modepy.quadrature.xiao_gimbutas import XiaoGimbutasSimplexQuadrature
@@ -177,6 +181,8 @@
     "submesh_for_shape",
     "symbolicize_function",
     "tensor_product_nodes",
+    "transplanted_1d_quadrature",
+    "transplanted_legendre_gauss_quadrature",
     "unit_vertices_for_shape",
     "vandermonde",
     "warp_and_blend_nodes",