grid-apps 0.1.0b1__tar.gz

grid_apps-0.1.0b1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2025 Mira Geoscience
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

grid_apps-0.1.0b1/PKG-INFO

@@ -0,0 +1,105 @@
+Metadata-Version: 2.4
+Name: grid-apps
+Version: 0.1.0b1
+Summary: Grid creation and manipulation using GEOH5 format.
+License-Expression: MIT
+License-File: LICENSE
+License-File: docs/source/THIRD_PARTY_SOFTWARE.rst
+Keywords: geology,geophysics,earth sciences
+Author: Mira Geoscience
+Author-email: support@mirageoscience.com
+Maintainer: Benjamin Kary
+Maintainer-email: benjamink@mirageoscience.com
+Requires-Python: >=3.10,<4.0
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Natural Language :: English
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: Unix
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Requires-Dist: discretize (>=0.11.0,<0.12.dev)
+Requires-Dist: geoapps-utils (>=0.6.0b1,<0.7.dev)
+Requires-Dist: geoh5py (>=0.12.0b1,<0.13.dev)
+Requires-Dist: numpy (>=1.26.0,<1.27.0)
+Requires-Dist: pydantic (>=2.5.2,<3.0.0)
+Requires-Dist: scipy (>=1.14.0,<1.15.0)
+Project-URL: Documentation, https://mirageoscience-grid-apps.readthedocs-hosted.com/
+Project-URL: Homepage, https://www.mirageoscience.com/mining-industry-software/python-integration/
+Project-URL: Repository, https://github.com/MiraGeoscience/grid-apps
+Description-Content-Type: text/x-rst
+
+grid-apps
+=========
+
+The **grid-apps** library offers tools for the creation and manipulation of grid objects (Octree, BlockModel, Grid2D, DrapeModel) using various Python libraries and `geoh5py <https://mirageoscience-geoh5py.readthedocs-hosted.com/>`_.
+
+Installation
+^^^^^^^^^^^^
+**grid-apps** is currently written for Python 3.10 or higher.
+
+Install **grid-apps** from PyPI::
+
+    $ pip install grid-apps
+
+
+Feedback
+^^^^^^^^
+Have comments or suggestions? Submit feedback.
+All the content can be found on the github_ repository.
+
+.. _github: https://github.com/MiraGeoscience/grid-apps
+
+
+Visit `Mira Geoscience website <https://mirageoscience.com/>`_ to learn more about our products
+and services.
+
+
+License
+^^^^^^^
+MIT License
+
+Copyright (c) 2024-2025 Mira Geoscience
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Third Party Software
+^^^^^^^^^^^^^^^^^^^^
+The grid-apps Software may provide links to third party libraries or code (collectively “Third Party Software”)
+to implement various functions. Third Party Software does not comprise part of the Software.
+The use of Third Party Software is governed by the terms of such software license(s).
+Third Party Software notices and/or additional terms and conditions are located in the
+`THIRD_PARTY_SOFTWARE.rst`_ file.
+
+.. _THIRD_PARTY_SOFTWARE.rst: docs/source/THIRD_PARTY_SOFTWARE.rst
+
+Copyright
+^^^^^^^^^
+Copyright (c) 2024-2025 Mira Geoscience Ltd.
+

grid_apps-0.1.0b1/docs/source/THIRD_PARTY_SOFTWARE.rst

@@ -0,0 +1,28 @@
+Third Party Software
+====================
+
+The octree-creation-app repository and source distributions bundle several libraries that are
+compatibly licensed.  We list these here.
+
+.. list-table::
+  :widths: 30 30 60
+  :header-rows: 1
+
+  * - Name
+    - License
+    - Description
+  * - `discretize <https://simpeg.xyz/>`_
+    - MIT
+    - Discretization tools for finite volume and inverse problems
+  * - `geoh5py <https://github.com/MiraGeoscience/geoh5py>`_
+    - LGPL-3.0-or-later
+    - Python API for geoh5, an open file format for geoscientific data
+  * - `geoapps-utils <https://github.com/MiraGeoscience/geoapps-utils>`_
+    - MIT
+    - Utilities for geoscientific applications.
+  * - `numpy <https://github.com/numpy/numpy>`_
+    - BSD-3-Clause
+    - Fundamental package for array computing in Python
+  * - `scipy <https://github.com/scipy/scipy>`_
+    - BSD-3-Clause
+    - Fundamental algorithms for scientific computing in Python

