Line data    Source code

       1            0 : \cond NEVER
       2              : Distributed under the MIT License.
       3              : See LICENSE.txt for details.
       4              : \endcond
       5              : # Using Variables in SpECTRE {#variables_foundations}
       6              : 
       7              : # What is a Variables and Why Use Them?
       8              : Variables are a data structure that hold a contiguous memory block with Tensors
       9              : pointing to it. Variables temporaries allow you to declare temporary tensors and
      10              : scalars so that you can do all allocations needed for a computation at one time.
      11              : Since physical memory is shared between CPU cores, processes can't allocate in
      12              : parallel since they might try to allocate to the same chunk of memory. As more
      13              : CPU cores are used, this becomes a bottleneck, slowing down or stopping other
      14              : processes while memory is being allocated. Using a Variables to allocate all
      15              : memory needed at once can improve efficiency allowing the computation to
      16              : operate smoothly and uninterrupted.
      17              : 
      18              : # Defining a Variables of Temporary Tags
      19              : To define a Variables, you'll need the TempTensor and Variables headers
      20              : ```cpp
      21              : #include "DataStructures/Tags/TempTensor.hpp"
      22              : #include "DataStructures/Variables.hpp"
      23              : ```
      24              : this will give you access to temporary Scalars and Tensors we'll need to
      25              : allocate. You can define a Variables that allocates one Scalar with something
      26              : like this:
      27              : ```cpp
      28              : Variables<tmpl::list<::Tags::TempScalar<0>>>
      29              : temp_buffer{get<0,0>(spatial_metric).size()};
      30              : ```
      31              : Here, the Variables we've defined `temp_buffer` provides a tmpl::list with a
      32              : TempScalar inside as the template argument, this will allocate a single
      33              : temporary scalar. The size and DataType of the TempScalar is deduced by what's
      34              : inside the {}, you can provide any tensor or std::array with the correct size
      35              : needed. Now, to use the allocation you've made, you can do:
      36              : ```cpp
      37              : auto& useful_scalar = get<::Tags::TempScalar<0>>(temp_buffer);
      38              : ```
      39              : 
      40              : # Real Use Example
      41              : Now that we've got the basics, using them to allocate multiple Scalars and
      42              : Tensors is quite easy. For instance, let's say I need to allocate 2 scalars,
      43              : a spatial vector and 2 lower rank 2 tensors for my function.
      44              : ```cpp
      45              : Variables<tmpl::list<::Tags::TempScalar<0>, ::Tags::TempScalar<1>,
      46              : ::Tags::TempI<0, 3, Frame::Inertial>, ::Tags::Tempij<0, 3, Frame::Inertial>,
      47              : ::Tags::Tempij<1, 3, Frame::Inertial>>>
      48              : temp_buffer{get<0,0>(spatial_metric).size()};
      49              : ```
      50              : Here, when we allocate for the same type of scalar or tensor (rank 2 lower) the
      51              : way we distinguish multiple allocations is through the number within the <>.
      52              : Now, to use each individual allocation, we can do something like:
      53              : ```cpp
      54              : auto& cool_scalar1 = get<::Tags::TempScalar<0>>(temp_buffer);
      55              : auto& cool_scalar2 = get<::Tags::TempScalar<1>>(temp_buffer);
      56              : auto& cool_tensor1 = get<::Tags::Tempij<0, 3, Frame::Inertial>>(temp_buffer);
      57              : auto& cool_tensor2 = get<::Tags::Tempij<1, 3, Frame::Inertial>>(temp_buffer);
      58              : ```
      59              : 
      60              : # Tips
      61              : In the interest of reducing memory allocations, there a certain scenarios where
      62              : you can resuse old allocations that are no longer useful to your computation.
      63              : 
      64              : To see this, let's say that you're trying to make two unit vectors. You might
      65              : start by saying you'll need two different vectors (rank 1 upper tensors) and 2
      66              : different scalars as the magnitude of each vector.
      67              : The way we'd allocate for this is by doing:
      68              : ```cpp
      69              : Variables<tmpl::list<::Tags::TempScalar<0>, ::Tags::TempScalar<1>,
      70              : ::Tags::TempI<0, 3, Frame::Inertial>, ::Tags::TempI<1, 3, Frame::Inertial>>>
      71              : temp_buffer{get<0,0>(spatial_metric).size()};
      72              : ```
      73              : However, doing this allocates more memory than we actually need. Once we finish
      74              : calculating the first unit vector, the memory we've allocated for the scalar
      75              : magnitude of the first vector will just sit there unused. We can reuse the
      76              : allocation for the TempScalar<0> and use it when calculating the second unit
      77              : vector without having to allocate another TempScalar. Now, allocating an extra
      78              : scalar is not very expensive, but when using tensors, the memory required really
      79              : adds up, so this is just another way to help make SpECTRE a bit more efficient.