Examples

This page walks through two real modules of the SciFortran / EDIpack code base. They were chosen because they sit at the two ends of what a Fortran documentation tool has to cope with:

SF_ARRAYS: A library of functions. The documentation is in the routines: descriptions, arguments, optional arguments, results.
ED_INPUT_VARS: A module made of about 120 input variables and a handful of routines, with C bindings, default values, lists of allowed values, LaTeX and preprocessor directives.

The sources are copied in the examples folder of the documentation, which is the fortran_src directory of conf.py. Each example ends with its live rendering, built by the directives shown there. Every block of reStructuredText in between is the actual output of the parser.

Example 1: a library of functions (`SF_ARRAYS`)

The module begins with a one-line description, right under the module statement, followed by its public statements:

module SF_ARRAYS
!SciFortran module for array creation and manipulation
  implicit none

  !GRIDS:
  public :: linspace
  public :: logspace
  ...
contains

Two-line documentation in the .rst file is all that is needed:

.. f:automodule:: sf_arrays

The head of the generated text (the one-line description is used as synopsis in the module index, and Quick access lists the public routines):

.. f:module:: sf_arrays
   :synopsis: SciFortran module for array creation and manipulation

.. rubric:: Description

SciFortran module for array creation and manipulation

.. rubric:: Quick access

:Routines: :f:func:`arange`, :f:func:`linspace`, :f:func:`logspace`, :f:func:`powspace`, :f:func:`upminterval`, :f:func:`upmspace`

A function with optional arguments: `linspace`

function linspace(start,stop,num,istart,iend,mesh) result(array)
!
!Returns an array of evenly spaced numbers over a specified interval.
!Returns :f:var:`num` evenly spaced samples, calculated over the interval [:f:var:`start`, :f:var:`stop`].
!The start and end points of the interval can optionally be excluded.
!
  real(8)          :: start           !Starting value of the sequence
  real(8)          :: stop            !End value of the sequence
  integer          :: num             !Number of samples to generate
  logical,optional :: istart          !If :code:`.true.`, :f:var:`start` is included in the resulting array. Default :code:`.true.`
  logical,optional :: iend            !If :code:`.true.`, :f:var:`stop` is included in the resulting array. Default :code:`.true.`
  real(8),optional :: mesh            !If present, the step is saved in this variable
  real(8)          :: array(num)      !Contains :f:var:`num` equally spaced samples in the interval
                                      ![:f:var:`start`, :f:var:`stop`], left/right open or closed depending on
                                      !:f:var:`istart` and :f:var:`iend`

.. f:function:: linspace(start, stop, num[, istart, iend, mesh])

   Returns an array of evenly spaced numbers over a specified interval.
   Returns :f:var:`num` evenly spaced samples, calculated over the interval [:f:var:`start`, :f:var:`stop`].
   The start and end points of the interval can optionally be excluded.

   :p real start: Starting value of the sequence
   :p real stop: End value of the sequence
   :p integer num: Number of samples to generate
   :o logical istart: If :code:`.true.`, :f:var:`start` is included in the resulting array. Default :code:`.true.`
   :o logical iend: If :code:`.true.`, :f:var:`stop` is included in the resulting array. Default :code:`.true.`
   :o real mesh: If present, the step is saved in this variable
   :r real array(num): Contains :f:var:`num` equally spaced samples in the interval [:f:var:`start`, :f:var:`stop`], left/right open or closed depending on :f:var:`istart` and :f:var:`iend`

What the parser did for us:

optional in the declarations gave the brackets in the signature and the :o fields;
result(array) selected the variable that is documented in the :r field, with its shape (num);
real(8) is shown as real: the kind is not part of the output;
the three comment lines of array were joined into one description (each line ends with a space).

Mathematics and cross-references: `upmspace`

Descriptions are reStructuredText, so LaTeX maths and links are available:

function upmspace(start,stop,p,u,ndim,base,istart,iend,mesh) result(aout)
!
!Returns an array of number spaced linearly between exponentially spaced checkpoints.
!The interval [:f:var:`start`, :f:var:`stop`] is first divided into :f:var:`p`
!coarse regions, the width of which is exponentially increasing so that the
!i-th checkpoint is (:f:var:`stop` - :f:var:`start`) :math:`\cdot` :f:var:`base` ^ ( - :f:var:`p` + :code:`i` ).
!Each of the coarse intervals is then linearly divided in :f:var:`u` subintervals.
!
  real(8)          :: start  !First element of the array
  ...
  integer          :: ndim   !Length of the out array, must be :math:`p \cdot u` or  :math:`p \cdot u + 1`
  real(8),optional :: mesh(ndim) !If present, contains the distances between consecutive points in :f:var:`aout`.
                                 !The last element is :code:`aout(ndim) - aout(ndim-1)`

