spectral_galerkin_heat.solvers.spectral
=======================================

.. py:module:: spectral_galerkin_heat.solvers.spectral

.. autoapi-nested-parse::

   Unified Spectral Solver (CPU and GPU).



Classes
-------

.. autoapisummary::

   spectral_galerkin_heat.solvers.spectral.SpectralSolver


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

.. py:class:: SpectralSolver(backend, context = None, *, mixing_omega = None, convergence_tol = None, max_picard_iter = None)

   Bases: :py:obj:`spectral_galerkin_heat.solvers.base.HeatSolver`


   Spectral method solver for the heat equation with phase change and evaporation.

   Uses fast cosine transforms (DCT) and exponential time differencing (ETD1).
   Runs on CPU (NumPy/Numba) or GPU (CuPy/CUDA) depending on the injected
   :class:`~spectral_galerkin_heat.backends.base.MathBackend`: use
   ``NumpyBackend()`` for CPU and ``get_backend("cupy")`` for GPU.

   Every numerical operation goes through ``self.backend.xp`` (the array
   module) and ``self.backend.kernels`` (the physics kernels), so the solver
   code is identical for both targets.


   .. py:method:: initialize(context = None)

      Set up the spectral solver state, allocate buffers, and set the initial condition.

      :param context: If provided, replaces the stored SimulationContext. By default None.
      :type context: SimulationContext, optional

      :returns: The initialized solver state object (backend-specific
                ``SpectralSolverState``) containing grid buffers and spectra.
      :rtype: Any

      :raises RuntimeError: If SimulationContext is neither provided here nor at construction.



   .. py:method:: step(t, dt)

      Advance the spectral solution by one time step using ETD1 and nonlinear evaporation correction.

      Handles laser source, latent heat, and evaporation effects.

      :param t: Current simulation time.
      :type t: float
      :param dt: Time step size.
      :type dt: float

      :returns:

                SsState : Any
                    The updated solver state.
                metrics : dict
                    Metrics from the iteration, such as max temperature and number
                    of evaporation steps.
      :rtype: tuple



   .. py:method:: set_state(temperature_field)

      Overwrite the internal spectral coefficients from a spatial temperature field.

      Converts the cell-centred temperature array into spectral (DCT) modes
      so that the solver can continue stepping from the injected state.

      :param temperature_field: A 3-D array (shape ``(N_z, N_y, N_x)``) containing temperatures.
                                May be a NumPy or CuPy array.
      :type temperature_field: ndarray

      :raises RuntimeError: If called before the solver is initialized.



   .. py:method:: finalize()

      Release nothing and return.

      The spectral solver holds no resources requiring explicit release
      (CuPy frees device memory on garbage collection). This override is
      present only to satisfy the abstract :meth:`HeatSolver.finalize`
      interface so the class is instantiable.