credit.postblock.mslp
=====================

.. py:module:: credit.postblock.mslp

.. autoapi-nested-parse::

   MSLPDiagnostic postblock
   ------------------------
   Computes mean sea level pressure (MSLP) from surface pressure, near-surface
   temperature, and static surface geopotential using the Trenberth et al. (1993)
   formula.  Fully vectorized in PyTorch — no numpy, no per-pixel loops.

   Reference:
       Trenberth, K., J. Berry, and L. Buja, 1993: Vertical Interpolation and
       Truncation of Model-Coordinate Data. NCAR Tech. Note NCAR/TN-396+STR.
       https://doi.org/10.5065/D6HX19NH

   Bug fixed vs. the original numpy implementation in credit/interp.py (merged
   in PR #341): the sea-level temperature branch test used `LAPSE_RATE * sgp`
   where sgp is geopotential (m² s⁻²); it must be `LAPSE_RATE * sgp / GRAVITY`
   to convert geopotential to height in metres.



Attributes
----------

.. autoapisummary::

   credit.postblock.mslp._LAPSE_RATE
   credit.postblock.mslp._ALPHA_STD
   credit.postblock.mslp._T_WARM
   credit.postblock.mslp._T_COLD


Classes
-------

.. autoapisummary::

   credit.postblock.mslp.MSLPDiagnostic


Functions
---------

.. autoapisummary::

   credit.postblock.mslp.mslp_from_surface_pressure


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

.. py:data:: _LAPSE_RATE
   :value: 0.0065


.. py:data:: _ALPHA_STD
   :value: 0.19026120030795432


.. py:data:: _T_WARM
   :value: 290.5


.. py:data:: _T_COLD
   :value: 255.0


.. py:function:: mslp_from_surface_pressure(surface_pressure: torch.Tensor, temperature: torch.Tensor, surface_geopotential: torch.Tensor) -> torch.Tensor

   Vectorized MSLP from surface pressure, near-surface T, and PHIS.

   Implements the simplified Trenberth et al. (1993) formula.  All inputs
   must be broadcastable to the same shape.

   :param surface_pressure: surface pressure in Pa, shape (..., H, W).
   :param temperature: near-surface temperature in K, shape (..., H, W).
   :param surface_geopotential: PHIS in m² s⁻², shape (..., H, W).

   :returns: MSLP in Pa, same shape as inputs.


.. py:class:: MSLPDiagnostic(output_name: str = 'ARCO_ERA5/derived_diagnostic/2d/mean_sea_level_pressure', dataset_name: str = 'ARCO_ERA5', data_keys: Iterable[str] = ('prediction', 'target'), surface_pressure_var: str = 'ARCO_ERA5/prognostic/2d/surface_pressure', temperature_var: str = 'ARCO_ERA5/prognostic/2d/2m_temperature', surface_geopotential_var: str = 'ARCO_ERA5/static/2d/geopotential_at_surface')

   Bases: :py:obj:`torch.nn.Module`


   Postblock that computes MSLP from surface pressure, 2m temperature, and PHIS.

   Follows the same data-dict protocol as ``GeopotentialDiagnostic``: all
   inputs are accessed by variable name from the nested batch dict, and the
   result is written back under ``output_name``.

   :param output_name: key written into ``data[dataset_name]`` for the result.
   :param dataset_name: top-level key inside each ``data_type`` sub-dict.
   :param data_keys: which top-level batch-dict keys to process (e.g.
                     ``("prediction", "target")``).
   :param surface_pressure_var: variable name for surface pressure (Pa).
   :param temperature_var: variable name for near-surface temperature (K).
   :param surface_geopotential_var: variable name for PHIS (m² s⁻²).


   .. py:attribute:: output_name
      :value: 'ARCO_ERA5/derived_diagnostic/2d/mean_sea_level_pressure'



   .. py:attribute:: dataset_name
      :value: 'ARCO_ERA5'



   .. py:attribute:: data_keys
      :value: ('prediction', 'target')



   .. py:attribute:: surface_pressure_var
      :value: 'ARCO_ERA5/prognostic/2d/surface_pressure'



   .. py:attribute:: temperature_var
      :value: 'ARCO_ERA5/prognostic/2d/2m_temperature'



   .. py:attribute:: surface_geopotential_var
      :value: 'ARCO_ERA5/static/2d/geopotential_at_surface'



   .. py:method:: forward(data_dict: dict) -> dict

      Compute MSLP for each requested data key and write into the batch dict.

      :param data_dict: nested batch dict.  Each ``data_dict[data_type][dataset_name]``
                        must contain ``surface_pressure_var``, ``temperature_var``, and
                        ``surface_geopotential_var`` as tensors with shapes broadcastable
                        to ``(B, 1, n_time, H, W)``.

      :returns: The same ``data_dict`` with ``output_name`` added under each
                processed ``data_type[dataset_name]``.