coverage
========

.. py:module:: coverage

.. autoapi-nested-parse::

   Coverage model for arc gas treatment.

   This module provides models for ensuring the pulsed arc treats all flowing gas,
   as if the arc was painting the cross-flow gas.



Classes
-------

.. autoapisummary::

   coverage.ArcCoverageModel


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

.. py:class:: ArcCoverageModel

   Bases: :py:obj:`paroto.core.models.base.EmpiricalModel`


   Arc coverage model for gas treatment (Medium Fidelity).

   .. warning::
      Equations are AI generated, not ready for production.

   This model ensures that the pulsed arc treats all gas flowing through the torch.
   The arc "paints" a thermal cross-sectional area with each pulse, as if the arc
   was painting the cross-flow gas, and the pulse frequency must be high enough
   to cover all gas passing through.

   Physical basis:

   The arc sweeps out a thermal area per pulse cycle. For complete gas treatment,
   the volume swept by the arc must equal or exceed the gas volume flowing through:

   .. math::

      V_{arc,swept} = \frac{\pi \cdot e \cdot d_a^2}{4} \cdot f

      V_{gas,flow} = v \cdot S = v \cdot d_t \cdot e

      \text{Coverage constraint: } V_{arc,swept} \geq V_{gas,flow}

   Rearranging:

   .. math::

      \frac{\pi \cdot e \cdot d_a^2}{4} \cdot f \geq v \cdot d_t \cdot e

      \frac{\pi \cdot d_a^2}{4} \cdot f \geq v \cdot d_t

   where:
   - \(d_a\) is thermal arc diameter (m)
   - \(e\) is electrode gap distance (m)
   - \(f\) is pulse frequency (Hz)
   - \(v\) is gas velocity (m/s)
   - \(d_t\) is torch diameter (m)
   - \(S = d_t \cdot e\) is gas flow cross-section (m²)

   Coverage fraction:

   .. math::

      \eta_{coverage} = \frac{V_{arc,swept}}{V_{gas,flow}} =
      \frac{\pi \cdot d_a^2 \cdot f}{4 \cdot v \cdot d_t}

   .. rubric:: Examples

   Minimal usage example:

   >>> import openmdao.api as om
   >>> from paroto.core.models.coverage import ArcCoverageModel
   >>>
   >>> prob = om.Problem()
   >>> prob.model.add_subsystem("coverage", ArcCoverageModel())
   >>> prob.setup()
   >>> prob.set_val("coverage.gap_distance", 0.01)  # 10 mm
   >>> prob.set_val("coverage.torch_diameter", 0.02)  # 20 mm
   >>> prob.set_val("coverage.pulse_frequency", 50e3)  # 50 kHz
   >>> prob.set_val("coverage.flow_velocity", 1.0)  # 1 m/s
   >>> prob.set_val("coverage.thermal_diameter", 0.003)  # 3 mm arc
   >>> prob.run_model()
   >>> coverage = prob.get_val("coverage.coverage_fraction")
   >>> print(f"Coverage: {coverage[0]:.2%}")

   .. rubric:: Examples

   .. minigallery:: paroto.core.models.coverage.ArcCoverageModel
       :add-heading: Examples using this model

   For complete examples, see:
   - Gallery: examples/gallery/plot_coverage_model_example.py
   - Validation: paroto/validation/validate_coverage.py


   .. py:method:: initialize()

      Initialize model options.



   .. py:method:: setup()

      Define inputs and outputs.



   .. py:method:: compute(inputs, outputs)

      Compute arc coverage, as if the arc was painting the cross-flow gas.

      .. warning::
         Equations are AI generated, not ready for production.

      The constraint is:
      π * d_a² * f / 4 >= v * d_t

      Coverage fraction:
      η = (π * d_a² * f) / (4 * v * d_t)

      Margin:
      margin = (π * d_a² * f / 4) - (v * d_t)