/*****************************************************************************\
 *  README.txt                                                               *
 *                                                                           *
 *  Created on: Feb 14, 2014                                                 *
 *  Last update: April 1, 2019                                               *
 *      Authors: Ben O'Leary ([email protected])                     *
 *               José Eliel Camargo-Molina ([email protected])        *
 *                                                                           *
 *      This file is part of VevaciousPlusPlus, a program designed to find   *
 *      configurations of vacuum expectation values (VEVs) for the           *
 *      minima of a quantum field theory potential energy function, and to   *
 *      calculate quantum and thermal tunneling out of a given desired       *
 *      symmetry-breaking vacuum if possible. It is a re-write of Vevacious  *
 *      by Ben O'Leary, Florian Staub, José Eliel Camargo Molina, and Werner *
 *      Porod.                                                               *
 *                                                                           *
 *      VevaciousPlusPlus is free software: you can redistribute it and/or   *
 *      modify it under the terms of the GNU General Public License as       *
 *      published by the Free Software Foundation, either version 3 of the   *
 *      License, or (at your option) any later version.                      *
 *                                                                           *
 *      VevaciousPlusPlus is distributed in the hope that it will be         *
 *      useful, but WITHOUT ANY WARRANTY; without even the implied warranty  *
 *       of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU *
 *      General Public License for more details                              *
 *      <http://www.gnu.org/licenses/>.                                      *
 *                                                                           *
\*****************************************************************************/

 Now that the legalese preamble is out of the way, the description of the code
 and how to use it can begin!

 VevaciousPlusPlus is a program written fully in C++ to try to find all the
 minima of a loop-corrected potential and to calculate tunneling out of a
 desired symmetry-breaking minimum if this happens to be a false vacuum. It is
 designed to be used with model files which we recommend be generated by SARAH,
 a Mathematica package by Florian Staub, and utilizes the MINUIT algorithms by
 Fred James, and uses the Eigen C++ library for matrix inversion and eigenvalue
 calculation and the Boost C++ Library. 
 Much of the tunneling code is based on the Python package CosmoTransitions, 
 by Carroll (Max) Wainwright.
 For the Homotopy continuation two codes are automatically downloaded, PHC by
 Jan Verschelde and Hom4PS2 by Tsung-Lin Lee, Tien-Yien Li and Chih-Hsiung Tsai
 
 VevaciousPlusPlus is an implementation of the process of attempting to find
 the minima of a quantum field theory potential with loop and thermal
 corrections, as decided upon by the collaboration of
 José Eliel Camargo-Molina ([email protected]),
 Björn Garbrecht ([email protected]),
 Ben O'Leary ([email protected]),
 Werner Porod ([email protected]), and
 Florian Staub ([email protected]). This README file was written by
 Ben O'Leary and  José Eliel Camargo-Molina.
 
 A manual describing the physics and process of VevaciousPlusPlus will be
 available from http://arxiv.org/abs/????.???? and there will be a quickstart
 guide available from http://vevacious.hepforge.org/ following the appropriate
 link.

The C++ files of VevaciousPlusPlus are:

 <> headers in Vevacious/include/:
 *.hpp

 <> source files in Vevacious/source/:
 *.cpp

 Requirements: 
 <> CMake version 2.8.12 or greater 
 <> Eigen3 libraries version 3.1.0 or greater
 <> Boost libraries version 1.41 or greater 
 <> A C++ compiler with C++11 support 
 
****************************************************
                   Quick Start 
****************************************************

<> From the Vevacious/ directory do 
   > mkdir build
<> From the newly created build/ directory do 
   > cmake ..
<> OPTIONAL: If you want to use PHC instead of the default HOM4PS2 for  
   The homotopy continuation, do
   > make phc_2.4.66
<> Once CMake has finished setting everything up do 
   > make VevaciousPlusPlus
<> Besides making the main executable and library, this will download and compile 
the Minuit2 library, Hom4PS2 and PHC (homotopy continuation codes)
<> Now you can run Vevacious with 
   > VevaciousPlusPlus InputFile.xml 
The executable is in /bin.

****************************************************
    Default models, initialization and input files
****************************************************

Vevacious comes with the following models out of the box. 
There are example SLHA files for each model. 

<> MSSM with stop and stau VEVs 

For using this model run "VevaciousPlusPlus MSSM.xml"

<> MSSM with all sfermion VEVs allowed

For using this model run "VevaciousPlusPlus MSSM_allVEVs.xml"

The model has the possibility to turn any VEVs on/off in 
/Vevacious/ModelFiles/PotentialFunctions/MSSM_All_Sfermion_RealVevs.vin. 
Read the comments therein for details. 

<> Two Higgs doublet model, with loop corrections assuming Type I

For using this model run "VevaciousPlusPlus THDM.xml"


****************************************************
               Advanced settings
****************************************************

Vevacious comes with many settings that can be accessed by changing values 
in three initialization XML files. The default models come with initialization 
files with the most common settings set to their default values. 
** In the following and for clarity the file names are written but they can be
 chosen to be anything you want ** 


The input file structure is as follows: 
                                                                    

                                          --> PotentialFunctionInitialization.xml
                                         |
InputFile.xml --> InitializationFile.xml --> PotentialMinimizerInitialization.xml 
                                         | 
                                          --> TunnelingCalculationInitialization.xml


The only place where you have model dependent settings is in PotentialFunctionInitialization.xml.

The other files contain all the settings which are explained in detail in the comments of 
the default Initialization files included with Vevacious. 

LHA input parameter points are given in InputFile.xml


*****************************************************
              Adding your own models
*****************************************************

Models can be implemented in SARAH and added to Vevacious. This will require you to implement the 
model first in SARAH and within do "MakeVevacious[Version->"++"]". 
Sarah will give two output files a "YOURMODEL.vin" and "ScaleAndBlock.xml". 
The first one is the potential for your model and the second one tells Vevacious 
how to handle the input from LHA files. 
If you want to follow what is done with the default models then 
Put "YOURMODEL.vin" -> /Vevacious/PotentialFunctions
and "ScaleAndBlock.vin" -> /Vevacious/LagrangianParameters

No matter where you place them, you will have to tell Vevacious where they are in your 
chosen PotentialFunctionInitialization.xml file. 

Once you have set everything up, just provide LHA files in the InputFile.xml file.