TamarA 2.0 User Guide.

The paper describes the Mathematica package TamarA for analytical calculation of Feynman diagram expressions. The package supports both relativistic and non-relativistic three dimensional calculation of traces. The package also includes numerous simplification rules of four and three dimensional expressions. User friendliness was one of first priorities when the package was designed. Output is graphical and very close to standard physics notations. Keyboard input is easy to remember. Many short notations are defined as alternatives. This guide includes a detailed description of the package with usage examples.

1. Introduction.

Analytical calculations of Feynman diagrams are very time consuming but routine tasks in particle and nuclear physics. Once Feynman rules are derived for a chosen Lagrangian the remaining calculations can be done by a computer program. However, existing programs, for example FORM [1], REDUCE [1], and Tracer [2] are not very user-friendly, so the diagrams are often calculated by hand.
The ten year old Tracer source code inspired me to write a new more user friendly program, TamarA. Although many useful ideas were taken from the Tracer code, TamarA was written from scratch. Both Tracer and TamarA are Mathematica packages. TamarA takes advantages of new graphical features of Mathematica 3.0. The program produces nicely formatted graphical output which usually follows standard physics notations. The output in TamarA can always be interpreted as input: a user may utilize copy and paste to continue work with the data. Keyboard input is intuitive and easy to learn.
Many extra features were added to the package. TamarA distinguishes covariant and contravariant indices, automatically does index contraction. Three-dimensional objects, summation and traces are also implemented.
Compared to Tracer, TamarA never produces meaningless output even if input is inconsistent. When input is wrong TamarA usually issues an error message or just outputs the confusing part unevaluated.
The program was checked extensively by comparing against known results. It was found that the package is very reliable and correct in all tested cases.
Though the program comes without warranty of any kind, I will release possible bug corrections and upgrades as time allows. I hope you will enjoy using the package as much as I do.
The following section discusses rule-based programming. The third section explains index notation type checking functions. The forth section defines four dimensional objects and their three dimensional equivalents. The fifth section is devoted to trace taking functions. Appendices include the license agreement and full package code.

2. Variable testing functions.

Variable testing is very important in rule matching. Over fifty different variable testing functions are defined in TamarA to ensure proper package work. Most of the functions may not be called directly. We will discuss only user available functions.

2.1. Name definitions and testing.

■ Vector Name is an expression suitable for naming a vector. It may be a symbol, such as a variable name, or an indexed symbol. Boolean VecNameQ function tests if the expression is an allowed vector name.

VecNameQ[(Subscript[b, 1])]

VecNameQ[2  a]

In the example above,   (Subscript[b, 1]) is a subscripted symbol and a proper vector name; 2a is not a symbol, because it starts with a number.

■ Extended Vector Name is used in shortcuts of expressions. It may be sum of Vector Names multiplied by numbers. The variable is automatically reduced to Vector Name variables inside of many functions. The testing is done by ExVecNameQ boolean function.

ExVecNameQ[4 (2  a + b) - c]

ExVecNameQ[d (2  a + b) - c]

In the example above the expression includes products of two symbols, consequently it is not an Extended Vector Name.

2.2. Index definitions and testing.

■  Index may be only 0, 1, 2 or 3.
Besides standard four dimensional objects, the package uses three dimensional equivalents, consequently three dimensional indices are required.

■ 3D Integer Index represents 1, 2 or 3.

■ Symbolic Index may be a symbol or indexed symbol.
We also have to distinguish four and three dimensional symbolic indices.

■ 3D Symbolic Index is a Symbolic Index declared by d3[x] function. A 3D Symbolic Index can be declared anywhere, but must be declared before it is used or can be declared inside of the actual function call. 3D indices are always printed as subscripts.

d3[c]; ep3[d3[a, b], c]

For example, c variable was declared before the ep3 function call, a and b variables were declared inside of the call.
The d3[] function, without arguments, outputs the sequence of all declared three dimensional indices.

■ Covariant Index is an Integer or Symbolic Index but not a  3D Symbolic Index. d4[x] function is used to reclaim 3D Symbolic Index for covariant notation. The combination d4[d3[]] changes all three dimensional indices declarations to four dimensional.

■ Contravariant Index variable is designed as a covariant index variable inside of the up[x] function. The index is printed at the top of objects.

g[up[i], j]

The up[x] function may take more then one argument, for example, the shortcut g[up[i,j]] is equivalent to g[up[i],up[j]].

g[up[i, j]]

