pycif.plugins.transforms.complex.diagmet — API reference

pycif.plugins.transforms.complex.diagmet — API reference#

Configuration reference: diagmet plugin

pycif.plugins.transforms.complex.diagmet.adjoint.adjoint(transf, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, onlyinit=False, **kwargs)[source]#

No-op adjoint for diagmet.

Meteorological fields are not control variables; diagmet has no adjoint. This function exists solely to satisfy the transform interface contract.

pycif.plugins.transforms.complex.diagmet.forward.forward(transf, inout_datastore, controlvect, obsvect, mapper, di, df, mode, runsubdir, workdir, onlyinit=False, **kwargs)[source]#

Run the full DIAGMET meteorological processing pipeline.

Executes the following steps in order, each implemented in a dedicated utility module under utils/:

  1. altipres — pressure at level mid-points, altitudes, air density.

  2. defcolumn — interpolation of 3-D fields to the surface level.

  3. uv_rotation — rotation of u/v wind components to the model grid.

  4. mean_z0_shf_extra_urban_temp — urban heat island correction to roughness length and sensible heat flux.

  5. sv_heat_flux — sensible and virtual heat fluxes.

  6. friction_velocity — friction velocity \(u^*\) (Ustar).

  7. boundary_layer_height — PBL height.

  8. checkcfl — CFL condition check and wind-speed limiting.

  9. low_cloud_top — low cloud top pressure.

  10. obukov_length — Obukhov length \(L\).

  11. vertical_turbulent_diffusivity — turbulent diffusion coefficient \(K_{zz}\) at CHIMERE layer tops.

  12. convection — convective mass fluxes.

  13. precipitations — total precipitation (convective + large-scale).

  14. cloud_optical_thickness — cloud optical depth.

The physical formula carried out by each step is documented in DIAGMET meteorological pre-processing.

A temporary transf.diag_misc dict is created at entry and deleted at exit to allow intermediate fields to be passed between steps.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore; 'inputs' provides the raw ECMWF fields; 'outputs' receives the derived CHIMERE meteorological fields.

  • controlvect – unused.

  • obsvect – unused.

  • mapper (dict) – transform mapper.

  • di (datetime) – sub-simulation start date.

  • df (datetime) – sub-simulation end date.

  • mode (str) – 'fwd' (adjoint is a no-op for diagmet).

  • runsubdir (str) – unused.

  • workdir (str) – unused.

  • onlyinit (bool) – unused.

  • **kwargs – forwarded to each utility function.

pycif.plugins.transforms.complex.diagmet.propagate_incompatible.propagate_incompatible_domain(self, trans_mapper, trid_in, mode='backward')[source]#

Assign the correct domain to a diagmet input tracer.

2-D (surface) and 3-D (column) meteorological fields use different domain objects. This function inspects the output domains already present in the mapper, selects the appropriate 2-D or 3-D domain for trid_in, and assigns it.

Parameters:

  • self (Plugin) – diagmet plugin instance (carries meteo_parameters_2d_in listing 2-D field names).

  • trans_mapper (dict) – transform mapper; 'inputs'[trid_in]["domain"] is set in-place.

  • trid_in (tuple) – ('meteo', parameter_name) key of the input tracer whose domain should be resolved.

  • mode (str) – propagation direction (unused; kept for API consistency).

Raises:

Exception – if multiple distinct 3-D or 2-D domains are found in the output mapper (should not occur in a well-formed configuration).

pycif.plugins.transforms.complex.diagmet.utils.altipres.altipres(transf, inout_datastore, ddi, mapper)[source]#

Compute mid-layer pressures, altitudes, and air density.

Derives:

  • pres_mid (Pa) — pressure at the middle of each model layer, stored in transf.diag_misc['pres'] for use by downstream steps.

  • alti (m) — cumulative layer thickness above the surface, output as ('meteo', 'alti').

  • airm (molecules cm⁻³) — air number density, output as ('meteo', 'airm') using \(n = 7.29 \times 10^{16} \cdot P/T\).

  • oro (m) — orography from geopotential (divided by g = 9.81), output as ('meteo', 'oro').

See DIAGMET meteorological pre-processing (section 1) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper (provides domain sigma coefficients via mapper["inputs"][("meteo", "winz")]["domain"]).

pycif.plugins.transforms.complex.diagmet.utils.boundary_layer_height.boundary_layer_height(transf, inout_datastore, ddi, mapper)[source]#

Interpolate the virtual potential temperature to a fixed 25 m reference height.

Note

Despite its name (inherited from the historical diagmet.f90), this step does not compute the PBL height: CHIMERE reuses the ECMWF boundary layer height (hght) directly, passed through unchanged elsewhere in the transform. It only linearly interpolates the virtual potential temperature po (computed by friction_velocity()) to \(z_\mathrm{therm}=25\) m, storing the result as potts for obukov_length().

See DIAGMET meteorological pre-processing (section 7) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.checkcfl.checkcfl(transf, inout_datastore, ddi, mapper)[source]#

Check and enforce CFL stability: limit wind speeds so that the Courant number stays below 1.

Sets the number of CHIMERE physical time steps per hour (nphourm) so that the horizontal Courant number stays below 0.5 everywhere in the domain, given the grid-cell sizes (great-circle distance between corners) and the strongest horizontal winds. The vertical CFL contribution is not implemented (no explicit vertical wind is available from ECMWF). See DIAGMET meteorological pre-processing (section 8) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.cloud_optical_thickness.cloud_optical_thickness(transf, inout_datastore, ddi, mapper)[source]#

Compute cloud optical thickness for low, medium, and high cloud layers.

