derive_transport
================

.. py:module:: derive_transport


Attributes
----------

.. autoapisummary::

   derive_transport.model_trans_dir
   derive_transport.weight_folder
   derive_transport.monthly_transport
   derive_transport.filepath
   derive_transport.gc_metpath
   derive_transport.month


Functions
---------

.. autoapisummary::

   derive_transport.interpolate_T
   derive_transport.interpolate_cflux
   derive_transport.pchip2
   derive_transport.infer_eddy_agrid
   derive_transport.validation_tracer_agrid
   derive_transport.smoothKzz
   derive_transport.correct_eddy
   derive_transport.derive_ustar
   derive_transport.wstar_potentialtemp
   derive_transport.make_nondivergent
   derive_transport.add_convection
   derive_transport.make_2D_yearly_files


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

.. py:data:: model_trans_dir
   :value: 'Uninferable/model_data/transport/'


.. py:data:: weight_folder
   :value: '/user/home/lw13938/work/TwoDmodel/weights'


.. py:data:: monthly_transport
   :value: '/user/home/lw13938/work/TwoDmodel/TransportParameters'


.. py:data:: filepath
   :value: '/user/home/lw13938/work/GCClassic.13.3.4/rundirs/Tracer_outputs/'


.. py:data:: gc_metpath
   :value: '/user/home/lw13938/shared/GEOS_CHEM/data/ExtData/GEOS_4x5/MERRA2/'


.. py:function:: interpolate_T(ds_met, var, zb3D, lon, zx2D, latx2D)

   Interpolate dataset variable from 3D to 2D grid using xesmf

   :param ds_met: xarray dataset containing variable to interpolate
   :type ds_met: dataset
   :param var: variable to interpolate
   :type var: string
   :param zb3D: Scale height of 3D model
   :type zb3D: array
   :param lon: Longitude of 3D model
   :type lon: array
   :param zx2D: Scale height of 2D model
   :type zx2D: array
   :param latx2D: Latitude of 2D model
   :type latx2D: array

   :returns: xarray DataArray of interpolated variable
   :rtype: DataArray


.. py:function:: interpolate_cflux(ds_met, var, zb3D, lon, zx2D, latx2D)

   Interpolate dataset variable from 3D to 2D grid using xesmf.
   Basically the same as interpolate_T but need some slight modifications.

   :param ds_met: xarray dataset containing variable to interpolate
   :type ds_met: dataset
   :param var: variable to interpolate
   :type var: string
   :param zb3D: Scale height of 3D model
   :type zb3D: array
   :param lon: Longitude of 3D model
   :type lon: array
   :param zx2D: Scale height of 2D model
   :type zx2D: array
   :param latx2D: Latitude of 2D model
   :type latx2D: array

   :returns: xarray DataArray of interpolated variable
   :rtype: DataArray


.. py:function:: pchip2(x, y, z, xi, yi)

   P-chip interpolation on 2-D. x, y, xi, yi should be 1-D
   and z.shape == (len(x), len(y))

   Taken from: https://scipy-user.scipy.narkive.com/FG5DVM1l/2-d-data-interpolation
   This ensures monoticity for interpolation (splines can over/undershoot)


.. py:function:: infer_eddy_agrid(dsvqt, dsvt, dswqt, dswt, y2D, ym2D)

   This infers the eddy trasport tensor following the approach of Bachmann et al. (2015)
   Input are data arrays of v and w winds, and dataset of transport tracers all interpolated
   to the 2D model resolution.

   :param dsvqt: Concentrations on same grid as v-field
   :type dsvqt: dataset
   :param dsvt: Met data on same grid as v-field
   :type dsvt: dataset
   :param dswqt: Concentrations on same grid as w-field
   :type dswqt: dataset
   :param dswt: Met data on same grid as w-field
   :type dswt: dataset
   :param y2D: y-coordinate at grid cell edges
   :type y2D: array
   :param ym2D: y-coordinate at grid cell mid-points
   :type ym2D: array

   :returns: Lists containing the eddy flux tensor and gradient flux fields
   :rtype: list


