diff --git a/docs/_quarto.yml b/docs/_quarto.yml index bd7623f..d77072d 100644 --- a/docs/_quarto.yml +++ b/docs/_quarto.yml @@ -50,6 +50,8 @@ website: logo: thumbnails/logo_beta_horiz_cropped.png logo-alt: "ClimateCritters" left: + - file: get-started/overview.qmd + text: Overview - file: get-started/installation.qmd text: Get Started - file: tutorials/index.qmd @@ -109,7 +111,7 @@ website: href: notebooks/model_demos/ebm0d.ipynb - text: "1D (latitude)" href: notebooks/model_demos/ebm1d_lat.ipynb - - section: Oscillators + - section: Pendulums and Springs contents: - text: "SimplePendulum & Spring" href: notebooks/model_demos/pendulums_and_spring.ipynb @@ -117,15 +119,15 @@ website: href: notebooks/model_demos/double_pendulum.ipynb - section: Climate contents: - - text: "ENSO" + - text: "ENSO recharge oscillator (Jin, 1996)" href: notebooks/model_demos/enso_recharge.ipynb - - text: "Ganopolski 2024, Model 3" + - text: " Pleistocene Ice Volume (Ganopolski, 2024)" href: notebooks/model_demos/g24.ipynb - - text: "Stommel" + - text: "Thermohaline Circulation (Stommel, 1961)" href: notebooks/model_demos/stommel.ipynb - - text: "Melcher 2025, Bistable" + - text: "Thermohaline Circulation (Melcher et al 2025)" href: notebooks/model_demos/bistable_melcher.ipynb - - section: Attractors + - section: Lorenz & Rössler contents: - text: "Roessler" href: notebooks/model_demos/roessler.ipynb diff --git a/docs/get-started/overview.qmd b/docs/get-started/overview.qmd index c285a77..c19855c 100644 --- a/docs/get-started/overview.qmd +++ b/docs/get-started/overview.qmd @@ -3,16 +3,27 @@ title: About ClimateCritters sidebar: get-started --- -The name comes from Wally Broecker, who characterized Earth's climate as an "angry beast" — capable of abrupt, large-amplitude shifts that defy easy extrapolation. ClimateCritters is a collection of minimal models that try to capture pieces of that behavior in a tractable, well-understood form. +## Origin Story -The motivation borrows loosely from biology, where progress often runs through model organisms: well-characterized systems whose dynamics are known precisely enough to serve as a reference for new methods and theories. The models gathered here — Lorenz's three-equation convection system, thermohaline box models, ice-volume oscillators, energy balance frameworks, and others — are not intended as comprehensive representations of climate. Their value runs in the other direction: they are simple enough to explore fully, yet rich enough to exhibit chaos, multiple equilibria, tipping points, and intermittency. +[Wally Broecker](https://news.climate.columbia.edu/2019/02/19/wallace-broecker-early-prophet-of-climate-change/) once characterized Earth's climate as an "angry beast" — capable of abrupt, large-amplitude shifts in response to gradual pressures. `ClimateCritters` is a collection of minimal models that try to capture pieces of that behavior in a form that lends itself to experimentation. -A few things these models lend themselves to: +The motivation borrows loosely from biology, where progress often runs through _model organisms_: well-characterized systems whose structure and behavior are known well enough to serve as a reference for new methods and theories. Climate science, [famously](https://doi.org/10.1175/BAMS-86-11-1609), has fewer of those. `ClimateCritters` aims to gather under a unified structure a few of the field's most useful simple models (e.g. Ed Lorenz 3-equation depiction of atmospheric convection, which birthed chaos theory; Stommel's 1961 bistable model of the ocean's thermohaline circulation; box models allowing to explore the carbon cycle; idealized models of Pleistocene ice ages). These models are not intended as comprehensive representations of climate -- for this, we have Earth System models, which are mighty, rich, and impossible to use for most people. The value of `ClimateCritters` runs in the other direction: the critters are simple enough to explore fully, yet rich enough to exhibit the hallmarks of complex systems behavior like chaos, multiple equilibria, tipping points, and intermittency. -- **Sensitivity and parameter exploration** — because the models are small, parameter sweeps, forcing scenarios, and initial-condition experiments run quickly and the results are interpretable. +A unique layer of `ClimateCritters` is that beyond the models themselves, the package also offers utilities that approximate the processes whereby climate signals are encoded and emplaced in the geologic record. This is particularly useful for paleoclimatology -- the study of past climates -- as one can now easily simulate how a climate-like signal gets altered by various depositional, post-depositional (["taphonomy"](https://en.wikipedia.org/wiki/Taphonomy)), as well as observational processes (like age determination). A related innovation is that `ClimateCritters` output can be readily exported to [Pyleoclim](https://pyleoclim-util.readthedocs.io/) for downstream analysis via `output.to_pyleo()`. -- **Evaluating analysis methods** — running a spectral method, a causal inference algorithm, or a tipping-point detector on a synthetic series with known properties can help build intuition about what the method is actually responding to. The structure of the underlying system matters here in the first instance: a method suited to a stationary periodic signal will behave quite differently on a chaotic or intermittent one, independent of noise or sampling effects. Taphonomic complications — noise, irregular sampling, bioturbation — add a further layer of realism once the structural questions are reasonably well understood. +## Intended Use -- **Taphonomic simulation** — real paleoclimate archives introduce noise, irregular sampling, and age uncertainty between the climate signal and the record. ClimateCritters includes utilities for adding these effects to model output, so that the gap between clean synthetic series and proxy-like records can be explored gradually. +A few things `ClimateCritters` was designed for: + +- **Sensitivity and parameter exploration** — with small models it is easy to conduct sweeps across broad parameter ranges, forcing scenarios, and initial-condition ensembles, with interpretable results. + +- **Evaluating analysis methods** — running a spectral method, a causal inference algorithm, or tipping-point detection on a synthetic series with known properties can help build intuition about what the method is actually responding to. The structure of the underlying system matters here in the first instance: a method suited to a stationary periodic signal will behave quite differently on a chaotic or intermittent one, independent of noise or sampling effects. Taphonomic complications — noise, irregular sampling, bioturbation — add a further layer of realism once the structural questions are reasonably well understood. + +- **Taphonomic simulation** — real paleoclimate archives introduce noise, irregular sampling, and age uncertainty between the climate signal and the record. `ClimateCritters` includes utilities for adding these effects to model output, so that the gap between clean synthetic series and proxy-like records can be explored gradually. + +We would be thrilled to see this package find more applications throughout the climate sciences. + +## Contributing + +`ClimateCritters` was conceived by [Julien Emile-Geay](https://orcid.org/0000-0001-5920-4751), [Jordan Landers](https://orcid.org/0000-0001-9772-7617) and [Alexander James](https://orcid.org/0000-0001-8561-3188), with contributions from Maryam Niati, and is maintained by the [Climate Dynamics Laboratory at the University of Southern California](https://commonclimate.github.io). To report bugs or contribute, please open a [GitHub issue](https://github.com/LinkedEarth/ClimateCritters/issues). -Model output can be exported to [Pyleoclim](https://pyleoclim-util.readthedocs.io/) for downstream analysis via `output.to_pyleo()`. diff --git a/docs/index.qmd b/docs/index.qmd index 8c62695..2b54b56 100644 --- a/docs/index.qmd +++ b/docs/index.qmd @@ -1,20 +1,20 @@ --- title: "ClimateCritters" -subtitle: "Synthetic paleoclimate signal models" +subtitle: "A Ménagerie of Minimal Climate Models" sidebar: ClimateCritters --- -ClimateCritters is a Python package for generating synthetic paleoclimate time series -from dynamical systems models. It provides a unified interface for integrating +`ClimateCritters` is a Python package for experimenting with minimal climate models +and well-known dynamical systems. It provides a unified interface for integrating climate models, chaotic systems, and custom box models, with built-in support -for time-varying parameters, stochastic forcing, and export to +for time-varying parameters, stochastic forcing, taphonimc alterations and export to [Pyleoclim](https://pyleoclim-util.readthedocs.io/) for analysis. ## Features - **Unified model API** — every model shares the same `integrate()` → `CCOutput` workflow - **Flexible forcing** — constants, callables, or composable `Forcing` sequences (Hold, Ramp, Harmonic) -- **Time-varying parameters** — any parameter can be swapped for a callable or Forcing object at runtime +- **Time-varying parameters** — any parameter can be swapped for a callable or `Forcing` object at runtime - **Multiple solvers** — Euler, RK4, RK45, Euler-Maruyama (SDE), and scipy adaptive methods - **Pyleoclim integration** — export directly to `Series` or `MultipleSeries` for spectral analysis and plotting @@ -29,7 +29,6 @@ pip install git+https://github.com/LinkedEarth/ClimateCritters.git ```python import climatecritters as cc from climatecritters.model_critters import Lorenz63 - model = Lorenz63() output = model.integrate(t_span=(0, 50), y0=[1, 1, 1], method='RK45') ts = output.to_pyleo(var_names='x')