# What do the API methods in "Step 6 – Implicit coupling" do exactly?

I have 4 questions regarding: Step 6 – Implicit coupling (Step 6 – Implicit coupling | preCICE - The Coupling Library)
(I use the two figures from your website to describe my questions. One figure is the “Fixed time window” in Step 5 – Non-matching timestep sizes. The other figure is the pseudo-code in Step 6 – Implicit coupling)

``````My 1st question is about the condition “if(precice.isActionRequired(coric)){ // timestep not converged”:
``````

What will cause this condition to be TRUE?
My understanding is that it can be TRUE only when ADVANCE checks the convergence when time is at t^(n+1).
If the convergence is not satisfied, this time window is failed and precice will try to redo the time window t^n→t^(n+1), so reloadOldState().

``````My 2nd question is if this condition is FALSE, why does precice endTimeStep()?
``````

If solver A does subcycle and just finishes τ^(k-1), (we still need march τ^k to reach t^(n+1)), ADVANCE shouldn’t check convergence yet, so FALSE.
Then we enter this ELSE branch to endTimeStep(). But we should ask solver A to do τ^k instead of endTimeStep(), right?

``````My 3rd question is if timestep not converged, what will precice do to make it converge when redo the time window with reloadOldState()?
``````

My understanding is that reloadOldState() will restart from the status at t^n, right?

Some background is that:
For my implicit solver, it is based on a Newton-Raphson loop to solve each τ^(k-1).
If my implicit solver can’t converge for τ^(k-1), what it does is to reduce τ^(k-1) to a smaller time increment, for example 0.25*τ^(k-1) to retry.
Basically, my implicit solver retry the Newon loop with a smaller time increment to linearize the nonlinear problem if it is highly nonlinear.
We call this reduction of time increment size a cutback. The trade-off is we needs more number of time increments to solve the whole problem.

But it appears precice can’t use such a method because can be only either fixed or first-participant.

If my implicit solver reduces each τ^(k-1) (or in another words, my implicit solver increases the number of subcycles from t^n→t^(n+1)), is this a recommended way to redo the time window t^n→t^(n+1)?

If time window is small like t^(n+1)-t^n< τ^(k-1), my implicit solver should use the time increment size of t^(n+1)-t^n instead of its own τ^(k-1).
If here my implicit solver can’t converge, it will reduce to 0.25(t^(n+1)-t^n) to retry, then my implicit solver will enter subcycling too.

``````My last question is for both functions precice.readBlockVectorData and precice.writeBlockVectorData.
``````

Why don’t we put them under “if (precice.isReadDataAvailable())” and “if (precice.isWriteDataRequired(dt))” as in “Step 5 – Non-matching timestep sizes”.
My answer is that they are dummy here, meaning these two won’t have any effect on the results because they will be exchanged/refreshed only in ADVANCE when time reaches t^(n+1).

Thanks a lot in advance.
Best
Hongwu

Welcome @hongwuw

1. … the condition `if(precice.isActionRequired(coric))`: What will cause this condition to be TRUE?

`coric` stands for “constant read iteration checkpoint”. The condition is true when the solver needs to reset its internal variable to a saved checkpoint.

My understanding is that it can be TRUE only when ADVANCE checks the convergence when time is at t^(n+1). If the convergence is not satisfied, this time window is failed and precice will try to redo the time window t^n→t^(n+1), so reloadOldState().

Exactly.

1. … if this condition is FALSE, why does precice `endTimeStep()`?

If the condition is FALSE, this means implicitly that the coupling within this time window converged. Hence, the solver can end the current timestep and move forward in time.

If solver A does subcycle and just finishes τ^(k-1), (we still need march τ^k to reach t^(n+1)), ADVANCE shouldn’t check convergence yet, so FALSE.
Then we enter this ELSE branch to endTimeStep(). But we should ask solver A to do τ^k instead of endTimeStep(), right?

Both true. The example is in “Step 6” is a bit simplified (and will only work if both solvers use identical timestep sizes). What users typically do to also support subcycling is:

``````while interface.is_coupling_ongoing(): # main time loop

if interface.is_action_required(precice.action_write_iteration_checkpoint()):
u_checkpoint = u
t_checkpoint = t
interface.mark_action_fulfilled(precice.action_write_iteration_checkpoint())

# read data

dt = compute_adaptive_dt()
dt = min(precice_dt, dt)

u = solve_time_step(dt, u) # returns new solution

# write data

precice_dt = interface.advance(dt)
t += dt

if interface.is_action_required(precice.action_read_iteration_checkpoint()):
u = u_checkpoint
t = t_checkpoint
interface.mark_action_fulfilled(precice.action_read_iteration_checkpoint())
``````
1. … if timestep not converged, what will precice do to make it converge when redo the time window with reloadOldState()?

preCICE applies an acceleration method. Was this your question?

Some background is that:
For my implicit solver, it is based on a Newton-Raphson loop to solve each τ^(k-1).
If my implicit solver can’t converge for τ^(k-1), what it does is to reduce τ^(k-1) to a smaller time increment, for example 0.25*τ^(k-1) to retry.
Basically, my implicit solver retry the Newton loop with a smaller time increment to linearize the nonlinear problem if it is highly nonlinear.
We call this reduction of time increment size a cutback. The trade-off is we needs more number of time increments to solve the whole problem.
But it appears precice can’t use such a method because can be only either fixed or first-participant.

No, there is no problem here. Use a fixed time window. Within the time window, the solvers can do what they want (e.g. subcycle).

1. … is for both functions precice.readBlockVectorData and precice.writeBlockVectorData.
Why don’t we put them under “if (precice.isReadDataAvailable())” and “if (precice.isWriteDataRequired(dt))” as in “Step 5 – Non-matching timestep sizes”.
My answer is that they are dummy here, meaning these two won’t have any effect on the results because they will be exchanged/refreshed only in ADVANCE when time reaches t^(n+1).

Exactly. You can use these two optional safeguards here as well. We are removing these two with the upcoming preCICE v3.

Dear Benjamin,
Thanks a lot for your answers and warm welcome. Regarding my question
3, after I read your paper “Parallel coupling numerics for partitioned
fluid–structure interaction simulations” carefully, I think I get what
you mean (this is my first time to check this type of method like
Precice for FSI). If I understand correctly, the coupling problem is
casted into the fixed point equation, for a specific time-window,
Precice might need to loop through this time window several times with
the help of the fluid solver and the solid solver. Each such loop is
what Precice calls the Precice iteration. Finally, the fixed point is
found and becomes the solution for this specific time-window. While
for the explicit Precice coupling, there won’t be check on converging
to the fixed point. Once the solvers exchange solutions via Precice,
time is marched into next time window. Please correct me if I am wrong
here. So generally speaking, how many iterations will Precice do for a
time window? Any rough estimation on the convergence rate?
Thanks again
Best
Hongwu

All correct and well summarized

So generally speaking, how many iterations will Precice do for a time window? Any rough estimation on the convergence rate?

Number of iterations is hard to say. Depends on the coupled problem, material parameters, the geometry, the application, … For FSI, a larger added mass (lighter solid) is typically reflected in more iterations. Reducing the time window size helps for compressible flow, but not for incompressible flow.
Very rough estimate: 3-10 iterations for aerodynamic applications with incompressible flow. With compressible flow, even explicit coupling might be good enough. For hemodynamic applications, iterations could be higher.

Convergence rate: the quasi-Newton coupling does not have the second-order convergence rate a full Newton method would have once it is close enough to the solution, but is oftentimes still “fast enough”. There has been quite some literature. I review some of them in my dissertation (2016) (sections 3.2 and 3.3).
For more theoretical results, see for example the publications by C.T. Kelley, e.g. https://doi.org/10.1137/130919398.