.. py:function:: validation_tracer_agrid(dsvqt, dsvt, dswqt, dswt, tn, y2D, ym2D)

   Flux-gradient calculation if wishing to validate the eddy-flux derivation.
   Note, this is not currently used.

   :param dsvqt: Concentrations on same grid as v-field
   :type dsvqt: dataset
   :param dsvt: Met data on same grid as v-field
   :type dsvt: dataset
   :param dswqt: Concentrations on same grid as w-field
   :type dswqt: dataset
   :param dswt: Met data on same grid as w-field
   :type dswt: dataset
   :param tn: Tracer number used for validation
   :type tn: int
   :param y2D: y-coordinate at grid cell edges
   :type y2D: array
   :param ym2D: y-coordinate at grid cell mid-points
   :type ym2D: array

   :returns: Gradient flux fields.
   :rtype: arrays


.. py:function:: smoothKzz(Kz, limit=50.0, lower=False)

   Kzz is hard to derive so smooth over unrealistically high diffusion.
   Kzz is generally higher in the lower atmosphere. Set upper Kzz limit
   to 50 m2/s (Plumb and Mahlman max is around 20) as upper limit,
   and reset as the average of surrounding grid squares.

   :param Kz: Kzz component of eddy-transport tensor
   :type Kz: array
   :param limit: Upper limit of Kzz. Defaults to 50.
   :type limit: float, optional
   :param lower: True if setting a lower limit. Defaults to False.
   :type lower: bool, optional

   :returns: Smoothed Kzz tensor component.
   :rtype: array


.. py:function:: correct_eddy(K, zm2D, z2D, ym2D, y2D)

   Kyy can't be negative. Put in check/correction as Plumb & Mahlman 1986

   :param K: Eddy-transport tensor
   :type K: list
   :param zm2D: z-coordinate mid-points in 2D model
   :type zm2D: array
   :param z2D: z-coordinate edges in 2D model
   :type z2D: array
   :param ym2D: y-coordinate mid-points in 2D model
   :type ym2D: array
   :param y2D: y-coordinate edges in 2D model
   :type y2D: array

   :returns:

             Corrected Eddy-transport tensor, the Kzy tensor component
                           interpolated to other edges, diffusivity on different grids
   :rtype: list, arrays


.. py:function:: derive_ustar(K, Kzy_ygrid, Kyz_zgrid, zm2D, ym2D)

   Take anti-symmetric part of eddy transport tensor to derive
   residual advective transport.

   :param K: Eddy-transport tensor.
   :type K: list
   :param Kzy_ygrid: Kzy component on v-wind grid.
   :type Kzy_ygrid: array
   :param Kyz_zgrid: Kzy component on w-wind grid.
   :type Kyz_zgrid: array
   :param zm2D: z-coordinate mid-points in 2D model.
   :type zm2D: array
   :param ym2D: y-coordinate mid-points in 2D model.
   :type ym2D: array

   :returns: residual v and w advection.
   :rtype: array


.. py:function:: wstar_potentialtemp(dsTwt, dsvwt, H)

   Calculate w* (eddy advective component) using potential temperature (not used)


.. py:function:: make_nondivergent(w_in, v_in, cosc, cose, H, z, zm, y, dz, dy)

   Ensure residual wind fields are non-divergence.
   This is lost through interpolation etc.

   :param w_in: Divergent w-wind.
   :type w_in: array
   :param v_in: Divergent v-wind.
   :type v_in: array
   :param cosc: Cosine of latitude at grid centres.
   :type cosc: _type_
   :param cose: Cosine of latitude at grid edges.
   :type cose: _type_
   :param H: Scale height
   :type H: float
   :param z: z-coordinate edge points in 2D model.
   :type z: array
   :param zm: z-coordinate mid-points in 2D model.
   :type zm: array
   :param y: y-coordinate edge points in 2D model.
   :type y: array
   :param dz: Grid cell heights.
   :type dz: array
   :param dy: Grid cell widths.
   :type dy: array

   :returns: Non-divergent w and v wind fields.
   :rtype: arrays


.. py:function:: add_convection(ds2d)

   Add convective parameters straight from MERRA2 met data

   :param ds2d: The monthly dataset of 2D transport to which
                the convection will be added
   :type ds2d: xarray dataset

   :returns: A Data Array of the 2D monthly convective flux
   :rtype: xarray dataarray


.. py:function:: make_2D_yearly_files(start_year, end_year=None)

   Take monthly 2D transport and make CF compliant 3D netcdf files


.. py:data:: month