tephpy.transforms
=================

.. py:module:: tephpy.transforms

.. autoapi-nested-parse::

   Coordinate transforms for the tephigram projection.

   Pure numpy functions between the three coordinate frames of the tephigram
   (spec §3.1): pressure/temperature (p, T), temperature/potential-temperature
   (T, theta), and the rotated tephigram (x, y) plane, where

       x = MA * ln(theta_K) + T        y = MA * ln(theta_K) - T

   with MA = 300 and theta_K the potential temperature in Kelvin. The
   construction is derived from Met Office Factsheet 13 and Stull,
   *Practical Meteorology* ch. 5, and cross-validated against tephi as an
   oracle (``tests/test_oracle.py``) — not ported from it.

   This module is the documented exemption to the pint units policy (spec §5):
   bare ``float64`` arrays in diagram-native units — pressure in hPa,
   temperatures in degrees Celsius, x/y dimensionless. Out-of-domain input
   (non-positive pressure, potential temperatures theta at or below absolute
   zero) propagates NaN; exception-carrying validation lives at the
   quantified boundaries above this module (spec §6).

   ..
       !! processed by numpydoc !!


Functions
---------

.. autoapisummary::

   tephpy.transforms.theta_from_pressure_temperature
   tephpy.transforms.pressure_from_temperature_theta
   tephpy.transforms.xy_from_temperature_theta
   tephpy.transforms.temperature_theta_from_xy


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

.. py:function:: theta_from_pressure_temperature(pressure: numpy.typing.ArrayLike, temperature: numpy.typing.ArrayLike) -> numpy.typing.NDArray[numpy.float64]

   
   Convert pressure and temperature to potential temperature.

   Poisson's equation: ``theta_K = T_K * (P_REF / p) ** kappa``.

   :Parameters:

       **pressure** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Pressure in hPa. Non-positive values yield NaN.

       **temperature** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Temperature in degrees Celsius.



   :Returns:

       :obj:`numpy.ndarray`
           Potential temperature in degrees Celsius, ``float64``, broadcast
           over the inputs.











   ..
       !! processed by numpydoc !!

.. py:function:: pressure_from_temperature_theta(temperature: numpy.typing.ArrayLike, theta: numpy.typing.ArrayLike) -> numpy.typing.NDArray[numpy.float64]

   
   Convert temperature and potential temperature to pressure.

   Inverse of :func:`theta_from_pressure_temperature`:
   ``p = P_REF * (T_K / theta_K) ** (1 / kappa)``.

   :Parameters:

       **temperature** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Temperature in degrees Celsius.

       **theta** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Potential temperature in degrees Celsius. Values at or below
           absolute zero yield NaN.



   :Returns:

       :obj:`numpy.ndarray`
           Pressure in hPa, ``float64``, broadcast over the inputs.











   ..
       !! processed by numpydoc !!

.. py:function:: xy_from_temperature_theta(temperature: numpy.typing.ArrayLike, theta: numpy.typing.ArrayLike) -> tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

   
   Convert temperature and potential temperature to tephigram (x, y).

   The rotated tephigram mapping: ``x = MA * ln(theta_K) + T`` and
   ``y = MA * ln(theta_K) - T``, which renders isotherms and dry adiabats
   as exactly perpendicular straight lines.

   :Parameters:

       **temperature** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Temperature in degrees Celsius.

       **theta** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Potential temperature in degrees Celsius. Values at or below
           absolute zero yield NaN.



   :Returns:

       :class:`python:tuple` of :obj:`numpy.ndarray`
           The tephigram ``(x, y)`` coordinates (the axes' data space),
           ``float64``, broadcast over the inputs.











   ..
       !! processed by numpydoc !!

.. py:function:: temperature_theta_from_xy(x: numpy.typing.ArrayLike, y: numpy.typing.ArrayLike) -> tuple[numpy.typing.NDArray[numpy.float64], numpy.typing.NDArray[numpy.float64]]

   
   Convert tephigram (x, y) coordinates back to temperature and theta.

   Inverse of :func:`xy_from_temperature_theta`: ``T = (x - y) / 2`` and
   ``theta_K = exp((x + y) / (2 * MA))``.

   :Parameters:

       **x** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Tephigram x coordinate (dimensionless, the axes' data space).

       **y** : :obj:`ArrayLike <numpy.typing.ArrayLike>`
           Tephigram y coordinate (dimensionless, the axes' data space).



   :Returns:

       :class:`python:tuple` of :obj:`numpy.ndarray`
           ``(temperature, theta)`` in degrees Celsius, ``float64``,
           broadcast over the inputs.











   ..
       !! processed by numpydoc !!