■ 4D Vector-Contracted Index is a Vector Name inside of a v4[x] function.

■ 3D Vector-Contracted Index is a Vector Name inside of a  v3[x] function.
Discussion of the vector-contracted indices is deferred until the next section.

■ 3D Index is a 3D Integer, 3D Symbolic, or 3D Vector-Contracted Index. The variables are tested by D3IndexQ[x] function.

D3IndexQ[e]

d3[e]; D3IndexQ[e]

The example above shows that a three dimensional symbolic index must be declared.
Three dimensional symbolic index is the only kind of object requiring previous declaration.

■ 4D Index is an Integer, Covariant, Contravariant or 4D Vector-Contracted Index. The variables are tested by D4IndexQ[x] function.

d3[(Subscript[a, v])]; D4IndexQ[(Subscript[a, v])]

d3[(Subscript[a, v])]; d4[(Subscript[a, v])]; D4IndexQ[(Subscript[a, v])]

The examples demonstrate that a declared 3D Symbolic Index may not be used as a 4D Index, the 3D Index declaration may be canceled by the d4 function with the same argument.

■ Index type represents either 4D Index or 3D Index. The variables are tested by the IndexQ[x] function.

3. TamarA Objects.

This section discusses objects defined in the TamarA package and simplification rules automatically applied to them. All of the definitions are in agreement with Bjorken and Drell [3,4] notation.

3.1. Metric and Kronecker tensors.

The metric tensor is represented by g[Index,Index] function.

Outer[g, l = {0, 1, 2, 3}, l] // MatrixForm

The function is formatted according to traditional physics notation.

g[up[α], β]

Index contraction rules are always applied whenever appropriate. For example, the contravariant index up[a] of g[up[a],b] is automatically summed with the matching covariant index a in g[a,c].

\(\(\(g[
        up[α, β]]\)\(*\)\(g[α, γ]\)\(	\)\)\)

TamarA won’t sum four dimensional objects by a three dimensional index.

\(d3[a]; \(\(g[up[a, β]]\)\(*\)\(g[
        a, γ]\)\(	\)\)\)

In the example above, index a was declared as a three dimensional, consequently the summation rule was not applied.
Summation over an index does not automatically open parentheses. In such cases, the Mathematica function Expand may be useful.

g[up[α, β]]*(g[α, γ] + d)

(d+(Subscript[g, αγ])) (g^(αβ))//Expand

When both arguments are 3D Indices the metric tensor is automatically reduced to the Kronecker delta.

g[d3[a, b]]

The Kronecker delta is represented by the  delta[3DIndex,3DIndex] function. Three dimensional objects may not be used with a 4D Index.

d4[a]; d3[b]; delta[a, b]

Standard summation rules are also applied to three dimensional objects, for example, to delta.

d3[a, b, c]; delta[a, b]*delta[b, c]

3.2. Vectors.

Four dimensional and three dimensional vectors are represented by vec[ExVecName,Index] and vec3[ExVecName,3DIndex] functions correspondingly. 
vec function is formatted according to physics notations, vec3 function has an additional tilde symbol above as in the following example.

d4[a]; vec[c, up[a]]

d3[b]; vec3[c, b]

If a three dimensional index is used with a four dimensional vector, the vector is automatically reduced to three dimensional.

d3[a]; vec[c, a]

If the first argument of vec or vec3 has ExVecName type, the functions are immediately expanded into corresponding linear combinations.

vec[4 (2  a + b) + c, up[μ]]

vec3[4 (2  a + b) + c, d3[i]]

The vector indices are also automatically contracted when appropriate.

3.3. Scalar Product.

Automatic summations often produce scalar products.

vec[a, up[μ]]*vec[b, μ]

d3[i]; vec3[a, i]*vec3[b, i]

Four and three dimensional scalar products are represented by sc[ExVecName,ExVecName] and sc3[ExVecName,ExVecName] functions correspondingly. If arguments have ExVecName type the functions are immediately expanded into the corresponding linear combination.

sc[4 (2  a + b) + c, 2  d]

The special ToD3 function reduces four dimensional scalar products to three dimensional. The ToD4 function has the opposite effect.

2 (a·d)+(b·d)//ToD3

-((Overscript[b, →])·(Overscript[d, →]))+(Subscript[b, 0]) (Subscript[d, 0])+2 (-((Overscript[a, →])·(Overscript[d, →]))+(Subscript[a, 0]) (Subscript[d, 0]))//ToD4

3.4. Absolute anti-symmetric tensors.

