hofa.char#

This module contains the Numpy implementation for performing higher-order Fourier analysis using the spectral approach developed by Candela, González-Sánchez, and Szegedy.

Conventions#

The following conventions are used for functions and data structures in this file:

Any finite abelian group \(Z\) is isomorphic to \(Z/n_1Z \times Z/n_2Z \times ... \times Z/n_kZ\). Therefore, a function \(f: Z \to \mathbb{C}\) is represented as a numpy.ndarray tensor with shape \((n_1, n_2, ..., n_k)\).
A \(Z\)-matrix, where \(Z = Z/n_1Z \times ... \times Z/n_kZ\), is represented as a numpy.ndarray tensor with shape \((n_1, ..., n_k, n_1, ..., n_k)\).

Attributes#

logger

Logger for this module.

Classes#

`RandomSeparator`	Abstract base class for an abstract separator of higher order characters.
`StandardRandomSeparator`	A standard implementation of `RandomSeparator`.
`RandomizedSeparationResult`	A container for the results of a randomized separation algorithm.
`RandomizedSearchCallback`	Abstract base class for callback objects used during randomized search algorithms.
`PrintRandomizedSearchCallback`	A concrete callback class that prints progress updates during randomized search.

Functions#

`spechoft`(→ RandomizedSeparationResult)	Find higher-order characters using a randomized algorithm with customizable regularization.
`find_middle_point_of_largest_gap`(→ float)	Find the midpoint of the largest gap in a filtered array within specified bounds.
`eigenvals_separated`(→ bool)	Check if eigenvalues are sufficiently separated based on a minimum gap threshold.
`random_complex_unit_vector`(→ numpy.ndarray)	Generate a random complex vector with unit \(\ell^2\) norm.
`individual_eigenvals_separated`(→ numpy.ndarray)	Return a boolean mask indicating which eigenvalues are separated from their neighbors by at least threshold.

Module Contents#

hofa.char.logger#

Logger for this module.

This module-level logger is used to log messages related to the functionality provided by this module. It follows the standard Python logging convention, where the logger name is set to the module’s name (__name__).

The logger can be used to output messages at various severity levels: - DEBUG: Detailed information, typically of interest only when diagnosing problems. - INFO: Confirmation that things are working as expected.

To configure the logging behavior (e.g., log level, output format, handlers), users should configure the Python logging system at the application level. For example:

Example:

>>> import logging
>>> # Configure basic logging to console
>>> logging.basicConfig(level=logging.INFO)

Note:

The actual output and visibility of log messages depends on the logging configuration set by the application using this module. By default, if no logging configuration is set, messages at WARNING level and above will be sent to stderr.

class hofa.char.RandomSeparator#

Bases: abc.ABC

Abstract base class for an abstract separator of higher order characters.

This abstract class provides with an interface for the basic functionality to look for the higher-order components of a function using a randomized algorithm.

abstractmethod initial_threshold(f: numpy.ndarray, reg_res: hofa.rgz.RegularizationResult) → float#

Compute the initial threshold for the given input and regularization result.

This method should be implemented by subclasses to define how the initial threshold is determined based on the input data and the first regularization outcome.

Parameters:

f (np.ndarray) – Input array for which the threshold is computed.
reg_res (hofa.rgz.RegularizationResult) – Result of a regularization process of f.

Returns:

The computed threshold.

Return type:

float

Note:

Subclasses must override this method. See StandardRandomSeparator.initial_threshold().

abstractmethod iteration_threshold(f: numpy.ndarray, reg_res: hofa.rgz.RegularizationResult, initial_f: numpy.ndarray, initial_reg_res: hofa.rgz.RegularizationResult) → float#

Compute the threshold to be used in the loop for finding the higher order characters.

This method should be implemented by subclasses to define how the iterative threshold is determined based on the iterative regularized function and the iterative regularization of such function.

Parameters:

f (np.ndarray) – Input array for which the threshold is computed.
reg_res (rgz.RegularizationResult) – Result of a regularization process of the iteration.

Returns:

The computed threshold.

Return type:

float

Note:

Subclasses must override this method. See StandardRandomSeparator.iteration_threshold().

