ginac/integration_kernel.h

   1 /** @file integration_kernel.h
   2  *
   3  *  Interface to GiNaC's integration kernels for iterated integrals. */
   4
   5 /*
   6  *  GiNaC Copyright (C) 1999-2021 Johannes Gutenberg University Mainz, Germany
   7  *
   8  *  This program is free software; you can redistribute it and/or modify
   9  *  it under the terms of the GNU General Public License as published by
  10  *  the Free Software Foundation; either version 2 of the License, or
  11  *  (at your option) any later version.
  12  *
  13  *  This program is distributed in the hope that it will be useful,
  14  *  but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  *  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  16  *  GNU General Public License for more details.
  17  *
  18  *  You should have received a copy of the GNU General Public License
  19  *  along with this program; if not, write to the Free Software
  20  *  Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
  21  */
  22
  23 #ifndef GINAC_INTEGRATION_KERNEL_H
  24 #define GINAC_INTEGRATION_KERNEL_H
  25
  26 #include "basic.h"
  27 #include "archive.h"
  28 #include "numeric.h"
  29 #include "lst.h"
  30
  31 #include <cln/complex.h>
  32 #include <vector>
  33
  34 namespace GiNaC {
  35
  36 ex ifactor(const numeric & n);
  37 bool is_discriminant_of_quadratic_number_field(const numeric & n);
  38 numeric kronecker_symbol(const numeric & a, const numeric & n);
  39 numeric primitive_dirichlet_character(const numeric & n, const numeric & a);
  40 numeric dirichlet_character(const numeric & n, const numeric & a, const numeric & N);
  41 numeric generalised_Bernoulli_number(const numeric & k, const numeric & b);
  42 ex Bernoulli_polynomial(const numeric & k, const ex & x);
  43
  44 /**
  45  *
  46  * The base class for integration kernels for iterated integrals.
  47  *
  48  * This class represents the differential one-form
  49  * \f[
  50  *    \omega = d\lambda
  51  * \f]
  52  * The integration variable is a dummy variable and does not need to be specified.
  53  *
  54  */
  55 class integration_kernel : public basic
  56 {
  57         GINAC_DECLARE_REGISTERED_CLASS(integration_kernel, basic)
  58
  59         // ctors
  60 public:
  61
  62         // functions overriding virtual functions from base classes
  63 public:
  64         ex series(const relational & r, int order, unsigned options = 0) const override;
  65
  66 protected:
  67
  68         // new virtual functions which can be overridden by derived classes
  69 public:
  70         virtual bool has_trailing_zero(void) const;
  71         virtual bool is_numeric(void) const;
  72         virtual ex Laurent_series(const ex & x, int order) const;
  73         virtual ex  get_numerical_value(const ex & lambda, int N_trunc = 0) const;
  74
  75 protected:
  76         virtual bool uses_Laurent_series() const;
  77         virtual cln::cl_N series_coeff_impl(int i) const;
  78
  79         // non-virtual functions
  80 public:
  81         size_t get_cache_size(void) const;
  82         void set_cache_step(int cache_steps) const;
  83         ex get_series_coeff(int i) const;
  84         cln::cl_N series_coeff(int i) const;
  85
  86 protected:
  87         ex  get_numerical_value_impl(const ex & lambda, const ex & pre, int shift, int N_trunc) const;
  88         void do_print(const print_context & c, unsigned level) const;
  89
  90         // friends :
  91
  92         // member variables :
  93
  94 protected:
  95         // cache is increased by steps of cache_step_size
  96         mutable int cache_step_size;
  97         // cache already computed series coefficients
  98         mutable std::vector<cln::cl_N> series_vec;
  99
 100 };
 101
 102 GINAC_DECLARE_UNARCHIVER(integration_kernel);
 103
 104 /**
 105  *
 106  * The basic integration kernel with a logarithmic singularity at the origin.
 107  *
 108  * This class represents the differential one-form
 109  * \f[
 110  *    L_0 = \frac{d\lambda}{\lambda}
 111  * \f]
 112  *
 113  */
 114 class basic_log_kernel : public integration_kernel
 115 {
 116         GINAC_DECLARE_REGISTERED_CLASS(basic_log_kernel, integration_kernel)
 117
 118         // ctors
 119 public:
 120
 121         // functions overriding virtual functions from base classes
 122 public:
 123
 124 protected:
 125         cln::cl_N series_coeff_impl(int i) const override;
 126
 127         // new virtual functions which can be overridden by derived classes
 128 public:
 129
 130 protected:
 131
 132         // non-virtual functions
 133 public:
 134
 135 protected:
 136         void do_print(const print_context & c, unsigned level) const;
 137
 138         // friends :
 139
 140         // member variables :
 141
 142 protected:
 143
 144 };
 145
 146 GINAC_DECLARE_UNARCHIVER(basic_log_kernel);
 147
 148 /**
 149  *
 150  * The integration kernel for multiple polylogarithms.
 151  *
 152  * This class represents the differential one-form
 153  * \f[
 154  *    \omega^{\mathrm{mpl}}(z) = \frac{d\lambda}{\lambda-z}
 155  * \f]
 156  *
 157  * For the case \f$ z=0 \f$ the class basic_log_kernel should be used.
 158  *
 159  */
 160 class multiple_polylog_kernel : public integration_kernel
 161 {
 162         GINAC_DECLARE_REGISTERED_CLASS(multiple_polylog_kernel, integration_kernel)
 163
 164         // ctors
 165 public:
 166         multiple_polylog_kernel(const ex & z);
 167
 168         // functions overriding virtual functions from base classes
 169 public:
 170         size_t nops() const override;
 171         ex op(size_t i) const override;
 172         ex & let_op(size_t i) override;
 173
 174         bool is_numeric(void) const override;
 175
 176 protected:
 177         cln::cl_N series_coeff_impl(int i) const override;
 178
 179         // new virtual functions which can be overridden by derived classes
 180 public:
 181
 182 protected:
 183
 184         // non-virtual functions
 185 public:
 186
 187 protected:
 188         void do_print(const print_context & c, unsigned level) const;
 189
 190         // friends :
 191
 192         // member variables :
 193
 194 protected:
 195         ex z;
 196
 197 };
 198
 199 GINAC_DECLARE_UNARCHIVER(multiple_polylog_kernel);
 200
 201 /**
 202  *
 203  * The ELi-kernel.
 204  *
 205  * This class represents the differential one-form
 206  * \f[
 207  *    \omega^{\mathrm{ELi}}_{n;m}(x;y) = \mathrm{ELi}_{n;m}(x;y;\bar{q}) \frac{d\bar{q}}{\bar{q}}
 208  * \f]
 209  *
 210  */
 211 class ELi_kernel : public integration_kernel
 212 {
 213         GINAC_DECLARE_REGISTERED_CLASS(ELi_kernel, integration_kernel)
 214
 215         // ctors
 216 public:
 217         ELi_kernel(const ex & n, const ex & m, const ex & x, const ex & y);
 218
 219         // functions overriding virtual functions from base classes
 220 public:
 221         size_t nops() const override;
 222         ex op(size_t i) const override;
 223         ex & let_op(size_t i) override;
 224
 225         bool is_numeric(void) const override;
 226         ex get_numerical_value(const ex & qbar, int N_trunc = 0) const override;
 227
 228 protected:
 229         cln::cl_N series_coeff_impl(int i) const override;
 230
 231         // new virtual functions which can be overridden by derived classes
 232 public:
 233
 234 protected:
 235
 236         // non-virtual functions
 237 public:
 238
 239 protected:
 240         void do_print(const print_context & c, unsigned level) const;
 241
 242         // friends :
 243
 244         // member variables :
 245
 246 protected:
 247         ex n;
 248         ex m;
 249         ex x;
 250         ex y;
 251
 252 };
 253
 254 GINAC_DECLARE_UNARCHIVER(ELi_kernel);
 255
 256 /**
 257  *
 258  * The Ebar-kernel
 259  *
 260  * This class represents the differential one-form
 261  * \f[
 262  *  \omega^{\overline{\mathrm{E}}}_{n;m}(x;y) = \overline{\mathrm{E}}_{n;m}(x;y;\bar{q}) \frac{d\bar{q}}{\bar{q}}
 263  * \f]
 264  *
 265  */
 266 class Ebar_kernel : public integration_kernel
 267 {
 268         GINAC_DECLARE_REGISTERED_CLASS(Ebar_kernel, integration_kernel)
 269
 270         // ctors
 271 public:
 272         Ebar_kernel(const ex & n, const ex & m, const ex & x, const ex & y);
 273
 274         // functions overriding virtual functions from base classes
 275 public:
 276         size_t nops() const override;
 277         ex op(size_t i) const override;
 278         ex & let_op(size_t i) override;
 279
 280         bool is_numeric(void) const override;
 281         ex get_numerical_value(const ex & qbar, int N_trunc = 0) const override;
 282
 283 protected:
 284         cln::cl_N series_coeff_impl(int i) const override;
 285
 286         // new virtual functions which can be overridden by derived classes
 287 public:
 288
 289 protected:
 290
 291         // non-virtual functions
 292 public:
 293
 294 protected:
 295         void do_print(const print_context & c, unsigned level) const;
 296
 297         // friends :
 298
 299         // member variables :
 300
 301 protected:
 302         ex n;
 303         ex m;
 304         ex x;
 305         ex y;
 306
 307 };
 308
 309 GINAC_DECLARE_UNARCHIVER(Ebar_kernel);
 310
 311 /**
 312  *
 313  * The kernel corresponding to integrating the Kronecker coefficient function \f$ g^{(n)}(z_j,K \tau) \f$
 314  * in \f$ \tau \f$ (or equivalently in \f$ \bar{q} \f$).
 315  *
 316  * This class represents the differential one-form
 317  * \f[
 318  *  \omega^{\mathrm{Kronecker},\tau}_{n,K}(z_j) = \frac{C_n K (n-1)}{(2\pi i)^n} g^{(n)}(z_j,K \tau) \frac{d\bar{q}}{\bar{q}}
 319  * \f]
 320  *
 321  */
 322 class Kronecker_dtau_kernel : public integration_kernel
 323 {
 324         GINAC_DECLARE_REGISTERED_CLASS(Kronecker_dtau_kernel, integration_kernel)
 325
 326         // ctors
 327 public:
 328         Kronecker_dtau_kernel(const ex & n, const ex & z, const ex & K = numeric(1), const ex & C_norm = numeric(1));
 329
 330         // functions overriding virtual functions from base classes
 331 public:
 332         size_t nops() const override;
 333         ex op(size_t i) const override;
 334         ex & let_op(size_t i) override;
 335
 336         bool is_numeric(void) const override;
 337         ex get_numerical_value(const ex & qbar, int N_trunc = 0) const override;
 338
 339 protected:
 340         cln::cl_N series_coeff_impl(int i) const override;
 341
 342         // new virtual functions which can be overridden by derived classes
 343 public:
 344
 345 protected:
 346
 347         // non-virtual functions
 348 public:
 349
 350 protected:
 351         void do_print(const print_context & c, unsigned level) const;
 352
 353         // friends :
 354
 355         // member variables :
 356
 357 protected:
 358         ex n;
 359         ex z;
 360         ex K;
 361         ex C_norm;
 362 };
 363
 364 GINAC_DECLARE_UNARCHIVER(Kronecker_dtau_kernel);
 365
 366
 367 /**
 368  *
 369  * The kernel corresponding to integrating the Kronecker coefficient function \f$ g^{(n-1)}(z-z_j, K \tau) \f$
 370  * in \f$ z \f$.
 371  *
 372  * This class represents the differential one-form
 373  * \f[
 374  *   \omega^{\mathrm{Kronecker},z}_{n,K}(z_j,\tau) = C_n (2\pi i)^{2-n} g^{(n-1)}(z-z_j, K \tau) dz
 375  * \f]
 376  *
 377  */
 378 class Kronecker_dz_kernel : public integration_kernel
 379 {
 380         GINAC_DECLARE_REGISTERED_CLASS(Kronecker_dz_kernel, integration_kernel)
 381
 382         // ctors
 383 public:
 384         Kronecker_dz_kernel(const ex & n, const ex & z_j, const ex & tau, const ex & K = numeric(1), const ex & C_norm = numeric(1));
 385
 386         // functions overriding virtual functions from base classes
 387 public:
 388         size_t nops() const override;
 389         ex op(size_t i) const override;
 390         ex & let_op(size_t i) override;
 391
 392         bool is_numeric(void) const override;
 393         ex get_numerical_value(const ex & z, int N_trunc = 0) const override;
 394
 395 protected:
 396         cln::cl_N series_coeff_impl(int i) const override;
 397
 398         // new virtual functions which can be overridden by derived classes
 399 public:
 400
 401 protected:
 402
 403         // non-virtual functions
 404 public:
 405
 406 protected:
 407         void do_print(const print_context & c, unsigned level) const;
 408
 409         // friends :
 410
 411         // member variables :
 412
 413 protected:
 414         ex n;
 415         ex z_j;
 416         ex tau;
 417         ex K;
 418         ex C_norm;
 419
 420 };
 421
 422 GINAC_DECLARE_UNARCHIVER(Kronecker_dz_kernel);
 423
 424
 425 /**
 426  *
 427  * The kernel corresponding to the Eisenstein series \f$ E_{k,N,a,b,K}(\tau) \f$.
 428  *
 429  * This class represents the differential one-form
 430  * \f[
 431  *   \omega^{\mathrm{Eisenstein}}_{k,N,a,b,K} = C_k E_{k,N,a,b,K}(\tau) \frac{d\bar{q}_N}{\bar{q}_N}
 432  * \f]
 433  *
 434  * The integers a and b are either one or the discriminant of a quadratic number field.
 435  * This class represents Eisenstein series, which can be defined by primitive Dirichlet characters from the Kronecker symbol.
 436  * This implies that the characters take the values -1,0,1, i.e. no higher roots of unity occur.
 437  * The \f[ \bar{q} \f]-expansion has then rational coefficients.
 438  *
 439  * Ref.: W. Stein, Modular Forms: A Computational Approach, Chapter 5
 440  *
 441  */
 442 class Eisenstein_kernel : public integration_kernel
 443 {
 444         GINAC_DECLARE_REGISTERED_CLASS(Eisenstein_kernel, integration_kernel)
 445
 446         // ctors
 447 public:
 448         Eisenstein_kernel(const ex & k, const ex & N, const ex & a, const ex & b, const ex & K, const ex & C_norm = numeric(1));
 449
 450         // functions overriding virtual functions from base classes
 451 public:
 452         ex series(const relational & r, int order, unsigned options = 0) const override;
 453
 454         size_t nops() const override;
 455         ex op(size_t i) const override;
 456         ex & let_op(size_t i) override;
 457
 458         bool is_numeric(void) const override;
 459         ex Laurent_series(const ex & x, int order) const override;
 460         ex get_numerical_value(const ex & qbar, int N_trunc = 0) const override;
 461
 462 protected:
 463         bool uses_Laurent_series() const override;
 464
 465         // new virtual functions which can be overridden by derived classes
 466 public:
 467
 468 protected:
 469
 470         // non-virtual functions
 471 public:
 472         ex q_expansion_modular_form(const ex & q, int order) const;
 473
 474 protected:
 475         void do_print(const print_context & c, unsigned level) const;
 476
 477         // friends :
 478
 479         // member variables :
 480
 481 protected:
 482         ex k;
 483         ex N;
 484         ex a;
 485         ex b;
 486         ex K;
 487         ex C_norm;
 488
 489 };
 490
 491 GINAC_DECLARE_UNARCHIVER(Eisenstein_kernel);
 492
 493
 494 /**
 495  *
 496  * The kernel corresponding to the Eisenstein series \f$ h_{k,N,r,s}(\tau) \f$.
 497  *
 498  * This class represents the differential one-form
 499  * \f[
 500  *   \omega^{\mathrm{Eisenstein,h}}_{k,N,r,s} = C_k h_{k,N,r,s}(\tau) \frac{d\bar{q}_N}{\bar{q}_N}
 501  * \f]
 502  *
 503  */
 504 class Eisenstein_h_kernel : public integration_kernel
 505 {
 506         GINAC_DECLARE_REGISTERED_CLASS(Eisenstein_h_kernel, integration_kernel)
 507
 508         // ctors
 509 public:
 510         Eisenstein_h_kernel(const ex & k, const ex & N, const ex & r, const ex & s, const ex & C_norm = numeric(1));
 511
 512         // functions overriding virtual functions from base classes
 513 public:
 514         ex series(const relational & r, int order, unsigned options = 0) const override;
 515
 516         size_t nops() const override;
 517         ex op(size_t i) const override;
 518         ex & let_op(size_t i) override;
 519
 520         bool is_numeric(void) const override;
 521         ex Laurent_series(const ex & x, int order) const override;
 522         ex get_numerical_value(const ex & qbar, int N_trunc = 0) const override;
 523
 524 protected:
 525         bool uses_Laurent_series() const override;
 526
 527         // new virtual functions which can be overridden by derived classes
 528 public:
 529
 530 protected:
 531
 532         // non-virtual functions
 533 public:
 534         ex coefficient_a0(const numeric & k, const numeric & r, const numeric & s, const numeric & N) const;
 535         ex coefficient_an(const numeric & n, const numeric & k, const numeric & r, const numeric & s, const numeric & N) const;
 536         ex q_expansion_modular_form(const ex & q, int order) const;
 537
 538 protected:
 539         void do_print(const print_context & c, unsigned level) const;
 540
 541         // friends :
 542
 543         // member variables :
 544
 545 protected:
 546         ex k;
 547         ex N;
 548         ex r;
 549         ex s;
 550         ex C_norm;
 551
 552 };
 553
 554 GINAC_DECLARE_UNARCHIVER(Eisenstein_h_kernel);
 555
 556
 557 /**
 558  *
 559  * A kernel corresponding to a polynomial in Eisenstein series.
 560  *
 561  * This class represents the differential one-form
 562  * \f[
 563  *   \omega^{\mathrm{modular}}(P_k(\eta^{(1)}_{k_1}, \dots, \eta^{(r)}_{k_r})) = C_k P_k(\eta^{(1)}_{k_1}, \dots, \eta^{(r)}_{k_r}) \frac{d\bar{q}_N}{\bar{q}_N}.
 564  * \f]
 565  *
 566  */
 567 class modular_form_kernel : public integration_kernel
 568 {
 569         GINAC_DECLARE_REGISTERED_CLASS(modular_form_kernel, integration_kernel)
 570
 571         // ctors
 572 public:
 573         modular_form_kernel(const ex & k, const ex & P, const ex & C_norm = numeric(1));
 574
 575         // functions overriding virtual functions from base classes
 576 public:
 577         ex series(const relational & r, int order, unsigned options = 0) const override;
 578
 579         size_t nops() const override;
 580         ex op(size_t i) const override;
 581         ex & let_op(size_t i) override;
 582
 583         bool is_numeric(void) const override;
 584         ex Laurent_series(const ex & qbar, int order) const override;
 585         ex get_numerical_value(const ex & qbar, int N_trunc = 0) const override;
 586
 587 protected:
 588         bool uses_Laurent_series() const override;
 589
 590         // new virtual functions which can be overridden by derived classes
 591 public:
 592
 593 protected:
 594
 595         // non-virtual functions
 596 public:
 597         ex q_expansion_modular_form(const ex & q, int order) const;
 598
 599 protected:
 600         void do_print(const print_context & c, unsigned level) const;
 601
 602         // friends :
 603
 604         // member variables :
 605
 606 protected:
 607         ex k;
 608         ex P;
 609         ex C_norm;
 610
 611 };
 612
 613 GINAC_DECLARE_UNARCHIVER(modular_form_kernel);
 614
 615
 616 /**
 617  *
 618  * A user-defined integration kernel.
 619  * The input is an expression \f$ f \f$, depending on a variable \f$ x \f$.
 620  * It is assumed that \f$ f \f$ has a Laurent expansion around \f$ x=0 \f$ and
 621  * maximally a simple pole at \f$ x=0 \f$.
 622  *
 623  */
 624 class user_defined_kernel : public integration_kernel
 625 {
 626         GINAC_DECLARE_REGISTERED_CLASS(user_defined_kernel, integration_kernel)
 627
 628         // ctors
 629 public:
 630         user_defined_kernel(const ex & f, const ex & x);
 631
 632         // functions overriding virtual functions from base classes
 633 public:
 634         size_t nops() const override;
 635         ex op(size_t i) const override;
 636         ex & let_op(size_t i) override;
 637
 638         bool is_numeric(void) const override;
 639         ex Laurent_series(const ex & x, int order) const override;
 640
 641 protected:
 642         bool uses_Laurent_series() const override;
 643
 644         // new virtual functions which can be overridden by derived classes
 645 public:
 646
 647 protected:
 648
 649         // non-virtual functions
 650 public:
 651
 652 protected:
 653         void do_print(const print_context & c, unsigned level) const;
 654
 655         // friends :
 656
 657         // member variables :
 658
 659 protected:
 660         ex f;
 661         ex x;
 662
 663 };
 664
 665 GINAC_DECLARE_UNARCHIVER(user_defined_kernel);
 666
 667 } // namespace GiNaC
 668
 669 #endif // ndef GINAC_INTEGRATION_KERNEL_H