adding first draft of HSSUSY documentation

doc/mainpage.dox.in

@@ -40,6 +40,7 @@ To run the NMSSM spectrum generator, run
 - @ref librarylink
 - @ref documentation
 - @ref package
+- @ref model_descriptions
 - @ref utilities
 
 \section References

doc/models.dox

@@ -0,0 +1,85 @@
+/**
+\page model_descriptions Models
+\tableofcontents
+
+\section model_hssusy HSSUSY
+
+HSSUSY (high scale supersymmetry) is an implementation of the Standard
+Model, matched to the MSSM at the SUSY scale, \f$M_\text{SUSY}\f$.  At
+the SUSY scale, the quartic Higgs coupling,
+\f$\lambda(M_\text{SUSY})\f$ is predicted from the matching to the
+MSSM using the threshold corrections of [arXiv:1407.4081,
+arxiv:1504.05200].  The 3-loop renormalization group equations of
+[arxiv:1504.05200, arxiv:1303.4364] are used to run
+\f$\lambda(M_\text{SUSY})\f$ down to the electroweak scale.  At the
+electroweak scale, the gauge and Yukawa couplings as well as the SM
+vacuum expectation value (VEV) are calculated at the 1-loop level from
+the known low-energy couplings \f$\alpha_{\text{em}}(M_Z)\f$,
+\f$\alpha_s(M_Z)\f$ and Standard Model masses.  The top Yukawa
+coupling \f$y_t(M_Z)\f$ is calculated at the 1-loop level from the
+top pole mass, taking 2-loop [hep-ph/9803493] and 3-loop
+[arxiv:hep-ph/9911434] corrections into account.
+
+__Input parameters__
+
+ Parameter                                  | description                                                  | input block/field
+--------------------------------------------|--------------------------------------------------------------|------------------
+\f$M_{\text{SUSY}}\f$                       | SUSY scale                                                   | `EXTPAR[0]`
+\f$M_1(M_\text{SUSY})\f$                    | Bino mass                                                    | `EXTPAR[1]`
+\f$M_2(M_\text{SUSY})\f$                    | Wino mass                                                    | `EXTPAR[2]`
+\f$M_3(M_\text{SUSY})\f$                    | Gluino mass                                                  | `EXTPAR[3]`
+\f$\mu(M_\text{SUSY})\f$                    | \f$\mu\f$-parameter                                          | `EXTPAR[4]`
+\f$m_A(M_\text{SUSY})\f$                    | running CP-odd Higgs mass                                    | `EXTPAR[5]`
+\f$M_{\text{EWSB}}\f$                       | scale at which the pole mass spectrum is calculated          | `EXTPAR[5]`
+\f$A_t(M_\text{SUSY})\f$                    | trililear stop coupling                                      | `EXTPAR[7]`
+\f$\tan\beta(M_\text{SUSY})\f$              | \f$\tan\beta(M_\text{SUSY})=\frac{v_u}{v_d}\f$               | `EXTPAR[25]`
+\f$(m_{\tilde{q}}^2)_{ij}(M_\text{SUSY})\f$ | soft-breaking left-handed squark mass parameters             | `MSQ2IN`
+\f$(m_{\tilde{u}}^2)_{ij}(M_\text{SUSY})\f$ | soft-breaking right-handed up-type squark mass parameters    | `MSU2IN`
+\f$(m_{\tilde{d}}^2)_{ij}(M_\text{SUSY})\f$ | soft-breaking right-handed down-type squark mass parameters  | `MSD2IN`
+\f$(m_{\tilde{l}}^2)_{ij}(M_\text{SUSY})\f$ | soft-breaking left-handed slepton mass parameters            | `MSL2IN`
+\f$(m_{\tilde{e}}^2)_{ij}(M_\text{SUSY})\f$ | soft-breaking right-handed down-type slepton mass parameters | `MSE2IN`
+
+__EWSB__
+
+The 1-loop electroweak symmetry breaking condition is imposed at the
+scale \f$M_{\text{EWSB}}\f$ and is used to fix the value of the
+bililear Higgs coupling \f$\mu^2(M_{\text{EWSB}})\f$.
+
+__Boundary conditions__
+
+_High scale_
+
+The high scale (`HighScale`) is fixed \f$M_{\text{SUSY}}\f$.  At
+\f$M_{\text{SUSY}}\f$, the quartic Higgs coupling
+\f$\lambda(M_\text{SUSY})\f$ is fixed using the 1- and leading 2-loop
+threshold corrections of [arXiv:1407.4081, arxiv:1504.05200].
+
+_EWSB scale_
+
+The scale at which the pole mass spectrum (including the Higgs mass)
+(`SUSYScale`) is calculated is the electroweak symmetry breaking
+scale, \f$M_{\text{EWSB}}\f$.
+
+_Low scale_
+
+At the low scale (`LowScale`) the gauge and Yukawa couplings as well
+as the VEV are calculated from the input parameters
+\f$\alpha_{\text{em}}(M_Z)\f$, \f$\alpha_s(M_Z)\f$, \f$G_F\f$,
+\f$m_u(2\,\text{GeV})\f$, \f$m_d(2\,\text{GeV})\f$,
+\f$m_s(2\,\text{GeV})\f$, \f$m_c(m_c)\f$, \f$m_b(m_b)\f$, \f$M_t\f$,
+\f$M_e\f$, \f$M_\mu\f$, \f$M_\tau\f$, \f$M_Z\f$ using the approach
+described in [arxiv:1609.00371].
+
+Depending on the given input flags, the top Yukawa coupling,
+\f$y_t(M_Z)\f$, is calculated at the 1-loop level plus additional
+2-loop [hep-ph/9803493] and 3-loop [arxiv:hep-ph/9911434] QCD
+corrections, see \ref FlexibleSUSY_config .
+
+__Pole masses__
+
+The Standard Model pole mass spectrum is calculated at the 1-loop
+level.  Depending on the given input flags, 2-loop corrections
+\f$O(\alpha_t\alpha_s + \alpha_t^2)\f$ of [arxiv:1205.6497, Eq. (20)]
+are included.
+
+*/