Four dimensional and Three dimensional absolute anti-symmetric tensors are represented by eps[Index,Index,Index,Index] and ep3[3DIndex,3DIndex,3DIndex] correspondingly.
Both functions are formatted according to standard physics notations.

3.5. Non-commutative Product.

The non-commutative product of four dimensional matrices is represented by the lg function. The Mathematica NoncommutativeMultiply operator ** is automatically reduced to the lg function. Non-commutative products are formatted as comma separated lists inside of angular brackets.

lg[2  a + b, lg[b, c] + d ** e]

A similar function ls is designed for the product of 2x2  matrices. 
Multiple matrix products are simplified as in the following examples.

lg[lg[a, b], c]

lg[ls[a, b], c]

The difference between lg and ls is minor: automatic simplification rules defined for four gamma matrices are not available in ls and vice versa.

3.6. Gamma and Sigma matrices.

Gamma matrices are represented by gm[Index or 5] function.
If the function is called with more than one argument, the function is immediately substituted by the corresponding product of gamma matrices.

gm[a, up[b], c, 5]

The index of a gamma matrix is also automatically contracted. Sigma matrices are represented by the sg[Index,Index] function. The function is defined as an independent object. It is not replaced by a combination of gamma matrices. The matrix is formatted according to standard physics notations.

3.7. Vector-Contracted Index and Slash Notation.

Standard slash notation is represented by the sl[ExVecName] function. The function is immediately reduced to the proper combination of gamma matrices with 4D Vector Contracted indices. Slash notation is found to be convenient in physics. The notation is used in a more general way in the package. We use a special kind of index, Vector Contracted Index in the notations. The 4D Vector Contracted Index is represented by the v4 function of a vector name.
For example, the expression gm[i]*vec[a,up[i]] = 
 is automatically substituted by gm[v4[a]]. The v4[a] function shows that the index of gm was contracted with a vector named a. In TamarA the v4 function is printed by a bar above the argument.

gm[v4[a]]

The function v4 also takes more than one argument. For example in many shortcuts like

eps[i, v4[a, b, c]]

and

gm[v4[a, b, c]]

Extended slash notation is represented by sl[ExtVecName]. The function is automatically reduced to the corresponding combination of gammas with vector-contracted indices.

sl[4 (2  a + b) + c]

The vector-contracted index is a valid four dimensional index and may be used with any four dimensional object.

3.8. Pauli Matrices.

Pauli matrices are represented by s[3DIndex] function. The function is formatted according to standard physics notation. When more than one argument is used the function is immediately substituted by the corresponding ls matrix product.

s[d3[i, j, k]]

There is a three dimensional analog of the v4 function. Function v3 represents the 3D Vector contracted index. The function looks like a vector sign above the index in output.

d3[i]; vec3[a, i]*s[i]

4. Taking traces.

This section describes various functions related to taking traces.

4.1. Dirac Spinors.

Dirac spinors u and v are represented by u[p,s] and v[p,s] functions correspondingly, where p and s are Vector Names.
The conjugated spinors are represented by ub[p,s] and vb[p,s] functions correspondingly. The second argument of the spinors is optional. If used, it shows that we are interested in polarization. The spinors are formatted according to physics notations.

ub[p, s]

Many automatic simplification rules are defined for the spinors. For example, orthogonality, completeness, Dirac equation, reducing to traces.

4.2. Hermitian Conjugation.

Hermitian conjugation is represented by the cj[Expression] function. The conjugation is formatted according to physics notations.

gm[μ] // cj

4.3. Trace Functions.

Trace taking functions tr are used for four dimensional traces. For example,

⟨(Subscript[γ, α]),(Subscript[γ, β]),(Subscript[γ, γ]),(Subscript[γ, δ])⟩//tr

When more than one argument is used, the input is understood as the non-commutative product of the arguments. For example,

tr[gm[α], gm[β], gm[γ], gm[δ]]

A similar function trs is used for taking traces of 2x2 matrices. For example,

trs[s[d3[i, j, k]]]

Although there is no limit on the length of the arguments, calculation of very long traces may become impractical because of the long execution time.

4.4. Expansion into Basis.

Function ToBasis expands its argument into the Dirac basis. For example,

gm[α, β] // ToBasis

A very similar function ToSBasis expands expressions of 2x2 matrices. For example,

s[d3[i, j, k]] // ToSBasis

The functions may be used for simplification, like in the following example.

