deploy: db643c1

_modules/xugrid/ugrid/ugrid2d.html

@@ -2626,9 +2626,9 @@ <h1>Source code for xugrid.ugrid.ugrid2d</h1><div class="highlight"><pre>
 <span class="sd">        Parameters</span>
 <span class="sd">        ----------</span>
 <span class="sd">        x_intervals: np.ndarray of shape (M + 1,)</span>
-<span class="sd">            x-coordinate interval values for N row and M columns.</span>
+<span class="sd">            x-coordinate interval values for N rows and M columns.</span>
 <span class="sd">        y_intervals: np.ndarray of shape (N + 1,)</span>
-<span class="sd">            y-coordinate interval values for N row and M columns.</span>
+<span class="sd">            y-coordinate interval values for N rows and M columns.</span>
 <span class="sd">        name: str</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">x_intervals</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">asarray</span><span class="p">(</span><span class="n">x_intervals</span><span class="p">)</span>
@@ -2655,9 +2655,9 @@ <h1>Source code for xugrid.ugrid.ugrid2d</h1><div class="highlight"><pre>
 <span class="sd">        Parameters</span>
 <span class="sd">        ----------</span>
 <span class="sd">        x_intervals: np.ndarray of shape shape (N + 1, M + 1)</span>
-<span class="sd">            x-coordinate interval values for N row and M columns.</span>
+<span class="sd">            x-coordinate interval values for N rows and M columns.</span>
 <span class="sd">        y_intervals: np.ndarray of shape shape (N + 1, M + 1)</span>
-<span class="sd">            y-coordinate interval values for N row and M columns.</span>
+<span class="sd">            y-coordinate interval values for N rows and M columns.</span>
 <span class="sd">        name: str</span>
 <span class="sd">        &quot;&quot;&quot;</span>
         <span class="n">x_intervals</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">asarray</span><span class="p">(</span><span class="n">x_intervals</span><span class="p">)</span>
@@ -2684,30 +2684,63 @@ <h1>Source code for xugrid.ugrid.ugrid2d</h1><div class="highlight"><pre>
         <span class="n">x_bounds</span><span class="p">:</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span>
         <span class="n">y_bounds</span><span class="p">:</span> <span class="n">np</span><span class="o">.</span><span class="n">ndarray</span><span class="p">,</span>
         <span class="n">name</span><span class="p">:</span> <span class="nb">str</span> <span class="o">=</span> <span class="s2">&quot;mesh2d&quot;</span><span class="p">,</span>
-    <span class="p">)</span> <span class="o">-&gt;</span> <span class="s2">&quot;Ugrid2d&quot;</span><span class="p">:</span>
+        <span class="n">return_index</span><span class="p">:</span> <span class="nb">bool</span> <span class="o">=</span> <span class="kc">False</span><span class="p">,</span>
+    <span class="p">)</span> <span class="o">-&gt;</span> <span class="n">Union</span><span class="p">[</span><span class="s2">&quot;Ugrid2d&quot;</span><span class="p">,</span> <span class="n">Tuple</span><span class="p">[</span><span class="s2">&quot;Ugrid2d&quot;</span><span class="p">,</span> <span class="n">Union</span><span class="p">[</span><span class="n">BoolArray</span><span class="p">,</span> <span class="nb">slice</span><span class="p">]]]:</span>
 <span class="w">        </span><span class="sd">&quot;&quot;&quot;</span>
-<span class="sd">        Create a Ugrid2d topology from a structured topology based on 1D bounds.</span>
+<span class="sd">        Create a Ugrid2d topology from a structured topology based on 2D or 3D</span>
+<span class="sd">        bounds.</span>
 
-<span class="sd">        The bounds contain the lower and upper cell boundary for each cell.</span>
+<span class="sd">        The bounds contain the lower and upper cell boundary for each cell for</span>
+<span class="sd">        2D, and the four corner vertices in case of 3D bounds. The order of the</span>
+<span class="sd">        corners in bounds_x and bounds_y must be consistent with each other,</span>
+<span class="sd">        but may be arbitrary: this method ensures counterclockwise orientation</span>
+<span class="sd">        for UGRID. Inactive cells are assumed to be marked with one or more NaN</span>
+<span class="sd">        values for their corner coordinates. These coordinates are discarded</span>
+<span class="sd">        and the cells are marked in the optionally returned index.</span>
 
 <span class="sd">        Parameters</span>
 <span class="sd">        ----------</span>
