o-----------------------------------------------------------------------------o
 |
 | Generalized Truncated Power Series Algebra
 |
 | Methodical Accelerator Design - Copyright (c) 2016+
 | Support: http://cern.ch/mad  - mad at cern.ch
 | Authors: L. Deniau, laurent.deniau at cern.ch
 | Contrib: -
 |
 o-----------------------------------------------------------------------------o
 | You can redistribute this file and/or modify it under the terms of the GNU
 | General Public License GPLv3 (or later), as published by the Free Software
 | Foundation. This file is distributed in the hope that it will be useful, but
 | WITHOUT ANY WARRANTY OF ANY KIND. See http://gnu.org/licenses for details.
 o-----------------------------------------------------------------------------o

This README file is about how to compile the GTPSA as a standalone library and
use it from C (c99) or Fortran (f2003).

Build:
------

From the MAD-NG repository
http://github.com/MethodicalAcceleratorDesign/MAD

# go to source directory
cd mad/src

# copy all core files
mkdir -p path-to-dir/mygtpsa
cp -a mad_*.[hc] mad_*.tc sse libgtpsa path-to-dir/mygtpsa
cd path-to-dir/mygtpsa

# remove files not needed
rm mad_main.c mad_fft.c mad_nlopt.[hc]

# add files needed to replace MAD core dependencies
cp libgtpsa/mad_*.[hc] .

# compile all C files to build the archive
# (remove -f options after -fPIC in case of trouble)
gcc -std=c99 -W -Wall -Wextra -pedantic -O3 -fPIC -ffast-math -ftree-vectorize -flto \
    -I. -c *.c sse/*.c
ar -ruv libgtpsa.a *.o

Dependencies:
-------------

The functions mad_tpsa_minv, mad_tpsa_pminv, mad_ctpsa_minv, and mad_ctpsa_pminv
requires LAPACK 3.2 or greater to be available and linked with (i.e. -llapack).

Examples:
---------

Examples are in the subdirectory src/libgtpsa/*_ex*.c.

# go to down to examples in libgtpsa
cd libgtpsa

# to compile a standalone example (e.g. ex1), lapack is not mandatory for ex1
gcc -std=c99 -W -Wall -Wextra -pedantic -O3 -fPIC -ffast-math -ftree-vectorize -flto \
    -I.. -L.. gtpsa_ex1.c -o gtpsa_ex1 -lgtpsa

# to compile all the examples, lapack is not mandatory for examples
for i in `seq 0 8` ; do \
  echo ">>> compiling C example $i <<<" ; \
  gcc -std=c99 -W -Wall -Wextra -pedantic -O3 -fPIC -ffast-math -ftree-vectorize -flto \
      -I.. -L.. gtpsa_ex$i.c -o gtpsa_ex$i -lgtpsa ; \
done

# to run all the examples
for i in `seq 0 8` ; do \
  echo ">>> running C example $i <<<" ; \
  ./gtpsa_ex$i ; \
done

Fortran:
--------

The library comes with a Fortran 2003 (ISO C BINDING) interface to the C modules
for mono(mials), desc(riptors), tpsa and ctpsa, and some C files helpers in the
file gtpsa.f90. Examples in C have been translated to fortran in the
subdirectory src/libgtpsa/*_ex*.f90.

# go to down to examples in libgtpsa
cd libgtpsa

# to compile a standalone example (e.g. ex1), you may need LAPACK installed
gfortran -W -Wall -Wextra -pedantic -std=f2018 \
         -L.. gtpsa.f90 gtpsa_ex1.f90 -o gtpsa_ex1_f -lgtpsa

# to compile all the examples
for i in `seq 0 8` ; do \
  echo ">>> compiling fortran example $i <<<" ; \
  gfortran -W -Wall -Wextra -pedantic -std=f2018 \
           -L.. gtpsa.f90 gtpsa_ex$i.f90 -o gtpsa_ex${i}_f -lgtpsa ; \
done

# to run all the examples
for i in `seq 0 8` ; do \
  echo ">>> running fortan example $i <<<" ; \
  ./gtpsa_ex${i}_f ; \
done

Information:
------------

To know the functions provided by the library look at the header files:

mad_mono.h       API for GTPSA monomials
mad_desc.h       API for GTPSA descriptors
mad_tpsa.h       API for real    GTPSA
mad_ctpsa.h      API for complex GTPSA

or for fortran to interfaces in file:

gtpsa.f90        API for GTPSA monomials, descriptors, real and complex

The library is entirely written in C with some optimised functions for Intel
compliant CPUs in the sse subdirectory, based on Intel intrinsics available with
most mainstream C compilers. Files with extension .tc are C templates included
by other C files. The ctpsa are built from the tpsa with some macros, and use
the same code (template-like code generation).

Debugging:
----------

If you suspect a bug in the GTPSA, you can activate various levels of debugging
and tracing from the library. Setup DEBUG value in mad_desc_impl.h to a positive
integer value. Level 1 will check the validity (integrity) of the GTPSA on entry
and exit of each function. Level 2 will also output the name of the function on
entry (->) and exit (<-). Level 3 will display intermediate information during
the construction of the descriptors. Descriptors integrity are always checked
after building, and any error or inconsistencies are reported immediately. Hence
level 3 is more about tracing a crash during the construction than for errors.

Support:
--------

You can send questions about the GTPSA to laurent dot deniau at cern dot ch.