abstractmethod separation_gap(f: numpy.ndarray, reg_res: hofa.rgz.RegularizationResult, initial_f: numpy.ndarray, initial_reg_res: hofa.rgz.RegularizationResult) → float#

Compute the gap required between top eigenvalues.

This method should be implemented by subclasses to define how the iterative gap is determined based on the iterative regularized function and the iterative regularization of such function.

Parameters:

f (np.ndarray) – Input array for which the threshold is computed.
reg_res (rgz.RegularizationResult) – Result of a regularization process of the iteration.

Returns:

The computed gap.

Return type:

float

Note:

Subclasses must override this method. See StandardRandomSeparator.separation_gap().

abstractmethod get_rng()#

Get the random number generator (RNG) instance used by this object.

This abstract method should be implemented by subclasses to return the numpy.random.Generator instance that is used internally for all randomized operations. This allows users to inspect the RNG state or use the same RNG for other operations to ensure reproducibility.

The returned RNG should be the same instance used internally by the object for all randomized operations, such as generating random vectors or initializing iterative processes.

Returns:: The random number generator instance used by this object.
Return type:: numpy.random.Generator
Note:: Subclasses must override this method to return the RNG instance used internally. The RNG should be properly initialized during the object’s construction (e.g., in __init__()).
Raises:: NotImplementedError – If the method is not overridden in a subclass.

abstractmethod max_iter(f: numpy.ndarray, reg_res: hofa.rgz.RegularizationResult) → int#

Get the maximum number of iterations for the iterative process.

This abstract method should be implemented by subclasses to define how the maximum number of iterations is determined based on the input data f and the regularization result reg_res. The returned value controls the maximum number of iterations allowed in iterative algorithms (e.g., during eigenvalue separation or character refinement).

Subclasses may use f and reg_res to dynamically determine the maximum iterations, or they may return a fixed value set during initialization.

Parameters:

f (numpy.ndarray) – Input data array, which may be used to determine the maximum iterations.
reg_res (rgz.RegularizationResult) – Regularization result object, which may be used to determine the maximum iterations. This may include residuals, parameters, or other metadata from the regularization process.

Returns:

The maximum number of iterations to perform in iterative processes.

Return type:

int

Note:

Subclasses must override this method. The implementation should define how the maximum iterations are determined, either dynamically (based on f and reg_res) or as a fixed value. For an example implementation, see StandardRandomSeparator.max_iter().

Raises:

NotImplementedError – If the method is not overridden in a subclass.

abstractmethod iterative_search() → bool#

Check whether the algorithm should use iterative search.

This abstract method should be implemented by subclasses to return a boolean indicating whether the algorithm should use an iterative approach for separation or a non-iterative (direct) method. This flag controls the overall strategy of the algorithm, where iterative search is generally faster and similarly accurate.

The returned value should be determined based on the algorithm’s configuration (e.g., parameters set during initialization) and the specific requirements of the subclass implementation.

Returns:: True if iterative search is enabled, False if a non-iterative method should be used.
Return type:: bool
Note:: Subclasses must override this method. The implementation should return the value of the iterative search flag, which is typically set during initialization. For an example implementation, see StandardRandomSeparator.iterative_search().
Raises:: NotImplementedError – If the method is not overridden in a subclass.

class hofa.char.StandardRandomSeparator(param_initial: float | int = 1.2, mode_initial: str = 'dynamic-relative', param_iter: float | int = 1.2, mode_iter: str = 'dynamic-relative', param_separation: float | int = 0.6, mode_separation: str = 'dynamic', max_iterations: int = 20, iterative_search: bool = True, rng: int | numpy.random.Generator | None = None)#

Bases: RandomSeparator

A standard implementation of RandomSeparator.

This constructor sets up the parameters and modes for the initialization, iteration, and separation phases of the algorithm. The values of param_initial, param_iter, and param_separation must be positive numbers.

The values of mode_initial, mode_iter, and mode_separation must be one of the following. In the sequel, let \(\sigma^2\) be the variance of the input function

