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