Skip to content

Commit 7df148d

Browse files
gardner48gardner48
committed
Feature: KINSOL relax requirements on KINSetMAA and KINSetOrthAA (#742)
Update `KINSetMAA` and `KINSetOrthAA` to allow for setting the Anderson acceleration depth and orthogonalization method after `KINInit`. Additionally, `KINSetMAA` and `KINSetNumMaxIters` may now be called in any order.
1 parent 648c230 commit 7df148d

File tree

19 files changed

+468
-526
lines changed

19 files changed

+468
-526
lines changed

‎CHANGELOG.md‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,11 @@
66

77
### New Features and Enhancements
88

9+
The functions `KINSetMAA` and `KINSetOrthAA` have been updated to allow for
10+
setting the Anderson acceleration depth and orthogonalization method after
11+
`KINInit`. Additionally, `KINSetMAA` and `KINSetNumMaxIters` may now be called
12+
in any order.
13+
914
### Bug Fixes
1015

1116
The shared library version numbers for the oneMKL dense linear solver and

‎doc/kinsol/guide/source/Usage/index.rst‎

Lines changed: 30 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -1008,28 +1008,40 @@ negative, so a test ``retval`` :math:`<0` will catch any error.
10081008
10091009
.. c:function:: int KINSetMAA(void * kin_mem, long int maa)
10101010
1011-
The function :c:func:`KINSetMAA` specifies the size of the subspace used with
1012-
Anderson acceleration in conjunction with Picard or fixed-point iteration.
1011+
The function :c:func:`KINSetMAA` specifies the Anderson acceleration subspace
1012+
size (depth) in the Picard or fixed-point iteration.
1013+
1014+
The default depth is 0, indicating no acceleration. Providing a value
1015+
:math:`> 0` will enable acceleration. The input ``maa`` must be less than the
1016+
maximum number of iterations allowed, ``mxiter`` (see
1017+
:c:func:`KINSetNumMaxIters`). This limit is enforced within :c:func:`KINSol`,
1018+
so :c:func:`KINSetMAA` and :c:func:`KINSetNumMaxIters` may be called in any
1019+
order. If ``maa`` is greater than or equal to ``mxiter``, it is set to the
1020+
maximum possible depth, ``maa = mxiter - 1``.
10131021
10141022
**Arguments:**
10151023
* ``kin_mem`` -- pointer to the KINSOL memory block.
1016-
* ``maa`` -- subspace size for various methods. A value of 0 means no acceleration, while a positive value means acceleration will be done.
1024+
* ``maa`` -- subspace size for various methods. A value of 0 means no
1025+
acceleration, while a positive value means acceleration will be done.
10171026
10181027
**Return value:**
10191028
* ``KIN_SUCCESS`` -- The optional value has been successfully set.
10201029
* ``KIN_MEM_NULL`` -- The ``kin_mem`` pointer is ``NULL``.
10211030
* ``KIN_ILL_INPUT`` -- The argument ``maa`` was negative.
10221031
1023-
**Notes:**
1024-
This function sets the subspace size, which needs to be :math:`> 0` if
1025-
Anderson Acceleration is to be used. It also allocates additional memory
1026-
necessary for Anderson Acceleration. The default value of ``maa`` is 0,
1027-
indicating no acceleration. The value of ``maa`` should always be less
1028-
than ``mxiter``. This function MUST be called before calling
1029-
:c:func:`KINInit`. If the user calls the function KINSetNumMaxIters, that
1030-
call should be made before the call to KINSetMAA, as the latter uses the
1031-
value of ``mxiter``.
1032+
.. note::
1033+
1034+
Users solving a series of problems with the same KINSOL instance and
1035+
changing the maximum number of iterations between :c:func:`KINSol` calls
1036+
may need to also call :c:func:`KINSetMAA` to adjust the depth as its value
1037+
may have been limited in the last :c:func:`KINSol` call to enforce ``maa <
1038+
mxiter``.
10321039
1040+
.. versionchanged:: x.y.z
1041+
1042+
This function can now be called any time after :c:func:`KINCreate` (i.e.,
1043+
it no longer needs to be call before :c:func:`KINInit`) and may be called
1044+
before or after :c:func:`KINSetNumMaxIters`.
10331045
10341046
.. c:function:: int KINSetDampingAA(void * kin_mem, sunrealtype beta)
10351047
@@ -1098,12 +1110,14 @@ negative, so a test ``retval`` :math:`<0` will catch any error.
10981110
* ``KIN_ILL_INPUT`` -- The argument ``orthaa`` was not one of the predefined
10991111
orthogonalization routines defined in KINSOL.
11001112
1101-
.. note::
1113+
**Examples codes:**
1114+
1115+
* ``examples/kinsol/serial/kinAnalytic_fp.c``
11021116
1103-
This function *must* be called before calling :c:func:`KINInit`.
1117+
.. versionchanged:: x.y.z
11041118
1105-
An example of how to use this function can be found in
1106-
``examples/kinsol/serial/kinAnalytic_fp.c``
1119+
This function can now be called any time after :c:func:`KINCreate` (i.e.,
1120+
it no longer needs to be call before :c:func:`KINInit`).
11071121
11081122
11091123
.. c:function:: int KINSetDampingFn(void* kin_mem, KINDampingFn damping_fn)

‎doc/shared/RecentChanges.rst‎

Lines changed: 9 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -5,6 +5,11 @@
55

66
**New Features and Enhancements**
77

8+
The functions :c:func:`KINSetMAA` and :c:func:`KINSetOrthAA` have been updated
9+
to allow for setting the Anderson acceleration depth and orthogonalization
10+
method after :c:func:`KINInit`. Additionally, :c:func:`KINSetMAA` and
11+
:c:func:`KINSetNumMaxIters` may now be called in any order.
12+
813
**Bug Fixes**
914

1015
The shared library version numbers for the oneMKL dense linear solver and
@@ -13,9 +18,10 @@ matrix as well as the PETSc SNES nonlinear solver have been corrected.
1318
Fixed a CMake bug where the MRI H-Tol controller was not included in the ARKODE
1419
Fortran module.
1520

16-
Fixed a bug in the CUDA and HIP implementations of ``SUNMemoryHelper_CopyAsync``
17-
where the execution stream is not extracted correctly from the helper when a
18-
stream is not provided to ``SUNMemoryHelper_CopyAsync``.
21+
Fixed a bug in the CUDA and HIP implementations of
22+
:c:func:`SUNMemoryHelper_CopyAsync` where the execution stream is not extracted
23+
correctly from the helper when a stream is not provided to
24+
:c:func:`SUNMemoryHelper_CopyAsync`.
1925

2026
Fixed a bug in MRIStep where a segfault would occur when an MRI coupling table
2127
is not explicitly set and an MRI integrator is nested inside another MRI

‎examples/kinsol/CUDA_mpi/kin_em_mpicuda.cu‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -283,6 +283,10 @@ int main(int argc, char* argv[])
283283
void* kin_mem = KINCreate(sunctx);
284284
if (check_retval((void*)kin_mem, "KINCreate", 0)) { return 1; }
285285

286+
// Set Fixed Point Function
287+
retval = KINInit(kin_mem, FPFunction, u);
288+
if (check_retval(&retval, "KINInit", 1)) { return 1; }
289+
286290
// Set number of prior residuals used in Anderson Acceleration
287291
retval = KINSetMAA(kin_mem, udata->maa);
288292
if (check_retval(&retval, "KINSetMAA", 0)) { return 1; }
@@ -291,10 +295,6 @@ int main(int argc, char* argv[])
291295
retval = KINSetOrthAA(kin_mem, udata->orthaa);
292296
if (check_retval(&retval, "KINSetOrthAA", 0)) { return 1; }
293297

294-
// Set Fixed Point Function
295-
retval = KINInit(kin_mem, FPFunction, u);
296-
if (check_retval(&retval, "KINInit", 1)) { return 1; }
297-
298298
// Specify tolerances
299299
retval = KINSetFuncNormTol(kin_mem, udata->rtol);
300300
if (check_retval(&retval, "KINSetFuncNormTol", 1)) { return 1; }

‎examples/kinsol/CXX_parallel/kin_em_p.cpp‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -215,6 +215,10 @@ int main(int argc, char* argv[])
215215
void* kin_mem = KINCreate(sunctx);
216216
if (check_retval((void*)kin_mem, "KINCreate", 0)) { return 1; }
217217

218+
// Set Fixed Point Function
219+
retval = KINInit(kin_mem, FPFunction, u);
220+
if (check_retval(&retval, "KINInit", 1)) { return 1; }
221+
218222
// Set number of prior residuals used in Anderson Acceleration
219223
retval = KINSetMAA(kin_mem, udata->maa);
220224
if (check_retval(&retval, "KINSetMAA", 0)) { return 1; }
@@ -223,10 +227,6 @@ int main(int argc, char* argv[])
223227
retval = KINSetOrthAA(kin_mem, udata->orthaa);
224228
if (check_retval(&retval, "KINSetOrthAA", 0)) { return 1; }
225229

226-
// Set Fixed Point Function
227-
retval = KINInit(kin_mem, FPFunction, u);
228-
if (check_retval(&retval, "KINInit", 1)) { return 1; }
229-
230230
// Specify tolerances
231231
retval = KINSetFuncNormTol(kin_mem, udata->rtol);
232232
if (check_retval(&retval, "KINSetFuncNormTol", 1)) { return 1; }

‎examples/kinsol/CXX_parallel/kin_heat2D_nonlin_p.cpp‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -155,6 +155,10 @@ int main(int argc, char* argv[])
155155
void* kin_mem = KINCreate(sunctx);
156156
if (check_retval((void*)kin_mem, "KINCreate", 0)) { return 1; }
157157

158+
// Set Fixed Point Function
159+
retval = KINInit(kin_mem, FPFunction, u);
160+
if (check_retval(&retval, "KINInit", 1)) { return 1; }
161+
158162
// Set number of prior residuals used in Anderson Acceleration
159163
retval = KINSetMAA(kin_mem, udata->maa);
160164
if (check_retval(&retval, "KINSetMAA", 0)) { return 1; }
@@ -163,10 +167,6 @@ int main(int argc, char* argv[])
163167
retval = KINSetOrthAA(kin_mem, udata->orthaa);
164168
if (check_retval(&retval, "KINSetOrthAA", 0)) { return 1; }
165169

166-
// Set Fixed Point Function
167-
retval = KINInit(kin_mem, FPFunction, u);
168-
if (check_retval(&retval, "KINInit", 1)) { return 1; }
169-
170170
// Specify tolerances
171171
retval = KINSetFuncNormTol(kin_mem, udata->rtol);
172172
if (check_retval(&retval, "KINSetFuncNormTol", 1)) { return 1; }

‎examples/kinsol/CXX_parhyp/kin_bratu2D_hypre_pfmg.cpp‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -164,6 +164,10 @@ int main(int argc, char* argv[])
164164
void* kin_mem = KINCreate(sunctx);
165165
if (check_retval((void*)kin_mem, "KINCreate", 0)) { return 1; }
166166

167+
// Set Fixed Point Function
168+
retval = KINInit(kin_mem, FPFunction, u);
169+
if (check_retval(&retval, "KINInit", 1)) { return 1; }
170+
167171
// Set number of prior residuals used in Anderson Acceleration
168172
retval = KINSetMAA(kin_mem, udata->maa);
169173
if (check_retval(&retval, "KINSetMAA", 1)) { return 1; }
@@ -172,10 +176,6 @@ int main(int argc, char* argv[])
172176
retval = KINSetOrthAA(kin_mem, udata->orthaa);
173177
if (check_retval(&retval, "KINSetOrthAA", 1)) { return 1; }
174178

175-
// Set Fixed Point Function
176-
retval = KINInit(kin_mem, FPFunction, u);
177-
if (check_retval(&retval, "KINInit", 1)) { return 1; }
178-
179179
// Specify tolerances
180180
retval = KINSetFuncNormTol(kin_mem, udata->rtol);
181181
if (check_retval(&retval, "KINSetFuncNormTol", 1)) { return 1; }

‎examples/kinsol/CXX_parhyp/kin_heat2D_nonlin_hypre_pfmg.cpp‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,10 @@ int main(int argc, char* argv[])
176176
void* kin_mem = KINCreate(sunctx);
177177
if (check_retval((void*)kin_mem, "KINCreate", 0)) { return 1; }
178178

179+
// Set Fixed Point Function
180+
retval = KINInit(kin_mem, FPFunction, u);
181+
if (check_retval(&retval, "KINInit", 1)) { return 1; }
182+
179183
// Set number of prior residuals used in Anderson Acceleration
180184
retval = KINSetMAA(kin_mem, udata->maa);
181185
if (check_retval(&retval, "KINSetMAA", 1)) { return 1; }
@@ -184,10 +188,6 @@ int main(int argc, char* argv[])
184188
retval = KINSetOrthAA(kin_mem, udata->orthaa);
185189
if (check_retval(&retval, "KINSetOrthAA", 1)) { return 1; }
186190

187-
// Set Fixed Point Function
188-
retval = KINInit(kin_mem, FPFunction, u);
189-
if (check_retval(&retval, "KINInit", 1)) { return 1; }
190-
191191
// Specify tolerances
192192
retval = KINSetFuncNormTol(kin_mem, udata->rtol);
193193
if (check_retval(&retval, "KINSetFuncNormTol", 1)) { return 1; }

‎examples/kinsol/F2003_serial/kinLaplace_picard_kry_f2003.f90‎

Lines changed: 1 addition & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -418,7 +418,7 @@ subroutine PrintFinalStats(kmem)
418418

419419
integer(c_int) :: ierr
420420
integer(c_long) :: nni(1), nli(1), ncfl(1), nfe(1), nfeLS(1), njvevals(1)
421-
integer(c_long) :: npe(1), nps(1), lenrw(1), leniw(1), lenrwLS(1), leniwLS(1)
421+
integer(c_long) :: npe(1), nps(1)
422422

423423
!======= Internals ============
424424

@@ -474,31 +474,12 @@ subroutine PrintFinalStats(kmem)
474474
stop 1
475475
end if
476476

477-
! Main solver workspace size
478-
479-
ierr = FKINGetWorkSpace(kmem, lenrw, leniw)
480-
if (ierr /= 0) then
481-
print *, 'Error in FKINGetWorkSpace, ierr = ', ierr, '; halting'
482-
stop 1
483-
end if
484-
485-
! Linear solver workspace size
486-
487-
ierr = FKINGetLinWorkSpace(kmem, lenrwLS, leniwLS)
488-
if (ierr /= 0) then
489-
print *, 'Error in FKINGetLinWorkSpace, ierr = ', ierr, '; halting'
490-
stop 1
491-
end if
492-
493477
print *, ' '
494478
print '(A)', 'Final Statistics..'
495479
print *, ' '
496480
print '(3(A,i6))', 'nni = ', nni, ' nli = ', nli, ' ncfl = ', ncfl
497481
print '(3(A,i6))', 'nfe = ', nfe, ' nfeLS = ', nfeLS, ' njt = ', njvevals
498482
print '(2(A,i6))', 'npe = ', npe, ' nps = ', nps
499-
print *, ' '
500-
print '(2(A,i6))', 'lenrw = ', lenrw, ' leniw = ', leniw
501-
print '(2(A,i6))', 'lenrwLS = ', lenrwLS, ' leniwLS = ', leniwLS
502483

503484
return
504485

‎examples/kinsol/F2003_serial/kinLaplace_picard_kry_f2003.out‎

Lines changed: 0 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,3 @@ Final Statistics..
2727
nni = 42 nli = 350 ncfl = 31
2828
nfe = 43 nfeLS = 0 njt = 392
2929
npe = 0 nps = 0
30-
31-
lenrw = 19237 leniw = 42
32-
lenrwLS = 15529 leniwLS = 37

0 commit comments

Comments
 (0)