******************************** Welcome to SMH v1.0 ******************************** Copyright (C) 2014 S.P. Martin and D.G. Robertson This program 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 2 of the License, or (at your option) any later version. See the file LICENSE.txt for further details. Contents of this file: I. Overview II. Building SMH III. Using SMH IV. The SMH API ************************************************************************ I. Overview ************************************************************************ SMH is a library of utilities for calculations involving the Higgs sector of the Standard Model. It implements the relation between the Higgs boson pole mass Mh and the dimensionless Higgs self-coupling lambda and the other Standard Model parameters, to full 2-loop order with leading 3-loop corrections. Either of Mh or lambda can be taken as an input, and the other is computed as an output. SMH also contains utilities for minimizing the effective potential to determine the relation between the Higgs vacuum expectation value and the Lagrangian mass squared parameter, and for renormalization group running of the Standard Model parameters. The code is written in C, and may be linked from C or C++. SMH requires the TSIL library of utilities for the numerical calculation of dimensionally regularized two-loop self-energy integrals. Authors: S.P. Martin [spmartin AT niu.edu] Department of Physics Northern Illinois University DeKalb, IL 60115 USA D.G. Robertson [drobertson AT otterbein.edu] Department of Physics Otterbein University Westerville, OH 43081 USA To cite this program, please reference the paper (referred to in this document as [MR14]): [MR14] "Higgs boson mass in the Standard Model at two-loop order and beyond", by S.P. Martin and D.G. Robertson, [arXiv:1407.nnnn]. It would be nice to also cite the following papers that contain important 2-loop integral results directly used in SMH for the Higgs mass calculation: [MR05] "TSIL: a program for the calculation of two-loop self-energy integrals", by S.P. Martin and D.G. Robertson, Comp. Phys. Comm. 174 (2006) 133, [hep-ph/0501132]. [SPM03] "Evaluation of two loop selfenergy basis integrals using differential equations", by S.P. Martin Phys. Rev. D 68, 075002 (2003) [hep-ph/0307101]. Also, the following papers contain results directly used in the Standard Model effective potential minimization routines: [FJJ92] "The Standard model effective potential at two loops," by C. Ford, I. Jack and D.R.T. Jones, Nucl. Phys. B387, 373 (1992) [Erratum-ibid.\ B {\bf 504}, 551 (1997)], [hep-ph/0111190] [SPM13] "Three-loop Standard Model effective potential at leading order in strong and top Yukawa couplings," by S.P. Martin, Phys. Rev. D 89, 013003 (2014), arXiv:1310.7553 [hep-ph]. [SPM14] "Taming the Goldstone contributions to the effective potential," by S.P. Martin, arXiv:1406.2355 [hep-ph]. The 3-loop renormalization group running routines in SMH use results found in [FJJ92] above, and refs. [27-30] and [38-39] listed in [MR14]. SMH is available from: http://www.niu.edu/spmartin/SMH http://faculty.otterbein.edu/drobertson/SMH Version number: 1.0 ************************************************************************ II. Building SMH ************************************************************************ SMH can be compiled on any system that supports the GNU Compiler Collection (gcc), the Intel C compiler (icc), or a similar C compiler with support for complex mathematics. You will first need to build the TSIL library, available from either of: http://www.niu.edu/spmartin/TSIL http://faculty.otterbein.edu/drobertson/TSIL Full documentation for compiling TSIL can be found in the enclosed documentation and in the paper [MR05] mentioned above. As part of the TSIL build, you will choose a size for the basic floating point datatypes. This choice is controlled by a flag set in the Makefile: -DTSIL_SIZE_ where may be LONG or DOUBLE: LONG Basic floating point type is long double DOUBLE Basic floating point type is double Simply uncomment the line for the type you wish. (If neither flag is given, LONG is selected.) LONG is strongly recommended on systems where it is available, as this gives the most accurate results and is not significantly slower on most systems. It is important that SMH be compiled with the same data types as TSIL. Simply choose the same size parameter in the SMH Makefile that you used for TSIL. You can also adjust the compiler and optimization flags to suit your preferences. However, differing levels of optimization on SMH will have only a very modest effect on run times, since most of the computational time is spent in TSIL evaluations. SMH is currently known to compile with gcc (under Linux or Mac OS X) and icc, and should compile fine on any system where TSIL can be built. Other C compilers should work provided that complex mathematics is supported, but in this case you will need to explicitly set the compiler name and optimization flags. If you succeed in building SMH on a new platform, the authors would be grateful to know it, and to learn of any special measures that were needed to compile it. Once these choices have been made, simply type make to build the library, along with the associated test and sample programs. Congratulations, SMH is ready for action! The end product intended for the user consists of the files: libsmh.a The static SMH archive (will be placed in SMH_LIBDIR upon "make install") smhiggs.h The SMH header file, must be included in any user code that uses SMH (will be placed in SMH_INCDIR upon "make install") smh.tst Test program (see below for details) calc_Mh Executables for performing standard calc_lambda tasks; see below for details. calc_vev calc_m2 calc_rgrun fig_vev_vs_Q Executables that generate the data for figs. fig_m2_vs_Q 4.1, 4.2, 4.3, 4.4, and 4.5, in [MR14]. fig_Mh_vs_Q fig_lambda_vs_Q It is strongly recommended that you run the test program after compiling SMH, to insure that correct results are being obtained. The program smh.tst computes a variety of results given a standard benchmark set of parameter values, and compares them to expected results. ************************************************************************ III. Using SMH ************************************************************************ To use SMH functions in your code, you must: 1. Include the header file smhiggs.h in any source file that makes use of SMH functions, e.g., by adding the line #include "smhiggs.h" This is appropriate if the file smhiggs.h is located in the directory where the code is being compiled; if it has been placed in a standard location such as /usr/include, then #include would work. If it is a nonstandard directory , the compiler option -I will generically be necessary. See the compiler man pages on your system for further details. Note that smhiggs.h itself #includes tsil.h, so there is no need to do this separately. #including smhiggs.h will define for you a set of global variables that represent the couplings of the standard model. These variable names are prefixed by SMH_ so that they should not collide with other objects in users' code. These are: SMH_Q; MSbar renormalization scale SMH_g3; SU(3) gauge coupling SMH_gp; U(1)_Y gauge coupling SMH_g; SU(2) gauge coupling SMH_yt; Top Yukawa coupling SMH_lambda; Higgs self coupling SMH_m2; Higgs lagrangian mass^2 parameter (should be negative) SMH_v; Higgs VEV All of these are real parameters of type TSIL_REAL. Typical tasks will use most of these parameters as inputs. Users may set their values freely, and SMH functions use them in their computations. 2. Link to the SMH, TSIL, and C math libraries at the end of the compilation process. This is accomplished via the (linker) flag -lsmh -ltsil -lm in that order. (See examples in the SMH Makefile.) If libsmh.a and/or libtsil.a is not in a standard location (including the case where they are in the current directory), you will generally need to add the flag -L where is the directory in which libtsil.a may be found. If this is the current directory, then -L. may be used. Again, consult the compiler man pages for complete details on making user libraries available to the linker. Complete details regarding the SMH functions are given in section IV of this document. In the rest of this section we will describe the operation of the programs provided with the distribution. These can also serve as potentially useful examples of using SMH. In addition to the test program smh.tst, there are five programs that implement basic SMH computations, and four that generate the data plotted in figs. 4.1, 4.2, 4.3, 4.4, and 4.5 of [MR14]. smh.tst (source file smhtest.c) ------------------------------- This is a basic test of SMH, comparing results for Mh, lambda, m2, and vev at two different renormalization scales to benchmark data. The second scale is reached by RG running within SMH, so this includes a test of that functionality as well as the basic calculations. Compile as, e.g., gcc -DTSIL_SIZE_LONG -o smh.tst smhtest.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes), and run as ./smh.tst The computed and expected values will be printed, along with a pass/fail verdict. SMH passes the test if all computed values agree with the expected ones to a part in 10^8 (see parameter TOL in smhtest.c). Should SMH fail this test, it is very likely that the TSIL build is at fault, or that different datatypes were used in SMH and TSIL. calc_Mh (source file: calc_Mh.c) -------------------------------- Implements an SMH calculation of Mh. It takes input values of lambda v yt g3 g gp Q [loops] (as command line arguments, in that order) and prints the value of Mh. The computation uses equations (2.43), (2.46)-(2.48), and (3.2)-(3.4) of [MR14]. The argument loops is optional, with allowed values: 0 tree level 1 1-loop level 1.5 1-loop plus 2-loop QCD 2 2-loop level 2.5 2-loop plus leading 3-loop QCD 3 2-loop plus leading 3-loop If loops is omitted, the default value is 3. Dimensionful quantities are in appropriate powers of GeV. General and timing information for the computation are also printed. Compile as, e.g., gcc -DTSIL_SIZE_LONG -o calc_Mh calc_Mh.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes) and run as, e.g., ./calc_Mh 0.127 247.0 0.936 1.167 0.648 0.358 173.1 or ./calc_Mh 0.127 247.0 0.936 1.167 0.648 0.358 173.1 2.5 calc_lambda (source file: calc_lambda.c) ---------------------------------------- Implements an SMH calculation of the Higgs self coupling lambda given a specified Higgs pole mass Mh. It takes input values of Mh v yt g3 g gp Q [loops] (as command line arguments, in that order) and prints the value of lambda. The computation uses equations (2.43), (2.46)-(2.48), and (3.2)-(3.4) of [MR14]. The argument loops is optional, with allowed values: 0 tree level 1 1-loop level 1.5 1-loop plus 2-loop QCD 2 2-loop level 2.5 2-loop plus leading 3-loop QCD 3 2-loop plus leading 3-loop If loops is omitted, the default value is 3. Dimensionful quantities are in appropriate powers of GeV. General and timing information for the computation are also printed. Compile as, e.g., gcc -DTSIL_SIZE_LONG -o calc_lambda calc_lambda.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes) and run as, e.g., ./calc_lambda 125.6 247.0 0.936 1.167 0.648 0.358 173.1 or ./calc_lambda 125.6 247.0 0.936 1.167 0.648 0.358 173.1 2.5 calc_vev (source file: calc_vev.c) ---------------------------------- Implements an SMH calculation of the Higgs vev, obtained by minimizing the Landau gauge effective potential, after resummation of Goldstone boson contributions, at full 2-loop order with leading 3-loop contributions (by default). The computation uses equations (4.18)-(4.21) of [SPM14]. It takes 7 or 8 command-line inputs: m2 lambda yt g3 g gp Q [loops] (in that order) and prints the value of the vev. The argument loops is the loop order of the calculation, and is optional. Permissible values are 0,1,2,3. If loops is omitted, the default value is 3. Dimensionful quantities are in appropriate powers of GeV. Compile as, e.g. gcc -DTSIL_SIZE_LONG -o calc_vev calc_vev.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes) and run as, e.g., ./calc_vev -8716.09 0.127 0.936 1.167 0.648 0.358 173.1 for the result with full 2-loop and leading 3-loop contributions, or ./calc_vev -8716.09 0.127 0.936 1.167 0.648 0.358 173.1 2 for the result with only full 2-loop contributions. calc_m2 (source file: calc_m2.c) -------------------------------- Implements an SMH calculation of the Higgs lagrangian squared mass parameter, obtained by minimizing the Landau gauge effective potential, after resummation of Goldstone boson contributions, at full 2-loop order with leading 3-loop contributions (by default). The computation uses equations (4.18)-(4.21) of [SPM14]. It takes 7 or 8 command-line inputs: vev lambda yt g3 g gp Q [loops] (in that order) and prints the value of m2. The argument loops is the loop order of the calculation, and is optional. Permissible values are 0,1,2,3. If loops is omitted, the default value is 3. Dimensionful quantities are in appropriate powers of GeV. General and timing information for the computation are also printed. Compile as, e.g. gcc -DTSIL_SIZE_LONG -o calc_m2 calc_m2.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes) and run as, e.g., ./calc_m2 247.0 0.12711 0.936 1.167 0.648 0.358 173.1 for the result with full 2-loop and leading 3-loop contributions, or ./calc_m2 247.0 0.12711 0.936 1.167 0.648 0.358 173.1 2 for the result with only full 2-loop contributions. rgrun (source file: calc_rgrun.c) --------------------------------- Implements renormalization group running of all standard model parameters from one specified scale to another. It takes 9 or 10 command line inputs lambda yt g3 g gp vev m2 Qinitial Qfinal [loops] (in that order) and prints the values of lambda, yt, g3, g, gp, v, and m2 at the scale Qfinal. The last input loops is the loop order of the RG running, and is optional. Allowed values for loops are 1,2,3. By default, loops = 3, and full 3-loop beta functions are used. General and timing information for the computation are also printed. Compile as, e.g. gcc -DTSIL_SIZE_LONG -o rgrun calc_rgrun.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes) and run as, e.g., ./rgrun 0.127 0.936 1.167 0.648 0.358 247. -8716.09 173.1 250.0 for full 3-loop running, or ./rgrun 0.127 0.936 1.167 0.648 0.358 247. -8716.09 173.1 250.0 2 for 2-loop running. fig_Mh_vs_Q ----------- Produces the data shown in Figures 4.3 and 4.4 of [MR14]. This consists of Higgs pole mass vs. MSbar renormalization scale data including tree, 1-loop, 1-loop plus 2-loop QCD, full 2-loop, and 2-loop plus leading 3-loop QCD and non-QCD corrections. Compile as: gcc -DTSIL_SIZE_LONG -o fig_Mh_vs_Q fig_Mh_vs_Q.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes), and run as ./fig_Mh_vs_Q The data is output in the file "FIG_Mh_vs_Q.dat" in 7 columns, respectively: Q, Mh(0), Mh(1), Mh(1.5), Mh(2), Mh(2.5), and Mh(3), where the number in parentheses is the loop order. fig_lambda_vs_Q --------------- Produces the data shown in Figure 4.5 of [MR14]. This consists of Higgs self coupling vs. MSbar renormalization scale data including the ratio of lambda calculated from a given Higgs pole mass and the value obtained by renormalization group running from the benchmark point. Compile as: gcc -DTSIL_SIZE_LONG -o fig_lambda_vs_Q fig_lambda_vs_Q.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes), and run as ./fig_lambda_vs_Q The data is output in the file "FIG_lambda_vs_Q.dat" in 3 columns, respectively: Q, lambda(3), and lambda(3)/lambda(run), where lambda(3) is the value obtained at Q from the Higgs pole mass at leading 3-loop order, and lambda(run) is obtained by directly running the input value of lambda to the scale Q. fig_m2_vs_Q ----------- Produces the data shown in Figure 4.2 of [MR14]. This consists of Higgs lagrangian mass^2 parameter vs. MSbar renormalization scale data, determined by minimization of the scalar effective potential. Compile as: gcc -DTSIL_SIZE_LONG -o fig_m2_vs_Q fig_m2_vs_Q.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes), and run as ./fig_m2_vs_Q The data is output in the file "FIG_m2_vs_Q.dat" in 5 columns, respectively: Q, sqrt(-m2(2)), sqrt(-m2(3)), m2(2)/m2(run), m2(3)/m2(run) where m2(n) is the value of m2 obtained by requiring the effective potential to be minimized at Q at n-loop order, and m2(run) is obtained by directly running the input value of m2 to the scale Q using 3-loop RG equations. fig_vev_vs_Q ------------ Produces the data shown in Figure 4.1 of [MR14]. This consists of scalar field VEV vs. MSbar renormalization scale data, determined by minimization of the scalar effective potential. Compile as: gcc -DTSIL_SIZE_LONG -o fig_vev_vs_Q fig_vev_vs_Q.c -L. -lsmh -ltsil -lm (assuming libsmh.a and libtsil.a are in the current directory, and these were compiled using long double floating point data sizes), and run as ./fig_vev_vs_Q The data is output in the file "FIG_vev_vs_Q.dat" in 5 columns, respectively: Q, v(2), v(3), v(2)/v(run), v(3)/v(run) where v(n) is the value of v obtained by minimizing the effective potential at n-loop order at the scale Q, and v(run) is obtained by directly running the input value of v to the scale Q using 3-loop RG equations. ************************************************************************ IV. The SMH Application Programmer Interface ************************************************************************ In this section we define the signatures of all SMH functions, and describe their operation. SMH function names are all preceded by SMH_ to avoid collisions with user defined functions and variables. Renormalization Group Running ============================= int SMH_RGrun (TSIL_REAL Qfinal, int loopOrder) Runs the current model parameters from the current MSbar scale SMH_Q to the specified Qfinal at loopOrder loops. This is accomplished by numerical integration of the renormalization group equations using a 6-stage, 5th-order embedded Runge-Kutta scheme with coefficients given by Cash and Karp, as described in [MR05]. The loop order can be 1,2, or 3. The return value is a status code that is currently deprecated. Higgs Mass Calculations ======================= TSIL_REAL SMH_Find_Mh (float loopOrder); Returns the Higgs pole mass at loopOrder order, computed from the current model parameters. Allowed values for loopOrder are: 0 tree level 1 1-loop level 1.5 1-loop plus 2-loop QCD corrections 2 full 2-loop level 2.5 2-loop plus leading 3-loop QCD corrections 3 2-loop plus all leading 3-loop corrections The calculation proceeds by iteration of eqs. (2.43), (2.46)-(2.48), and (3.2)-(3.4) in [MR14]. For the coefficients needed in eq. (2.48), see the ancillary file "coefficients.txt". --------------------------------------------------------------------- TSIL_REAL SMH_Find_lambda (TSIL_REAL Mh, float loopOrder); Given a value for the Higgs pole mass Mh, returns the Higgs scalar self coupling computed at loopOrder order from the current model parameters. Allowed values for loopOrder are as above. Note that the variable SMH_lambda is *not* set by this routine; use, e.g., SMH_lambda = SMH_Find_lambda (Mh, loopOrder); to achieve this. The calculation proceeds by iteration of eqs. (2.43), (2.46)-(2.48), and (3.2)-(3.4) in [MR14]. For the coefficients needed in eq. (2.48), see the ancillary file "coefficients.txt". Effective Potential Minimization Functions ========================================== TSIL_REAL SMH_Veff (int loopOrder); Returns the value of the scalar effective potential evaluated at order loopOrder. This currently implements the full 2-loop effective potential as found in [FJJ92], with the leading 3-loop corrections found in [SPM13]. Unlike the other effective potential functions described below, it does *not* include the effects of Goldstone boson resummation. --------------------------------------------------------------------- TSIL_REAL SMH_Find_vev (int loopOrder); Determines the Higgs vacuum expectation value, obtained by minimizing the Landau gauge effective potential, after resummation of Goldstone boson contributions, with up to full 2-loop order with leading 3-loop contributions. The computation uses equations (4.18)-(4.21) of [SPM14]. Note that the variable SMH_v is *not* set by this routine; use, e.g., SMH_v = SMH_Find_vev (loopOrder); to achieve this. --------------------------------------------------------------------- TSIL_REAL SMH_Find_m2 (int loopOrder); Determines the (negative) Higgs lagrangian mass squared parameter, obtained by minimizing the Landau gauge effective potential, after resummation of Goldstone boson contributions, with up to full 2-loop order with leading 3-loop contributions. The computation uses equations (4.18)-(4.21) of [SPM14]. Note that the variable SMH_m2 is *not* set by this routine; use, e.g., SMH_m2 = SMH_Find_m2 (loopOrder); to achieve this. General Utilities ================= void SMH_DisplayParameters (void); Prints the current model parameters to stdout. --------------------------------------------------------------------- void SMH_DisplayModel (void); Prints the current model parameters and lagrangian mass squared parameters to stdout. --------------------------------------------------------------------- void SMH_Update (void); Updates all tree-level running lagrangian mass squared parameters, as well as various powers of model parameters used in the calculations. --------------------------------------------------------------------- void SMH_Version (void); Prints SMH version information to stdout. --------------------------------------------------------------------- The following nine routines perform simple checks on the model parameters, to see whether they are in "reasonable" ranges. If out of range, a warning message is printed (but execution is not halted). The ranges have been set to be rather conservative, but users can adjust these to suit their needs. void SMH_Check_Mh_range (TSIL_REAL testMh); Checks testMh. Default reasonable range is 120-130 GeV. --------------------------------------------------------------------- void SMH_Check_Q_range (void); Checks SMH_Q. Default reasonable range is 25-500 GeV. --------------------------------------------------------------------- void SMH_Check_g3_range (void); Checks SMH_g3 (SU(3) coupling). Default reasonable range is 0.5-2.0. --------------------------------------------------------------------- void SMH_Check_g_range (void); Checks SMH_g (SU(2) coupling). Default reasonable range is 0.4-0.8. --------------------------------------------------------------------- void SMH_Check_gp_range (void); Checks SMH_gp (U(1)_Y coupling). Default reasonable range is 0.2-0.5. --------------------------------------------------------------------- void SMH_Check_lambda_range (void); Checks SMH_lambda (Higgs self-coupling). Default reasonable range is 0.05-0.2. --------------------------------------------------------------------- void SMH_Check_m2_range (void); Checks SMH_m2 (Higgs Lagrangian mass^2 parameter). Default reasonable range is -(120*120) to -(60*60) GeV^2. --------------------------------------------------------------------- void SMH_Check_vev_range (void); Checks SMH_v (scalar vacuum expectation value). Default reasonable range is 200-300 GeV. --------------------------------------------------------------------- void SMH_Check_yt_range (void); Checks SMH_yt (top-quark Yukawa coupling). Default reasonable range is 0.5-1.5. --------------------------------------------------------------------- void SMH_Error (char *funcName, char *errMsg, int status); Prints a message of the form: ERROR (funcName): errMsg and exits with status code status. A stack trace is also printed for diagnostic purposes. SMH error messages appear on stdout by default, so they are seen even if warnings have been disabled or redirected. --------------------------------------------------------------------- void SMH_Warn (char *, char *); Prints a message of the form: WARN (funcName): errMsg and execution continues. SMH warnings appear on stderr so they can be redirected by the shell or otherwise suppressed, e.g., by fclose (stderr); Sample Code =========== Below is a code fragment that illustrates the use of SMH: #include #include "smhiggs.h" /* Must be included when SMH is used. */ int main () { ... /* Set parameter valuess; these are the benchmark data from [MR14]. Note that these variables are defined in smhiggs.h. */ SMH_Q = 173.10; SMH_gp = 0.35761; SMH_g = 0.64822; SMH_g3 = 1.1666; SMH_yt = 0.93558; SMH_lambda = 0.12711; SMH_m2 = -(93.36*93.36); SMH_v = 247.03931235397684; SMH_DisplayModel (); /* Print coupling and lagrangian mass^2 parameter values for reference. */ SMH_RGrun (250.0, 3); /* Run the model to Q=250 GeV using 3-loop beta functions. */ printf("\nMh = %Lf\n", SMH_Find_Mh (2.5)); /* Calculate and print the Higgs pole mass at 2 loops and with leading 3-loop QCD contrib- utions. */ ... } ************************************************************************ End of README.txt ************************************************************************