evomap.mapping._optim#

Core functions shared within mapping module. Mostly related to different optimization routines implemented and adjusted for mapping.

Attributes#

EPSILON

Exceptions#

`Error`	Base class for other exceptions
`DivergingGradientError`	Raised when the input value is too small

Functions#

`gradient_descent_line_search`(objective, init, n_iter)	Gradient descent optimization with backtracking line search via halving.
`gradient_descent_with_momentum`(objective, init, n_iter)	Gradient descent optimization with momentum.
`report_optim_progress`(iter, method_str, cost[, grad_norm])	Print the progress of the optimization during iterative updates.

Module Contents#

evomap.mapping._optim.EPSILON = 1e-12#

exception evomap.mapping._optim.Error[source]#

Bases: Exception

Base class for other exceptions

exception evomap.mapping._optim.DivergingGradientError[source]#

Bases: Error

Raised when the input value is too small

evomap.mapping._optim.gradient_descent_line_search(objective, init, n_iter, n_iter_check=50, max_halves=10, step_size=1, min_grad_norm=1e-07, verbose=0, method_str='', args=None, kwargs=None)[source]#

Gradient descent optimization with backtracking line search via halving.

This function performs gradient descent optimization to minimize the objective function, using a backtracking line search to adaptively adjust the step size.

Parameters:

objective (callable) – The objective function to be minimized. It should return both the cost (value) and the gradient when called. The function signature is expected to be objective(Y, *args, **kwargs) where Y is the current map coordinates and args and kwargs are additional arguments.
init (ndarray of shape (n_samples, n_dims)) – The initial starting point for the optimization (e.g., initial coordinates).
n_iter (int) – The total number of gradient descent iterations to perform.
n_iter_check (int, optional) – The frequency at which the progress of the optimization is reported, by default 50.
max_halves (int, optional) – The maximum number of times to halve the step size during backtracking, by default 10.
step_size (float, optional) – The initial step size for the gradient descent updates, by default 1.
min_grad_norm (float, optional) – The tolerance level for stopping the optimization based on the gradient norm, by default 1e-7.
verbose (int, optional) – The verbosity level of the function’s output: - 0: No output - 1: Only final status messages - 2: Detailed iteration-by-iteration progress, by default 0.
method_str (str, optional) – A string to identify the method, useful for logging and output messages, by default “” (empty string).
args (list, optional) – Additional positional arguments passed to the objective function, by default None.
kwargs (dict, optional) – Additional keyword arguments passed to the objective function, by default None.

Returns:

ndarray of shape (n_samples, n_dims) – The optimized map coordinates (final positions in the reduced space).
float – The final value of the cost function after optimization.

Raises:

DivergingGradientError – If the gradient norm becomes excessively large, indicating divergence.

evomap.mapping._optim.gradient_descent_with_momentum(objective, init, n_iter, start_iter=0, n_iter_check=50, momentum=0.8, eta=50, min_grad_norm=1e-07, verbose=0, method_str='', args=None, kwargs=None)[source]#

Gradient descent optimization with momentum.

This function performs gradient descent with momentum to optimize an objective function.

Parameters:

objective (callable) – The objective function to be minimized. It should return both the cost (value) and the gradient when called. The function signature is expected to be objective(Y, *args, **kwargs) where Y is the current map coordinates and args and kwargs are additional arguments.
init (ndarray of shape (n_samples, n_dims)) – The initial starting point for the optimization (e.g., initial coordinates).
n_iter (int) – The total number of gradient descent iterations to perform.
start_iter (int, optional) – The starting iteration, useful for resuming optimization from a certain point, by default 0.
n_iter_check (int, optional) – The frequency at which the progress of the optimization is reported, by default 50.
momentum (float, optional) – The momentum factor that determines how much of the previous step’s velocity is retained. Higher values increase momentum, by default 0.8.
eta (float, optional) – The learning rate, or step size, that controls how much the parameters are adjusted in each iteration, by default 50.
min_grad_norm (float, optional) – The tolerance level for stopping the optimization based on the gradient norm, by default 1e-7.
verbose (int, optional) – The verbosity level of the function’s output: - 0: No output - 1: Only final status messages - 2: Detailed iteration-by-iteration progress, by default 0.
method_str (str, optional) – A string to identify the method, useful for logging and output messages, by default “” (empty string).
args (list, optional) – Additional positional arguments passed to the objective function, by default None.
kwargs (dict, optional) – Additional keyword arguments passed to the objective function, by default None.

Returns:

ndarray of shape (n_samples, n_dims) – The optimized map coordinates (final positions in the reduced space).
float – The final value of the cost function after optimization.

Raises:

DivergingGradientError – If the gradient norm becomes excessively large, indicating divergence.

evomap.mapping._optim.report_optim_progress(iter, method_str, cost, grad_norm=None)[source]#

Print the progress of the optimization during iterative updates.

Parameters:

iter (int) – The current iteration of the optimization process.
method_str (str) – A string identifier for the method being used, useful for logging or distinguishing between different optimization methods.
cost (float) – The current value of the cost function being minimized.
grad_norm (float, optional) – The norm of the gradient at the current iteration, by default None. If provided, it is displayed in the progress report.