======= climlab

|docs| |JOSS| |DOI| |pypi| |Build Status| |coverage|

Python package for process-oriented climate modeling

Author

| Brian E. J. Rose | Department of Atmospheric and Environmental Sciences | University at Albany | brose@albany.edu

About climlab

climlab is a flexible engine for process-oriented climate modeling. It is based on a very general concept of a model as a collection of individual, interacting processes. climlab defines a base class called Process, which can contain an arbitrarily complex tree of sub-processes (each also some sub-class of Process). Every climate process (radiative, dynamical, physical, turbulent, convective, chemical, etc.) can be simulated as a stand-alone process model given appropriate input, or as a sub-process of a more complex model. New classes of model can easily be defined and run interactively by putting together an appropriate collection of sub-processes.

Currently, climlab has out-of-the-box support and documented examples for

• Radiative and radiative-convective column models, with various radiation schemes:
  • RRTMG (a widely used radiative transfer code)
  • CAM3 (from the NCAR GCM)
  • Grey Gas
  • Simplified band-averaged models (4 bands each in longwave and shortwave)
• Convection schemes:
  • Emanuel moist convection scheme
  • Frierson's Simplified Betts Miller scheme
  • Hard convective adjustment (to constant lapse rate or to moist adiabat)
• 1D Advection-Diffusion solvers
• Moist and dry Energy Balance Models
• Flexible insolation including:
  • Seasonal and annual-mean models
  • Arbitrary orbital parameters
• Boundary layer scheme including sensible and latent heat fluxes
• Arbitrary combinations of the above, for example:
  • 2D latitude-pressure models with radiation, horizontally-varying meridional diffusion, and fixed relative humidity

Installation

Installing pre-built binaries with conda (Mac OSX, OSX-ARM64, and Linux)

By far the simplest and recommended way to install ``climlab`` is using conda_
(which is the wonderful package manager that comes with `Anaconda Python`_).

You can install ``climlab`` and all its dependencies with::

    conda install -c conda-forge climlab

Or (recommended) add ``conda-forge`` to your conda channels with::

    conda config --add channels conda-forge

and then simply do::

    conda install climlab

Binaries are available for OSX and Linux. 
Some binaries for earlier versions are available for Windows but this is not currently supported.

Installing from source
~~~~~~~~~~~~~~~~~~~~~~
Consult the documentation_ for detailed instructions.

.. _conda: https://conda.io/docs/
.. _`Anaconda Python`: https://www.continuum.io/downloads
.. _`pypi repository`: https://pypi.python.org



Links
-----

-  HTML documentation: http://climlab.readthedocs.io/en/latest/intro.html
-  Issue tracker: http://github.com/climlab/climlab/issues
-  Source code: http://github.com/climlab/climlab
-  JOSS meta-paper: https://doi.org/10.21105/joss.00659


Dependencies
------------

These are handled automatically if you install with conda_.

Required
~~~~~~~~
- Python (currently testing on versions 3.10, 3.11, 3.12, 3.13)
- numpy
- scipy
- pooch (for remote data access and caching)
- xarray (for data handling)

Recommended for full functionality
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
- numba >=0.43.1 (used for acceleration of some components)

*Note that there is a bug in previous numba versions that caused a hanging condition in climlab under Python 3.*


Documentation and Examples
--------------------------
Full user manual is available here_.

A rich and up-to-date collection of example usage can be found in Brian Rose's online textbook
`The Climate Laboratory`_.

Source notebooks for the `tutorials in the docs`_ can be found in the ``climlab/docs/source/courseware/`` directory of the source repo.

These are self-describing, and should run out-of-the-box once the package is installed, e.g:

``jupyter notebook Insolation.ipynb``


Release history
---------------

Version 0.9.2 (released March 2025)
    Maintenance release bringing compatibility with Pandas 3.0 and some bug fixes.

