Skip to content

CAMulatorForcing

GlobalNCAR

Import path: earth2studio.data.CAMulatorForcing

View source on GitHub

Documentation

CAMulator prescribed forcing data source: TOA insolation (mtdwswrf), sea-surface temperature (sst), sea-ice fraction (sic) and CO2 volume mixing ratio (global_mean_co2, ppm) on the 1 degree CAMulator grid, as shipped with the CAMulator model on HuggingFace. Two records are available: a cyclic climatological year (default; every year of a rollout sees the same forcing) and the transient 1980-2014 record. Files are downloaded on demand and cached.

The forcing files use a 365-day (no leap) calendar at 6-hourly resolution. Requested times are matched by month, day and hour (cyclic) or year, month, day and hour (transient); the 29th of February has no forcing and by default reuses the 28th.

Parameters:

  • mode (str, default: 'cyclic' ) –

    Either "cyclic" (climatological year) or "transient" (1980-2014), by default "cyclic"

  • forcing_file (str, default: None ) –

    Local NetCDF file to read instead of downloading the shipped file. Must hold the CESM variables SOLIN, SST, ICEFRAC and co2vmr_3d with dimensions (time, latitude, longitude) on the CAMulator grid and a no-leap time coordinate, by default None

  • leap_day (str, default: 'nearest' ) –

    Handling of 29 February requests: "nearest" reuses the 28 February forcing (a warning is logged once), "raise" raises a ValueError, by default "nearest"

  • cache (bool, default: True ) –

    Cache the downloaded forcing file on local disk, by default True

  • verbose (bool, default: True ) –

    Log download progress, by default True

Warning

The forcing is served from single NetCDF files downloaded on first use: about 1.3 GB for the cyclic year and 9.7 GB for the transient record. With cache=True the file lives in the HuggingFace hub cache (HF_HOME); with cache=False it is deleted after every call, which is unsuitable for model rollouts.

Note

Additional information on the forcing data can be found at:

__call__ 

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

Function to get data

Parameters:

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

    Timestamps to return data for (UTC). Must fall on 00, 06, 12 or 18 UTC.

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

    String, list of strings or array of strings that refer to variables to return. Must be forcing variables in the CAMulator lexicon.

Returns:

  • DataArray –

    Forcing data array with dimensions [time, variable, lat, lon]

fetch async 

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

Async function to get data

Parameters:

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

    Timestamps to return data for (UTC). Must fall on 00, 06, 12 or 18 UTC.

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

    String, list of strings or array of strings that refer to variables to return. Must be forcing variables in the CAMulator lexicon.

Returns:

  • DataArray –

    Forcing data array with dimensions [time, variable, lat, lon]

available classmethod 

available(time: datetime | datetime64) -> bool

Checks if the given time is on the 6-hourly CAMulator forcing grid. Whether a particular date exists in the record depends on the mode of the instance (any date for the cyclic year, 1980-2014 for the transient record), which is checked when data is requested.

Parameters:

Returns:

  • bool –

    True if the time falls on 00, 06, 12 or 18 UTC