From 91d3beee8fbc06088c1694d24208d59f4002df47 Mon Sep 17 00:00:00 2001
From: Matthew Scroggs <matthew.w.scroggs@gmail.com>
Date: Mon, 22 Apr 2024 17:59:03 +0100
Subject: [PATCH] Document transpose data storate for blocked elements (#3156)

* Add dof transformation docs

* Doc updates

* correct (?) and document transpose data storage for blocked elements

* that's a permutation not a transformation

* Update cpp/dolfinx/fem/FiniteElement.h

* Update cpp/dolfinx/fem/FiniteElement.h

* better doc

---------

Co-authored-by: Garth N. Wells <gnw20@cam.ac.uk>
---
 cpp/dolfinx/fem/FiniteElement.cpp | 2 +-
 cpp/dolfinx/fem/FiniteElement.h   | 8 ++++++--
 2 files changed, 7 insertions(+), 3 deletions(-)

diff --git a/cpp/dolfinx/fem/FiniteElement.cpp b/cpp/dolfinx/fem/FiniteElement.cpp
index f80ed3fb1a9..9704258c561 100644
--- a/cpp/dolfinx/fem/FiniteElement.cpp
+++ b/cpp/dolfinx/fem/FiniteElement.cpp
@@ -617,7 +617,7 @@ FiniteElement<T>::dof_permutation_fn(bool inverse, bool scalar_element) const
     }
     else if (!scalar_element)
     {
-      // Vector element
+      // Blocked element
       std::function<void(std::span<std::int32_t>, std::uint32_t)>
           sub_element_function = _sub_elements[0]->dof_permutation_fn(inverse);
       int dim = _sub_elements[0]->space_dimension();
diff --git a/cpp/dolfinx/fem/FiniteElement.h b/cpp/dolfinx/fem/FiniteElement.h
index e811680ae17..fdfe33cb899 100644
--- a/cpp/dolfinx/fem/FiniteElement.h
+++ b/cpp/dolfinx/fem/FiniteElement.h
@@ -336,7 +336,7 @@ class FiniteElement
       }
       else if (!scalar_element)
       {
-        // Vector element
+        // Blocked element
         std::function<void(std::span<U>, std::span<const std::uint32_t>,
                            std::int32_t, int)>
             sub_function
@@ -438,7 +438,11 @@ class FiniteElement
       }
       else if (!scalar_element)
       {
-        // Vector element
+        // Blocked element
+        // The transformation from the left can be used here as blocked
+        // elements use xyzxyzxyz ordering, and so applying the DOF
+        // transformation from the right is equivalent to applying the DOF
+        // transformation from the left to data using xxxyyyzzz ordering
         std::function<void(std::span<U>, std::span<const std::uint32_t>,
                            std::int32_t, int)>
             sub_function