Added descriptions of fortran test programs to docs, and made other m…

…inor updates to docs and test program comments

README.md

@@ -4,9 +4,9 @@ Authors: [Jason Kaye](https://github.com/jasonkaye) and [Hugo UR Strand](https:/
 
 `libdlr` is a library providing Fortran subroutines to build and work with the
 discrete Lehmann representation for single particle imaginary time Green's functions,
-as well as the stand-alone Python module `pydlr` implementing the same functionality.
+as well as a stand-alone Python module `pydlr` implementing the same functionality.
 
-For more information see the [documentation](https://libdlr.readthedocs.io).
+For more information see the [documentation](https://libdlr.readthedocs.io), and the references below.
 
 There is a Julia package implementing the discrete Lehmann
 representation, [Lehmann.jl](https://github.com/numericaleft/Lehmann.jl).
@@ -17,8 +17,8 @@ If this library helps you to create software or publications, please let
 us know, and cite
 
 - our repository: https://github.com/jasonkaye/libdlr
-- ["libdlr: Efficient imaginary time calculations using the discrete Lehmann representation", Jason Kaye, Kun Chen, and Hugo U.R. Strand, arXiv:2110.06765.](https://arxiv.org/abs/2110.06765)
-- ["Discrete Lehmann representation of imaginary time Green's functions", Jason Kaye, Kun Chen, and Olivier Parcollet, Phys. Rev. B 105, 235115, 2022.](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.105.235115) \[[arXiv:2107.13094](https://arxiv.org/abs/2107.13094)\]
+- [libdlr: Efficient imaginary time calculations using the discrete Lehmann representation, Jason Kaye, Kun Chen, and Hugo U.R. Strand, arXiv:2110.06765.](https://arxiv.org/abs/2110.06765)
+- [Discrete Lehmann representation of imaginary time Green's functions, Jason Kaye, Kun Chen, and Olivier Parcollet, Phys. Rev. B 105, 235115, 2022.](https://journals.aps.org/prb/abstract/10.1103/PhysRevB.105.235115) \[[arXiv:2107.13094](https://arxiv.org/abs/2107.13094)\]
 
 ## Contact
 

doc/background.rst

@@ -29,9 +29,7 @@ Discrete Lehmann Representation
 
 The discrete Lehmann representation (DLR) provides and efficient method of representing imaginary time functions numerically. The theory and methodology behind is based on the analysis of an integral kernel (`the analytic continuation kernel <https://en.wikipedia.org/wiki/Numerical_analytic_continuation>`_) combined with a clever linear algebra factorization (`the interpolative decomposition <https://en.wikipedia.org/wiki/Interpolative_decomposition>`_). 
 
-For an in depth background on the discrete Lehmann representation (DLR), we suggest reading the original reference on the DLR:
-
-"Discrete Lehmann representation of imaginary time Green's functions", Jason Kaye, Kun Chen, and Olivier Parcollet, `arXiv:2107.13094 <https://arxiv.org/abs/2107.13094>`_
+For an in depth background on the discrete Lehmann representation (DLR), we suggest looking at the two papers cited just below.
 
 
 .. _citations:
@@ -43,8 +41,8 @@ If this library helps you to create software or publications, please let
 us know, and cite
 
 - our repository: `<https://github.com/jasonkaye/libdlr>`_
-- "libdlr: Efficient imaginary time calculations using the discrete Lehmann representation", Jason Kaye and Hugo U.R. Strand, `arXiv:2110.06765 <https://arxiv.org/abs/2110.06765>`_
-- "Discrete Lehmann representation of imaginary time Green's functions", Jason Kaye, Kun Chen, and Olivier Parcollet, `arXiv:2107.13094 <https://arxiv.org/abs/2107.13094>`_
+- `libdlr: Efficient imaginary time calculations using the discrete Lehmann representation, Jason Kaye, Kun Chen, and Hugo U.R. Strand, arXiv:2110.06765. <https://arxiv.org/abs/2110.06765>`_
+- `Discrete Lehmann representation of imaginary time Green's functions, Jason Kaye, Kun Chen, and Olivier Parcollet, Phys. Rev. B 105, 235115, 2022. <https://journals.aps.org/prb/abstract/10.1103/PhysRevB.105.235115>`_ [`arXiv:2107.13094 <https://arxiv.org/abs/2107.13094>`_]
 
 
 ``libdlr`` imaginary time point format
@@ -74,7 +72,7 @@ maintain full relative accuracy.
 
 This apparently annoying characteristic of ``libdlr`` is simply the price of
 maintaining all the accuracy that is possible to maintain in floating
-point arithmic. It is the right thing to do. But it is also largely
+point arithmic. But it is largely
 ignoreable if the loss of accuracy is not noticeable in your application
 (this will be the case for the vast majority of users). Just use the
 provided demos to get started, and follow these guidelines:
@@ -98,3 +96,6 @@ provided demos to get started, and follow these guidelines:
 3. If you happen to want to evaluate a Green's function on an
    equispaced grid on :math:`[0,1]` in imaginary time, use the subroutine ``eqpts_rel``
    to generate this grid in the relative format.
+
+A more in-depth discussion of the relative format is given in Appendix C
+of `our paper on libdlr <https://arxiv.org/abs/2110.06765>`_.

doc/conf.py

@@ -67,9 +67,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = u'0.1.0'
+version = u'1.0.0'
 # The full version, including alpha/beta/rc tags.
-release = u'0.1.0'
+release = u'1.0.0'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

doc/fortran_examples.rst

@@ -1,10 +1,22 @@
 
+.. _Fortran examples:
+
 Fortran examples
 ================
 
-For the Fortran library, ``libdlr``, the sample programs contained in the folder ``./libdlr/demo`` show standard examples of usage, and should serve as a useful starting point. The demos are thoroughly commented. For more information on specific subroutines, please refer to the :ref:`API Documentation ``libdlr```.
+Sample programs for the Fortran library ``libdlr`` are contained in the folders ``./libdlr/demo`` and ``./libdlr/test``. Both show standard examples of usage, and can serve as a useful starting point, however we recommend looking at the ``demo`` folder first. If you do not find the example you need there, then look through the programs in the ``test`` folder. These also serve as compilation test programs and are typically designed to test specific operations using analytically solvable examples. Both the demos and tests are thoroughly commented. For more information on specific subroutines, please refer to the :ref:`API Documentation ``libdlr```. Below, we provide a list of all demo and test programs, with brief descriptions.
+
+We note, in particular, the C test program `ha_it.c`_, which provides an
+example of the C interface included with ``libdlr``.
 
-The following is a list of the demos, with brief descriptions:
+The Python examples section of this documentation provides a more
+step-by-step tutorial of the use of the DLR in standard situations than
+is given here, but the Fortran demos and tests should be sufficient for
+users who have read at least one of the papers listed in the
+:ref:`Background` section.
+
+Demo programs
+~~~~~~~~~~~~~
 
 DLR from Matsubara frequency
 ----------------------------
@@ -21,18 +33,71 @@ Fit noisy imaginary time data
 
 `sc_it_fit.f90`_ - Recover DLR of Green's function with semi-circular spectral density from noisy samples on a uniform imaginary time grid.
 
-Solve SYK in imaginary time
+SYK model in imaginary time
 ---------------------------
 
 `syk_it.f90`_ - Solve the SYK model (Dyson equation with SYK self-energy) by an imaginary time domain method.
 
-Solve SYK in Matsubara frequency and imaginary time
----------------------------------------------------
+SYK model in Matsubara frequency
+--------------------------------
 
 `syk_mf.f90`_ - Solve the SYK model (Dyson equation with SYK self-energy) by a more standard method, which computes the self-energy in the imaginary time domain, and solves the Dyson equation in the Matsubara frequency domain.
 
+
+Test programs
+~~~~~~~~~~~~~
+
+DLR from Matsubara frequency
+----------------------------
+
+`ha_mf.f90`_ - Recover DLR of Green's function with sum-of-delta-functions spectral density from its samples on the DLR Matsubara frequency grid.
+
+DLR from imaginary time 
+-----------------------
+
+`ha_it.f90`_ - Recover DLR of Green's function with sum-of-delta-functions spectral density from its samples on the DLR imaginary time grid.
+
+C example: DLR from imaginary time
+----------------------------------
+
+`ha_it.c`_ - Same as ha_it.f90, but in C. This program demonstrates the
+use of the C interface included with ``libdlr``.
+
+Convolution in imaginary time
+-----------------------------
+
+`conv_exp.f90`_ - Convolve two Green's functions represented by their
+values on the DLR imaginary time grid, obtaining the result on the same
+grid.
+
+Dyson equation with fixed self-energy
+-------------------------------------
+
+`dyson_sc.f90`_ - Solve the Dyson equation with a fixed self-energy both
+in imaginary time and in Matsubara frequency.
+
+Matrix-valued Dyson equation with fixed self-energy
+---------------------------------------------------
+
+`dyson_mat.f90`_ - Solve matrix-valued Dyson equation with a fixed self-energy in
+imaginary time.
+
+L^2 inner products
+------------------
+
+`ip_exp.f90`_ - Compute the L^2 inner product of two Green's functions
+in imaginary time.
+
+
 .. _sc_it.f90: https://github.com/jasonkaye/libdlr/blob/main/demo/sc_it.f90#L24
 .. _sc_it_fit.f90: https://github.com/jasonkaye/libdlr/blob/main/demo/sc_it_fit.f90#L24
 .. _sc_mf.f90: https://github.com/jasonkaye/libdlr/blob/main/demo/sc_mf.f90#L24
 .. _syk_it.f90: https://github.com/jasonkaye/libdlr/blob/main/demo/syk_it.f90#L24
 .. _syk_mf.f90: https://github.com/jasonkaye/libdlr/blob/main/demo/syk_mf.f90#L24
+.. _ha_mf.f90: https://github.com/jasonkaye/libdlr/blob/main/test/ha_mf.f90#L24
+.. _ha_it.f90: https://github.com/jasonkaye/libdlr/blob/main/test/ha_it.f90#L24
+.. _ha_it.c: https://github.com/jasonkaye/libdlr/blob/main/test/ha_it.c#L23
+.. _conv_exp.f90: https://github.com/jasonkaye/libdlr/blob/main/test/conv_exp.f90#L24
+.. _dyson_sc.f90: https://github.com/jasonkaye/libdlr/blob/main/test/dyson_sc.f90#L24
+.. _dyson_mat.f90: https://github.com/jasonkaye/libdlr/blob/main/test/dyson_mat.f90#L24
+.. _ip_exp.f90: https://github.com/jasonkaye/libdlr/blob/main/test/ip_exp.f90#L24

doc/index.rst

@@ -2,11 +2,16 @@
 ``libdlr``: Imaginary time calculations using the Discrete Lehmann Representation
 =================================================================================
 
-The ``libdlr`` library provides routines for efficient imaginary time calculations of single particle Green's functions using the **Discrete Lehmann Representation** (DLR). For more information on the DLR and the imaginary time formalism, please see the :ref:`Background`.
+The ``libdlr`` library provides Fortran routines for efficient imaginary time calculations of single particle Green's functions using the **Discrete Lehmann Representation** (DLR), as well as a stand-alone Python module ``pydlr`` implementing the same functionality. For more information on the DLR and the imaginary time formalism, please see the :ref:`Background`.
 
 Take a look at our recent preprint for an introduction to the library:
 
-- "libdlr: Efficient imaginary time calculations using the discrete Lehmann representation", Jason Kaye, Kun Chen, and Hugo U.R. Strand, `arXiv:2110.06765 <https://arxiv.org/abs/2110.06765>`_
+- `libdlr: Efficient imaginary time calculations using the discrete Lehmann representation, Jason Kaye, Kun Chen, and Hugo U.R. Strand, arXiv:2110.06765. <https://arxiv.org/abs/2110.06765>`_
+
+We note that ``libdlr`` provides an easy to use C interface. An example
+program is described in the :ref:`Fortran examples` section. There is
+also a Julia package, `Lehmann.jl <https://github.com/numericaleft/Lehmann.jl>`_, which implements similar
+functionality to ``libdlr``.
 
 .. toctree::
    :maxdepth: 2

test/conv_exp.f90

@@ -191,11 +191,13 @@ subroutine conv_exp_main(lambda,eps,ntst,beta)
 
       write(6,*) ''
       write(6,*) 'DLR rank = ',r
+      write(6,*) 'Errors for first method -- convolution tensor:'
       write(6,*) 'Abs L^inf err = ',err1linf
       write(6,*) 'Abs L^2 err   = ',err1l2
       write(6,*) 'Rel L^inf err = ',err1linf/gmax
       write(6,*) 'Rel L^2 err   = ',err1l2/gl2
 
+      write(6,*) 'Errors for second method -- fast convolution:'
       write(6,*) 'Abs L^inf err = ',err2linf
       write(6,*) 'Abs L^2 err   = ',err2l2
       write(6,*) 'Rel L^inf err = ',err2linf/gmax

test/ha_it.c

@@ -37,6 +37,10 @@
       // sum of two delta functions. Recover DLR coefficients from
       // values of Green's function on imaginary time grid, and measure
       // the error of the resulting DLR expansion on a test grid.
+      //
+      // The purpose of this program is to demonstrate and test the C
+      // interface included with libdlr. It carries out the same
+      // calculation as ha_it.f90.
 
       int ntst;
       double lambda,eps,beta;