DOFVector.md 15.2 KB
Newer Older
Praetorius, Simon's avatar
Praetorius, Simon committed
1
2
3
4
5
# DOFVector and DiscreteFunction {: #group-dofvector }
## Summary
The class [`DOFVector`](#class-dofvector) acts as a container for storing the coefficients of the solution discrete function.
It is attached to a global basis to give its coefficients a meaning. A [`DiscreteFunction`](#class-discretefunction) goes
one step further and transforms a DOFVector or subspaces of a DOFVector (with respecto to a sub basis)
Müller, Felix's avatar
Müller, Felix committed
6
into a [`GridFunction`](../GridFunctions) that allows to use it like a function defined on a grid.
Praetorius, Simon's avatar
Praetorius, Simon committed
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25

Let $`\{\phi_i\}`$ be the set of basis functions of a finite-element space $`V`$. A function $`u\in V`$ can be represented
as
```math
u(\mathbf{x}) = \sum_i u_i \phi_i(\mathbf{x})
```
with coefficients $`(u_i)`$.

The pair $`\{(u_i),\{\phi_i\}\}`$ is called `DOFVector` and the function $`u=u(\mathbf{x})`$ is called `DiscreteFunction`.

### Classes

 Class                          | Descriptions
--------------------------------|---------------------------------------------
[`DOFVector`](#class-dofvector) | Standard container for storing solution coefficients associated to a functionspace basis
[`DiscreteFunction`](#class-discretefunction) | Wrapper that transforms a DOFVector into a GridFunction


## class `DOFVector`
26
Defined in header [`<amdis/DOFVector.hpp>`](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/DOFVector.hpp)
Praetorius, Simon's avatar
Praetorius, Simon committed
27
28
29
30

```c++
template <class GB,
          class T = double,
Müller, Felix's avatar
Müller, Felix committed
31
          class Traits = BackendTraits<GB>>
Praetorius, Simon's avatar
Praetorius, Simon committed
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
class DOFVector
  : public VectorFacade<T, Traits::template VectorImpl>
```

`DOFVector` is a vector data-structure for the coefficients of a discrete function associated to a GlobalBasis `GB`.

The template parameter `GB` defines the global basis type and `T` the value type of the coefficients
in the vector. It defaults to `double`. The third parameter `Traits` is a collection of parameters
characterizing the Linear-Algebra backend. It defaults to the default backend Traits.

### Member Types

 Member Type                    | Definition
--------------------------------|---------------------------------------------
`GlobalBasis`                   | `GB`
`Traits`                        | `Traits`
`size_type`                     | `typename GlobalBasis::size_type`
`value_type`                    | `typename Backend::value_type`

The `value_type` is often the same as `T`, but might be just something similar, like `PetscScalar`.

### Member functions

 Function                       | Descriptions
--------------------------------|---------------------------------------------
[*(constructor)*](#function-dofvectordofvector)               | Construct the DOFVector
[`backup`](#function-dofvectorbackup)                         | Write DOFVector to file
[`restore`](#function-dofvectorrestore)                       | Read backup data from file
[`dataTransfer`](#function-dofvectordataTransfer)             | Return the associated DataTransfer object

Müller, Felix's avatar
Müller, Felix committed
62
??? seealso "Functions inherited from [`VectorFacade`](../MatVecFacade/#class-vectorfacade)"
Praetorius, Simon's avatar
Praetorius, Simon committed
63
64
    Function                       | Descriptions
    --------------------------------|---------------------------------------------
Müller, Felix's avatar
Müller, Felix committed
65
66
67
68
69
70
71
72
73
74
    [`impl`](../MatVecFacade#function-vectorbasebackend)                | Return the backend vector wrapper implementing the actual algebra
    [`localSize,globalSize`](../MatVecFacade#function-vectorbasesize)   | The number of entries in the local part of the vector
    [`resize,resizeZero`](../MatVecFacade#function-vectorbaseglobalSize)| Resize the vector to the size of the basis
    [`init`](../MatVecFacade#function-vectorbaseglobalSize)             | Prepare the vector for insertion of values
    [`finish`](../MatVecFacade#function-vectorbaseglobalSize)           | Finish the insertion of values
    [`at`](../MatVecFacade#function-vectorbaseat)                       | Return the value of the vector at the given local index
    [`insert,set,add`](../MatVecFacade#function-vectorbaseinsert)       | Insert a single value into the matrix
    [`gather`](../MatVecFacade#function-vectorbasegather)               | Extract values from the vector referring to the given local indices
    [`scatter`](../MatVecFacade#function-vectorbasescatter)             | Insert a block of values into the vector
    [`forEach`](../MatVecFacade#function-vectorbasescatter)             | Apply a functor to each value at given indices
Praetorius, Simon's avatar
Praetorius, Simon committed
75
76
77
78
79
80


## function `DOFVector::DOFVector`
```c++
template <class Basis>
DOFVector(Basis&& basis, DataTransferOperation op = INTERPOLATE)
Müller, Felix's avatar
Müller, Felix committed
81
82
83

template <class GV, class PBF>
DOFVector(GV const& gridView, PBF const& preBasisFactory, DataTransferOperation op = INTERPOLATE)
Praetorius, Simon's avatar
Praetorius, Simon committed
84
85
```

Müller, Felix's avatar
Müller, Felix committed
86
Constructs the DOFVector from a given global basis or a grid view and a basis factory, and optionally a DataTransferOperation that defines how the DOFVector is handled during grid adaption.
Praetorius, Simon's avatar
Praetorius, Simon committed
87
88
89

#### Arguments
`Basis basis`
Müller, Felix's avatar
Müller, Felix committed
90
91
92
93
94
95
96
:   Either a `shared_ptr` to the `GlobalBasis` type or anything that can be converted to that, e.g. a reference or a `unique_ptr`. References to lvalues are wrapped into non-destroying `shared_ptr`s whereas rvalue-references are moved into new basis objects.

`GV gridView`
:   A grid view provided by the grid

`PBF preBasisFactory`
:   A factory to create a pre-basis, see [the ref page on GlobalBasis](../GlobalBasis#making-a-prebasis)
Praetorius, Simon's avatar
Praetorius, Simon committed
97
98
99
100
101
102
103
104
105
106

`DataTransferOperation op`
:   The operation performed during data-transfer, either `DataTransferOperation::INTERPOLATE` or `DataTransferOperation::NO_OPERATION`

#### Example
```c++
using Grid = Dune::YaspGrid<2>;
Grid grid({1.0, 1.0}, {2, 2});

using namespace Dune::Functions::BasisFactory;
107
GlobalBasis basis1(grid.leafGridView(), lagrange<2>());
Praetorius, Simon's avatar
Praetorius, Simon committed
108
109
110
111

DOFVector<decltype(basis1)> vec0(basis1);
DOFVector vec1(basis1);                     // C++17 only

112
auto basis2 = makeUniquePtr(GlobalBasis{grid.leafGridView(), lagrange<2>()});
Praetorius, Simon's avatar
Praetorius, Simon committed
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
DOFVector<Underlying_t<decltype(basis2)>> vec2(std::move(basis2));
```

#### See Also
- Generator function to construct a DOFVector: [`makeDOFVector()`](#function-makedofvector)


## function `DOFVector::backup`
```c++
void backup(std::string const& filename);
```

Writes the coefficients of the DOFVector to file. Thereby the data is first extracted element-wise and then
written using binary ofstreams.

#### Arguments
`std::string filename`
:   The filename of the backup file that is created.


## function `DOFVector::restore`
```c++
void restore(std::string const& filename);
```

Reads a backup of the DOFVector from file previously created using the [backup()](#function-dofvectorbackup) function.

#### Arguments
`std::string filename`
:   The filename of the backup file to read from.


## function `makeDOFVector`
146
Defined in header [`<amdis/DOFVector.hpp>`](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/DOFVector.hpp)
Praetorius, Simon's avatar
Praetorius, Simon committed
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164

```c++
template <class T = double,
          class Basis>
DOFVector<...> makeDOFVector(Basis&& basis, DataTransferOperation op = INTERPOLATE)
```

Creates a DOFVector from a basis.

This generator function accepts the basis as reference, temporary, or
`shared_ptr`. Internally the reference is wrapped into a non-destroying
`shared_ptr` and the temporary is moved into a new `shared_ptr`, see [DOFVector::DOFVector](#function-dofvectordofvector).

The `DataTransferOperation` controls what is done during grid changes with the
DOFVector. The default is interpolation of the data to the new grid.

#### Arguments
`Basis basis`
165
:   Reference, temporary, or `shared_ptr` to dune global basis or `GlobalBasis`
Praetorius, Simon's avatar
Praetorius, Simon committed
166
167
168
169
170
171
172
173
174

`DataTransferOperation op`
:   The operation performed during data-transfer, either `DataTransferOperation::INTERPOLATE` or `DataTransferOperation::NO_OPERATION`

#### Template types
`T`
:   The type of the coefficients to store in the DOFVector

#### Return value
175
Returns a `DOFVector<GB, T>` with `GB = GlobalBasis<typename Underlying_t<Basis>::PreBasis>`. The
Praetorius, Simon's avatar
Praetorius, Simon committed
176
177
178
179
180
181
182
underlying type is either the `remove_cvref_t` for references, or the pointed-to type for smart pointers.

#### Example
```c++
using namespace Dune::Functions::BasisFactory;

// pass a reference to the basis
183
GlobalBasis basis1(gridView, lagrange<2>());
Praetorius, Simon's avatar
Praetorius, Simon committed
184
185
186
187
188
189
190
191
192
auto vec1 = makeDOFVector<double>(basis1);

// pass a smart pointer
auto basis2 = std::make_shared<decltype(basis1)>(basis1);
auto vec2 = makeDOFVector(basis2, DataTransferOperation::NO_OPERATION);
```


## class `DiscreteFunction`
193
Defined in header [`<amdis/gridfunctions/DiscreteFunction.hpp>`](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/amdis/gridfunctions/DiscreteFunction.hpp)
Praetorius, Simon's avatar
Praetorius, Simon committed
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247

```c++
template <class Coefficients,
          class GlobalBasis,
          class TreePath>
class DiscreteFunction
```

A `DiscreteFunction` is the interpretation of a `DOFVector` as grid function.

### Template parameters
`Coefficients`
:   Type of the coefficient vector

`GlobalBasis`
:   The type of the global basis associated with the DOFVector

`TreePath`
:   The path in the basis tree representing the subspace represented by this DiscreteFunction

### Member Types

 Member Type         | Definition
---------------------|---------------------------------------------
`EntitySet`          | Set of entities the DiscreteFunction is defined on, `GridViewEntitySet<GlobalBasis::GridView, 0>`
`Domain`             | Global coordinates of the EntitySet
`Range`              | Range type of this DiscreteFunction, given by sub-tree and coefficient type

### Member functions of the const DiscreteFunction

 Function                       | Descriptions
--------------------------------|---------------------------------------------
[*(constructor)*](#function-discretefunctiondiscretefunction) | Construct the const DiscreteFunction
[`entitySet`](#function-discretefunctionentityset)            | Return the stored GridViewEntitySet
[`basis`](#function-discretefunctionbasis)                    | Return global basis bound to the DOFVector
[`treePath`](#function-discretefunctiontreepath)              | Return the treePath associated with this discrete function
[`coefficients`](#function-discretefunctioncoefficients)      | Return const coefficient vector
[`child`](#function-discretefunctionchild)                    | Return the sub-range view of this DiscreteFunction

### Member functions of the mutable DiscreteFunction

 Function                       | Descriptions
--------------------------------|---------------------------------------------
[*(constructor)*](#function-discretefunctiondiscretefunction)  | Construct the mutable DiscreteFunction
[`interpolate_noalias`](#function-discretefunctioninterpolate) | Interpolation of GridFunction to DOFVector assuming no aliasing
[`interpolate`](#function-discretefunctioninterpolate)         | Interpolation of GridFunction to DOFVector
[`operator<<`](#function-discretefunctioninterpolate)          | Interpolation of GridFunction to DOFVector
[`operator+=`](#function-discretefunctioninterpolate)          | Accumulated interpolation of GridFunction to DOFVector
[`operator-=`](#function-discretefunctioninterpolate)          | Accumulated interpolation of GridFunction to DOFVector


## function `DiscreteFunction::DiscreteFunction`
```c++
// (1)
Müller, Felix's avatar
Müller, Felix committed
248
DiscreteFunction(DOFVector<GlobalBasis,T> const& dofVector, GlobalBasis const& basis,
Praetorius, Simon's avatar
Praetorius, Simon committed
249
250
                 TreePath const& treePath = {})
// (2)
Müller, Felix's avatar
Müller, Felix committed
251
DiscreteFunction(DOFVector<GlobalBasis,T>& dofVector, GlobalBasis const& basis,
Praetorius, Simon's avatar
Praetorius, Simon committed
252
253
254
255
256
257
258
259
260
261
262
                 TreePath const& treePath = {})
```

Construction of a `DiscreteFunction` from a const (1) or mutable (2) `DOFVector`. The corresponding constructor is
only available for the const or mutable `is_const` template parameter specialization.

#### Arguments
`DOFVector<...> dofvector`
:   The container storing the global coefficients. Is stored as pointer in the DiscreteFunction and thus must have a longer lifetime
    than the DiscreteFunction.

Müller, Felix's avatar
Müller, Felix committed
263
264
265
`GlobalBasis const& basis`
:   The global basis associated with the dofvector.

Praetorius, Simon's avatar
Praetorius, Simon committed
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
`TreePath treePath`
:   A `Dune::TypeTree::HybridTreePath<...>` representing the coordinates of a node in the basis tree this DiscreteFunction is
    defined on. The type of the treePath also defines the `Range` type of the DiscreteFunction.


## function `DiscreteFunction::entitySet`
```c++
EntitySet const& entitySet() const
```

Returns a `Dune::Functions::GridViewEntitySet` of the `GridView` associated to the `GlobalBasis`.


## function `DiscreteFunction::basis`
```c++
std::shared_ptr<GlobalBasis const> basis() const
```

Returns the global basis bound to the DOFVector.


## function `DiscreteFunction::treePath`
```c++
TreePath const& treePath() const
```

Returns the treePath associated with this DiscreteFunction.


## function `DiscreteFunction::coefficients`
```c++
DOFVector<GB,VT> const& coefficients() const  // (1)
DOFVector<GB,VT>&       coefficients()        // (2)
```

Returns the const (1) or mutable (2) coefficient vector.


## function `DiscreteFunction::child`
```c++
// (1)
307
308
template <class... Indices>
auto child(Indices... ii) const
Praetorius, Simon's avatar
Praetorius, Simon committed
309
310

// (2)
311
312
template <class... Indices>
auto child(Indices... ii)
Praetorius, Simon's avatar
Praetorius, Simon committed
313
314
315
316
317
```

Returns the const (1) or mutable (2) sub-range view of the stored DOFVector.

#### Arguments
318
319
`Indices... ii`
:   Components of the tree-path identifying a node in the basis tree.
Praetorius, Simon's avatar
Praetorius, Simon committed
320
321
322

#### Example
```c++
323
GlobalBasis basis{gridView, power<3>(lagrange<1>())};
Praetorius, Simon's avatar
Praetorius, Simon committed
324
auto vec = makeDOFVector(basis);
325
auto df = valueOf(vec);
Praetorius, Simon's avatar
Praetorius, Simon committed
326
327
328
329

auto df1 = df.child();
auto df2 = df.child(0);
auto df3 = df.child(_0);
330
331
auto df4 = valueOf(df,0);
auto df5 = valueOf(vec,0); // df4 == df5
Praetorius, Simon's avatar
Praetorius, Simon committed
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
```


## function `DiscreteFunction::interpolate*` {: #function-discretefunctioninterpolate }
```c++
// (1)
template <class Expr, class Tag = tag::average>
void interpolate_noalias(Expr&& expr, Tag strategy)

// (2)
template <class Expr, class Tag = tag::average>
void interpolate(Expr&& expr, Tag strategy)

// (3)
template <class Expr>
DiscreteFunction& operator<<(Expr&& expr)

// (4)
template <class Expr>
DiscreteFunction& operator+=(Expr&& expr)

// (5)
template <class Expr>
Müller, Felix's avatar
Müller, Felix committed
355
DiscreteFunction& operator-=(Expr&& expr)
Praetorius, Simon's avatar
Praetorius, Simon committed
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
```

(1) Interpolation of a `GridFunction` (or Expression) to the subtree of the DOFVector, assuming that there is no
reference to this DOFVector in the expression (no aliasing).

(2) Interpolation of a `GridFunction` (or Expression) to the subtree of the DOFVector, allowing aliasing.

(3) Operator notation of (2) using averaging strategy.

(4) Interpolate `(*this) + expr` to the subtree of the DOFVector.

(5) Interpolate `(*this) - expr` to the subtree of the DOFVector.

In case *aliasing* is allowed, a temporary DOFVector is created first as copy of *this* and the interpolation
performed on the temporary using *noalias* interpolation (1). Then, this tempoary is moved back to *this*.

Note, the range type of the expression must be compatible with the `Range` type of the DiscreteFunction.

#### Arguments
`Expr expr`
:   An Expression representing a `GridFunction`

`Tag strategy`
:   An interpolation strategy, either `tag::average` or `tag::assign`.
    The `average `strategy accumulates interpolation values on each dof and takes the average by
    divising through the number of assignees. The `assign` strategy diretly assigns an interpolation
    value to a dof that might be overwritten in a subsequent interpolation step.

#### Example
```c++
386
GlobalBasis basis{gridView, power<3>(lagrange<1>())};
Praetorius, Simon's avatar
Praetorius, Simon committed
387
388
389
auto vec = makeDOFVector(basis);

// Range type is FieldVector<double,3>
390
valueOf(vec) << [](FieldVector<double,3> const& x) -> FieldVector<double,3> { return x; };
Praetorius, Simon's avatar
Praetorius, Simon committed
391
392

// Range type is double
393
valueOf(vec,0) += 42.0;
Praetorius, Simon's avatar
Praetorius, Simon committed
394
```