-<span class="sd">        x_bounds: np.ndarray of shape (M, 2)</span>
-<span class="sd">            x-coordinate bounds for N row and M columns.</span>
-<span class="sd">        y_bounds: np.ndarray of shape (N, 2)</span>
-<span class="sd">            y-coordinate bounds for N row and M columns.</span>
+<span class="sd">        x_bounds: np.ndarray of shape (M, 2) or (N, M, 4).</span>
+<span class="sd">            x-coordinate bounds for N rows and M columns.</span>
+<span class="sd">        y_bounds: np.ndarray of shape (N, 2) or (N, M, 4).</span>
+<span class="sd">            y-coordinate bounds for N rows and M columns.</span>
 <span class="sd">        name: str</span>
+<span class="sd">        return_index: bool, default is False.</span>
 
 <span class="sd">        Returns</span>
 <span class="sd">        -------</span>
 <span class="sd">        grid: Ugrid2d</span>
+<span class="sd">        index: np.ndarray of bool | slice</span>
+<span class="sd">            Indicates which cells are part of the Ugrid2d topology.</span>
+<span class="sd">            Provided if ``return_index`` is True.</span>
 <span class="sd">        &quot;&quot;&quot;</span>
-        <span class="n">nx</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">x_bounds</span><span class="o">.</span><span class="n">shape</span>
-        <span class="n">ny</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">y_bounds</span><span class="o">.</span><span class="n">shape</span>
-        <span class="n">x</span> <span class="o">=</span> <span class="n">conversion</span><span class="o">.</span><span class="n">bounds_to_vertices</span><span class="p">(</span><span class="n">x_bounds</span><span class="p">)</span>
-        <span class="n">y</span> <span class="o">=</span> <span class="n">conversion</span><span class="o">.</span><span class="n">bounds_to_vertices</span><span class="p">(</span><span class="n">y_bounds</span><span class="p">)</span>
-        <span class="n">node_y</span><span class="p">,</span> <span class="n">node_x</span> <span class="o">=</span> <span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">ravel</span><span class="p">()</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">np</span><span class="o">.</span><span class="n">meshgrid</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">indexing</span><span class="o">=</span><span class="s2">&quot;ij&quot;</span><span class="p">))</span>
-        <span class="k">return</span> <span class="n">Ugrid2d</span><span class="o">.</span><span class="n">_from_intervals_helper</span><span class="p">(</span><span class="n">node_x</span><span class="p">,</span> <span class="n">node_y</span><span class="p">,</span> <span class="n">nx</span><span class="p">,</span> <span class="n">ny</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span></div>
+        <span class="n">x_shape</span> <span class="o">=</span> <span class="n">x_bounds</span><span class="o">.</span><span class="n">shape</span>
+        <span class="n">y_shape</span> <span class="o">=</span> <span class="n">y_bounds</span><span class="o">.</span><span class="n">shape</span>
+        <span class="n">ndim</span> <span class="o">=</span> <span class="n">x_bounds</span><span class="o">.</span><span class="n">ndim</span>
+        <span class="k">if</span> <span class="n">ndim</span> <span class="o">==</span> <span class="mi">2</span><span class="p">:</span>
+            <span class="n">nx</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">x_shape</span>
+            <span class="n">ny</span><span class="p">,</span> <span class="n">_</span> <span class="o">=</span> <span class="n">y_shape</span>
+            <span class="n">x</span> <span class="o">=</span> <span class="n">conversion</span><span class="o">.</span><span class="n">bounds1d_to_vertices</span><span class="p">(</span><span class="n">x_bounds</span><span class="p">)</span>
+            <span class="n">y</span> <span class="o">=</span> <span class="n">conversion</span><span class="o">.</span><span class="n">bounds1d_to_vertices</span><span class="p">(</span><span class="n">y_bounds</span><span class="p">)</span>
+            <span class="n">node_y</span><span class="p">,</span> <span class="n">node_x</span> <span class="o">=</span> <span class="p">(</span><span class="n">a</span><span class="o">.</span><span class="n">ravel</span><span class="p">()</span> <span class="k">for</span> <span class="n">a</span> <span class="ow">in</span> <span class="n">np</span><span class="o">.</span><span class="n">meshgrid</span><span class="p">(</span><span class="n">y</span><span class="p">,</span> <span class="n">x</span><span class="p">,</span> <span class="n">indexing</span><span class="o">=</span><span class="s2">&quot;ij&quot;</span><span class="p">))</span>
+            <span class="n">grid</span> <span class="o">=</span> <span class="n">Ugrid2d</span><span class="o">.</span><span class="n">_from_intervals_helper</span><span class="p">(</span><span class="n">node_x</span><span class="p">,</span> <span class="n">node_y</span><span class="p">,</span> <span class="n">nx</span><span class="p">,</span> <span class="n">ny</span><span class="p">,</span> <span class="n">name</span><span class="p">)</span>
+            <span class="n">index</span> <span class="o">=</span> <span class="nb">slice</span><span class="p">(</span><span class="kc">None</span><span class="p">,</span> <span class="kc">None</span><span class="p">)</span>
+        <span class="k">elif</span> <span class="n">ndim</span> <span class="o">==</span> <span class="mi">3</span><span class="p">:</span>
+            <span class="k">if</span> <span class="n">x_shape</span> <span class="o">!=</span> <span class="n">y_shape</span><span class="p">:</span>
+                <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span>
+                    <span class="sa">f</span><span class="s2">&quot;Bounds shapes do not match: </span><span class="si">{</span><span class="n">x_shape</span><span class="si">}</span><span class="s2"> versus </span><span class="si">{</span><span class="n">y_shape</span><span class="si">}</span><span class="s2">&quot;</span>
+                <span class="p">)</span>
+            <span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="n">face_node_connectivity</span><span class="p">,</span> <span class="n">index</span> <span class="o">=</span> <span class="n">conversion</span><span class="o">.</span><span class="n">bounds2d_to_topology2d</span><span class="p">(</span>
+                <span class="n">x_bounds</span><span class="p">,</span> <span class="n">y_bounds</span>
+            <span class="p">)</span>
+            <span class="n">grid</span> <span class="o">=</span> <span class="n">Ugrid2d</span><span class="p">(</span><span class="n">x</span><span class="p">,</span> <span class="n">y</span><span class="p">,</span> <span class="o">-</span><span class="mi">1</span><span class="p">,</span> <span class="n">face_node_connectivity</span><span class="p">,</span> <span class="n">name</span><span class="o">=</span><span class="n">name</span><span class="p">)</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="sa">f</span><span class="s2">&quot;Expected 2 or 3 dimensions on bounds, received: </span><span class="si">{</span><span class="n">ndim</span><span class="si">}</span><span class="s2">&quot;</span><span class="p">)</span>
+
+        <span class="k">if</span> <span class="n">return_index</span><span class="p">:</span>
+            <span class="k">return</span> <span class="n">grid</span><span class="p">,</span> <span class="n">index</span>
+        <span class="k">else</span><span class="p">:</span>
+            <span class="k">return</span> <span class="n">grid</span></div>
 
 
     <span class="nd">@staticmethod</span>

