NewtonHook.md

subroutine NewtonHook(...)

See also the newton-Lorenz template and comments within the Main file.

Usage notes.

• For the Hookstep to be calculated correctly, GMRES needs to converge within m iterations (each Newton iteration).
  • For a small system, simply equate m to the dimension of the system, $n$.
  • If the dimension is high and you are not integrating with timestepping, then you will need a preconditioner to assist GMRES.
  • If you are coupling with a timestepper and looking for an equilibrium, doubling $T$ will typically halve the GMRES iterations required each Newton iteration.
  • For a periodic orbit, $T$ should be sufficiently long already to keep m to a reasonable value.
  • Any implementation of GMRES(m) is likely to struggle if m gets to $O(1000)$, due to accumulated errors in the orthogonalisation. Aim to keep m $\sim 50$ or less.
• In the Fortran version, prior to calling the subroutine newtonhook(...), the arrays new_x(:) $\equiv{\bf x}_i$ and new_fx(:) $\equiv{\bf F}({\bf x}_i)$ need to be allocated with the dimension $n$: allocate(new_x(n),new_fx(n))
• Prior to calling newtonhook(...), the array variable new_x(:) must be assigned the initial guess ${\bf x}_0$. As the calculation proceeds, new_x(:) is updated with the improved solution, having smaller corresponding new_fx(:) .
• newtonhook(...) also needs to be passed
  • a function that calculates the dot product of two vectors,
  • a function that calculates ${\bf F}({\bf x})$ for a given ${\bf x}$,
  • a function that calculates $\frac{{\bf \partial F}}{\bf {\partial x}}\ {\bf \delta x}$ at ${{\bf x}_i}$ for a given ${\bf \delta x}$. See approximation in README.md and note that ${\bf F}({\bf x}_i)$ is already stored in new_fx(:).
  • a subroutine that replaces a vector ${\bf x}$ with the solution of $M{\bf x}'={\bf x}$ for ${\bf x}'$, where $M$ is a preconditioner matrix. This may simply be an empty subroutine if no preconditioner is required, i.e. $M=I$.
  • a subroutine that is called at the end of each iteration. This may be used to save the current state after each iteration, if desired.
• The functions above may require auxiliary data, in addition to the given ${\bf x}$ or ${\bf \delta x}$. There are several possible solutions, e.g.:
  • place the required data in a module and access via use mymodule.
  • place the data in a common block.
  • place the data in global variables (MATLAB).
  • write the vector to disk, call a script that runs an external programme, then load the result.
• Extra constraints may be necessary, e.g. that determine an update to the period of an orbit.
  The function that evaluates $\frac{{\bf \partial F}}{{\bf \partial x}}\ {\bf \delta x}$ for a given ${\bf \delta x}$ should append to the result the evaluations of the constraints. Correspondingly for each constraint, an extra 0 should be appended to ${\bf F}({\bf x}_i)$ (the evaluated constraint should equal zero when converged).

Parallel use

It is NOT necessary to edit this code for parallel (MPI) use:

• let each thread pass its subsection of the vector ${\bf x}$,
• make the dot product function mpi_allreduce the result of the dot product.
• to avoid multiple outputs to the terminal, set info=1 on rank 0 and info=0 for the other ranks.