Installation#

During alpha development, install lauelab from source in the Conda environment supplied by this repository. python -m pip install . compiles the native indexing library and command-line programs with CMake, then installs the Python package. The project does not publish prebuilt wheels or Conda packages.

Pip can create a temporary wheel while it installs the source tree. This is part of the build process and does not avoid native compilation. Wheels created with python -m build are development artifacts. They require compatible native libraries and are not supported outside the environment used to build them.

Supported platforms#

Linux x86-64 with GCC.
Python 3.11, 3.12, or 3.13. The maintained environment uses Python 3.12.

macOS, Windows, Linux ARM, and Clang are not supported.

Native dependencies#

The build needs these tools and libraries:

Dependency	Purpose
GCC with C99 support	Compiles all native code
CMake 3.24 or later and Ninja	Build system (pip installs them from PyPI when they are absent)
GSL 2.8 with headers	Indexing and reconstruction
HDF5 1.14 with headers and `h5cc`	Peak search and reconstruction
zlib with headers	HDF5 compression
OpenMP (part of GCC)	CPU reconstruction
`patchelf`	Normalizes library search paths in the installed files (pip installs it from PyPI)

Other minor versions of GSL and HDF5 can work, but the tests run against the versions above.

Running the complete native memory regression test also requires Valgrind and a C compiler available as cc. Both are included in environment.yml; on Debian or Ubuntu install valgrind alongside build-essential.

CUDA is not required. See GPU reconstruction.

Install with conda (recommended)#

Use this path at APS and for alpha testing. environment.yml provides the compiler and native libraries from conda-forge. Build, install, and run lauelab in this environment so the native programs can load the same GSL and HDF5 libraries.

Clone the repository:

$ git clone https://github.com/AdvancedPhotonSource/lauelab.git
$ cd lauelab

Create and activate the environment:

$ conda env create -f environment.yml
$ conda activate laue-analysis

Install the package:
```
$ python -m pip install .
```

Using lauelab in Jupyter#

The maintained Conda environment includes JupyterLab, IPython kernel support, and the nbformat package that Plotly uses for notebook display. Register the environment as a named kernel:

$ conda activate laue-analysis
$ python -m ipykernel install --user --name laue-analysis --display-name "Python (laue-analysis)"
$ jupyter lab

Select Python (laue-analysis) in JupyterLab. Plotly figures display inline when you call figure.show(). The custom Matplotlib example in the visualization guide requires matplotlib, which the maintained environment also includes.

Install with a virtual environment#

Use this path on a Linux system that already provides the native dependencies, for example through the distribution package manager or HPC environment modules.

Install the native dependencies. On Debian or Ubuntu:

$ sudo apt-get install build-essential libgsl-dev libhdf5-dev zlib1g-dev valgrind

Create and activate a virtual environment:

$ python -m venv .venv
$ source .venv/bin/activate

Install the package:
```
$ python -m pip install .
```

Do not run pip with sudo.

The installed programs find GSL and HDF5 through the dynamic loader’s search path. If environment modules or another non-system prefix provides the libraries, add its library directory to LD_LIBRARY_PATH at run time. A virtual environment does not inherit access to libraries from a separate Conda environment. Do not move a wheel built in one environment into another environment unless the target provides compatible native libraries.

Verify the installation#

Run these commands after installation.

Check the Python package:

$ python -c "from lauelab.indexing import Indexer, index_frame; print('import ok')"
import ok

Check that the native indexing library loads:

$ python -c "from lauelab.indexing._liblaue import get_library; get_library(); print('native indexing ok')"
native indexing ok

Check that the CPU reconstruction program runs:

$ python -c "from lauelab.reconstruct import find_executable; print(find_executable())"

The second command loads a private module only as an installation check. Do not use _liblaue as an application API.

What the build produces#

A default installation builds all of these:

Component	Location in the installed package	Required
`liblaue.so`	`lauelab/indexing/bin/`	Yes. The in-process indexing API needs it.
`peaksearch`, `pix2qs`, `euler`	`lauelab/indexing/bin/`	Yes. Used by the LaueGo compatibility functions.
`reconstructN_cpu`	`lauelab/reconstruct/bin/`	Yes. Used by `reconstruct()`.

The in-process indexing API is the main path for new code. The LaueGo compatibility functions and their command-line programs remain supported for existing workflows. The build stops with an error when a required dependency is missing or a component fails to compile. It does not install a partial package.

Native code is compiled for the generic x86-64 baseline with SSE2. The same installed files run on any x86-64 Linux machine that has compatible GSL and HDF5 libraries.

GPU reconstruction#

CPU reconstruction is the supported path. The package does not build or distribute the CUDA reconstruction program, and it does not detect CUDA during installation. reconstruct_gpu() can run an externally installed reconstructN_gpu executable from PATH. It raises FileNotFoundError when the executable is unavailable.

The source distribution and repository include the CUDA source and a stand-alone Makefile in src/lauelab/reconstruct/source/recon_gpu/. This build is not part of the maintained package installation.

Troubleshooting#

The build reports that GSL or HDF5 was not found. Install the development package that provides headers and gsl-config or h5cc, then run pip install . again. In a conda environment, confirm that the environment is active.

The build reports that patchelf is required. This appears only with pip install --no-build-isolation. Install patchelf into the environment (pip install patchelf or conda install -c conda-forge patchelf).

liblaue.so fails to load with “cannot open shared object file”. The dynamic loader cannot find libgsl or libhdf5. Activate the environment that provides them, or add their directory to LD_LIBRARY_PATH.

reconstructN_gpu is not found. GPU reconstruction is not built by the package. See GPU reconstruction.

Report a problem#

Open an issue in the lauelab repository. Include:

The lauelab version or Git commit
Operating system, Python version, and whether you used conda or a virtual environment
The installation command
The complete compiler, CMake, or linker error

Remove sample names, user names, local paths, and other sensitive experiment metadata before posting logs.