_sources/api.rst.txt

@@ -43,7 +43,7 @@ UgridDataArray
 
     UgridDataArray
     UgridDataArray.ugrid
-    UgridDataArray.from_structured
+    UgridDataArray.from_structured2d
     UgridDataArray.from_data
 
 UgridDataset
@@ -55,7 +55,7 @@ UgridDataset
     UgridDataset
     UgridDataset.ugrid
     UgridDataset.from_geodataframe
-    UgridDataset.from_structured
+    UgridDataset.from_structured2d
 
 UGRID Accessor
 --------------

_sources/api/xugrid.UgridDataArray.from_structured2d.rst.txt

@@ -0,0 +1,6 @@
+xugrid.UgridDataArray.from\_structured2d
+========================================
+
+.. currentmodule:: xugrid
+
+.. automethod:: UgridDataArray.from_structured2d

_sources/api/xugrid.UgridDataArray.rst.txt

@@ -63,6 +63,7 @@
       ~UgridDataArray.from_iris
       ~UgridDataArray.from_series
       ~UgridDataArray.from_structured
+      ~UgridDataArray.from_structured2d
       ~UgridDataArray.get_axis_num
       ~UgridDataArray.get_index
       ~UgridDataArray.groupby

_sources/api/xugrid.UgridDataset.from_structured2d.rst.txt

@@ -0,0 +1,6 @@
+xugrid.UgridDataset.from\_structured2d
+======================================
+
+.. currentmodule:: xugrid
+
+.. automethod:: UgridDataset.from_structured2d

_sources/api/xugrid.UgridDataset.rst.txt

@@ -67,6 +67,7 @@
       ~UgridDataset.from_dict
       ~UgridDataset.from_geodataframe
       ~UgridDataset.from_structured
+      ~UgridDataset.from_structured2d
       ~UgridDataset.get
       ~UgridDataset.get_index
       ~UgridDataset.groupby

_sources/changelog.rst.txt

@@ -9,6 +9,29 @@ The format is based on `Keep a Changelog`_, and this project adheres to
 Unreleased
 ----------
 
+Changed
+~~~~~~~
+
+- :meth:`xugrid.UgridDataset.from_structured` and
+  :meth:`xugrid.UgridDataArray.from_structured` are deprecated and will be
+  removed in the future; calling them will raise a FutureWarning. They have
+  been replaced by :meth:`xugrid.UgridDataset.from_structured2d` and
+  :meth:`xugrid.UgridDataArray.from_structured2d` respectively.
+
+Added
+~~~~~
+
+- :meth:`xugrid.Ugrid2d.from_structured_bounds` now accepts 3D bounds to allow
+  conversion of grids with non-monotonic x and y coordinates, such as strongly
+  curvilinear grids.
+- :meth:`xugrid.Ugrid2d.from_structured_bounds` now takes an optional
+  ``return_index`` argument to return the indices of invalid grid faces,
+  identified by one or more NaNs in its bounds.
+- This method is used in :meth:`xugrid.UgridDataArray.from_structured2d` and
+  :meth:`xugrid.UgridDataset.from_structured2d` when the optional arguments
+  ``x_bounds`` and ``y_bounds`` are provided.
+
+
 [0.12.2] 2025-01-31
 -------------------
 

