SpeedyWeather.jl

SpeedyWeather.jl

SpeedyWeather.jl is a global atmospheric model developed as a research playground with an everything-flexible attitude as long as it is speedy. Technically it is a climate model with simple, yet interactive representations of ocean, land and sea-ice. It is fast on CPU and GPU, easy to use and easy to extend, making atmospheric modelling an interactive experience – in the terminal, in a notebook or conventionally through scripts. With minimal code redundancies, it supports

Dynamics and physics

• Different physical equations (barotropic vorticity, shallow water, primitive equations, with and without humidity)
• Particle and tracer advection in 2D/3D for all equations
• Physics parameterizations for convection, precipitation, boundary layer, radiation, etc.
• Parameterizations can be easily changed and customized using modular fused GPU kernels
• Various more or less realistic planets and what-if scenarios by easily modifying initial and boundary conditions
• A slab ocean and thermodynamic sea ice model
• A 2-layer land bucket model with soil temperature, moisture, vegetation and snow

Numerics and computing

• Different spatial grids (full and octahedral, Gaussian and Clenshaw-Curtis, HEALPix, OctaHEALPix)
• Different resolutions (for example T16 to T1024 in spectral matched flexibly with various 800km to 10km grids)
• Different arithmetics: Float32 (default), Float64, and (experimental) BFloat16, stochastic rounding
• Fast on single CPUs (x86, arm) for laptop prototyping, live demos and education
• GPU acceleration (typically 5-50x faster) on Nvidia and AMD GPUs (Metal is WIP)
• Automatic differentiation via Enzyme.jl for sensitivity analysis, parameter calibration and ML-physics hybrid modelling (limited to Julia 1.10 currently)
• A very fast and flexible spherical harmonics transform library SpeedyTransforms.jl for CPU and GPU

User interface

• Data visualisation: 2D, 3D, interactive (you can zoom and rotate!) powered by Makie, Browzarr or Octant
• Extensibility: New model components (incl. parameterizations) can be externally defined
• Modularity: Models are constructed from its components, non-defaults are passed on as argument
• Interactivity: SpeedyWeather.jl runs in a notebook or in the REPL as well as from scripts
• Callbacks can be used to inject any piece of code after every time step, e.g. custom output, event handling, changing the model while it’s running

and Julia will compile to these choices just-in-time.

For an overview of the functionality and explanation see the documentation. You are always encouraged to raise an issue (even it is not actually an issue but an idea, a suggestion or really anything) describing what you’d like to use SpeedyWeather for. We’re keen to help!

Vision and roadmap

Why another model? You may ask. We believe that most currently available are stiff, difficult to use and extend, and therefore slow down research whereas a modern code in a modern language wouldn’t have to. We decided to use Julia because it combines the best of Fortran and Python: Within a single language we can interactively run SpeedyWeather on big GPUs but also extend it, inspect its components, evaluate individual terms of the equations, and analyse and visualise output on the fly.

We do not necessarily aim to make SpeedyWeather an atmospheric model for the purpose of production-ready weather forecasting, at least not at the cost of our current level of interactivity and ease of use or extensibility. It is more build with a climate application scope in mind and with a focus on research and education. New parameterizations of atmospheric processes can be very complicated and computationally expensive, and we are happy to provide a general interface to enable and support such extensions. These can even be developed as their own independent projects in separate repositories thanks to the modular structure of SpeedyWeather. Since SpeedyWeather follows an “easy and fast by default” philosophy, these complex extensions may not be used by default though. We would nevertheless appreciate such efforts since we aim for SpeedyWeather to enable a “hierarchy of models” spanning multiple levels process and computational complexity and runnable on hardware ranging from a single laptop to a large HPC cluster. It is important, however, that SpeedyWeather’s defaults be balanced: physically accurate yet fast enough to run on a laptop; comprehensive enough to simulate realistic weather yet understandable for newcomers; holistic enough to provide an easy-to-use interface yet modular enough to allow for extensive customization.

