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