_sources/examples-dev/sg_execution_times.rst.txt

@@ -6,7 +6,7 @@
 
 Computation times
 =================
-**00:01.367** total execution time for 1 file **from examples-dev**:
+**00:01.334** total execution time for 1 file **from examples-dev**:
 
 .. container::
 
@@ -33,5 +33,5 @@ Computation times
      - Time
      - Mem (MB)
    * - :ref:`sphx_glr_examples-dev_voronoi.py` (``voronoi.py``)
-     - 00:01.367
+     - 00:01.334
      - 0.0

_sources/examples-dev/voronoi.rst.txt

@@ -666,7 +666,7 @@ The figure shows:
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 1.367 seconds)
+   **Total running time of the script:** (0 minutes 1.334 seconds)
 
 
 .. _sphx_glr_download_examples-dev_voronoi.py:

_sources/examples/connectivity.rst.txt

@@ -129,7 +129,7 @@ By default, the border value for binary erosion is set to ``False`` (equal to
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f5ca34499a0>
+    <matplotlib.collections.PolyCollection object at 0x7f416d300e00>
 
 
 
@@ -165,7 +165,7 @@ start by setting a single value in the center of the grid to ``True``.
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f5c9a68bda0>
+    <matplotlib.collections.PolyCollection object at 0x7f4176cdda90>
 
 
 
@@ -200,7 +200,7 @@ alternative border value:
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f5c9a72c500>
+    <matplotlib.collections.PolyCollection object at 0x7f4176defc20>
 
 
 
@@ -238,7 +238,7 @@ analyse connected parts of the mesh.
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f5c9a764890>
+    <matplotlib.collections.PolyCollection object at 0x7f4177e2ae70>
 
 
 
@@ -272,7 +272,7 @@ Tesselation.
  .. code-block:: none
 
 
-    <matplotlib.collections.LineCollection object at 0x7f5c99ae3a10>
+    <matplotlib.collections.LineCollection object at 0x7f4176cae810>
 
 
 
@@ -316,7 +316,7 @@ the original.
  .. code-block:: none
 
 
-    <matplotlib.collections.LineCollection object at 0x7f5ca483a180>
+    <matplotlib.collections.LineCollection object at 0x7f416d292300>
 
 
 
@@ -355,7 +355,7 @@ We can break down one of the Voronoi tesselations from above into triangles:
  .. code-block:: none
 
 
-    <matplotlib.collections.LineCollection object at 0x7f5c99ba6d80>
+    <matplotlib.collections.LineCollection object at 0x7f416d1989e0>
 
 
 
@@ -409,7 +409,7 @@ the upper and lower parts:
  .. code-block:: none
 
 
-    <matplotlib.collections.LineCollection object at 0x7f5c9a9ef5f0>
+    <matplotlib.collections.LineCollection object at 0x7f4177bc9820>
 
 
 
@@ -439,7 +439,7 @@ We can now use Laplace interpolation to fill the gaps in the grid.
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f5c9a962990>
+    <matplotlib.collections.PolyCollection object at 0x7f416e1c24e0>
 
 
 
@@ -477,7 +477,7 @@ interpolation.
  .. code-block:: none
 
 
-    <matplotlib.collections.PolyCollection object at 0x7f5c9996ea20>
+    <matplotlib.collections.PolyCollection object at 0x7f416d1da330>
 
 
 
@@ -518,7 +518,7 @@ To illustrate, let's take a look at the connectivity matrix of the Xoxo grid.
  .. code-block:: none
 
 
-    <matplotlib.image.AxesImage object at 0x7f5c9a420a40>
+    <matplotlib.image.AxesImage object at 0x7f416ce37f50>
 
 
 
@@ -554,14 +554,14 @@ locality:
  .. code-block:: none
 
 
-    <matplotlib.image.AxesImage object at 0x7f5c999574a0>
+    <matplotlib.image.AxesImage object at 0x7f416d2b6ba0>
 
 
 
 
 .. rst-class:: sphx-glr-timing
 
-   **Total running time of the script:** (0 minutes 1.432 seconds)
+   **Total running time of the script:** (0 minutes 1.426 seconds)
 
 
 .. _sphx_glr_download_examples_connectivity.py: