slmsuite.holography.algorithms.SpotHologram

class SpotHologram(shape, spot_vectors, basis='kxy', spot_amp=None, cameraslm=None, null_vectors=None, null_radius=None, null_region=None, null_region_radius_frac=None, **kwargs)

Bases: FeedbackHologram

Holography optimized for the generation of optical focal arrays (DFT-based).

Is a subclass of FeedbackHologram, but falls back to non-camera-feedback routines if cameraslm is not passed.

Tip

Quality of life features to generate noise regions for mixed region amplitude freedom (MRAF) algorithms are supported. Specifically, set null_region parameters to help specify where the noise region is not.

spot_knm

Spot locations in the "knm" (computational k-space) basis, stored as float vectors with shape (2, N) in the style of format_2vectors().

Type:

array_like of float

spot_kxy

Spot locations in the "kxy" basis, autocomputed from the others.

Type:

array_like of float OR None

spot_ij

Spot locations in the "ij" (camera) basis, autocomputed from the others. None if the necessary transformations do not exist.

Type:

array_like of float OR None

spot_knm_rounded

spot_knm rounded to nearest integers (indices). These vectors are integers. This is necessary because GS algorithms operate on a pixel grid, and the target for each spot in a SpotHologram is a single pixel (index).

Type:

array_like of int

spot_kxy_rounded

Once spot_knm_rounded is rounded, the original spot_kxy is no longer accurate. Transformations are again used to backcompute the position in the "kxy" basis corresponding to the true computational location of a given spot.

Type:

array_like of float

spot_ij_rounded

As spot_kxy_rounded, but in the "ij" basis. These vectors are floats.

Type:

array_like of float

spot_amp

The amplitudes to target for each spot. The target powers are the square of the amplitudes. Must have length corresponding to the number of spots. For instance, the user can request dimmer or brighter spots.

Type:

array_like of float

external_spot_amp

When using "external_spot" feedback or the "external_spot" stat group, the user must supply external data. This data is transferred through this attribute. For iterative feedback, have the callback() function set external_spot_amp dynamically. By default, this variable is set to a copy of spot_amp.

Type:

array_like of float

spot_integration_width_knm

For spot-specific feedback methods, better SNR is achieved when integrating over many farfield pixels. This variable stores the width of the integration region in "knm" (farfield) space.

Type:

int

null_knm

In addition to points where power is desired, SpotHologram is equipped with quality of life features to select points where power is undesired. These points are stored in null_knm with shape (2, M) in the style of format_2vectors(). A region around these points is set to zero (null) and not allowed to participate in the noise region.

Type:

array_like of float OR None

null_radius_knm

The radius in "knm" space around the points null_knm to zero or null (prevent from participating in the nan noise region). This is useful to prevent power being deflected to very high orders, which are unlikely to be properly represented in practice on a physical SLM.

Type:

int

null_region_knm

Array of shape shape. Where True, sets the background to zero instead of nan. If None, has no effect.

Type:

array_like of bool OR None

Methods

get_amp	Collects the current nearfield amplitude regardless of np/cp configuration.
get_farfield	Collects the current complex DFT farfield, potentially with transformations.
get_log	Return this object's log records (only), as a list of plain-text strings.
get_mempool_limit	Helper function to get the cupy memory pool size.
get_padded_shape	Helper function to calculate the shape of the computational space.
get_phase	Collects the current nearfield phase from the GPU with cupy.ndarray.get().
get_weights	Returns the current weights.
ijcam_to_knmslm	Convert an image in the camera domain to computational SLM k-space using, in part, the affine transformation stored in a cameraslm's Fourier calibration.
load_stats	Uses load_h5() to import the statistics hierarchy from a given h5 file.
log_state	Log the current values of all tracked attributes.
make_rectangular_array	Helper function to initialize a rectangular 2D array of spots, with certain size and pitch.
measure	Method to request a measurement to occur.
optimize	Optimizes to solve the "phase problem": approximating the nearfield phase that transforms a known nearfield source amplitude to a desired farfield target amplitude.
optimize_cg	Gradient-based iterative phase retrieval via torch autograd and a torch.optim optimizer (the "CG" method; see optimize()).
optimize_gs	GPU-accelerated Gerchberg-Saxton (GS) iterative phase retrieval.
pickle	Returns a dictionary containing selected attributes of this class.
plot_farfield	Plots an overview (left) and zoom (right) view of source.
plot_nearfield	Plots the amplitude (left) and phase (right) of the nearfield (plane of the SLM).
plot_stats	Plots the statistics contained in the given dictionary.
refine_offset	Hones the positions of the produced spots toward the desired targets to compensate for Fourier calibration imperfections.
remove_vortices	Spot holograms do not need to consider vortices.
reset	Resets the hologram to an initial state.
reset_phase	Randomize or set the phase.
reset_weights	Resets the hologram weights to the target defaults.
save	Saves the dictionary returned from pickle() to a file like "path/name_id.h5".
save_stats	Uses save_h5() to export the statistics hierarchy to a given h5 file.
set_mempool_limit	Helper function to set the cupy memory pool size.
set_target	From the spot locations stored in spot_knm, update the target pattern.
set_weights	Sets the weights to a new value.