.. f:function:: upmspace(start, stop, p, u, ndim[, base, istart, iend, mesh])

   Returns an array of number spaced linearly between exponentially spaced checkpoints.
   The interval [:f:var:`start`, :f:var:`stop`] is first divided into :f:var:`p`
   coarse regions, the width of which is exponentially increasing so that the
   i-th checkpoint is (:f:var:`stop` - :f:var:`start`) :math:`\cdot` :f:var:`base` ^ ( - :f:var:`p` + :code:`i` ).
   Each of the coarse intervals is then linearly divided in :f:var:`u` subintervals.

   :p real start: First element of the array
   :p real stop: Last element of the array
   :p integer p: Number of coarse subdivisions
   :p integer u: Number of fine subdivisions
   :o integer ndim: Length of the out array, must be :math:`p \cdot u` or  :math:`p \cdot u + 1`
   :o real base: Base of the exponential spacing (default :code:`2`)
   :o logical istart: If :code:`.true.`, :f:var:`start` is included in the resulting array. Default :code:`.true.`
   :o logical iend: If :code:`.true.`, :f:var:`stop` is included in the resulting array. Default :code:`.true.`
   :o real mesh(ndim): If present, contains the distances between consecutive points in :f:var:`aout`. The last element is :code:`aout(ndim) - aout(ndim-1)`
   :r real aout(ndim): Contains :f:var:`p` coarse exponentially-spaced checkpoints, each two of which separated by :f:var:`u` linearly spaced points

Note

ndim is declared plainly (integer :: ndim) yet is shown with the :o field, although the signature does not bracket it. This comes from the f2py-derived parser, which treats an argument that is only used to dimension another one (here mesh(ndim), an optional array) as optional with an inferred value. Compare the generated fields with the declarations, which are the reference. To get a plain :p field, the :o / :p role cannot be changed from the comment: write the routine by hand with f:function if it matters.

Cross-references to a routine 

upminterval refers to upmspace with a role written in the Fortran comment:

!This is achieved by calling :f:func:`upmspace` twice in a mirror-like fashion.

In the built page this is a link to the description of upmspace.

Documenting one routine only 

.. f:autoroutine:: powspace

If a routine needs a handwritten paragraph, f:automodule can declare the module while the routines are placed where you want them:

.. f:automodule:: sf_arrays
   :hide-output: 1

Linear grids
------------

.. f:autoroutine:: linspace
.. f:autoroutine:: arange

Exponential grids
-----------------

.. f:autoroutine:: powspace
.. f:autoroutine:: upmspace

Live rendering of `SF_ARRAYS`

Everything below is generated from examples/SF_ARRAYS.f90 by

.. f:automodule:: sf_arrays

Description

SciFortran module for array creation and manipulation

Quick access

Routines:: arange(), linspace(), logspace(), powspace(), upminterval(), upmspace()

Subroutines and functions

function linspace(start, stop, num[, istart, iend, mesh])

Returns an array of evenly spaced numbers over a specified interval. Returns num evenly spaced samples, calculated over the interval [start, stop]. The start and end points of the interval can optionally be excluded.

Parameters:

start [real] – Starting value of the sequence
stop [real] – End value of the sequence
num [integer] – Number of samples to generate

Options:

istart [logical] – If .true., start is included in the resulting array. Default .true.
iend [logical] – If .true., stop is included in the resulting array. Default .true.
mesh [real] – If present, the step is saved in this variable

Result:

array (num) [real] – Contains num equally spaced samples in the interval [start, stop], left/right open or closed depending on istart and iend

function logspace(start, stop, num[, base])

Returns numbers spaced evenly on a log scale. In linear space, the sequence starts at start and ends with stop (differently from numpy).

Parameters:

start [real] – The starting value of the sequence. Must be positive. If set to 0, it will be reshifted to 1e-12
stop [real] – The end value of the sequence. Must be positive. If set to 0, it will be reshifted to 1e-12
num [integer] – Number of samples to generate

Options:

base [real] – The base of the exponential. Default 10

Result:

array (num) [real] – Contains num samples, equally spaced on a log scale in the closed interval [start, stop]

function arange(start, num)

Returns an array of num integers starting with start

Parameters:

start [integer] – First element of the array
num [integer] – Length of the array

Result:

array (num) [integer] – Contains the integer numbers in [start, start+num-1]

function upmspace(start, stop, p, u, ndim[, base, istart, iend, mesh])

Returns an array of number spaced linearly between exponentially spaced checkpoints. The interval [start, stop] is first divided into p coarse regions, the width of which is exponentially increasing so that the i-th checkpoint is (stop - start) \(\cdot\) base ^ ( - p + i ). Each of the coarse intervals is then linearly divided in u subintervals.

Parameters:

start [real] – First element of the array
stop [real] – Last element of the array
p [integer] – Number of coarse subdivisions
u [integer] – Number of fine subdivisions

Options:

ndim [integer] – Length of the out array, must be \(p \cdot u\) or \(p \cdot u + 1\)
base [real] – Base of the exponential spacing (default 2)
istart [logical] – If .true., start is included in the resulting array. Default .true.
iend [logical] – If .true., stop is included in the resulting array. Default .true.
mesh (ndim) [real] – If present, contains the distances between consecutive points in aout. The last element is aout(ndim) - aout(ndim-1)

Result:

aout (ndim) [real] – Contains p coarse exponentially-spaced checkpoints, each two of which separated by u linearly spaced points

function upminterval(start, stop, midpoint, p, q[, type, base, mesh])

Returns an array of number spaced linearly between exponentially spaced checkpoints, specularly around a middle point between the interval extrema. This is achieved by calling upmspace() twice in a mirror-like fashion. The exponential thickening of the mesh can be around the middle ( type !=0 ) or the boundaries( type =0 )

Parameters:

start [real] – First element of the array
stop [real] – Last element of the array
midpoint [real] – Middle point of the array. The distance between the coarse checkpoints behaves specularly on the two sides
p [integer, in,required] – Number of coarse subdivisions
q [integer, in,required] – If present, contains the distances between consecutive points in array. The last element is array(2 · p · q+1) - array(2 · p · q)

Options:

type [integer] – If =0, mesh is thicker around start and stop. If =1, mesh is thicker around midpoint. Default 0
base [real] – Base of the exponential spacing (default 2)
mesh (1 + 2 · p · q) [real] – If present, contains the distances between consecutive points in array. The last element is array(2 · p · q+1) - array(2 · p · q)

Result:

array (1 + 2 · p · q) [real] – Contains \(2 \cdot p \cdot q+1\) points

function powspace(start, stop, num[, base])

Returns numbers spaced evenly on an exponential scale. The i-th number is start + (stop - start) \(\cdot\) base ^ ( - num + i )

Parameters:

start [real] – first element of the array
stop [real] – last element of the array
num [integer] – number of elements of the array

Options:

base [real] – base of the exponential (defaule 2)

Result:

array (num) [real] – contains num exponentially spaced reals

Example 2: a module of input variables (`ED_INPUT_VARS`)

This module has few routines and many variables, described in the trailing-bang style (see Formatting Fortran (.f90) Code for Auto-Documentation): the declaration ends with a bare ! and the description follows on the next comment lines, a bare ! closing it.

MODULE ED_INPUT_VARS
  !:synopsis: User-accessible input variables
  !Contains all global input variables which can be set by the user through the input file.
  ...
  USE SF_VERSION
  USE SF_PARSE_INPUT
  USE SF_IOTOOLS, only:str,free_unit,to_upper,to_lower
  USE ED_VERSION
  use iso_c_binding
  implicit none

The generated head (the Quick access list has 119 variables and is shortened here):

.. f:module:: ed_input_vars
   :synopsis: User-accessible input variables

.. rubric:: Description

Contains all global input variables which can be set by the user through the input file. A specific preocedure :f:func:`ed_read_input` should be called to read the input file using :f:func:`parse_input_variable` procedure from SciFortran. All variables are automatically set to a default, looked for and updated by reading into the file and, sequentially looked for and updated from command line (std.input) using the notation `variable_name=variable_value(s)` (case independent).

.. rubric:: Quick access

:Variables: :f:var:`a_ph`, :f:var:`bath_type`, :f:var:`beta`, ... (119 entries)
:Routines: :f:func:`ed_read_input`, :f:func:`ed_update_input`, :f:func:`print_logo`, :f:func:`s_chop`, :f:func:`substring_delete`

.. rubric:: External modules

- :f:mod:`sf_version`

- :f:mod:`sf_parse_input`

- :f:mod:`sf_iotools`

   - :f:func:`~sf_iotools/str`
   -  :f:func:`~sf_iotools/free_unit`
   -  :f:func:`~sf_iotools/to_upper`
   -  :f:func:`~sf_iotools/to_lower`

- :f:mod:`ed_version`

- :f:mod:`iso_c_binding`

A variable with a list of allowed values and a default 

integer(c_int),bind(c, name="Nbath")   :: Nbath   !
!Number of bath sites:
! * :f:var:`bath_type` = :code:`normal` : number of bath sites per orbital
! * :f:var:`bath_type` = :code:`hybrid` : total number of bath sites
! * :f:var:`bath_type` = :code:`replica/general` : number of replicas
! :Default Nbath:`6`
!

.. f:variable:: nbath

   Number of bath sites:

    * :f:var:`bath_type` = :code:`normal` : number of bath sites per orbital

    * :f:var:`bath_type` = :code:`hybrid` : total number of bath sites

    * :f:var:`bath_type` = :code:`replica/general` : number of replicas

   :Type: integer

   :Bindings: Language = **c**, Name = **nbath**
   :Default: 6

* item lines became a bullet list;
:Default Nbath:`6` was removed from the text and became the :Default: field;
bind(c, name="Nbath") became the :Bindings: field, and integer(c_int) the type integer.

An array variable 

real(c_double),dimension(5),bind(c, name="Uloc")   :: Uloc   !
!Values of the local interaction per orbital (max :code:`5` )
! :Default Uloc:`(/( 2d0,i=1,Norb )/)`
!

.. f:variable:: uloc

   Values of the local interaction per orbital (max :code:`5` )

   :Type: real(5)

   :Bindings: Language = **c**, Name = **uloc**
   :Default: (/( 2d0,i=1,Norb )/)

The shape is appended to the type: real(5) is a real array with five elements.

Mathematics, and a warning in a variable 

character(len=12)    :: cg_norm   !
!Which norm to use in the evaluation of the :math:`\chi^{2}` for matrix quantities.
! * :code:`ELEMENTAL` : :math:`\chi^{2}` is the sum of each component's :math:`\chi^{2}`
! * :code:`FROBENIUS` : :math:`\chi^{2}` is calculated on the Frobenius norm (Matrix distance)
! :Default cg_norm:`ELEMENTAL`
!.. warning::
!   The Frobenius norm is currently implemented only for ...

