array([[[3.e-01, 4.e-01, 3.e+30, 3.e+30],\n",
" [3.e+30, 3.e+30, 3.e+30, 3.e+30],\n",
" [3.e+30, 3.e+30, 3.e+30, 3.e+30]],\n",
"\n",
@@ -2191,22 +2058,15 @@
"source": [
"ds = evt.to_xarray()\n",
"pxdp = ds[\"pxdp\"]\n",
- "assert pxdp.dims == (\"per\", \"nseg-1\", \"layer\", \"row\", \"col\")\n",
- "pxdp.isel(per=0, layer=0)"
+ "assert pxdp.dims == (\"kper\", \"nseg-1\", \"layer\", \"row\", \"col\")\n",
+ "pxdp.isel(kper=0, layer=0)"
]
},
{
"cell_type": "code",
"execution_count": 20,
- "id": "f680508c",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-10-19T13:38:00.396369Z",
- "iopub.status.busy": "2026-10-19T13:38:00.396307Z",
- "iopub.status.idle": "2026-10-19T13:38:00.398901Z",
- "shell.execute_reply": "2026-10-19T13:38:00.398613Z"
- }
- },
+ "id": "84a0f991",
+ "metadata": {},
"outputs": [],
"source": [
"np.testing.assert_array_equal(pxdp[0, :, 0, 0, 0], [0.3, 0.6])\n",
@@ -2218,7 +2078,7 @@
},
{
"cell_type": "markdown",
- "id": "3f733347",
+ "id": "c1f71ff6",
"metadata": {},
"source": [
"### Writing and running\n",
@@ -2230,15 +2090,8 @@
{
"cell_type": "code",
"execution_count": 21,
- "id": "09185408",
- "metadata": {
- "execution": {
- "iopub.execute_input": "2026-10-19T13:38:00.400168Z",
- "iopub.status.busy": "2026-10-19T13:38:00.400107Z",
- "iopub.status.idle": "2026-10-19T13:38:00.488617Z",
- "shell.execute_reply": "2026-10-19T13:38:00.488153Z"
- }
- },
+ "id": "cb2475a7",
+ "metadata": {},
"outputs": [],
"source": [
"Ims(parent=sim, models=[gwf])\n",
@@ -2252,7 +2105,7 @@
},
{
"cell_type": "markdown",
- "id": "53a4bfaa",
+ "id": "a3de8a74",
"metadata": {},
"source": [
"### Lists or arrays?\n",
diff --git a/docs/examples/period-data.py b/docs/examples/period-data.py
index 40afc62f..2806b84c 100644
--- a/docs/examples/period-data.py
+++ b/docs/examples/period-data.py
@@ -90,7 +90,7 @@
# ### The array view
#
-# `to_xarray()` gives a variable per value column on `(per, layer, row, col)`,
+# `to_xarray()` gives a variable per value column on `(kper, layer, row, col)`,
# with every period filled forward. Empty cells hold `FILL_DNODATA` (3e30).
#
# * Each auxiliary variable is its own variable (`conc`).
@@ -104,7 +104,7 @@
# +
q = ds["q"]
-assert q.dims == ("per", "layer", "row", "col")
+assert q.dims == ("kper", "layer", "row", "col")
assert q[1, 0, 0, 0] == -1.0 # period 1 filled forward from period 0
assert q[0, 0, 1, 1] == FILL_DNODATA # no well here until period 2
assert q[2, 0, 1, 1] == -2.5 # two wells, summed
@@ -157,9 +157,9 @@
# * `duplicates="sum"`, `"first"` or `"last"` merges them. `"sum"` can't sum
# a time series. The boundname kept is the first row's for `"first"`, the
# last row's otherwise.
-# * `sparse=True` keeps every row, on an `entry` dim with the period and cell
-# as coordinates. This also suits packages without a single cell per row
-# (HFB, MVR, OC).
+# * `sparse=True` keeps every row, on an `entry` dim, with `kper` and
+# the cell as coordinates. This also suits packages without a single cell
+# per row (HFB, MVR, OC).
wel = Wel(
parent=gwf,
@@ -207,8 +207,8 @@
ds = evt.to_xarray()
pxdp = ds["pxdp"]
-assert pxdp.dims == ("per", "nseg-1", "layer", "row", "col")
-pxdp.isel(per=0, layer=0)
+assert pxdp.dims == ("kper", "nseg-1", "layer", "row", "col")
+pxdp.isel(kper=0, layer=0)
# +
np.testing.assert_array_equal(pxdp[0, :, 0, 0, 0], [0.3, 0.6])
diff --git a/flopy4/attrs_xarray.py b/flopy4/attrs_xarray.py
index b2a4cdad..b97364b7 100644
--- a/flopy4/attrs_xarray.py
+++ b/flopy4/attrs_xarray.py
@@ -112,9 +112,9 @@ def _named_dim(field: attrs.Attribute) -> str | None:
def _period_dim(field: attrs.Attribute) -> str | None:
"""For period arrays (WELG's q, RCHA's aux), ``{kper: array}``, the dim to
- stack the given periods along, labeled by period ("q_period")."""
+ stack the given periods along, labeled by kper ("q_kper")."""
periods = field.metadata.get("fill_forward") and is_array(field)
- return f"{field.name}_period" if periods else None
+ return f"{field.name}_kper" if periods else None
def _period_shape(arrays: list) -> tuple[int, ...]:
@@ -139,7 +139,7 @@ def _period_dataarray(field: attrs.Attribute, name: str, value: dict) -> xr.Data
from flopy4.mf6._types import TimeArraySeriesRef
from flopy4.mf6.constants import FILL_DNODATA
- period, tas = f"{name}_period", f"{name}_tas"
+ period, tas = f"{name}_kper", f"{name}_tas"
if key := _named_dim(field):
names = list(dict.fromkeys(n for arrays in value.values() for n in arrays))
cells = [a for arrays in value.values() for a in arrays.values()]
@@ -183,7 +183,7 @@ def _period_value(field: attrs.Attribute, da: xr.DataArray) -> dict:
from flopy4.mf6._types import TimeArraySeriesRef
from flopy4.mf6.constants import FILL_DNODATA
- period = f"{field.name}_period"
+ period = f"{field.name}_kper"
tas = da.coords.get(f"{field.name}_tas")
periods = [int(k) for k in da[period].values]
diff --git a/flopy4/mf6/package.py b/flopy4/mf6/package.py
index a98e8ecc..d967da7c 100644
--- a/flopy4/mf6/package.py
+++ b/flopy4/mf6/package.py
@@ -1055,7 +1055,7 @@ def _array_dims(self, *names: str) -> dict[str, int]:
def to_dataarray(self, field_name: str) -> "xr.DataArray":
"""Single griddata or period array field as xr.DataArray. A period
array is the values in effect each period (see `period_array`), with
- a leading "per" dim. Stays lazy if dask-backed."""
+ a leading "kper" dim. Stays lazy if dask-backed."""
period = any(f.name == field_name for f in self._period_array_fields())
arr = self.period_array(field_name) if period else getattr(self, field_name)
if arr is None:
@@ -1097,7 +1097,7 @@ def to_dataarray(self, field_name: str) -> "xr.DataArray":
width = 1
dims = tuple(d for _, d in GRID_DIMS[width])
if nper is not None:
- dims = ("per", *dims)
+ dims = ("kper", *dims)
da = xr.DataArray(arr, dims=dims, name=field_name)
return self._with_cell_centers(da)
@@ -1122,7 +1122,7 @@ def _with_cell_centers(self, da: xr.DataArray) -> xr.DataArray:
if len(coords) < 2:
return da
da = da.assign_coords(coords)
- cells = tuple(d for d in da.dims if d != "per")
+ cells = tuple(d for d in da.dims if d != "kper")
top, botm = getattr(dis, "top", None), getattr(dis, "botm", None)
shape = tuple(da.sizes[d] for d in cells)
if cells[0] == "layer" and top is not None and botm is not None:
diff --git a/flopy4/mf6/period_lists.py b/flopy4/mf6/period_lists.py
index 35a7f12c..7a50ffd7 100644
--- a/flopy4/mf6/period_lists.py
+++ b/flopy4/mf6/period_lists.py
@@ -8,7 +8,7 @@
table's dim (``nreaches``), or with ``grid=True`` the grid via its cellid;
- the package's own index (SPC's ``bndno``): a dim named for it.
-``to_dataset`` gives each value column a ``(per, ...)`` variable, plus one
+``to_dataset`` gives each value column a ``(kper, ...)`` variable, plus one
per aux name and, for keystring packages (SFR, LAK, MAW), per setting. An
array column (EVT's pxdp) gets a dim for its size (``nseg-1``). Unset
positions are ``FILL_DNODATA``, ``FILL_INT64`` or ``None``.
@@ -22,8 +22,8 @@
"last") merges them. "sum" adds every value column, aux included; a series
can't be summed. The merged position keeps one boundname: the first row's
for "first", the last row's for "sum" and "last". ``sparse=True`` keeps
-every row along an ``entry`` dim, with period, key and setting as
-coordinates; rows without a single key (HFB, MVR, OC) have only this form.
+every row along an ``entry`` dim, with ``kper``, key and setting
+as coordinates; rows without a single key (HFB, MVR, OC) have only this form.
Use ``ds["head"]``, not ``ds.head``, which is ``Dataset.head()``.
@@ -469,14 +469,14 @@ def shape(var: _Var) -> tuple[int, ...]:
data_vars = {}
coords = {}
for n, var in variables.items():
- dims = ("per", *var.extra_dims, *var.key.dims)
+ dims = ("kper", *var.extra_dims, *var.key.dims)
data_vars[n] = xr.DataArray(_stack(frames[n], nper), dims=dims)
if n in ts_frames:
none = np.full(shape(var), None, object) # periods before its first series
series = {k: ts_frames[n].get(k, none) for k in sorted(periods)}
coords[f"{n}_ts"] = (dims, _stack(series, nper))
if bnames is not None:
- coords["boundname"] = (("per", *keys[bkey].dims), _stack(frames["boundname"], nper)) # type: ignore[index]
+ coords["boundname"] = (("kper", *keys[bkey].dims), _stack(frames["boundname"], nper)) # type: ignore[index]
return xr.Dataset(data_vars, coords=coords)
@@ -678,14 +678,14 @@ def shape(var: _Var) -> tuple[int, ...]:
data_vars = {}
coords = {}
for n, var in variables.items():
- dims = ("per", *var.extra_dims, *var.key.dims)
+ dims = ("kper", *var.extra_dims, *var.key.dims)
data_vars[n] = xr.DataArray(_stack(frames[n], nper), dims=dims)
if n in has_ts:
none = np.full(shape(var), None, object) # periods without series
series = {k: ts_frames[n].get(k, none) for k in sorted(periods)}
coords[f"{n}_ts"] = (dims, _stack(series, nper))
if with_bnames:
- coords["boundname"] = (("per", *key.dims), _stack(bframes, nper))
+ coords["boundname"] = (("kper", *key.dims), _stack(bframes, nper))
return xr.Dataset(data_vars, coords=coords)
@@ -942,7 +942,7 @@ def _block_rows(
key, back = keys[layout.settings[0].key.name]
spd: dict[int, Any] = {}
prev: Optional[dict] = None
- for p in range(dense.ds.sizes["per"]):
+ for p in range(dense.ds.sizes["kper"]):
now = dense.period(p)
if prev is not None and not any(_changed(now[n], prev[n]).any() for n in now):
continue
@@ -974,7 +974,7 @@ def _setting_rows(
for n in [n for n in prev if f"{n}_ts" in first]:
prev[f"{n}_ts"] = np.full(prev[n].shape, None, object)
spd: dict[int, list] = {}
- for p in range(dense.ds.sizes["per"]):
+ for p in range(dense.ds.sizes["kper"]):
now = dense.period(p)
changed = {n: _changed(now[n], prev[n]) for n in prev if not n.endswith("_ts")}
for n in changed:
@@ -1185,7 +1185,7 @@ def put_block(
n += len(rows)
data_vars: dict[str, Any] = {}
- coords: dict[str, Any] = {"per": ("entry", np.concatenate(per))}
+ coords: dict[str, Any] = {"kper": ("entry", np.concatenate(per))}
if union:
coords["setting"] = ("entry", np.array(keywords, dtype=object))
for name, col in columns.items():
@@ -1300,7 +1300,7 @@ def _sparse_tables(pkg: Any, ds: xr.Dataset, item: Any, names: dict) -> Optional
table = ItemTable.from_columns(item, n, given)
if table is None:
return None
- per = ds.coords["per"].values.astype(np.int64)
+ per = ds.coords["kper"].values.astype(np.int64)
spd: dict[int, Any] = {int(k): ItemTable(item, {}, 0) for k in ds.attrs.get("periods", [])}
order = np.argsort(per, kind="stable")
kpers, starts = np.unique(per[order], return_index=True)
@@ -1334,7 +1334,7 @@ def _from_sparse(pkg: Any, ds: xr.Dataset) -> dict[int, Any]:
words, arms = cast(tuple, _union_field_arms(item, arm_field))
by_keyword = {a.keyword().upper(): a for a in arms}
aux = _aux_names(pkg)
- names = {**ds.data_vars, **{c: ds.coords[c] for c in ds.coords if c not in ("per", "setting")}}
+ names = {**ds.data_vars, **{c: ds.coords[c] for c in ds.coords if c not in ("kper", "setting")}}
if not arms and "setting" not in ds.coords:
if (tables := _sparse_tables(pkg, ds, item, names)) is not None:
return tables
@@ -1368,7 +1368,7 @@ def kwargs_for(cls: type, i: int) -> dict[str, Any]:
n = ds.sizes["entry"]
spd: dict[int, list] = {int(k): [] for k in ds.attrs.get("periods", [])}
for i in range(n):
- kper = int(ds.coords["per"].values[i])
+ kper = int(ds.coords["kper"].values[i])
keyword = ds.coords["setting"].values[i] if "setting" in ds.coords else None
if keyword is not None and str(keyword).upper() in words:
row: Any = str(keyword).upper()
diff --git a/test/mf6/test_mf6_component.py b/test/mf6/test_mf6_component.py
index d80013d9..6a97966c 100644
--- a/test/mf6/test_mf6_component.py
+++ b/test/mf6/test_mf6_component.py
@@ -3058,7 +3058,7 @@ def test_to_dataarray_period_arrays_on_cells():
gwf.rch = [Rcha(recharge={0: 0.1, 2: np.full(6, 0.3)})]
da = gwf.rch[0].to_dataarray("recharge")
- assert da.dims == ("per", "layer", "row", "col")
+ assert da.dims == ("kper", "layer", "row", "col")
assert da.shape == (3, 1, 2, 3)
# period 1 fills forward from period 0, a constant filled to the grid
assert da.values[:, 0, 0, 0].tolist() == [0.1, 0.1, 0.3]
@@ -3681,8 +3681,8 @@ def test_to_xarray_period_arrays_share_periods_without_nper():
irch={0: np.array([0, 1])},
)
ds = rch.to_xarray()
- assert ds.sizes["per"] == 2
- np.testing.assert_array_equal(ds["irch"].isel(per=0), ds["irch"].isel(per=1))
+ assert ds.sizes["kper"] == 2
+ np.testing.assert_array_equal(ds["irch"].isel(kper=0), ds["irch"].isel(kper=1))
assert rch.period_array("irch").shape[0] == 2
assert rch.period_array("irch", nper=4).shape[0] == 4
@@ -3706,6 +3706,6 @@ def test_to_dataarray_period_constants_need_a_shape():
rch = Rcha(recharge={0: 0.1, 1: 0.2}, irch={0: 1}, dims={"ncpl": 4})
ds = rch.to_xarray()
- assert ds["recharge"].dims == ("per", "layer", "cell")
+ assert ds["recharge"].dims == ("kper", "layer", "cell")
assert ds["recharge"].shape == (2, 1, 4)
- assert (ds["recharge"].isel(per=1) == 0.2).all()
+ assert (ds["recharge"].isel(kper=1) == 0.2).all()
diff --git a/test/mf6/test_mf6_period_arrays.py b/test/mf6/test_mf6_period_arrays.py
index 25d8dce1..24e40e74 100644
--- a/test/mf6/test_mf6_period_arrays.py
+++ b/test/mf6/test_mf6_period_arrays.py
@@ -155,8 +155,8 @@ def test_welg_xarray_round_trip_keeps_periods():
)
assert welg.q[2] is None
ds = attrs_to_dataset(welg)
- assert ds["q"].dims == ("q_period", "nodes")
- assert list(ds["q_period"].values) == [0, 2]
+ assert ds["q"].dims == ("q_kper", "nodes")
+ assert list(ds["q_kper"].values) == [0, 2]
np.testing.assert_array_equal(ds["q"].values[1], [NODATA, NODATA])
loaded = dataset_to_attrs(Welg, ds)
assert loaded == welg
@@ -166,7 +166,7 @@ def test_welg_xarray_round_trip_keeps_periods():
def test_rcha_to_dataarray_fills_forward():
rcha = Rcha(recharge={0: np.array([0.1, 0.2]), 2: np.array([0.3, 0.4])})
da = rcha.to_dataarray("recharge")
- assert da.dims == ("per", "node")
+ assert da.dims == ("kper", "node")
np.testing.assert_array_equal(da.values[1], [0.1, 0.2])
@@ -221,14 +221,14 @@ def test_tas_reference_xarray_coordinate(tmp_path):
)
ds = attrs_to_dataset(rcha)
recharge = ds["recharge"]
- assert list(recharge["recharge_period"].values) == [0, 2]
+ assert list(recharge["recharge_kper"].values) == [0, 2]
assert recharge["recharge_tas"].values[0] == "rch"
assert pd.isnull(recharge["recharge_tas"].values[1])
- assert np.isnan(recharge.sel(recharge_period=0)).all()
+ assert np.isnan(recharge.sel(recharge_kper=0)).all()
# the coordinate goes along with the data
- assert recharge.isel(recharge_period=0)["recharge_tas"].item() == "rch"
- assert ds["aux"]["aux_tas"].sel(aux_period=0, aux_name="conc").item() == "cs"
- assert np.isnan(ds["aux"].sel(aux_period=0, aux_name="conc")).all()
+ assert recharge.isel(recharge_kper=0)["recharge_tas"].item() == "rch"
+ assert ds["aux"]["aux_tas"].sel(aux_kper=0, aux_name="conc").item() == "cs"
+ assert np.isnan(ds["aux"].sel(aux_kper=0, aux_name="conc")).all()
path = tmp_path / "rcha.nc"
ds.drop_attrs().to_netcdf(path)
diff --git a/test/mf6/test_mf6_period_lists.py b/test/mf6/test_mf6_period_lists.py
index a46ac1ad..941daef1 100644
--- a/test/mf6/test_mf6_period_lists.py
+++ b/test/mf6/test_mf6_period_lists.py
@@ -24,7 +24,7 @@ def round_trips(pkg, **kwargs):
def test_chd_on_grid_carries_periods_forward():
chd = Chd(period_data={0: [((0, 0, 0), 1.0), ((0, 1, 2), 2.0)], 2: []}, dims=DIMS)
head = chd.to_xarray()["head"]
- assert head.dims == ("per", "layer", "row", "col")
+ assert head.dims == ("kper", "layer", "row", "col")
expected = np.full((2, 3), NODATA)
expected[0, 0], expected[1, 2] = 1.0, 2.0
np.testing.assert_array_equal(head.values[0, 0], expected)
@@ -62,7 +62,7 @@ def test_array_column_has_a_dim_named_for_its_size():
dims=DIMS,
)
ds = evt.to_xarray()
- assert ds["pxdp"].dims == ("per", "nseg-1", "layer", "row", "col")
+ assert ds["pxdp"].dims == ("kper", "nseg-1", "layer", "row", "col")
np.testing.assert_array_equal(ds["pxdp"].values[0, :, 0, 0, 0], [0.3, 0.6])
assert "petm0" not in ds # optional, and no row gives it
round_trips(evt)
@@ -84,7 +84,7 @@ def test_conditional_column():
def test_disv_grid():
chd = Chd(period_data={0: [((1, 2), 1.0)]}, dims={"nlay": 2, "ncpl": 4, "nper": 1})
head = chd.to_xarray()["head"]
- assert head.dims == ("per", "layer", "cell")
+ assert head.dims == ("kper", "layer", "cell")
assert head.values[0, 1, 2] == 1.0
round_trips(chd)
@@ -96,7 +96,7 @@ def test_boundnames_are_a_coordinate():
dims=DIMS,
)
ds = chd.to_xarray()
- assert ds.coords["boundname"].dims == ("per", "layer", "row", "col")
+ assert ds.coords["boundname"].dims == ("kper", "layer", "row", "col")
assert ds.coords["boundname"].values[2, 0, 0, 0] == "a"
assert pd.isnull(ds.coords["boundname"].values[0, 0, 1, 1])
round_trips(chd)
@@ -274,14 +274,14 @@ def uzf():
def test_uzf_rows_are_on_the_feature_dim():
ds = uzf().to_xarray()
- assert ds["finf"].dims == ("per", "nuzfcells")
+ assert ds["finf"].dims == ("kper", "nuzfcells")
np.testing.assert_array_equal(ds["finf"].values[0], [NODATA, 0.01])
round_trips(uzf())
def test_uzf_rows_on_the_grid_through_packagedata():
ds = uzf().to_xarray(grid=True)
- assert ds["finf"].dims == ("per", "layer", "row", "col")
+ assert ds["finf"].dims == ("kper", "layer", "row", "col")
assert ds["finf"].values[0, 0, 1, 0] == 0.01
round_trips(uzf(), grid=True)
@@ -299,7 +299,7 @@ def test_sfr_settings_are_variables_per_setting():
)
ds = pkg.to_xarray()
assert set(ds.data_vars) == {"status", "inflow"}
- assert ds["inflow"].dims == ("per", "nreaches")
+ assert ds["inflow"].dims == ("kper", "nreaches")
np.testing.assert_array_equal(ds["inflow"].values[0], [1.0, NODATA, 3.0])
# settings hold until set again: reach 0's inflow carries past period 2
np.testing.assert_array_equal(ds["inflow"].values[2], [1.0, NODATA, 4.0])
@@ -311,7 +311,7 @@ def test_sfr_settings_are_variables_per_setting():
def test_sfr_setting_index_is_a_dim():
pkg = sfr({0: [(0, "diversion", 1, 0.5)]})
ds = pkg.to_xarray()
- assert ds["divflow"].dims == ("per", "idv", "nreaches")
+ assert ds["divflow"].dims == ("kper", "idv", "nreaches")
assert ds["divflow"].values[0, 1, 0] == 0.5
assert ds["divflow"].values[0, 0, 0] == NODATA
round_trips(pkg)
@@ -340,8 +340,8 @@ def test_lak_settings_are_on_their_keys_dims():
dims=DIMS,
)
ds = lak.to_xarray()
- assert ds["stage"].dims == ("per", "nlakes")
- assert ds["rate"].dims == ("per", "noutlets")
+ assert ds["stage"].dims == ("kper", "nlakes")
+ assert ds["rate"].dims == ("kper", "noutlets")
round_trips(lak)
@@ -417,6 +417,7 @@ def test_sparse_round_trips(pkg):
p = pkg()
ds = p.to_xarray(sparse=True)
assert "entry" in ds.dims
+ assert ds.coords["kper"].dims == ("entry",)
round_trips(p, sparse=True)