API Reference

This page provides an auto-generated summary of slmsuite’s API. You can find the source on GitHub.

slmsuite is divided into two modules: algorithms and analysis in holography and connectivity to physical devices via hardware.

Holography

As a core functionality, slmsuite optimizes nearfield phase profiles (applied to slms) to produce desired farfield results (measured by cameras). These methods are provided in:

algorithms

GPU-accelerated holography algorithms.

Additionally, quality-of-life support methods are provided, divided into SLM- and camera- centric categories:

toolbox	Helper functions for manipulating phase patterns.
analysis	Helper functions for processing images.

Hardware

A central concept of slmsuite is experimental holography. Thus, we require interfaces to control the hardware used in experiment. While some common hardware implementions are included, we welcome contributions to expand the scope and utility of the package! Hardware is divided into two main categories:

slms	The phase displays used to produce holograms.
cameras	The sensor arrays used to measure results.

The unification of these two categories is stored in:

cameraslms

Datastructures, methods, and calibrations for an SLM monitored by a camera.

API Formalism

Data-Order Conventions

slmsuite follows the shape = (h, w) and vector = (x, y) formalism adopted by the numpy ecosystem. numpy, scipy, matplotlib, etc generally follow this formalism. The shape and indexing of an array or image always uses the inverted (h, w) form, but other functions such as numpy.meshgrid(x, y) (default), scipy.odr.Data(x, y), or matplotlib.pyplot.scatter(x, y) use the standard cartesian (x, y) form that is more familiar to users. This is not ideal and causes confusion, but this is the formalism generally adopted by the community.

We additionally adopt the convention that a list of \(N\) vectors with dimension \(D\) is represented with shape (D, N). This is so that linear transformations can be done with a direct and easy multiplication with a (D, D) matrix. Stacks of \(W \times H\) images, however, are stored with the inverted shape (N, H, W). These conventions are arguably consistent with the chosen ordering.

\(k\)-Space Bases

This package uses a number of spatial bases or coordinate spaces to describe the \(k\)-space of the SLM. Some coordinate spaces are directly used by the user (most often the camera basis "ij" used for feedback). Other bases are less often used directly, but are important to how holograms are optimized under the hood (esp. "knm", the coordinate space of optimization when using discrete Fourier transforms). The following describes the bases that general functions (e.g. Hologram) accept. Other units for coordinate bases can be converted to these standard bases using convert_vector().

Bases used in slmsuite.

Basis	Meaning
"kxy"	Normalized basis of the SLM’s \(k\)-space in normalized units. For small angles, this is equivalent to radians. Centered at (kx, ky) = (0, 0). This basis is what the SLM projects in angular space (which maps to the camera’s image space via the Fourier transform implemented by the optical train separating the two). The edge of Fourier space that is accessible to the SLM corresponds to \(\pm\frac{\lambda}{2\Delta x}\) radians, dependant on the pixel size \(\Delta x\) of the SLM. For most SLMs and wavelengths, this angle corresponds to a few degrees at most. Thus, this edge is generally within the small angle approximation. The true edge of the hemisphere of Fourier space corresponds to when \(\sqrt{k_x^2 + k_y^2} = 1\). At this boundary, numerical aperture is 1. Note that the small angle approximation breaks down in this limit.
"knm"	Nyquist basis of the SLM’s computational \(k\)-space for a given discrete computational grid of shape shape. Centered at (kn, km) = (shape[1]/2, shape[0]/2). "knm" is a discrete version of the continuous "kxy". This is important because holograms need to be stored in computer memory, a discrete medium with pixels, rather than being purely continuous. For instance, in SpotHologram, spots targeting specific continuous angles are rounded to the nearest discrete pixels of "knm" space in practice (though CompressedSpotHologram transcends this limitation). Then, this "knm" space image is handled as a standard image/array, and operations such as the discrete Fourier transform (instrumental for numerical hologram optimization) can be applied. The edge of "knm" space is bounded by zero and the extent of shape. In "kxy" space, this edge corresponds to the Nyquist limit of the SLM and is strictly smaller than the full extent of Fourier space. Increasing the shape of "knm" space increases the resolution of the grid in Fourier space, as the edge of "knm" space is fixed by the SLM.
"ij"	Pixel basis of the camera. Centered at (i, j) = (cam.shape[1]/2, cam.shape[0]/2). Is in the image space of the camera. The bounds of pixel space may be larger or smaller than Fourier or Nyquist space, depending upon the imaging optics that separate the camera and SLM.

See the first tip in Hologram to learn more about "kxy" and "knm" space.