.. f:variable:: cg_norm

   Which norm to use in the evaluation of the :math:`\chi^{2}` for matrix quantities.

    * :code:`ELEMENTAL` : :math:`\chi^{2}` is the sum of each component's :math:`\chi^{2}`

    * :code:`FROBENIUS` : :math:`\chi^{2}` is calculated on the Frobenius norm (Matrix distance)

    .. warning::    The Frobenius norm is currently implemented only for :f:var:`ed_bath` = :code:`replica, general`.    Also, for :f:var:`cg_pow` :math:`\neq 2`  the Frobenius norm is ill-defined, at least with respect    to its usual mathematical meaning. The behavior of :code:`cg_norm=frobenius` might be changed or    removed in future versions of the code, breaking back-compatibility.

   :Type: character(len=12)

   :Default: ELEMENTAL

The admonition is written as a single line by the parser: its content follows the .. warning:: marker on the same line, which docutils reads as the content of the warning. It is placed after the :Default: field in the source, but the field is displayed at the end of the description.

Logical flags and text following the list 

When text follows a list, the list is closed automatically by the blank lines that the parser inserts:

.. f:variable:: ed_total_ud

   Flag to select which type of quantum numbers have to be considered (if :f:var:`ed_mode` = :code:`normal`)

    * :code:`T` : blocks have different total :math:`N_{\uparrow}` and :math:`N_{\downarrow}`

    * :code:`F` : blocks have different total :math:`N^{\alpha}_{\uparrow}` and :math:`N^{\alpha}_{\downarrow}`

   where :math:`\alpha` is the orbital index. Speeds up calculation in the case where orbitals are not hybridized

   :Type: logical

   :Bindings: Language = **c**, Name = **ed_total_ud**
   :Default: T

Variables with a `save` attribute 

LOGfile is declared integer(c_int),bind(c, name="LOGfile"),save. The non-bind attributes go into the :Attributes: field:

.. f:variable:: logfile

   Logfile unit

   :Type: integer

   :Attributes: save
   :Bindings: Language = **c**, Name = **logfile**
   :Default: 6

Routines of the module 

ed_read_input is documented by one description line under its signature:

subroutine ed_read_input(INPUTunit)
  !
  !This functions reads the input file provided by :code:`INPUTunit` and sets the global variables accordingly
#ifdef _MPI
  USE MPI
  USE SF_MPI
#endif
  character(len=*) :: INPUTunit

.. f:subroutine:: ed_read_input(inputunit)

   This functions reads the input file provided by :code:`INPUTunit` and sets the global variables accordingly

   :p character(len=*) inputunit:
   :use: :f:mod:`mpi`, :f:mod:`sf_mpi`

Note the :use: field: both mpi and sf_mpi are listed because the preprocessor is not run. INPUTunit has no description, so the field is empty; add a comment at the end of its declaration to fill it.

Which variables need attention?

Running the parser on the module shows 119 module variables, of which 105 have a description. Of the 14 remaining ones:

11 are the internal helpers ending in _ (ed_twin_, uloc_, pair_field_, …): they have no description because they are implementation details of the input reader. They are listed in the documentation because they are public. Exclude them with :undoc-members: (see the live rendering below), or declare them private;
g_ph_diag and niter really lack a description: g_ph_diag has the description on the next lines but no trailing ! on the declaration, and niter has a bare ! followed by a blank;
normal_complex is set by the preprocessor and has no comment.

Two things in the source of cg_norm are worth fixing by the author: the warning refers to :f:var:`ed_bath`, which does not exist (the variable is bath_type), so the link stays unresolved, and the module description says “preocedure”.

Live rendering of `ED_INPUT_VARS`

Everything below is generated from examples/ED_INPUT_VARS.f90. The variables whose name ends in an underscore are internal helpers of the input reader and are left out with :undoc-members::

.. f:automodule:: ed_input_vars
   :undoc-members: chidens_flag_, chiexct_flag_, chipair_flag_, chispin_flag_,
                   ed_read_umatrix_, ed_total_ud_, ed_twin_, ed_use_kanamori_,
                   pair_field_, rdm_flag_, uloc_

Description

Contains all global input variables which can be set by the user through the input file. A specific preocedure ed_read_input() should be called to read the input file using parse_input_variable() procedure from SciFortran. All variables are automatically set to a default, looked for and updated by reading into the file and, sequentially looked for and updated from command line (std.input) using the notation variable_name=variable_value(s) (case independent).

Quick access

