Skip to content

Commit 5a8f790

Browse files
kanishkbhuekerman
kanishkbh
and
uekerman
authored
Add global data to the documentation (#279)
* Add global data documentation. * Minor changes. * Add global data in other parts of the webpage * Title: Global data exchange -> Global data Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Undo changes in xmlreference.md (following review comment #279 (comment)) * Update note about feature limitations Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Update title -> make shorter Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Update page summary: make crisp Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Crisp subheader Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Use sentence case Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Use sentence case Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Use sentence case Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Better wording Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Crisp subheader Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Use sentence case Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com> * Add a rudimentary coupling scheme in the xml example. * Update pages/docs/couple-your-code/couple-your-code-global-data.md * Update pages/docs/couple-your-code/couple-your-code-global-data.md * Update pages/docs/couple-your-code/couple-your-code-global-data.md * Update pages/docs/couple-your-code/couple-your-code-global-data.md * Update pages/docs/couple-your-code/couple-your-code-global-data.md --------- Co-authored-by: Benjamin Uekermann <benjamin.uekermann@gmail.com>
1 parent 1f960e6 commit 5a8f790

File tree

3 files changed

+79
-1
lines changed

3 files changed

+79
-1
lines changed

‎_data/sidebars/docs_sidebar.yml‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -482,6 +482,10 @@ entries:
482482
url: /couple-your-code-waveform.html
483483
output: web, pdf
484484

485+
- title: Global data
486+
url: /couple-your-code-global-data.html
487+
output: web, pdf
488+
485489
- title: Porting guides for major versions
486490
output: web, pdf
487491
subfolderitems:

‎pages/docs/couple-your-code/couple-your-code-global-data.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,74 @@
1+
---
2+
title: Global data
3+
permalink: couple-your-code-global-data.html
4+
keywords: api, adapter, data, global
5+
summary: "Define and exchange global data (data not associated to a mesh) by using specific optional API functions."
6+
---
7+
8+
{% warning %}
9+
These API functions are a work in progress, experimental, and are not yet released. The API might change during the ongoing development process. Use with care.
10+
{% endwarning %}
11+
12+
{% note %}
13+
This feature is only available for coupling between two participants, i.e. does not yet support [multi coupling](https://precice.org/configuration-coupling-multi.html). Further, it does not yet allow [convergence measures](https://precice.org/configuration-coupling.html#implicit-coupling-schemes) and [acceleration](https://precice.org/configuration-acceleration) to be defined for global data. An extension to these features is planned.
14+
{% endnote %}
15+
16+
preCICE allows participants to exchange data that is not associated with any mesh. Examples of such data are global background pressure (e.g. fluid-acoustic coupling) and angles between coordinate systems (e.g. fluid-structure coupling for rotor blades).
17+
18+
## Configuration
19+
20+
Configuration of global data objects is described below with examples.
21+
22+
In order to use this feature, global data needs to be explicitly defined in the configuration file using the `global-data` tag.
23+
24+
```xml
25+
<precice-configuration dimensions="3" experimental="true">
26+
<global-data:vector name="angles" />
27+
...
28+
```
29+
30+
Rest of the global data configuration steps are similar to the usual *mesh-associated* data as described in [introduction to configuration](https://precice.org/configuration-introduction.html).
31+
32+
```xml
33+
...
34+
<participant name="SolverOne">
35+
<write-data name="angles" />
36+
...
37+
<participant name="SolverTwo">
38+
<read-data name="angles">
39+
...
40+
<coupling-scheme:serial-explicit>
41+
<exchange data="angles" from="SolverOne" to="SolverTwo" />
42+
...
43+
```
44+
45+
Since global data is not associated with any mesh, it should not be configured with the `use-data` tag under the `mesh` definition. Similarly, tags such as `read-data`, `write-data`, or `exchange` require no `mesh` attribute if used for global data.
46+
47+
## API
48+
49+
The API functions `writeGlobalData(...)` and `readGlobalData(...)` enable exchange of global data analogous to the `writeData(...)` and `readData(...)` functions for mesh-associated data. For the above example, the API calls would be as follows.
50+
51+
For SolverOne:
52+
53+
```C++
54+
...
55+
participant.writeGlobalData("angles", writeAngles);
56+
...
57+
```
58+
59+
For SolverTwo:
60+
61+
```C++
62+
...
63+
participant.readGlobalData("angles", dt, readAngles);
64+
...
65+
66+
```
67+
68+
## Supported functionality
69+
70+
Global data exchange is supported in both explicit and implicit [coupling schemes](https://precice.org/configuration-coupling.html) with serial as well as parallel [coupling flow](https://precice.org/couple-your-code-coupling-flow.html#parallel-coupling-schemes).
71+
72+
Within implicit coupling, convergence measures and acceleration are not yet supported.
73+
74+
[Data initialization](https://precice.org/couple-your-code-initializing-coupling-data.html) and [time interpolation](https://precice.org/couple-your-code-waveform.html) are also supported for global data.

‎pages/docs/fundamentals/fundamentals-roadmap.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,7 @@ We are currently working towards [preCICE v3](https://github.com/precice/precice
2424
- [Coupling with Functional Mock-Up Units](https://github.com/precice/fmi-runner)
2525
- [Adaptive and flexible macro-micro coupling software](https://github.com/precice/micro-manager)
2626
- [Solver-based data mapping](couple-your-code-direct-access.html) to take advantage of higher-order shape functions
27-
- [Non-mesh-related global data exchange](https://github.com/precice/precice/issues/202)
27+
- [Non-mesh-related global data exchange](couple-your-code-global-data.html)
2828
- [Dynamic coupling meshes](https://github.com/precice/precice/projects/2)
2929
- [Cell-based linear interpolation for volumetric coupling](https://github.com/precice/precice/issues/468)
3030
- [Improving](https://github.com/precice/precice/issues/1252) the experimental [Nearest-neighbor gradient data mapping](https://github.com/precice/precice/pull/1169)

0 commit comments

Comments
 (0)