Finding a good balance is difficult, but we try our best.

Despite our commitment to simplicity and ease-of-use, many more physical processes and other features are continuing to be developed. On our TODO list are

• Radiation depending on greenhouse gas concentrations to represent climate change
• Better cloud parameterizations + aerosols
• Exoplanet support with more flexibility on the atmospheric composition
• 3D particle advection
• Semi-Lagrangian tracer advection
• Hybrid sigma-pressure vertical coordinates
• 3rd and 4th order time stepping (Lorenz N-Cycle scheme)
• Interactive visualisations on native HEALPix/OctaHEALPix grids

Currently in development, but already (partially) available are

• Better CPU multi-threading support
• MLIR/OpenXLA compilation with Reactant

Contributing

Open-source lives from large teams of (even occasional) contributors. If you are interested to fix something, implement something, or just use it and provide feedback you are always welcome. We are more than happy to guide you, especially when you don’t know where to start. We can point you to the respective code, highlight how everything is connected and tell you about dos and don’ts. Just express your interest to contribute and we’ll be happy to have you.

Example use

For a more comprehensive tutorial with several examples, see Examples in the documentation. The basic interface to SpeedyWeather.jl consist of 4 steps: define the grid, construct the model, initialize, run

spectral_grid = SpectralGrid(truncation=32, nlayers=8)  # define resolution
model = PrimitiveWetModel(spectral_grid)                # construct model
simulation = initialize!(model)                         # initialize all model components
run!(simulation, period=Day(10), output=true)           # aaaand action!

showing

 run_0001 100% Time: 0:00:01 (2000-01-11, 1395.22 years/day,  90 m/s, [ -80,   35] ˚C)

Hurray🥳 In a second we just simulated 10 days of the Earth’s atmosphere at a speed of almost 1400 simulated years per wallclock day. Also printed is the model time, the maximum wind speed and the temperature range (on any layer). This simulation used a T31 spectral resolution on an octahedral Gaussian grid (~400km resolution) solving the primitive equations on 8 vertical layers, storing NetCDF output.

More examples in the How to run SpeedyWeather section of the documentation.

Interactive use

You can use SpeedyWeather from the Julia REPL, running a script like julia speedyweather.jl, or interactively through Jupyter (install a Julia kernel with IJulia) or Pluto notebooks. Here an example for a Pluto notebook, changing interactively resolution and switching off convection and surface humidity fluxes, automatically updating a plot of near-surface humidity

(Note that in SpeedyWeather v0.19 the variable paths have changed so the respective line now needs to be written as q = get_step(simulation.variables.grid.humidity)[:, end])

Gallery

Specific humidity in the primitive equation model simulated at T340 spectral resolution (about 40km) with 16 vertical levels (shown here is level 15, just above the surface) on the octahedral Gaussian grid computed in single precision multi-threaded on 16 CPUs. With convection, large-scale condensation, surface fluxes and some simplified radiation (the daily cycle is visible)

https://github.com/SpeedyWeather/SpeedyWeather.jl/assets/25530332/614f04cf-5080-4c89-9fd6-35efd54103a7

Relative vorticity in the shallow water model, simulated at T1023 spectral resolution (about 10km) on an octahedral Clenshaw-Curtis grid with more than 4 million grid points

https://user-images.githubusercontent.com/25530332/190443050-d5b8d093-86c0-46c9-b515-8420059ac8dc.mp4

Surface temperature in the primitive equation model without surface fluxes or radiation at T511 (~20km resolution) and 31 vertical levels. The simulation was multi-threaded in Float32 (single precision).

https://github.com/SpeedyWeather/SpeedyWeather.jl/assets/25530332/95897b82-9b81-4980-934b-cfdcf4d5a4b0

SpeedyWeather.jl can also solve the 2D barotropic vorticity equations on the sphere. Here, we use Float32 (single precision) at a resolution of T340 (40km) on an octahedral Gaussian grid. Forcing is a stochastic stirring on northern hemisphere mid-latitudes following Barnes and Hartmann, 2011. Map projection is orthographic centred on the north pole.

