.. _sphx_glr_auto_examples_gallery:

Paroto Model Gallery
====================

This gallery contains minimal, standalone examples demonstrating individual models from the
paroto library. Each example is self-contained (20-30 lines) and can be run independently.

Quick Start
-----------

Each example can be run directly:

.. code-block:: bash

   python plot_initial_temperature_model_example.py
   python plot_coverage_model_example.py
   python plot_arc_density_model_example.py
   python plot_pulsed_breakdown_example.py
   python plot_mobility_model_example.py
   python plot_generator_system_example.py
   python plot_torch_flow_system_example.py

Gallery Index
-------------

1. Initial Temperature Model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**File:** plot_initial_temperature_model_example.py

Demonstrates the ``PulseInitialTemperatureModel`` which computes initial gas temperature
accounting for:

- Energy-to-temperature conversion (via sub-model)
- Cylindrical thermal diffusion
- Relaxation between pulses

**Output:** Temperature evolution plot showing instantaneous jump and exponential decay.

1b. Energy to Temperature Conversion
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**File:** plot_energy_to_temperature_example.py

Demonstrates both energy conversion models:

- ``ConstantCpEnergyModel`` - Simple, constant specific heat (low fidelity)
- ``CanteraEnergyModel`` - Temperature-dependent properties (high fidelity)

**Output:** Comparison of both models showing temperature rise differences.

2. Coverage Model
~~~~~~~~~~~~~~~~~

**File:** plot_coverage_model_example.py

Demonstrates the ``ArcCoverageModel`` which ensures complete gas treatment by the arc:

- Coverage fraction calculation
- Constraint satisfaction check
- Recommendations for incomplete coverage

**Output:** Text summary of coverage analysis.

3. Arc Density Constraint Model
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**File:** plot_arc_density_model_example.py

Demonstrates the ``ArcDensityConstraintModel`` which limits energy density in the arc:

- Energy density calculation
- Constraint margin
- Safety assessment

**Output:** Text summary of energy density check.

4. Pulsed Breakdown Model
~~~~~~~~~~~~~~~~~~~~~~~~~~

**File:** plot_pulsed_breakdown_example.py

Demonstrates the ``RepetitivePulseBreakdownModel`` showing memory effects:

- Breakdown voltage for 1, 10, 100 pulses
- Transition from single-pulse to DC breakdown
- Memory effect from repetitive pulsing

**Output:** Text summary showing voltage reduction with pulse number.

5. Arc Mobility Model
~~~~~~~~~~~~~~~~~~~~~~

**File:** plot_mobility_model_example.py

Demonstrates the ``BrownianArcMobilityModel`` for arc displacement:

- RMS displacement calculation
- Mobility factor
- Thermal load spreading

**Output:** Text summary of arc movement characteristics.

6. High Voltage Generator System
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

**File:** plot_generator_system_example.py

Demonstrates the ``HighVoltageGeneratorSystem`` for operating window constraints:

- Operating window power calculation
- Constraint satisfaction check
- Generator capability assessment

**Output:** Text summary of generator operating point.

7. Torch Flow System
~~~~~~~~~~~~~~~~~~~~~

**File:** plot_torch_flow_system_example.py

Demonstrates the ``TorchFlowSystem`` for flow calculations:

- Flow velocity computation
- Residence time calculation
- Pressure drop estimation

**Output:** Text summary of flow characteristics.

Related Resources
-----------------

Full Validation Scripts
~~~~~~~~~~~~~~~~~~~~~~~

For detailed temporal behavior and comprehensive validation:

- paroto/validation/validate_initial_temperature.py - 4 plots showing T(t) evolution
- paroto/validation/validate_pulsed_breakdown.py - Memory effects and transitions
- paroto/validation/validate_coverage.py - Coverage vs frequency analysis
- paroto/validation/validate_mobility.py - Displacement and lensing risk

Complete Examples
~~~~~~~~~~~~~~~~~

For integrated system examples:

- examples/VedEf_optim/example_operating_window_5d.py - 5D parameter sweep
- examples/VedEf_optim/dashboard_operating_window.py - Interactive dashboard
- examples/VDEF_optim/example_vdef_mdao.py - MDAO optimization

Model Documentation
-------------------

Each model class includes comprehensive docstrings with:

- Physics equations in LaTeX format
- Input/output descriptions
- Usage examples
- References to gallery and validation scripts

Requirements
------------

