The tuw_cvodeevolve extension is an Oxs time evolver class that provides
LLG integration via two methods from the Lawrence Livermore National
Laboratory's SUNDIALS/CVODE library, an Adams-Moulton method for
non-stiff problems, and a BDF method for stiff problems. This extension
was joint work circa 2000 between Vassilios Tsiantos from the Vienna
University of Technology (TU Wien) and Don Porter and Michael Donahue at
NIST.

The original code was written to the CVODE version 2.x interface, but
has been patched by Michael Donahue to build against Sundials versions
2.x through 7.x.

NB: Builds of tuw_cvodeevolve with Sundials versions 2.x and 3.x don't
pass the OOMMF oxsregression tests. This appears to be due to a change
in CVodeCreate() interface between releases 3.x and 4.0. The change
seems superficial as it does not appear to affect program correctness.

--- INSTALLATION NOTES ---
If CVODE include files and libraries are not in the standard system
compiler/linker search path, then modify the

   oommf/config/platforms/local/<platform>.tcl

file to include

   $config SetValue program_compiler_extra_include_dirs <header_dirs>
   $config SetValue program_linker_extra_lib_dirs <lib_dirs>

with appropriate header_dirs and lib_dirs. Depending on your compiler,
an alternative may be adjusting some environment variables. For example,
on Linux and macOS you can set

   export CPLUS_INCLUDE_PATH=<header_dirs>
   export LIBRARY_PATH=<lib_dirs>

Note: Settings in the <platform.tcl> file take precedence over
environment variables.

If the compiler complains about std::make_unique not being defined, the
issue is that the C++ headers in Sundials versions 6 and later use
std::make_unique. As of this date (July 2024) OOMMF by default builds
using the C++11 standard, whereas std::make_unique is a C++14 feature. A
workaround has been placed in tuw_cvodeevolve.h, but if that fails then
try adjusting the compiler standards compliance C++ flags in the
oommf/config/platforms/local/<platform>.tcl file. For example, for the
GNU g++ compiler use

   $config SetValue program_compiler_c++_remove_flags {--std=c[+][+]11}
   $config SetValue program_compiler_c++_add_flags    {--std=c++14}

(The brackets around the +'s in the first of these is necessary because
OOMMF interprets the remove flags as a regular expressions.)

If you get an error message about the linker not being able to find some
library, then check the linker search path. On Linux and macOS you can
adjust the link-time search path with the environment variable
LIBRARY_PATH, or you can adjust the platform program_linker_extra_args
as described above.

If you get linker error messages about undefined references then the
link command is either missing a library or is linking to the wrong one
(i.e., a mismatch between the Sundials C compiler headers and the link
library versions). The former can be fixed with the program_linker_args
option in oommf/config/platforms/local/<platform>.tcl. The syntax varies
by platform and linker, but on Linux the setting should look like

   $config SetValue program_linker_extra_args \
      {-L/opt/local/lib -lsundials_core}

Here '-L' adds to the library search path and '-l' specifies the library
stem name. On Linux and macOS you may be able to identify which
libraries to add using the 'nm -g' command, which lists library symbol
tables.

If you have multiple versions of Sundials installed and the linker is
grabbing the wrong one, then on Linux you can use a line like

   $config SetValue program_linker_extra_args \
      {-l:libsundials_cvode.so.2 -l:libsundials_nvecserial.so.2}

to select the specific library version. As a particular example, the error
message

  ... undefined reference to `CVSpgmr'
  ... undefined reference to `CVSpilsSetGSType'

indicates a compile with Sundials 2.x headers linking against Sundials
3 or later libraries.

If the build is successful but you encounter a library load error when
running oxs, check the oxs executable runtime dependencies. On Linux use

   ldd app/oxs/linux-x86_64/oxs

and on macOS

   otool -L app/oxs/darwin/oxs

If necessary, adjust the dynamic linker/loader search path with the
environment variable LD_LIBRARY_PATH on Linux and DYLD_LIBRARY_PATH or
DYLD_FALLBACK_LIBRARY_PATH on macOS. See the manpages for ld.so and
dyld, respectively, for details.

On macOS, if you get this error when launching oxs:

   dyld[#]: symbol not found in flat namespace (_klu_analyze)

then check that "-lklu" is on the pimake oxs link line; it should be
added automatically by the

   app/oxs/local/tuw_cvodeevolve/tuw_cvodeevolve.rules

build script, but if not then add "-lklu" to the the
program_linker_extra_args setting described above.

-Michael Donahue, 7-Aug-2024

