Utilities

Quatm general-purpose utility functions: variable density sampling and other helpers

Overview

The quatm.utils package provides general-purpose utility functions used across the modules of the Quatm framework.

Variable density sampling — `quatm.utils.vds`

Variable density sampling (VDS) allows efficient exploration of a parameter space by concentrating the sampling points in the regions of interest (such as near resonances or phase transitions in quantum systems).

Core idea

In a physics experiment, some parameter regions are more meaningful than others. For example:

magnetic-field scans near a Feshbach resonance
frequency scans near the centre of a spectral line
parameter exploration near a phase-transition critical point

By automatically densifying the sampling points in the regions of interest and sampling sparsely in flat regions, VDS extracts the maximum information with the minimum number of data points.

`gauss_prime_norm` — normalised Gaussian derivative

The derivative of a Gaussian function, normalised to a maximum of 1:

$$f(x) = \sqrt{e} \cdot \frac{x - \mu}{\sigma} \exp\left(-\frac{(x-\mu)^2}{2\sigma^2}\right)$$

from quatm.utils.vds import gauss_prime_norm

# evaluate the Gaussian derivative at x=5.0
val = gauss_prime_norm(5.0, mu=5.0, sigma=1.0)

Parameter	Description
`x`	input value, either a scalar or a `numpy.ndarray`
`mu`	centre of the Gaussian
`sigma`	standard deviation of the Gaussian

`gauss_prime_norm_abs` — absolute-value normalised Gaussian derivative

The normalised form of the absolute value of the Gaussian derivative, suitable as an interest function for symmetric peak detection.

`create_support_points_stochastic` — stochastic support-point generation

Starts from a fine equidistant grid and randomly removes the points in regions of low interest, keeping the points in regions of high interest.

from quatm.utils.vds import (
    create_support_points_stochastic,
    gauss_prime_norm_abs
)

# define the interest function: concentrate the sampling around x=5.0
def interest(x, center, width):
    return gauss_prime_norm_abs(x, center, width)

points = create_support_points_stochastic(
    start=0.0,      # scan start
    stop=10.0,      # scan stop
    steps=50,       # number of final support points
    interest_fn=interest,
    max_stepsize=0.5,   # maximum permitted step size
    enhancement=0.8,    # 0-1, 1 means strong enhancement
    center=5.0,         # passed to interest_fn
    width=1.0           # passed to interest_fn
)

Parameter	Description
`start`	scan start, always included in the final support points
`stop`	scan stop, always included in the final support points
`steps`	number of final support points
`interest_fn`	interest function `f(x, **kwargs)` returning 0 (low interest) to 1 (high interest)
`max_stepsize`	maximum spacing between adjacent support points
`enhancement`	0-1, 1 means strong enhancement of the regions of interest, 0 means uniform random sampling
`**kwargs`	additional arguments passed to `interest_fn`

Application scenarios

Variable density sampling is particularly suitable for:

Feshbach resonance spectrum scans: densify the sampling near the resonance peak
Spectral line scans: improve the resolution near the line centre
Phase-transition parameter scans: explore the critical region finely
Trap-frequency measurements: concentrate the sampling near the expected resonance frequency

Variable density sampling

Variable density sampling: a support-point generator that densifies the sampling in parameter space according to an interest function.

Utilities

Overview

Variable density sampling — quatm.utils.vds