update exports and docs

Author: lschneiderbauer

NAMESPACE

@@ -16,6 +16,7 @@ export("%_%")
 export(.)
 export(as_a)
 export(asym)
+export(christoffel)
 export(d)
 export(e)
 export(expect_tensor_equal)
@@ -24,7 +25,11 @@ export(g_eucl_sph)
 export(g_mink)
 export(kron)
 export(l)
+export(metric_field)
 export(r)
+export(ricci)
+export(ricci_sc)
+export(riemann)
 export(subst)
 export(sym)
 export(tensor)

R/covd.R

@@ -1,7 +1,27 @@
 # used indices
 globalVariables(c("i", "j", "k", "l", "i2"))
 
-
+#' Christoffel symbols
+#'
+#' Provides the Christoffel symbols of the first kind \eqn{Gamma_{ijk}} with
+#' respect to the Levi Civita connection for a given metric tensor.
+#'
+#' The Christoffel symbols are a rank 3 array of numbers.
+#'
+#' @param g
+#'  A covariant metric tensor, a "metric_field" object. See [metric_field()]
+#'  to create a new metric tensor, or use predefined metrics,
+#'  e.g. [g_eucl_cart()].
+#' @return
+#'  Returns the Christoffel symbols of the first kind \eqn{Gamma_{ijk}}
+#'  as rank 3 [array()].
+#'
+#' @examples
+#' christoffel(g_eucl_sph(3))
+#' @seealso Wikipedia: [Christoffel symbols](https://en.wikipedia.org/wiki/Christoffel_symbols])
+#' @export
+#' @concept geom_tensors
+#' @family geometric tensors
 christoffel <- function(g) {
   stopifnot(inherits(g, "metric_field"))
 
@@ -12,6 +32,21 @@ christoffel <- function(g) {
     as_a(i, k, l)
 }
 
+#' Riemann curvature tensor
+#'
+#' Provides the covariant Riemann curvature tensor \eqn{R_{ijkl}}.
+#'
+#' @inheritParams christoffel
+#' @return
+#'  Returns the covariant Riemann curvature tensor \eqn{R_{ijkl}}
+#'  as rank 4 [array()].
+#'
+#' @examples
+#' riemann(g_eucl_sph(3))
+#' @seealso Wikipedia: [Riemann curvature tensor](https://en.wikipedia.org/wiki/Riemann_curvature_tensor)
+#' @export
+#' @concept geom_tensors
+#' @family geometric tensors
 riemann <- function(g) {
   stopifnot(inherits(g, "metric_field"))
 
@@ -24,11 +59,40 @@ riemann <- function(g) {
     as_a(i2, k, j, l)
 }
 
+#' Ricci curvature tensor
+#'
+#' Provides the covariant Ricci curvature tensor \eqn{R_{ij}=R^{s}_{i s j}}.
+#'
+#' @inheritParams christoffel
+#' @return
+#'  Returns the covariant Ricci curvature tensor \eqn{R_{ij}}
+#'  as rank 2 [array()].
+#'
+#' @examples
+#' ricci(g_eucl_sph(3))
+#' @seealso Wikipedia: [Ricci curvature tensor](https://en.wikipedia.org/wiki/Riemann_curvature_tensor#Ricci_curvature)
+#' @export
+#' @concept geom_tensors
+#' @family geometric tensors
 ricci <- function(g) {
   (riemann(g) %_% .(i, j, k, l) * g %_% .(+i, +k)) |>
     as_a(j, l)
 }
 
+#' Ricci scalar
+#'
+#' Provides the Ricci scalar \eqn{R}.
+#'
+#' @inheritParams christoffel
+#' @return
+#'  Returns the Ricci scalar \eqn{R} as single number/expression.
+#'
+#' @examples
+#' ricci_sc(g_eucl_sph(3))
+#' @seealso Wikipedia: [Ricci scalar](https://en.wikipedia.org/wiki/Scalar_curvature)
+#' @export
+#' @concept geom_tensors
+#' @family geometric tensors
 ricci_sc <- function(g) {
   (ricci(g) %_% .(i, j) * g %_% .(+i, +j)) |> as_a()
 }

R/metric_field.R

@@ -9,6 +9,34 @@ new_metric_field <- function(metric, coords, metric_inv) {
   )
 }
 
+#' Create a metric tensor field
+#'
+#' Metric tensors are an essential ingredient of (Pseudo-) Riemannian
+#' manifolds and define distance relations between points.
+#' They are used to define geometric tensors such as e.g. the Ricci curvature
+#' [ricci()], and a metric connection, i.e. a covariant derivative.
+#' They are also essential for raising and lowering indices of tensor fields
+#' correctly when using non-flat coordinates.
+#'
+#' @param metric
+#'  A `nxn` matrix / array representing the covariant metric tensor components.
+#'  The components are usually expressions as character strings formed from
+#'  coordinates, since numeric values can only represent constant tensor fields.
+#'
+#' @param metric_inv
+#'  A `nxn` matrix / array representing the contraviant metric tensor components,
+#'  i.e. the inverse matrix of the covariant metric tensor component matrix.
+#'
+#' @param coords
+#'  A character vector of `n` coordinate names that are used in the component
+#'  expressions. This information is essential
+#'  for forming symbolic derivatives.
+#'
+#' @seealso Wikipedia: [Metric tensor](https://en.wikipedia.org/wiki/Metric_tensor)
+#' @concept metric_tensors
+#' @family metric tensors
+#'
+#' @export
 metric_field <- function(metric, metric_inv, coords) {
   stopifnot(is.array(metric))
   stopifnot(is.character(coords))

R/tensor_instances.R

@@ -18,7 +18,7 @@
 #'
 #' d(3)(i, j, +k, +l)
 #' @export
-#' @concept tensor_instance
+#' @concept tensor_symbols
 #' @family tensor symbols
 d <- function(n) {
   function(...) {
@@ -59,7 +59,7 @@ d <- function(n) {
 #' e(i, j, k)
 #' @seealso Wikipedia: [Levi-Civita symbol](https://en.wikipedia.org/wiki/Levi-Civita_symbol)
 #' @export
-#' @concept tensor_instance
+#' @concept tensor_symbols
 #' @family tensor symbols
 e <- function(...) {
   i <- .(...)
@@ -90,7 +90,7 @@ e <- function(...) {
 #' g_mink(4)
 #' g_mink(4) %_% .(+i, +j)
 #' @export
-#' @concept tensor_instance
+#' @concept metric_tensors
 #' @family metric tensors
 g_mink <- function(n, coords = paste0("x", 1:n - 1)) {
   metric_field(
@@ -124,7 +124,7 @@ g_mink <- function(n, coords = paste0("x", 1:n - 1)) {
 #' g_eucl_cart(3)
 #' g_eucl_cart(3) %_% .(+i, +j)
 #' @export
-#' @concept tensor_instance
+#' @concept metric_tensors
 #' @family metric tensors
 #' @rdname g_eucl
 g_eucl_cart <- function(n, coords = paste0("x", 1:n)) {

R/tensor_ops.R

@@ -8,8 +8,9 @@
 #'
 #' @param x  A labeled tensor object, created by [`%_%`] or [tensor()].
 #' @param g
-#'  An (unlabeled) covariant metric tensor as array used for raising and
-#'  lowering indices.
+#'  A covariant metric tensor, a "metric_field" object. See [metric_field()]
+#'  to create a new metric tensor, or use predefined metrics,
+#'  e.g. [g_eucl_cart()].
 #'  If no metric tensor is provided, indices are raised/lowered with
 #'  the identity matrix.
 #' @param ... Any number of index expressions. The indices need to occur

_pkgdown.yml

@@ -10,9 +10,15 @@ reference:
 - title: "Tensor operations"
   contents:
   - has_concept("tensor_ops")
-- title: "Predefined tensors"
+- title: "Tensor symbols"
   contents:
-  - has_concept("tensor_instance")
+  - has_concept("tensor_symbols")
+- title: "Metrics tensor fields"
+  contents:
+  - has_concept("metric_tensors")
+- title: "Geometric tensor fields"
+  contents:
+  - has_concept("geom_tensors")
 - title: "Testthat expectation"
   contents:
   - expect_tensor_equal