spectral_galerkin_heat.core.laser
=================================

.. py:module:: spectral_galerkin_heat.core.laser

.. autoapi-nested-parse::

   Laser path and state definitions.



Classes
-------

.. autoapisummary::

   spectral_galerkin_heat.core.laser.LaserProfile
   spectral_galerkin_heat.core.laser.LaserState
   spectral_galerkin_heat.core.laser.LaserPath


Functions
---------

.. autoapisummary::

   spectral_galerkin_heat.core.laser.super_gaussian_area_factor
   spectral_galerkin_heat.core.laser.super_gaussian_flux
   spectral_galerkin_heat.core.laser.gaussian_cell_integrated_flux
   spectral_galerkin_heat.core.laser.build_laser_profile


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

.. py:function:: super_gaussian_area_factor(order)

   Dimensionless ``f`` such that ``∬ s dA = f · r_x · r_y`` for the
   super-Gaussian ``s = exp(-2 ρⁿ)``: ``f(n) = π · 2^(1-2/n) · Γ(2/n) / n``
   (``f(2) = π/2`` Gaussian, ``f(n→∞) → π`` flat-top).


.. py:function:: super_gaussian_flux(xp, x, y, x0, y0, r_x, r_y, order, peak_intensity)

   Super-Gaussian flux ``I₀ · exp(-2 ρⁿ)``, ``ρ² = ((x-x0)/r_x)² + ((y-y0)/r_y)²``.

   Backend-agnostic via ``xp`` (numpy/cupy); ``order = 2`` is the Gaussian.


.. py:function:: gaussian_cell_integrated_flux(xp, x, y, x0, y0, r_x, r_y, hx, hy, peak_intensity)

   Return the cell-mean Gaussian flux, integrated analytically over each cell.

   Each node ``(x_i, y_j)`` stores the *mean* of ``q = I₀·exp(-2 ρ²)`` over its
   cell ``[x_i ± hx/2] × [y_j ± hy/2]`` instead of the point sample. The integral
   separates into 1-D factors

       ∫_a^b exp(-2 u²/r²) du = r·√(π/8)·[erf(√2·b/r) − erf(√2·a/r)].

   Done so a beam narrower than the grid (``r ≪ h``) still deposits its full power.

   ``hx``/``hy`` are the cell sizes (``geom.d.x``/``geom.d.y``). Gaussian only;
   other-order super-Gaussians have no elementary integral.


.. py:class:: LaserProfile

   A beam profile: spatial shape and its energy-conserving normalization.

   Both the area factor ``f`` and the spatial shape derive from ``order``.


   .. py:property:: area_factor
      :type: float


      Dimensionless ``f`` such that ``∬ s dA = f · r_x · r_y``.


   .. py:method:: peak_intensity(power, absorptivity, ref_area)

      Energy-conserving peak ``I₀ = A·P / (f · ref_area)`` (``ref_area = r_x·r_y``).



   .. py:method:: flux(xp, x, y, x0, y0, r_x, r_y, peak_intensity, hx=None, hy=None)

      Spatial flux field ``I₀ · s(x, y)`` for this profile.

      With ``cell_integrated`` set (Gaussian only) and the cell sizes
      ``hx``/``hy`` supplied, returns the exact cell-averaged flux so the total
      deposited power equals ``A·P`` independent of beam position; otherwise
      point-samples the shape at the cell centres.



.. py:function:: build_laser_profile(name, order = 2.0, cell_integrated = False)

   Resolve a profile name to a :class:`LaserProfile`. ``order`` is used only
   for ``"super_gaussian"``; raises ``ValueError`` on an unknown name.

   ``cell_integrated`` enables exact analytic cell-averaging of the Gaussian
   flux (see :func:`gaussian_cell_integrated_flux`).


.. py:class:: LaserState

   Immutable snapshot of the laser at one time point.

   :ivar x, y: Laser position in metres (within the domain ``[0, L]``).
   :vartype x, y: float
   :ivar power: Laser power in watts.
   :vartype power: float
   :ivar is_on: True while the laser is emitting.
   :vartype is_on: bool
   :ivar v: Velocity ``(vx, vy)`` in m/s, by default ``(0.0, 0.0)``.

   :vartype v: tuple[float, float], optional


.. py:class:: LaserPath

   Bases: :py:obj:`abc.ABC`


   Abstract laser trajectory: position and power as a function of time.

   Implementations return a :class:`LaserState` per time step (consistent units:
   metres, watts, m/s). Set ``is_on=False`` (or power 0) once the laser leaves
   the domain.

   .. rubric:: Example

   >>> class ConstantVelocityLaser(LaserPath):
   ...     def __init__(self, x0, y0, vx, power):
   ...         self.x0, self.y0, self.vx, self.power = x0, y0, vx, power
   ...     def get_state(self, time, dt):
   ...         return LaserState(self.x0 + self.vx * time, self.y0,
   ...                           self.power, is_on=True, v=(self.vx, 0.0))


   .. py:method:: get_state(time, dt)
      :abstractmethod:


      Return the :class:`LaserState` at *time* (called once per time step).

      :param time: Current simulation time in seconds (monotonically increasing).
      :type time: float
      :param dt: Current time-step length in seconds.
      :type dt: float