Development

.github/.devcontainer/DOCKERFILE_GHCS

@@ -4,8 +4,8 @@ RUN conda install -n base -c conda-forge mamba
 
 # Here we can install all the dependencies using mamba (as we do in the test scripts)
 
-COPY .devcontainer/uw_environment.yml  /tmp/conda-tmp/
-RUN  mamba env update -n base --file /tmp/conda-tmp/uw_environment.yml 
+COPY .devcontainer/uw_environment.yaml  /tmp/conda-tmp/
+RUN  mamba env update -n base --file /tmp/conda-tmp/uw_environment.yaml 
 
 # Add other dependencies that can't be installed correctly.
 

.github/.devcontainer/uw_environment.yaml

@@ -0,0 +1 @@
+../../environment.yaml

.github/workflows/build_deploy_pdoc.yml → .github/workflows/build_deploy_pdoc.yaml

@@ -21,7 +21,7 @@ jobs:
       - name: Install Conda environment with Micromamba
         uses: mamba-org/setup-micromamba@v2
         with:
-          environment-file: ./environment.yml
+          environment-file: ./environment.yaml
           cache-downloads: true
           cache-environment: true
 

.github/workflows/build_uw3_and_test.yml → .github/workflows/build_uw3_and_test.yaml

@@ -23,7 +23,7 @@ jobs:
       - name: Install Conda environment with Micromamba
         uses: mamba-org/setup-micromamba@v2
         with:
-          environment-file: ./environment.yml
+          environment-file: ./environment.yaml
           cache-downloads: true
           cache-environment: true
 

.github/workflows/deploy_to_gh_pages.yml.disabled

@@ -34,7 +34,7 @@ jobs:
     - name: Cache book files
       uses: actions/cache@v1
       env:
-        # Increase this value to reset cache if etc/example-environment.yml has not changed
+        # Increase this value to reset cache if etc/example-environment.yaml has not changed
         CACHE_NUMBER: 0
       with:
         path: |

.github/workflows/envs/build_uw_docs.yaml

@@ -0,0 +1 @@
+../../../environment.yaml

.github/workflows/publish.yml → .github/workflows/publish.yaml

@@ -22,8 +22,8 @@ jobs:
         uses: mamba-org/setup-micromamba@v2
         with:
           #micromamba-version: "1.5.6-0" # any version from https://github.com/mamba-org/micromamba-releases
-          #environment-file: .github/workflows/envs/build_quickstart.yml
-          environment-file: ./environment.yml
+          #environment-file: .github/workflows/envs/build_quickstart.yaml
+          environment-file: ./environment.yaml
           init-shell: bash
           cache-environment: true
           post-cleanup: "all"

README.md

