tud_lbm.io.plotting.ca_theta_plot
=================================

.. py:module:: tud_lbm.io.plotting.ca_theta_plot

.. autoapi-nested-parse::

   Ca–θ plotting utilities for leading and trailing contact lines.



Classes
-------

.. autoapisummary::

   tud_lbm.io.plotting.ca_theta_plot.CaThetaVsTimePlot
   tud_lbm.io.plotting.ca_theta_plot.CaThetaVsXPlot


Functions
---------

.. autoapisummary::

   tud_lbm.io.plotting.ca_theta_plot.plot_dual_axis_ca_theta
   tud_lbm.io.plotting.ca_theta_plot.plot_contact_angle_vs_capillary_number
   tud_lbm.io.plotting.ca_theta_plot.save_figure


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

.. py:function:: plot_dual_axis_ca_theta(x_data: numpy.ndarray, ca_trailing: numpy.ndarray, ca_leading: numpy.ndarray, theta_trailing: numpy.ndarray, theta_leading: numpy.ndarray, *, x_label: str = '$X_{\\mathrm{avg}}/R_0$', figsize: tuple[float, float] = DEFAULT_STYLE.dual_axis_figsize, dpi: int = DEFAULT_STYLE.dpi, ca_limits: tuple[float, float] | None = None, angle_limits: tuple[float, float] | None = None, x_limits: tuple[float, float] | None = None) -> matplotlib.figure.Figure

   Plot capillary number and contact angle on dual y-axes vs a shared x.

   Creates a figure with Ca on the left y-axis and θ on the right y-axis
   (via ``twinx``). Trailing and leading edges are distinguished by colour.

   :param x_data: Shared x data; typically normalised time (Δt/t_tot) or
                  normalised position (X_avg/R_0).
   :param ca_trailing: Capillary number for the trailing contact line.
   :param ca_leading: Capillary number for the leading contact line.
   :param theta_trailing: Contact angle (degrees) for the trailing contact line.
   :param theta_leading: Contact angle (degrees) for the leading contact line.
   :param x_label: Label for the shared x-axis.
   :param figsize: Figure size in inches ``(width, height)``.
   :param dpi: Resolution in dots per inch.
   :param ca_limits: ``(y_min, y_max)`` for the Ca axis; auto-scaled when ``None``.
   :param angle_limits: ``(y_min, y_max)`` for the θ axis; auto-scaled when ``None``.
   :param x_limits: ``(x_min, x_max)`` for the x-axis; auto-scaled when ``None``.

   :returns: A :class:`matplotlib.figure.Figure`.


.. py:function:: plot_contact_angle_vs_capillary_number(ca_trailing: numpy.ndarray, theta_trailing: numpy.ndarray, ca_leading: numpy.ndarray, theta_leading: numpy.ndarray, *, log_scale: bool = False, title: str | None = None, figsize: tuple[float, float] = DEFAULT_STYLE.ca_theta_figsize, dpi: int = DEFAULT_STYLE.dpi, reference_csv: str | pathlib.Path | None = None) -> matplotlib.figure.Figure

   Plot contact angle vs capillary number (θ on y, Ca on x).

   Useful for overlaying an older reference dataset on a new one. For the
   standard dual-axis time/position view use :func:`plot_dual_axis_ca_theta`.

   :param ca_trailing: Capillary number array for the trailing edge.
   :param theta_trailing: Contact angle array (degrees) for the trailing edge.
   :param ca_leading: Capillary number array for the leading edge.
   :param theta_leading: Contact angle array (degrees) for the leading edge.
   :param log_scale: Apply logarithmic scale to the Ca axis when ``True``.
   :param title: Optional figure title.
   :param figsize: Figure size in inches ``(width, height)``.
   :param dpi: Figure resolution in dots per inch.
   :param reference_csv: Path to a CSV file with columns ``Ca_trailing``,
                         ``theta_trailing``, ``Ca_leading``, ``theta_leading``. When
                         supplied the reference data is overlaid as open markers.

   :returns: A :class:`matplotlib.figure.Figure`.


.. py:function:: save_figure(fig: matplotlib.figure.Figure, path: str | pathlib.Path, *, dpi: int = 300) -> None

   Save *fig* to *path*; file format is inferred from the path suffix.

   :param fig: The figure to save.
   :param path: Output path (e.g. ``"ca_theta.png"`` or ``"ca_theta.pdf"``).
   :param dpi: Resolution in dots per inch (only relevant for raster formats).


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

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


   Dual-axis Ca/θ plot with normalised timestep (Δt/t_tot) on the x-axis.


   .. py:attribute:: name
      :value: 'ca_theta_vs_time'



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



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

      Compute Ca, θ and x_time arrays from snapshot files.



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

      Draw dual-axis Ca/θ scatter with normalised time on x.



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

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


   Dual-axis Ca/θ plot with normalised position (X_avg/R_0) on the x-axis.


   .. py:attribute:: name
      :value: 'ca_theta_vs_x'



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



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

      Compute Ca, θ and x_pos arrays from snapshot files.



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

      Draw dual-axis Ca/θ scatter with normalised position on x.