earthsciencekit.climate

Domain hub · History · Examples · API reference

Inspectable climate models; SI units unless stated otherwise.

earthsciencekit.climate.absorbed_solar(solar_constant, albedo)

Planetary mean absorbed sunlight.

Sphere geometry and reflection set the global mean solar input.

Parameters:

• solar_constant (float or array_like) – W/m^2; constraint: nonnegative.

• albedo (float or array_like) – 1; constraint: fraction.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Global mean rather than local insolation; fixed bolometric albedo. Equation: solar_constant * (1 - albedo) / 4. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.carbon_airborne_fraction(atmospheric_increase, emissions)

Carbon budget fraction.

A carbon mass budget partitions emissions and atmospheric accumulation.

Parameters:

• atmospheric_increase (float or array_like) – kg C; constraint: nonnegative.

• emissions (float or array_like) – kg C; constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Same time interval and carbon mass units; feedback-driven values above one are not clipped. Equation: atmospheric_increase / emissions. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.carbon_decay(initial_excess, timescale, time)

Single-reservoir carbon relaxation.

A reservoir model illustrates first-order removal and residence time.

Parameters:

• initial_excess (float or array_like) – kg C; constraint: nonnegative.

• timescale (float or array_like) – s; constraint: positive.

• time (float or array_like) – s; constraint: nonnegative.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Not a realistic complete atmospheric CO2 impulse response, which has multiple timescales. Equation: initial_excess * np.exp(-time / timescale). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.co2_forcing(concentration, reference_concentration, coefficient)

Logarithmic CO2 forcing approximation.

A logarithmic approximation connects concentration changes to a forcing perturbation.

Parameters:

• concentration (float or array_like) – ppm; constraint: positive.

• reference_concentration (float or array_like) – ppm; constraint: positive.

• coefficient (float or array_like) – W/m^2; constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

User-supplied coefficient; an educational parameterization, not a current assessed forcing product. Equation: coefficient * np.log(concentration / reference_concentration). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.daily_insolation(solar_constant, latitude, declination, distance_ratio)

Daily-mean top-of-atmosphere insolation.

Latitude, solar declination and Earth-Sun distance set the sunlight a latitude receives over a day.

Parameters:

• solar_constant (float or array_like) – W/m^2 at the mean Earth-Sun distance; constraint: nonnegative.

• latitude (float or array_like) – rad; constraint: closed interval [-pi/2, pi/2].

• declination (float or array_like) – rad; constraint: closed interval [-pi/2, pi/2].