Attributes

spot_integration_width_ij

Width in camera pixels of the square region integrated around each spot for "experimental_spot" feedback.

__init__(shape, spot_vectors, basis='kxy', spot_amp=None, cameraslm=None, null_vectors=None, null_radius=None, null_region=None, null_region_radius_frac=None, **kwargs)

Initializes a SpotHologram targeting given spots at spot_vectors.

Parameters:

• shape ((int, int)) – Computational shape of the SLM. See Hologram.__init__().

• spot_vectors (array_like) – Spot position vectors with shape (2, N) in the style of format_2vectors().

• basis (str) –

  The spots can be in any of the following bases:

  • "kxy" for centered normalized SLM \(k\)-space (radians),

  • "knm" for computational SLM \(k\)-space (pixels),

  • "ij" for camera coordinates (pixels).

  Defaults to "kxy".

• spot_amp (array_like OR None) – The amplitudes to target for each spot. The target powers are the square of the amplitudes. See spot_amp. If None, all spots are assumed to have the same amplitude. Normalization is performed automatically; the user is not required to normalize.

• cameraslm (FourierSLM OR None) – If the "ij" or "kxy" bases are chosen, and/or if the user wants to make use of camera feedback, a slmsuite.hardware.cameraslms.FourierSLM must be provided.

• null_vectors (array_like OR None) – Null position vectors with shape (2, N) in the style of format_2vectors(). MRAF methods are forced zero around these points.

• null_radius (float OR None) – Radius to null around in the given basis. Note that basis conversions are imperfect for anisotropic basis transformations. The radius will always be set to be circular in "knm" space, and will attempt to match to the closest circle to the (potentially elliptical) projection into "knm" from the given basis.

• null_region (array_like OR None) – Array of shape shape. Where True, sets the background to zero instead of nan. If None, has no effect.

• null_region_radius_frac (float OR None) – Helper function to set the null_region to zero for Fourier space radius fractions above null_region_radius_frac. This is useful to prevent power being deflected to very high orders, which are unlikely to be properly represented on a physical SLM. If None, defaults to \(\sqrt{2}\) (circumscribing the square farfield in fractional units) and there is no null region.

• **kwargs – Passed to FeedbackHologram.__init__().

get_amp()

Collects the current nearfield amplitude regardless of np/cp configuration.

Returns:

Nearfield amplitude.

Return type:

numpy.ndarray

get_farfield(shape=None, propagation_kernel=None, affine=None, get=True)

Collects the current complex DFT farfield, potentially with transformations. This includes collecting the data from the GPU with cupy.ndarray.get().

Parameters:

• shape ((int, int)) – Shape of the DFT. Useful to change the resolution of the farfield. If None, defaults to shape, and falls back to slm_shape.

• propagation_kernel (array_like) – Used to check the result of the hologram at different depths. See propagation_kernel. If None, defaults to propagation_kernel if one is present. Otherwise, no kernel is applied. Zeroing can force no kernel to be applied and yield the raw DFT.

• affine (dict) – Affine transformation to apply to farfield data (in the form of a dictionary with keys "M" and "b"). If None, no transformation is applied.

• get (bool) – Whether or not to convert the cupy array to a numpy array if cupy is used. This is ignored if numpy is used.

Returns:

Current farfield expected from the current phase.

Return type:

numpy.ndarray

get_log(verbose=False)

Return this object’s log records (only), as a list of plain-text strings.

Parameters:

verbose (bool, optional) – If True, also print the records to the console.

static get_mempool_limit(device=0)

Helper function to get the cupy memory pool size.

Parameters:

device (int) – Which GPU to set the limit on. Passed to cupy.cuda.Device().

Returns:

Current memory pool limit in bytes

Return type:

int

static get_padded_shape(slm_shape, padding_order=1, square_padding=True, precision=inf, precision_basis='kxy')

Helper function to calculate the shape of the computational space. For a given base slm_shape, pads to the user’s requirements. If the user chooses multiple requirements, the largest dimensions for the shape are selected. By default, pads to the smallest square power of two that encapsulates the original slm_shape.

See also

Hologram

Note

Under development: a parameter to pad based on available memory (see _calculate_memory_constrained_shape()).

Parameters:

• slm_shape ((int, int) OR FourierSLM OR SLM) – The original shape of the SLM in numpy (h, w) form. The user can pass a FourierSLM or SLM instead, and should pass this when using the precision parameter.

• padding_order (int) – Scales to the padding_order th larger power of 2. A padding_order of zero does nothing. For instance, with square_padding=False, an SLM with shape (720, 1280) would yield (720, 1280) for padding_order=0, (1024, 2048) for padding_order=1, and (2048, 4096) for padding_order=2.

• square_padding (bool) – If True, sets the smaller shape dimension to that of the larger, yielding a square.

• precision (float) – Returns the shape that produces a computational k-space with resolution smaller than precision. The default, infinity, requests a padded shape larger than zero, so padding_order will dominate.

• precision_basis (str) – Basis for the precision. Can be "ij" (camera) or "kxy" (normalized blaze).

Returns:

Shape of the computational space which satisfies the above requirements.

Return type:

(int, int)

get_phase(include_propagation=False)

Collects the current nearfield phase from the GPU with cupy.ndarray.get(). Also offsets by \(\pi\), which shifts the \([-\pi, \pi]\) range of numpy.arctan2() to \([0, 2\pi]\) for faster writing to the SLM (see set_phase()). The result is not wrapped, so a phase from CG, a quadratic initialization, or an included propagation_kernel can fall outside this range.

Parameters:

include_propagation (bool) – Whether to include the propagation_kernel, if available.

Returns:

Current nearfield phase of the optimization.

Return type:

numpy.ndarray

get_weights()

Returns the current weights. Collects the current weights from the GPU if applicable.

ijcam_to_knmslm(img, out=None, blur_ij=None, order=3, roi=None)

Convert an image in the camera domain to computational SLM k-space using, in part, the affine transformation stored in a cameraslm’s Fourier calibration.

Note

This includes two transformations:

• The affine transformation "ij" -> "kxy" (camera pixels to normalized k-space).

• The scaling "kxy" -> "knm" (normalized k-space to computational k-space pixels).

Parameters:

• img (numpy.ndarray OR cupy.ndarray) – Image to transform. This should be the same shape as images returned by the camera, unless roi is given (see below).

• out (numpy.ndarray OR cupy.ndarray OR None) – If out is not None, this array will be used to write the memory in-place.

• blur_ij (int OR None) – Applies a blur_ij pixel-width Gaussian blur to img. If None, defaults to the "blur_ij" flag if present; otherwise zero. With roi, the blur is applied within the sub-image.

• order (int) – Order of interpolation used for transformation. Defaults to 3 (cubic).

• roi ((int, int) OR None) –

  Region of interest, as the (y, x) camera pixel that img[0, 0] corresponds to. When given, img is a sub-image of the camera frame rather than a full frame, and everything outside it is undefined (as numpy.nan padding would be). Only the sub-image is uploaded to the GPU, which is much cheaper than embedding it in a camera-sized canvas. If None, img covers the full camera frame.

  Source coordinates in the outer half-pixel rim of the sub-image are undefined, so leave a pixel of margin around the signal. Above order=0, the spline prefilter makes the result differ slightly from a full-frame transform.

Returns:

Image transformed into "knm" space.

Return type:

numpy.ndarray OR cupy.ndarray

load_stats(file_path, include_state=True)

Uses load_h5() to import the statistics hierarchy from a given h5 file.

Parameters:

• file_path (str) – Full path to the file to read the data from.

• include_state (bool) – If True, also overwrite all other attributes of Hologram except for dtype and amp_ff.

log_state(level=10)

Log the current values of all tracked attributes.

Parameters:

level (int, optional) – Logging level. Defaults to logging.DEBUG.

static make_rectangular_array(shape, array_shape, array_pitch, array_center=None, basis='knm', orientation_check=False, spot_amp=None, **kwargs)

