diff --git a/docs/whats_new.md b/docs/whats_new.md index 44814b9..866ac6c 100644 --- a/docs/whats_new.md +++ b/docs/whats_new.md @@ -1,5 +1,8 @@ # What's New +## v0.5.1 (September 14, 2023) +* renamed all references to "divergence" to "convergence" instead + ## v0.5.0 (September 12, 2023) * the mixed layer depth function now returns positive values diff --git a/xroms/__init__.py b/xroms/__init__.py index 61cd897..ccbb405 100644 --- a/xroms/__init__.py +++ b/xroms/__init__.py @@ -8,7 +8,7 @@ from .derived import ( EKE, KE, - divergence, + convergence, dudz, dvdz, ertel, diff --git a/xroms/accessor.py b/xroms/accessor.py index a740c9e..9099dcf 100644 --- a/xroms/accessor.py +++ b/xroms/accessor.py @@ -13,7 +13,7 @@ from .derived import ( EKE, KE, - divergence, + convergence, dudz, dvdz, ertel, @@ -549,64 +549,64 @@ def find_horizontal_velocities(self): return vel_use @property - def div(self): - """Calculate divergence, rho/rho grid. + def convergence(self): + """Calculate convergence, rho/rho grid. Notes ----- - See `xroms.divergence` for full docstring. + See `xroms.convergence` for full docstring. `hboundary` and `sboundary` both set to 'extend'. Examples -------- - >>> ds.xroms.div + >>> ds.xroms.convergence """ - if "div" not in self.ds: + if "convergence" not in self.ds: # # find names of horizontal velocities, in case they are different # # just need to be ortogonal. # uname, vname = self.find_horizontal_velocities() - var = divergence( + var = convergence( self.u, self.v, self.xgrid, hboundary="extend", sboundary="extend", ) - self.ds["div"] = var - return self.ds.div + self.ds["convergence"] = var + return self.ds.convergence @property - def div_norm(self): - """Calculate normalized surface divergence, rho/rho grid. + def convergence_norm(self): + """Calculate normalized surface convergence, rho/rho grid. The surface currents are selected for this calculation, so return is `[T,Y,X]`. - The divergence is normalized by $f$. It is dimensionless. + The convergence is normalized by $f$. It is dimensionless. Notes ----- - See `xroms.divergence` for full docstring. + See `xroms.convergence` for full docstring. `hboundary` and `sboundary` both set to 'extend'. Examples -------- - >>> ds.xroms.div_norm + >>> ds.xroms.convergence_norm """ - if "div_norm" not in self.ds: - var = self.div - self.ds["div_norm"] = var.cf.isel(Z=-1) / self.ds.f - self.ds["div_norm"].name = "normalized surface horizontal divergence" + if "convergence_norm" not in self.ds: + var = self.convergence + self.ds["convergence_norm"] = var.cf.isel(Z=-1) / self.ds.f + self.ds["convergence_norm"].name = "convergence_norm" attrs = { - "name": "div_norm", - "long_name": "normalized surface horizontal divergence", + "name": "convergence_norm", + "long_name": "normalized surface horizontal convergence", "units": "", } - self.ds["div_norm"].attrs = attrs + self.ds["convergence_norm"].attrs = attrs - return self.ds.div_norm + return self.ds.convergence_norm @property def ertel(self): diff --git a/xroms/derived.py b/xroms/derived.py index c9965e6..33a8fc2 100644 --- a/xroms/derived.py +++ b/xroms/derived.py @@ -513,7 +513,7 @@ def relative_vorticity( return var -def divergence( +def convergence( u: xr.DataArray, v: xr.DataArray, xgrid, @@ -522,7 +522,7 @@ def divergence( sboundary="extend", sfill_value=None, ) -> xr.DataArray: - """Calculate 2D divergence from u and v [1/s]. + """Calculate 2D convergence from u and v [1/s]. Parameters ---------- @@ -567,19 +567,19 @@ def divergence( Returns ------- - DataArray of 2D divergence of horizontal currents on rho/rho grids. + DataArray of 2D convergence of horizontal currents on rho/rho grids. Output is `[T,Z,Y,X]`. Notes ----- - 2D divergence = u_x + v_y + 2D convergence = u_x + v_y Resource for more information: https://uw.pressbooks.pub/ocean285/chapter/the-divergence/ Examples -------- >>> ds, xgrid = xroms.roms_dataset(ds) - >>> xroms.divergence(u, v, xgrid) + >>> xroms.convergence(u, v, xgrid) """ assert isinstance(u, xr.DataArray), "u must be DataArray" @@ -608,8 +608,8 @@ def divergence( var = dudxi + dvdeta - var.attrs["name"] = "div" - var.attrs["long_name"] = "horizontal divergence" + var.attrs["name"] = "convergence" + var.attrs["long_name"] = "horizontal convergence" var.attrs["units"] = "1/s" var.name = var.attrs["name"] diff --git a/xroms/tests/test_accessor.py b/xroms/tests/test_accessor.py index 44839a4..3debff6 100644 --- a/xroms/tests/test_accessor.py +++ b/xroms/tests/test_accessor.py @@ -235,15 +235,15 @@ def test_relative_vorticity(): assert acc.cf[coordname].name == coord -def test_div(): - acc = ds.xroms.div - assert np.allclose(acc, xroms.divergence(ds["u"], ds["v"], grid)) +def test_convergence(): + acc = ds.xroms.convergence + assert np.allclose(acc, xroms.convergence(ds["u"], ds["v"], grid)) -def test_div_norm(): - acc = ds.xroms.div_norm +def test_convergence_norm(): + acc = ds.xroms.convergence_norm assert np.allclose( - acc, xroms.divergence(ds["u"], ds["v"], grid).cf.isel(Z=-1) / ds["f"] + acc, xroms.convergence(ds["u"], ds["v"], grid).cf.isel(Z=-1) / ds["f"] ) diff --git a/xroms/tests/test_derived.py b/xroms/tests/test_derived.py index ce20dd5..1ad83bb 100644 --- a/xroms/tests/test_derived.py +++ b/xroms/tests/test_derived.py @@ -103,12 +103,12 @@ def test_relative_vorticity(): assert np.allclose(xroms.relative_vorticity(ds.u, ds.v, grid), 0) -def test_divergence(): +def test_convergence(): dudxi = (ds.u[0, -1, 0, 2] - ds.u[0, -1, 0, 0]) / (ds.dx[0, 1] + ds.dx[0, 0]) dvdeta = (ds.v[0, -1, 2, 0] - ds.v[0, -1, 0, 0]) / (ds.dy[1, 0] + ds.dy[0, 0]) calc = dudxi + dvdeta - # choose middle divergence value in depth because of boundary effects? - assert np.allclose(xroms.divergence(ds.u, ds.v, grid)[0, 1, 1, 1], calc, atol=2e8) + # choose middle convergence value in depth because of boundary effects? + assert np.allclose(xroms.convergence(ds.u, ds.v, grid)[0, 1, 1, 1], calc, atol=2e8) def test_ertel():