From 45d0f55d72b8bb81610e7d47b13770d0581686d6 Mon Sep 17 00:00:00 2001
From: Wolfgang Bangerth <bangerth@math.tamu.edu>
Date: Fri, 25 Mar 2016 15:28:39 -0500
Subject: [PATCH] Define product between a vector and a symmetric tensor.

Also update some confusing pieces of documentation.
---
 doc/news/changes.h                      |  8 +++++++
 include/deal.II/base/symmetric_tensor.h | 29 ++++++++++++++++---------
 2 files changed, 27 insertions(+), 10 deletions(-)

diff --git a/doc/news/changes.h b/doc/news/changes.h
index f47409cb59..8f76112a59 100644
--- a/doc/news/changes.h
+++ b/doc/news/changes.h
@@ -111,6 +111,14 @@ inconvenience this causes.
 <h3>Specific improvements</h3>
 
 <ol>
+ <li> New: The product of a rank-1 tensor (a vector) and a rank-2
+ symmetric tensor (a symmetric matrix) is now defined and yields
+ a rank-1 tensor (a vector). The opposite product was previously
+ already defined.
+ <br>
+ (Wolfgang Bangerth, 2016/03/25)
+ </li>
+
  <li> Fixed: DoFHandler::locally_owned_dofs() could create a segmentation
  fault in cases where some processors do not own any cells. This was caused
  by an incorrect computation in DoFTools::locally_owned_dofs_per_subdomain().
diff --git a/include/deal.II/base/symmetric_tensor.h b/include/deal.II/base/symmetric_tensor.h
index 4743fd22ad..671a1c3301 100644
--- a/include/deal.II/base/symmetric_tensor.h
+++ b/include/deal.II/base/symmetric_tensor.h
@@ -3067,16 +3067,8 @@ double_contract (SymmetricTensor<2,3,Number> &tmp,
 
 
 /**
- * Multiplication operator performing a contraction of the last index of the
- * first argument and the first index of the second argument. This function
- * therefore does the same as the corresponding <tt>contract</tt> function,
- * but returns the result as a return value, rather than writing it into the
- * reference given as the first argument to the <tt>contract</tt> function.
- *
- * Note that for the <tt>Tensor</tt> class, the multiplication operator only
- * performs a contraction over a single pair of indices. This is in contrast
- * to the multiplication operator for symmetric tensors, which does the double
- * contraction.
+ * Multiply a symmetric rank-2 tensor (i.e., a matrix) by a rank-1 tensor
+ * (i.e., a vector). The result is a rank-1 tensor (i.e., a vector).
  *
  * @relates SymmetricTensor
  * @author Wolfgang Bangerth, 2005
@@ -3094,6 +3086,23 @@ operator * (const SymmetricTensor<2,dim,Number> &src1,
 }
 
 
+/**
+ * Multiply a rank-1 tensor (i.e., a vector) by a symmetric rank-2 tensor
+ * (i.e., a matrix). The result is a rank-1 tensor (i.e., a vector).
+ *
+ * @relates SymmetricTensor
+ * @author Wolfgang Bangerth, 2005
+ */
+template <int dim, typename Number>
+Tensor<1,dim,Number>
+operator * (const Tensor<1,dim,Number> &src1,
+            const SymmetricTensor<2,dim,Number> &src2)
+{
+  // this is easy for symmetric tensors:
+  return src2 * src1;
+}
+
+
 /**
  * Output operator for symmetric tensors of rank 2. Print the elements
  * consecutively, with a space in between, two spaces between rank 1
-- 
2.39.5