Changes from previous releases
==============================

6.1.1
-----
A maintenance release on top of 6.1.0, focused on build and packaging
robustness across Windows (MSVC), macOS, conda-forge and pip.  There are no
API or numerical changes.

Highlights
~~~~~~~~~~
 - esys-escript now compiles cleanly with the Windows MSVC toolchain.
 - macOS shared libraries and Python extensions carry an RPATH, so
   ``import esys.escript`` works from a plain interpreter without
   ``run-escript``.
 - conda-forge and pip packaging fixes.
 - The ``run-escript`` man page is consistent with the launcher's options.

Windows / MSVC build
~~~~~~~~~~~~~~~~~~~~~~
 - Use ``&&`` instead of the ``and`` keyword, ``unsigned int`` instead of the
   POSIX ``uint``, signed loop counters for OpenMP ``for`` loops, and an
   explicit ``std::complex<double>`` where MSVC requires it.
 - Guard POSIX-only calls in ``Utils.cpp`` behind ``_WIN32``.
 - Do not propagate ``ESCRIPT_EXPORTS`` to the Python wrapper on Windows;
   skip ``pythonMPIcpp.pyd`` when mpi4py is disabled.
 - Probe for the MUMPS MPI shim header on Windows and ``#undef
   MPI_COMM_WORLD`` before including it.
 - Fix MSVC narrowing warnings; this also uncovered a latent Paso bug, where
   the ``Options::reordering`` field was ``bool`` but must be ``index_t``.

macOS
~~~~~
 - Bake ``<prefix>/lib/esys`` (and ``<prefix>/lib``) as an RPATH into every
   shared library and extension, so bare imports and the SCons configure
   probes resolve ``libomp``/``libgomp`` without ``LD_LIBRARY_PATH``.
   (``SHLINKFLAGS`` rpath dropped as ``LINKFLAGS`` already covers it.)
 - Fix an OpenMP duplicate-runtime abort in Homebrew builds.
 - Drop the deprecated ``boost::math::complex::acos`` fallback.

Packaging
~~~~~~~~~
 - pip: only run the lib-path bootstrap when the ``esys_escript_lib/``
   directory is present, so bare ``import esys`` works for conda and system
   installs.
 - conda-forge recipe updated for the 6.1 series.

Build system
~~~~~~~~~~~~
 - More robust Boost.NumPy detection: find NumPy's include directory early,
   normalise ``boost_libs`` before concatenation, and surface the probe
   exception text on failure.
 - Use raw strings for the gmsh GEO templates; split ``ld_extra`` into
   separate link arguments; generate ``run_escript.py`` before the escript
   SConscript runs.

Other fixes
~~~~~~~~~~~
 - Fix self-initialisation of ``X``/``Y``/``D`` in the Speckley
   ``DefaultAssembler2D``.

Documentation
~~~~~~~~~~~~~
 - The ``run-escript`` man page now documents all launcher options (adds
   ``-a`` and ``-x``), corrects the ``-p``/``-f``/``-i``/``-o`` descriptions,
   and drops the untested ``-m`` (valgrind) option.

