== The !ToolBox ==

The !FeynRules !ToolBox provides the user a developper environment for building up his new model inside Mathmatica®. The !ToolBox contains a set of Mathmatica functions that are useful even before and independently of the calculation of Feynman rules. These functions can serve the user as a starting point to develop his own routines, using the full power of Mathematica. The user can like this develop ad expand his own !ToolBox. The current version of the !ToolBox contains
   1. Routines to expand over all the suppressed indices in the lagrangian, as well as writing the lagrangian into a flavor-expanded form. 
   1. Routines to pick out different pieces of a lagrangian (kinetic terms, mass terms, cubic interactions, ...) 
   1. Routines to check if all kinetic and mass terms are flavor diagonal. 
   1. Checking if the Lagrangian is hermitian. 
   1. A routine for checking quantum number conservation in the lagrangian. 
   1. Routines to calculate the field strength tensor of a vector field, as well as its dual. 
   1. Routines to manipulate the vertex lists produced by !FeynRules. 
   1. Routines for numerical evaluation of the parameters. 
   1. A set of boolean functions ( ''e.g.'' {{{FieldQ}}}), useful for the development of new routines. 

The most recent version of the !ToolBox is provided together with the [:CoreCode:package], or it can as well be downloaded from below.



=== Current content of the !ToolBox ===
==== Miscellaneous ====

The !ToolBox contains a set of boolean functions which can be usefull when writing new routines, ''e.g.''

{{{FieldQ[ψ]}}} returns True if the symbol ψ was defined as a field. Undefined otherwise.

Other boolean functions for fields that work in the same way are {{{FermionQ}}}, {{{BosonQ}}}, {{{ScalarFieldQ}}}, {{{GhostFieldQ}}}, {{{VectorFieldQ}}}, {{{DiracFieldQ}}}, {{{MajoranaFieldQ}}}, {{{Spin2FieldQ}}}, {{{SelfConjugateQ}}}.

Similarly, there is a set of boolean functions for parameters:

{{{numQ[c]}}} returns {{{True}}} if {{{c}}} is a scalar parameter, ''i.e.'' {{{c}}} is a ''c'' -number. Undefined otherwise.

{{{CnumQ[c]}}} returns {{{True}}} if {{{c}}} is a complex scalar parameter, and {{{False}}} for real scalar parameters. Undefined otherwise.

{{{TensQ[T]}}} returns {{{True}}} if the symbol {{{T}}} represents a tensor (e.g. CKM matrix). Undefined otherwise.

{{{UnitaryQ[T]}}} returns {{{True}}} if the symbol {{{T}}} represents a unitary tensor. Undefined otherwise. Functions that work in the same way: {{{HermitianQ}}}, {{{OrthogonalQ}}}.

Another usefull function to build user-defined routines is =$IndList=:

=$IndList[ψ]= returns the list of symbols carried by the symbol ψ.
==== Numerical evaluation of parameters ====

{{{NumericalValue[p]}}} returns the numerical value of the parameter {{{p}}}. If {{{p}}} is an internal parameter given in terms of algebraic relations to others parameters, {{{NumericalValue}}} evaluates this algebraic relation to return a number. If no numerical value could be obtained, {{{NoValue}}} is returned.
==== Index and flavor expansion ====

The !ToolBox has a routine which allows to represent explicitly the lagrangian with all indices. Let us consider as an example the lagrangian descripbing the coupling of the charged leptons to the photon:
{{{L = I lbar.Ga[mu].del[l,mu] + ee lbar.Ga[mu].l A[mu] 
}}}

where l represents the class of the charge leptons ( {{{e}}}, {{{m}}}, {{{tt}}}). {{{ExpandIndices[L]}}} returns the lagrangian {{{L}}} with all indices written explicitly:
{{{{{{ExpandIndices[L] = I Ga[mu,r,s] lbar[r,f].del[l[s,f],mu] + ee Ga[mu,r,s] lbar[r,f].l[s,f] A[mu]}}} }}}

where {{{r}}}, {{{s}}} represent the {{{Spin}}} indices of the leptons, and {{{f}}} the {{{Generation}}} index.

