climt 0.31.0

Installation

Note - The GFS dynamical core has been made into a seperate package called gfs_dynamical_core for ease of maintenance. If you need the dynamical core, please install this package from source or directly using pip. Doing this will automatically install climt as well.

pip install gfs_dynamical_core

climt can be installed directly from the python package index using pip.

pip install climt

should work on most systems. From version 0.9.2 onwards, this command will install binary wheels, eliminating the requirement of a compiler on your system.

Detailed instructions for Mac and Linux systems are available in the documentation.

Features

• climt is fully units-aware!

• Uses the xarray DataArray abstraction to build self describing model arrays.

• Provides different levels of abstraction towards building a climate model.

• Like sympl, climt consciously uses descriptive names in the user API to ensure model scripts are self-documenting.

• Allows for quick prototyping of earth system model components.

• Provides a clean and convenient interface to add new components.

Citing climt

If you use climt in your research, please cite the following paper documenting sympl and climt

https://www.geosci-model-dev.net/11/3781/2018/

Credits

This package was created with Cookiecutter and the audreyr/cookiecutter-pypackage project template.

v.0.31.0

• New docs section — A Modelling Tour of the Climate System (docs/modelling-tour/), six in-browser pages supplying the computational half of the EC2213 course notes. Each page prescribes a profile and asks CORK’s per-band diagnostics what it makes of it — the OLR spectrum behind a single emissivity, the window’s real width, the weighting function and its per-band radiating levels, the analytic gray solution validated and then broken, the forcing per CO₂ doubling, and the water vapour feedback with the runaway limit. No time integration anywhere: single component calls and parameter sweeps only. The pages’ computational core lives in importable Python under docs/modelling-tour/_tour/ and is exercised natively by tests/test_modelling_tour.py — on both the 56-band table pages 1-3 run on and the shipped 14-band fallback — so nothing on a page is unguarded by a test.

• Fix — the live RCE walkthrough (docs/radiative-transfer/09-live-rce.qmd) now draws its profiles on a logarithmic pressure axis. On the linear axis the entire upper atmosphere was crushed into the top sliver of the panel, so the skin temperature the surrounding text discusses was not actually visible; the text also claimed an isothermal top for the non-grey column, which keeps cooling to the model lid, and now says so.

• New feature — CorkLongwaveRadiation takes a diffusivity_factor constructor argument, so the two-stream diffusivity D in trans = exp(-D * tau) is settable per component. The default is unchanged at the Elsasser value 1.66; the EC2213 notes derive their equations with D = 2, which the gray-equilibrium page needs to reproduce them exactly. The default also lives on the class, so a component pickled under an earlier climt still resolves it after unpickling here rather than raising AttributeError from array_call.

• New data — the tour_gray_lw correlated-k table: single band, constant k, calibrated at D = 2 to a diffusivity-scaled column optical depth of tau_inf = 4. scripts/generate_gray_default_table.py gains a --diffusivity flag (the calibration target is D * sum(k * m) == --total-optical-depth, so it must match the D the component runs with) and now resolves --output by full path rather than by basename, so it can write outside the package data directory.

• Performance — load_k_table now materialises .npz correlated-k tables into a plain dict instead of returning numpy’s lazy NpzFile. An NpzFile re-inflates the requested array out of the zip archive on every __getitem__, and the CORK components index the table several times per call, so table decompression dominated every radiation step (~15 ms per k_coefficients read for earth_low_res_lw). Measured on one reference machine at nz=18, single column: CorkLongwaveRadiation 57.4 -> 3.6 ms/call with numba and 89.5 -> 36.8 ms/call with NUMBA_DISABLE_JIT=1 (the Pyodide/browser path); CorkShortwaveRadiation 12.2 -> 5.0 ms/call. Outputs are bitwise unchanged. The cost moves to a one-time ~18 ms at load, and the loaded table now holds every array in memory (~3 MB for earth_low_res_lw). .nc tables already returned a dict, so both backends are now consistent; the reads also happen inside the importlib_resources as_file block, which fixes a latent failure for zipped installs where the extracted temp file is removed on block exit.

v.0.30.0

• Behaviour change — BucketHydrology surface fluxes were missing their air-density factors and are now dimensionally correct. The bulk formulae are built from one evaporative mass flux E = beta * rho * c_D * U * (q_s - q_a), with rho the density at the lowest model level from the ideal gas law. Consequences:

  • surface_upward_sensible_heat_flux gains rho * c_p and is about 1200x larger (it was ~0.05 W m^-2 where tens of W m^-2 are physical).

  • surface_upward_latent_heat_flux gains rho and is about 1.2x larger.

  • evaporation_rate, declared m s^-1, is now the liquid-water-equivalent depth rate E / rho_water and is about 830x smaller. Previously it returned metres per day rather than millimetres per day, draining the default 0.15 m bucket in roughly 90 minutes.

  Soil-moisture and surface-temperature evolution therefore change for any run with non-zero wind. air_pressure ([mid_levels, *], Pa) is a new required input. The cached regression outputs are unaffected because their default state has zero wind, which zeroed both fluxes regardless; tests/test_bucket_fluxes.py now covers the flux magnitudes directly.