⟨(Subscript[σ, (Overscript[a, →])]),(Subscript[σ, (Overscript[b, →])]),(Subscript[σ, (Overscript[c, →])])⟩//ToSBasis

4.5. Automatic Generation of Traces.

The trace function tr may be generated automatically. The following example illustrates this. Let’s consider an amplitude of muon decay.

\(TextForm
    \`μ\^–⟶e\^– + ν\&—\_e + 
      ν\_μ\)

I skip the constant for clarity.

\(M = 
      lg[ub[e], gm[up[α]], 1 + gm[5], v[ν\_e]]*
		lg[
          ub[ν\_μ], gm[α], 1 + gm[5], u[μ]]\)

I multiply M by its Hermitian conjugation. The summation index is substituted to avoid confusion with many repeated indices.

M*cj[M /. α -> β]

The generated tr functions are held until the Mathematica ReleaseHold function is applied. This is done on purpose to give the user a chance to examine intermediate results.

% // ReleaseHold

I need to apply Mathematica Expand and Together functions to simplify the result: Expand opens parenthesizes to make the summations visible, Together collects the expression to a common denominator.

% // Expand // Together

A. Reference.

Metric Tensor.

({{Physics, Output, Input}, {(Subscript[g, αβ]), (Subscript[g, αβ]), g[α, β]}, {(Subscript[g, α]^β), (Subscript[g, α]^β), g[α, up[β]]}, {(g^(αβ)), (g^(αβ)), g[up[α, β]], 
          
g[up[α], up[β]]}})

Gamma Matrices.

({{Physics, Output, Input}, {(Subscript[γ, α]), (Subscript[γ, α]), gm[α]}, {(γ^α), (γ^α), gm[up[α]]}, {(Subscript[γ, 5]), (Subscript[γ, 5]), gm[5]}})

Sigma Matrices.

({{Physics, Output, Input}, {(Subscript[σ, αβ]), (Subscript[σ, αβ]), sg[α, β]}, {(Subscript[σ, ·β]^α), (Subscript[σ, ·β]^α), sg[up[α], β]}, {(σ^(αβ)), (σ^(αβ)), sg[up[α, β]], 
          
sg[up[α], up[β]]}})

Non-Commutative Product.

({{Physics, Output, Input}, {(Subscript[γ, α])(Subscript[γ, β]), ⟨(Subscript[γ, α]),(Subscript[γ, β])⟩, gm[α, β], 
          
gm[α]**gm[β], 
          
lg[gm[α], gm[β]]}, {(Subscript[γ, α]) (a + b (Subscript[γ, β])), ⟨(Subscript[γ, α]),a+b (Subscript[γ, β])⟩, lg[gm[α], a + b*gm[β]]}})

Vectors .

({{Physics, Output, Input}, {(Subscript[p, α]), (Subscript[p, α]), vec[p, α]}, {(p^α), (p^α), vec[p, up[α]]}, {(Subscript[p, α])-2 (Subscript[q, α]), (Subscript[p, α])-2 (Subscript[q, α]), vec[p - 2  q, α]}})

Scalar Product.

({{Physics, Output, Input}, {(a·b), (a·b), sc[a, b]}})

Mass Notation.

({{Physics, Output, Input}, {(Subscript[m, p]), (Subscript[m, p]), m[p]}, {2 (Subscript[m, n])+(Subscript[m, p]), (2 (Subscript[m, n])+(Subscript[m, p])), m[p + 2  n]}})

Slash Notation.

({{Physics, Output, Input}, {\(p\&^ = \(γ\_α\) p\^α\), (Subscript[γ, (Overscript[p, ─])]), sl[p], 
gm[v4[p]]}, {\(\(a\&^\) b\&^\), ⟨(Subscript[γ, (Overscript[a, ─])]),(Subscript[γ, (Overscript[b, ─])])⟩, sl[a, b], 
sl[a]**sl[b], 
          
gm[v4[a, b]], 
          
lg[sl[a], sl[b]], }, {\(p\&^\)(Subscript[γ, α]), ⟨(Subscript[γ, (Overscript[p, ─])]),(Subscript[γ, α])⟩, sl[p]**gm[α], 
          
gm[v4[p], α]}, {\(p\&^ - 2  q\&^\), ((Subscript[γ, (Overscript[p, ─])])-2 (Subscript[γ, (Overscript[q, ─])])), sl[p - 2  q], 
          
sl[p] - 2  sl[q]}})

Absolute anti-symmetric tensor.

({{Physics, Output, Input}, {(Subscript[ϵ, αβγδ]), (Subscript[ϵ, αβγδ]), eps[α, β, γ, δ]}, {(p^β)(Subscript[ϵ, αβγδ]), (Subscript[ϵ, αγδ(Overscript[p, ─])]), eps[α, v4[p], γ, δ]}, {(Subscript[ϵ, ··γδ]^(αβ)), (Subscript[ϵ, ··γδ]^(αβ)), eps[up[α, β], γ, δ]}})

3D Objects.

({{Physics, Output, Input}, {(Subscript[δ, ij]), (Subscript[δ, ij]), delta[i, j]}, {(Subscript[σ, i]), (Subscript[σ, i]), s[i]}, {(Subscript[σ, i]) (Subscript[σ, j]), ⟨(Subscript[σ, i]),(Subscript[σ, j])⟩, s[i, j], 
          
ls[s[i], s[j]]}, {(Subscript[σ, i]) (a + b (Subscript[σ, j])), ⟨(Subscript[σ, i]),a+b (Subscript[σ, j])⟩, ls[s[i], a + b*s[j]]}, {(Subscript[p, i]), (Subscript[(Overscript[p, ∼]), i]), vec3[p, i]}, {(Subscript[p, i]) - 2  (Subscript[q, i]), ((Subscript[(Overscript[p, ∼]), i])-2 (Subscript[(Overscript[q, ∼]), i])), vec3[p - 2  q, i]}, {(Subscript[p, i]) (Subscript[σ, i]), (Subscript[σ, (Overscript[p, →])]), s[v3[p]]}, {((Overscript[a, →])·(Overscript[b, →])), ((Overscript[a, →])·(Overscript[b, →])), sc3[a, b]}, {(Subscript[ϵ, ijk]), (Subscript[ϵ, ijk]), ep3[i, j, k]}, {(Subscript[p, i])(Subscript[ϵ, ijk]), (Subscript[ϵ, ij(Overscript[p, →])]), ep3[i, j, v3[p]]}, {(Subscript[((Overscript[a, →])×(Overscript[b, →])), i]), (Subscript[((Overscript[a, →])×(Overscript[b, →])), i]), ep3[i, v3[a, b]]}, {((Overscript[a, →])·[(Overscript[b, →])×(Overscript[c, →])]), ((Overscript[a, →])·[(Overscript[b, →])×(Overscript[c, →])]), ep3[v3[a, b, c]]}})

Hermitian Conjugation.

({{Physics, Output, Input}, {(SuperDagger[((Subscript[γ, μ]))]), (SuperDagger[((Subscript[γ, μ]))]), cj[gm[μ]]}})

Dirac Spinors.

({{Physics, Output, Input}, {u (p, s), u[p, s], u[p, s]}, {u (p), u[p], u[p]}, {\(\(u\&_\) \((p, s)\)\), \(u\&_[p, s]\), ub[p, s]}, {\(\(u\&_\) \((p)\)\), \(u\&_[p]\), ub[p]}, {v (p, s), v[p, s], v[p, s]}, {v (p), v[p], v[p]}, {\(\(v\&_\) \((p, s)\)\), \(v\&_[p, s]\), vb[p, s]}, {\(\(v\&_\) \((p)\)\), \(v\&_[p]\), vb[p]}})

B. License Agreement and Disclaimer of Warranty.

The author hereby grants permission to use, copy, and distribute this software and its documentation for any purpose, provided that existing copyright notices are retained in all copies and that this notice is included verbatim in any distributions. Additionally, the author grants permission to modify this software and its documentation for any purpose, provided that such modifications are not distributed without the explicit consent of the authors and that existing copyright notices are retained in all copies. Users of the software are asked to feed back problems, benefits, and/or suggestions about the software to the author (tetervak@sc.edu). Support for this software - fixing of bugs, incorporation of new features - is done on a best effort basis. All bug fixes and enhancements will be made available under the same terms and conditions as the original software.
IN NO EVENT SHALL THE AUTHOR OR DISTRIBUTORS BE LIABLE TO ANY PARTY FOR DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OF THIS SOFTWARE, ITS DOCUMENTATION, OR ANY DERIVATIVES THEREOF, EVEN IF THE AUTHOR HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. THE AUTHOR AND DISTRIBUTORS SPECIFICALLY DISCLAIM ANY WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT. THIS SOFTWARE IS PROVIDED ON AN "AS IS" BASIS, AND THE AUTHOR AND DISTRIBUTORS HAVE NO OBLIGATION TO PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.