<a id="internals-timecoding"></a>

# Time Coding

This page gives an overview how xarray encodes and decodes times and which conventions and functions are used.

## Pandas functionality

### to_datetime

The function [`pandas.to_datetime()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html#pandas.to_datetime) is used within xarray for inferring units and for testing purposes.

In normal operation [`pandas.to_datetime()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html#pandas.to_datetime) returns a [`pandas.Timestamp`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html#pandas.Timestamp) (for scalar input) or [`pandas.DatetimeIndex`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.html#pandas.DatetimeIndex) (for array-like input) which are related to `np.datetime64` values with a resolution inherited from the input (can be one of `'s'`, `'ms'`, `'us'`, `'ns'`). If no resolution can be inherited `'ns'` is assumed. That has the implication that the maximum usable time range for those cases is approximately +/- 292 years centered around the Unix epoch (1970-01-01). To accommodate that, we carefully check the units/resolution in the encoding and decoding step.

When the arguments are numeric (not strings or `np.datetime64` values) `"unit"` can be anything from `'Y'`, `'W'`, `'D'`, `'h'`, `'m'`, `'s'`, `'ms'`, `'us'` or `'ns'`, though the returned resolution will be `"ns"`.

```ipython3
print(f"Minimum datetime: {pd.to_datetime(int64_min, unit="ns")}")
print(f"Maximum datetime: {pd.to_datetime(int64_max, unit="ns")}")
```

```myst-ansi
Minimum datetime: 1677-09-21 00:12:43.145224193
Maximum datetime: 2262-04-11 23:47:16.854775807
```

For input values which can’t be represented in nanosecond resolution an `pandas.OutOfBoundsDatetime` exception is raised:

```ipython3
try:
    dtime = pd.to_datetime(int64_max, unit="us")
except Exception as err:
    print(err)
```

```ipython3
try:
    dtime = pd.to_datetime(uint64_max, unit="ns")
    print("Wrong:", dtime)
    dtime = pd.to_datetime([uint64_max], unit="ns")
except Exception as err:
    print(err)
```

```myst-ansi
Wrong: 1969-12-31 23:59:59.999999999
cannot convert input 18446744073709551615 with the unit 'ns'
```

`np.datetime64` values can be extracted with [`pandas.Timestamp.to_numpy()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.to_numpy.html#pandas.Timestamp.to_numpy) and `pandas.DatetimeIndex.to_numpy()`. The returned resolution depends on the internal representation. This representation can be changed using [`pandas.Timestamp.as_unit()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.as_unit.html#pandas.Timestamp.as_unit)
and [`pandas.DatetimeIndex.as_unit()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.as_unit.html#pandas.DatetimeIndex.as_unit) respectively.

`as_unit` takes one of `'s'`, `'ms'`, `'us'`, `'ns'` as an argument. That means we are able to represent datetimes with second, millisecond, microsecond or nanosecond resolution.

```ipython3
time = pd.to_datetime(np.datetime64(0, "D"))
print("Datetime:", time, np.asarray([time.to_numpy()]).dtype)
print("Datetime as_unit('ms'):", time.as_unit("ms"))
print("Datetime to_numpy():", time.as_unit("ms").to_numpy())
```

```myst-ansi
Datetime: 1970-01-01 00:00:00 datetime64[s]
Datetime as_unit('ms'): 1970-01-01 00:00:00
Datetime to_numpy(): 1970-01-01T00:00:00.000
```

```ipython3
time = pd.to_datetime(np.array([-1000, 1, 2], dtype="datetime64[Y]"))
print("DatetimeIndex:", time)
print("DatetimeIndex as_unit('us'):", time.as_unit("us"))
print("DatetimeIndex to_numpy():", time.as_unit("us").to_numpy())
```

```myst-ansi
DatetimeIndex: DatetimeIndex(['970-01-01', '1971-01-01', '1972-01-01'], dtype='datetime64[s]', freq=None)
DatetimeIndex as_unit('us'): DatetimeIndex(['970-01-01', '1971-01-01', '1972-01-01'], dtype='datetime64[us]', freq=None)
DatetimeIndex to_numpy(): ['0970-01-01T00:00:00.000000' '1971-01-01T00:00:00.000000'
 '1972-01-01T00:00:00.000000']
```

#### WARNING
Input data with resolution higher than `'ns'` (eg. `'ps'`, `'fs'`, `'as'`) is truncated (not rounded) at the `'ns'`-level. This is [currently broken](https://github.com/pandas-dev/pandas/issues/60341) for the `'ps'` input, where it is interpreted as `'ns'`.
See the cell below:

```ipython3
print("Good:", pd.to_datetime([np.datetime64(1901901901901, "as")]))
print("Good:", pd.to_datetime([np.datetime64(1901901901901, "fs")]))
print(" Bad:", pd.to_datetime([np.datetime64(1901901901901, "ps")]))
print("Good:", pd.to_datetime([np.datetime64(1901901901901, "ns")]))
print("Good:", pd.to_datetime([np.datetime64(1901901901901, "us")]))
print("Good:", pd.to_datetime([np.datetime64(1901901901901, "ms")]))
```

```myst-ansi
Good: DatetimeIndex(['1970-01-01 00:00:00.000001901'], dtype='datetime64[ns]', freq=None)
Good: DatetimeIndex(['1970-01-01 00:00:00.001901901'], dtype='datetime64[ns]', freq=None)
 Bad: DatetimeIndex(['1970-01-01 00:00:01.901901901'], dtype='datetime64[ns]', freq=None)
Good: DatetimeIndex(['1970-01-01 00:31:41.901901901'], dtype='datetime64[ns]', freq=None)
Good: DatetimeIndex(['1970-01-23 00:18:21.901901'], dtype='datetime64[us]', freq=None)
Good: DatetimeIndex(['2030-04-08 18:05:01.901000'], dtype='datetime64[ms]', freq=None)
```

#### WARNING
Care has to be taken, as some configurations of input data will raise. The following shows, that we are safe to use [`pandas.to_datetime()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_datetime.html#pandas.to_datetime) when providing [`numpy.datetime64`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.datetime64) as scalar or numpy array as input.
See the cell below:

```ipython3
print(
    "Works:",
    np.datetime64(1901901901901, "s"),
    pd.to_datetime(np.datetime64(1901901901901, "s")),
)
print(
    "Works:",
    np.array([np.datetime64(1901901901901, "s")]),
    pd.to_datetime(np.array([np.datetime64(1901901901901, "s")])),
)
try:
    pd.to_datetime([np.datetime64(1901901901901, "s")])
except Exception as err:
    print("Raises:", err)
try:
    pd.to_datetime(1901901901901, unit="s")
except Exception as err:
    print("Raises:", err)
try:
    pd.to_datetime([1901901901901], unit="s")
except Exception as err:
    print("Raises:", err)
try:
    pd.to_datetime(np.array([1901901901901]), unit="s")
except Exception as err:
    print("Raises:", err)
```

```myst-ansi
Works: 62238-11-15T11:51:41 62238-11-15 11:51:41
Works: ['62238-11-15T11:51:41'] DatetimeIndex(['62238-11-15 11:51:41'], dtype='datetime64[s]', freq=None)
```

### to_timedelta

The function [`pandas.to_timedelta()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_timedelta.html#pandas.to_timedelta) is used within xarray for inferring units and for testing purposes.

In normal operation [`pandas.to_timedelta()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_timedelta.html#pandas.to_timedelta) returns a [`pandas.Timedelta`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timedelta.html#pandas.Timedelta) (for scalar input) or [`pandas.TimedeltaIndex`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.TimedeltaIndex.html#pandas.TimedeltaIndex) (for array-like input) which are `np.timedelta64` values with `ns` resolution internally. That has the implication, that the usable timedelta covers only roughly 585 years. To accommodate for that, we are working around that limitation in the encoding and decoding step.

```ipython3
f"Maximum timedelta range: ({pd.to_timedelta(int64_min, unit="ns")}, {pd.to_timedelta(int64_max, unit="ns")})"
```

For input values which can’t be represented in nanosecond resolution an `pandas.OutOfBoundsTimedelta` exception is raised:

```ipython3
try:
    delta = pd.to_timedelta(int64_max, unit="us")
except Exception as err:
    print("First:", err)
```

```ipython3
try:
    delta = pd.to_timedelta(uint64_max, unit="ns")
except Exception as err:
    print("Second:", err)
```

```myst-ansi
Second: Cannot cast 18446744073709551615 from ns to 'ns' without overflow.
```

When arguments are numeric (not strings or `np.timedelta64` values) “unit” can be anything from `'W'`, `'D'`, `'h'`, `'m'`, `'s'`, `'ms'`, `'us'` or `'ns'`, though the returned resolution will be `"ns"`.

`np.timedelta64` values can be extracted with [`pandas.Timedelta.to_numpy()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timedelta.to_numpy.html#pandas.Timedelta.to_numpy) and `pandas.TimedeltaIndex.to_numpy()`. The returned resolution depends on the internal representation. This representation can be changed using [`pandas.Timedelta.as_unit()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timedelta.as_unit.html#pandas.Timedelta.as_unit)
and [`pandas.TimedeltaIndex.as_unit()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.TimedeltaIndex.as_unit.html#pandas.TimedeltaIndex.as_unit) respectively.

`as_unit` takes one of `'s'`, `'ms'`, `'us'`, `'ns'` as an argument. That means we are able to represent timedeltas with second, millisecond, microsecond or nanosecond resolution.

```ipython3
delta = pd.to_timedelta(np.timedelta64(1, "D"))
print("Timedelta:", delta, np.asarray([delta.to_numpy()]).dtype)
print("Timedelta as_unit('ms'):", delta.as_unit("ms"))
print("Timedelta to_numpy():", delta.as_unit("ms").to_numpy())
```

```myst-ansi
Timedelta: 1 days 00:00:00 timedelta64[s]
Timedelta as_unit('ms'): 1 days 00:00:00
Timedelta to_numpy(): 86400000 milliseconds
```

```ipython3
delta = pd.to_timedelta([0, 1, 2], unit="D")
print("TimedeltaIndex:", delta)
print("TimedeltaIndex as_unit('ms'):", delta.as_unit("ms"))
print("TimedeltaIndex to_numpy():", delta.as_unit("ms").to_numpy())
```

```myst-ansi
TimedeltaIndex: TimedeltaIndex(['0 days', '1 days', '2 days'], dtype='timedelta64[s]', freq=None)
TimedeltaIndex as_unit('ms'): TimedeltaIndex(['0 days', '1 days', '2 days'], dtype='timedelta64[ms]', freq=None)
TimedeltaIndex to_numpy(): [        0  86400000 172800000]
```

#### WARNING
Care has to be taken, as some configurations of input data will raise. The following shows, that we are safe to use [`pandas.to_timedelta()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_timedelta.html#pandas.to_timedelta) when providing [`numpy.timedelta64`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.timedelta64) as scalar or numpy array as input.
See the cell below:

```ipython3
print(
    "Works:",
    np.timedelta64(1901901901901, "s"),
    pd.to_timedelta(np.timedelta64(1901901901901, "s")),
)
print(
    "Works:",
    np.array([np.timedelta64(1901901901901, "s")]),
    pd.to_timedelta(np.array([np.timedelta64(1901901901901, "s")])),
)
try:
    pd.to_timedelta([np.timedelta64(1901901901901, "s")])
except Exception as err:
    print("Raises:", err)
try:
    pd.to_timedelta(1901901901901, unit="s")
except Exception as err:
    print("Raises:", err)
try:
    pd.to_timedelta([1901901901901], unit="s")
except Exception as err:
    print("Raises:", err)
try:
    pd.to_timedelta(np.array([1901901901901]), unit="s")
except Exception as err:
    print("Raises:", err)
```

```myst-ansi
Works: 1901901901901 seconds 22012753 days 11:51:41
Works: [1901901901901] TimedeltaIndex(['22012753 days 11:51:41'], dtype='timedelta64[s]', freq=None)
```

### Timestamp

[`pandas.Timestamp`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html#pandas.Timestamp) is used within xarray to wrap strings of CF encoding reference times and datetime.datetime.

When arguments are numeric (not strings) “unit” can be anything from `'Y'`, `'W'`, `'D'`, `'h'`, `'m'`, `'s'`, `'ms'`, `'us'` or `'ns'`, though the returned resolution will be `"ns"`.

In normal operation [`pandas.Timestamp`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html#pandas.Timestamp) holds the timestamp in the provided resolution, but only one of `'s'`, `'ms'`, `'us'`, `'ns'`. Lower resolution input is automatically converted to `'s'`, higher resolution input is truncated to `'ns'`.

The same conversion rules apply here as for [`pandas.to_timedelta()`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.to_timedelta.html#pandas.to_timedelta) (see [to_timedelta]).
Depending on the internal resolution Timestamps can be represented in the range:

```ipython3
for unit in ["s", "ms", "us", "ns"]:
    print(
        f"unit: {unit!r} time range ({pd.Timestamp(int64_min, unit=unit)}, {pd.Timestamp(int64_max, unit=unit)})"
    )
```

```myst-ansi
unit: 's' time range (-292277022657-01-27 08:29:53, 292277026596-12-04 15:30:07)
unit: 'ms' time range (-292275055-05-16 16:47:04.193000, 292278994-08-17 07:12:55.807000)
unit: 'us' time range (-290308-12-21 19:59:05.224193, 294247-01-10 04:00:54.775807)
unit: 'ns' time range (1677-09-21 00:12:43.145224193, 2262-04-11 23:47:16.854775807)
```

Since relaxing the resolution, this enhances the range to several hundreds of thousands of centuries with microsecond representation. `NaT` will be at `np.iinfo("int64").min` for all of the different representations.

#### WARNING
When initialized with a datetime string this is only defined from `-9999-01-01` to `9999-12-31`.
See the cell below:

```ipython3
try:
    print("Works:", pd.Timestamp("-9999-01-01 00:00:00"))
    print("Works, too:", pd.Timestamp("9999-12-31 23:59:59"))
    print(pd.Timestamp("10000-01-01 00:00:00"))
except Exception as err:
    print("Errors:", err)
```

```myst-ansi
Works: -9999-01-01 00:00:00
Works, too: 9999-12-31 23:59:59
Errors: year must be in 1..9999, not 10000: 10000-01-01 00:00:00
```

#### NOTE
[`pandas.Timestamp`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html#pandas.Timestamp) is the only current possibility to correctly import time reference strings. It handles non-ISO formatted strings, keeps the resolution of the strings (`'s'`, `'ms'` etc.) and imports time zones. When initialized with [`numpy.datetime64`](https://numpy.org/doc/stable/reference/arrays.scalars.html#numpy.datetime64) instead of a string it even overcomes the above limitation of the possible time range.
See the cell below:

```ipython3
try:
    print("Handles non-ISO:", pd.Timestamp("92-1-8 151542"))
    print(
        "Keeps resolution 1:",
        pd.Timestamp("1992-10-08 15:15:42"),
        pd.Timestamp("1992-10-08 15:15:42").unit,
    )
    print(
        "Keeps resolution 2:",
        pd.Timestamp("1992-10-08 15:15:42.5"),
        pd.Timestamp("1992-10-08 15:15:42.5").unit,
    )
    print(
        "Keeps timezone:",
        pd.Timestamp("1992-10-08 15:15:42.5 -6:00"),
        pd.Timestamp("1992-10-08 15:15:42.5 -6:00").unit,
    )
    print(
        "Extends timerange :",
        pd.Timestamp(np.datetime64("-10000-10-08 15:15:42.5001")),
        pd.Timestamp(np.datetime64("-10000-10-08 15:15:42.5001")).unit,
    )
except Exception as err:
    print("Errors:", err)
```

```myst-ansi
Handles non-ISO: 1992-01-08 15:15:42
Keeps resolution 1: 1992-10-08 15:15:42 us
Keeps resolution 2: 1992-10-08 15:15:42.500000 us
Keeps timezone: 1992-10-08 15:15:42.500000-06:00 us
Extends timerange : -10000-10-08 15:15:42.500100 us
```

### DatetimeIndex

[`pandas.DatetimeIndex`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.html#pandas.DatetimeIndex) is used to wrap `np.datetime64` values or other datetime-likes when encoding. The resolution of the DatetimeIndex depends on the input, but can be only one of `'s'`, `'ms'`, `'us'`, `'ns'`. Lower resolution input is automatically converted to `'s'`, higher resolution input is cut to `'ns'`.
[`pandas.DatetimeIndex`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.html#pandas.DatetimeIndex) will raise `pandas.OutOfBoundsDatetime` if the input can’t be represented in the given resolution.

```ipython3
try:
    print(
        "Works:",
        pd.DatetimeIndex(
            np.array(["1992-01-08", "1992-01-09"], dtype="datetime64[D]")
        ),
    )
    print(
        "Works:",
        pd.DatetimeIndex(
            np.array(
                ["1992-01-08 15:15:42", "1992-01-09 15:15:42"],
                dtype="datetime64[s]",
            )
        ),
    )
    print(
        "Works:",
        pd.DatetimeIndex(
            np.array(
                ["1992-01-08 15:15:42.5", "1992-01-09 15:15:42.0"],
                dtype="datetime64[ms]",
            )
        ),
    )
    print(
        "Works:",
        pd.DatetimeIndex(
            np.array(
                ["1970-01-01 00:00:00.401501601701801901", "1970-01-01 00:00:00"],
                dtype="datetime64[as]",
            )
        ),
    )
    print(
        "Works:",
        pd.DatetimeIndex(
            np.array(
                ["-10000-01-01 00:00:00.401501", "1970-01-01 00:00:00"],
                dtype="datetime64[us]",
            )
        ),
    )
except Exception as err:
    print("Errors:", err)
```

```myst-ansi
Works: DatetimeIndex(['1992-01-08', '1992-01-09'], dtype='datetime64[s]', freq=None)
Works: DatetimeIndex(['1992-01-08 15:15:42', '1992-01-09 15:15:42'], dtype='datetime64[s]', freq=None)
Works: DatetimeIndex(['1992-01-08 15:15:42.500000', '1992-01-09 15:15:42'], dtype='datetime64[ms]', freq=None)
Works: DatetimeIndex(['1970-01-01 00:00:00.401501601', '1970-01-01 00:00:00'], dtype='datetime64[ns]', freq=None)
Works: DatetimeIndex(['-10000-01-01 00:00:00.401501', '1970-01-01 00:00:00'], dtype='datetime64[us]', freq=None)
```

## CF Conventions Time Handling

Xarray tries to adhere to the latest version of the [CF Conventions](https://cfconventions.org). Relevant is the section on [Time Coordinate](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.11/cf-conventions.html#time-coordinate) and the [Calendar](https://cfconventions.org/Data/cf-conventions/cf-conventions-1.11/cf-conventions.html#calendar) subsection.

### CF time decoding

Decoding of `values` with a time unit specification like `"seconds since 1992-10-8 15:15:42.5 -6:00"` into datetimes using the CF conventions is a multistage process.

1. If we have a non-standard calendar (e.g. `"noleap"`) decoding is done with the `cftime` package, which is not covered in this section. For the `"standard"`/`"gregorian"` calendar as well as the `"proleptic_gregorian"` calendar the above outlined pandas functionality is used.
2. The `"standard"`/`"gregorian"` calendar and the `"proleptic_gregorian"` are equivalent for any dates and reference times >= `"1582-10-15"`. First the reference time is checked and any timezone information stripped off. In a second step, the minimum and maximum `values` are checked if they can be represented in the current reference time resolution. At the same time integer overflow would be caught. For the `"standard"`/`"gregorian"` calendar the dates are checked to be >= `"1582-10-15"`. If anything fails, the decoding is attempted with `cftime`.
3. As the unit (here `"seconds"`) and the resolution of the reference time `"1992-10-8 15:15:42.5 -6:00"` (here `"milliseconds"`) might be different, the decoding resolution is aligned to the higher resolution of the two. Users may also specify their wanted target resolution by setting the `time_unit` keyword argument to one of `'s'`, `'ms'`, `'us'`, `'ns'` (default `'ns'`). This will be included in the alignment process. This is done by multiplying the `values` by the ratio of nanoseconds per time unit and nanoseconds per reference time unit. To retain consistency for `NaT` values a mask is kept and re-introduced after the multiplication.
4. Times encoded as floating point values are checked for fractional parts and the resolution is enhanced in an iterative process until a fitting resolution (or `'ns'`) is found. A `SerializationWarning` is issued to make the user aware of the possibly problematic encoding.
5. Finally, the `values` (at this point converted to `int64` values) are cast to `datetime64[unit]` (using the above retrieved unit) and added to the reference time [`pandas.Timestamp`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html#pandas.Timestamp).

```ipython3
calendar = "proleptic_gregorian"
values = np.array([-1000 * 365, 0, 1000 * 365], dtype="int64")
units = "days since 2000-01-01 00:00:00.000001"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[us]"
dt
```

```ipython3
units = "microseconds since 2000-01-01 00:00:00"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[us]"
dt
```

```ipython3
values = np.array([0, 0.25, 0.5, 0.75, 1.0], dtype="float64")
units = "days since 2000-01-01 00:00:00.001"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[ms]"
dt
```

```ipython3
values = np.array([0, 0.25, 0.5, 0.75, 1.0], dtype="float64")
units = "hours since 2000-01-01"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[s]"
dt
```

```ipython3
values = np.array([0, 0.25, 0.5, 0.75, 1.0], dtype="float64")
units = "hours since 2000-01-01 00:00:00 03:30"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[s]"
dt
```

```ipython3
values = np.array([-2002 * 365 - 121, -366, 365, 2000 * 365 + 119], dtype="int64")
units = "days since 0001-01-01 00:00:00"
dt = xr.coding.times.decode_cf_datetime(values, units, calendar, time_unit="s")
assert dt.dtype == "datetime64[s]"
dt
```

### CF time encoding

For encoding the process is more or less a reversal of the above, but we have to make some decisions on default values.

1. Infer `data_units` from the given `dates`.
2. Infer `units` (either cleanup given `units` or use `data_units`
3. Infer the calendar name from the given `dates`.
4. If dates are [`cftime.datetime`](https://unidata.github.io/cftime/api.html#cftime.datetime) objects then encode with `cftime.date2num`
5. Retrieve `time_units` and `ref_date` from `units`
6. Check `ref_date` >= `1582-10-15`, otherwise -> `cftime`
7. Wrap `dates` with pd.DatetimeIndex
8. Subtracting `ref_date` ([`pandas.Timestamp`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Timestamp.html#pandas.Timestamp)) from above [`pandas.DatetimeIndex`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.DatetimeIndex.html#pandas.DatetimeIndex) will return [`pandas.TimedeltaIndex`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.TimedeltaIndex.html#pandas.TimedeltaIndex)
9. Align resolution of [`pandas.TimedeltaIndex`](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.TimedeltaIndex.html#pandas.TimedeltaIndex) with resolution of `time_units`
10. Retrieve needed `units` and `delta` to faithfully encode into int64
11. Divide `time_deltas` by `delta`, use floor division (integer) or normal division (float)
12. Return result

```ipython3
calendar = "proleptic_gregorian"
dates = np.array(
    [
        "-2000-01-01T00:00:00",
        "0000-01-01T00:00:00",
        "0002-01-01T00:00:00",
        "2000-01-01T00:00:00",
    ],
    dtype="datetime64[s]",
)
orig_values = np.array(
    [-2002 * 365 - 121, -366, 365, 2000 * 365 + 119], dtype="int64"
)
units = "days since 0001-01-01 00:00:00"
values, _, _ = xr.coding.times.encode_cf_datetime(
    dates, units, calendar, dtype=np.dtype("int64")
)
print(values, units)
np.testing.assert_array_equal(values, orig_values)
```

```myst-ansi
[-730851    -366     365  730119] days since 0001-01-01 00:00:00
```

```ipython3
dates = np.array(
    [
        "-2000-01-01T01:00:00",
        "0000-01-01T00:00:00",
        "0002-01-01T00:00:00",
        "2000-01-01T00:00:00",
    ],
    dtype="datetime64[s]",
)
orig_values = np.array(
    [-2002 * 365 - 121, -366, 365, 2000 * 365 + 119], dtype="int64"
)
orig_values *= 24  # Convert to hours
orig_values[0] += 1  # Adjust for the hour offset in dates above

units = "days since 0001-01-01 00:00:00"
values, units, _ = xr.coding.times.encode_cf_datetime(
    dates, units, calendar, dtype=np.dtype("int64")
)
print(values, units)
np.testing.assert_array_equal(values, orig_values)
```

```myst-ansi
[-17540423     -8784      8760  17522856] hours since 0001-01-01
```

<a id="internals-default-timeunit"></a>

### Default Time Unit

The current default time unit of xarray is `'ns'`. When setting keyword argument `time_unit` unit to `'s'` (the lowest resolution pandas allows) datetimes will be converted to at least `'s'`-resolution, if possible. The same holds true for `'ms'` and `'us'`.

```ipython3
datetimes1_filename = "test-datetimes1.nc"
```

```ipython3
attrs = {"units": "hours since 2000-01-01"}
ds = xr.Dataset({"time": ("time", [0, 1, 2, 3], attrs)})
ds.to_netcdf(datetimes1_filename)
```

```ipython3
xr.open_dataset(datetimes1_filename)
```

```ipython3
coder = xr.coders.CFDatetimeCoder(time_unit="s")
xr.open_dataset(datetimes1_filename, decode_times=coder)
```

If a coarser unit is requested the datetimes are decoded into their native
on-disk resolution, if possible.

```ipython3
datetimes2_filename = "test-datetimes2.nc"
```

```ipython3
attrs = {"units": "milliseconds since 2000-01-01"}
ds = xr.Dataset({"time": ("time", [0, 1, 2, 3], attrs)})
ds.to_netcdf(datetimes2_filename)

xr.open_dataset(datetimes2_filename)
```

```ipython3
coder = xr.coders.CFDatetimeCoder(time_unit="s")
xr.open_dataset(datetimes2_filename, decode_times=coder)
```

Similar logic applies for decoding timedelta values. The default resolution is
`"ns"`:

```ipython3
timedeltas1_filename = "test-timedeltas1.nc"
```

```ipython3
attrs = {"units": "hours"}
ds = xr.Dataset({"time": ("time", [0, 1, 2, 3], attrs)})
ds.to_netcdf(timedeltas1_filename)
```

```ipython3
xr.open_dataset(timedeltas1_filename)
```

By default, timedeltas will be decoded to the same resolution as datetimes:

```ipython3
coder = xr.coders.CFDatetimeCoder(time_unit="s")
xr.open_dataset(timedeltas1_filename, decode_times=coder, decode_timedelta=True)
```

but if one would like to decode timedeltas to a different resolution, one can
provide a coder specifically for timedeltas to `decode_timedelta`:

```ipython3
timedelta_coder = xr.coders.CFTimedeltaCoder(time_unit="ms")
xr.open_dataset(
    timedeltas1_filename, decode_times=coder, decode_timedelta=timedelta_coder
)
```

As with datetimes, if a coarser unit is requested the timedeltas are decoded
into their native on-disk resolution, if possible:

```ipython3
timedeltas2_filename = "test-timedeltas2.nc"
```

```ipython3
attrs = {"units": "milliseconds"}
ds = xr.Dataset({"time": ("time", [0, 1, 2, 3], attrs)})
ds.to_netcdf(timedeltas2_filename)

xr.open_dataset(timedeltas2_filename, decode_timedelta=True)
```

```ipython3
coder = xr.coders.CFDatetimeCoder(time_unit="s")
xr.open_dataset(timedeltas2_filename, decode_times=coder, decode_timedelta=True)
```

To opt-out of timedelta decoding (see issue [Undesired decoding to timedelta64](https://github.com/pydata/xarray/issues/1621)) pass `False` to `decode_timedelta`:

```ipython3
xr.open_dataset(timedeltas2_filename, decode_timedelta=False)
```

#### NOTE
Note that in the future the default value of `decode_timedelta` will be
`False` rather than `None`.