tud_lbm.io.plotting.analysis
============================

.. py:module:: tud_lbm.io.plotting.analysis

.. autoapi-nested-parse::

   Analysis plot operators for saved simulation history.



Classes
-------

.. autoapisummary::

   tud_lbm.io.plotting.analysis.MaxVelocityPlot
   tud_lbm.io.plotting.analysis.DensityRatioPlot
   tud_lbm.io.plotting.analysis.AvgDensityPlot
   tud_lbm.io.plotting.analysis.ContactAngleLeftPlot
   tud_lbm.io.plotting.analysis.ContactAngleRightPlot
   tud_lbm.io.plotting.analysis.ContactLineSpeedLeftPlot
   tud_lbm.io.plotting.analysis.ContactLineSpeedRightPlot
   tud_lbm.io.plotting.analysis.ContactAnglesPairPlot
   tud_lbm.io.plotting.analysis.ContactLineSpeedsPairPlot
   tud_lbm.io.plotting.analysis.SimulationCsvExport
   tud_lbm.io.plotting.analysis.RZero


Functions
---------

.. autoapisummary::

   tud_lbm.io.plotting.analysis.build_simulation_csv
   tud_lbm.io.plotting.analysis.compare_runs
   tud_lbm.io.plotting.analysis.process_parent_dir
   tud_lbm.io.plotting.analysis.main


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