Combines fixed reference optical depths for low/medium/high cloud layers, scaled by the ECMWF cloud-cover fraction of each layer, into a broadband cloud attenuation factor (atte). Only the “read cloud cover fraction” option is currently implemented; the liquid/ice-water-path and relative-humidity-based options are not yet ported from the original diagmet.f90. See DIAGMET meteorological pre-processing (section 14) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.convection.convection(transf, inout_datastore, ddi, mapper)[source]#

Compute convective mass fluxes (up-draught and down-draught) for CHIMERE.

Passes through the ECMWF updraught/downdraught detrainment profiles (dpdu, dpdd, clipped to non-negative values) and recovers the corresponding entrainment profiles (dpeu, dped) as the level-to-level convergence of the mass flux plus the detrainment term. All four outputs are zero when deep_convection is disabled. See DIAGMET meteorological pre-processing (section 12) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.defcolumn.defcolumn(transf, inout_datastore, ddi, mapper)[source]#

Interpolate 3-D fields to the surface and compute column-integrated quantities.

Prepends a synthetic surface level (index 0) to every 3-D field (pressure, specific humidity, total condensed water, temperature, winds) by linear extrapolation from the two lowest model levels, using the 2 m temperature for the temperature extrapolation. All downstream diagmet steps operate on this augmented column. See DIAGMET meteorological pre-processing (section 2) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.friction_velocity.friction_velocity(transf, inout_datastore, ddi, mapper)[source]#

Compute friction velocity u* using the Louis (1982) stability function.

Only run when usta: recompute (the default); otherwise \(u_*\) is read directly from ECMWF. Builds a bulk Richardson number between the surface and 10 m from virtual potential temperature and wind speed, applies the Louis (1982) stability correction to the neutral drag coefficient, and combines the mechanical and convective (wstar0, see sv_heat_flux()) contributions. See DIAGMET meteorological pre-processing (section 6) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.low_cloud_top.low_cloud_top(transf, inout_datastore, ddi, mapper)[source]#

Compute the top pressure of the low cloud layer from relative humidity and temperature.

Relative humidity is derived at every level from the Tetens saturation vapour pressure formula. Outputs the surface relative humidity (sreh) and stores a below-1000 m maximum relative humidity (rhmaxx, clipped to \([0.90, 1]\)) in transf.diag_misc for use by vertical_turbulent_diffusivity(). See DIAGMET meteorological pre-processing (section 9) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.mean_z0_shf_extra_urban_temp.mean_z0_shf_extra_urban_temp(transf, inout_datastore, ddi, mapper)[source]#

Apply urban heat island corrections to roughness length, sensible heat flux, and 2-m temperature.

Combines the LANDUSE land-cover fractions and the monthly LANDPAR roughness lengths into four grid-cell diagnostics — urban wind-reduction factor awf, area-weighted roughness length az0, additional urban heat-flux fraction auf, and urban-corrected minimum PBL height pm — stored in transf.diag_misc for use by later steps, and applies awf to the lowest-level winds. See DIAGMET meteorological pre-processing (section 4) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.obukov_length.obukov_length(transf, inout_datastore, ddi, mapper)[source]#

Compute the Obukhov length L from sensible heat flux and friction velocity.

Derives the Obukhov length obuk, aerodynamic resistance aerr (integrated Monin-Obukhov flux-profile relationships, stable or unstable), and convective velocity scale wsta from the near-surface potential temperature (potts), virtual heat flux (potf/potfm), friction velocity, and roughness length. See DIAGMET meteorological pre-processing (section 10) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.precipitations.precipitations(transf, inout_datastore, ddi, mapper)[source]#

Compute total precipitation as the sum of convective and large-scale components.

Outputs ('meteo', 'topc') = convective precipitation (copc) + large-scale precipitation (lspc).

See DIAGMET meteorological pre-processing (section 13) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper (unused).

pycif.plugins.transforms.complex.diagmet.utils.sv_heat_flux.sv_heat_flux(transf, inout_datastore, ddi, mapper)[source]#

Compute sensible and virtual heat fluxes from surface temperature and humidity fields.

Derives the surface virtual potential-temperature flux potf from the ECMWF accumulated sensible/latent heat fluxes, and a convective velocity scale wstar0 from potf using a fixed convective height scale of 1500 m. Both are stored in transf.diag_misc for use by friction_velocity() and obukov_length(). See DIAGMET meteorological pre-processing (section 5) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.uv_rotation.uv_rotation(transf, inout_datastore, ddi, mapper)[source]#

Rotate u/v wind components from the meteorological (lat/lon) grid to the model grid.

The local grid-cell orientation \((\cos\theta, \sin\theta)\) is derived from the geographic coordinates of the grid-cell corners, and winds are rotated as \(u' = \cos\theta\, u - \sin\theta\, v\), \(v' = \sin\theta\, u + \cos\theta\, v\). See DIAGMET meteorological pre-processing (section 3) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.

pycif.plugins.transforms.complex.diagmet.utils.vertical_turbulent_diffusivity.vertical_turbulent_diffusivity(transf, inout_datastore, ddi, mapper)[source]#

Compute the vertical turbulent diffusivity Kzz at CHIMERE layer interfaces.

Inside the PBL, uses an O’Brien-type parabolic profile scaled by a convective velocity that depends on stability, with a minimum diffusivity enhanced in cloudy layers (using rhmaxx from low_cloud_top()). Above the PBL, uses a mixing-length closure with a moist-corrected gradient Richardson number and the Louis (1982) stability correction. See DIAGMET meteorological pre-processing (section 11) for the full derivation.

Parameters:

  • transf (Plugin) – diagmet transform instance.

  • inout_datastore (dict) – mutable datastore.

  • ddi (datetime) – current sub-simulation date.

  • mapper (dict) – transform mapper.