<commit_before>hubbard
=======

Introduction
------------

hubbard can currently perform full configuration interaction (FCI) calculations
of the Hubbard model using either the real space or momentum space formulation.
Full and Lanczos diagonalisation methods are implemented using external
libraries (lapack/scalapack and TRLan respectively) and can be performed in
both serial and parallel.  Lanczos diagonalisation can be performed with or
without precomputing the Hamiltonian matrix.

The target is to implement an efficient full configuration interaction quantum
monte carlo (FCIQMC) algorithm for the Hubbard model.

Directory structure
--------------------

./
    Root directory of the program.
bin/
  Directory containing the compiled program, hubbard.x.  Created during
  compilation.
config/
  Directory containing the configuration input files used to generate makefiles.
dest/
  Directory containing the compiled object files and dependency files.  Created
  during compilation.
documentation/
   Directory containing documentation on the hubbard program.  The
   documentation is written in reStructured Text and can be converted
   into a wide range of output formats.
src/
    Directory containing the main source files.
lib/
   Directory containing "library" source files.  These a procedures which are
   not specific to the hubbard code but are generally useful.  Some are written
   by the authors, some are freely available (as noted in the source files).
tools/
    Directory containing scripts and tools for compiling, running and analysing
    output from hubbard.

Compilation
-----------

