Skip to content

Commit b2e9d2b

Browse files
fsimonisfsimonis
committed
Cleanup API section
1 parent 6e8c784 commit b2e9d2b

File tree

1 file changed

+47
-28
lines changed

1 file changed

+47
-28
lines changed

‎pages/docs/couple-your-code/couple-your-code-porting-v2-3.md

Lines changed: 47 additions & 28 deletions
Original file line numberDiff line numberDiff line change
@@ -114,38 +114,45 @@ Please add breaking changes here when merged to the `develop` branch.
114114
- Where declaring a preCICE object, replace the `precice::SolverInterface` type with `precice::Participant`.
115115
- Where constructing a preCICE object, replace the `precice::SolverInterface( ... )` constructor with `precice::Participant( ... )`.
116116
- 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.
117+
- Steering methods
118+
- Replace `double preciceDt = initialize()` and `double preciceDt = advance(dt)` with `initialize()` and `advance(dt)`, as they don't have a return value.
119+
- Use `double preciceDt = getMaxTimeStepSize()`, where you need the max time step size or the relative end of the time window.
120+
- Dimensions
121+
- Replace `getDimensions()` with `getMeshDimensions(meshName)`
122+
- Replace custom logic to determine the dimensionality of data with `getDataDimensions(meshName, dataName)`
123+
- Migrate to mesh and data ids to names
124+
- Remove the now obsolete calls to `getMeshID()` and `getDataID()` and uses of types `MeshID` and `DataID`.
125+
- Replace the use of mesh IDs with the mesh name.
126+
- Replace the use of data IDs with both the mesh name and the data name.
117127
- Migrate connectivity information to the vertex-only API. All `setMeshX` methods take vertex IDs as input and return nothing.
118128
- 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.
119129
- Rename `setMeshTriangleWithEdges` to `setMeshTriangle` and `setMeshQuadWithEdges` to `setMeshQuad`. The edge-based implementation was removed.
120130
- Use the new bulk functions to reduce sanitization overhead: `setMeshEdges`, `setMeshTriangles`, `setMeshQuads`, `setMeshTetrahedra`.
121-
- Remove `mapWriteDataFrom()` and `mapReadDataTo()`.
122-
- 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`).
123-
- Remove `isReadDataAvailable()` and `isWriteDataRequired()`, or replace them with your own logic if you are subcycling in your adapter.
124-
- Remove `getMeshVertices()` and `getMeshVertexIDsFromPositions()`. This information is already known by the adapter.
125-
- Replace `isActionRequired()` with their respective requirement clause: `requiresInitialData()`, `requiresReadingCheckpoint()` or `requiresWritingCheckpoint()`.
126-
- Remove `precice::constants::*` and corresponding `#include` statements as they are no longer needed.
127-
- Remove `markActionFullfiled()`. If `requiresInitialData()`, `requiresReadingCheckpoint()`, or `requiresWritingCheckpoint()` are called, then they are promised to be acted on. Therefore, `markActionFullfiled()` is no longer needed.
128-
- Replace `isMeshConnectivityRequired` with `requiresMeshConnectivityFor`. Instead of the input argument `meshID`, pass the `meshName`.
129-
- Replace `isGradientDataRequired` with `requiresGradientDataFor`. Instead of the input argument `dataID`, pass the `meshName` and `dataName`.
130-
- Remove the now obsolete calls to `getMeshID()` and `getDataID()`.
131-
- Remove `hasMesh()` and `hasData()`.
132-
- Replace the commands to read data: `readBlockVectorData`, `readVectorData`, `readBlockScalarData`, `readScalarData` with a single command `readData`.
133-
- Replace the commands to write data: `writeBlockVectorData`, `writeVectorData`, `writeBlockScalarData`, `writeScalarData` with a single command `writeData`.
134-
- Replace the commands to write gradient data: `writeBlockVectorGradientData`, `writeVectorGradientData`, `writeBlockScalarGradientData`, `writeScalarGradientData` with a single command `writeGradientData`.
135-
- Replace `getMeshVerticesAndIDs` with `getMeshVertexIDsAndCoordinates`. Change the input argument meshID to meshName.
136-
- 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`.
137-
- Change integer input argument `dataID` to string arguments mesh name and data name in the API commands `hasData`.
138-
- 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()`.
139-
- Replace `getDimensions()` with either `getMeshDimensions(meshName)` or `getDataDimensions(meshName, dataName)`, depending on whether the mesh dimension or data dimension is required.
140-
141-
- Renamed CMake variables as follows:
142-
- `PRECICE_PETScMapping` -> `PRECICE_FEATURE_PETSC_MAPPING`
143-
- `PRECICE_MPICommunication` -> `PRECICE_FEATURE_MPI_COMMUNICATION`
144-
- `PRECICE_Packages` -> `PRECICE_CONFIGURE_PACKAGE_GENERATION`
145-
- `PRECICE_PythonActions` -> `PRECICE_FEATURE_PYTHON_ACTIONS`
146-
- `PRECICE_ENABLE_C` -> `PRECICE_BINDINGS_C`
147-
- `PRECICE_ENABLE_FORTRAN` ->`PRECICE_BINDINGS_FORTRAN`
148-
- `PRECICE_ENABLE_LIBBACKTRACE` -> `PRECICE_FEATURE_LIBBACKTRACE_STACKTRACES`
131+
- Implicit coupling
132+
- Remove `precice::constants::actionReadIterationCheckpoint()` and `precice::constants::actionWriteIterationCheckpoint()`
133+
- Remove `markActionFulfilled()` of the above actions.
134+
- Replace `isActionRequired()` of the above actions with `requiresReadingCheckpoint()` or `requiresWritingCheckpoint()`.
135+
- Migrate data access
136+
- Replace the commands to read data: `readBlockVectorData`, `readVectorData`, `readBlockScalarData`, `readScalarData` with a single command `readData`.
137+
- To simplify migration, use `getMaxTimeStepSize()` as relative read time for now and read up on time interpolation later.
138+
- Replace the commands to write data: `writeBlockVectorData`, `writeVectorData`, `writeBlockScalarData`, `writeScalarData` with a single command `writeData`.
139+
- Replace the commands to write gradient data: `writeBlockVectorGradientData`, `writeVectorGradientData`, `writeBlockScalarGradientData`, `writeScalarGradientData` with a single command `writeGradientData`.
140+
- Migrate data initialization
141+
- Remove `precice::constants::actionWriteInitialData()`.
142+
- Remove `markActionFulfilled()` of write initial data.
143+
- Replace `isActionRequired()` of write initial data with `requiresInitialData()`.
144+
- Remove `initializeData()`. The function `initializeData()` has been merged into `ìnitialize()`.
145+
- Move the data initalization before the call to `initialize()`. You have to initialize the data if `requiresInitialData()` returns `true`.
146+
- Renamed functions:
147+
- Replace `getMeshVerticesAndIDs` with `getMeshVertexIDsAndCoordinates`. Change the input argument meshID to meshName and swap the arguments.
148+
- Replace `isMeshConnectivityRequired` with `requiresMeshConnectivityFor`. Instead of the input argument `meshID`, pass the `meshName`.
149+
- Replace `isGradientDataRequired` with `requiresGradientDataFor`. Instead of the input argument `dataID`, pass the `meshName` and `dataName`.
150+
- Removed functionality:
151+
- Remove `mapWriteDataFrom()` and `mapReadDataTo()`.
152+
- Remove `hasMesh()` and `hasData()`.
153+
- Remove `hasToEvaluateSurrogateModel()` and `hasToEvaluateFineModel()`.
154+
- Remove `getMeshVertices()` and `getMeshVertexIDsFromPositions()`. This information is already known by the adapter.
155+
- Remove `isReadDataAvailable()` and `isWriteDataRequired()`. Due to time interpolation, reading and writing is now always possible.
149156