.. py:class:: MaxVelocityPlot(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`_BaseAnalysisPlot`


   Plot maximum velocity magnitude over time.


   .. py:attribute:: name
      :value: 'max_velocity'



   .. py:attribute:: title
      :value: 'Maximum velocity vs timestep'



   .. py:attribute:: ylabel
      :value: 'max(|u|)'



   .. py:attribute:: color
      :value: 'tab:blue'



   .. py:attribute:: required_keys
      :value: ('u',)



   .. py:method:: compute(files: list[pathlib.Path]) -> dict[str, numpy.ndarray]

      Compute maximum velocity values for each timestep file.



.. py:class:: DensityRatioPlot(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`_BaseAnalysisPlot`


   Plot max/min density ratio over time.


   .. py:attribute:: name
      :value: 'density_ratio'



   .. py:attribute:: title
      :value: 'Density ratio vs timestep'



   .. py:attribute:: ylabel
      :value: 'max(rho) / min(rho)'



   .. py:attribute:: color
      :value: 'tab:orange'



   .. py:attribute:: ylog
      :value: True



   .. py:attribute:: required_keys
      :value: ('rho',)



   .. py:method:: compute(files: list[pathlib.Path]) -> dict[str, numpy.ndarray]

      Compute density ratio values for each timestep file.



.. py:class:: AvgDensityPlot(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`_BaseAnalysisPlot`


   Plot average density over time.


   .. py:attribute:: name
      :value: 'avg_density'



   .. py:attribute:: title
      :value: 'Average density vs timestep'



   .. py:attribute:: ylabel
      :value: 'mean(rho)'



   .. py:attribute:: color
      :value: 'tab:green'



   .. py:attribute:: required_keys
      :value: ('rho',)



   .. py:method:: compute(files: list[pathlib.Path]) -> dict[str, numpy.ndarray]

      Compute average density values for each timestep file.



.. py:class:: ContactAngleLeftPlot(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`_BaseAnalysisPlot`


   Plot left contact angle over time.


   .. py:attribute:: name
      :value: 'contact_angle_left'



   .. py:attribute:: title
      :value: 'Left contact angle vs timestep'



   .. py:attribute:: ylabel
      :value: 'Contact angle (deg)'



   .. py:attribute:: color
      :value: 'tab:purple'



   .. py:attribute:: required_keys
      :value: ('ca_left',)



   .. py:method:: compute(files: list[pathlib.Path]) -> dict[str, numpy.ndarray]

      Compute left contact angle values for each timestep file.



.. py:class:: ContactAngleRightPlot(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`_BaseAnalysisPlot`


   Plot right contact angle over time.


   .. py:attribute:: name
      :value: 'contact_angle_right'



   .. py:attribute:: title
      :value: 'Right contact angle vs timestep'



   .. py:attribute:: ylabel
      :value: 'Contact angle (deg)'



   .. py:attribute:: color
      :value: 'tab:red'



   .. py:attribute:: required_keys
      :value: ('ca_right',)



   .. py:method:: compute(files: list[pathlib.Path]) -> dict[str, numpy.ndarray]

      Compute right contact angle values for each timestep file.



.. py:class:: ContactLineSpeedLeftPlot(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`_ContactLineSpeedBase`


   Plot left contact-line speed over time.


   .. py:attribute:: name
      :value: 'contact_line_speed_left'



   .. py:attribute:: title
      :value: 'Left contact-line speed vs timestep'



   .. py:attribute:: ylabel
      :value: 'd(cll_left)/dt'



   .. py:attribute:: color
      :value: 'tab:brown'



   .. py:attribute:: cl_key
      :value: 'cll_left'



   .. py:attribute:: required_keys
      :value: ('cll_left',)



.. py:class:: ContactLineSpeedRightPlot(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`_ContactLineSpeedBase`


   Plot right contact-line speed over time.


   .. py:attribute:: name
      :value: 'contact_line_speed_right'



   .. py:attribute:: title
      :value: 'Right contact-line speed vs timestep'



   .. py:attribute:: ylabel
      :value: 'd(cll_right)/dt'



   .. py:attribute:: color
      :value: 'tab:pink'



   .. py:attribute:: cl_key
      :value: 'cll_right'



   .. py:attribute:: required_keys
      :value: ('cll_right',)



.. py:class:: ContactAnglesPairPlot(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`tud_lbm.io.plotting.base.AnalysisPlot`


   Render paired left/right contact-angle history.


   .. py:attribute:: name
      :value: 'contact_angles_pair'



   .. py:attribute:: required_keys
      :value: ('ca_left', 'ca_right')



   .. py:method:: compute(files: list[pathlib.Path]) -> dict[str, numpy.ndarray]

      Compute left/right contact-angle arrays for all snapshots.



   .. py:method:: render(ax: matplotlib.axes.Axes, precomputed: dict[str, numpy.ndarray]) -> None

      Draw the paired contact-angle scatter plot.



.. py:class:: ContactLineSpeedsPairPlot(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`tud_lbm.io.plotting.base.AnalysisPlot`


   Render paired left/right contact-line speed history.


   .. py:attribute:: name
      :value: 'contact_line_speeds_pair'



   .. py:attribute:: required_keys
      :value: ('cll_left', 'cll_right')



   .. py:method:: compute(files: list[pathlib.Path]) -> dict[str, numpy.ndarray]

      Compute left/right contact-line speed arrays for all snapshots.



   .. py:method:: render(ax: matplotlib.axes.Axes, precomputed: dict[str, numpy.ndarray]) -> None

      Draw the paired contact-line speed scatter plot.



.. py:class:: SimulationCsvExport(config: tud_lbm.config.SimulationConfig | None = None)

   Bases: :py:obj:`tud_lbm.io.plotting.base.AnalysisPlot`


   Export per-timestep droplet metrics to ``simulation_data.csv``.


   .. py:attribute:: name
      :value: 'simulation_csv'



   .. py:attribute:: required_keys
      :value: ('rho', 'u')



   .. py:attribute:: export_only
      :value: True



   .. py:method:: compute(files: list[pathlib.Path]) -> dict[str, numpy.ndarray]

      Return an empty payload because this operator is export-only.



   .. py:method:: render(ax: matplotlib.axes.Axes, precomputed: dict[str, numpy.ndarray]) -> None

      Render a placeholder panel when this operator is selected for plotting.



   .. py:method:: export(run_dir: pathlib.Path) -> pathlib.Path | None

      Write ``simulation_data.csv`` for the configured run directory.



.. py:class:: RZero

   Bases: :py:obj:`NamedTuple`


   Resolved R₀ plus whether the nominal-radius fallback was used.


   .. py:attribute:: value
      :type:  float


   .. py:attribute:: used_fallback
      :type:  bool


.. py:function:: build_simulation_csv(run_dir: str | pathlib.Path, config: tud_lbm.config.SimulationConfig) -> pathlib.Path | None

   Compute per-timestep metrics and write ``simulation_data.csv``.

   Skips silently (returns ``None``) when *config.sim_type* is not a
   supported wetting variant. Saves the CSV directly to *run_dir*.

   :param run_dir: Run directory (contains ``data/timestep_*.npz``).
   :param config: :class:`~tud_lbm.config.simulation_config.SimulationConfig`.

   :returns: Path to the written CSV, or ``None`` when skipped.


.. py:function:: compare_runs(parent_dir: str | pathlib.Path) -> None

   Generate 8 comparison scatter plots across all processed runs.

   Reads ``simulation_data.csv`` files produced by :func:`build_simulation_csv`
   from every run directory under *parent_dir* and writes 8 plots to
   ``<parent_dir>/comparison_analysis/``.

   :param parent_dir: Parent directory that contains the individual run directories.


.. py:function:: process_parent_dir(parent_dir: str | pathlib.Path, fields: list[str] | None = None) -> tuple[int, int]

   Discover runs, export per-run CSVs, and generate comparison plots.

   Discovers runs by searching for ``config.toml`` files recursively.
   Skips directories whose path contains ``"init"`` or ``"comparison_analysis"``.
   Writes ``simulation_data.csv`` per run, then generates 8 comparison plots
   when at least one run produced CSV data.

   :param parent_dir: Absolute or relative path to the parent directory.
   :param fields: Comparison operator names to run as per-run analysis plots.
                  When ``None``, no per-run analysis plots are generated beyond the CSV.

   :returns: A tuple ``(n_runs_found, n_runs_with_csv)``.


.. py:function:: main(parent_dir: str | None = None) -> None

   Script entry point for batch CSV export and run comparison plots.