Helper function to initialize a rectangular 2D array of spots, with certain size and pitch.

Note

The array can be in SLM k-space coordinates or in camera pixel coordinates, depending upon the choice of basis. For the "ij" basis, cameraslm must be included as one of the kwargs. See __init__() for more basis information.

Important

Spot positions will be rounded to the grid of computational k-space "knm", to create the target image (of finite size) that algorithms optimize towards. Choose array_pitch and array_center carefully to avoid undesired pitch non-uniformity caused by this rounding.

Parameters:

• shape ((int, int)) – Computational shape of the SLM in numpy (h, w) form. See SpotHologram.__init__().

• array_shape ((int, int) OR int) – The size of the rectangular array in number of spots (NX, NY). If a scalar N is given, assume (N, N).

• array_pitch ((float, float) OR float) – The spacing between spots in the x and y directions (pitchx, pitchy). If a single pitch is given, assume (pitch, pitch).

• array_center ((float, float) OR None) –

  The shift of the center of the spot array from the zeroth order. Uses (x, y) form in the chosen basis. If None, defaults to the position of the zeroth order, converted into the relevant basis:

  • If "knm", this is (shape[1], shape[0])/2.

  • If "kxy", this is (0,0).

  • If "ij", this is the pixel position of the zeroth order on the camera (calculated via Fourier calibration).

• basis (str) – See __init__().

• orientation_check (bool) – Whether to delete the last two points to check for parity.

• spot_amp (array_like OR None) – See spot_amp, in the order that the grid is raveled. Trimmed alongside the points that orientation_check deletes.

• **kwargs – Any other arguments are passed to __init__().

measure(basis='ij')

Method to request a measurement to occur. If img_ij is None, then a new image will be grabbed from the camera (this is done automatically in algorithms).

Parameters:

basis (str) –

The cached image to be sure to fill with new data. Can be "ij" or "knm".

• If "knm", then img_ij and img_knm are filled.

• If "ij", then img_ij is filled, and img_knm is ignored.

This is useful to avoid (expensive) transformation from the "ij" to the "knm" basis if img_knm is not needed.

optimize(method='GS', maxiter=20, verbose=True, callback=None, feedback=None, stat_groups=None, **kwargs)

Optimizes to solve the “phase problem”: approximating the nearfield phase that transforms a known nearfield source amplitude to a desired farfield target amplitude. Supported optimization methods include:

• Gerchberg-Saxton (GS) phase retrieval.

  • 'GS'

    An iterative algorithm for phase retrieval, accomplished by moving back and forth between the imaging and Fourier domains, with amplitude corrections applied to each. This is usually implemented using fast discrete Fourier transforms, potentially GPU-accelerated.

• Weighted Gerchberg-Saxton (WGS) phase retrieval algorithms of various flavors. Improves the uniformity of GS-computed focus arrays using weighting methods and techniques from literature. The method keywords are:

  • 'WGS-Leonardo'

    The original WGS algorithm. Weights the target amplitudes by the ratio of mean amplitude to computed amplitude, which amplifies weak spots while attenuating strong spots. Uses the following weighting function:

    \[\mathcal{W} = \mathcal{W}\left(\frac{\mathcal{T}}{\mathcal{F}}\right)^p\]

    where \(\mathcal{W}\), \(\mathcal{T}\), and \(\mathcal{F}\) are the weight amplitudes, target (goal) amplitudes, and feedback (measured) amplitudes, and \(p\) is the power passed as "feedback_exponent" in flags (see kwargs). The power \(p\) defaults to .8 if not passed. In general, smaller \(p\) will lead to slower yet more stable optimization.

  • 'WGS-Kim'

    Improves the convergence of WGS-Leonardo by fixing the farfield phase strictly after a desired number of net iterations specified by "fix_phase_iteration" or after exceeding a desired efficiency (fraction of farfield energy at the desired points) specified by "fix_phase_efficiency"

  • 'WGS-Nogrette'

    Weights target intensities by a tunable gain factor.

    \[\mathcal{W} = \mathcal{W}\Big/\left(1 - f\left(1 - \frac{\mathcal{F}/\mathcal{T}}{\langle\mathcal{F}/\mathcal{T}\rangle}\right)\right)\]

    where \(\langle\cdot\rangle\) is the mean and \(f\) is the gain factor passed as "feedback_factor" in flags (see kwargs). The factor \(f\) defaults to .1 if not passed.

    Note that while Nogrette et al. compare powers, this implementation compares amplitudes for speed. These are identical to first order.

  • 'WGS-Wu'

    Weights using an exponential function, which is less sensitive to near-zero values of \(\mathcal{F}\) or \(\mathcal{T}\).

    \[\mathcal{W} = \mathcal{W}\exp\left( p (\mathcal{T} - \mathcal{F}) \right)\]

    The speed of correction is controlled by \(p\), the power passed as "feedback_exponent".

  • 'WGS-tanh'

    Weights by hyperbolic tangent, commonly used as an activation function in machine learning.

    \[\mathcal{W} = \mathcal{W}\left[1 + f\text{tanh}\left( p (\mathcal{T} - \mathcal{F}) \right) \right]\]

    This weighting limits each update to a relative change of \(\pm f\), passed as "feedback_factor", which is useful to prevent large changes. The speed of correction is controlled by \(p\), the power passed as "feedback_exponent".