Variables:: a_ph, bath_type, beta, bfile, cg_ftol, cg_grad, cg_method, cg_minimize_hh, cg_minimize_ver, cg_niter, cg_norm, cg_pow, cg_scheme, cg_stop, cg_weight, chidens_flag, chiexct_flag, chipair_flag, chispin_flag, cutoff, deltasc, dmft_error, ed_all_g, ed_finite_temp, ed_hw_bath, ed_input_file, ed_mode, ed_obs_all, ed_offset_bath, ed_print_chidens, ed_print_chiexct, ed_print_chipair, ed_print_chispin, ed_print_g, ed_print_g0, ed_print_sigma, ed_read_umatrix, ed_sectors, ed_sectors_shift, ed_solve_offdiag_gf, ed_sparse_h, ed_total_ud, ed_twin, ed_use_kanamori, ed_verbose, eps, exc_field, finitet, g_ph, g_ph_diag, gphfile, gs_threshold, hfile, hfmode, hlocfile, jh, jp, jx, jz_basis, jz_max, jz_max_value, lanc_dim_threshold, lanc_method, lanc_ncv_add, lanc_ncv_factor, lanc_ngfiter, lanc_niter, lanc_nstates_sector, lanc_nstates_step, lanc_nstates_total, lanc_tolerance, lfit, lmats, logfile, lpos, lreal, ltau, nbath, ncoeff, ndelta, nerr, niter, nloop, norb, normal_complex, nph, nread, nspin, nsuccess, pair_field, ph_type, print_input_vars, print_sector_eigenvalues, rdm_flag, sb_field, sectorfile, spin_field_x, spin_field_y, spin_field_z, uloc, umatrix_file, ust, w0_ph, wfin, wini, xmax, xmin, xmu
Routines:: ed_read_input(), ed_update_input(), print_logo(), s_chop(), substring_delete()

External modules

sf_version
sf_parse_input
sf_iotools
- str()
- free_unit()
- to_upper()
- to_lower()
ed_version
iso_c_binding

Variables

a_ph

Phonon forcing field coupled to displacement operator (constant)

Type:: real
Default:: 0d0

bath_type

Flag to select the bath geometry

normal : each impurity orbital has a set of bath levels in a star geometry

hybrid : all impurity orbitals communicate with the same set of bath levels in a star geometry

replica : the impurity communicates with clusters of the same form via an hybridization term \(V\mathbb{I}\)

general : extends replica so that each orbital has a different hybridization strength

Type:: character(len=8)
Default:: normal

beta

Inverse temperature, at zero temperature it is used as a IR cut-off.

Type:: real
Bindings:: Language = c, Name = beta
Default:: 1000d0

bfile

File where to retrieve/store the bath parameters

Type:: character(len=100)
Default:: hbasis[.used/restart]

cg_ftol

Tolerance in the conjugate-gradient fitting procedure

Type:: real
Default:: 1d-5

cg_grad

Flag to set the type of gradient evaluation (if cg_method = 0 )

0 : analytic

1 : numeric

Type:: integer
Default:: 0

cg_method

Conjugate-gradient fitting routine to be used:

0 : Numerical Recipes

1 :minimize (FORTRAN77 code)

Type:: integer
Default:: 0

cg_minimize_hh

Unknown parameter used in the CG minimize procedure ( for cg_grad = 1 )

Type:: real
Default:: 1d-4

cg_minimize_ver

If cg_grad = 1 , select which version of minimize.f to use

T : Lichtenstein (newer)

F : Krauth (older)

Type:: logical
Default:: F

cg_niter

Maximum number of iterations in the bath fitting procedure

Type:: integer
Default:: 500

cg_norm

Which norm to use in the evaluation of the \(\chi^{2}\) for matrix quantities.

ELEMENTAL : \(\chi^{2}\) is the sum of each component’s \(\chi^{2}\)

FROBENIUS : \(\chi^{2}\) is calculated on the Frobenius norm (Matrix distance)

Warning

The Frobenius norm is currently implemented only for ed_bath = replica, general. Also, for cg_pow \(\neq 2\) the Frobenius norm is ill-defined, at least with respect to its usual mathematical meaning. The behavior of cg_norm=frobenius might be changed or removed in future versions of the code, breaking back-compatibility.

Type:: character(len=12)
Default:: ELEMENTAL

cg_pow

Power exponent in the \(\chi^{2}\) , according to \(\vert \mathcal{G}_{0}(i\omega_{n}) - G_{0}^{\mathrm{And}}(i\omega_{n}) \vert ^{\mathrm{cg\_pow}}\) or \(\vert \Delta(i\omega_{n})- \Delta^{\mathrm{And}}(i\omega_{n}) \vert ^{\mathrm{cg\_pow}}\)

Type:: integer
Default:: 2

cg_scheme

Which quantity to use in the bath fitting routine:

WEISS : the lattice Weiss field Green’s function \(\mathcal{G}_{0}(i\omega_{n})\) is fitted

DELTA : the lattice Hybridization function \(\Delta(i\omega_{n})\) is fitted

Type:: character(len=6)
Default:: Weiss

cg_stop

Conjugate-gradient stopping condition

0 : 1 .and. 2

1 : \(\vert F_{n-1} -F_{n} \vert < \mathrm{tol} \cdot (1+F_{n})\)

2 : \(\vert\vert x_{n-1} -x_{n} \vert\vert <\mathrm{tol} \cdot (1+ \vert\vert x_{n} \vert\vert\))

Type:: integer
Default:: 0

cg_weight

Weight assigned to the imaginary frequency data points in the calculation of the \(\chi^{2}\)

0 : \(1\)

1 : \(\frac{1}{n}\)

2 : \(\frac{1}{\omega_{n}}\)

