Fourier Validators

Added in version 2.0.0.

Helper functions to validate inputs when running MembraneCurvature with the Fourier surface method.

These validators check user-provided coordinates, grid sizes, and related parameters before the Fourier fit is run, so invalid inputs fail fast with clear error messages.

Invalid inputs raise ValueError with messages that describe the problem. For example, if the coordinates are invalid, the error message will be:

ValueError: positions must contain at least one row

or if the grid sizes are invalid, the error message will be:

ValueError: n_x_bins and n_y_bins must be positive;

Error messages always display the original error message and the traceback with the source of the error.

Warning

We provide the API documentation for the validators for reference only.

Validators are not intended to be called directly by the user. They are called automatically by the high-level entry points in the surface derivation methods: fourier_surface and binning_surface.

Functions

membrane_curvature.fourier_validators._coerce_positions(positions) → ndarray

Convert atom coordinates into a NumPy array of floats.

Internal helper used by the public Fourier entry points to accept list/tuple/array-like input and produce a contiguous numpy.ndarray of float64 values.

Shape checks (2D, at least three columns, non-empty) are handled separately by validate_positions().

Parameters:

positions (array-like) – Atom coordinates. Any data type that can be turned into a numeric NumPy array works: nested lists/tuples, a NumPy array, etc.

Returns:

positions – The input as a float NumPy array.

Return type:

numpy.ndarray, dtype float64

Raises:

ValueError – If the input cannot be converted to a numeric array. Common causes are non-numeric entries (for example strings) or rows of different lengths (a “ragged” list of lists). The original NumPy error is chained via __cause__ so the traceback shows what NumPy actually complained about.

membrane_curvature.fourier_validators.validate_positions(positions: ndarray) → None

Check that an atom coordinate array has the expected shape.

A Fourier fit needs a 2D array of shape (n_atoms, 3) (or more columns; only the first three are used as \(x\), \(y\), \(z\)). This helper raises a clear error if that is not the case. Typically called after coercing the input to a NumPy float array.

Parameters:

positions (numpy.ndarray) – Atom coordinates. Usually the output of _coerce_positions().

Raises:

ValueError – Raised when the array does not look like a list of 3D points. The message states which expectation failed: - not 2D (for example, a flat list of numbers), - fewer than three columns (missing \(x\), \(y\), or \(z\)), - no rows at all (the selection is empty).

membrane_curvature.fourier_validators.validate_positive_bin_counts(n_x_bins, n_y_bins) → None

Validate that grid bin counts are strictly positive integers.

Catches invalid grid sizes before they propagate to operations that would otherwise produce an empty mesh or divide by zero (for example Lx / n_x_bins and Ly / n_y_bins in _bin_centre_mesh()).

Parameters:

• n_x_bins (int) – Number of bins along \(x\). Python int and numpy.integer are accepted; floats and bool are rejected even though bool is an int subclass.

• n_y_bins (int) – Number of bins along \(y\). Same constraint as n_x_bins.

Raises:

ValueError – Raised if either input is not a positive integer. Three cases: - non-integer type, that is, not int / numpy.integer (for example 1.5, "10", or None), - bool (True / False), rejected explicitly even though bool is an int subclass, - integer that is zero or negative. The message names the offending argument, its value, and its type so the mistake is easy to spot.

membrane_curvature.fourier_validators.validate_positive_domain_widths(x_range: tuple[float, float], y_range: tuple[float, float]) → None

Check that the periodic domain has strictly positive width on each axis.

The Fourier fit treats \(L_x = x_{\max} - x_{\min}\) and \(L_y = y_{\max} - y_{\min}\) as the period lengths. A zero or negative width would make wavevectors and the bin spacing wrong. This helper catches that mistake early.

Parameters:

x_range, y_range (tuple of (float, float)) – (min, max) extents of the periodic domain along \(x\) and \(y\).

Raises:

ValueError – If x_range[1] - x_range[0] or y_range[1] - y_range[0] is not strictly positive (max must be greater than min).