• climt now publishes a pure-Python wheel (py3-none-any) to PyPI alongside the compiled platform wheels. It carries no Fortran/Cython extensions, so the components that need them raise a clear error on use (climt.has_fortran_extensions() reports availability), but the rest of the package — including the CORK correlated-k radiation scheme — works anywhere Python runs, including in the browser under Pyodide. pip continues to prefer the compiled wheel wherever one is published for your platform.

• Windows binaries are no longer built, tested or published. The Windows CI job and the Windows release job (which uploaded a separate mingw-built wheel to PyPI) have both been removed. Windows users now install the pure-Python wheel described above: it needs no compiler, but the Fortran-backed components raise on use — check with climt.has_fortran_extensions(). Building from source on Windows may still work but is unsupported; WSL is the recommended route for the compiled components. Linux (x86_64) and macOS (Apple silicon) compiled wheels are unaffected.

• New land-surface physics: BucketHydrology gains an optional two-layer (deep + shallow) mode via num_layers=2, adding deep_soil_moisture_content / deep_soil_temperature stores and runoff_rate diagnostics. The num_layers=1 default is unchanged (bit-for-bit). A stray hardcoded soil-moisture clamp that ignored the configured soil_moisture_max was also fixed.

• New component SecondBEST: a modular, intermediate-complexity BEST land-surface model built as a thin Stepper orchestrator over five swappable process objects (SoilProperties, SurfaceAlbedo, SurfaceLayer, SurfaceFluxes, SubsurfaceTransport), each with a Best* default. Adds a soil vertical grid, soil-profile state quantities, and registers the von_karman_constant. SecondBEST also emits stability-consistent screen-level diagnostics on land columns (air_temperature_at_2m, specific_humidity_at_2m, eastward_wind_at_10m, northward_wind_at_10m), interpolated between the surface and the lowest model level using the surface layer’s own stability profile.

• New components for ocean/ice surface physics: LandMask, SeaIce, LandIce and DataOcean, plus a slab-ocean q-flux (prescribed ocean_heat_transport_convergence) and optional Ekman heat-transport convergence in SlabSurface (include_ekman).

• SlabSurface: when include_ekman=True, the ocean_heat_transport_convergence diagnostic now reports the TOTAL ocean heat-transport convergence actually applied to sea cells (prescribed q-flux + Ekman), not just the prescribed input. The Ekman-only breakdown is still available separately as ekman_heat_transport_convergence. With the default include_ekman=False, Ekman is zero and this diagnostic is unchanged from prior releases.

• Deprecated: IceSheet is deprecated in favor of the new SeaIce (owns area_type == "sea_ice") and LandIce (owns area_type in ("land", "land_ice")) components. IceSheet is now a thin dispatching shim over SeaIce/LandIce kept only for backward compatibility, and emits a DeprecationWarning on construction. Its numerical output is not bit-for-bit identical to the old monolith, even with default arguments, because SeaIce/LandIce carry deliberate defect fixes:

  • The basal boundary condition changed from a hardcoded freezing Dirichlet condition to a prescribed ocean-heat-flux Flux (Neumann) condition (heat_flux_into_sea_water_due_to_sea_ice).

  • Sea-ice thickness is now clamped to be non-negative.

  • Surface albedo is now configurable rather than hardcoded.

  • The surface_downward_heat_flux_in_sea_ice diagnostic is now produced only by the internal SeaIce instance, so it reads as the registered default of 0.0 on land/land_ice columns (previously computed uniformly across sea_ice, land_ice and land columns by the old monolith).

  • Columns with area_type == "sea" (owned by neither SeaIce nor LandIce) now pass surface_temperature straight through from the input instead of taking either sub-component’s internally derived proxy value.

  Existing users of IceSheet should migrate to SeaIce and LandIce directly; see their docstrings for further detail on each fix.

v.0.17.0

• Removed dycore to move it to independent package

v.0.16.15

• Move to Github Actions tentatively finished!

v.0.16.11

• New component BucketHydrology that implements Manabe first generation land model

• BucketHydrology calculates the sensible and latent heat flux within the component

• Conservation test for the component also added

• Moving CI to Github Actions

v.0.16.8

• Fix timeout for all MAC builds

v.0.16.6

• Prevent MAC OS builds from timing out

v.0.16.5

• Fix formatting errors which prevent pypi deployment

v.0.16.4

• Fix MCICA for the shortwave component of RRTMG

• Revise random number generation for MCICA

• Improvement of the user interface to control MCICA

v.0.16.3

• update numpy requirement to avoid binary incompatibility error

• Fix error in documentation

v.0.16.2

• Fix wheel build on Mac

v.0.16.1

• Fixed issue with Mac build

• Few changes in the dry convection component. Significantly improves the performance.

• Changed logo!

• Fixed failing docs build

v0.16.0