https://github.com/SpeedyWeather/SpeedyWeather.jl/assets/25530332/3d7fccd5-b66d-42e3-9f73-64dcf21d00ee

Here, SpeedyWeather.jl simulates atmospheric gravity waves, initialised randomly interacting with orography over a period of 2 days. Each frame is one time step, solved with a centred semi-implicit scheme that resolves gravity waves with a timestep of CFL=1.2-1.4 despite a single-stage RAW-filtered leapfrog integration.

https://github.com/SpeedyWeather/SpeedyWeather.jl/assets/25530332/510c38c7-12cb-42d5-b905-c66b4eaa514d

Advection of 5000 particles with wind in the lower-most layer of the primitive equation model at T85 (150km) resolution and 8 vertical layers.

https://github.com/SpeedyWeather/SpeedyWeather.jl/assets/25530332/a6192374-24d9-4065-9fcc-8b719190472f

Data visualisation

Difficult to plot spherical data? SpeedyWeather also includes extensions for Makie and GeoMakie making it supereasy to create plots and interactively investigate a variables from a simulation. Two examples, a variable from a simulation

https://github.com/user-attachments/assets/543cddf8-bcd9-41a7-83e3-184dba994069

or visualising cell centres and faces of the HEALPixGrid via our globe function

https://github.com/user-attachments/assets/fa0636e3-30d7-4fbe-af29-dba047e8bded

History

SpeedyWeather.jl started off as a reinvention of the atmospheric general circulation model SPEEDY in Julia. SpeedyWeather has a different philosophy except for the simplicty of some parameterizations and many features have been added or changed so that only some of the numerical schemes share similarities, but so do many global spectral models. Fortran SPEEDY’s dynamical core has an obscure history: Large parts were written by Isaac Held at GFDL in/before the 90ies with an unknown amount of contributions/modifications from Steve Jewson (Oxford) in the 90ies. The physical parametrizations were then added by Franco Molteni, Fred Kucharski, and Martin P. King afterwards while the model was still written in Fortran77. Around 2018-19, SPEEDY was then translated to Fortran90 by Sam Hatfield in speedy.f90. SpeedyWeather.jl is then adopted from first translations to Julia by Sam Hatfield. All these past creators and contributors are strongly acknowledged. Thank you for letting us use your efforts to create intermediate-complexity climate models as a conceptual launchpad for SpeedyWeather!

Submodules

SpeedyWeather.jl defines several modules that are part of this repository, but also available to be used and installed as stand-alone packages:

• RingGrids, a module that defines several iso-latitude ring-based spherical grids (like the FullGaussianGrid or the HEALPixGrid) and interpolations between them
• LowerTriangularArrays, a module that defines LowerTriangularMatrix used for the spherical harmonic coefficients
• SpeedyTransforms, a module that defines the spherical harmonic transform between spectral space (for which LowerTriangularArrays is used) and grid-point space (as defined by RingGrids).

These modules can also be used independently of SpeedyWeather. They are registered, so just install and use them as every other package, e.g:

(@v1.11) pkg> add RingGrids
julia> using RingGrids

check out their documentation: RingGrids, LowerTriangularArrays, SpeedyTransforms.

Installation

SpeedyWeather.jl is registered in Julia’s registry, so open the package manager with ] and

(@v1.11) pkg> add SpeedyWeather

which will install the latest release and all dependencies automatically. For more information see the Installation in the documentation. Please use the current minor version of Julia, compatibilities with older versions are not guaranteed.

Benchmarks