‘dynamic-relative’:
Let \(\rho\) be the product of param multiplied by \(\sigma\sqrt{|Z|/\log|Z|}\). The parameter (the threshold or gap) will be then the middle point of the largest gap of the eigenvalues of the regularization in the interval \([\rho/2,\rho]\).

‘dynamic-strict’:
The parameter (the threshold or gap) will be param multiplied by \(\sigma\sqrt{|Z|/\log|Z|}\).

‘literal-relative’:
The parameter (the threshold or gap) will be the middle point of the largest gap of the eigenvalues of the regularization in the interval \([\text{param}/2,\text{param}]\).

‘literal-strict’:
The parameter will be param.

Parameters:

param_initial (float or int) – Initial parameter value for the first phase of the algorithm. Default is 1.2.
mode_initial (str) – Mode for the initialization phase.
param_iter (float or int) – Parameter value for the iteration phase of the algorithm. Default is 1.2.
mode_iter (str) – Mode for the iteration phase.
param_separation (float or int) – Parameter value for the separation phase of the algorithm. Default is 1.2.
mode_separation (str) – Mode for the separation phase.
random_state (int or numpy.random.Generator or None) – Seed for the random number generator or a numpy.random.Generator instance for reproducibility. If None, the global random state is used.

Note:

The ‘dynamic-relative’ mode is the default for all phases and is recommended for most use cases. Other modes may require specific parameter values.

Example:

>>> separator = StandardRandomSeparator(
...     param_initial=1.5,
...     mode_initial='dynamic-strict'
... )

param_initial = 1.2#

mode_initial = 'dynamic-relative'#

param_iter = 1.2#

mode_iter = 'dynamic-relative'#

param_separation = 0.6#

mode_separation = 'dynamic'#

max_iterations = 20#

do_iterative_search = True#

group_size = 0#

initial_threshold(f: numpy.ndarray, reg_res: hofa.rgz.RegularizationResult) → float#

Compute the initial threshold value based on input data and regularization result.

This method calculates an initial threshold for the eigenvalues of the algorithm. The threshold is determined based on the input data array f and the result of the regularization process contained in reg_res. Depending on the values of self.param_initial and self.mode_initial, the threshold is computed according to the rules described in StandardRandomSeparator.

Parameters:

f (numpy.ndarray) – Input data array for which the threshold is computed.
reg_res (rgz.RegularizationResult) – Regularization result object containing information needed to compute the threshold.

Returns:

The computed initial threshold value.

Return type:

float

iteration_threshold(f: numpy.ndarray, reg_res: hofa.rgz.RegularizationResult, initial_f: numpy.ndarray, initial_reg_res: hofa.rgz.RegularizationResult) → float#

Compute the iteration threshold value based on input data and regularization result.

This method calculates an iteration threshold for the eigenvalues. The threshold is determined based on the input data array f and the result of the regularization process contained in reg_res. Depending on the values of self.param_iteration and self.mode_iteration, the threshold is computed according to the rules described in StandardRandomSeparator.

Parameters:

f (numpy.ndarray) – Input data array for which the threshold is computed.
reg_res (rgz.RegularizationResult) – Regularization result object containing information needed to compute the threshold.

Returns:

The computed initial threshold value.

Return type:

float

separation_gap(f: numpy.ndarray, reg_res: hofa.rgz.RegularizationResult, initial_f: numpy.ndarray, initial_reg_res: hofa.rgz.RegularizationResult) → float#

Compute the separation gap value based on input data and regularization result.

This method calculates an separation gap for the eigenvalues. The threshold is determined based on the input data array f and the result of the regularization process contained in reg_res. Depending on the values of self.param_separation and self.mode_separation, the threshold is computed according to the rules described in StandardRandomSeparator.

Parameters:

f (numpy.ndarray) – Input data array for which the threshold is computed.
reg_res (rgz.RegularizationResult) – Regularization result object containing information needed to compute the threshold.

Returns:

The computed initial threshold value.

Return type:

float

get_rng()#

Get the random number generator (RNG) instance used by this object.

This method returns the numpy.random.Generator instance that is used internally for all randomized operations.

Returns:: The random number generator instance used by this object.
Return type:: numpy.random.Generator
Note:: The returned RNG is the same instance used internally by this object. Modifying its state (e.g., by calling its methods) may affect the reproducibility of this object’s operations.

