Repository files navigation

The goal of {ricci} is to provide acompact¹ R interface forperformingtensorcalculations. This isachieved by allowing (upper and lower) index labeling of R’sarray andmaking use of Ricci calculus conventions toimplicitly triggercontractions and diagonal subsetting. Explicit tensor operations,such asaddition, subtraction and multiplication of tensors via thestandard operators (*,+,-,/,==),raising and loweringindices, takingsymmetric orantisymmetric tensor parts, aswell as theKronecker product are available. Common tensors like theKronecker delta, Levi Civita epsilon, certain metric tensors, theChristoffel symbols, the Riemann as well as Ricci tensors are provided.Thecovariant derivative of tensor fields with respect to any metrictensor can be evaluated. An effort was made to provide the user withuseful error messages.

{ricci} uses thecalculus package(Guidotti 2022) behind the scenes to perform calculations and providesan alternative interface to a subset of its functionality.{calculus} supports symboliccalculations, allowing {ricci} to support it as well. Symbolicexpressions are optionally simplified if theRyacas package is installed.

You can install the latest CRAN release of ricci with:

install.packages("ricci")

Alternatively, you can install the development version of ricci fromGitHub with:

# install.packages("pak")pak::pak("lschneiderbauer/ricci")

The central object is R’sarray. Adding index slot labels allows us toperform common tensor operations implicitly. After the desiredcalculations have been carried out we can remove the labels to obtain anordinaryarray.

The following (admittedly very artificial) example shows how to expressthe contraction of two tensors, and subsequent symmetrization anddiagonal subsetting. For demonstration purposes we use an arbitraryarray of rank 3.

library(ricci)# numeric dataa<-array(1:(2^3),dim= c(2,2,2))# create labeled array (tensor)(a %_% .(i,j,k)*# mutliply with a labeled array (tensor) and raise index i and ka %_% .(i,l,k)|> r(i,k,g= g_mink_cart(2)))|># * -i and +i as well as -k and +k dimension are implictely contracted# the result is a tensor of rank 2  sym(j,l)|># symmetrize over i and l  subst(l->j)|># rename index and trigger diagonal subsetting  as_a(j)# we unlabel the tensor with index order (j)#> [1] 8 8

The same instructions work for a symbolic array:

# enable optional simplfying procedures# (takes a toll on performance)options(ricci.auto_simplify=TRUE)# symbolic dataa<-array(paste0("a",1:(2^3)),dim= c(2,2,2))(a %_% .(i,j,k)*# mutliply with a labeled array (tensor) and raise index i and ka %_% .(i,l,k)|> r(i,k,g= g_mink_cart(2)))|># * -i and +i as well as -k and +k dimension are implictely contracted# the result is a tensor of rank 2  sym(j,l)|># symmetrize over i and l  subst(l->j)|># rename index and trigger diagonal subsetting  as_a(j)# we unlabel the tensor with index order (j)#> [1] "a1^2+a6^2-(a5^2+a2^2)" "a3^2+a8^2-(a7^2+a4^2)"

Another main feature is the covariant derivative of symbolic arrays. Thefollowing examples calculate the Hessian matrix as well as the Laplacianof the scalar function$\sin(r)$ in spherical coordinates in threedimensions.

$$D_{ik} = \nabla_i \nabla_k \sin(r)$$

covd("sin(r)", .(i,k),g= g_eucl_sph(3))|>  simplify()#> <Labeled Array> [3x3] .(-i, -k)#>      [,1]      [,2]       [,3]#> [1,] "-sin(r)" "0"        "0"#> [2,] "0"       "r*cos(r)" "0"#> [3,] "0"       "0"        "r*sin(ph1)^2*cos(r)"

$$\Delta \sin(r) = \nabla_i \nabla^i \sin(r)$$

covd("sin(r)", .(i,+i),g= g_eucl_sph(3))|>  simplify()#> <Scalar>#> [1] "(2*cos(r)-r*sin(r))/r"

The covariant derivative can not only be taken from scalars, but generalindexed tensors, as the following example, involving the curl of$a$,shows.

$$\left(\nabla \times a\right)^i = \varepsilon^{i}_{;jk} \nabla^j a^k$$

g<- g_eucl_sph(3)a<- c(0,1,0)(a %_% .(+k)|> covd(.(+j),g=g)*  e(i,j,k)|> r(i,g=g))|>  simplify()#> <Labeled Array> [3] .(+i)#> [1] "0"                  "0"                  "2/(r^3*sin(ph1)^2)"

For more details, seevignette("ricci", package = "ricci"). For moreinformation about how to use tensor fields and the covariant derivative,seevignette("tensor_fields", package = "ricci").