flexiblesusy is hosted by Hepforge, IPPP Durham
FlexibleSUSY
README.rst
Go to the documentation of this file.
1.. sectnum::
2
3============
4FlexibleSUSY
5============
6
7|release| |commits-since| |static-analysis| |tests|
8
9.. |release| image:: https://img.shields.io/github/v/release/FlexibleSUSY/FlexibleSUSY
10.. |commits-since| image:: https://img.shields.io/github/commits-since/FlexibleSUSY/FlexibleSUSY/latest/development
11 :alt: GitHub commits since latest release (by SemVer including pre-releases)
12.. |static-analysis| image:: https://github.com/FlexibleSUSY/FlexibleSUSY/workflows/static%20analysis/badge.svg?branch=development
13 :target: https://github.com/FlexibleSUSY/FlexibleSUSY/actions/workflows/static-analysis.yml
14.. |tests| image:: https://github.com/FlexibleSUSY/FlexibleSUSY/actions/workflows/tests.yml/badge.svg?branch=development
15 :target: https://github.com/FlexibleSUSY/FlexibleSUSY/actions/workflows/tests.yml
16
17.. image:: doc/images/FS-logo.png
18 :align: right
19
20FlexibleSUSY provides Mathematica and C++ code to create spectrum
21generators for supersymmetric and non-supersymmetric models. It is
22designed for generating fast and modular C++ code, allowing for easy
23modification, extension and reuse.
24
25* Homepage: https://flexiblesusy.hepforge.org
26* Mailing list: flexiblesusy@projects.hepforge.org
27* Source code repository: https://github.com/FlexibleSUSY
28* Bug reports: https://github.com/FlexibleSUSY/FlexibleSUSY/issues
29* References: [1406.2319]_, [1609.00371]_, [1710.03760]_, [2204.05285]_
30
31 If you use **FlexibleSUSY** in your work please cite [1406.2319]_
32 and [1710.03760]_.
33
34 If you use the **FlexibleEFTHiggs** approach in your work please
35 cite [1609.00371]_ and [1710.03760]_.
36
37 If you use **FlexibleSUSY+Himalaya** or Himalaya_ in your work,
38 please cite [1005.5709]_, [1708.05720]_, [1807.03509]_ and
39 [1910.03595]_.
40
41 If you use **FlexibleSUSY+GM2Calc** in your work, please cite
42 [1510.08071]_ and (if appropriate) [2110.13238]_.
43
44 If you use **FlexibleDecay** in your work, please cite
45 [2106.05038]_ and [1211.2099]_.
46
47 If you use the W boson pole mass prediction in FlexibleSUSY 2.7.0
48 (or later), please cite [2204.05285]_.
49
50 If you use **NPointFunctions** in your work, please cite [2402.14630]_.
51
52 FlexibleSUSY depends on SARAH_ and contains components from
53 SOFTSUSY_. Therefore, please also cite the following publications
54 along with FlexibleSUSY:
55
56 - **SARAH** [0909.2863]_, [1002.0840]_, [1207.0906]_, [1309.7223]_
57 - **SOFTSUSY** [hep-ph:0104145]_, [1311.7659]_
58
59 The list of references in BibTeX format can be found in
60 `<doc/references.bib>`_.
61
62.. contents:: Table of Contents
63 :depth: 2
64
65
66Quick start
67===========
68
69Install required libraries and packages (if not already done)
70
71.. code-block:: shell
72
73 pip install conan
74 conan install . --build=missing
75 sudo apt-get install libgsl-dev
76 ./install-sarah
77
78Build a spectrum generator (here: HSSUSY [1710.03760]_
79[1804.09410]_)
80
81.. code-block:: shell
82
83 ./createmodel --name=HSSUSY
84 ./configure --with-models=HSSUSY
85 make -j4
86
87Run the spectrum generator
88
89.. code-block:: shell
90
91 ./models/HSSUSY/run_HSSUSY.x --slha-input-file=model_files/HSSUSY/LesHouches.in.HSSUSY
92
93
94Building FlexibleSUSY
95=====================
96
97Requirements
98------------
99
100* C++17 compiler (g++ >= 7.0.0 or clang++ >= 4.0.0 or icpc >= 18.0.0)
101* Fortran compiler (gfortran, ifort)
102* `Mathematica/Wolfram Engine`_ (version 11.0 or higher)
103* SARAH_ (version 4.11.0 or higher)
104* Boost_ (version 1.37.0 or higher)
105* `Eigen 3`_ (version 3.1 or higher)
106* `GNU scientific library`_
107
108Optional:
109
110* FeynArts_ (version 3.9 or higher)
111* FormCalc_ (version 9.5 or higher)
112* GM2Calc_ (version 2.1.0 or higher)
113* LoopTools_ (version 2.8 or higher)
114* COLLIER_
115* Himalaya_
116* TSIL_
117
118Installation of required/optional libraries
119-------------------------------------------
120
121The required libraries Boost_, `Eigen 3`_ and `GNU scientific library`_
122can usually be installed via the package manager of the operating system.
123On Debian/Ubuntu one may run for example
124
125.. code-block:: shell
126
127 sudo apt-get install libboost-all-dev libeigen3-dev libgsl-dev
128
129The required and optional libraries Boost_, `Eigen 3`_, GM2Calc_,
130LoopTools_, Himalaya_ and TSIL_ can be also installed using the Conan_
131package manager. If not already installed, Conan can be installed
132with pip
133
134.. code-block:: shell
135
136 pip install conan
137
138To install the libraries required by FlexibleSUSY, run
139
140.. code-block:: shell
141
142 conan install . --build=missing
143
144The `GNU scientific library`_ can currently not be installed via
145Conan_.
146
147If the required libraries are installed via Conan or the operating
148system's package manager, they will be found automatically by
149FlexibleSUSY's ``configure`` script, see below.
150
151Installation of SARAH
152---------------------
153
154FlexibleSUSY requires SARAH to be installed and to be loadable with
155the ``Needs["SARAH`"]`` command from inside Mathematica. We recommend
156the following setup
157
158.. code-block:: shell
159
160 SARAH_VERSION=4.15.0
161 cd ~/.Mathematica/Applications/
162 wget https://sarah.hepforge.org/downloads/SARAH-${SARAH_VERSION}.tar.gz
163 tar -xf SARAH-${SARAH_VERSION}.tar.gz
164 ln -s ${PWD}/SARAH-${SARAH_VERSION}/ SARAH
165
166 cd ~/.Mathematica/Kernel/
167 echo "AppendTo[\$Path, \"${HOME}/.Mathematica/Applications/SARAH/\"];" >> init.m
168
169All the above steps can be executed at once with the ``install-sarah``
170script
171
172.. code-block:: shell
173
174 ./install-sarah
175
176See ``./install-sarah --help`` for more options.
177
178Installation of FeynArts/FormCalc (optional)
179--------------------------------------------
180
181If you want FlexibleSUSY to use FeynArts_ or FormCalc_ you will need
182to install these packages first. Also — as with SARAH — they need to
183be loadable with the ``Needs[]`` command from inside Mathematica. We
184recommend using the installation script ``FeynInstall`` provided on
185the FeynArts web page. e.g.
186
187.. code-block:: shell
188
189 cd ~/.local
190 wget http://www.feynarts.de/FeynInstall
191 chmod 755 FeynInstall
192 ./FeynInstall
193
194which will install the latest versions of FeynArts, FormCalc and
195LoopTools in the ``~/.local/`` directory as well as configure
196Mathematica to find these packages. Note that running the
197``FeynInstall`` script might require user intervention.
198
199Building a FlexibleSUSY model
200-----------------------------
201
2020. Before you setup a FlexibleSUSY model, you have to provide a SARAH
203 model file. To make it available in FlexibleSUSY, you can put it
204 either into FlexibleSUSY's SARAH model directory
205 ``FlexibleSUSY/sarah/<model>/`` or directly into SARAH's own model
206 directly ``SARAH/Models/<model>/``. Here ``<model>`` is the name
207 of your model (e.g. MSSM, NMSSM, etc.). Note, that there are
208 already plenty of pre-installed model files in FlexibleSUSY's and
209 SARAH's model directories that can be used.
210
2111. Create a new or re-initialize an existing FlexibleSUSY model
212
213 .. code-block:: shell
214
215 ./createmodel --name=<model>
216
217 See ``./createmodel --help`` for more details. Afterwards there will
218 be
219
220 * a model directory ``models/<model>/``
221 * a makefile module ``models/<model>/module.mk``
222 * a Mathematica start script ``models/<model>/start.m``
223 * and a FlexibleSUSY model file ``models/<model>/FlexibleSUSY.m``
224
225 To modify the model details (input parameters, boundary conditions,
226 etc.), edit the FlexibleSUSY model file
227 ``models/<model>/FlexibleSUSY.m``. For more details see the
228 documentation of the `FlexibleSUSY model file`_ and
229 `FlexibleEFTHiggs`_.
230
2312. Create the Makefile and register your model(s)
232
233 .. code-block:: shell
234
235 ./configure --with-models=<model>
236
237 Multiple models can be specified, separated by a comma. See
238 ``./configure --help`` for more options.
239
2403. Compile FlexibleSUSY with your model::
241
242 make
243
244 Use ``make -j<N>`` to use ``<N>`` CPU cores. When ``make`` is
245 executed, Mathematica is called, which generates the C++ code for
246 the specified models. All C++ source files are written to the
247 directory ``models/<model>/``. When ``make`` has finished, the
248 following spectrum generator(s) are available for each specified
249 model:
250
251 * ``models/<model>/run_<model>.x``: command line spectrum generator
252 * ``models/<model>/run_<model>.m``: Mathematica interface
253
254Example
255
256.. code-block:: shell
257
258 ./createmodel --name=HSSUSY
259 ./configure --with-models=HSSUSY
260 make -j4
261
262 ./models/HSSUSY/run_HSSUSY.x --slha-input-file=model_files/HSSUSY/LesHouches.in.HSSUSY
263
264
265Using FlexibleSUSY
266==================
267
268Available models
269----------------
270
271FlexibleSUSY ships with many pre-generated models. The following
272table includes an (incomplete) list of models with a detailed
273documentation.
274
275======================== ====================================
276 Model Description
277======================== ====================================
278 `HSSUSY`_ high-scale MSSM (pure EFT)
279 `MSSMEFTHiggs`_ high-scale MSSM (FlexibleEFTHiggs)
280 `NUHMSSMNoFVHimalaya`_ fixed-order MSSM
281======================== ====================================
282
283.. _`HSSUSY`: doc/models/HSSUSY.rst
284.. _`MSSMEFTHiggs`: doc/models/MSSMEFTHiggs.rst
285.. _`NUHMSSMNoFVHimalaya`: doc/models/NUHMSSMNoFVHimalaya.rst
286
287
288Command line
289------------
290
291For each model FlexibleSUSY creates an executable
292``models/<model>/run_<model>.x`` that can be run from the command
293line. The executable accepts the input in the SLHA format, for
294example in form of a file
295
296.. code-block:: shell
297
298 ./models/MSSM/run_MSSM.x \
299 --slha-input-file=models/MSSM/LesHouches.in.MSSM \
300 --slha-output-file=LesHouches.out.MSSM
301
302or as a stream
303
304.. code-block:: shell
305
306 cat models/MSSM/LesHouches.in.MSSM \
307 | ./models/MSSM/run_MSSM.x --slha-input-file=- --slha-output-file=LesHouches.out.MSSM
308
309For a documentation of FlexibleSUSY-specific switches in the SLHA
310input see the section on `SLHA input parameters`_.
311
312By default the executable writes the output in SLHA format to stdout.
313The output can also be appended to an SQLite database
314
315.. code-block:: shell
316
317 ./models/MSSM/run_MSSM.x \
318 --slha-input-file=models/MSSM/LesHouches.in.MSSM \
319 --slha-output-file=LesHouches.out.MSSM \
320 --database-output-file=points.db
321
322See ``models/<model>/run_<model>.x --help`` for further options.
323
324
325Mass spectrum and renormalization group running
326```````````````````````````````````````````````
327
328The pole mass spectrum and the RG flow can be written to text files
329for easy plotting. In the MSSM for example these text files can be
330generated via
331
332.. code-block:: shell
333
334 ./models/MSSM/run_MSSM.x \
335 --slha-input-file=model_files/MSSM/LesHouches.in.MSSM \
336 --rgflow-output-file=MSSM_rgflow.dat \
337 --spectrum-output-file=MSSM_spectrum.dat
338
339The generated files ``MSSM_rgflow.dat`` and ``MSSM_spectrum.dat`` can
340be plotted for example with the gnuplot scripts in the model
341directory
342
343.. code-block:: shell
344
345 gnuplot -persist -e "filename='MSSM_spectrum.dat'" \
346 models/MSSM/MSSM_plot_spectrum.gnuplot
347
348 gnuplot -persist -e "filename='MSSM_rgflow.dat'" \
349 models/MSSM/MSSM_plot_rgflow.gnuplot
350
351The gnuplot scripts are just for illustration and currently plot all
352running parameters, regardless of their mass dimension, so the
353resulting plot is not particularly informative. However, one may
354easily adapt the scripts to plot any chosen subset of the parameters.
355
356
357Mathematica interface
358---------------------
359
360FlexibleSUSY can be called from within Mathematica using Wolfram's
361LibraryLink. By default, FlexibleSUSY creates a LibraryLink library
362for each spectrum generator. The generated library can be found in
363``models/<model>/<model>_librarylink.so``, where ``<model>`` is the
364model name.
365
366Example
367
368.. code-block:: mathematica
369
370 Get["models/CMSSM/CMSSM_librarylink.m"];
371
372 (* Create a handle to a model given the input parameters.
373 See Options[FSCMSSMOpenHandle] for all default options. *)
374 handle = FSCMSSMOpenHandle[
375 fsSettings -> { precisionGoal -> 1.*^-4 },
376 fsSMParameters -> { Mt -> 173.3 },
377 fsModelParameters -> {
378 m0 -> 125, m12 -> 500, TanBeta -> 10, SignMu -> 1, Azero -> 0 }
379 ];
380
381 (* calculate pole mass spectrum *)
382 FSCMSSMCalculateSpectrum[handle];
383
384 (* calculate observables *)
385 FSCMSSMCalculateObservables[handle];
386
387 (* close the model handle *)
388 FSCMSSMCloseHandle[handle];
389
390For each model, FlexibleSUSY creates an example Mathematica script
391which illustrates the use of the Mathematica interface. The generated
392example can be found in ``models/<model>/run_<model>.m`` which can be
393run for example as
394
395.. code-block:: shell
396
397 math -run "<< \"models/<model>/run_<model>.m\""
398
399Before running it, the model parameters in the script should be set to
400reasonable values. More advanced examples can be found in the
401FlexibleSUSY documentation.
402
403Note: In order to compile the library, Mathematica must be installed.
404To disable the LibraryLink interface, configure with
405``--disable-librarylink``.
406
407Further details and examples can be found in the `LibraryLink
408documentation`_.
409
410.. _`LibraryLink documentation`: doc/librarylink.rst
411
412Parameter scans
413---------------
414
415FlexibleSUSY contains two shell scripts aiming to help the user
416performing parameter scans based on SLHA files.
417
418Tabular output
419``````````````
420
421The script ``utils/scan-slha.sh`` performs a scan over an input
422parameter.
423
424Examples:
425
426To perform a scan over :math:`\tan\beta(M_Z)` in the CMSSM (given in
427the SLHA input file in the ``MINPAR[3]`` field) and print out the the
428values of :math:`\tan\beta(M_Z)`, :math:`M_h` (``MASS[25]``) and
429:math:`y_t(M_{\text{SUSY}})` (``YU[2,2]``) run
430
431.. code-block:: shell
432
433 utils/scan-slha.sh \
434 --spectrum-generator=models/CMSSM/run_CMSSM.x \
435 --slha-input-file=model_files/CMSSM/LesHouches.in.CMSSM \
436 --scan-range=MINPAR[3]=1~30:10 \
437 --output=MINPAR[3],MASS[25],YU[2:2]
438
439Alternatively, the SLHA input can be piped into the script as
440
441.. code-block:: shell
442
443 cat model_files/CMSSM/LesHouches.in.CMSSM \
444 | utils/scan-slha.sh \
445 --spectrum-generator=models/CMSSM/run_CMSSM.x \
446 --scan-range=MINPAR[3]=1~30:10 \
447 --output=MINPAR[3],MASS[25],YU[2:2]
448
449The spectrum generator executable is specified using the
450``--spectrum-generator=`` option. The parameter to be scanned over as
451well as the scan range and the number of steps must be specified using
452the ``--scan-range=`` option. The syntax is
453
454.. code-block:: shell
455
456 --scan-range=<block>[<field>]=<start>~<stop>:<number_of_steps>
457
458Here ``<block>`` is the SLHA block in which the input parameter is to
459be found and ``<field>`` is the block entry corresponding to the
460parameter. ``<start>`` and ``<stop>`` define the scan range and
461``<number_of_steps>`` define the number of steps. By default the step
462size is linear. Alternatively, a logarithmic step size can be chosen
463by passing ``--step-size=log`` to the script. See also
464``utils/scan-slha.sh --help``. The parameters to print to the output
465stream must be defined using the ``--output=`` option. The syntax
466is
467
468.. code-block:: shell
469
470 --output=<block>[<fields>]
471
472where ``<block>`` is the SLHA block in which the output parameter is to
473be read from and ``<field>`` is the block entry corresponding to the
474parameter. To read a matrix element from a block, use a colon ``:`` to
475specify the matrix element indices. Multiple output parameters can be
476specified by a comma.
477
478Database output
479```````````````
480
481As an alternative, all parameters calculated during a scan can be
482written to a SQLite database using the ``scan-database.sh`` script.
483
484Examples
485
486.. code-block:: shell
487
488 utils/scan-database.sh \
489 --spectrum-generator=models/CMSSM/run_CMSSM.x \
490 --slha-input-file=model_files/CMSSM/LesHouches.in.CMSSM \
491 --scan-range=MINPAR[3]=1~30:10 \
492 --database-output-file=scan.db
493
494or
495
496.. code-block:: shell
497
498 cat model_files/CMSSM/LesHouches.in.CMSSM \
499 | ./utils/scan-database.sh \
500 --spectrum-generator=models/CMSSM/run_CMSSM.x \
501 --scan-range=MINPAR[3]=1~30:10 \
502 --database-output-file=scan.db
503
504The name of the database file must be set using the
505``--database-output-file=`` option.
506
507Convert SPheno to FlexibleSUSY model file
508-----------------------------------------
509
510The script ``utils/convert_SPheno_to_FlexibleSUSY.m`` can help to
511convert a SPheno model file (``SPheno.m``) to a FlexibleSUSY model
512file (``FlexibleSUSY.m.in``). The conversion is not perfect, because
513it is usually not unique. Therefore one should check the generated
514``FlexibleSUSY.m.in`` file.
515
516Example
517
518.. code-block:: shell
519
520 cat << EOF | math -noprompt > FlexibleSUSY.m.in
521 sphenoFile = "~/.Mathematica/Applications/SARAH/Models/MSSM/SPheno.m";
522 Get["utils/convert_SPheno_to_FlexibleSUSY.m"];
523 EOF
524
525
526Advanced FlexibleSUSY build options
527===================================
528
529Generating source code files only (no compilation)
530----------------------------------------------------
531
532If you want to only create the C++ source files for your model, but do
533not want to compile the code, you can use the ``--disable-compile``
534configure option
535
536.. code-block:: shell
537
538 ./configure --with-models=MSSM --disable-compile
539 make
540
541Here, configure will not check for installed compilers or libraries.
542It will only search for Mathematica and SARAH. The execution of
543``make`` will stop as soon as all C++ source code files are generated.
544See below for how to export the generated source code.
545
546
547Compile only (don't generate source code)
548-----------------------------------------
549
550If you want to only compile already created the C++ source files for
551your model, you can use the ``--disable-meta`` configure option
552
553.. code-block:: shell
554
555 ./configure --with-models=MSSM --disable-meta
556 make
557
558Here, configure will only check for installed compilers or libraries.
559It will not check for Mathematica and SARAH.
560
561This option is useful if you want to generate the source code on one
562computer and then transfer the generated code to another computer to
563compile it. This option can also be used with the pre-generated
564FlexibleSUSY models, which are provided at the FlexibleSUSY home page.
565
566Warning: Please make sure all C++ source files of your model are
567available in the model directory ``models/<model>/``. Otherwise the
568compilation will fail.
569
570
571Exporting the generated source code
572-----------------------------------
573
574The complete FlexibleSUSY source code, including the generated C++
575code for the specified model(s) (but without the Mathematica meta
576code), can be exported to a new directory. The exported source code
577is a complete standalone package, with it's own build system. To
578export the code, one has to set the target directory during
579configuration via the ``--with-install-dir=`` option. For example
580
581.. code-block:: shell
582
583 ./configure --with-models=<models> --with-install-dir=/path/to/export/directory
584
585Afterwards
586
587.. code-block:: shell
588
589 make install-src
590
591must be executed, which will copy the generated C++ source code for
592all ``<models>`` to ``/path/to/export/directory``, together with the
593non-model specific source code from ``config/``, ``doc/``, ``slhaea/``
594and ``src/``. Afterwards, the standalone package can be build like
595this
596
597.. code-block:: shell
598
599 cd /path/to/export/directory
600 ./configure
601 make
602
603It is also possible to create a "model package", which includes only
604the generated source code for a given model, but does not contain the
605whole FlexibleSUSY build system. This is useful when the source code
606for a model should be generated on one computer and later transferred
607to another one to be compiled. To create such a "model package" run
608
609.. code-block:: shell
610
611 make pack-<model>-src
612
613where ``<model>`` is the name of the model whose generated source code
614shall be packed. After ``make`` has finished, the package file
615``<model>.tar.gz`` can be found in the working directory.
616
617
618Dynamic libraries
619-----------------
620
621If you want to create dynamic model libraries (instead of static
622libraries, which is the default) you need to pass the
623``--enable-shared-libs`` option to the configure script. The file
624name extension for the shared libraries as well as the command to
625build them can be overwritten using the ``--with-shared-lib-ext=``
626``--with-shared-lib-cmd=``. parameters. For example, when Intel
627compilers should be used, replace gcc by icc or icpc
628
629.. code-block:: shell
630
631 ./configure --with-models=CMSSM,NMSSM \
632 --enable-shared-libs \
633 --with-shared-lib-ext=".so" \
634 --with-shared-lib-cmd="gcc -shared -o"
635
636**Important remark:**
637
638The libraries are linked to the executables with *absolute* paths.
639This means that, if you for example move the FlexibleSUSY directory to
640another location, the executables will no longer find the libraries.
641To make the executables find the libraries again, you have to relink
642them via
643
644.. code-block:: shell
645
646 make clean-executables
647 make allexec
648
649
650Statically linked executables
651-----------------------------
652
653External libraries can be linked statically to the spectrum generator
654executables by passing ``--enable-static`` to configure. This is
655useful when the executable should be transferred to another computer,
656where some libraries are not available.
657
658Example
659
660.. code-block:: shell
661
662 ./configure --with-models=CMSSM --enable-static
663
664If ``--enable-static`` is used, the following linker flags and
665additional libraries will be used
666
667.. code-block:: shell
668
669 LDFLAGS = -static
670 LDLIBS = -ldl
671
672These linker-specific flags and additional libraries can be
673overwritten using ``--with-static-ldflags=`` and
674``--with-static-ldlibs=``
675
676Example
677
678.. code-block:: shell
679
680 ./configure --with-models=CMSSM \
681 --enable-static \
682 --with-static-ldflags="-static" \
683 --with-static-ldlibs="-lquadmath -ldl"
684
685In case of dynamic linking (``--disable-static``, which is the default),
686the options ``--with-shared-ldflags=`` and ``--with-shared-ldlibs=`` must
687be used to set ``LDFLAGS`` and ``LDLIBS``.
688
689
690Support for alternative loop libraries
691--------------------------------------
692
693FlexibleSUSY ships with its own implementation of the
694Passarino-Veltman 1-loop functions, which have been translated from
695SOFTSUSY_. However, alternative implementations of the 1-loop
696functions can be used:
697
698* LoopTools_
699* COLLIER_
700* FFlite (a thread-safe variant of LoopTools_, shipped with FlexibleSUSY)
701
702The loop function libraries can be enabled by passing
703``--with-loop-libraries=`` to the ``configure`` script
704
705.. code-block:: shell
706
707 ./configure --with-loop-libraries=<libraries>
708
709where ``<libraries>`` can be any (or a combination) of ``collier``,
710``looptools`` or ``fflite``.
711
712Example
713
714.. code-block:: shell
715
716 ./configure --with-loop-libraries=collier,looptools
717
718When the SLHA input is used, the loop library to use can be selected
719by setting the entry of ``FlexibleSUSY[31]`` to ``0`` (= SOFTSUSY),
720``1`` ( = COLLIER), ``2`` (= LoopTools) or ``3`` (= FFlite). See
721`SLHA input parameters`_ for details.
722
723Example::
724
725 Block FlexibleSUSY
726 31 0 # loop library (0 = SOFTSUSY, 1 = COLLIER, 2 = LoopTools, 3 = FFlite)
727
728When the Mathematica interface is used, the loop library to use can be
729selected by setting the value of ``loopLibrary`` appropriately
730
731.. code-block:: mathematica
732
733 FS@ModelName@OpenHandle[
734 fsSettings -> {
735 loopLibrary -> 0 (* 0 = SOFTSUSY, 1 = COLLIER, 2 = LoopTools, 3 = FFlite *)
736 }
737 ]
738
739In the following it is described in more detail how to enable these
740alternative loop function libraries in FlexibleSUSY.
741
742LoopTools support
743`````````````````
744
745It is possible to use LoopTools_ for calculating the loop functions,
746instead of using SOFTSUSY's loop functions. To enable LoopTools,
747configure FlexibleSUSY via
748
749.. code-block:: shell
750
751 ./configure --enable-looptools
752
753or
754
755.. code-block:: shell
756
757 ./configure --with-loop-libraries=looptools
758
759If LoopTools has been installed via Conan_, the configure will
760automatically find the paths to the LoopTools library.
761
762To use the LoopTools library and header files from a specific
763directory, run ``configure`` via
764
765.. code-block:: shell
766
767 LOOPTOOL_DIR=/path/to/looptools/build
768
769 ./configure --enable-looptools \
770 --with-looptools-incdir=$LOOPTOOLS_DIR \
771 --with-looptools-libdir=$LOOPTOOLS_DIR
772
773Note: LoopTools 2.8 or higher is required.
774Also, if FlexibleSUSY is compiled with LibraryLink (default) then LoopTools has to be compiled with ``-fPIC`` option.
775This is achieved by setting the ``FFLAGS`` variable during LoopTools configuration as
776
777.. code-block:: shell
778
779 FFLAGS="-O3 -fPIC" ./configure
780
781COLLIER support
782```````````````
783
784It is possible to use COLLIER_ for calculating the loop functions,
785instead of using SOFTSUSY's loop functions. To enable COLLIER
786configure FlexibleSUSY via
787
788.. code-block:: shell
789
790 ./configure --with-loop-libraries=collier
791
792To use the COLLIER library and header files from a specific
793directory configure via
794
795.. code-block:: shell
796
797 COLLIER_DIR=/path/to/COLLIER-x.y.z
798
799 ./configure --with-loop-libraries=collier \
800 --with-collier-incdir=$COLLIER_DIR/modules \
801 --with-collier-libdir=$COLLIER_DIR
802
803Note: versions since COLLIER-1.2.3 were tested so far.
804Also, COLLIER static library should be configured with
805``-Dstatic=ON -DCMAKE_POSITION_INDEPENDENT_CODE=ON`` flags.
806
807TSIL support
808````````````
809
810Some models of FlexibleSUSY require TSIL_, for example `HSSUSY`_. When
811such models are activated (via ``./configure --with-models=<model>``),
812FlexibleSUSY requires TSIL to be available. If TSIL is installed in a
813system directory or installed via Conan_, FlexibleSUSY will find the
814TSIL automatically. To use TSIL from a a non-standard directory,
815configure FlexibleSUSY like this
816
817.. code-block:: shell
818
819 $TSIL_DIR=/path/to/tsil
820
821 ./configure --enable-tsil \
822 --with-tsil-incdir=$TSIL_DIR \
823 --with-tsil-libdir=$TSIL_DIR
824
825Note also that TSIL must be compiled with ``-fPIC``, which can be
826achieved by setting in the TSIL ``Makefile``
827
828.. code-block:: shell
829
830 TSIL_OPT = -O3 -funroll-loops -fPIC
831
832
833Creating an addon
834-----------------
835
836A FlexibleSUSY addon is a program or library, which uses parts of the
837FlexibleSUSY libraries or the generated models or is integrated into
838FlexibleSUSY. An addon can be created via
839
840.. code-block:: shell
841
842 ./createaddon --name=<addon>
843
844where ``<addon>`` is the name of the addon. The createaddon script
845creates the directory ``addons/<addon>/`` and the corresponding makefile
846module ``addons/<addon>/module.mk``. If an addon has been created with
847the above script, the user may edit the makefile module
848(``addons/<addon>/module.mk``) to add source files in to the three
849variables
850
851.. code-block:: shell
852
853 LIB@ADDON@_SRC # list of source files to be included in library
854 EXE@ADDON@_SRC # list of source files with a main()
855 LIB@ADDON@_HDR # list of header files
856
857Example
858
859.. code-block:: shell
860
861 LIB@ADDON@_SRC := $(DIR)/file1.cpp
862 EXE@ADDON@_SRC := $(DIR)/run.cpp
863 LIB@ADDON@_HDR := $(DIR)/file1.hpp
864
865To configure and compile the addon run
866
867.. code-block:: shell
868
869 ./configure --with-addons=<addon>
870 make
871
872make compiles all source files and creates the addon library
873``addons/<addon>/lib<addon>.a`` (including the object file ``file1.o`` in
874the above example) and an executable (``addons/<addon>/run.x`` in the
875above example).
876
877
878Creating the source code documentation
879--------------------------------------
880
881FlexibleSUSY's source code documentation (including the generated
882source code files) can be generated with Doxygen in HTML or man
883format. To generate the HTML documentation please run
884
885.. code-block:: shell
886
887 make doc-html
888
889The generated HTML index file can then be found in
890``doc/html/index.html`` and can be viewed with any HTML browser, e.g.
891
892.. code-block:: shell
893
894 firefox doc/html/index.html
895
896To generate the man documentation please run
897
898.. code-block:: shell
899
900 make doc-man
901
902The generated man pages can then be found in ``doc/man/man3/`` and can
903be viewed as
904
905.. code-block:: shell
906
907 man doc/man/man3/model_file_options.3
908
909
910Cleaning
911--------
912
913There are several make targets to remove generated files, compiled
914object files, libraries or executables::
915
916 make clean # deletes all .d .o .a .x files
917
918 make distclean # does `clean` and `clean-generated`
919 # and deletes in addition:
920 # Makefile flexiblesusy-config config.*
921 # config/list_sarah_model_files.sh
922
923 make clean-dep # deletes all .d files
924
925 make clean-executables # deletes all .x files
926
927 make clean-generated # deletes generated files
928
929 make clean-lib # deletes all libraries
930
931 make clean-obj # deletes all .o files
932
933For each model ``<model>`` or addon there are specific clean targets
934to remove model-specific files::
935
936 make clean-<model> # deletes .d .o .a .x files
937
938 make distclean-<model> # same as `make clean-<model> clean-<model>-src`
939
940 make clean-<model>-dep # deletes .d files
941
942 make clean-<model>-lib # deletes model library
943
944 make clean-<model>-obj # deletes .o files
945
946 make clean-<model>-src # deletes generated files
947
948
949Package content
950===============
951
952In the following all sub-directories within the FlexibleSUSY package
953are listed:
954
955* ``addons/`` contains addons for FlexibleSUSY
956
957* ``config/`` contains helper scripts and makefile modules for the
958 build system
959
960* ``doc/`` contains the FlexibleSUSY documentation
961
962* ``examples/`` contains examples how to build you own spectrum
963 generator based on FlexibleSUSY
964
965* ``fflite/`` contains an alternative implementation of the
966 Passarino-Veltman loop functions, based on FF
967
968* ``meta/`` contains the Mathematica meta code which generates the
969 spectrum generators. See the `meta code documentation`_ for more
970 details.
971
972* ``model_files/`` contains default model files for some frequently
973 used models (SM, SplitMSSM, MSSM, NMSSM, SMSSM, UMSSM, etc.)
974
975* ``model_specific/`` contains model-specific higher order corrections
976 for the MSSM, NMSSM, SM and SplitMSSM from the literature
977
978* ``models/`` This is the output directory where the generated C++
979 code for the spectrum generators will be stored.
980
981* ``nlohmann/`` contains the nlohmann_ JSON library
982
983* ``Output/`` contains SARAHs model-specific output files
984
985* ``sarah/`` contains SARAH model files shipped with FlexibleSUSY
986
987* ``slhaea/`` contains the slhaea_ SLHA reader library
988
989* ``src/`` contains model-independent FlexibleSUSY C++ source code
990
991* ``templates/`` contains C++ template files for the spectrum generators
992
993* ``test/`` contains the FlexibleSUSY test suite
994
995* ``utils/`` contains some utility scripts to perform scans or extract
996 data from SLHA files
997
998
999Further reading
1000===============
1001
1002* `FlexibleSUSY model file`_
1003* `FlexibleEFTHiggs`_
1004* `LibraryLink documentation`_
1005* `meta code documentation`_
1006* `SLHA input parameters`_
1007* `Observables`_
1008
1009
1010References
1011==========
1012
1013.. _slhaea: https://github.com/fthomas/slhaea
1014.. _GM2Calc: https://github.com/GM2Calc/GM2Calc
1015.. _SARAH: http://sarah.hepforge.org
1016.. _SOFTSUSY: http://softsusy.hepforge.org
1017.. _Boost: http://www.boost.org
1018.. _Conan: https://conan.io/
1019.. _Eigen 3: http://eigen.tuxfamily.org
1020.. _FeynArts: http://www.feynarts.de
1021.. _FormCalc: http://www.feynarts.de/formcalc
1022.. _GNU scientific library: http://www.gnu.org/software/gsl
1023.. _`Mathematica/Wolfram Engine`: https://www.wolfram.com
1024.. _LoopTools: http://www.feynarts.de/looptools
1025.. _COLLIER: https://collier.hepforge.org
1026.. _Himalaya: https://github.com/Himalaya-Library/Himalaya
1027.. _TSIL: https://www.niu.edu/spmartin/tsil
1028.. _nlohmann: https://github.com/nlohmann/json
1029
1030.. _`FlexibleSUSY model file`: doc/model_file.rst
1031.. _`FlexibleEFTHiggs`: doc/FlexibleEFTHiggs.rst
1032.. _`meta code documentation`: doc/meta_code.rst
1033.. _`SLHA input parameters`: doc/slha_input.rst
1034.. _`Observables`: doc/observables.rst
1035
1036.. [hep-ph:0104145] `CPC 143 (2002) 305-331 <https://inspirehep.net/record/555481>`_ [`arxiv:hep-ph/0104145 <http://arxiv.org/abs/hep-ph/0104145>`_]
1037.. [0909.2863] `CPC 181 (2010) 1077-1086 <https://inspirehep.net/record/831371>`_ [`arxiv:0909.2863 <http://arxiv.org/abs/0909.2863>`_]
1038.. [1002.0840] `CPC 182 (2011) 808-833 <https://inspirehep.net/record/845241>`_ [`arxiv:1002.0840 <http://arxiv.org/abs/1002.0840>`_]
1039.. [1005.5709] `JHEP 1008 (2010) 104 <https://inspirehep.net/record/856612>`_ [`arxiv:1005.5709 <https://arxiv.org/abs/1005.5709>`_]
1040.. [1207.0906] `CPC 184 (2013) 1792-1809 <https://inspirehep.net/record/1121136>`_ [`arxiv:1207.0906 <http://arxiv.org/abs/1207.0906>`_]
1041.. [1211.2099] `Eur. Phys. J. C73 (2013) no. 2, 2310 <https://inspirehep.net/literature/1201957>`_ [`arxiv:1211.2099 <https://arxiv.org/abs/1211.2099>`_]
1042.. [1309.7223] `CPC 185 (2014) 1773-1790 <https://inspirehep.net/record/1255845>`_ [`arxiv:1309.7223 <http://arxiv.org/abs/1309.7223>`_]
1043.. [1311.7659] `CPC 185 (2014) 2322 <https://inspirehep.net/record/1266808>`_ [`arxiv:1311.7659 <http://arxiv.org/abs/1311.7659>`_]
1044.. [1406.2319] `CPC 190 (2015) 139-172 <https://inspirehep.net/record/1299998>`_ [`arxiv:1406.2319 <https://arxiv.org/abs/1406.2319>`_]
1045.. [1510.08071] `Eur. Phys. J. C76 (2016) no. 2, 62 <https://inspirehep.net/literature/1401235>`_ [`arXiv:1510.08071 <https://arxiv.org/abs/1510.08071>`_]
1046.. [1609.00371] `JHEP 1701 (2017) 079 <https://inspirehep.net/record/1484857>`_ [`arxiv:1609.00371 <https://arxiv.org/abs/1609.00371>`_]
1047.. [1708.05720] `Eur. Phys. J. C77 (2017) no. 12, 814 <https://inspirehep.net/record/1617767>`_ [`arxiv:1708.05720 <https://arxiv.org/abs/1708.05720>`_]
1048.. [1710.03760] `CPC 230 (2018) 145-217 <https://inspirehep.net/record/1629978>`_ [`arXiv:1710.03760 <https://arxiv.org/abs/1710.03760>`_]
1049.. [1804.09410] `Eur. Phys. J. C78 (2018) no. 7, 573 <https://inspirehep.net/record/1670032>`_ [`arxiv:1804.09410 <https://arxiv.org/abs/1804.09410>`_]
1050.. [1807.03509] `Eur. Phys. J. C78 (2018) no. 10, 874 <https://inspirehep.net/record/1681658>`_ [`arxiv:1807.03509 <https://arxiv.org/abs/1807.03509>`_]
1051.. [1910.03595] `Eur. Phys. J. C80 (2020) no. 3, 186 <https://inspirehep.net/record/1758261>`_ [`arxiv:1910.03595 <https://arxiv.org/abs/1910.03595>`_]
1052.. [2106.05038] `CPC 283 (2023) 108584 <https://inspirehep.net/literature/1867840>`_ [`arxiv:2106.05038 <http://arxiv.org/abs/2106.05038>`_]
1053.. [2110.13238] `Eur. Phys. J. C82 (2022) no. 3, 229 <https://inspirehep.net/literature/1952331>`_ [`arxiv:2110.13238 <https://arxiv.org/abs/2110.13238>`_]
1054.. [2204.05285] `Phys. Rev. D 106 (2022) 9, 095023 <https://inspirehep.net/literature/2065408>`_ [`arxiv:2204.05285 <https://arxiv.org/abs/2204.05285>`_]
1055.. [2402.14630] [`arxiv:2402.14630 <https://arxiv.org/pdf/2402.14630.pdf>`_]