MiraGeoscience · sebhmg · Sep 16, 2025 · Apr 21, 2026 · Apr 24, 2026 · May 6, 2026
diff --git a/.github/workflows/python_analysis.yml b/.github/workflows/python_analysis.yml
@@ -31,7 +31,7 @@ jobs:
       contents: read
       pull-requests: read
     with:
-      package-manager: 'conda'
+      package-manager: 'pixi'
       app-name: 'grid_apps'
       python-version: '3.12'
   call-workflow-pytest:
@@ -41,7 +41,7 @@ jobs:
       contents: read
       pull-requests: read
     with:
-      package-manager: 'conda'
+      package-manager: 'pixi'
       python-versions: '["3.12", "3.13", "3.14"]'
       os: '["ubuntu-latest", "windows-latest"]'
       cache-number: 1

diff --git a/.gitignore b/.gitignore
@@ -146,6 +146,16 @@ dmypy.json
 # tempory generated files
 pyproject-sha.toml
 
-#version ignore
+# auto-generated version file
 grid_apps/_version.py
 /_version.json
+
+# not using poetry to lock, but pixi
+poetry.lock
+
+# pixi environments
+.pixi/*
+!.pixi/config.toml
+
+# generated conda env files by pixi
+*.pixi.conda.yml
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -64,7 +64,7 @@ repos:
     hooks:
     -   id: pylint
         name: pylint
-        entry: .\\devtools\\conda_env_pylint.bat
+        entry: pixi run --locked pylint
         language: system
         require_serial: true  # pylint does its own parallelism
         types: [python]
@@ -73,7 +73,7 @@ repos:
     rev: v2.4.2
     hooks:
     -   id: codespell
-        exclude: (-lock\.ya?ml|\benvironments/.*\.ya?ml|\.ipynb|^THIRD_PARTY_SOFTWARE\.rst)$
+        exclude: (^pixi.lock|-lock\.ya?ml|\benvironments/.*\.ya?ml|\.ipynb|^THIRD_PARTY_SOFTWARE\.rst)$
         entry: codespell -I .codespellignore
 -   repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v6.0.0

diff --git a/.readthedocs.yml b/.readthedocs.yml
@@ -1,19 +1,37 @@
 version: 2
 
-# Set the version of Python and other tools you might need
 build:
-  os: "ubuntu-22.04"
+  os: ubuntu-24.04
   tools:
-    python: "mambaforge-22.9"
+    python: "3.10"  # pre-install for the py310 environment of pixi
+  jobs:
+    post_checkout:
+      # Download and uncompress binary for the desired version of Git LFS
+      - |
+        set -e
+        LFS_VERSION="3.4.0"
+        wget "https://github.com/git-lfs/git-lfs/releases/download/v${LFS_VERSION}/git-lfs-linux-amd64-v${LFS_VERSION}.tar.gz"
+        tar xzf "git-lfs-linux-amd64-v${LFS_VERSION}.tar.gz" --strip-components=1 "git-lfs-${LFS_VERSION}/git-lfs"
+        rm "git-lfs-linux-amd64-v${LFS_VERSION}.tar.gz"
+      # Modify LFS config paths to point where git-lfs binary was downloaded
+      - git config filter.lfs.process "$(pwd)/git-lfs filter-process"
+      - git config filter.lfs.smudge  "$(pwd)/git-lfs smudge -- %f"
+      - git config filter.lfs.clean "$(pwd)/git-lfs clean -- %f"
+      # Make LFS available in current repository
+      - ./git-lfs install
+      # Download content from remote
+      - ./git-lfs fetch
+      # Make local files to have the real content on them
+      - ./git-lfs checkout
 
-# Build documentation in the docs/ directory with Sphinx
-sphinx:
-  configuration: docs/source/conf.py
+    create_environment:
+      - asdf plugin add pixi
+      - asdf install pixi latest
+      - asdf global pixi latest
+      - asdf plugin add uv
+      - asdf install uv latest
+      - asdf global uv latest
 
-conda:
-  environment: docs/environment.yml
-
-python:
-  install:
-    - method: pip
-      path: .
+    build:
+      html:
+        - pixi run --frozen build-docs html $READTHEDOCS_OUTPUT
diff --git a/deps-lock-config.yaml b/deps-lock-config.yaml
diff --git a/devtools/conda_env_pylint.bat b/devtools/conda_env_pylint.bat
diff --git a/docs/environment.yml b/docs/environment.yml
diff --git a/docs/source/block_model.rst b/docs/source/block_model.rst
@@ -3,13 +3,24 @@
 Block Model Creation
 ====================
 
-.. note::
+The ``Block Model Creation`` module has been developed as a user interface for the creation of regular (Tensor)
+BlockModel objects using the `discretize <https://discretize.simpeg.xyz/en/main/>`_ package.  A Block
+Model grid is a discretization of a 3D volume into a set of rectangular cells.
 
-    Under construction.
+.. figure:: /images/block_model_creation_result.png
+    :width: 800
 
-The ``Block Model`` module has been developed as a user-interface for the creation of regular (Tensor) BlockModel objects using the `discretize <https://discretize.simpeg.xyz/en/main/>`_ package.
+In order to determine the core extents of the block model, the user will select an input ``Object`` and
+``Core depth``.  The padding is controlled by ``Horizontal padding``, ``Bottom padding``, and
+``Expansion factor``.  The resolution is set per axis by the ``Minimum cell size`` parameters.
 
-# .. figure:: /images/octree_grid.png
-#    :width: 800
+.. figure:: /images/block_model_creation_uijson.png
+   :width: 500
 
-An Block Model grid is a discretization of a 3D volume into a set of rectangular cells.
+The resulting block model will have its core region set by the object and limited by the ``Core depth``
+parameter. The core region will contain cells at the requested ``Minimum cell size`` in all three
+Cartesian directions. ``Horizontal`` and ``Vertical padding`` will be applied outward from the
+core region to the specified distances.  Within the padding region, the cells expand outward at the
+provided ``Expansion factor`` rate.
+
+.. figure:: /images/block_model_creation_result.png
diff --git a/docs/source/block_model_to_octree.rst b/docs/source/block_model_to_octree.rst
@@ -3,14 +3,32 @@
 Block Model to Octree
 =====================
 
-.. note::
 
-    Under construction.
+The ``Block Model to Octree`` module has been developed as a user interface for the conversion between
+regular 3D grid (`BlockModel`) objects to Octree, using the `discretize <https://discretize.simpeg.xyz/en/main/>`_
+package.
 
-The ``Block model to Octree`` module has been developed as a user-interface for the conversion between regular (Tensor) BlockModel objects to Octree, using the `discretize <https://discretize.simpeg.xyz/en/main/>`_ package.
+.. figure:: /images/block_model_to_octree_advanced.png
+    :width: 800
 
-# .. figure:: /images/octree_grid.png
-#    :width: 800
+In its most simple form, the application creates an octree from the input block model.
 
-An octree mesh is a discretization of a 3D volume into a set of rectangular cells. The cells are defined by a tree
-structure, where each node has 8 children.
+.. figure:: /images/block_model_to_octree_uijson_basic.png
+   :width: 500
+
+In this case the application will create an octree with the core region matching the cells of
+the block model with a small padding region where the cells are allowed to expand to the closest
+octree level.
+
+.. figure:: /images/block_model_to_octree_basic_usage.png
+    :width: 800
+
+Optionally, users can select a model stored on the tensor mesh.
+
+.. figure:: /images/block_model_to_octree_uijson_advanced.png
+   :width: 500
+
+The octree will then be refined in areas that contain large gradients in the selected model.
+
+.. figure:: /images/block_model_to_octree_advanced.png
+    :width: 800
diff --git a/docs/source/conf.py b/docs/source/conf.py
@@ -8,8 +8,9 @@
 #                                                                                        '
 # ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
+import os
 from datetime import datetime
-from importlib.metadata import version
+from importlib.metadata import version as get_version
 
 from packaging.version import Version
 
@@ -26,38 +27,63 @@
 author = "Mira Geoscience Ltd."
 project_copyright = "%Y, Mira Geoscience Ltd"
 
+package_name = "grid-apps"
+
+full_version = Version(get_version(package_name))
+# The full public version, including alpha/beta/rc tags
+release = full_version.public
+# remove the post release segment, if any
+if full_version.is_postrelease:
+    release = release.rsplit(".post", 1)[0]
+# The short X.Y.Z version.
+version = full_version.base_version
 
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-# The full version, including alpha/beta/rc tags.
-release = version("grid-apps")
-# The shorter X.Y.Z version.
-version = Version(release).base_version
-
-autodoc_mock_imports = [
-    "numpy",
-    "geoh5py",
-    "geoapps_utils",
-    "pydantic",
-    "discretize",
-]
+nitpicky = True
 
 extensions = [
     "sphinx.ext.autodoc",
     "sphinx.ext.autosummary",
+    "sphinx.ext.intersphinx",
     "sphinx.ext.todo",
+    "sphinx.ext.viewcode",
+    "sphinx_issues",
+    "sphinxcontrib.googleanalytics",
 ]
 
+intersphinx_mapping = {
+    # use None to auto-fetch objects.inv
+    "numpy": ("https://numpy.org/doc/1.26/", None),
+    "python": ("http://docs.python.org/3", None),
+}
+
 templates_path = ["_templates"]
 exclude_patterns = []
 todo_include_todos = True
 
+googleanalytics_id = os.environ.get("GOOGLE_ANALYTICS_ID", "")
+if not googleanalytics_id:
+    googleanalytics_enabled = False
+
+issues_github_path = f"mirageoscience/{package_name}"
+
 # -- Options for auto-doc ----------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/extensions/autodoc.html#module-sphinx.ext.autodoc
 
 autodoc_typehints = "signature"
 
+autodoc_mock_imports = [
+    "discretize",
+    "geoapps_utils",
+    "geoh5py",
+    "numpy",
+    "pydantic",
+    "scipy",
+    "tqdm",
+]
+
 # -- Options for HTML output -------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 

diff --git a/docs/source/images/block_model_creation_result.png b/docs/source/images/block_model_creation_result.png
diff --git a/docs/source/images/block_model_creation_uijson.png b/docs/source/images/block_model_creation_uijson.png
diff --git a/docs/source/images/block_model_to_octree_advanced.png b/docs/source/images/block_model_to_octree_advanced.png
diff --git a/docs/source/images/block_model_to_octree_basic_usage.png b/docs/source/images/block_model_to_octree_basic_usage.png
diff --git a/docs/source/images/block_model_to_octree_uijson_advanced.png b/docs/source/images/block_model_to_octree_uijson_advanced.png
diff --git a/docs/source/images/block_model_to_octree_uijson_basic.png b/docs/source/images/block_model_to_octree_uijson_basic.png
diff --git a/docs/source/images/ui_json_general.png b/docs/source/images/ui_json_general.png
diff --git a/docs/source/images/ui_json_refinements.png b/docs/source/images/ui_json_refinements.png
diff --git a/environments/env-python-3.12.yml b/environments/env-python-3.12.yml
diff --git a/environments/env-python-3.13.yml b/environments/env-python-3.13.yml
diff --git a/environments/env-python-3.14.yml b/environments/env-python-3.14.yml