:py:mod:`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.



Module Contents
---------------


Functions
~~~~~~~~~

.. autoapisummary::

   evomap.mapping._optim.gradient_descent_line_search
   evomap.mapping._optim.gradient_descent_with_momentum
   evomap.mapping._optim.report_optim_progress



Attributes
~~~~~~~~~~

.. autoapisummary::

   evomap.mapping._optim.EPSILON


.. 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 with backtracking via halving.

   Optimizes the objective function iteratively. At each step, a halving
   procedure is used to ensure that step sizes are set such that cost values
   decrease.

   :param objective: Function to be optimized. Expected to return the function value and the
                     gradient when called. See examples for exact syntax.
   :type objective: callable
   :param init: Starting initialization.
   :type init: ndarray of shape (n_samples, n_dims)
   :param n_iter: Total number of gradient descent iterations.
   :type n_iter: int
   :param n_iter_check: Interval in which cost values are reported, by default 1
   :type n_iter_check: int, optional
   :param max_halves: Maximum number of halving steps in line search, by default 10
   :type max_halves: int, optional
   :param step_size: Initial step size, by default 1
   :type step_size: int, optional
   :param min_grad_norm: Error tolerance, by default 1e-7
   :type min_grad_norm: float, optional
   :param verbose: Level of verbosity, by default 0
   :type verbose: int, optional
   :param method_str: Method label, by default ""
   :type method_str: str, optional
   :param args: Arguments passed to the objective function, by default None
   :type args: list, optional
   :param kwargs: Keyword arguments passed to the objective function, by default None
   :type kwargs: dict, optional

   :returns: * *ndarray of shape (n_samples, n_dims)* -- Final map coordinates
             * *float* -- Final cost function value


.. 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 with momentum.

   Optimize the objective function using momentum-based gradient descent,
   as used, for instance, in t-SNE.

   :param objective: Function to be optimized. Expected to return the function value and the
                     gradient when called. See examples for exact syntax.
   :type objective: callable
   :param init: _description_
   :type init: ndarray of shape (n_samples, n_dims)
   :param n_iter: Total number of gradient descent iterations.
   :type n_iter: int
   :param start_iter: Startint iteration, if optimization (re-)starts at a later stage
                      , by default 0
   :type start_iter: int, optional
   :param n_iter_check: Interval in which cost values are reported, by default 50
   :type n_iter_check: int, optional
   :param momentum: Momentum factor, by default .8
   :type momentum: float, optional
   :param eta: Learning rate, by default 50
   :type eta: int, optional
   :param min_grad_norm: Error tolerance, by default 1e-7
   :type min_grad_norm: float, optional
   :param verbose: Level of verbosity, by default 0
   :type verbose: int, optional
   :param method_str: Method label, by default ""
   :type method_str: str, optional
   :param args: Arguments passed to the objective function, by default None
   :type args: list, optional
   :param kwargs: Keyword arguments passed to the objective function, by default None
   :type kwargs: dict, optional

   :returns: * *ndarray of shape (n_samples, n_dims)* -- Final map coordinates
             * *float* -- Final cost function value


.. py:function:: report_optim_progress(iter, method_str, cost, grad_norm=None)

   Print optimization progress.

   :param iter: Current iteration.
   :type iter: int
   :param method_str: Method label.
   :type method_str: str
   :param cost: Current cost function value
   :type cost: float
   :param grad_norm: Gradient norm, by default None
   :type grad_norm: float, optional