scotch for Debian
-----------------

Metis/Parmetis compatibility libraries
--------------------------------------

Scotch provides a metis and parmetis interface which would allow one
to compile programs and libraries requiring metis whitout having to
install parmetis (which is a non-free software)

From release 6.1.1, the default Metis compatibility set in
library_metis.h has been configured to Metis v5 (build flag
-DSCOTCH_METIS_VERSION=5).

From release 7.0.0 both libscotchmetisv3.so and libscotchmetisv5.so
are built. Select between them by compiling with
-lscotchmetisv3 or -lscotchmetisv5
(-DSCOTCH_METIS_VERSION=3 or 5 will be needed if the metis.h
compatibility header is used)

Parmetis compatibility is provided through -lptscotchparmetisv3
(Parmetis v3 only).


Multi-threading and MPI
-----------------------

Scotch provides multithreading, but care must be taken when using in
conjunction with MPI. More discussion on binding threads to cores and
MPI processes is provided in the INSTALL.txt file (provided in the
upstream source and copied to the debian doc directories for
ptscotch).  e.g. OpenMPI:
 mpirun -np 2 --map-by socket --bind-to socket <program>

Particular care must be taken with Scotch 7 and later, since it now
provides dynamic thread management, which is a new feature and
therefore may result in a change in behaviour compared to previous
versions.


64-bit Scotch
-------------

A 64-bit build of SCOTCH (64-bit integers and indexing with INTSIZE=64
IDXSIZE=64) was previously provided in the custom int64 subdir.  To
align with other 64-bit packages, the 64-bit SCOTCH libraries are now
provided independently via libscotch-64-dev or libscotch-64i-dev (and
libptscotch-64*-dev, libscotchmetis-64*-dev, libscotchparmetis-64*-dev)
with corresponding executables in scotch-64* and ptscotch-64*. The
64-bit libraries have a distinct soname marked with a _64 or _64i
suffix, allowing installation alongside the standard 32-bit-int
libraries.

The *-64i packages provide full 64-bit support for both integers and
indexing (INTSIZE=64 and IDXSIZE=64).

The *-64 packages provide 64-bit indexing (IDXSIZE=64) for
SCOTCH_Idx but standard 32-bit integers for SCOTCH_Num.

Note that upstream allows suffix renaming of the Scotch API,
facilitating use of standard and 64-bit Scotch simulataneously from
the same client program. The Debian packages do not use this
facility. The API is identical for standard and 64-bit builds, only
the definition of SCOTCH_Num is different, with a corresponding
different ABI soname in the libraries. The goal for the Debian
packages is to enable alternative standard and 64-bit builds of client
packages rather than simultaneous use of both from one program.

Default (32-bit) header files have been moved from /usr/include to
/usr/include/scotch (in libscotch-dev). 64-bit header files are
provided by libscotch-64-dev in /usr/include/scotch_64,
and libscotch-64-dev in /usr/include/scotch_64i.
You may need to configure include paths
  -I/usr/include/scotch      to access the standard build
  -I/usr/include/scotch_64   to access 64-bit indexing (IDXSIZE=64 only)
  -I/usr/include/scotch_64i  to access the full 64-bit integer build

The dev packages now provide SCOTCH cmake config files.
Scotch can be found by cmake with

  find_package(SCOTCH)

providing  SCOTCH_INCLUDE_DIR  for the include paths
  e.g.  target_include_directories(hello PRIVATE ${SCOTCH_INCLUDE_DIR})
and  SCOTCH::scotch  (and SCOTCH::ptscotch) for linking to libraries
  e.g.  target_link_libraries(hello SCOTCH::scotch)

Cmake config files have been provided for the 64-bit builds to be used
alongside the standard build using the _64* suffix. Files are found in
.../cmake/scotch_64 identified via SCOTCH_64 for 64-bit indexing:

  find_package(SCOTCH_64)

or for full 64-bit integers and indexing,

  find_package(SCOTCH_64i)

and still provides SCOTCH_INCLUDE_DIR and SCOTCH::scotch, SCOTCH::ptscotch
for use by client packages (not SCOTCH_64::scotch or SCOTCH_64::scotch_64)

To allow dual builds of client packages with or without 64-bit integer
support, you might want to use a variable in your CMakeLists.txt

  find_package(SCOTCH_${SCOTCH_SONAME_SUFFIX})

and activate access to the 64-bit library with
  cmake -DSCOTCH_SONAME_SUFFIX=_64 ..
or
  cmake -DSCOTCH_SONAME_SUFFIX=_64i ..