max_iter(f: numpy.ndarray, reg_res: hofa.rgz.RegularizationResult) → int#

Get the maximum number of iterations for the iterative process.

This method returns the maximum number of iterations (self.max_iterations) that will be used in iterative algorithms (e.g., during eigenvalue separation). The input parameters f and reg_res are accepted for consistency with the abstract RandomSeparator but are not used in this implementation.

Parameters:

f (numpy.ndarray) – Input data array. This parameter is accepted for consistency but is not used.
reg_res (rgz.RegularizationResult) – Regularization result object. This parameter is accepted for consistency but is not used.

Returns:

The maximum number of iterations, as set during initialization.

Return type:

int

Note:

This method is designed to be overridden in subclasses to allow dynamic determination of the maximum iterations based on f and reg_res. In this base implementation, it simply returns self.max_iterations.

iterative_search() → bool#

Check whether the algorithm should use iterative search.

This method returns the value of self.do_iterative_search, which determines whether the algorithm will use an iterative approach for separation or a non-iterative (direct) method.

Returns:: True if iterative search is enabled, False otherwise.
Return type:: bool
Note:: This flag is typically set during initialization and controls whether the algorithm will iterate to refine the separation (if True) or try to find all eigenvectors at once (if False). Iterative search is generally faster and similarly accurate.

class hofa.char.RandomizedSeparationResult#

Bases: NamedTuple

A container for the results of a randomized separation algorithm.

This NamedTuple stores the outputs of a randomized algorithm that separates higher-order characters and eigenvalues. It provides information about the separation process, including whether the separation was successful, the threshold used, and the number of iterations performed.

Variables:

higher_order_char (numpy.ndarray) – The computed higher-order characters after separation.
separated_eigenvalues (numpy.ndarray) – The eigenvalues obtained after separation. This is a 1D numpy array.
are_separated (bool) – Boolean flag indicating whether the separation was successful. True if the characters and eigenvalues were successfully separated according to the algorithm’s criteria, False otherwise.
separation_threshold (float) – The threshold value used for the separation process. This value determines the criterion for successful separation.
total_iterations (int) – The total number of iterations performed by the separation algorithm before termination.

Note:

This NamedTuple is typically returned by functions that perform randomized separation of higher-order characters and eigenvalues. The are_separated flag should be checked to verify if the separation was successful before using the results.

Example:

>>> # Assuming 'result' is returned by a separation function
>>> if result.are_separated:
...     print("Separation successful!")
...     print("Higher-order characters:", result.higher_order_char)
...     print("Eigenvalues:", result.separated_eigenvalues)
... else:
...     print("Separation failed after", result.total_iterations, "iterations")

higher_order_char: numpy.ndarray#

separated_eigenvalues: numpy.ndarray#

are_separated: bool#

separation_threshold: float#

total_iterations: int#

class hofa.char.RandomizedSearchCallback#

Bases: abc.ABC

Abstract base class for callback objects used during randomized search algorithms.

This class defines the interface for callback objects that can be used to monitor the progress of the randomized search algorithm at every iteration. Subclasses should implement the callback methods to perform custom actions.

on_iteration(iteration_count: int, eigenvalues_found: int, number_eigenvales_separated: int, iteration_rho: float, separation_delta: float, f_reg_iteration: hofa.rgz.RegularizationResult, rnd_separator: RandomSeparator, number_of_eig_already_found: int, target_number_eigenvalues: int)#

Callback method invoked after each iteration of the randomized search algorithm.

This method is called at each iteration just after computing the regularization of the particular function from which we want to obtain the higher order characters, providing information about the current state of the algorithm. Subclasses should override this method to implement custom behavior, such as printing progress updates, logging metrics, or updating visualizations.

Parameters:

iteration_count (int) – The current iteration index (0-based).
eigenvalues_found (int) – The total number of eigenvalues found so far.
number_eigenvales_separated (int) – The number of eigenvalues successfully separated in the current iteration.
iteration_rho (float) – The threshold used during the current iteration.
separation_delta (float) – The separation gap or threshold used during the current iteration.
f_reg_iteration (rgz.RegularizationResult) – The regularization result object for the current iteration.
rnd_separator (RandomSeparator) – The random separator object.
number_of_eig_already_found (int) – The cumulative number of eigenvalues found before this iteration.
target_number_eigenvalues (int) – The target number of eigenvalues to find.

Note:

Subclasses must override this method to implement custom behavior. The base implementation does nothing.

on_end(iteration_count: int, rnd_separator: RandomSeparator, number_of_eig_already_found: int, target_number_eigenvalues: int)#

Callback method invoked at the end of the randomized search algorithm.

This method is called once when the algorithm terminates, providing a summary of the final state. Subclasses should override this method to implement custom behavior, such as printing a summary, logging final results, or cleaning up resources.

Parameters:

iteration_count (int) – The total number of iterations performed.
rnd_separator (RandomSeparator) – The random separator object used during the final iteration.
number_of_eig_already_found (int) – The total number of eigenvalues found by the algorithm.
target_number_eigenvalues (int) – The target number of eigenvalues to find.

Note:

Subclasses must override this method to implement custom behavior. The base implementation does nothing.

class hofa.char.PrintRandomizedSearchCallback#

Bases: RandomizedSearchCallback

A concrete callback class that prints progress updates during randomized search.

This class implements the RandomizedSearchCallback interface to provide real-time progress updates during the execution of a randomized search algorithm. It prints information about each iteration and a summary at the end of the process, allowing users to monitor the algorithm’s progress directly in the console.

The output is formatted to update on a single line (using \r) during iterations, providing a clean and compact progress display. At the end of the process, a summary line is printed with the final results.

Example:

>>> callback = PrintRandomizedSearchCallback()
>>> # Pass the callback to your randomized search function
>>> result = spechoft(f, callback=callback)

on_iteration(iteration_count: int, eigenvalues_found: int, number_eigenvales_separated: int, iteration_rho: float, separation_delta: float, f_reg_iteration: hofa.rgz.RegularizationResult, rnd_separator: RandomSeparator, number_of_eig_already_found: int, target_number_eigenvalues: int)#

Print progress information for the current iteration.

This method prints a compact progress update for each iteration of the randomized search algorithm. The output is formatted to overwrite the previous line (using \r), creating a dynamic progress display in the console.

The printed information includes: - Current iteration count - Number of eigenvalues found in this iteration - Number of eigenvalues separated in this iteration - Whether iterative search is enabled - Cumulative number of eigenvalues found so far - Target number of eigenvalues

Parameters:

iteration_count (int) – Current iteration index (0-based).
eigenvalues_found (int) – Number of eigenvalues found in this iteration.
number_eigenvales_separated (int) – Number of eigenvalues successfully separated in this iteration.
iteration_rho (float) – Current value of the rho parameter (not printed but available).
separation_delta (float) – Current separation delta (not printed but available).
f_reg_iteration (rgz.RegularizationResult) – Regularization result for this iteration (not used but available).
rnd_separator (RandomSeparator) – Random separator object used in this iteration.
number_of_eig_already_found (int) – Cumulative number of eigenvalues found so far.
target_number_eigenvalues (int) – Target number of eigenvalues to find.

Note:

The output is printed with end='\r', which causes the text to overwrite the previous line in most terminals. This creates a dynamic progress display that updates in place rather than scrolling.

on_end(iteration_count: int, rnd_separator: RandomSeparator, number_of_eig_already_found: int, target_number_eigenvalues: int)#

Print a summary of the randomized search results at the end of the process.

This method prints a summary line with the final results of the randomized search algorithm, including: - Total number of iterations performed - Whether iterative search was used - Total number of eigenvalues found - Target number of eigenvalues

Unlike the iteration updates, this summary is printed as a new line to ensure it remains visible after the process completes.

Parameters:

iteration_count (int) – Total number of iterations performed.
rnd_separator (RandomSeparator) – Random separator object used in the final iteration.
number_of_eig_already_found (int) – Total number of eigenvalues found.
target_number_eigenvalues (int) – Target number of eigenvalues to find.