• Conjugate Gradient (CG) phase retrieval.

  • 'CG'

    (This feature is experimental.)

    Some holography—especially that with more complicated holographic objectives—can be better treated with gradient-based methods. In these cases, the phase is guided to an optimized state by following the back-propagated gradients (with respect to phase) of given objective loss which is passed as one of the flags to optimize(). Weighting different components of the objective leads to tradeoffs between those components: for instance a tradeoff between power guided into a given pattern and the uniformity of the realized pattern. slmsuite uses torch as a backend for gradient computation. Notably, memory is still owned and initialized by cupy, but gradients can be calculated by using torch-cupy interoperability.

    The objective loss is expected to be a torch.nn.Module and defaults to a complex variant of torch.nn.MSELoss() that skips undefined (nan) target pixels, such as an MRAF noise region, but normalizes the farfield over the whole plane. loss is called in the style of torch, using (as arguments) the computed farfield (with gradient tree intact) and the target values for the farfield. Internally, this looks like:

    result = loss(      # The user provides this nn.Module to .optimize()
        farfield,       # The farfield (with gradients), calculated from `phase` by slmsuite
        target          # The target, initialized by the user and processed by slmsuite
    )
    result.backward()   # Gradients are back-propagated to the input `phase`.
    

    For FeedbackHologram and subclasses, the gradients are computed computationally, but the computational values are then replaced with the experimental results. This allows optimization of the experimental results using the computational gradients (correct to first order) as a guide. Pixels the camera does not see are passed as undefined target pixels, so a null_region there is not enforced, and a target pixel the camera reads as zero passes no gradient: start from a computational solution. Currently, feedback is not supported for spot arrays with "experimental_spot" or "computational_spot" feedback (WGS probably works better for such spot array objectives anyway).

    Creating a custom objective is as simple as making a custom torch.nn.Module.forward() method. These methods can be as simple as a single expression or as complicated as a full neural network operating on the input parameters. However, remember to use torch methods because the arguments are of type torch.Tensor. Here’s an example of a custom torch.nn.Module.forward() which implements the Huber loss:

    # Define the loss as a class.
    class HuberLoss(nn.Module):
        def __init__(self, delta=1.0):
            super(HuberLoss, self).__init__()
            self.delta = delta
    
        def forward(self, farfield, target):
            residual = torch.abs(farfield - target)
            quadratic = torch.clamp(residual, max=self.delta)
            linear = residual - quadratic
            loss = 0.5 * quadratic ** 2 + self.delta * linear
    
            return torch.mean(loss)
    
    # Initialize the class. Remember that we can pass arguments (delta) here.
    loss = HuberLoss(delta=2.0)
    
    # Pass the loss to the hologram by one of two methods:
    hologram.optimize(..., loss=loss)       # 1. Pass as **kwarg.
    hologram.flags["loss"] = loss           # 2. Set directly.
    

    MRAF (next section), if desired, needs to be handled by the loss function. MRAF information is encoded in the target, with the noise region being nan.

• The option for Mixed Region Amplitude Freedom (MRAF) feedback. In standard iterative algorithms, the entire Fourier-domain unpatterned field is replaced with zeros. This is disadvantageous because a desired farfield pattern might not be especially compatible with a given nearfield amplitude, or otherwise. MRAF enables “noise regions” where some fraction of the given farfield is not replaced with zeros and instead is allowed to vary. In practice, MRAF is enabled by setting parts of the target to nan; these regions act as the noise regions. The "mraf_factor" flag in flags allows the user to partially attenuate the noise regions. A factor of 0 fully attenuates the noise region (normal WGS behavior). A factor of 1 does not attenuate the noise region at all (the default). Middle ground is recommended, but is application-dependent as a tradeoff between improving pattern fidelity and maintaining pattern efficiency. Setting the "mraf" flag to False disables MRAF even when the target contains nan. With MRAF enabled, a nonzero "zero_factor" flag \(f_0\) replaces the zeroing of zero-target pixels with an accumulated correction \(\mathcal{W}_0 \leftarrow \mathcal{W}_0 - f_0|E|E\), where \(E\) is the complex farfield there (default 0, zeroing).

  As examples, consider two cases where MRAF can be useful:

  • Sloping a top hat. Suppose we want very flat amplitude on a beam. Requesting a sharp edge to this beam can lead to fringing effects at the boundary which mitigate flatness both inside and outside the beam. If instead a noise region is defined in a band surrounding the beam, the noise region will be filled with whatever slope best enables the desired flat beam.

  • Mitigating diffractive orders. Without MRAF, spot patterns with high crystallinity often have “ghost” diffractive orders which continue the pattern past the edges of requested spots. Even though these orders are attenuated during each phase retrieval iteration, they remain part of the best solution for the recovered phase. With MRAF, a noise region can help solve for retrieved phase which does not generate these undesired orders.

Caution

Requesting stat_groups will slow the speed of optimization due to the overhead of processing and saving statistics, especially in the case of GPU-accelerated optimization where significant time cost is incurred by moving these statistics to the CPU. This is especially apparent in the case of fully-computational holography, where this effect can slow what is otherwise a fully-GPU-contained loop by an order of magnitude.

Tip

This function uses a parameter naming convention borrowed from scipy.optimize.minimize() and other functions in scipy.optimize. The parameters method, maxiter, and callback have the same functionality as the equivalently-named parameters in scipy.optimize.minimize().

Parameters:

• method (str) – Optimization method to use. See the list of optimization methods above.

• maxiter (int) – Number of iterations to optimize before terminating.

• verbose (bool OR int) – Whether to display tqdm progress bars. These bars are also not displayed for maxiter <= 1.

• callback (callable OR None) – Same functionality as the equivalently-named parameter in scipy.optimize.minimize(). callback must accept a Hologram or Hologram subclass as the single argument. If callback returns True, then the optimization exits. Ignored if None. When applying "external_spot" feedback, this callback is the place to update the "external_spot_amp" attribute.

• feedback (str OR None) –

  Type of feedback to use during optimization, for instance when weighting in "WGS". For direct instances of Hologram, this can only be "computational" feedback. Subclasses support more types of feedback. Supported feedback options include the following:

  • "computational" Uses the projected farfield pattern (transform of the complex nearfield) as feedback.

  • "experimental" Uses a camera contained in a passed cameraslm as feedback. Specific to subclasses of FeedbackHologram.

  • "computational_spot" Takes the computational result (the projected farfield pattern) and integrates regions around the expected positions of spots in an optical focus array. More stable than "computational" for spots. Specific to subclasses of SpotHologram.

  • "experimental_spot" Takes the experimental result (the image from a camera) and integrates regions around the expected positions of spots in an optical focus array. More stable than "experimental" for spots. Specific to subclasses of SpotHologram.

  • "external_spot" Uses some external user-provided metric for spot feedback. See SpotHologram.external_spot_amp. Usually applied during callback. Specific to subclasses of SpotHologram.

• stat_groups (list of str OR None) – Strings representing types of feedback (data gathering) upon which statistics should be derived. These strings correspond to valid types of feedback (see above). For instance, if "experimental" is passed as a stat group, statistics on the pixels in the experimental feedback image will automatically be computed and stored for each iteration of optimization. However, this comes with overhead (see above warning).

• **kwargs (dict, optional) – Various weight keywords and values to pass depending on the weight method. These are passed into flags. See options documented in the constructor. Flags read by reset_phase(), such as quadratic_phase, are stored too, but have no effect until reset_phase() is next called. The exception is name, which labels the tqdm progress bar and is not stored.

optimize_cg(iterations, callback)

Gradient-based iterative phase retrieval via torch autograd and a torch.optim optimizer (the "CG" method; see optimize()).

(This feature is experimental.)

