FlexibleSUSY
============

FlexibleSUSY provides Mathematica and C++ code to create spectrum
generators for non-minimal supersymmetric models.  It is designed for
generating fast and modular C++ code, allowing for easy modification,
extension and reuse.

Homepage:                https://flexiblesusy.hepforge.org
Mailing list:            flexiblesusy@projects.hepforge.org
Source code repository:  https://github.com/FlexibleSUSY
Bug reports:             https://github.com/FlexibleSUSY/FlexibleSUSY/issues
References:              CPC 190 (2015) 139-172 (arxiv:1406.2319 [hep-ph])


Requirements
============

 * C++ compiler (g++ >= 4.4.7 or clang++ >= 3.1 or icpc >= 12.1)
 * Fortran compiler (gfortran, ifort)
 * Mathematica (version 7.0 or higher)
 * SARAH (version 4.0.4 or higher)    http://sarah.hepforge.org
 * Boost (version 1.37.0 or higher)   http://www.boost.org
 * Eigen 3 (version 3.1 or higher)    http://eigen.tuxfamily.org
 * GNU scientific library             http://www.gnu.org/software/gsl/
 * Lapack / Blas                      http://www.netlib.org/lapack/

Optional:

 * Looptools (version 2.8 or higher)  http://www.feynarts.de/looptools/


Installation of SARAH
=====================

FlexibleSUSY requires SARAH to be installed and to be loadable with
the Needs["SARAH`"] command from inside Mathematica.  We recommend the
following setup:

   $ cd ~/.Mathematica/Applications/
   $ wget https://www.hepforge.org/archive/sarah/SARAH-4.7.0.tar.gz
   $ tar -xf SARAH-4.7.0.tar.gz
   $ ln -s $PWD/SARAH-4.7.0/ SARAH

   $ cd ~/.Mathematica/Kernel/
   $ echo "AppendTo[\$Path, \"$HOME/.Mathematica/Applications/SARAH/\"];" \
        >> init.m

All the above steps can be executed at once with the `install-sarah`
script.  Example:

   $ ./install-sarah

See `./install-sarah --help' for more options.


How to create a model
=====================

0. Before you setup a FlexibleSUSY model, you have to provide a SARAH
   model file.  To make it available in FlexibleSUSY, you can put it
   either into FlexibleSUSY's SARAH model directory

     FlexibleSUSY/sarah/<model>/

   or directly into SARAH's own model directly

     SARAH/Models/<model>/

   Here <model> is the name of your model (e.g. MSSM, NMSSM, etc.).
   Note, that there are already plenty of pre-installed model files
   under SARAH/Models/ that can be used.

1. Setup a FlexibleSUSY model

   $ ./createmodel --name=<model>

   See `./createmodel --help' for more details.  Afterwards there will
   be

   * a model directory models/<model>/
   * a makefile module models/<model>/module.mk
   * a Mathematica start script models/<model>/start.m
   * and a FlexibleSUSY model file models/<model>/FlexibleSUSY.m

   To modify the model details (input parameters, constraints, etc.),
   please edit the FlexibleSUSY model file
   models/<model>/FlexibleSUSY.m .

2. Create the Makefile and register your model

   $ ./configure --with-models=<model>

   Use `./configure --with-models=all' to build all available models.
   See `./configure --help' for more options.

3. Compile

   $ make

   When `make' is executed, Mathematica is called and generates the
   C++ code for the spectrum generator.  All C++ source files are
   written to models/<model>/ .  Afterwards this C++ code will be
   compiled and a user example spectrum generator
   models/<model>/run_<model>.x will be created.


Example
=======

   $ ./createmodel --name=NMSSM
   $ ./configure --with-models=NMSSM
   $ make
   $ ./models/NMSSM/run_NMSSM.x \
     --slha-input-file=model_files/NMSSM/LesHouches.in.NMSSM


Creating the soucre code documentation
======================================

FlexibleSUSY's source code documentation (including the generated
source code files) can be generated with Doxygen in HTML format.  To
generate the documentation please run:

   $ make doc-html

The generated HTML index file can then be found in doc/html/index.html
and can be viewed with any HTML browser, e.g.

   $ firefox doc/html/index.html


Creating only the source code files -- no compilation
=====================================================

If you want to only create the C++ source files for your model, but do
not want to compile the code, you can use the --disable-compile
configure option:

   $ ./configure --with-models=MSSM --disable-compile
   $ make

Here, configure will not check for installed compilers or libraries.
It will only check for Mathematica and SARAH.  The execution of `make'
will stop as soon as all C++ source code files are generated.


Compile only
============

If you want to only compile already created the C++ source files for
your model, you can use the --disable-meta configure option:

   $ ./configure --with-models=MSSM --disable-meta
   $ make

Here, configure will only check for installed compilers or libraries.
It will not check for Mathematica and SARAH.

Warning: Please make sure all C++ source files of your model are
available in the model directory models/<model>/ .  Otherwise the
compilation will fail.


Exporting the generated source code
===================================