Type:: integer
Default:: 0

chidens_flag

Flag to activate charge susceptibility evaluation

Type:: logical
Bindings:: Language = c, Name = chidens_flag
Default:: F

chiexct_flag

Flag to activate excitonic susceptibility evaluation

Type:: logical
Bindings:: Language = c, Name = chiexct_flag
Default:: F

chipair_flag

Flag to activate pairing susceptibility evaluation

Type:: logical
Bindings:: Language = c, Name = chipair_flag
Default:: F

chispin_flag

Flag to activate spin susceptibility evaluation

Type:: logical
Bindings:: Language = c, Name = chispin_flag
Default:: F

cutoff

Spectrum cut-off, used to determine the number states to be retained

Type:: real
Default:: 1d-9

deltasc

Value of the SC symmetry breaking term (only used if ed_mode = superc )

Type:: real
Default:: 2d-2

dmft_error

Error threshold for DMFT convergence

Type:: real
Bindings:: Language = c, Name = dmft_error
Default:: 1d-5

ed_all_g

Flag to evaluate all the components of the impurity Green`s functions irrespective of the symmetries

Type:: logical
Default:: F

ed_finite_temp

Flag to set whether the problem is at finite temperature.If T then lanc_nstates_total must be greater than 1.

Type:: logical
Default:: F

ed_hw_bath

Half-bandwidth for bath level initialization if bath_type = normal, hybrid . The levels will be equispaced in the range [-hw,hw]

Type:: real
Default:: 2d0

ed_input_file

Name of input file

Type:: character(len=200)

ed_mode

Flag to set the ED mode

normal : normal

superc : s-wave superconductive (singlet pairing)

nonsu2 : broken SU(2) symmetry

Type:: character(len=7)
Default:: normal

ed_obs_all

Flag to print observables for every loop

Type:: logical
Default:: T

ed_offset_bath

Offset for the initialization of diagonal terms if bath_type = replica, general . The replicas will be equally spaced in the range [-offset,offset]

Type:: real
Default:: 1d-1

ed_print_chidens

Flag to print impurity dens susceptibility, if calculated

Type:: logical
Default:: T

ed_print_chiexct

Flag to print impurity exct susceptibility, if calculated

Type:: logical
Default:: T

ed_print_chipair

Flag to print impurity pair susceptibility, if calculated

Type:: logical
Default:: T

ed_print_chispin

Flag to print impurity spin susceptibility, if calculated

Type:: logical
Default:: T

ed_print_g

Flag to print impurity Green`s functions

Type:: logical
Default:: T

ed_print_g0

