DOFVector.md 19.9 KB
Newer Older
Praetorius, Simon's avatar
Praetorius, Simon committed
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
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
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
# 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)
into a [`GridFunction`](/reference/GridFunctions) that allows to use it like a function defined on a grid.

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`
Defined in header [`<amdis/DOFVector.hpp>`](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/DOFVector.hpp)

```c++
template <class GB,
          class T = double,
          class Traits = BackendTraits<GB,T>>
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
[`child`](#function-dofvectorchild)                           | Return a DiscreteFunction of a given sub-space
[`backup`](#function-dofvectorbackup)                         | Write DOFVector to file
[`restore`](#function-dofvectorrestore)                       | Read backup data from file
[`dataTransfer`](#function-dofvectordataTransfer)             | Return the associated DataTransfer object

### Interpolation functions

 Function                       | Descriptions
--------------------------------|---------------------------------------------
[`interpolate`](#function-dofvectorinterpolate)               | Interpolation of GridFunction to DOFVector
[`interpolate_noalias`](#function-dofvectorinterpolate)       | Interpolation of GridFunction to DOFVector assuming no aliasing
[`operator<<`](#function-dofvectorinterpolate)                | Operator for the interpolation

??? seealso "Functions inherited from [`VectorFacade`](/reference/MatVecBase/#class-vectorfacade)"
    Function                       | Descriptions
    --------------------------------|---------------------------------------------
    [`basis`](/reference/MatVecBase#function-vectorbasebasis)                 | Return the GlobalBasis associated with the vector
    [`backend`](/reference/MatVecBase#function-vectorbasebackend)             | Return the backend vector wrapper implementing the actual algebra
    [`localSize,globalSize`](/reference/MatVecBase#function-vectorbasesize)   | The number of entries in the local part of the vector
    [`resize,resizeZero`](/reference/MatVecBase#function-vectorbaseglobalSize)| Resize the vector to the size of the basis
    [`init`](/reference/MatVecBase#function-vectorbaseglobalSize)             | Prepare the vector for insertion of values
    [`finish`](/reference/MatVecBase#function-vectorbaseglobalSize)           | Finish the insertion of values
    [`at`](/reference/MatVecBase#function-vectorbaseat)                       | Return the value of the vector at the given local index
    [`insert,set,add`](/reference/MatVecBase#function-vectorbaseinsert)       | Insert a single value into the matrix
    [`gather`](/reference/MatVecBase#function-vectorbasegather)               | Extract values from the vector referring to the given local indices
    [`scatter`](/reference/MatVecBase#function-vectorbasescatter)             | Insert a block of values into the vector
    [`copy`](/reference/MatVecBase#function-vectorbasescatter)                | Copies a block of values into the vector
    [`forEach`](/reference/MatVecBase#function-vectorbasescatter)             | Apply a functor to each value at given indices


## function `DOFVector::DOFVector`
```c++
template <class Basis>
DOFVector(Basis&& basis, DataTransferOperation op = INTERPOLATE)
```

Constructs the DOFVector from a given global basis and optionally a DataTransferOperation that
defines how the DOFVector is handled during grid adaption.

#### Arguments
`Basis basis`
:   Either a `shared_ptr` to the `GlobalBasis` type or anything that can be converted to that, e.g. a
    reference or a `unique_ptr` or a dune-functions `DefaultGlobalBasis`. References to lavlues are
    wrapped into non-destroying `shared_ptr`s whereas rvalue-references are moved into new basis objects.

`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;
Müller, Felix's avatar
Müller, Felix committed
112
ParallelGlobalBasis basis1(grid.leafGridView(), lagrange<2>());
Praetorius, Simon's avatar
Praetorius, Simon committed
113
114
115
116

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

Müller, Felix's avatar
Müller, Felix committed
117
auto basis2 = makeUniquePtr(ParallelGlobalBasis(grid.leafGridView(), lagrange<2>()));
Praetorius, Simon's avatar
Praetorius, Simon committed
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
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
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
248
249
250
251
252
253
DOFVector<Underlying_t<decltype(basis2)>> vec2(std::move(basis2));
```

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


## function `DOFVector::child`

```c++
template <class TreePath = RootTreePath>
auto child(TreePath const& path = {})         // (1)

template <class TreePath = RootTreePath>
auto child(TreePath const& path = {}) const   // (2)
```

(1) Creates a mutable `DiscreteFunction` representing the sub-space w.r.t. the passed tree-path. The `path` thereby
refers to the hierarchic global basis.

(2) Creates a constant `DiscreteFunction` representing the sub-space w.r.t. the passed tree-path. The `path` thereby
refers to the hierarchic global basis.

#### Arguments
`TreePath path`
:   A Treepath identifying a node in the basis tree.

#### Example
```c++
DOFVector vec(basis);

auto vec_ = vec.child();
auto vec_0 = vec.child(_0);
auto vec_10 = vec.child(treepath(_1,0));
```


## 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 `DOFVector::interpolate,interpolate_noalias,operator<<` {: #function-dofvectorinterpolate }
```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>
DOFVector& operator<<(Expr&& expr)
```

(1) Interpolation of a `GridFunction` (or Expression) to 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 DOFVector, allowing aliasing.

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

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*.

#### 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
    dividing by the number of assignees. The `assign` strategy diretly assigns an interpolation
    value to a dof that might be overwritten in a subsequent interpolation step.


## function `makeDOFVector`
Defined in header [`<amdis/DOFVector.hpp>`](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/DOFVector.hpp)

```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`
:   Reference, temporary, or `shared_ptr` to dune global basis or `ParallelGlobalBasis`

`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
Returns a `DOFVector<GlobalBasis, T>` with `GlobalBasis = ParallelGlobalBasis<typename Underlying_t<Basis>::PreBasis>`. The
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
Müller, Felix's avatar
Müller, Felix committed
254
ParallelGlobalBasis basis1(gridView, lagrange<2>());
Praetorius, Simon's avatar
Praetorius, Simon committed
255
256
257
258
259
260
261
262
263
264
265
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
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
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
386
387
388
389
390
391
392
393
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`
Defined in header [`<amdis/gridfunctions/DiscreteFunction.hpp>`](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/DiscreteFunction.hpp)

```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)
DiscreteFunction(DOFVector<GlobalBasis,T> const& dofVector,
                 TreePath const& treePath = {})
// (2)
DiscreteFunction(DOFVector<GlobalBasis,T>& dofVector,
                 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.

`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.

#### See Also
- Generator function to construct a DiscreteFunction: [`makeDiscreteFunction()`](#function-makediscretefunction)


## 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)
template <class TreePath = RootTreePath>
auto child(TreePath const& path = {}) const

// (2)
template <class TreePath = RootTreePath>
auto child(TreePath const& path = {})
```

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

#### Arguments
`TreePath path`
:   A Treepath identifying a node in the basis tree.

#### Example
```c++
Müller, Felix's avatar
Müller, Felix committed
394
ParallelGlobalBasis basis(gridView, power<3>(lagrange<1>()));
Praetorius, Simon's avatar
Praetorius, Simon committed
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
auto vec = makeDOFVector(basis);
auto df = makeDiscreteFunction(vec);

auto df1 = df.child();
auto df2 = df.child(0);
auto df3 = df.child(_0);
```


## 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>
DiscreteFunction& operator+=(Expr&& expr)
```

(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++
Müller, Felix's avatar
Müller, Felix committed
455
ParallelGlobalBasis basis(gridView, power<3>(lagrange<1>()));
Praetorius, Simon's avatar
Praetorius, Simon committed
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
auto vec = makeDOFVector(basis);

auto df1 = vec.child();
auto df2 = vec.child(0);

// Range type is FieldVector<double,3>
df1 << [](FieldVector<double,3> const& x) -> FieldVector<double,3> { return x; };

// Range type is double
df2 += 42.0;
```


## function `makeDiscreteFunction`
Defined in header [`<amdis/gridfunctions/DiscreteFunction.hpp>`](https://gitlab.mn.tu-dresden.de/amdis/amdis-core/blob/master/src/amdis/gridfunctions/DiscreteFunction.hpp)

```c++
// (1)
template <class GlobalBasis, class ValueType,
          class PreTreePath = Dune::TypeTree::HybridTreePath<>>
auto makeDiscreteFunction(DOFVector<GlobalBasis, ValueType> const& dofVector,
                          PreTreePath const& preTreePath = {})
// (2)
template <class GlobalBasis, class ValueType,
          class PreTreePath = Dune::TypeTree::HybridTreePath<>>
auto makeDiscreteFunction(DOFVector<GlobalBasis, ValueType>& dofVector,
                          PreTreePath const& preTreePath = {})
```

Constructs a const (1) or mutable (2) DiscreteFunction from a `DOFVector` and a tree path. The TreePath can therby
by given by a pree-tree path, i.e. a sequence of integers or integral constants a `Dune::TypeTree::HybridTreePath`
can be constructed from.

#### 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.

`PreTreePath preTreePath`
:   A pree-tree path, a `Dune::TypeTree::HybridTreePath<...>` can be created from.

#### Return value
Returns a `DiscreteFunction<GlobalBasis, ValueType, TREE_PATH, true>` if the `DOFVector` is const, or a
`DiscreteFunction<GlobalBasis, ValueType, TREE_PATH, false>` if the `DOFVector` is mutable. The `TREE_PATH` is
thereby given by the type of `makeTreePath(preTreePath)`.

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

// pass a reference to the basis
Müller, Felix's avatar
Müller, Felix committed
507
ParallelGlobalBasis basis(gridView, power<2>(lagrange<2>()));
Praetorius, Simon's avatar
Praetorius, Simon committed
508
509
510
511
512
513
514
auto vec = makeDOFVector<double>(basis1);

auto df1 = makeDiscreteFunction(vec);
auto df2 = makeDiscreteFunction(vec, 1);
auto df3 = makeDiscreteFunction(vec, _1);
auto df4 = makeDiscreteFunction(vec, Dune::TypeTree::hybridTreePath(0));
```