diff --git a/pages/docs/couple-your-code/couple-your-code-porting-v2-3.md b/pages/docs/couple-your-code/couple-your-code-porting-v2-3.md index 2a5b7251de..7082e5a564 100644 --- a/pages/docs/couple-your-code/couple-your-code-porting-v2-3.md +++ b/pages/docs/couple-your-code/couple-your-code-porting-v2-3.md @@ -113,39 +113,46 @@ Please add breaking changes here when merged to the `develop` branch. - Where declaring a preCICE object, replace the `precice::SolverInterface` type with `precice::Participant`. - Where constructing a preCICE object, replace the `precice::SolverInterface( ... )` constructor with `precice::Participant( ... )`. - 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. +- Steering methods + - Replace `double preciceDt = initialize()` and `double preciceDt = advance(dt)` with `initialize()` and `advance(dt)`, as they no longer have a return value. + - Use `double preciceDt = getMaxTimeStepSize()`, where you need the max time step size or the relative end of the time window. +- Dimensions + - Replace `getDimensions()` with `getMeshDimensions(meshName)` + - Replace any custom logic to determine the dimensionality of data with `getDataDimensions(meshName, dataName)` +- Migrate from using mesh and data ids to directly using names + - Remove the now obsolete calls to `getMeshID()` and `getDataID()` and any related variables / user-defined types. + - Replace the use of mesh IDs with the mesh name. + - Replace the use of data IDs with the respective mesh and data names. - Migrate connectivity information to the vertex-only API. All `setMeshX` methods take vertex IDs as input and return nothing. - 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. - Rename `setMeshTriangleWithEdges` to `setMeshTriangle` and `setMeshQuadWithEdges` to `setMeshQuad`. The edge-based implementation was removed. - Use the new bulk functions to reduce sanitization overhead: `setMeshEdges`, `setMeshTriangles`, `setMeshQuads`, `setMeshTetrahedra`. -- Remove `mapWriteDataFrom()` and `mapReadDataTo()`. -- 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`). -- Remove `isReadDataAvailable()` and `isWriteDataRequired()`, or replace them with your own logic if you are subcycling in your adapter. -- Remove `getMeshVertices()` and `getMeshVertexIDsFromPositions()`. This information is already known by the adapter. -- Replace `isActionRequired()` with their respective requirement clause: `requiresInitialData()`, `requiresReadingCheckpoint()` or `requiresWritingCheckpoint()`. -- Remove `precice::constants::*` and corresponding `#include` statements as they are no longer needed. -- Remove `markActionFullfiled()`. If `requiresInitialData()`, `requiresReadingCheckpoint()`, or `requiresWritingCheckpoint()` are called, then they are promised to be acted on. Therefore, `markActionFullfiled()` is no longer needed. -- Replace `isMeshConnectivityRequired` with `requiresMeshConnectivityFor`. Instead of the input argument `meshID`, pass the `meshName`. -- Replace `isGradientDataRequired` with `requiresGradientDataFor`. Instead of the input argument `dataID`, pass the `meshName` and `dataName`. -- Remove the now obsolete calls to `getMeshID()` and `getDataID()`. -- Remove `hasMesh()` and `hasData()`. -- Replace the commands to read data: `readBlockVectorData`, `readVectorData`, `readBlockScalarData`, `readScalarData` with a single command `readData`. -- Replace the commands to write data: `writeBlockVectorData`, `writeVectorData`, `writeBlockScalarData`, `writeScalarData` with a single command `writeData`. -- Replace the commands to write gradient data: `writeBlockVectorGradientData`, `writeVectorGradientData`, `writeBlockScalarGradientData`, `writeScalarGradientData` with a single command `writeGradientData`. -- The signature of `readData`, `writeData` and `writeGradientData` has changed from `const int*`, `const double*`, and `double*` to `span`, `span`, and `span`. If necessary change the data object, e.g., from `double* forces = new double[vertexSize*dim]` to `std::vector forces(vertexSize*dim)` and remove `.data()` in the function arguments. -- Replace `getMeshVerticesAndIDs` with `getMeshVertexIDsAndCoordinates`. Change the input argument meshID to meshName. -- 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`. -- Change integer input argument `dataID` to string arguments mesh name and data name in the API commands `hasData`. -- 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()`. -- Replace `getDimensions()` with either `getMeshDimensions(meshName)` or `getDataDimensions(meshName, dataName)`, depending on whether the mesh dimension or data dimension is required. - -- Renamed CMake variables as follows: - - `PRECICE_PETScMapping` -> `PRECICE_FEATURE_PETSC_MAPPING` - - `PRECICE_MPICommunication` -> `PRECICE_FEATURE_MPI_COMMUNICATION` - - `PRECICE_Packages` -> `PRECICE_CONFIGURE_PACKAGE_GENERATION` - - `PRECICE_PythonActions` -> `PRECICE_FEATURE_PYTHON_ACTIONS` - - `PRECICE_ENABLE_C` -> `PRECICE_BINDINGS_C` - - `PRECICE_ENABLE_FORTRAN` ->`PRECICE_BINDINGS_FORTRAN` - - `PRECICE_ENABLE_LIBBACKTRACE` -> `PRECICE_FEATURE_LIBBACKTRACE_STACKTRACES` +- Implicit coupling + - Remove `precice::constants::actionReadIterationCheckpoint()` and `precice::constants::actionWriteIterationCheckpoint()` + - Replace `isActionRequired()` of the above actions with `requiresReadingCheckpoint()` or `requiresWritingCheckpoint()`. + - Remove `markActionFulfilled()` of the above actions. It is now implied that a `requires*()` is directly executed/fulfilled. +- Migrate data access + - Replace the commands to read data: `readBlockVectorData`, `readVectorData`, `readBlockScalarData`, `readScalarData` with the single command `readData`. + - Replace the commands to write data: `writeBlockVectorData`, `writeVectorData`, `writeBlockScalarData`, `writeScalarData` with the single command `writeData`. + - Replace the commands to write gradient data: `writeBlockVectorGradientData`, `writeVectorGradientData`, `writeBlockScalarGradientData`, `writeScalarGradientData` with the single command `writeGradientData`. + - The signature of `readData`, `writeData` and `writeGradientData` has changed from `const int*`, `const double*`, and `double*` to `precice::span`, `precice::span`, and `span`. 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`. + - 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. +- Migrate data initialization + - Move the data initalization before the call to `initialize()`. You have to initialize the data if `requiresInitialData()` returns `true`. + - Remove `initializeData()`. The function `initializeData()` has been merged into `ìnitialize()`. + - Remove `precice::constants::actionWriteInitialData()`. + - Remove `markActionFulfilled()` of write initial data. + - Replace `isActionRequired()` of write initial data with `requiresInitialData()`. +- Rename the functions: + - Replace `getMeshVerticesAndIDs` with `getMeshVertexIDsAndCoordinates`. Change the input argument meshID to meshName and swap the arguments for IDs and coordinates. + - Replace `isMeshConnectivityRequired` with `requiresMeshConnectivityFor`. Instead of the input argument `meshID`, pass the `meshName`. + - Replace `isGradientDataRequired` with `requiresGradientDataFor`. Instead of the input argument `dataID`, pass the `meshName` and `dataName`. +- Remove the following without a replacement: + - Remove `mapWriteDataFrom()` and `mapReadDataTo()` as custom timings were removed. + - Remove `hasMesh()` and `hasData()` as there is no real usecase for them. All errors are unrecoverable. + - Remove `hasToEvaluateSurrogateModel()` and `hasToEvaluateFineModel()` as they were stubs of a long-removed feature. + - 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. + - 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. ### Add `relativeReadTime` for all read data calls @@ -201,58 +208,67 @@ error: ‘class precice::SolverInterface’ has no member named ‘initializeDat - The XML tag `` was removed and all underlying functionality was moved to the `` tag. Remove the lines including `` and ``, and move any attributes (such as `experimental`) from the `solver-interface` to the `precice-configuration` tag. Move the `sync-mode` attribute to the new `` tag (see below). - The `dimensions` configuration is now defined per mesh. Move the `dimensions="2"` or `dimensions="3"` from the `` tag to each `` tag: ``. -- Replace mapping constraint `scaled-consistent` with `scaled-consistent-surface`. -- Replace `` with ``, and `` with ``. -- Remove `` in ``. -- Replace all RBF related `` tags. RBF mappings are now defined in terms of the applied solver (current options ` - - -``` - -Example: - -preCICE version 2 rbf configuration: - -```xml - -``` - -corresponding preCICE version 3 rbf configuration (using the recommended auto selection): - -```xml - - - -``` - -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. - -- Renamed `` to ` `. -- Remove all timings in the mapping configuration ``. -- Remove the preallocations in the mapping configuration ``. - - - -- Renamed the `` attributes `from` -> `acceptor` and `to` -> `connector`. - -- Moved and renamed the optional attribute `` to `` by ``. - -- 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). +- Rename the `` attributes `from` -> `acceptor` and `to` -> `connector`. +- You can now add `` after the `` tag if you need full profiling data. + +- Participants + - Replace `` with ``, and `` with ``. + - Move and rename the optional attribute `` to `` for parallel participants with `` or ``. + - Replace mapping constraint `scaled-consistent` with `scaled-consistent-surface`. + - Remove all timings in the mapping configuration ``. preCICE now fully controls the mapping. + - Remove the preallocations in the mapping configuration ``. We always use the superior `tree` method. + - Replace all RBF related `` tags. RBF mappings are now defined in terms of the applied solver (current options ` + + + ``` + + Example: + + preCICE version 2 RBF configuration: + + ```xml + + ``` + + corresponding preCICE version 3 RBF configuration (using the recommended auto selection): + + ```xml + + + + ``` + + 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. + + - Rename `` to ` `. + - 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: + - Removed deprecated action timings `regular-prior`, `regular-post`, `on-exchange-prior`, and `on-exchange-post`. + - Removed action timings `read-mapping-prior`, `write-mapping-prior`, and `on-time-window-complete-post`. + - Removed `ComputeCurvatureAction` and `ScaleByDtAction` actions. + - Removed callback functions `vertexCallback` and `postAction` from `PythonAction` interface. + - Removed timewindowsize from the `performAction` signature of `PythonAction`. The new signature is `performAction(time, data)` + - Using actions with multiple couping schemes and mixed time window sizes is not well defined! + +- Coupling schemes + - Remove `` in ``. Contact us if you need this feature. + - Replace `` by ``. Not defining convergence measures leads to iterations until `max-iterations` is reached. + - 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). + +## Building preCICE + +Rename CMake configuration variables as follows: + +- `PRECICE_PETScMapping` -> `PRECICE_FEATURE_PETSC_MAPPING` +- `PRECICE_MPICommunication` -> `PRECICE_FEATURE_MPI_COMMUNICATION` +- `PRECICE_Packages` -> `PRECICE_CONFIGURE_PACKAGE_GENERATION` +- `PRECICE_PythonActions` -> `PRECICE_FEATURE_PYTHON_ACTIONS` +- `PRECICE_ENABLE_C` -> `PRECICE_BINDINGS_C` +- `PRECICE_ENABLE_FORTRAN` ->`PRECICE_BINDINGS_FORTRAN` +- `PRECICE_ENABLE_LIBBACKTRACE` -> `PRECICE_FEATURE_LIBBACKTRACE_STACKTRACES` ## Language bindings