grid_apps-0.1.0b1/grid_apps/__init__.py

@@ -0,0 +1,37 @@
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+#  Copyright (c) 2022-2025 Mira Geoscience Ltd.                                     '
+#                                                                                   '
+#  This file is part of grid-apps package.                                          '
+#                                                                                   '
+#  grid-apps is distributed under the terms and conditions of the MIT License       '
+#  (see LICENSE file at the root of this source code package).                      '
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+
+try:
+    from ._version import __version__
+except ModuleNotFoundError:
+    from datetime import datetime
+
+    __date_str = datetime.today().strftime("%Y%m%d")
+    __version__ = "0.0.0.dev0+" + __date_str
+
+
+logging.basicConfig(level=logging.INFO)
+
+
+def assets_path() -> Path:
+    """Return the path to the assets folder."""
+
+    parent = Path(__file__).parent
+    folder_name = f"{parent.name}-assets"
+    assets_folder = parent.parent / folder_name
+    if not assets_folder.is_dir():
+        raise RuntimeError(f"Assets folder not found: {assets_folder}")
+
+    return assets_folder

grid_apps-0.1.0b1/grid_apps/_version.py

@@ -0,0 +1,2 @@
+# Version placeholder that will be replaced during substitution
+__version__ = "0.1.0b1"

grid_apps-0.1.0b1/grid_apps/block_model_to_octree/__init__.py

@@ -0,0 +1,8 @@
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+#  Copyright (c) 2024-2025 Mira Geoscience Ltd.                                     '
+#                                                                                   '
+#  This file is part of grid-apps package.                                          '
+#                                                                                   '
+#  grid-apps is distributed under the terms and conditions of the MIT License       '
+#  (see LICENSE file at the root of this source code package).                      '
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''

grid_apps-0.1.0b1/grid_apps/block_model_to_octree/driver.py