Note:

This method prints a new line (without \r) to ensure the summary remains visible in the console after the process completes.

hofa.char.spechoft(f: numpy.ndarray, order: int | List[hofa.rgz.LayerRegularizer] = 2, rnd_separator: RandomSeparator | None = None, iteration_regularizers: List[hofa.rgz.LayerRegularizer] | None = None, rng: numpy.random.Generator | int | None = None, callback: RandomizedSearchCallback | None = None) → RandomizedSeparationResult#

Find higher-order characters using a randomized algorithm with customizable regularization.

This function implements a randomized algorithm to identify higher-order characters in the input data using a separation approach. We refer the reader to the online documentation for a more detailed account on the theory behind this algorithm.

The process roughly involves: 1. Initial separation using the provided random separator and initial regularizers. 2. Iterative trial an error until we find a separating function using the iteration-phase regularizers. 3. Termination when an appropriate function is found or when max_iterations is reached.

The function returns a comprehensive result object containing the separated higher-order characters, eigenvalues, and metadata about the separation process.

Parameters:

f (numpy.ndarray) – Input data array for which to find higher-order characters. The function from which to obtain the higher order characters.
order (int or List[rgz.LayerRegularizer]) – Order of the higher-order characters to compute, or a list of layer regularizers. Can be either: - An integer specifying the order (default is 2). - A list of rgz.LayerRegularizer objects for more fine-grained control. Default is 2.
rnd_separator (RandomSeparator or None) – Random separator object to use for the separation process. If None, a default random separator will be created. The separator defines the strategy for separating eigenvalues and characters.
iteration_regularizers (List[rgz.LayerRegularizer] or None) – List of layer regularizers to use during the iteration phase. If None, a copy of the regularizers given in the order variable is used.
rng (numpy.random.Generator or int or None) – Random number generator or seed for reproducibility. If None parameters are used for the variables order and iteration_regularizers, then this random number generator will be used to generate them, ensuring predictable outcome if the rng is either a numpy.random.Generator instance or an integer. Can be either: - A numpy.random.Generator instance. - An integer seed (which will be used to create a Generator). - None, in which case the global random state is used. Default is None.
callback (RandomizedSearchCallback or None) – Optional callback object for monitoring progress. Should be an instance of RandomizedSearchCallback. If provided, the callback’s methods will be invoked during the algorithm’s execution. Default is None.

Returns:

A named tuple containing the results of the spectral decomposition. The result includes: - higher_order_char: The computed higher-order characters. - separated_eigenvalues: The separated eigenvalues. - are_separated: Boolean indicating if separation was successful. - separation_threshold: The threshold used for separation. - total_iterations: Number of iterations performed.

Return type:

RandomizedSeparationResult

Note:

The quality of the results depends on the choice of random separator and regularizers. The ‘dynamic-relative’ mode in the random separator often provides a good balance between speed and accuracy.

If per_layer_regularizers_initial or per_layer_regularizers_iteration is an integer, default regularizers will be created for each layer.

For reproducible results, provide a fixed seed or Generator for the rng parameter.

Example:

>>> import numpy as np
>>> import hofa.char
>>>
>>> # Create input data
>>> n = 501
>>> f = np.sin(2*np.pi*x**2/n)
>>>
>>> # Run the algorithm with default parameters
>>> result = hofa.char.spechoft(f)
>>>
>>> # Check if separation was successful
>>> if result.are_separated:
...     print("Separation successful!")
...     print("Higher-order characters: ", result.higher_order_char)
... else:
...     print("Separation failed after ", result.total_iterations, " iterations")

hofa.char.find_middle_point_of_largest_gap(x_array: numpy.ndarray, lower_end: float, upper_end: float) → float#

Find the midpoint of the largest gap in a filtered array within specified bounds.

This auxiliary function identifies the largest gap between consecutive elements in a filtered version of the input array, where only elements within the range [lower_end, upper_end] are considered. The midpoint of this largest gap is then returned.

Parameters:

x_array (numpy.ndarray) – Input array of values. Can contain any real numbers.
lower_end (float) – Lower bound of the range to consider. Values in x_array below this are ignored. Its value must be lower than upper_end, undefined behaviour otherwise.
upper_end (float) – Upper bound of the range to consider. Values in x_array above this are ignored. Its value must be higher than lower_end, undefined behaviour otherwise.

Returns:

The midpoint of the largest gap in the filtered and extended array. This is returned as a Python float scalar.

Return type:

float

Note:

If all elements in x_array are outside the [lower_end, upper_end] range, the function will return the midpoint between lower_end and upper_end. If there are no gaps (all elements are identical), the function will return one of the boundary points.

Example:

>>> import numpy as np
>>> import hofa.char
>>> x = np.array([1.0, 2.0, 3.5, 4.0, 6.0, 7.0, 11.0])
>>> c = hofa.char.find_middle_point_of_largest_gap(x, 3.0, 7.0)
>>> print(c)
5.0

hofa.char.eigenvals_separated(eig_vals, delta) → bool#

Check if eigenvalues are sufficiently separated based on a minimum gap threshold.

This function determines whether the eigenvalues in the input array are separated by at least the specified threshold delta. It computes the gaps between consecutive eigenvalues and checks if all gaps are greater than delta.

If there are fewer than 2 eigenvalues, the function returns True by convention, as separation is trivially satisfied.

Parameters:

eig_vals (numpy.ndarray) – 1D array of eigenvalues, sorted in ascending order. The function assumes the input is sorted; if not, results may be incorrect.
delta (float) – Minimum required gap between consecutive eigenvalues. If all gaps are greater than delta, the eigenvalues are considered separated.

Returns:

True if all gaps between consecutive eigenvalues are greater than delta, or if there are fewer than 2 eigenvalues. False otherwise.

Return type:

bool

Note:

This function assumes that eig_vals is sorted in ascending order. If the input is not sorted, call np.sort(eig_vals) first or sort the array before passing it to this function.

Example:

>>> import numpy as np
>>> import hofa.char
>>> eig_vals = np.array([1.0, 2.5, 4.0, 5.5])
>>> print(hofa.char.eigenvals_separated(eig_vals, 1.0))  # True, all gaps > 1.0
True
>>> print(hofa.char.eigenvals_separated(eig_vals, 1.5))  # False, gap between 2.5 and 4.0 is 1.5 (not > 1.5)
False
>>> print(hofa.char.eigenvals_separated(np.array([1.0]), 1.0))  # True, fewer than 2 eigenvalues
True

hofa.char.random_complex_unit_vector(rng: numpy.random.Generator, dim: int) → numpy.ndarray#

Generate a random complex vector with unit \(\ell^2\) norm.

This function creates a random unit complex vector of the specified dimension.

Parameters:

rng (numpy.random.Generator) – Random number generator instance for reproducibility. Use numpy.random.default_rng() to create a generator with a seed for reproducible results.
dim (int) – Dimension of the complex vector to generate, must be at least 1.

Returns:

A complex vector of shape (dim,) with unit norm. Each element is a complex number with real and imaginary parts drawn from a standard normal distribution.

Return type:

numpy.ndarray

Note:

The returned vector has a unit \(\ell^2\) norm, meaning that the sum of the squared magnitudes of all components equals 1.

Example:

>>> import numpy as np
>>> import hofa.char
>>> rng = np.random.default_rng(seed=42)  # For reproducibility
>>> vec = hofa.char.random_complex_unit_vector(rng, dim=5)
>>> print(vec.shape)
(5,)
>>> print(np.isclose(np.linalg.norm(vec), 1.0))
True

hofa.char.individual_eigenvals_separated(eigenvals: numpy.ndarray, threshold: float) → numpy.ndarray#

Return a boolean mask indicating which eigenvalues are separated from their neighbors by at least threshold.

Args:: eigenvals: 1D array of shape (n,) containing real numbers in increasing order. threshold: Minimum distance required for an eigenvalue to be considered separated.
Returns:: np.ndarray: Boolean mask of shape (n,), where res[i] is True if eigenvals[i] is separated from its neighbors.

hofa.char#

Conventions#

Attributes#

Classes#

Functions#

Module Contents#

Table of Contents

Previous topic

Next topic