• Added some documentation for using RRTMG with McICA

• CI Testing for Mac and py37 added.

• Refactored initialisation code

• Enable the McICA version of RRTMG Longwave for consistency with the Shortwave component.

• Fix bugs in IceSheet

• Add tests to verify conservation of quantities

• Fix bugs in initialisation

• Fix energy conservation in surface flux scheme

• Enable the McICA version of RRTMG Shortwave, so that partial cloud fractions can be used.

• Add GMD example scripts to repository.

• Fix docs to reflect API changes after refactor.

• Fix wrong initialisation to use sigma values instead of pressure values of optical depth for GrayLongwaveRadiation

Breaking Changes

• The flux outputs of GrayLongwaveRadiation have been renamed to eliminate on_interface_levels to keep consistency with other components.

• All arrays are now 3/2d by default based on their expected dimensions.

• horizontal dimensions are now lon, lat, but inputs used by components remain the same (latitude, longitude).

v.0.14.8

Many of the changes in this version come from changes in Sympl 0.4.0. We recommend reading those changes in the Sympl documentation.

• Updated component APIs to work with Sympl 0.4.0

• Many components which previously required horizontal dimensions now use wildcard matches for column dimensions.

• Switched many print statements to logging calls.

• Fixed bugs in some components

Breaking Changes

• get_constant and set_constant have been removed, use the ones in Sympl.

• Emanuel convection scheme can no longer be set to perform dry adiabatic adjustment to the boundary layer. This has been implemented in a separate component.

• ClimtPrognostic, ClimtImplicitPrognostic, ClimtDiagnostic, ClimtImplicit have been removed. Use the base types in Sympl.

• State initialization has been entirely re-worked. get_default_state now takes in an optional grid state instead of options to do with the state grid. A function get_grid is provided which can create a grid state, or one can be created manually. A grid state is a state containing air pressure and sigma on mid and interface levels, as well as surface pressure.

• Replaced references to “thermal_capacity” with references to “heat_capacity” in component quantity names.

v.0.14.7

• Fix issue with pip v10 and pandas 0.22 conflicts

v.0.14.3

• Fix release issue because of pip API change

v.0.14.1

• Fix appveyor fail due to pip changes

v.0.14.0

• Fixed broken version numbers

v.0.12.0

• new release to fix version numbers and create zenodo ID

v.0.9.4

• Added attributes to inputs/outputs/ etc., to work with ScalingWrapper Added tests as well.

• Added tests for constants functions

• Fixed requirements to ensure this version of climt installs the correct versions of sympl and numpy.

v.0.9.3

• Released because of a labelling issue. See 0.9.2 for details.

v.0.9.2

• Updated documentation

• Cleaned up examples

• Added (*)_properties as a property to all components

• The gas constant for dry air in the Emanuel scheme is now renamed _Rdair

• RRTMG LW and SW are now OpenMP parallel

• Added Instellation component to calculate zenith angle

• Added tests to increase coverage

• New constants handling functionality added

• Travis builds now use stages

• Appveyor CI up and running

• Pre-installation of cython and numpy no longer necessary for source builds

• Added snow-ice component

• Ozone profiles do not need to be specified externally

• Now also tested on Python 3.6

Breaking Changes

• API for constants setting changed to set_constant_from_dict and add_constants_from_dict

• GfsDynamicalCore renamed to GFSDynamicalCore for consistency

• get_prognostic_version method of ClimtImplicit renamed to prognostic_version, and no longer accepts timestep as an argument. The current timestep should be set in ClimtImplicit.current_time_step during each iteration.

• RRTMGShortwave now uses sympl’s solar constant by default instead of from fortran.

v.0.9.1

• Held-Suarez and moist GCM with grey radiation work!

• Added DCMIP initial conditions, test 4 tried out.

• Dynamical core integrated now.

• BIG change in the build system. Tests pass on Mac as well

• Arrays can now have arbitrary dtype (to use qualitative, string, quantities)

• Added Emanuel Convection, surface energy balance model and ice sheet energy balance

• 2D coordinates are now supported for horizontal coordinates

• Replaced create_output_arrays() with a more general get_state_dict_for() and get_numpy_arrays_from_state() combination.

• State arrays now have coordinates

• Updated documentation

• RTD finally working, phew!

• Added RRTMG Longwave, Simple Physics

• Added helper functions to reduce boilerplate code in components

Breaking Changes

Latest

• method to obtain piecewise constant prognostic has been renamed to piecewise_constant_version

• Ozone profile has been modified

• Heating rate for RRTMG top-of-atmosphere is no longer manually set to zero

• Components no longer accept constants during initialisation. All constant handling is done internally.

v.0.9

• SlabSurface no longer uses depth_slab_surface as input

• changed order of outputs of GfsDynamicalCore and SimplePhysics to conform to TimeStepper order of diagnostics, new_state

• get_default_state now accepts mid_levels and interface_levels instead of z to specify vertical coordinates.

• mass_to_volume_mixing_ratio now uses numpy arrays instead of DataArrays.