@@ -0,0 +1,234 @@
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+#  Copyright (c) 2024-2025 Mira Geoscience Ltd.                                     '
+#                                                                                   '
+#  This file is part of grid-apps package.                                          '
+#                                                                                   '
+#  grid-apps is distributed under the terms and conditions of the MIT License       '
+#  (see LICENSE file at the root of this source code package).                      '
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+from __future__ import annotations
+
+import logging
+import sys
+from pathlib import Path
+
+import numpy as np
+from discretize import TreeMesh
+from geoh5py.data import FloatData, ReferencedData
+from geoh5py.objects import BlockModel, Octree
+from geoh5py.ui_json.utils import fetch_active_workspace
+from scipy.spatial import cKDTree
+
+from grid_apps.block_model_to_octree.options import BlockModel2OctreeOptions
+from grid_apps.driver import BaseGridDriver
+from grid_apps.utils import (
+    block_model_to_discretize,
+    boundary_value_indices,
+    tensor_mesh_ordering,
+    treemesh_2_octree,
+)
+
+
+logger = logging.getLogger(__name__)
+
+
+class Driver(BaseGridDriver):
+    """
+    Convert a BlockModel object to Octree with various refinement strategies.
+    """
+
+    _params_class = BlockModel2OctreeOptions
+
+    @staticmethod
+    def block_model_to_treemesh(
+        entity: BlockModel, diagonal_balance=True, finalize=True
+    ) -> TreeMesh:
+        """
+        Convert a block model to an octree mesh with the same base cell size and
+        centered.
+
+        :param entity: BlockModel object to be converted
+        :param diagonal_balance: Whether to balance the mesh diagonally.
+        :param finalize: Whether to finalize the treemesh after creation.
+
+        :return: TreeMesh object.
+        """
+        origin = []
+        octree_cells = []
+        for ii, ax in zip("xyz", "uvz", strict=True):
+            cell_sizes = np.abs(getattr(entity, f"{ax}_cells"))
+            h_core = cell_sizes.min()
+
+            # Compute number of octree cells to span the extent
+            n_c = np.ceil(np.log2(np.sum(cell_sizes) / h_core))
+            cell_sizes_octree = np.ones(int(2**n_c)) * h_core
+            octree_cells.append(cell_sizes_octree)
+
+            # Colocate the center of the octree with the center of the block model
+            ind_core = np.where(cell_sizes == h_core)[0]
+            center = (
+                entity.origin[ii]
+                + entity.local_axis_centers(ax)[ind_core[len(ind_core) // 2]]
+            )
+
+            axis_center = len(cell_sizes_octree) // 2
+            origin.append(center - np.sum(cell_sizes_octree[:axis_center]) - h_core / 2)
+
+        treemesh = TreeMesh(
+            octree_cells,
+            x0=origin,
+            finalize=finalize,
+            diagonal_balance=diagonal_balance,
+        )
+
+        return treemesh
+
+    def make_grid(self) -> Octree:
+        """
+        Convert the block model and output the octree mesh.
+
+        :return: Octree object refined by the cell volumes or gradient of the data.
+        """
+        with fetch_active_workspace(self.params.geoh5, mode="r+"):
+            entity = self.params.entity
+
+            treemesh = Driver.block_model_to_treemesh(entity, finalize=False)
+            model = None
+            if self.params.data is None:
+                treemesh = Driver.refine_by_cell_volumes(
+                    treemesh, entity, finalize=True
+                )
+            else:
+                treemesh = Driver.refine_by_values(
+                    treemesh, self.params.data, finalize=True
+                )
+                # Transfer the model
+                ind = treemesh.get_containing_cells(entity.centroids)
+                model = (
+                    np.ones(treemesh.n_cells, dtype=self.params.data.values.dtype)
+                    * self.params.data.nan_value
+                )
+                model[ind] = self.params.data.values
+
+                nan_vals = (model == self.params.data.nan_value) | np.isnan(model)
+                if np.any(nan_vals):
+                    tree = cKDTree(entity.centroids)
+                    ind = tree.query(treemesh.cell_centers[nan_vals])[1]
+                    model[nan_vals] = self.params.data.values[ind]
+
+            octree = treemesh_2_octree(
+                self.params.geoh5,
+                treemesh,
+                parent=self.params.output.out_group,
+                name=self.params.output.export_as or entity.name + "_octree",
+            )
+
+            if model is not None and self.params.data is not None:
+                octree.add_data(
+                    {
+                        self.params.data.name: {
+                            "values": model,
+                            "entity_type": self.params.data.entity_type,
+                        }
+                    }
+                )
+
+            return octree
+
+    @staticmethod
+    def refine_by_cell_volumes(
+        mesh: TreeMesh,
+        entity: BlockModel,
+        finalize: bool = True,
+        mask: np.ndarray | None = None,
+    ) -> TreeMesh:
+        """
+        Refine the octree mesh by the cell volumes of the block model.
+
+        :param mesh: TreeMesh object to be refined.
+        :param entity: BlockModel object to be used for refinement.
+        :param finalize: Whether to finalize the treemesh after refinement.
+        :param mask: Optional mask on the block model centroids to apply the refinement over.
+
+        :return: TreeMesh object with refined levels.
+        """
+        if not isinstance(entity, BlockModel):
+            raise TypeError("entity must be an instance of BlockModel.")
+
+        tensor_oct_level = []
+        for ax in "uvz":
+            cell_sizes = np.abs(getattr(entity, f"{ax}_cells"))
+            h_core = cell_sizes.min()
+            # Find the core region
+            tensor_oct_level.append(np.log2(cell_sizes / h_core).astype(int))
+
+        e_x, e_y, e_z = np.meshgrid(*tensor_oct_level)
+        max_level = np.c_[np.ravel(e_x), np.ravel(e_y), np.ravel(e_z)].max(axis=1)
+
+        locations = entity.centroids
+        if mask is not None:
+            locations = locations[mask]
+            max_level = max_level[mask]
+
+        mesh.insert_cells(locations, mesh.max_level - max_level, finalize=finalize)
+
+        return mesh
+
+    @staticmethod
+    def refine_by_values(
+        mesh: TreeMesh, data: FloatData | ReferencedData, finalize=True
+    ) -> TreeMesh:
+        """
+        Increase the mesh resolution based on the gradient of data values.
+
+        :param mesh: Input TreeMesh object.
+        :param data: FloatData or ReferencedData object containing the values to
+            be used for refinement.
+        :param finalize: Whether to finalize the treemesh after refinement.
+
+        :return: TreeMesh object with refined levels.
+        """
+        if not isinstance(data, FloatData | ReferencedData):
+            raise TypeError(
+                "Argument 'data' must be an instance of FloatData or ReferencedData."
+            )
+
+        entity = data.parent
+        if not isinstance(entity, BlockModel):
+            raise TypeError("The parent of 'data' must be an instance of BlockModel.")
+
+        tensor = block_model_to_discretize(entity)
+        indices = tensor_mesh_ordering(entity)
+
+        gradients = np.abs(tensor.cell_gradient @ data.values[indices])
+        levels = np.zeros(gradients.shape, dtype=int)
+        isnan = np.isnan(gradients)
+
+        if isinstance(data, FloatData):
+            actives = gradients[~isnan]
+            bins = np.percentile(
+                actives[actives > 0], np.linspace(5, 95, mesh.max_level)
+            )
+            levels[~isnan] = np.searchsorted(bins, actives)
+        else:
+            levels[gradients > 0] = mesh.max_level
+
+        # Refine on the value/nan interface, without boundary cells
+        if any(isnan):
+            horizon = boundary_value_indices(
+                tensor, data.values[indices], data.nan_value
+            )
+            mesh = Driver.refine_by_cell_volumes(
+                mesh, entity, finalize=False, mask=horizon[np.argsort(indices)]
+            )
+
+        locs = tensor.average_cell_to_face @ tensor.cell_centers
+        mesh.insert_cells(locs[~isnan], levels[~isnan].astype(int), finalize=finalize)
+
+        return mesh
+
+
+if __name__ == "__main__":
+    file = Path(sys.argv[1]).resolve()
+    Driver.start(file)

grid_apps-0.1.0b1/grid_apps/block_model_to_octree/options.py

@@ -0,0 +1,60 @@
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+#  Copyright (c) 2024-2025 Mira Geoscience Ltd.                                     '
+#                                                                                   '
+#  This file is part of grid-apps package.                                          '
+#                                                                                   '
+#  grid-apps is distributed under the terms and conditions of the MIT License       '
+#  (see LICENSE file at the root of this source code package).                      '
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import ClassVar
+
+from geoapps_utils.driver.data import BaseData
+from geoh5py.data import FloatData, ReferencedData
+from geoh5py.groups import UIJsonGroup
+from geoh5py.objects import BlockModel
+from pydantic import BaseModel, ConfigDict
+
+from grid_apps import assets_path
+
+
+class OutputOptions(BaseModel):
+    """
+    Output parameters for block model creation.
+
+    :param export_as: Name of the output entity.
+    :param out_group: Output UIJson group.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    export_as: str | None = None
+    out_group: UIJsonGroup | None = None
+
+
+class BlockModel2OctreeOptions(BaseData):
+    """
+    Block model parameters for use with `block_models.driver`.
+
+    :param entity: BlockModel source object.
+    :param data: Optional data to refine the octree mesh.
+    :param output: Output options.
+    """
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    name: ClassVar[str] = "block_model_to_octree"
+    default_ui_json: ClassVar[Path] = (
+        assets_path() / "uijson/block_model_to_octree.ui.json"
+    )
+    title: ClassVar[str] = "Block Model to Octree Conversion"
+    run_command: ClassVar[str] = "grid_apps.block_model_to_octree.driver"
+    conda_environment: str = "grid_apps"
+
+    entity: BlockModel
+    data: FloatData | ReferencedData | None = None
+
+    output: OutputOptions = OutputOptions()

grid_apps-0.1.0b1/grid_apps/block_models/__init__.py

@@ -0,0 +1,8 @@
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
+#  Copyright (c) 2024-2025 Mira Geoscience Ltd.                                     '
+#                                                                                   '
+#  This file is part of grid-apps package.                                          '
+#                                                                                   '
+#  grid-apps is distributed under the terms and conditions of the MIT License       '
+#  (see LICENSE file at the root of this source code package).                      '
+# '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''