Solves the “phase problem”: approximates the nearfield phase that transforms a known nearfield source amplitude to a desired farfield target amplitude.

Caution

This function should be called through optimize() and not called directly. It is left as a public function exposed in documentation to clarify how the internals of optimize() work.

Caution

This method does not currently support "experimental_spot" or "external_spot" feedback.

Parameters:

• iterations (iterable) – Number of loop iterations to run. Is an iterable to pass a tqdm iterable.

• callback (callable OR None) – See optimize().

optimize_gs(iterations, callback)

GPU-accelerated Gerchberg-Saxton (GS) iterative phase retrieval.

Solves the “phase problem”: approximates the nearfield phase that transforms a known nearfield source amplitude to a desired farfield target amplitude.

Caution

This function should be called through optimize() and not called directly. It is left as a public function exposed in documentation to clarify how the internals of optimize() work.

Parameters:

• iterations (iterable) – Number of loop iterations to run. Is an iterable to pass a tqdm iterable.

• callback (callable OR None) – See optimize().

pickle(attributes=True, metadata=True)

Returns a dictionary containing selected attributes of this class.

Parameters:

• attributes (bool OR list of str) – If False, pickles only baseline attributes, usually single floats. If True, also pickles ‘heavy’ attributes such as large images and calibrations. If list of str, pickles the keys in the given list. By default, the chosen attributes should be things that can be written to .h5 files: scalars and lists of scalars.

• metadata (bool) – If True, package the dictionary as the "__meta__" value of a superdictionary which also contains: "__version__", the current slmsuite version, "__time__", the time formatted as a date string, and "__timestamp__", the time formatted as a floating point timestamp. This information is used as standard metadata for calibrations and saving.

plot_farfield(source=None, title='', limits=None, units='knm', limit_padding=0.1, figsize=(8, 4), cbar=False, axs=None)

Plots an overview (left) and zoom (right) view of source.

Parameters:

• source (array_like OR None) – Should have shape equal to shape. If None, defaults to amp_ff.

• title (str) – Title of the plots. If "phase" is a substring of title, then the source is treated as a phase.

• limits (((float, float), (float, float)) OR None) – \(x\) and \(y\) limits for the zoom plot in "knm" space. If None, limits are autocomputed as the smallest bounds that show all non-zero values (plus limit_padding). Note that autocomputing on target will perform well, as zero values are set to actually be zero. However, doing so on computational or experimental outputs (e.g. amp_ff) will likely perform poorly, as values in the field deviate slightly from zero and artificially expand the limits.

• units (str) – Far-field units for plots (see convert_vector() for options). If units requiring a SLM are desired, the attribute cameraslm must be filled.

• limit_padding (float) – Fraction of the width and height to expand the limits of the zoom plot by, only if the passed limits is None (autocompute).

• figsize (tuple) – Size of the plot.

• cbar (bool) – Whether to add colorbars to the plots. Defaults to False.

• axs (matplotlib.axes.Axes OR None) – If provided, uses these axes instead of creating new ones.

Returns:

Used limits, which may be autocomputed. Autocomputed limits are returned as integers.

Return type:

((float, float), (float, float))

plot_nearfield(source=None, title='', padded=False, figsize=(8, 4), cbar=False)

Plots the amplitude (left) and phase (right) of the nearfield (plane of the SLM). The amplitude is assumed (whether uniform, assumed, or measured) while the phase is the result of optimization.

Parameters:

• source (array_like OR None) – Source to plot. If None, defaults to the current amplitude and phase.

• title (str) – Title of the plots.

• padded (bool) – If True, shows the full computational nearfield of shape shape. Otherwise, shows the region at the center of the computational space of size slm_shape corresponding to the unpadded SLM.

• figsize (tuple) – Size of the plot.

• cbar (bool) – Whether to add colorbars to the plots. Defaults to False.

plot_stats(stats_dict=None, stat_groups=None, ylim=None, show=False)

Plots the statistics contained in the given dictionary.

Parameters:

• stats_dict (dict OR None) – Stats to plot in dictionary form. If None, defaults to stats.

• stat_groups (list of str OR None) – Which statistics groups to plot. If empty or None is provided, defaults to all groups present in stats.

• ylim ((int, int) OR None) – Allows the user to pass in desired y limits. If None, the default y limits are used.

• show (bool) – Whether or not to immediately show the plot. Defaults to False.