The generated C++ source code can be exported to a separate directory,
without the Mathematica meta code.  This exported directory will be a
complete standalone package, with it's own build system.  To export
the code, one has to set the target directory during configuration via
the --with-install-dir= option.  For example

   $ ./configure --with-models=<models> \
     --with-install-dir=/path/to/export/directory

By running

   $ make install-src

the generated C++ source code for all <models> is copied to
/path/to/export/directory , together with the non-model specific
source code from config/ , doc/ , legacy/ , slhaea/ and src/ .
Afterwards, the standalone package can be build via

   $ cd /path/to/export/directory
   $ ./configure
   $ make


Dynamic libraries
=================

If you want to create dynamic libraries (instead of static libraries)
you have to pass all the following options to the ./configure script

   --disable-static-libs
   --with-lib-ext=".so"
   --with-make-lib-cmd="gcc -shared -o"

When using Intel compilers, replace `gcc' by `icc' or `icpc'.

Example:

   $ ./configure --with-models=MSSM,NMSSM \
     --disable-static-libs \
     --with-lib-ext=".so" \
     --with-make-lib-cmd="gcc -shared -o"

Important remark:

The libraries are linked to the executables with _absolute_ paths.
This means that, if you move the package directory to another
location, the executables will no longer work, because the libraries
are now at another place.  To make the executables work again, you
have to rebuild them via

   $ make clean-executables
   $ make allexec


Statically linked executables
=============================

External libraries can be statically linked to the spectrum generator
executables by setting linker specific flags in LDFLAGS.  On some
systems additional libraries have to be linked to the executables in
such cases.  In FlexibleSUSY such additional libraries can be
specified in the variable LDLIBS.

Example (using g++ on Debian Jessie):

   $ ./configure --with-models=CMSSM \
     --with-ldflags="-static" \
     --with-ldlibs="-lquadmath"

This will create a standalone executable which does not depend on
dynamic libraries.


Looptools
=========

It is possible to use Looptools (http://www.feynarts.de/looptools/)
for calculating the loop functions, instead of using Softsusy's loop
functions.  To enable Looptools configure via

   $ ./configure --enable-looptools

To use the Looptools library and header files from a specific
directory configure via

   $ ./configure --enable-looptools \
     --with-looptools-incdir="/path/to/looptools/build/" \
     --with-looptools-libdir="/path/to/looptools/build/"

Note: Looptools 2.8 or higher is required.  Versions <= 2.7 will fail
to build with the following compiler error message (or similar):

   In file included from models/MSSM/MSSM_two_scale_model.cpp:28:0:
   /usr/include/clooptools.h:67:28: error: conflicting declaration ‘typedef struct std::complex<double> Complex’
   In file included from src/utils.h:15:0,
                    from src/rge.h:17,
                    from models/MSSM/MSSM_two_scale_soft_parameters.hpp:24,
                    from models/MSSM/MSSM_two_scale_model.hpp:25,
                    from models/MSSM/MSSM_two_scale_model.cpp:21:
   src/mycomplex.h:17:7: error: ‘class Complex’ has a previous declaration as ‘class Complex’


Plotting spectrum and RG running
================================

The pole mass spectrum and the RG flow can be written to data files
for easy plotting.  In the MSSM for example these data files can be
generated via

   $ ./models/MSSM/run_MSSM.x \
     --slha-input-file=model_files/MSSM/LesHouches.in.MSSM \
     --rgflow-output-file=MSSM_rgflow.dat \
     --spectrum-output-file=MSSM_spectrum.dat

The generated files "MSSM_rgflow.dat" and "MSSM_spectrum.dat" can be
plotted with the gnuplot scripts in the model directory:

   $ gnuplot -persist -e "filename='MSSM_spectrum.dat'" \
       models/MSSM/MSSM_plot_spectrum.gnuplot

   $ gnuplot -persist -e "filename='MSSM_rgflow.dat'" \
       models/MSSM/MSSM_plot_rgflow.gnuplot

The latter is just for illustration and currently plots all DR-bar
parameters regardless of dimension, so the resulting plot is not
particularly informative.  However the user may then adapt this script
to plot any chosen subset of the parameters.


Addons
======

A FlexibleSUSY addon is a program or library, which uses parts of the
FlexibleSUSY libraries or the generated models.  An addon can be
created via

   $ ./createaddon --name=<addon>

where <addon> is the name of the addon.  This script creates the
directory addons/<addon>/ and the corresponding makefile module
addons/<addon>/module.mk .  If an addon has been created with the
above script, the user may edit the makefile module to add his source
files in to the three variables

   LIB@ADDON@_SRC   (list of library source files)
   EXE@ADDON@_SRC   (list of soucre files with a main())
   LIB@ADDON@_HDR   (list of header files)

Example:

   LIB@ADDON@_SRC := $(DIR)/file1.cpp
   EXE@ADDON@_SRC := $(DIR)/run.cpp
   LIB@ADDON@_HDR := $(DIR)/file1.hpp

To configure and compile the addon run

   ./configure --with-addons=<addon>
   make

make compiles all source files and creates the addon library
addons/<addon>/lib<addon>.a (including the object file file1.o from
the above example) and an executable (addons/<addon>/run.x in the
above example).