uclchem.style
=============

.. py:module:: uclchem.style

.. autoapi-nested-parse::

   Publication-quality matplotlib style for UCLCHEM.

   Applies STIX serif fonts and MNRAS-compatible sizes without requiring a
   LaTeX installation.  The style is applied automatically when ``uclchem`` is
   imported.  Set the environment variable ``UCLCHEM_NO_STYLE=1`` before
   importing to suppress auto-apply.

   **Key Functions:**

   - :func:`apply` - Apply the UCLCHEM rcParams globally
   - :func:`reset` - Restore matplotlib defaults
   - :func:`context` - Temporary style context manager
   - :func:`format_chemical_formula` - Convert species names to mathtext labels
   - :func:`format_reaction_label` - Convert reaction strings to mathtext labels

   **Example Usage:**

       >>> import uclchem  # style applied on import
       >>> import matplotlib.pyplot as plt
       >>> fig, ax = plt.subplots()
       >>> _ = ax.set_xlabel(uclchem.style.format_chemical_formula("HCO+"))
       >>> uclchem.style.reset()      # restore matplotlib defaults
       >>> uclchem.style.apply()      # re-apply UCLCHEM style



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


Functions
~~~~~~~~~

.. autoapisummary::

   uclchem.style.apply
   uclchem.style.context
   uclchem.style.format_chemical_formula
   uclchem.style.format_reaction_label
   uclchem.style.reset



Attributes
~~~~~~~~~~

.. autoapisummary::

   uclchem.style.UCLCHEM_STYLE


.. py:function:: apply(style: dict[str, object] = UCLCHEM_STYLE) -> None

   Apply *style* to the global matplotlib rcParams.

   :param style: Mapping of rcParam keys to values.  Defaults to
                 :data:`UCLCHEM_STYLE`.
   :type style: dict[str, object]


.. py:function:: context(style: dict[str, object] = UCLCHEM_STYLE) -> collections.abc.Generator[None, None, None]

   Apply *style* temporarily as a context manager.

   :param style: Mapping of rcParam keys to values.  Defaults to
                 :data:`UCLCHEM_STYLE`.
   :type style: dict[str, object]

   :Yields: *None* -- All ``plt`` calls inside the block use *style*; settings are
            restored on exit.

   .. rubric:: Examples

   >>> import uclchem
   >>> with uclchem.style.context():
   ...     pass  # plots here use UCLCHEM style


.. py:function:: format_chemical_formula(name: str) -> str

   Convert a UCLCHEM species name to a mathtext label.

   Subscripts digit runs and superscripts charge suffixes so the result
   renders correctly with matplotlib's built-in mathtext engine (no LaTeX
   required).

   :param name: UCLCHEM species name, e.g. ``"HCO+"``, ``"#H2O"``, ``"@CO2"``,
                ``"E-"``, ``"o-H2"``.
   :type name: str

   :returns: Mathtext string, e.g. ``r"$\mathrm{HCO^{+}}$"``.
   :rtype: str

   .. rubric:: Examples

   >>> format_chemical_formula("HCO+")
   '$\\mathrm{HCO^{+}}$'
   >>> format_chemical_formula("H2O")
   '$\\mathrm{H_{2}O}$'
   >>> format_chemical_formula("#H2O")
   '#$\\mathrm{H_{2}O}$'


.. py:function:: format_reaction_label(rxn: str, k_mean: float | None = None) -> str

   Convert a UCLCHEM reaction string to a mathtext legend label.

   :param rxn: Reaction string in UCLCHEM format, e.g.
               ``"H3+ + CO -> HCO+ + H2"``.
   :type rxn: str
   :param k_mean: Mean rate coefficient to append to the label.  If ``None`` no
                  rate is shown.  Default: ``None``.
   :type k_mean: float | None

   :returns: Mathtext string suitable for use as a matplotlib legend label.
   :rtype: str

   .. rubric:: Examples

   >>> format_reaction_label("H2 + O -> OH + H")
   '$\\mathrm{H_{2}}$ + $\\mathrm{O}$ $\\rightarrow$ $\\mathrm{OH}$ + $\\mathrm{H}$'


.. py:function:: reset() -> None

   Restore matplotlib's built-in default rcParams.


.. py:data:: UCLCHEM_STYLE
   :type:  dict[str, object]