refine_offset(img=None, basis='kxy', force_affine=True, plot=False)

Hones the positions of the produced spots toward the desired targets to compensate for Fourier calibration imperfections. Works either by moving camera integration regions to the positions where the spots ended up (basis="ij") or by moving the \(k\)-space targets to target the desired camera pixels (basis="knm"/basis="kxy"). This should be run at the user’s request between optimize() iterations.

Parameters:

• img (numpy.ndarray OR None) – Image measured by the camera. If None, defaults to img_ij via measure().

• basis (str) –

  The correction can be in any of the following bases:

  • "ij" changes the pixel that the spot is expected at,

  • "kxy", "knm" change the k-vector which the SLM targets.

  Defaults to "kxy". If basis is set to None, no correction is applied to the data in the SpotHologram.

• force_affine (bool) – Whether to force the offset refinement to behave as an affine transformation between the original and refined coordinate system. This helps to tame outliers. Defaults to True.

• plot (int OR bool) – Enables debug plots at 1 and above.

Returns:

Spot shift in the "ij" basis for each spot.

Return type:

numpy.ndarray

remove_vortices(plot=False)

Spot holograms do not need to consider vortices.

reset(reset_phase=True, reset_flags=False, reset_weights=True)

Resets the hologram to an initial state. Does not restore the preconditioned phase that may have been passed to the constructor (as this information is lost upon optimization). Instead, phase is randomized if reset_phase=True. Also uses the current target rather than the target that may have been passed to the constructor (e.g. includes current refine_offset() changes, etc).

Parameters:

• reset_phase (bool) – Whether to additionally call reset_phase().

• reset_flags (bool) – Whether to erase the information (including passed kwargs) stored in flags.

• reset_weights (bool) – Whether to additionally call reset_weights(). Pass False when the caller has already re-derived the weights from the current target.

reset_phase(*args, **kwargs)

Randomize or set the phase.

reset_weights()

Resets the hologram weights to the target defaults.

save(path='.', name=None, **kwargs)

Saves the dictionary returned from pickle() to a file like "path/name_id.h5".

Parameters:

• path (str) – Path to directory to save in. Default is current directory.

• name (str OR None) – Name of the save file. If None, will use the object’s name + '-pickle'.

• **kwargs – Passed to pickle() to customize how and what data is saved.

Returns:

The file path that the pickled data was saved to.

Return type:

str

save_stats(file_path, include_state=True)

Uses save_h5() to export the statistics hierarchy to a given h5 file.

Tip

Enabling the "raw_stats" flag will save feedback data from each iteration instead of only derived statistics. Consider enabling this to save more detailed information.

Parameters:

• file_path (str) – Full path to the file to write the data to.

• include_state (bool) – If True, also includes all other attributes of Hologram except for dtype (cannot pickle) and amp_ff (can regenerate). These attributes are converted to numpy if necessary. Note that the intent is not to produce a runnable Hologram by default (as this would require pickling hardware interfaces), but rather to provide extra information for debugging.

static set_mempool_limit(device=0, size=None, fraction=None)

Helper function to set the cupy memory pool size.

Parameters:

• device (int) – Which GPU to set the limit on. Passed to cupy.cuda.Device().

• size (int) – Desired number of bytes in the pool. Passed to cupy.cuda.MemoryPool.set_limit().

• fraction (float) – Fraction of available memory to use. Passed to cupy.cuda.MemoryPool.set_limit().

set_target(reset_weights=False)

From the spot locations stored in spot_knm, update the target pattern.

Note

If there’s a cameraslm, updates the spot_ij_rounded attribute corresponding to where pixels in the \(k\)-space were actually placed (due to rounding to integers, stored in spot_knm_rounded), rather than the idealized floats spot_knm.

Note

The target and weights matrices are modified in-place for speed, unlike Hologram or FeedbackHologram which make new matrices. This is because spot positions are expected to be corrected using refine_offset().

Parameters:

reset_weights (bool) – Whether to reset the weights to this new target.

set_weights(new_weights)

Sets the weights to a new value. Handles moving data onto the GPU if applicable.

property spot_integration_width_ij

Width in camera pixels of the square region integrated around each spot for "experimental_spot" feedback. Integrating over many camera pixels gives better SNR. None when the spots are not located on a camera.

Setting this re-runs _check_spots_in_frame(), as a width assigned after construction (as wavefront_calibrate_zernike() does) can push the integration regions off the frame.