@@ -41,9 +41,13 @@ The quickest option is **not to install** anything but try the binder demo above
 
 If do you want to install the code on your own machine, we recommend using `miniconda` and `mamba`. Create a separate virtual environment and install the code from source. More details on how to do that are in the [Installation Instructions](https://underworldcode.github.io/underworld3/development/_quickstart/Installation.html)
 
-## References 
+## References and Archives 
 
 The canonical releases of the code can be found at [zenodo.org](https://doi.org/10.5281/zenodo.16810746).
 
 [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.16810747.svg)](https://doi.org/10.5281/zenodo.16810746)
 
+There is a [publication in the Journal of Open Source Software](https://joss.theoj.org/papers/4f7a1ed76bde560968c246fa8eff778d) 
+([doi:10.21105/joss.07831](https://doi.org/10.21105/joss.07831)) that can be cited when using the software. 
+
+[![status](https://joss.theoj.org/papers/4f7a1ed76bde560968c246fa8eff778d/status.svg)](https://joss.theoj.org/papers/4f7a1ed76bde560968c246fa8eff778d)

docs/developer/container/Containerfile

@@ -0,0 +1,59 @@
+# syntax=docker/dockerfile:1.7-labs
+
+### how to build Underworld3 image
+### MUST run from the underworld3 top directory
+#   podman build . --rm \
+#       --format docker \
+#       -f ./docs/developer/container/Containerfile \ 
+#       -t underworldcode/underworld3:<version-id>
+#
+### requires the '--format docker' to run on podman, but no under docker.
+#
+#
+### Example usage (taken from - https://jupyter-docker-stacks.readthedocs.io/en/latest/using/running.html#using-the-podman-cli )
+# uid=57439
+# gid=57439
+
+# subuidSize=$(( $(podman info --format "{{ range .Host.IDMappings.UIDMap }}+{{.Size }}{{end }}" ) - 1 ))
+# subgidSize=$(( $(podman info --format "{{ range .Host.IDMappings.GIDMap }}+{{.Size }}{{end }}" ) - 1 ))
+# podman run   -it --rm   -p 10000:8888   -v "${HOME}/uw_space":/home/mambauser/host   --uidmap $uid:0:1 --uidmap 0:1:$uid --uidmap $(($uid+1)):$(($uid+1)):$(($subuidSize-$uid))   --gidmap $gid:0:1 --gidmap 0:1:$gid --gidmap $(($gid+1)):$(($gid+1)):$(($subgidSize-$gid)) underworldcode/underworld3:<version-id>
+
+FROM docker.io/mambaorg/micromamba:2.3.0
+
+# install os requirements for headless pyvista
+USER root
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    xvfb \
+    libgl1-mesa-dev \
+    && rm -rf /var/lib/apt/lists/*
+USER $MAMBA_USER
+
+# create the conda environment with all dependencies 
+# see https://micromamba-docker.readthedocs.io/en/latest/quick_start.html#quick-start
+COPY --chown=$MAMBA_USER:$MAMBA_USER environment.yaml /tmp/env.yaml
+RUN micromamba install -y -v -n base -f /tmp/env.yaml && \
+    micromamba clean --all --yes
+
+# activate mamba env during podman build
+ARG MAMBA_DOCKERFILE_ACTIVATE=1
+
+# pyvista - taken from pyvista docker files
+# see https://github.com/pyvista/pyvista/tree/main/docker
+RUN pip install --no-cache-dir --extra-index-url https://wheels.vtk.org vtk-osmesa
+
+# install UW3
+COPY --chown=$MAMBA_USER:$MAMBA_USER \
+     --exclude=**/.git \
+     . /home/$MAMBA_USER/underworld3
+WORKDIR /home/$MAMBA_USER/underworld3
+RUN pip install --no-build-isolation --no-cache-dir .
+
+# allow jupyterlab for ipyvtk
+ENV PYVISTA_OFF_SCREEN=true
+ENV JUPYTER_ENABLE_LAB=yes
+ENV PYVISTA_TRAME_SERVER_PROXY_PREFIX='/proxy/'
+
+WORKDIR /home/$MAMBA_USER/
+
+EXPOSE 8888
+CMD ["jupyter-lab", "--no-browser", "--ip=0.0.0.0"]

docs/developer/container/README.md

@@ -0,0 +1,22 @@
+The `Containerfile` is used to build the container and can be used with docker or podman. 
+At present only amd64 architecture is built, because vtk-osmesa isn't available for arm by default. This may change in future, or we could build vtk-osmesa from source (see https://docs.pyvista.org/extras/building_vtk.html)
+
+Example use, must be run from repository root.
+```bash
+   podman build . --rm \
+       --format docker \
+       -f ./docs/developer/container/Containerfile \ 
+       -t underworldcode/underworld3:foobar
+```
+
+The `launch-container.sh` is a script for launching the container using `podman` only. Podman is the preferred container runner because of `rootless` support.
+Expect the script to take a minute or so to load as permissions are updated. 
+Host port 10000 will run the container's default jupyter server. See script for details. 
+
+Useful links:
+- Container stacks with podman - https://jupyter-docker-stacks.readthedocs.io/en/latest/using/running.html#using-the-podman-cli
+- Micromamba images - https://micromamba-docker.readthedocs.io/en/latest/quick_start.html#quick-start
+- Pyvista containers: 
+    - https://github.com/pyvista/pyvista/tree/main/docker
+    - https://dev.pyvista.org/getting-started/installation#running-on-mybinder
+

docs/developer/container/launch-container.sh

@@ -0,0 +1,61 @@
+#!/usr/bin/env bash
+
+### Used for running the underworld3 container.
+# This requires 'podman', not docker. Install podman from 
+#   https://podman.io/docs/installation
+#
+# Once podman is installed and available on the command line, run with 
+#   ./launch-container.sh
+#
+# this will launch a container with a jupyter server running on
+#   http://localhost:10000
+# Also, the machine (host) directory 
+#   $HOME/uw_space
+# will be mapped into the container under /home/mambauser/host.
+# for transfering data to/from the container.
+#
+##
+
+set -x 
+
+# check to see if $HOME/uw_space exists, if not create it
+mkdir -p $HOME/uw_space
+
+# Set 'mambauser' uid/gid from base image, 'mambaorg/micromamba'
+uid=57439
+gid=57439
+
+subuidSize=$(( $(podman info --format "{{ range .Host.IDMappings.UIDMap }}+{{.Size }}{{end }}" ) - 1 ))
+subgidSize=$(( $(podman info --format "{{ range .Host.IDMappings.GIDMap }}+{{.Size }}{{end }}" ) - 1 ))
+
+# This will set an jupyter server on HOST port 10000
+# the uidmap / gidmap make the container UID compatible with the host system.
+# DO NOT run the following command with root, this is explain further below.
+podman run -it --rm \
+  -p 10000:8888     \
+  --uidmap $uid:0:1 \
+  --uidmap 0:1:$uid \
+  --uidmap $(($uid+1)):$(($uid+1)):$(($subuidSize-$uid)) \
+  --gidmap $gid:0:1 \
+  --gidmap 0:1:$gid \
+  --gidmap $(($gid+1)):$(($gid+1)):$((subgidSize-$gid)) \
+  -v "${HOME}/uw_space":/home/mambauser/host \
+  docker.io/underworldcode/underworld3:development 
+
+## Description of rootless podman and uidmap/gidmap.
+# Rootless podman allows a non-root user to run a container without elevated permissions.
+# DO NOT use `sudo` to execute the above `podman run` command
+# This is unlike rootful podman, or docker, thus it's more secure but has some complexity in the for of permission namespaces
+# the host and container permissions are elegantly 'namespaced' to two id mappings.
+#  1. host ids -> intermediate (/etc/subuid)
+#  2. intermediate -> container ids (uidmaps arguments)
+# 
+# In the above `podman run` we set uidmaps to allow for straight forward container / host directory bindmounts
+# container UID 57439 -> host UID 0 (if podman rootless this is host UID)
+# container UID 0-57438 -> host UID 1-57439
+# container UID 57440-delta -> host UID 57440-delta
+# as the container would have root accesson the host.
+# The $uid -> host UID 0 assumes podman "rootless" access, i.e. the host UID executing the container.
+# All other UIDs in the container are mapped to something different.
+#
+# This **MUST** be run without sudo, otherwise the host UID would be root.

docs/user/Installation.qmd

@@ -17,7 +17,7 @@ The `underworld3` build / run-time dependencies can be installed using
 ```bash
     (base) % git clone -b development --single-branch https://github.com/underworldcode/underworld3 /path/to/underworld3
     (base) % cd /path/to/underworld3
-    (base) % mamba env create -n uw3 -f environment.yml
+    (base) % mamba env create -n uw3 -f environment.yaml
     (base) % mamba activate uw3
 
     (uw3) % compile.sh
@@ -32,7 +32,7 @@ installed `PETSc` and `petsc4py`.
 ```bash
     (base) % git clone -b development --single-branch https://github.com/underworldcode/underworld3 /path/to/underworld3
     (base) % cd /path/to/underworld3
-    (base) % mamba env create -n uw3p -f environment.yml
+    (base) % mamba env create -n uw3p -f environment.yaml
     (base) % mamba activate uw3p
 
     (uw3p) % mamba remove petsc4py

environment.yml → environment.yaml

@@ -2,7 +2,7 @@ name: uw3
 channels:
   - conda-forge
 dependencies:
-  - python=3.11
+  - python <= 3.11
   - compilers
   - mpich
   - petsc=3.21.5
@@ -19,21 +19,25 @@ dependencies:
   - ipython
   - mpi4py
   - h5py=*=mpi*
-  - trame
-  - ipywidgets
   - gmsh
   - python-gmsh
   - python-xxhash
-  - jupyterlab
   - jupytext
-  - trame-vtk
-  - trame-vuetify
   - pygments
   - pint
+  - cmocean
+  - colorcet
+  - imageio
+  - imageio-ffmpeg
+  - ipywidgets<9.0.0
+  - jupyter-server-proxy
+  - jupyterlab<5.0.0
+  - trame>=2.5.2
+  - trame-vtk>=2.5.8
+  - trame-vuetify>=2.3.1
+  - trimesh
   - typeguard
   - pip
   - pip:
       - rich<14
       - meshio
-      - pygmsh
-        # - gmsh-api # is this used still in UW?

src/underworld3/ckdtree.pyx

@@ -215,9 +215,9 @@ cdef class KDTree:
             i = i.reshape(-1)
 
         if sqr_dists:
-            return numpy.sqrt(d), i
-        else:
             return d, i
+        else:
+            return numpy.sqrt(d), i
 
 
 ## A general point-to-point rbf interpolator here