You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: pages/docs/couple-your-code/couple-your-code-porting-v2-3.md
+97-81Lines changed: 97 additions & 81 deletions
Original file line number
Diff line number
Diff line change
@@ -109,39 +109,46 @@ Please add breaking changes here when merged to the `develop` branch.
109
109
- Where declaring a preCICE object, replace the `precice::SolverInterface` type with `precice::Participant`.
110
110
- Where constructing a preCICE object, replace the `precice::SolverInterface( ... )` constructor with `precice::Participant( ... )`.
111
111
- Consider renaming your objects from, e.g., `interface` to `participant`, to better reflect the purpose and to be consistent with the rest of the changes.
112
+
- Steering methods
113
+
- Replace `double preciceDt = initialize()` and `double preciceDt = advance(dt)` with `initialize()` and `advance(dt)`, as they no longer have a return value.
114
+
- Use `double preciceDt = getMaxTimeStepSize()`, where you need the max time step size or the relative end of the time window.
115
+
- Dimensions
116
+
- Replace `getDimensions()` with `getMeshDimensions(meshName)`
117
+
- Replace any custom logic to determine the dimensionality of data with `getDataDimensions(meshName, dataName)`
118
+
- Migrate from using mesh and data ids to directly using names
119
+
- Remove the now obsolete calls to `getMeshID()` and `getDataID()` and any related variables / user-defined types.
120
+
- Replace the use of mesh IDs with the mesh name.
121
+
- Replace the use of data IDs with the respective mesh and data names.
112
122
- Migrate connectivity information to the vertex-only API. All `setMeshX` methods take vertex IDs as input and return nothing.
113
123
- Directly define face elements or cells of your coupling mesh available in your solver by passing their vectices to preCICE, which automatically handles edges of triangles etc. See [Mesh Connectivity](couple-your-code-defining-mesh-connectivity) for more information.
114
124
- Rename `setMeshTriangleWithEdges` to `setMeshTriangle` and `setMeshQuadWithEdges` to `setMeshQuad`. The edge-based implementation was removed.
115
125
- Use the new bulk functions to reduce sanitization overhead: `setMeshEdges`, `setMeshTriangles`, `setMeshQuads`, `setMeshTetrahedra`.
116
-
- Remove `mapWriteDataFrom()` and `mapReadDataTo()`.
117
-
- Remove `initializeData()`. The functions `initializeData()` and `ìnitialize()` have been merged into the new function `initialize()`. Before calling `ìnitialize()`, you have to initialize the mesh and the data ( if `requiresInitialData()` is `true`).
118
-
- Remove `isReadDataAvailable()` and `isWriteDataRequired()`, or replace them with your own logic if you are subcycling in your adapter.
119
-
- Remove `getMeshVertices()` and `getMeshVertexIDsFromPositions()`. This information is already known by the adapter.
120
-
- Replace `isActionRequired()` with their respective requirement clause: `requiresInitialData()`, `requiresReadingCheckpoint()` or `requiresWritingCheckpoint()`.
121
-
- Remove `precice::constants::*` and corresponding `#include` statements as they are no longer needed.
122
-
- Remove `markActionFullfiled()`. If `requiresInitialData()`, `requiresReadingCheckpoint()`, or `requiresWritingCheckpoint()` are called, then they are promised to be acted on. Therefore, `markActionFullfiled()` is no longer needed.
123
-
- Replace `isMeshConnectivityRequired` with `requiresMeshConnectivityFor`. Instead of the input argument `meshID`, pass the `meshName`.
124
-
- Replace `isGradientDataRequired` with `requiresGradientDataFor`. Instead of the input argument `dataID`, pass the `meshName` and `dataName`.
125
-
- Remove the now obsolete calls to `getMeshID()` and `getDataID()`.
126
-
- Remove `hasMesh()` and `hasData()`.
127
-
- Replace the commands to read data: `readBlockVectorData`, `readVectorData`, `readBlockScalarData`, `readScalarData` with a single command `readData`.
128
-
- Replace the commands to write data: `writeBlockVectorData`, `writeVectorData`, `writeBlockScalarData`, `writeScalarData` with a single command `writeData`.
129
-
- Replace the commands to write gradient data: `writeBlockVectorGradientData`, `writeVectorGradientData`, `writeBlockScalarGradientData`, `writeScalarGradientData` with a single command `writeGradientData`.
130
-
- The signature of `readData`, `writeData` and `writeGradientData` has changed from `const int*`, `const double*`, and `double*` to `span<const VertexID>`, `span<const double>`, and `span<double>`. If necessary change the data object, e.g., from `double* forces = new double[vertexSize*dim]` to `std::vector<double> forces(vertexSize*dim)` and remove `.data()` in the function arguments.
131
-
- Replace `getMeshVerticesAndIDs` with `getMeshVertexIDsAndCoordinates`. Change the input argument meshID to meshName.
132
-
- Change integer input argument `meshID` to a string with the mesh name in the API commands `hasMesh`, `requiresMeshConnectivityFor`, `setMeshVertex`, `getMeshVertexSize`, `setMeshVertices`, `setMeshEdge`, `setMeshEdges`, `setMeshTriangle`, `setMeshTriangles`, `setMeshQuad`, `setMeshQuads`, `setMeshTetrahedron`, `setMeshTetrahedrons`, `setMeshAccessRegion`.
133
-
- Change integer input argument `dataID` to string arguments mesh name and data name in the API commands `hasData`.
134
-
- Replace `double preciceDt = initialize()` and `double preciceDt = advance(dt)` with `initialize()` and `advance(dt)`, as they don't have a return value. If you need to know `preciceDt`, you can use `double preciceDt = getMaxTimeStepSize()`.
135
-
- Replace `getDimensions()` with either `getMeshDimensions(meshName)` or `getDataDimensions(meshName, dataName)`, depending on whether the mesh dimension or data dimension is required.
- Remove `precice::constants::actionReadIterationCheckpoint()` and `precice::constants::actionWriteIterationCheckpoint()`
128
+
- Replace `isActionRequired()` of the above actions with `requiresReadingCheckpoint()` or `requiresWritingCheckpoint()`.
129
+
- Remove `markActionFulfilled()` of the above actions. It is now implied that a `requires*()` is directly executed/fulfilled.
130
+
- Migrate data access
131
+
- Replace the commands to read data: `readBlockVectorData`, `readVectorData`, `readBlockScalarData`, `readScalarData` with the single command `readData`.
132
+
- Replace the commands to write data: `writeBlockVectorData`, `writeVectorData`, `writeBlockScalarData`, `writeScalarData` with the single command `writeData`.
133
+
- Replace the commands to write gradient data: `writeBlockVectorGradientData`, `writeVectorGradientData`, `writeBlockScalarGradientData`, `writeScalarGradientData` with the single command `writeGradientData`.
134
+
- The signature of `readData`, `writeData` and `writeGradientData` has changed from `const int*`, `const double*`, and `double*` to `precice::span<const VertexID>`, `precice::span<const double>`, and `span<double>`. The sizes of passed spans are checked by preCICE. spans can be constructed using a pointer and size, or by a contigous container. Examples for the latter are `std::vector`, `std:array`, `Eigen::VectorXd`, and also `std::span`.
135
+
- To simplify migration to `readData()`, use `getMaxTimeStepSize()` as relative read time for now to always read data at the end of the time window. Read up on [time interpolation](couple-your-code-waveform.html) once you finished the port.
136
+
- Migrate data initialization
137
+
- Move the data initalization before the call to `initialize()`. You have to initialize the data if `requiresInitialData()` returns `true`.
138
+
- Remove `initializeData()`. The function `initializeData()` has been merged into `ìnitialize()`.
- Remove `markActionFulfilled()` of write initial data.
141
+
- Replace `isActionRequired()` of write initial data with `requiresInitialData()`.
142
+
- Rename the functions:
143
+
- Replace `getMeshVerticesAndIDs` with `getMeshVertexIDsAndCoordinates`. Change the input argument meshID to meshName and swap the arguments for IDs and coordinates.
144
+
- Replace `isMeshConnectivityRequired` with `requiresMeshConnectivityFor`. Instead of the input argument `meshID`, pass the `meshName`.
145
+
- Replace `isGradientDataRequired` with `requiresGradientDataFor`. Instead of the input argument `dataID`, pass the `meshName` and `dataName`.
146
+
- Remove the following without a replacement:
147
+
- Remove `mapWriteDataFrom()` and `mapReadDataTo()` as custom timings were removed.
148
+
- Remove `hasMesh()` and `hasData()` as there is no real usecase for them. All errors are unrecoverable.
149
+
- Remove `hasToEvaluateSurrogateModel()` and `hasToEvaluateFineModel()` as they were stubs of a long-removed feature.
150
+
- Remove `getMeshVertices()` and `getMeshVertexIDsFromPositions()`. This information is already known by the adapter. We docummented [strategies on how to handle this](couple-your-code-defining-mesh-connectivity.html) in adpters.
151
+
- Remove `isReadDataAvailable()` and `isWriteDataRequired()`. Due to time interpolation, writing generates samples in time, and reading is always possible between the current time and the end of the current time window.
145
152
146
153
### Add `relativeReadTime` for all read data calls
147
154
@@ -197,58 +204,67 @@ error: ‘class precice::SolverInterface’ has no member named ‘initializeDat
197
204
198
205
- The XML tag `<solver-interface>` was removed and all underlying functionality was moved to the `<precice-configuration>` tag. Remove the lines including `<solver-interface>` and `</solver-interface>`, and move any attributes (such as `experimental`) from the `solver-interface` to the `precice-configuration` tag. Move the `sync-mode` attribute to the new `<profiling>` tag (see below).
199
206
- The `dimensions` configuration is now defined per mesh. Move the `dimensions="2"` or `dimensions="3"` from the `<solver-interface>` tag to each `<mesh>` tag: `<mesh name="MeshOne" dimensions="3">`.
200
-
- Replace mapping constraint `scaled-consistent` with `scaled-consistent-surface`.
201
-
- Replace `<use-mesh provide="true" ... />` with `<provide-mesh ... />`, and `<use-mesh provide="false" ... />` with `<receive-mesh ... />`.
202
-
- Remove `<extraplation-order value="..." />` in `<coupling-scheme>`.
203
-
- Replace all RBF related `<mapping:rbf-... />` tags. RBF mappings are now defined in terms of the applied solver (current options `<mapping:rbf-global-direct ...`, `<mapping:rbf-global-iterative` or `<mapping:rbf-pum-direct ...`) and the applied basis function as a subtag of the solver. Users should use the additionally added auto selection of an appropriate solver, which omits the solver specification, as follows:
A specific solver should only be configured if you want to force preCICE to use and stick to a certain solver, independent of your problem size and execution.
- Remove all timings in the mapping configuration `<mapping: ... timing="initial/onadvance/ondemand" />`.
231
-
- Remove the preallocations in the mapping configuration `<mapping: ... preallocation="tree/compute/estimate/save/off" />`.
232
-
233
-
<!--
234
-
- Add `<profiling mode="all" />` after the `<log>` tag if you need profiling data.
235
-
- Replace `<export:vtk />` for parallel participants with `<export:vtu />` or `<export:vtp />`.
236
-
-->
237
-
238
-
- Renamed the `<m2n: ... />` attributes `from` -> `acceptor` and `to` -> `connector`.
239
-
240
-
- Moved and renamed the optional attribute `<read-data: ... waveform-order="1" />` to `<data:scalar/vector ... waveform-degree="1"`.
241
-
242
-
- We dropped quite some functionality concerning [data actions](https://precice.org/configuration-action.html) as these were not used to the best of our knowledge and hard to maintain:
243
-
- Removed deprecated action timings `regular-prior`, `regular-post`, `on-exchange-prior`, and `on-exchange-post`.
244
-
- Removed action timings `read-mapping-prior`, `write-mapping-prior`, and `on-time-window-complete-post`.
245
-
- Removed `ComputeCurvatureAction` and `ScaleByDtAction` actions.
246
-
- Removed callback functions `vertexCallback` and `postAction` from `PythonAction` interface.
247
-
- Removed timewindowsize from the `performAction` signature of `PythonAction`. The new signature is `performAction(time, data)`
248
-
249
-
- Replace `<min-iteration-convergence-measure min-iterations="3" ... />` by `<min-iterations value="3"/>`.
250
-
251
-
- We removed the plain `Broyden` acceleration. You could use `IQN-IMVJ` instead, which is a [multi-vector Broyden variant](http://hdl.handle.net/2117/191193).
207
+
- Rename the `<m2n: ... />` attributes `from` -> `acceptor` and `to` -> `connector`.
208
+
- You can now add `<profiling mode="all" />` after the `<log>` tag if you need full profiling data.
209
+
210
+
- Participants
211
+
- Replace `<use-mesh provide="true" ... />` with `<provide-mesh ... />`, and `<use-mesh provide="false" ... />` with `<receive-mesh ... />`.
212
+
- Move and rename the optional attribute `<read-data: ... waveform-order="1" />` to `<data:scalar/vector ... waveform-degree="1"`.
213
+
- Replace `<export:vtk />` for parallel participants with `<export:vtu />` or `<export:vtp />`.
214
+
- Replace mapping constraint `scaled-consistent` with `scaled-consistent-surface`.
215
+
- Remove all timings in the mapping configuration `<mapping: ... timing="initial/onadvance/ondemand" />`. preCICE now fully controls the mapping.
216
+
- Remove the preallocations in the mapping configuration `<mapping: ... preallocation="tree/compute/estimate/save/off" />`. We always use the superior `tree` method.
217
+
- Replace all RBF related `<mapping:rbf-... />` tags. RBF mappings are now defined in terms of the applied solver (current options `<mapping:rbf-global-direct ...`, `<mapping:rbf-global-iterative` or `<mapping:rbf-pum-direct ...`) and the applied basis function as a subtag of the solver. Users should use the additionally added auto selection of an appropriate solver, which omits the solver specification, as follows:
A specific solver should only be configured if you want to force preCICE to use and stick to a certain solver, independent of your problem size and execution.
- We dropped quite some functionality concerning [data actions](https://precice.org/configuration-action.html) as these were not used to the best of our knowledge and were hard to maintain:
245
+
- Removed deprecated action timings `regular-prior`, `regular-post`, `on-exchange-prior`, and `on-exchange-post`.
246
+
- Removed action timings `read-mapping-prior`, `write-mapping-prior`, and `on-time-window-complete-post`.
247
+
- Removed `ComputeCurvatureAction` and `ScaleByDtAction` actions.
248
+
- Removed callback functions `vertexCallback` and `postAction` from `PythonAction` interface.
249
+
- Removed timewindowsize from the `performAction` signature of `PythonAction`. The new signature is `performAction(time, data)`
250
+
- Using actions with multiple couping schemes and mixed time window sizes is not well defined!
251
+
252
+
- Coupling schemes
253
+
- Remove `<extraplation-ordervalue="..." />` in `<coupling-scheme>`. Contact us if you need this feature.
254
+
- Replace `<min-iteration-convergence-measuremin-iterations="3" ... />` by `<min-iterationsvalue="3"/>`. Not defining convergence measures leads to iterations until `max-iterations` is reached.
255
+
- We removed the plain `Broyden` acceleration. You could use `IQN-IMVJ` instead, which is a [multi-vector Broyden variant](http://hdl.handle.net/2117/191193).
0 commit comments