simopt.solvers.spsa
===================

.. py:module:: simopt.solvers.spsa

.. autoapi-nested-parse::

   Simultaneous Perturbation Stochastic Approximation (SPSA) Solver.

   Simultaneous perturbation stochastic approximation (SPSA) is an algorithm for
   optimizing systems with multiple unknown parameters.





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

.. py:class:: SPSAConfig

   Bases: :py:obj:`simopt.base.SolverConfig`


   Configuration for SPSA solver.


   .. py:attribute:: alpha
      :type:  Annotated[float, Field(default=0.602, gt=0, description='non-negative coefficient in the SPSA gain sequence ak')]


   .. py:attribute:: gamma
      :type:  Annotated[float, Field(default=0.101, gt=0, description='non-negative coefficient in the SPSA gain sequence ck')]


   .. py:attribute:: step
      :type:  Annotated[float, Field(default=0.1, gt=0, description='initial desired magnitude of change in the theta elements')]


   .. py:attribute:: gavg
      :type:  Annotated[int, Field(default=1, gt=0, description='averaged SP gradients used per iteration')]


   .. py:attribute:: n_reps
      :type:  Annotated[int, Field(default=30, gt=0, description='number of replications takes at each solution')]


   .. py:attribute:: n_loss
      :type:  Annotated[int, Field(default=2, gt=0, description='number of loss function evaluations used in gain calculation')]


   .. py:attribute:: eval_pct
      :type:  Annotated[float, Field(default=2 / 3, gt=0, le=1, description='percentage of the expected number of loss evaluations per run')]


   .. py:attribute:: iter_pct
      :type:  Annotated[float, Field(default=0.1, gt=0, le=1, description='percentage of the maximum expected number of iterations')]


.. py:class:: SPSA(name: str = '', fixed_factors: dict | None = None)

   Bases: :py:obj:`simopt.base.Solver`


   Simultaneous Perturbation Stochastic Approximation (SPSA) Solver.

   Simultaneous perturbation stochastic approximation (SPSA) is an algorithm for
   optimizing systems with multiple unknown parameters.

   Initialize a solver object.

   :param name: Name of the solver. Defaults to an empty string.
   :type name: str, optional
   :param fixed_factors: Dictionary of user-specified solver
                         factors. Defaults to None.
   :type fixed_factors: dict | None, optional


   .. py:attribute:: name
      :type:  str
      :value: 'SPSA'



   .. py:attribute:: config_class
      :type:  ClassVar[type[simopt.base.SolverConfig]]

      Configuration class for the solver.


   .. py:attribute:: class_name_abbr
      :type:  ClassVar[str]
      :value: 'SPSA'


      Short name of the solver class.


   .. py:attribute:: class_name
      :type:  ClassVar[str]
      :value: 'SPSA'


      Long name of the solver class.


   .. py:attribute:: objective_type
      :type:  ClassVar[simopt.base.ObjectiveType]

      Description of objective types.


   .. py:attribute:: constraint_type
      :type:  ClassVar[simopt.base.ConstraintType]

      Description of constraint types.


   .. py:attribute:: variable_type
      :type:  ClassVar[simopt.base.VariableType]

      Description of variable types.


   .. py:attribute:: gradient_needed
      :type:  ClassVar[bool]
      :value: False


      True if gradient of objective function is needed, otherwise False.


   .. py:method:: check_problem_factors() -> bool

      Determine if the joint settings of problem factors are permissible.

      :returns: True if problem factors are permissible; False otherwise.
      :rtype: bool



   .. py:method:: solve(problem: simopt.base.Problem) -> None

      Run a single macroreplication of a solver on a problem.

      :param problem: Simulation-optimization problem to solve.
      :type problem: Problem

      :returns:     - list [Solution]: List of solutions recommended throughout the budget.
                    - list [int]: List of intermediate budgets when recommended solutions
                        change.
      :rtype: tuple