ufl_legacy and Dolfin
---------------------

UFL 2023 is no longer compatible with legacy dolfin. The last
compatible UFL version 2022 is now provided separately as ufl_legacy
(python3-ufl-legacy). dolfin now uses ufl_legacy.

Depending on how you use dolfin and ufl, you may need to update
scripts, e.g. replace
    import ufl
with
    import ufl_legacy as ufl

or replace
    from ufl import FunctionSpace
with
    from ufl_legacy import FunctionSpace

If you use ufl classes from the dolfin namespace rather than the ufl
namespace, for instance `from dolfin import *; V=FunctionSpace(mesh,el)`
rather than `import ufl; V=ufl.FunctionSpace(mesh,el)`, then no code
changes should be needed

64-bit Dolfin
-------------

64-bit support is provided by python3-dolfin64-real and libdolfin64-dev.

64-bit here refers to 64-bit indexing provided by a 64-bit build of
PETSc, allowing handling of larger systems (larger meshes) with more
than 2 billion degress of freedom.

This is activated by setting PETSC_DIR and SLEPC_DIR to appropriate paths,
e.g.
  PETSC_DIR=/usr/lib/petsc64
  SLEPC_DIR=/usr/lib/slepc64

Depending on usage you may also need to specific the dolfin libname
extension ("64") to link to libdolfin64.so rather than libdolfin.so.
This is controlled via DOLFIN_LIB_NAME_EXT.
For cmake (C++ applications), set the cmake variable
  cmake -DDOLFIN_LIB_NAME_EXT=64
For python, set it as an environment variable
  DOLFIN_LIB_NAME_EXT=64 python3

Both PETSC_DIR (SLEPC_DIR) and DOLFIN_LIB_NAME_EXT need to be set to
ensure the program links to both libpetsc64_*.so and libdolfin64.so.

dijitso cache files are hashed by source file, not link library,
meaning subsequent use of the same source file will not distinguish
between a cached file linked against standard or 64-bit dolfin. The
discrepancy may result in runtime errors. To avoid this, use a
separate cache by defining the environment variable DIJITSO_CACHE_DIR
e.g.
  DIJITSO_CACHE_DIR=.dijitso_cache
or
  DIJITSO_CACHE_DIR=.dijitso_cache_64
and clean the cache if needed, with 'dijitso clean'.

python3-dolfin is now a base package providing a dolfin.pth pointing
by default at the preferred PETSc installation provided by
python3-dolfin-real (for PETSC_DIR=/usr/lib/petsc
SLEPC_DIR=/usr/lib/slepc).


Conditional Support for SuperLU-Dist
------------------------------------

In principle dolfin supports SuperLU-Dist. However the superlu-dist
package distributed by Debian is mostly useless since mc64, one of its
core functions, cannot legally be redistributed and so has been
removed from the Debian package. For this reason, we have given
preference to mumps over superlu_dist.

You may specify superlu_dist if desired (or if you have a local build
of superlu_dist that includes mc64), for instance with 
  solve(a == L, u, bc, solver_parameters={'linear_solver': 'superlu_dist'})

You may also successfully use superlu_dist without mc64 by specifying
C++:
  PETScOptions::set("-mat_superlu_dist_rowperm", "NATURAL");
Python:
  PETScOptions.set('-mat_superlu_dist_rowperm', 'NATURAL')
Performance will likely be reduced.

The same problem applies to superlu, from which mc64 has also been
removed. superlu still functions successfully however (mc64 is not
core for the serial version of SuperLU).

Internet availability for pusimp integration tests
--------------------------------------------------

The goal of some pusimp integration tests is to create a dirty virtualenv
in which some of dolfin dependecies are replaced with a manually installed
package from PyPI, and verify that pusimp actually triggers an error while
trying to import dolfin.
However, to create such virtualenv environment the build needs to be allowed
to download packages from pypi.org.

pusimp integration tests are run only with autopkgtest and are not run while
building the package, because python3-dolfin-{real,complex} is built using
setup.py rather than querying pybuild.

The file test/debian-only/test_pusimp.py gracefully handles a missing network
by checking for internet availability trying to fetch www.debian.org via
python3-requests. If networks is unreachable, all tests in the file will be
skipped, and pusimp integration will only be partially tested.
