diff --git a/_data/sidebars/docs_sidebar.yml b/_data/sidebars/docs_sidebar.yml index c095d499a7e..609aa5599ba 100644 --- a/_data/sidebars/docs_sidebar.yml +++ b/_data/sidebars/docs_sidebar.yml @@ -478,6 +478,10 @@ entries: url: /couple-your-code-waveform.html output: web, pdf + - title: Global data + url: /couple-your-code-global-data.html + output: web, pdf + - title: Porting guides for major versions output: web, pdf subfolderitems: diff --git a/pages/docs/couple-your-code/couple-your-code-global-data.md b/pages/docs/couple-your-code/couple-your-code-global-data.md new file mode 100644 index 00000000000..c4de1964b52 --- /dev/null +++ b/pages/docs/couple-your-code/couple-your-code-global-data.md @@ -0,0 +1,74 @@ +--- +title: Global data +permalink: couple-your-code-global-data.html +keywords: api, adapter, data, global +summary: "Define and exchange global data (data not associated to a mesh) by using specific optional API functions." +--- + +{% warning %} +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. +{% endwarning %} + +{% note %} +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. +{% endnote %} + +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). + +## Configuration + +Configuration of global data objects is described below with examples. + +In order to use this feature, global data needs to be explicitly defined in the configuration file using the `global-data` tag. + +```xml + + +... +``` + +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). + +```xml +... + + +... + + +... + + +... +``` + +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. + +## API + +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. + +For SolverOne: + +```C++ +... +participant.writeGlobalData("angles", writeAngles); +... +``` + +For SolverTwo: + +```C++ +... +participant.readGlobalData("angles", dt, readAngles); +... + +``` + +## Supported functionality + +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). + +Within implicit coupling, convergence measures and acceleration are not yet supported. + +[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. diff --git a/pages/docs/fundamentals/fundamentals-roadmap.md b/pages/docs/fundamentals/fundamentals-roadmap.md index 7c48c6aaa5e..100bc90d876 100644 --- a/pages/docs/fundamentals/fundamentals-roadmap.md +++ b/pages/docs/fundamentals/fundamentals-roadmap.md @@ -24,7 +24,7 @@ We are currently working towards [preCICE v3](https://github.com/precice/precice - [Coupling with Functional Mock-Up Units](https://github.com/precice/fmi-runner) - [Adaptive and flexible macro-micro coupling software](https://github.com/precice/micro-manager) - [Solver-based data mapping](couple-your-code-direct-access.html) to take advantage of higher-order shape functions -- [Non-mesh-related global data exchange](https://github.com/precice/precice/issues/202) +- [Non-mesh-related global data exchange](couple-your-code-global-data.html) - [Dynamic coupling meshes](https://github.com/precice/precice/projects/2) - [Cell-based linear interpolation for volumetric coupling](https://github.com/precice/precice/issues/468) - [Improving](https://github.com/precice/precice/issues/1252) the experimental [Nearest-neighbor gradient data mapping](https://github.com/precice/precice/pull/1169)