| 1 |
============== |
| 2 |
Installation |
| 3 |
============== |
| 4 |
|
| 5 |
Pre-built packages |
| 6 |
------------------ |
| 7 |
|
| 8 |
Pre-built binaries of `hdf5plugin` are available from: |
| 9 |
|
| 10 |
- `pypi <https://pypi.org/project/hdf5plugin>`_, to install run: |
| 11 |
``pip install hdf5plugin [--user]`` |
| 12 |
- `conda-forge <https://anaconda.org/conda-forge/hdf5plugin>`_, to install run: |
| 13 |
``conda install -c conda-forge hdf5plugin`` |
| 14 |
|
| 15 |
To maximize compatibility, those binaries are built without optimization options (such as `AVX2`_ and `OpenMP`_). |
| 16 |
`Installation from source`_ can achieve better performances than pre-built binaries. |
| 17 |
|
| 18 |
Installation from source |
| 19 |
------------------------ |
| 20 |
|
| 21 |
The build process enables compilation optimizations that are supported by the host machine. |
| 22 |
|
| 23 |
To install from source and recompile the HDF5 plugins, run:: |
| 24 |
|
| 25 |
pip install hdf5plugin --no-binary hdf5plugin [--user] |
| 26 |
|
| 27 |
To override the defaults that are probed from the machine, |
| 28 |
it is possible to specify build options by setting environment variables, for example: |
| 29 |
|
| 30 |
- ``HDF5PLUGIN_OPENMP=False pip install hdf5plugin --no-binary hdf5plugin`` |
| 31 |
- From the source directory: ``HDF5PLUGIN_OPENMP=False pip install .`` |
| 32 |
|
| 33 |
Available options |
| 34 |
................. |
| 35 |
|
| 36 |
.. list-table:: |
| 37 |
:widths: 1 4 |
| 38 |
:header-rows: 1 |
| 39 |
|
| 40 |
* - Environment variable |
| 41 |
- Description |
| 42 |
* - ``HDF5PLUGIN_HDF5_DIR`` |
| 43 |
- Custom path to HDF5 (as in h5py). |
| 44 |
It must contain a "include" subfolder and on Windows a "lib" subfolder with hdf5.lib. |
| 45 |
* - ``HDF5PLUGIN_OPENMP`` |
| 46 |
- Whether or not to compile with `OpenMP`_. |
| 47 |
Default: True if probed (always False on macOS). |
| 48 |
* - ``HDF5PLUGIN_NATIVE`` |
| 49 |
- True to compile specifically for the host, False for generic support (For unix compilers only). |
| 50 |
Default: True on supported architectures, False otherwise |
| 51 |
* - ``HDF5PLUGIN_SSE2`` |
| 52 |
- Whether or not to compile with `SSE2`_ support. |
| 53 |
Default: True on ppc64le and when probed on x86, False otherwise |
| 54 |
* - ``HDF5PLUGIN_SSSE3`` |
| 55 |
- Whether or not to compile with `SSSE3`_ support. |
| 56 |
Default: True when probed on x86, False otherwise |
| 57 |
* - ``HDF5PLUGIN_AVX2`` |
| 58 |
- Whether or not to compile with `AVX2`_ support. |
| 59 |
It requires enabling `SSE2`_ support. |
| 60 |
Default: True on x86 when probed, False otherwise |
| 61 |
* - ``HDF5PLUGIN_AVX512`` |
| 62 |
- Whether or not to compile with `AVX512`_ Foundation (F) and Byte and Word (BW) instruction sets support. |
| 63 |
It requires enabling `SSE2`_ and `AVX2`_ support. |
| 64 |
Default: True on x86 when probed, False otherwise |
| 65 |
* - ``HDF5PLUGIN_BMI2`` |
| 66 |
- Whether or not to compile Zstandard with `BMI2`_ support if available. |
| 67 |
Default: True on Linux and MacOS, False otherwise |
| 68 |
* - ``HDF5PLUGIN_CPP11`` |
| 69 |
- Whether or not to compile C++11 code if available. |
| 70 |
Default: True if probed. |
| 71 |
* - ``HDF5PLUGIN_CPP14`` |
| 72 |
- Whether or not to compile C++14 code if available. |
| 73 |
Default: True if probed. |
| 74 |
* - ``HDF5PLUGIN_CPP20`` |
| 75 |
- Whether or not to compile C++20 code if available. |
| 76 |
Default: True if probed. |
| 77 |
* - ``HDF5PLUGIN_INTEL_IPP_DIR`` |
| 78 |
- Experimental feature: Path to Intel `IPP`_ root directory. |
| 79 |
If provided, the LZ4 compression library and Blosc2 are set to use Intel `IPP`_. |
| 80 |
Default: Do not use INTEL `IPP`_ libraries. |
| 81 |
|
| 82 |
Note: Boolean options are passed as ``True`` or ``False``. |
| 83 |
|
| 84 |
|
| 85 |
.. _AVX2: https://en.wikipedia.org/wiki/Advanced_Vector_Extensions#Advanced_Vector_Extensions_2 |
| 86 |
.. _AVX512: https://en.wikipedia.org/wiki/AVX-512 |
| 87 |
.. _BMI2: https://en.wikipedia.org/wiki/X86_Bit_manipulation_instruction_set |
| 88 |
.. _IPP: https://en.wikipedia.org/wiki/Integrated_Performance_Primitives |
| 89 |
.. _SSE2: https://en.wikipedia.org/wiki/SSE2 |
| 90 |
.. _SSSE3: https://en.wikipedia.org/wiki/SSSE3 |
| 91 |
.. _OpenMP: https://www.openmp.org/ |