hubbard requires the lapack (http://www.netlib.org/lapack/), blas
(http://www.netlib.org/blas) and TRLan
(http://crd.lbl.gov/~kewu/ps/trlan_.html) libaries.

After meeting these requirements, produce a makefile by running the mkconfig.py
(residing in the tools subdirectory) script in the root directory:

.. code-block:: bash

    tools/mkconfig.py config

where config is one of the platforms available.  The config name is simply the
name of the relevant file residing in the config/ directory.  Various configurations
are provided and it is simple to adapt one to the local environment (e.g. changing
compiler or library paths).

Run

.. code-block:: bash

    tools/mkconfig.py --help

to see the options available, including inspecting available platforms.
A platform is defined using a simple ini file, consisting of three sections:
main, opt and dbg.  For instance::

    [main]
    cc = gfortran
    ld = gfortran
    libs = -llapack -lblas

    [opt]
    cflags = -O3

    [dbg]
    cflags = -g

Any option not specified in the 'opt' and 'dbg' sections is inherited from the
'main' section.  The settings in 'opt' are used by default; the debug options
can be selected by passing the -g option to mkconfig.py.

Available options are:

fc
    Set the fortran compiler.
fflags
    Set flags to be passed to the fortran compiler during compilation.
cppdefs
    Set definitions to be used in the C pre-processing step.
cppflags
    Set flags to be used in the C pre-processing step.
ld
    Set the linker program.
ldflags
    Set flags to be passed to the linker during linking of the compiled objects.
libs
    Set libraries to be used during the linking step.
module_flag
    Set the compiler-specific flag which specifies the directory where module
    (.mod) files are placed when created and where they should be searched for.

To compile the code run 

.. code-block:: bash

    make
    
hubbard.x uses the sfmakedepend script (http://www.arsc.edu/~kate/Perl/,
supplied in tools/) by <NAME> to generate the dependencies.  These are
generated automatically when make is run if the dependency files don't exist.

The executable, hubbard.x, is placed in the bin subdirectory.  Note that this is
actually a symbolic link: a unique executable is produced for each platform and
optimisation level and hubbard.x merely points to the most recently compiled executable
for convenience.  This makes testing against multiple platforms particularly easy.

There are various goals in the makefile.  Run

.. code-block:: bash

    make help

to see the available goals.

Usage
-----

.. code-block:: bash

    hubbard.x [input_filename]

If no input filename is provided then the input options are read from STDIN.
Note that this feature is not guaranteed to work when run in parallel!

Output is sent to STDOUT and can be redirected as desired.

hubbard.x only performs i/o operations on the root processor when run on
multiple processors.

Input options
-------------

Input options are case insensitive and can be given in any order.  A new line
is required for each keyword.  Keywords are given in **bold** text.  Items
following a keyword that are in *italics* are given as input values to that
keyword.  Optional arguments are enclosed in square brackets.

With the exception of the **lattice** keyword, all values associated with
a specific keyword should appear on the same line as that keyword.

Items enclosed in parentheses are treated as comments.  All input options are
echoed in the output and so comments allow for notes on the calculation to be
made in the input which are then automatically included in the output.
<commit_msg>Document cpp options.<commit_after>hubbard
=======

Introduction
------------

hubbard can currently perform full configuration interaction (FCI) calculations
of the Hubbard model using either the real space or momentum space formulation.
Full and Lanczos diagonalisation methods are implemented using external
libraries (lapack/scalapack and TRLan respectively) and can be performed in
both serial and parallel.  Lanczos diagonalisation can be performed with or
without precomputing the Hamiltonian matrix.

The target is to implement an efficient full configuration interaction quantum
monte carlo (FCIQMC) algorithm for the Hubbard model.

Directory structure
--------------------

./
    Root directory of the program.
bin/
  Directory containing the compiled program, hubbard.x.  Created during
  compilation.
config/
  Directory containing the configuration input files used to generate makefiles.
dest/
  Directory containing the compiled object files and dependency files.  Created
  during compilation.
documentation/
   Directory containing documentation on the hubbard program.  The
   documentation is written in reStructured Text and can be converted
   into a wide range of output formats.
src/
    Directory containing the main source files.
lib/
   Directory containing "library" source files.  These a procedures which are
   not specific to the hubbard code but are generally useful.  Some are written
   by the authors, some are freely available (as noted in the source files).
tools/
    Directory containing scripts and tools for compiling, running and analysing
    output from hubbard.

Compilation
-----------

hubbard requires the lapack (http://www.netlib.org/lapack/), blas
(http://www.netlib.org/blas) and TRLan
(http://crd.lbl.gov/~kewu/ps/trlan_.html) libaries.

After meeting these requirements, produce a makefile by running the mkconfig.py
(residing in the tools subdirectory) script in the root directory:

.. code-block:: bash

    tools/mkconfig.py config

where config is one of the platforms available.  The config name is simply the
name of the relevant file residing in the config/ directory.  Various configurations
are provided and it is simple to adapt one to the local environment (e.g. changing
compiler or library paths).

Run

.. code-block:: bash

    tools/mkconfig.py --help

to see the options available, including inspecting available platforms.
A platform is defined using a simple ini file, consisting of three sections:
main, opt and dbg.  For instance::

    [main]
    cc = gfortran
    ld = gfortran
    libs = -llapack -lblas

    [opt]
    cflags = -O3

    [dbg]
    cflags = -g

Any option not specified in the 'opt' and 'dbg' sections is inherited from the
'main' section.  The settings in 'opt' are used by default; the debug options
can be selected by passing the -g option to mkconfig.py.

Available options are:

fc
    Set the fortran compiler.
fflags
    Set flags to be passed to the fortran compiler during compilation.
cppdefs
    Set definitions to be used in the C pre-processing step.
cppflags
    Set flags to be used in the C pre-processing step.
ld
    Set the linker program.
ldflags
    Set flags to be passed to the linker during linking of the compiled objects.
libs
    Set libraries to be used during the linking step.
module_flag
    Set the compiler-specific flag which specifies the directory where module
    (.mod) files are placed when created and where they should be searched for.

To compile the code run 

.. code-block:: bash

    make
    
hubbard.x uses the sfmakedepend script (http://www.arsc.edu/~kate/Perl/,
supplied in tools/) by <NAME> to generate the dependencies.  These are
generated automatically when make is run if the dependency files don't exist.

The executable, hubbard.x, is placed in the bin subdirectory.  Note that this is
actually a symbolic link: a unique executable is produced for each platform and
optimisation level and hubbard.x merely points to the most recently compiled executable
for convenience.  This makes testing against multiple platforms particularly easy.

There are various goals in the makefile.  Run

.. code-block:: bash

    make help

to see the available goals.

Compile-time settings
^^^^^^^^^^^^^^^^^^^^^

The behaviour of the program can be changed in various ways by some choices at
compile-time by using C pre-processing.  These choices largely influence the
speed, memory usage, inclusion of parallel code and workarounds for certain
compilers.

The pre-processing options which accept a value are set by::

    -DOPTION=VAL

which defines the pre-processing definition OPTION to have value VAL.
Similarly, the options which just need to be defined to be used are set by::

    -DOPTION

These should be added to the cppflags or cppdefs lines in the configuration
files or in the Makefile, as desired.

DET_SIZE
    Default: 32.

    hubbard uses bit strings to store Slater determinants, where each bit
    corresponds to an occupied spin-orbital if the bit is set and an unoccupied
    spin orbital otherwise.  As fortran does not include a type for a single
    bit, integers are used.  Note that this does lead to some wasted memory when
    the number of spin-orbitals is not a multiple of the size of the integer used.
    An array of integers is used to store the determinant bit string if
    a single integer is not sufficient.

    This option sets the integer length to be used.  Allowed values are 8, 16,
    32 and 64, corresponding to using 8-bit, 16-bit, 32-bit and 64-bit integers
    respectively.  Note that using 8-bit or 16-bit integers is much slower on
    modern platforms.  The recommended value is 32 unless more than 32 basis
    functions are used, in which case 64 is also a good choice.
DSFMT_MEXP 
    Default: 19937.

    hubbard uses the dSFMT random number generator (RNG).  It is based on
    a Mersenne Twister algorithm, is extremely fast and produces high quality
    random numbers.  See http://www.math.sci.hiroshima-u.ac.jp/~m-mat/MT/SFMT/index.html 
    for more details. 

    DSFMT_EXP sets the exponent of the period of the RNG.  Allowed values are
    521, 1279, 2203, 4253, 11213, 19937, 44497, 86243,
    132049 and 216091 and lead to, for example, random numbers with a period of
    a Mersenne Prime such as 2^512-1.
NAGF95  
    Default: not defined.

    If defined then code specific to, and necessary for compilation using, the
    NAG Fortran compiler is included.
PGI  
    Default: not defined.

    If defined then code required to work around a bug in the PGI compiler (only 
    version 10.1 was tested) is included.  This is required for successful
    compilation if DET_SIZE is set to be 8 or 16.
PARALLEL  
    Default: not defined.

    Include source code required for running in parallel.
SINGLE_PRECISION  
    Default: not defined.

    Set the precision (where possible) to be single precision.  The default is
    double precision.  This is faster, but (of course) can change results
    significantly.  Use with care.

Usage
-----

.. code-block:: bash

    hubbard.x [input_filename]

If no input filename is provided then the input options are read from STDIN.
Note that this feature is not guaranteed to work when run in parallel!

Output is sent to STDOUT and can be redirected as desired.

hubbard.x only performs i/o operations on the root processor when run on
multiple processors.

Input options
-------------

Input options are case insensitive and can be given in any order.  A new line
is required for each keyword.  Keywords are given in **bold** text.  Items
following a keyword that are in *italics* are given as input values to that
keyword.  Optional arguments are enclosed in square brackets.

With the exception of the **lattice** keyword, all values associated with
a specific keyword should appear on the same line as that keyword.

Items enclosed in parentheses are treated as comments.  All input options are
echoed in the output and so comments allow for notes on the calculation to be
made in the input which are then automatically included in the output.

{'fraction_non_alphanumeric': 0.05405405405405406, 'fraction_numerical': 0.006887774200793591, 'mean_word_length': 3.5097906819716407, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 0, 'lorem ipsum': 0, 'www.': 7, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '7428345', 'n_tokens_mistral': 3595, 'n_tokens_neox': 3350, 'n_words': 1900}