Flag to print impurity non-interacting Green`s functions

Type:: logical
Default:: T

ed_print_sigma

Flag to print impurity Self-energies

Type:: logical
Default:: T

ed_read_umatrix

Flag to enable ( T ) or not (F ) reading the two-body terms from an external filedefined by umatrix_file

Type:: logical
Bindings:: Language = c, Name = ed_read_umatrix
Default:: F

ed_sectors

Flag to reduce sector scan for the spectrum to specific sectors

Type:: logical
Default:: F

ed_sectors_shift

Additional sectors to be evaluated if ed_sectors is set. These are sectors with all the quantum numbers varying of at most by ed_sectors_shift around the sectors listed in sectorfile.

Type:: integer
Default:: 1

ed_solve_offdiag_gf

Flag to select the calculation of the off-diagonal impurity GF. Set to T by default if bath_type is not normal

Type:: logical
Default:: F

ed_sparse_h

Flag to select storage of the Fock space Hamiltonian as a sparse matrix

T : \(H\) is stored. CPU intensive

F : on-the-fly \(H \cdot v\) product is stored. Memory intensive

Type:: logical
Default:: T

ed_total_ud

Flag to select which type of quantum numbers have to be considered (if ed_mode = normal)

T : blocks have different total \(N_{\uparrow}\) and \(N_{\downarrow}\)

F : blocks have different total \(N^{\alpha}_{\uparrow}\) and \(N^{\alpha}_{\downarrow}\)

where \(\alpha\) is the orbital index. Speeds up calculation in the case where orbitals are not hybridized

Type:: logical
Bindings:: Language = c, Name = ed_total_ud
Default:: T

ed_twin

Flag to reduce ( T ) or not (F ) the number of visited sector using twin symmetry

Type:: logical
Bindings:: Language = c, Name = ed_twin
Default:: F

ed_use_kanamori

Flag to enable ( T ) or not (F ) the use of the input variables ULOC, UST, JH, JX, JP for Hubbard-Kanamori coefficients.

Type:: logical
Bindings:: Language = c, Name = ed_use_kanamori
Default:: T

ed_verbose

Verbosity level:

0 : almost nothing

…

3 : most of the verbose output

…

5 : everything. Really, everything

Type:: integer
Default:: 3

eps

Broadening on the real frequency axis for Green’s function and Susceptibility calculations.

Type:: real
Bindings:: Language = c, Name = eps
Default:: 1d-2

exc_field

External field coupling to exciton order parameter

Type:: real(4)
Default:: zero

finitet

Flag to set finite-temperature calculation

Type:: logical

g_ph

Electron-phonon coupling constant all

Type:: complex(•, •)
Attributes:: allocatable
Default:: zero

g_ph_diag

Type:: real(•)
Attributes:: allocatable

gphfile

File of Phonon couplings. Set to NONE to use only density couplings.

Type:: character(len=100)
Default:: NONE

gs_threshold

Energy threshold for ground state degeneracy loop up

Type:: real
Default:: 1d-9

hfile

File where to retrieve/store the bath parameters

Type:: character(len=100)
Default:: hamiltonian[.used/restart]

hfmode

Flag to set the form of the Hubbard-Kanamori interaction

T : \(U(n_{\uparrow}-\frac{1}{2})(n_{\downarrow}-\frac{1}{2})\)

F : \(Un_{\uparrow}n_{\downarrow}\)

Type:: logical
Default:: T

hlocfile

File to read the input local H from

Type:: character(len=100)
Default:: inputHLOC.in

jh

Hund’s coupling constant

Type:: real
Bindings:: Language = c, Name = jh
Default:: 0.d0

jp

Coupling constant for the Pair-hopping interaction term

Type:: real
Bindings:: Language = c, Name = jp
Default:: 0.d0

jx

Coupling constant for the spin-eXchange interaction term

Type:: real
Bindings:: Language = c, Name = jx
Default:: 0.d0

jz_basis

Flag to enable the \(J_{z}\) basis in SOC calculations

Type:: logical
Default:: F

jz_max

Flag to enable a maximum value for \(J_{z}\)

Type:: logical
Default:: F

jz_max_value

Maximum value for Jz

Type:: real
Default:: 1000d0

lanc_dim_threshold

Minimal sector dimension for Lanczos diagonalization. Smaller sectors will be solved with Exact Diagonalization provided by Lapack

Type:: integer
Default:: 1024

lanc_method

Flag to select the Lanczos method to be used in the determination of the spectrum.

ARPACK : uses the Arnoldi algorithm

LANCZOS: uses an in-house Lanczos algorithm (limited to zero temperature)

Type:: character(len=12)
Default:: ARPACK

lanc_ncv_add

Offset to add to the size of the block to prevent it to become too small according to \(N_{cv}=\mathrm{lanc\_ncv\_factor} \cdot \mathrm{Neigen} + \mathrm{lanc\_ncv\_add}\)

Type:: integer
Default:: 0

lanc_ncv_factor

Size of the block used in Lanczos-Arpack by multiplying the required Neigen according to \(N_{cv}=\mathrm{lanc\_ncv\_factor} \cdot \mathrm{Neigen} + \mathrm{lanc\_ncv\_add}\)

Type:: integer
Default:: 10

lanc_ngfiter

Number of Lanczos iteration in GF determination. Number of moments.

Type:: integer
Default:: 200

lanc_niter

Max number of Lanczos iterations

Type:: integer
Default:: 512

lanc_nstates_sector

Max number of required eigenvalues per sector

Type:: integer
Default:: 2

lanc_nstates_step

Number of states added at each step for finite-temperature calculations: if the latest state included in thepartition function has a Boltzmann weight higher than cutoff, lanc_nstates_total will be increased by this amount at the next DMFT iteration.

Type:: integer
Default:: 2

lanc_nstates_total

Max number of states contributing to the partition function for finite-temperature calculations.It must be set to 1 for zero-temperature calculations, and to a greater value for finite-temperature calculations.

Type:: integer
Default:: 1

lanc_tolerance

Tolerance for the Lanczos iterations as used in Arpack and plain Lanczos

Type:: real
Default:: 1d-18

lfit

Number of frequencies for bath fitting

Type:: integer
Bindings:: Language = c, Name = lfit
Default:: 1000

lmats

Number of Matsubara frequencies

Type:: integer
Bindings:: Language = c, Name = lmats
Default:: 4096

logfile

Logfile unit

Type:: integer
Attributes:: save
Bindings:: Language = c, Name = logfile
Default:: 6

lpos

Number of points in Probability Distribution Function lattice for phonons

Type:: integer
Bindings:: Language = c, Name = lpos
Default:: 100

lreal

Number of real-axis frequencies

Type:: integer
Bindings:: Language = c, Name = lreal
Default:: 5000

ltau

Number of imaginary time points

Type:: integer
Bindings:: Language = c, Name = ltau
Default:: 1024

nbath

Number of bath sites:

bath_type = normal : number of bath sites per orbital

bath_type = hybrid : total number of bath sites

bath_type = replica/general : number of replicas

Type:: integer
Bindings:: Language = c, Name = nbath
Default:: 6

ncoeff

Multiplier for the ndelta value if xmu and its error are read from a file ( \(\mathrm{ndelta} \rightarrow \mathrm{ndelta} \cdot \mathrm{ncoeff}\) )

Type:: real
Default:: 1d0

ndelta

Initial chemical potential variation for fixed-density calculations

Type:: real
Default:: 1d-1

nerr

Error threshold for fixed-density calculations

Type:: real
Default:: 1d-4

niter

Type:: integer

nloop

Maximum number of DMFT loops

Type:: integer
Bindings:: Language = c, Name = nloop
Default:: 100

norb

Number of impurity orbitals (max 5 )

Type:: integer
Bindings:: Language = c, Name = norb
Default:: 1

normal_complex

Type:: integer
Bindings:: Language = c, Name = normal_complex
Default:: 1

nph

Max number of phonons allowed (cut off)

Type:: integer
Bindings:: Language = c, Name = nph
Default:: 0

nread

Target occupation value for fixed-density calculations. If set to 0.0 the calculation is assumed to be at fixed xmu

Type:: real
Bindings:: Language = c, Name = nread
Default:: 0d0

nspin

If 1, assume \(H_{\downarrow}\) = \(H_{\uparrow}\) . If 2 , the Hamiltonian needs to explicitly include spin-up and spin-down blocks

Type:: integer
Bindings:: Language = c, Name = nspin
Default:: 1

nsuccess

Number of repeated success to fall below convergence threshold

Type:: integer
Bindings:: Language = c, Name = nsuccess
Default:: 1

pair_field

Pair field per orbital (max 15) coupling to s-wave order parameter component which explicitly appears in the impurity Hamiltonian.

Type:: real(15)
Bindings:: Language = c, Name = pair_field
Default:: zero

ph_type

Shape of the e part of the e-ph interaction:

1 = orbital occupation

2 = orbital hybridization

Type:: integer
Default:: 1

print_input_vars

Flag to toggle the printing on the terminal output of a list of input variables and their values

Type:: logical
Default:: T

print_sector_eigenvalues

Flag to toggle the printing of the eigenvalues of each sectors to a file.

Type:: logical
Default:: T

rdm_flag

Flag to activate Reduced Density Matrix evaluation

Type:: logical
Bindings:: Language = c, Name = rdm_flag
Default:: F

sb_field

Value of a symmetry breaking field for magnetic solutions

Type:: real
Bindings:: Language = c, Name = sb_field
Default:: 1d-1

sectorfile

File where to retrieve/store the sectors contributing to the spectrum

Type:: character(len=100)
Default:: sectors[.used/restart]

spin_field_x

Magnetic field per orbital coupling to X-spin component

Type:: real(•)
Attributes:: allocatable
Default:: zero

spin_field_y

Magnetic field per orbital coupling to Y-spin component

Type:: real(•)
Attributes:: allocatable
Default:: zero

spin_field_z

Magnetic field per orbital coupling to Z-spin component

Type:: real(•)
Attributes:: allocatable
Default:: zero

uloc

Values of the local interaction per orbital (max 5 )

Type:: real(5)
Bindings:: Language = c, Name = uloc
Default:: (/( 2d0,i=1,Norb )/)

umatrix_file

File containing the list of two-body operators

Type:: character(len=100)
Default:: umatrix[.used/restart]

ust

Value of the inter-orbital interaction term

Type:: real
Bindings:: Language = c, Name = ust
Default:: 0d0

w0_ph

Phonon frequency

Type:: real
Default:: 0d0

wfin

Maximum value of the real frequency range

Type:: real
Bindings:: Language = c, Name = wfin
Default:: 5d0

wini

Minimum value of the real frequency range

Type:: real
Bindings:: Language = c, Name = wini
Default:: -5d0

xmax

Maximum of the x-range for the local lattice probability distribution function (phonons)

Type:: real
Bindings:: Language = c, Name = xmax
Default:: 3d0

xmin

Minimum of the x-range for the local lattice probability distribution function (phonons)

Type:: real
Bindings:: Language = c, Name = xmin
Default:: -3d0

xmu

Chemical potential. If HFMODE = T, xmu = 0.d0 indicates half-filling condition.

Type:: real
Bindings:: Language = c, Name = xmu
Default:: 0d0

Subroutines and functions

subroutine ed_read_input(inputunit)

This functions reads the input file provided by INPUTunit and sets the global variables accordingly

Parameters:: inputunit [character(len=*)]
Use :: mpi, sf_mpi

subroutine ed_update_input(name, vals)

This functions updates some variables in the input file, namely

exc_field, pair_field, exc_field,

spin_field_x, spin_field_y, and spin_field_z.

Parameters:

name [character(len=*)] – the name of the variable to update
vals (•) [real] – the new value of the variable

subroutine substring_delete(s, sub)

! S_S_DELETE2 recursively removes a substring from a string.

The remainder is left justified and padded with blanks.

The substitution is recursive, so

that, for example, removing all occurrences of “ab” from

“aaaaabbbbbQ” results in “Q”.

Parameters:

Input/output, character ( len = * ) S, the string to be transformed.

Input, character ( len = * ) SUB, the substring to be removed.

Output, integer ( kind = 4 ) IREP, the number of occurrences of

the substring.

Parameters:

s [character(len=*)]
sub [character(len=*)]

subroutine s_chop(s, ilo, ihi)

! S_CHOP “chops out” a portion of a string, and closes up the hole.

Example:

S = ‘Fred is not a jerk!’

call s_chop ( S, 9, 12 )

S = ‘Fred is a jerk! ‘

Parameters:

Input/output, character ( len = * ) S, the string to be transformed.

Input, integer ( kind = 4 ) ILO, IHI, the locations of the first and last

characters to be removed.

Parameters:

s [character(len=*)]
ilo [integer]
ihi [integer]

subroutine print_logo()