In a similar way, one can ask the code to expand over the flavor indices in the lagrangian (see the [[UserManual][user manual] forfurther information):
{{{ExpandIndices[L, FlavorExpand -> True] = I Ga[mu,r,s] ebar[r].del[e[s],mu] + ee Ga[mu,r,s] ebar[r].e[s] A[mu]
                                         +I Ga[mu,r,s] mbar[r].del[m[s],mu] + ee Ga[mu,r,s] mbar[r].m[s] A[mu] 
                                         +I Ga[mu,r,s] ttbar[r].del[tt[s],mu] + ee Ga[mu,r,s] ttbar[r].tt[s] A[mu]}}}

The option {{{IndexExpand}}} works in a similar fashion.

{{{ExpandIndices}}} has some additional options:
   * {{{ExpandIndices[L, MaxParticles -> n]}}} selects those terms of the lagrangian which invole at most {{{n}}} fields. 
   * {{{ExpandIndices[L, MinParticles -> n]}}} selects those terms of the lagrangian which invole at least {{{n}}} fields. 
   * {{{ExpandIndices[L, MaxCanonicalDimension -> n]}}} selects those terms of the lagrangian canonical dimension is at most {{{n}}}. 
   * {{{ExpandIndices[L, MinCanonicalDimension -> n]}}} selects those terms of the lagrangian canonical dimension is at least {{{n}}} 
   * {{{ExpandIndices[L, SelectParticles -> {{...}, {...}}]}}} selects those terms of the lagrangian which invole the field content specified in the list, ''e.g.'' {{{ExpandIndices[L, SelectParticles -> {{e, ebar, A}, {m, mbar, A}}, FlavorExpand -> True]}}} selects only the electron and muon QED couplings. Notice that the appearance of {{{FlavorExpand}}} is crucial in order to find the correct pieces! As a general rule, only mass eigenstates should be selected by this option. 

==== Selection of different pieces of a lagrangian ====

During the model building phase, it might sometimes be convenient to just select a specific substructure of the whole lagrangian, ''e.g.'' the kinetic terms. This can be done using the function
{{{GetKineticTerms[L] = I lbar.Ga[mu].del[l,mu] }}}

Functions that work in a similar way: {{{GetMassTerms}}}, {{{GetQuadraticTerms}}}, {{{GetInteractionTerms}}}. All of these functions make use of {{{ExpandIndices}}}, and share all its properties concerning flavor expansion, i.e.
{{{GetKineticTerms[L, FlavorExpand -> True]}}}

first flavor-expands the lagrangian, then looks for the kinetic terms.

There is another selection function available: {{{SelectFieldContent[L, ''list'' ]}}} is equivalent to {{{ExpandIndices[L, SelectParticles -> ''list'' ]}}}.
==== Checking for flavor diagonal lagrangians ====

It is convenient to check that the lagrangian is actually written in terms of mass eigenstates, i.e. that all the quadratic terms in the lagrangian are diagonal. This is done via

{{{CheckDiagonalQuadraticTerms}}} : Checks whether all quadratic terms are flavor diagonal.

{{{CheckDiagonalKineticTerms}}} : Checks whether all kinetic terms are flavor diagonal.

{{{CheckDiagonalMassTerms}}} : Checks whether all mass terms are flavor diagonal.

All of these functions make use of {{{ExpandIndices}}}, and share all its properties concerning flavor expansion, i.e.
{{{CheckDiagonalMassTerms[L, FlavorExpand -> True]}}}

first flavor-expands the lagrangian, then checks whether all mass terms are diagonal.
==== Checking for quantum number conservation ====

{{{CheckQuantumNumbers[L]}}} checks if all quantum numbers are conserved in the lagrangian.

{{{CheckQuantumNumbers[L, QN -> {QN1, QN2}]}}} checks if the quantum numbers {{{QN1}}}, {{{QN2}}}, ... are conserved in the lagrangian.

This functions make use of {{{ExpandIndices}}}, and share all its properties concerning flavor expansion, i.e.
{{{CheckQuantumNumbers[L, FlavorExpand -> True]}}}

first flavor-expands the lagrangian, then checks whether quantum numbers are conserved.
==== Check for hermiticity ====

{{{CheckHermiticity[L]}}} checks if the lagrangian {{{L}}} is hermitian. {{{CheckHermiticity}}} has the same options as {{{FeynmanRules}}}.

==== Field strength tensors ====

The !ToolBox contains routines that allow to build in an automated way the field strength tensors for vector fields:
   * For abelian vector fields {{{FS[A, mu, nu] = del[A[nu],mu] - del[A[mu] ,nu]}}} 
   * For non abelian vector fields {{{{{{FS[A, mu, nu, a, f, g] = del[A[nu, a],mu] - del[A[mu,a] ,nu] + g f[a ,b ,c] A[mu,b] A[nu,c]}}} }}} 

where {{{A}}} denotes the gauge boson, {{{mu}}} and {{{nu}}} the Lorentz indices of the field strength tensor, {{{a}}}, {{{b}}}, {{{c}}} the adjoint color indices, {{{f}}} the structure constant and {{{g}}} is the name of the gauge coupling constant.

'''Warning''': This definition for {{{FS}}} uses an implicit sign convention for the term in {{{A[mu, b] A[nu, c]}}}! This convention must be consistent with the sign convention used for the covariant derivation in order to insure gauge invariance!

The dual of the field strength tensor can e obtained via the {{{Dual}}} function:
   * {{{Dual[FS][A, mu, nu]}}} is the dual of {{{FS[A, mu, nu]}}}, {{{Dual[FS][A, mu, nu] = 1/2 Eps[mu, nu, rho, sig] FS[A, rho, sig]. }}} 
   * {{{Dual[FS][A, mu, nu, a, f, g]}}} is the dual of {{{FS[A, mu, nu, a, f, g]}}}. 
==== Manipulating the vertex lists ====

The results obtained by {{{FeynmanRules}}} are stored in the function {{{Vertices[ ]}}} (see the [:UserManual:user manual]). {{{Vertices[ ]}}} is a lis, whose entries are two-component lists:
   * The first entry contains a list whose entries are the particles that enter the vertex, ''e.g.'' {{G, 1}, {u, 2}, {ubar, 3}}. Each particle is represented by its symbol, followed by an integer number which labels its indices inside the vertex. 
   * The second entry is the analytic expression of the vertex. 
===== SelectVertices =====
   * {{{SelectVertices[Vertices[...], {G, u, ubar}]}}} extract the vertex ={G, u, ubar}= out of the vertex list {{{Vertices[...]}}}. 
   * {{{SelectVertices[Vertices[...], {{G, G, G}, {G,G,G}, ...}]}}} extract the vertices ={{G, G, G}, {G,G,G}, ...}= out of the vertex list {{{Vertices[...]}}}. 
===== Imposing momentum conservation =====
   * {{{MomentumReplace[{{{G,1}, {G,2}, {G,3}}, < ''analytic expression'' >}, n]}}} replaces the momentum of the particle with the tag {{{n}}} everywhere by the minus the sum of all the other particles. 
   * {{{ApplyMomentumConservation[Vertices[...]]}}} is equvalent to applying {{{MomentumReplace[ . , 1]}}} to each element of {{{Vertices[...]}}}. Mathematica is a registered trademark of Wolfram Research, Inc. 

-- Main.ClaudeDuhr - 09 Feb 2008