The primitive equations at 400km resolution with 8 vertical layers can be simulated by SpeedyWeather.jl at 2300 simulated years per day (SYPD) on a single core of newer CPUs with arm architecture (M4 MacBooks in this case). At that speed, simulating one year takes about 40 seconds without output. The complex fused-multiply adds of the spectral transform compile efficiently to the large vector extensions of the newer arm chips in single precision. Another considerable speed-up comes from the reduced grids minimizing the number of columns for which expensive parameterizations like convection have to be computed. The parameterizations take up 40-60% of the total simulation time, depending on the grid. Particularly the OctaminimalGaussianGrid, OctaHEALPixGrid and the HEALPixGrid are increasingly faster, at a small accuracy sacrifice of the then inexact spectral transforms.

On older CPUs, like the Intel CPU MacBooks, the speed drops to about 500-600 SYPD, which is still 2x faster than Fortran SPEEDY which is reported to reach 240 SYPD. With GPU support being a work in progress we do not expect a performance increase for the lower resolutions but aim to provide the ability to also run the model very efficiently at high resolution!

For an overview of typical simulation speeds a user can expect under different model setups see Benchmarks.

Citing

If you use SpeedyWeather.jl in research, teaching, or other activities, we would be grateful if you could mention SpeedyWeather.jl and cite our paper in JOSS:

Klöwer et al., (2024). SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility. Journal of Open Source Software, 9(98), 6323, doi:10.21105/joss.06323.

The bibtex entry for the paper is:

@article{SpeedyWeatherJOSS,
    doi = {10.21105/joss.06323},
    url = {https://doi.org/10.21105/joss.06323},
    year = {2024},
    publisher = {The Open Journal},
    volume = {9},
    number = {98},
    pages = {6323},
    author = {Milan Klöwer and Maximilian Gelbrecht and Daisuke Hotta and Justin Willmert and Simone Silvestri and Gregory L. Wagner and Alistair White and Sam Hatfield and Tom Kimpson and Navid C. Constantinou and Chris Hill},
    title = {{SpeedyWeather.jl: Reinventing atmospheric general circulation models towards interactivity and extensibility}},
    journal = {Journal of Open Source Software}
}

If you are using the differentiability of our model, please cite additionally

Moses, W. S., Cheng, G., Churavy, V., Gelbrecht, M., Klöwer, M., Kump, J., et al. (2026). DJ4Earth: Differentiable, and performance-portable Earth system modeling via program transformations. Journal of Advances in Modeling Earth Systems, 18, e2025MS005615. https://doi.org/10.1029/2025MS005615

with the bibtex entry

@article{DJ4EarthJAMES,
    author = {Moses, William S. and Cheng, Gong and Churavy, Valentin and Gelbrecht, Maximilian and Klöwer, Milan and Kump, Joseph and Morlighem, Mathieu and Williamson, Sarah and Apte, Dhruv and Berg, Paul and Giordano, Mosè and Hill, Christopher and Loose, Nora and Montoison, Alexis and Narayanan, Sri Hari Krishna and Pal, Avik and Schanen, Michel and Silvestri, Simone and Wagner, Greg and Heimbach, Patrick},
    title = {{DJ4Earth}: Differentiable, and Performance-Portable Earth System Modeling via Program Transformations},
    journal = {Journal of Advances in Modeling Earth Systems},
    volume = {18},
    number = {5},
    pages = {e2025MS005615},
    keywords = {DJ4Earth, reverse-mode automatic differentiation, Earth system modeling, online learning, differentiable programming, hybrid data assimilation/machine learning},
    doi = {https://doi.org/10.1029/2025MS005615},
    url = {https://agupubs.onlinelibrary.wiley.com/doi/abs/10.1029/2025MS005615},
    eprint = {https://agupubs.onlinelibrary.wiley.com/doi/pdf/10.1029/2025MS005615},
    note = {e2025MS005615 2025MS005615},
    year = {2026}
}

Copyright and license

Copyright © 2020 Milan Klöwer for SpeedyWeather.jl
Copyright © 2021 The SpeedyWeather.jl Contributors for SpeedyWeather.jl
Copyright © 2022 Fred Kucharski and Franco Molteni for SPEEDY parametrization schemes

Software licensed under the EUPL-1.2 license.