Debian Codegraph @

debian/README.Debian

raw
1 ufl_legacy and Dolfin
2 ---------------------
3
4 UFL 2023 is no longer compatible with legacy dolfin. The last
5 compatible UFL version 2022 is now provided separately as ufl_legacy
6 (python3-ufl-legacy). dolfin now uses ufl_legacy.
7
8 Depending on how you use dolfin and ufl, you may need to update
9 scripts, e.g. replace
10 import ufl
11 with
12 import ufl_legacy as ufl
13
14 or replace
15 from ufl import FunctionSpace
16 with
17 from ufl_legacy import FunctionSpace
18
19 If you use ufl classes from the dolfin namespace rather than the ufl
20 namespace, for instance `from dolfin import *; V=FunctionSpace(mesh,el)`
21 rather than `import ufl; V=ufl.FunctionSpace(mesh,el)`, then no code
22 changes should be needed
23
24 64-bit Dolfin
25 -------------
26
27 64-bit support is provided by python3-dolfin64-real and libdolfin64-dev.
28
29 64-bit here refers to 64-bit indexing provided by a 64-bit build of
30 PETSc, allowing handling of larger systems (larger meshes) with more
31 than 2 billion degress of freedom.
32
33 This is activated by setting PETSC_DIR and SLEPC_DIR to appropriate paths,
34 e.g.
35 PETSC_DIR=/usr/lib/petsc64
36 SLEPC_DIR=/usr/lib/slepc64
37
38 Depending on usage you may also need to specific the dolfin libname
39 extension ("64") to link to libdolfin64.so rather than libdolfin.so.
40 This is controlled via DOLFIN_LIB_NAME_EXT.
41 For cmake (C++ applications), set the cmake variable
42 cmake -DDOLFIN_LIB_NAME_EXT=64
43 For python, set it as an environment variable
44 DOLFIN_LIB_NAME_EXT=64 python3
45
46 Both PETSC_DIR (SLEPC_DIR) and DOLFIN_LIB_NAME_EXT need to be set to
47 ensure the program links to both libpetsc64_*.so and libdolfin64.so.
48
49 dijitso cache files are hashed by source file, not link library,
50 meaning subsequent use of the same source file will not distinguish
51 between a cached file linked against standard or 64-bit dolfin. The
52 discrepancy may result in runtime errors. To avoid this, use a
53 separate cache by defining the environment variable DIJITSO_CACHE_DIR
54 e.g.
55 DIJITSO_CACHE_DIR=.dijitso_cache
56 or
57 DIJITSO_CACHE_DIR=.dijitso_cache_64
58 and clean the cache if needed, with 'dijitso clean'.
59
60 python3-dolfin is now a base package providing a dolfin.pth pointing
61 by default at the preferred PETSc installation provided by
62 python3-dolfin-real (for PETSC_DIR=/usr/lib/petsc
63 SLEPC_DIR=/usr/lib/slepc).
64
65
66 Conditional Support for SuperLU-Dist
67 ------------------------------------
68
69 In principle dolfin supports SuperLU-Dist. However the superlu-dist
70 package distributed by Debian is mostly useless since mc64, one of its
71 core functions, cannot legally be redistributed and so has been
72 removed from the Debian package. For this reason, we have given
73 preference to mumps over superlu_dist.
74
75 You may specify superlu_dist if desired (or if you have a local build
76 of superlu_dist that includes mc64), for instance with
77 solve(a == L, u, bc, solver_parameters={'linear_solver': 'superlu_dist'})
78
79 You may also successfully use superlu_dist without mc64 by specifying
80 C++:
81 PETScOptions::set("-mat_superlu_dist_rowperm", "NATURAL");
82 Python:
83 PETScOptions.set('-mat_superlu_dist_rowperm', 'NATURAL')
84 Performance will likely be reduced.
85
86 The same problem applies to superlu, from which mc64 has also been
87 removed. superlu still functions successfully however (mc64 is not
88 core for the serial version of SuperLU).
89
90 Internet availability for pusimp integration tests
91 --------------------------------------------------
92
93 The goal of some pusimp integration tests is to create a dirty virtualenv
94 in which some of dolfin dependecies are replaced with a manually installed
95 package from PyPI, and verify that pusimp actually triggers an error while
96 trying to import dolfin.
97 However, to create such virtualenv environment the build needs to be allowed
98 to download packages from pypi.org.
99
100 pusimp integration tests are run only with autopkgtest and are not run while
101 building the package, because python3-dolfin-{real,complex} is built using
102 setup.py rather than querying pybuild.
103
104 The file test/debian-only/test_pusimp.py gracefully handles a missing network
105 by checking for internet availability trying to fetch www.debian.org via
106 python3-requests. If networks is unreachable, all tests in the file will be
107 skipped, and pusimp integration will only be partially tested.