git.iko.soy/typeable/nixpkgs
on master help sign in
doc/overlays.xml: update documentation for BLAS/LAPACK

This expands the documentation and explains how to assert LP64.

commit3c41d61514029d5aa4ea748c1e46098767ae448b authorMatthew Bauer <mjbauer95@gmail.com> dateTue 21 Apr 2020, 11:03 (7 years ago) parent8f58fa0
2 files changed+42−27
doc/languages-frameworks/python.section.md+3−26 doc/using/overlays.xml+39−1
doc/languages-frameworks/python.section.md+3−26
@@ -1290,32 +1290,9 @@ self: super: {
12901290
12911291### How to use Intel's MKL with numpy and scipy?
12921292
1293−A `site.cfg` is created that configures BLAS based on the `blas` parameter of
1294−the `numpy` derivation. By passing in `mkl`, `numpy` and packages depending on
1295−`numpy` will be built with `mkl`.
1296−
1297−The following is an overlay that configures `numpy` to use `mkl`:
1298−
1299−```nix
1300−self: super: {
1301− python37 = super.python37.override {
1302− packageOverrides = python-self: python-super: {
1303− numpy = python-super.numpy.override {
1304− blas = super.pkgs.mkl;
1305− };
1306− };
1307− };
1308−}
1309−```
1310−
1311−`mkl` requires an `openmp` implementation when running with multiple processors.
1312−By default, `mkl` will use Intel's `iomp` implementation if no other is
1313−specified, but this is a runtime-only dependency and binary compatible with the
1314−LLVM implementation. To use that one instead, Intel recommends users set it with
1315−`LD_PRELOAD`.
1316−
1317−Note that `mkl` is only available on `x86_64-{linux,darwin}` platforms;
1318−moreover, Hydra is not building and distributing pre-compiled binaries using it.
1293+MKL can be configured using an overlay. See the section “[Using
1294+overlays to configure
1295+alternatives](#sec-overlays-alternatives-blas-lapack)”.
13191296
13201297### What inputs do `setup_requires`, `install_requires` and `tests_require` map to?
13211298
doc/using/overlays.xml+39−1
@@ -177,7 +177,7 @@ self: super:
177177 <para>
178178 <link
179179 xlink:href="https://software.intel.com/en-us/mkl">Intel
180− MKL</link> (only works on x86 architecture)
180+ MKL</link> (only works on x86 architecture, unfree)
181181 </para>
182182 <para>
183183 The Nixpkgs attribute is <literal>mkl</literal>.
@@ -211,6 +211,44 @@ self: super:
211211 using <literal>LD_PRELOAD</literal> of libblas.so.3 and
212212 liblapack.so.3.
213213 </para>
214+ <para>
215+ Intel MKL requires an <literal>openmp</literal> implementation
216+ when running with multiple processors. By default,
217+ <literal>mkl</literal> will use Intel’s <literal>iomp</literal>
218+ implementation if no other is specified, but this is a
219+ runtime-only dependency and binary compatible with the LLVM
220+ implementation. To use that one instead, Intel recommends users
221+ set it with <literal>LD_PRELOAD</literal>. Note that
222+ <literal>mkl</literal> is only available on
223+ <literal>x86_64-linux</literal> and
224+ <literal>x86_64-darwin</literal>. Moreover, Hydra is not build
225+ and distributing pre-compiled binaries using it.
226+ </para>
227+ <para>
228+ For BLAS/LAPACK switching to work correctly, all packages must
229+ depend on <literal>blas</literal> or <literal>lapack</literal>.
230+ This ensures that only one BLAS/LAPACK library is used at one
231+ time. There are two versions versions of BLAS/LAPACK currently
232+ in the wild, <literal>LP64</literal> (integer size = 32 bits)
233+ and <literal>ILP64</literal> (integer size = 64 bits). Some
234+ software needs special flags or patches to work with
235+ <literal>ILP64</literal>. You can check if
236+ <literal>ILP64</literal> is used in Nixpkgs with
237+ <varname>blas.isILP64</varname> and
238+ <varname>lapack.isILP64</varname>. Some software does NOT work
239+ with <literal>ILP64</literal>, and derivations need to specify
240+ an assertion to prevent this. You can prevent
241+ <literal>ILP64</literal> from being used with the following:
242+ </para>
243+ <programlisting>
244+{ stdenv, blas, lapack, ... }:
245+
246+assert (!blas.isILP64) &amp;&amp; (!lapack.isILP64);
247+
248+stdenv.mkDerivation {
249+ ...
250+}
251+ </programlisting>
214252 </section>
215253 </section>
216254</chapter>