evomap.mapping._optim ===================== .. py:module:: evomap.mapping._optim .. autoapi-nested-parse:: Core functions shared within mapping module. Mostly related to different optimization routines implemented and adjusted for mapping. Attributes ---------- .. autoapisummary:: evomap.mapping._optim.EPSILON Exceptions ---------- .. autoapisummary:: evomap.mapping._optim.Error evomap.mapping._optim.DivergingGradientError Functions --------- .. autoapisummary:: evomap.mapping._optim.gradient_descent_line_search evomap.mapping._optim.gradient_descent_with_momentum evomap.mapping._optim.report_optim_progress Module Contents --------------- .. py:data:: EPSILON :value: 1e-12 .. py:exception:: Error Bases: :py:obj:`Exception` Base class for other exceptions .. py:exception:: DivergingGradientError Bases: :py:obj:`Error` Raised when the input value is too small .. py:function:: 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) 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. :param objective: 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. :type objective: callable :param init: The initial starting point for the optimization (e.g., initial coordinates). :type init: ndarray of shape (n_samples, n_dims) :param n_iter: The total number of gradient descent iterations to perform. :type n_iter: int :param n_iter_check: The frequency at which the progress of the optimization is reported, by default 50. :type n_iter_check: int, optional :param max_halves: The maximum number of times to halve the step size during backtracking, by default 10. :type max_halves: int, optional :param step_size: The initial step size for the gradient descent updates, by default 1. :type step_size: float, optional :param min_grad_norm: The tolerance level for stopping the optimization based on the gradient norm, by default 1e-7. :type min_grad_norm: float, optional :param verbose: 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. :type verbose: int, optional :param method_str: A string to identify the method, useful for logging and output messages, by default "" (empty string). :type method_str: str, optional :param args: Additional positional arguments passed to the objective function, by default None. :type args: list, optional :param kwargs: Additional keyword arguments passed to the objective function, by default None. :type kwargs: dict, optional :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. .. py:function:: 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) Gradient descent optimization with momentum. This function performs gradient descent with momentum to optimize an objective function. :param objective: 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. :type objective: callable :param init: The initial starting point for the optimization (e.g., initial coordinates). :type init: ndarray of shape (n_samples, n_dims) :param n_iter: The total number of gradient descent iterations to perform. :type n_iter: int :param start_iter: The starting iteration, useful for resuming optimization from a certain point, by default 0. :type start_iter: int, optional :param n_iter_check: The frequency at which the progress of the optimization is reported, by default 50. :type n_iter_check: int, optional :param momentum: The momentum factor that determines how much of the previous step's velocity is retained. Higher values increase momentum, by default 0.8. :type momentum: float, optional :param eta: The learning rate, or step size, that controls how much the parameters are adjusted in each iteration, by default 50. :type eta: float, optional :param min_grad_norm: The tolerance level for stopping the optimization based on the gradient norm, by default 1e-7. :type min_grad_norm: float, optional :param verbose: 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. :type verbose: int, optional :param method_str: A string to identify the method, useful for logging and output messages, by default "" (empty string). :type method_str: str, optional :param args: Additional positional arguments passed to the objective function, by default None. :type args: list, optional :param kwargs: Additional keyword arguments passed to the objective function, by default None. :type kwargs: dict, optional :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. .. py:function:: report_optim_progress(iter, method_str, cost, grad_norm=None) Print the progress of the optimization during iterative updates. :param iter: The current iteration of the optimization process. :type iter: int :param method_str: A string identifier for the method being used, useful for logging or distinguishing between different optimization methods. :type method_str: str :param cost: The current value of the cost function being minimized. :type cost: float :param grad_norm: The norm of the gradient at the current iteration, by default None. If provided, it is displayed in the progress report. :type grad_norm: float, optional