6.1
---
Highlights
~~~~~~~~~~
 - Trilinos has been upgraded from version 14 to **Trilinos 17.0.0** (bundled
   source built in-tree).  V14 source has been removed.
 - New public ``SolverFramework`` class replaces the ``SO_PACKAGE_PASO`` /
   ``SO_PACKAGE_TRILINOS`` constants and the ``setPackage`` API.  Domains can
   now be created with ``framework=SolverFramework.trilinos()`` (or ``.paso()``)
   to pin the linear-algebra back-end at construction time.
 - Major MPI-correctness fixes in Speckley, Ripley and the Trilinos wrapper
   (see below).  The test suite now runs cleanly under MPI > 1 ranks and
   under multi-thread OpenMP, where it previously aborted or silently produced
   corrupt matrices.
 - HDF5 dumping/loading support for complex Data, including mesh data.
 - InterpolationTable class for 1-D/2-D/3-D table-based interpolation,
   including complex-valued tables; replaces the deprecated
   ``Data.interpolateTable`` (issues #41, #55, #121).
 - macOS arm64 (Apple Silicon) build support, including Trilinos with MueLu
   and METIS via Homebrew.
 - GitHub Actions CI extended to test option templates across multiple Linux
   distributions and macOS.

Solvers and Trilinos integration
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 - ``SolverFramework`` API; tests updated from ``setPackage`` to ``framework=``.
 - Trilinos 17.0.0 default; older 16.x source removed.
 - METIS / ParMETIS / Scotch / PT-Scotch as configurable dependencies; paths
   passed through to the Trilinos build.
 - Complex PDE solver defaults and compatibility fixes for Trilinos.
 - Fix Belos GMRES NaN bug for complex scalar types (issue #131).
 - Fix silent convergence failure in Belos solvers.
 - Fix PCG API: callers updated after return-value change, iteration history
   now optionally returned.
 - Fix MinimizerLBFGS restart mechanism and re-enable it (issue #105); alpha
   resets to ``initialAlpha`` on breakdown.

MPI correctness fixes
~~~~~~~~~~~~~~~~~~~~~
 - Fix ``BlockCrsMatrixWrapper::nullifyRowsAndCols`` crash under MPI for
   system PDEs (e.g. LameEquation): the loop cast a local block-row index as
   a global ordinal, leading to ``std::vector(max_size())`` aborts or
   deadlocks at >1 ranks.
 - Templatise Speckley ``Brick`` neighbour-exchange functions to support
   complex Data.  Previously hard-coded ``double *`` / ``MPI_DOUBLE`` caused
   heap corruption (``corrupted double-linked list`` etc.) when complex
   coefficients were sent across rank boundaries.
 - Enable Nodes->Dirac and DOF->Dirac interpolation in Ripley under MPI.
 - Serialise ``Tpetra::CrsMatrix::sumIntoLocalValues`` in the Trilinos wrapper
   with ``#pragma omp critical``: previously a Kokkos
   ``SharedAllocationRecord`` race aborted Order-2 FEM assembly under
   OpenMP threading; the previously-skipped Order-2 ILU tests are
   re-enabled now that the underlying race is gone.

I/O and data handling
~~~~~~~~~~~~~~~~~~~~~
 - HDF5 dump/load for Data, including complex numbers and mesh data; netCDF
   dependency removed in favour of HDF5.
 - ``InterpolationTable`` (1-D/2-D/3-D, real or complex) with order-0 and
   order-1 interpolation; ``Data.interpolateTable`` deprecated.
 - Fix Python 3 ``zip()`` incompatibility in the Silo test comparator.
 - ``copyWithMask`` correctly handles a scalar mask on non-scalar data
   (issue #47).

Build system and platforms
~~~~~~~~~~~~~~~~~~~~~~~~~~
 - macOS arm64 (Apple Silicon) support: Apple Clang + libomp, LLVM Clang +
   Python 3.14, ``--break-system-packages`` handling for pip on PEP 668
   systems, Homebrew packages preferred over pip, brew zlib/LAPACK/OpenBLAS
   wired up.
 - Option templates restructured: each platform has a base MPI variant and
   a ``_nompi`` variant.  Defaults switched ``build_trilinos`` from ``make``
   to ``check`` so partial builds reuse an existing Trilinos.
 - ``trilinos_cc`` / ``trilinos_cxx`` build options to override the compiler
   used for the Trilinos build (needed for MueLu on macOS arm64).
 - Linux distros covered in CI: Ubuntu, Debian, Mint, Sid, Arch, OpenSUSE,
   Rocky Linux.  Job timeouts raised to 120 minutes for Trilinos builds.
 - ``run-escript`` launcher fixes for macOS CPU detection and for Windows
   install paths containing spaces (issue #117).
 - The generated ``escript/py_src/run_escript.py`` is no longer source-
   controlled; it is regenerated by scons on every build from
   ``run_escript_py.in``.
 - C++20 destructor syntax fix in ``DataVectorAlt``.

Documentation
~~~~~~~~~~~~~
 - User guide updated for the SolverFramework API.
 - Sphinx documentation restructured; user guide content linked from the
   landing page, examples ZIP/TAR.GZ archives generated alongside the API
   reference.
 - Third-party license notices added for Trilinos and p4est.
 - Installation instructions refreshed: Windows/WSL2 section, current Linux
   Mint instructions, python3-silo dependency noted, dynamic Python
   detection in option templates.
 - Copyright updated to 2026.

Test suite
~~~~~~~~~~
 - Test suite now passes cleanly under ``-t1 -n4 -p1`` (MPI), ``-t4 -n1 -p1``
   (OpenMP), and ``-t3 -n2 -p1`` (mixed).
 - Many MPI-rank-specific skips refined: 3D Multiresolution tests skip at
   ``mpiSize > 1`` (issue #132), odd-rank-count cases skip where Ripley's
   1xN decomposition exceeds a filter footprint, and the test_complex_table
   case uses ``Lsup`` instead of ``toListOfTuples`` so it is MPI-safe.

Removed
~~~~~~~
 - Trilinos 14 (replaced by Trilinos 17).
 - ``dudley`` module references; dudley itself was removed in 6.0.
 - ``splitworld`` references.
 - ``convert_latex.py`` and other obsolete scripts.
 - Demo / experiment scripts that previously sat in the repository root.

Known issues
~~~~~~~~~~~~
 - 3D Multiresolution domains (``MultiBrick``) do not yet support MPI;
   tests are skipped (issue #132).
 - ``run_savesilo_tests`` and ``run_savevtk_tests`` skip under MPI because
   their comparators assume single-block reference files; ``saveSilo``
   itself produces correct PMPIO output (issue #133).
 - Kokkos may report a finalize-time crash with Trilinos on shutdown;
   utest.sh treats exit code 134/139 as success when they occur after a
   successful run (issue #127).

6.0
---
 - escript now uses Trilinos 14.
 - escript now has a built-in Trilinos 14 compiler.
 - escript now utilises the p4est library.
 - The dudley module has been removed.
 - The oxley module has been added but is not fully functional yet.
 - sympy has been switched off.
 - packages downunder and models have been removed.