150157
### Add `relativeReadTime` for all read data calls
151158

@@ -254,6 +261,18 @@ A specific solver should only be configured if you want to force preCICE to use
254261

255262
- 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).
256263

264+
## Building preCICE
265+
266+
Renamed CMake variables as follows:
267+
268+
- `PRECICE_PETScMapping` -> `PRECICE_FEATURE_PETSC_MAPPING`
269+
- `PRECICE_MPICommunication` -> `PRECICE_FEATURE_MPI_COMMUNICATION`
270+
- `PRECICE_Packages` -> `PRECICE_CONFIGURE_PACKAGE_GENERATION`
271+
- `PRECICE_PythonActions` -> `PRECICE_FEATURE_PYTHON_ACTIONS`
272+
- `PRECICE_ENABLE_C` -> `PRECICE_BINDINGS_C`
273+
- `PRECICE_ENABLE_FORTRAN` ->`PRECICE_BINDINGS_FORTRAN`
274+
- `PRECICE_ENABLE_LIBBACKTRACE` -> `PRECICE_FEATURE_LIBBACKTRACE_STACKTRACES`
275+
257276
## Language bindings
258277

259278
The renaming of the preCICE API from `SolverInterface` to `preCICE` also applies to all language bindings. The C++ header change `precice/SolverInterface.hpp` to `precice/precice.hpp` becomes:

0 commit comments

Comments
 (0)