• distance_ratio (float or array_like) – 1, mean over actual Earth-Sun distance; constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Declination fixed over the day, no atmosphere; the sunset hour angle h0 is clipped for polar day and night. Equation: solar_constant * distance_ratio**2 / pi * (h0 * sin(phi) * sin(delta) + cos(phi) * cos(delta) * sin(h0)) with phi = latitude, delta = declination and h0 = arccos(clip(-tan(phi) * tan(delta), -1, 1)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.effective_temperature(absorbed_flux, emissivity)

Radiative equilibrium temperature.

Stefan-Boltzmann emission links an energy balance to temperature.

Parameters:

• absorbed_flux (float or array_like) – W/m^2; constraint: nonnegative.

• emissivity (float or array_like) – 1; constraint: open fraction.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Single emitting level in equilibrium; not the surface temperature of a greenhouse atmosphere. Equation: (absorbed_flux / (emissivity * SIGMA_SB))**0.25. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.equilibrium_solar_constant(temperature, emissivity, cold_albedo, warm_albedo, transition_temperature, width)

Solar constant that holds a planet with ice-albedo feedback at a given temperature.

Inverting the energy balance traces every equilibrium, including the unstable branch between a warm and an ice-covered state.

Parameters:

• temperature (float or array_like) – K; constraint: positive.

• emissivity (float or array_like) – 1; constraint: open fraction.

• cold_albedo (float or array_like) – 1; constraint: fraction below one.

• warm_albedo (float or array_like) – 1; constraint: fraction.

• transition_temperature (float or array_like) – K; constraint: positive.

• width (float or array_like) – K; constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Zero-dimensional greybody balance with the ice_albedo closure; equilibria with a negative slope dS/dT are unstable. Equation: 4 * emissivity * SIGMA_SB * temperature**4 / (1 - albedo), with albedo from ice_albedo. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.equilibrium_warming(forcing, restoring)

Linear climate response.

A restoring feedback maps steady forcing to equilibrium temperature change.

Parameters:

• forcing (float or array_like) – W/m^2; constraint: real.

• restoring (float or array_like) – W/(m^2 K); constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Stable linear response with a positive net restoring coefficient. Equation: forcing / restoring. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.greenhouse_surface_temperature(absorbed_flux, layer_emissivity)

Surface temperature under one absorbing atmospheric layer.

A layer that absorbs and re-emits infrared returns part of the surface emission and warms the ground.

Parameters:

• absorbed_flux (float or array_like) – W/m^2; constraint: nonnegative.

• layer_emissivity (float or array_like) – 1; constraint: fraction.

Returns:

Model value [K]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Blackbody surface, a grey isothermal layer transparent to sunlight; the layer temperature is the surface temperature over 2**0.25. Equation: (2 * absorbed_flux / ((2 - layer_emissivity) * SIGMA_SB))**0.25. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.gregory_regression(temperature_change, imbalance)

Forcing and feedback from a regression of imbalance on warming.

In a run with constant forcing, the top-of-atmosphere imbalance falls linearly with warming, so a straight-line fit gives both.

Parameters:

• temperature_change (array_like, shape (n,), n >= 2) – K; constraint: real, not all equal.

• imbalance (array_like, shape (n,)) – W/m^2, net downward top-of-atmosphere flux; constraint: real.

Returns:

[forcing, restoring]: the intercept [W/m^2] and minus the slope [W/(m^2 K)] of the least-squares line.

Return type:

numpy.ndarray, shape (2,)

Notes

Assumes N = F - lambda T with constant F and lambda; equilibrium warming is forcing / restoring. Equation: imbalance = forcing - restoring * temperature_change (ordinary least squares). Invalid, empty, nonreal or nonfinite inputs raise ValueError.

earthsciencekit.climate.heat_capacity_column(density, heat_capacity, depth)

Mixed-layer areal heat capacity.

Mixed-layer depth determines how much energy is needed for warming.

Parameters:

• density (float or array_like) – kg/m^3; constraint: positive.

• heat_capacity (float or array_like) – J/(kg K); constraint: positive.

• depth (float or array_like) – m; constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Uniform slab with constant material properties. Equation: density * heat_capacity * depth. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.heat_uptake(areal_heat_capacity, temperature_change)

Areal heat-content change.

Energy accounting connects warming to ocean heat storage.

Parameters:

• areal_heat_capacity (float or array_like) – J/(m^2 K); constraint: positive.

• temperature_change (float or array_like) – K; constraint: real.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

One uniform layer; temperature_change is an anomaly. Equation: areal_heat_capacity * temperature_change. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.ice_albedo(temperature, cold_albedo, warm_albedo, transition_temperature, width)

Smooth illustrative ice-albedo transition.

Temperature-dependent reflection illustrates ice-albedo feedback.

Parameters:

• temperature (float or array_like) – K; constraint: positive.

• cold_albedo (float or array_like) – 1; constraint: fraction.

• warm_albedo (float or array_like) – 1; constraint: fraction.

• transition_temperature (float or array_like) – K; constraint: positive.

• width (float or array_like) – K; constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Illustrative smooth closure, not a calibrated satellite albedo retrieval. Equation: warm_albedo + (cold_albedo - warm_albedo) * (1 - np.tanh((temperature - transition_temperature) / width)) / 2. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.methane_forcing(concentration, reference_concentration, nitrous_oxide)

Methane radiative forcing (Myhre et al. 1998).

Methane forcing grows as a square root of concentration, less the band it shares with nitrous oxide.

Parameters:

• concentration (float or array_like) – ppb; constraint: positive.

• reference_concentration (float or array_like) – ppb; constraint: positive.

• nitrous_oxide (float or array_like) – ppb, reference N2O concentration; constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Simplified fit to line-by-line calculations, valid near present-day concentrations; with f(M, N) = 0.47 * log(1 + 2.01e-5 * (M * N)**0.75 + 5.31e-15 * M * (M * N)**1.52). Equation: 0.036 * (sqrt(M) - sqrt(M0)) - (f(M, N0) - f(M0, N0)), with M = concentration, M0 = reference_concentration and N0 = nitrous_oxide. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.nitrous_oxide_forcing(concentration, reference_concentration, methane)

Nitrous oxide radiative forcing (Myhre et al. 1998).

Nitrous oxide forcing grows as a square root of concentration, less the band it shares with methane.

Parameters:

• concentration (float or array_like) – ppb; constraint: positive.

• reference_concentration (float or array_like) – ppb; constraint: positive.

• methane (float or array_like) – ppb, reference CH4 concentration; constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Simplified fit to line-by-line calculations, valid near present-day concentrations; f is the overlap term of methane_forcing. Equation: 0.12 * (sqrt(N) - sqrt(N0)) - (f(M0, N) - f(M0, N0)), with N = concentration, N0 = reference_concentration and M0 = methane. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.outgoing_longwave(temperature, emissivity)

Greybody infrared emission.

A greybody approximation maps temperature to outgoing radiant flux.

Parameters:

• temperature (float or array_like) – K; constraint: positive.

• emissivity (float or array_like) – 1; constraint: fraction.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Constant emissivity; not a spectral atmospheric radiative-transfer solver. Equation: emissivity * SIGMA_SB * temperature**4. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.planck_feedback(temperature, emissivity)

Blackbody restoring derivative.

The temperature derivative of emission supplies a radiative restoring coefficient.

Parameters:

• temperature (float or array_like) – K; constraint: positive.

• emissivity (float or array_like) – 1; constraint: open fraction.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Positive restoring magnitude in W per square metre per kelvin; other feedbacks are separate. Equation: 4 * emissivity * SIGMA_SB * temperature**3. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.radiative_convective_temperature(height, effective_temperature, lapse_rate, emission_height)

Radiative-convective equilibrium temperature profile.

Convection holds the troposphere at a fixed lapse rate below a radiatively balanced stratosphere.

Parameters:

• height (float or array_like) – m above the surface; constraint: nonnegative.

• effective_temperature (float or array_like) – K; constraint: positive.

• lapse_rate (float or array_like) – K/m; constraint: positive.

• emission_height (float or array_like) – m; constraint: nonnegative.

Returns:

Model value [K]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Grey optically thin stratosphere at the skin temperature effective_temperature / 2**0.25; the troposphere passes through effective_temperature at emission_height, so the surface is effective_temperature + lapse_rate * emission_height. Equation: np.maximum(effective_temperature + lapse_rate * (emission_height - height), effective_temperature / 2**0.25). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.red_noise_spectrum(frequency, forcing_spectrum, restoring, areal_heat_capacity)

Temperature spectrum of a one-box climate driven by white noise.

Heat capacity integrates random weather forcing into slow red-noise climate variability.

Parameters:

• frequency (float or array_like) – Hz; constraint: real.

• forcing_spectrum (float or array_like) – W^2/(m^4 Hz), two-sided; constraint: nonnegative.

• restoring (float or array_like) – W/(m^2 K); constraint: positive.

• areal_heat_capacity (float or array_like) – J/(m^2 K); constraint: positive.

Returns:

Model value [K^2/Hz], two-sided. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Linear C dT/dt = F - lambda T with white-noise F; integrating over all frequencies gives the variance forcing_spectrum / (2 * restoring * areal_heat_capacity). Equation: forcing_spectrum / (restoring**2 + (2 * np.pi * frequency * areal_heat_capacity)**2). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.response_timescale(areal_heat_capacity, restoring)

Climate relaxation time.

Heat storage delays the equilibrium response to forcing.

Parameters:

• areal_heat_capacity (float or array_like) – J/(m^2 K); constraint: positive.

• restoring (float or array_like) – W/(m^2 K); constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

One-box linear model; output is seconds. Equation: areal_heat_capacity / restoring. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.simulate_one_box(forcing, restoring, areal_heat_capacity, time, *, initial_anomaly=0.0)

Integrate a linear one-box climate energy balance.

Parameters:

• forcing (float) – Constant signed radiative perturbation [W/m^2].

• restoring (float) – Positive scalar net restoring coefficient [W/(m^2 K)].

• areal_heat_capacity (float) – Positive scalar effective heat capacity [J/(m^2 K)].

• time (array_like) – Nonnegative strictly increasing sampled times [s].

• initial_anomaly (float) – Finite scalar temperature anomaly [K] at the first supplied time.

Returns:

Temperature anomaly [K].

Return type:

TimeSeries

Notes

C dT/dt = F - lambda T. Compare with step_temperature for zero initial anomaly, using elapsed time since the first sample. This educational model omits deep-ocean exchange, nonlinear feedbacks and geographic structure.

earthsciencekit.climate.step_temperature(forcing, restoring, areal_heat_capacity, time)

Transient one-box warming.

A step forcing exposes the lag between forcing and temperature adjustment.

Parameters:

• forcing (float or array_like) – W/m^2; constraint: real.

• restoring (float or array_like) – W/(m^2 K); constraint: positive.

• areal_heat_capacity (float or array_like) – J/(m^2 K); constraint: positive.

• time (float or array_like) – s; constraint: nonnegative.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Zero initial anomaly and constant parameters; no deep-ocean exchange. Equation: forcing / restoring * (-np.expm1(-restoring * time / areal_heat_capacity)). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.thermal_expansion_sea_level(expansion_coefficient, depth, temperature_change)

Steric sea-level slab approximation.

Ocean expansion connects heat uptake to a sea-level contribution.

Parameters:

• expansion_coefficient (float or array_like) – 1/K; constraint: positive.

• depth (float or array_like) – m; constraint: positive.

• temperature_change (float or array_like) – K; constraint: real.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Constant coefficient and uniform warming; salinity and pressure dependence are omitted. Equation: expansion_coefficient * depth * temperature_change. Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.

earthsciencekit.climate.water_equivalent_sea_level(water_mass, ocean_area, water_density)

Mass-equivalent sea-level contribution.

Added ocean water changes mean level through mass conservation.

Parameters:

• water_mass (float or array_like) – kg; constraint: nonnegative.

• ocean_area (float or array_like) – m^2; constraint: positive.

• water_density (float or array_like) – kg/m^3; constraint: positive.

Returns:

Model value [W/m^2]. Scalar input returns a NumPy scalar; arrays broadcast.

Return type:

numpy scalar or ndarray

Notes

Uniform ocean area and density; gravitational fingerprints and land motion are omitted. Equation: water_mass / (ocean_area * water_density). Invalid, empty, nonreal or nonfinite inputs raise ValueError. NumPy broadcasting applies; singular and overflowing outputs raise ValueError.