Version 0.9.1 (released February 2025)
    Bug fix and clean up of the codebase. Some legacy code for former Python 2.7 support was removed (hasn't been tested or supported in a long time).

Version 0.9.0 (released February 2025)
    A major new release with significant new functionality and compatibility with the latest Python and Numpy versions. 
    New capabilities include

    - Full support for aerosols in RRTMG
    - New moist atmospheric physics
        - A new SimplifiedBettsMiller_ moist convection process following `Frierson (2007)`_
        - A simple LargeScaleCondensation_ process to represent condensation and precipitation from large-scale moisture convergence.
    - A new Limiter_ process that implements min/max bounds for state variables
    - Better consistency for internally generated diagnostics, including a new `additive assumption for same-named diagnostics`_ produced by multiple subprocesses.
    - Support for `multiple time-averaging methods for solar zenith angle`_, including more flexible support for zenith angle in RRTMG and CAM3 radiation processes.

    The compiled Fortran dependencies have also been updated, with some breaking changes to their interfaces.
    Thus climlab 0.9.0 requires `climlab-rrtmg`_ >= 0.4.1 and `climlab-cam3-radiation`_ >= 0.3. 
    conda_ will handle this for most users.
    
    This release also includes numerous documentation improvements, bug fixes, and support for Numpy 2 and Python 3.12 / 3.13.
    See the `release notes`_ and documentation_ for details.

Version 0.8.2 (released November 2023)
    New feature: process class `climlab.radiation.InstantInsolation()` which correctly interprets longitude, respects local solar time and calculates hour angle. 
    A utility function `climlab.solar.insolation.instant_insolation()` is also available, with usage mirroring the existing `climlab.solar.insolation.daily_insolation()`.
    Thanks to `@HenryDane <https://github.com/HenryDane>`_ for this contribution!

    This release also includes numerous bug fixes, updates for Python 3.11, and improvements to documentation and CI builds.

Version 0.8.1 (released May 2022)
    A major refactor of the internals: all the Fortran code has been moved into external companion
    packages `climlab-rrtmg`_, `climlab-cam3-radiation`_, and `climlab-emanuel-convection`_.
    Climlab is now (once again!) a pure Python package.
    Builds of these helper packages are available through conda-forge and will be
    automatically installed as dependencies by conda / mamba.

    The climlab source repo also moved to https://github.com/climlab/climlab

    There should be no breaking changes to the user-facing API.

    The major motivation for this change was to (vastly) simplify the development
    and testing of new-and-improved climlab internals (coming soon).

Version 0.7.13 (released February 2022)
    Maintenance release to support Python 3.10.

    The `attrdict package`_ by `Brendan Curran-Johnson`_ has been removed from the dependencies since it is broken on Python 3.10 and no longer under development.
    A modified version of the MIT-licensed attrdict source is now bundled internally with climlab. There are no changes to climlab's public API.

Version 0.7.12 (released May 2021)
    New feature: spectral output from RRTMG (accompanied by a new tutorial)

Version 0.7.11 (released May 2021)
    Improvements to data file download and caching (outsourcing this to `pooch`_)

Version 0.7.10 (released April 2021)
    Improvements to docs and build.

Version 0.7.9 (released December 2020)
    Bug fixes and doc improvements.

Version 0.7.8 (released December 2020)
    Bug fixes.

Version 0.7.7 (released October 2020)
    Bug fixes.

Version 0.7.6 (released January 2020)
    Bug fixes, Python 3.8 compatibility, improvements to build and docs.

Version 0.7.5 (released July 2019)
    Bug fixes and improvements to continuous integration

Version 0.7.4 (released June 2019)
    New flexible solver for 1D advection-diffusion processes on non-uniform grids, along with some bug fixes.

Version 0.7.3 (released April 2019)
    Bug fix and changes to continuous integration for Python 2.7 compatibility

Version 0.7.2 (released April 2019)
    Improvements to surface flux processes, a new data management strategy, and improved documentation.

    Details:
      - ``climlab.surface.LatentHeatFlux`` and ``climlab.surface.SensibleHeatFlux`` are now documented, more consistent with the climlab API, and have new optional ``resistance`` parameters to reduce the fluxes (e.g. for modeling stomatal resistance)
      - ``climlab.surface.LatentHeatFlux`` now produces the diagnostic ``evaporation`` in kg/m2/s. ``climlab.convection.EmanuelConvection`` produces ``precipitation`` in the same units.
      - The previous ``PRECIP`` diagnostic (mm/day) in ``climlab.convection.EmanuelConvection`` is removed. This is a BREAKING CHANGE.
      - Data files have been removed from the climlab source repository. All data is now accessible remotely. climlab will attempt to download and cache data files upon first use.
      - ``climlab.convection.ConvectiveAdjustement`` is now accelerated with ``numba`` if it is available (optional)

Version 0.7.1 (released January 2019)
    Deeper xarray integration, include one breaking change to ``climlab.solar.orbital.OrbitalTable``, Python 3.7 compatibility, and minor enhancements.

    Details:
      - Removed ``climlab.utils.attr_dict.AttrDict`` and replaced with AttrDict package (a new dependency)
      - Added ``xarray`` input and output capabilities for ``cl