- Python 3.11+
- OpenMDAO >= 3.27
- NumPy
- Matplotlib (for examples with plots)
- paroto library installed (``pip install -e .`` from repo root)

Notes
-----

⚠️ **AI-Generated Equations Warning**: The physics equations in these models are AI-generated
and not yet validated for production use. They serve as demonstrations of the model framework
and should be validated against experimental data before use in real applications.

Contributing
------------

To add a new gallery example:

1. Create a minimal 20-30 line script
2. Include clear comments and output
3. Add entry to this README
4. Reference the gallery example in the model's docstring



.. raw:: html

    <div class="sphx-glr-thumbnails">

.. thumbnail-parent-div-open

.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the ArcDensityConstraintModel which enforces energy density limits in the plasma arc to prevent excessive thermal loading.">

.. only:: html

  .. image:: /auto_examples/gallery/images/thumb/sphx_glr_plot_arc_density_model_example_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_gallery_plot_arc_density_model_example.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Arc Density Constraint Model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the basic usage of ArcCoverageModel for gas coverage calculation without plotting, suitable for quick validation.">

.. only:: html

  .. image:: /auto_examples/gallery/images/thumb/sphx_glr_plot_coverage_model_basic_example_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_gallery_plot_coverage_model_basic_example.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Arc Coverage Model (Basic)</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the ArcCoverageModel which ensures complete gas treatment by the arc through coverage fraction calculation.">

.. only:: html

  .. image:: /auto_examples/gallery/images/thumb/sphx_glr_plot_coverage_model_example_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_gallery_plot_coverage_model_example.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Arc Coverage Model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates both ConstantCpEnergyModel and CanteraEnergyModel for converting energy deposition to temperature increase in the plasma arc.">

.. only:: html

  .. image:: /auto_examples/gallery/images/thumb/sphx_glr_plot_energy_to_temperature_example_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_gallery_plot_energy_to_temperature_example.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Energy to Temperature Conversion</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the HighVoltageGeneratorSystem which calculates operating window constraints for the pulse power generator.">

.. only:: html

  .. image:: /auto_examples/gallery/images/thumb/sphx_glr_plot_generator_system_example_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_gallery_plot_generator_system_example.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">High Voltage Generator System</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the PulseInitialTemperatureModel which computes initial gas temperature accounting for energy-to-temperature conversion, cylindrical thermal diffusion, and relaxation between pulses.">

.. only:: html

  .. image:: /auto_examples/gallery/images/thumb/sphx_glr_plot_initial_temperature_model_example_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_gallery_plot_initial_temperature_model_example.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Initial Temperature Model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the BrownianArcMobilityModel which calculates arc displacement due to Brownian motion and thermal effects.">

.. only:: html

  .. image:: /auto_examples/gallery/images/thumb/sphx_glr_plot_mobility_model_example_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_gallery_plot_mobility_model_example.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Arc Mobility Model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the RepetitivePulseBreakdownModel which calculates breakdown voltage with memory effects from repetitive pulsing.">

.. only:: html

  .. image:: /auto_examples/gallery/images/thumb/sphx_glr_plot_pulsed_breakdown_example_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_gallery_plot_pulsed_breakdown_example.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Pulsed Breakdown Model</div>
    </div>


.. raw:: html

    <div class="sphx-glr-thumbcontainer" tooltip="This example demonstrates the TorchFlowSystem which calculates flow velocity, residence time, and pressure drop in the plasma torch.">

.. only:: html

  .. image:: /auto_examples/gallery/images/thumb/sphx_glr_plot_torch_flow_system_example_thumb.png
    :alt:

  :ref:`sphx_glr_auto_examples_gallery_plot_torch_flow_system_example.py`

.. raw:: html

      <div class="sphx-glr-thumbnail-title">Torch Flow System</div>
    </div>


.. thumbnail-parent-div-close

.. raw:: html

    </div>


.. toctree::
   :hidden:

   /auto_examples/gallery/plot_arc_density_model_example
   /auto_examples/gallery/plot_coverage_model_basic_example
   /auto_examples/gallery/plot_coverage_model_example
   /auto_examples/gallery/plot_energy_to_temperature_example
   /auto_examples/gallery/plot_generator_system_example
   /auto_examples/gallery/plot_initial_temperature_model_example
   /auto_examples/gallery/plot_mobility_model_example
   /auto_examples/gallery/plot_pulsed_breakdown_example
   /auto_examples/gallery/plot_torch_flow_system_example