Skip to content

SamudrACEForcingData

Global

Import path: earth2studio.data.SamudrACEForcingData

View source on GitHub

Documentation

Bases: _SamudrACEBase

SamudrACE exogenous forcing data source.

Provides the exogenous atmosphere forcing variables of the SamudrACE coupled emulator (e.g. downward shortwave radiation at the top of the atmosphere, land/lake fraction, surface height) from the allenai/SamudrACE-CM4-piControl HuggingFace repository, served with Earth2Studio variable names via the SamudrACELexicon.

Each forcing scenario NetCDF covers exactly one year of 6-hourly data on the no-leap CM4 model calendar (1460 timesteps). Time-varying fields are matched to requested times by month, day, and hour, ignoring the year, so the forcing series tiles annually for multi-year trajectories. Static fields are broadcast to every requested time. Requests that have no no-leap counterpart (February 29) or that fall off the 6-hourly grid raise an error.

Parameters:

  • scenario (str, default: '0311' ) –

    Forcing scenario, either "0151" or "0311", by default "0311".

  • cache (bool, default: True ) –

    Cache downloaded files locally (via the shared HuggingFace hub cache), by default True.

  • verbose (bool, default: True ) –

    Log download progress, by default True.

Warning

Each forcing scenario is a NetCDF file of roughly 300 MB that is downloaded on demand.

Note

For more information see the following references:

__call__ 

__call__(
    time: datetime | list[datetime] | TimeArray,
    variable: str | list[str] | VariableArray,
) -> DataArray

Fetch forcing data.

Parameters:

  • time (datetime | list[datetime] | TimeArray) –

    Timestamps to return data for. Time-varying fields are matched by month, day, and hour on the no-leap forcing calendar.

  • variable (str | list[str] | VariableArray) –

    Earth2Studio variable names (see SamudrACELexicon).

Returns:

  • DataArray –

    Data array with dimensions [time, variable, lat, lon] and latitude ordered north to south.

fetch async 

fetch(
    time: datetime | list[datetime] | TimeArray,
    variable: str | list[str] | VariableArray,
) -> DataArray

Async wrapper for __call__.

Parameters:

  • time (datetime | list[datetime] | TimeArray) –

    Timestamps to return data for.

  • variable (str | list[str] | VariableArray) –

    Earth2Studio variable names.

Returns:

  • DataArray –

    Data array with dimensions [time, variable, lat, lon].