Artifacts/docker

.github/FUNDING.yml

@@ -0,0 +1,13 @@
+# These are supported funding model platforms
+
+# github: # Replace with up to 4 GitHub Sponsors-enabled usernames e.g., [user1, user2]
+# patreon: # Replace with a single Patreon username
+open_collective:  opensource-fluidnumerics
+# ko_fi: # Replace with a single Ko-fi username
+# tidelift: # Replace with a single Tidelift platform-name/package-name e.g., npm/babel
+# community_bridge: # Replace with a single Community Bridge project-name e.g., cloud-foundry
+# liberapay: # Replace with a single Liberapay username
+# issuehunt: # Replace with a single IssueHunt username
+# otechie: # Replace with a single Otechie username
+# lfx_crowdfunding: # Replace with a single LFX Crowdfunding project-name e.g., cloud-foundry
+# custom: # Replace with up to 4 custom sponsorship URLs e.g., ['link1', 'link2']

LICENSE

@@ -3,9 +3,8 @@ Copyright © 2024 Fluid Numerics LLC
 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
 
 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
-
 3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
+4. Redistributions of any form whatsoever must retain the following acknowledgment: 'This product includes software developed by "Fluid Numerics LLC (https://www.fluidnumerics.com)"'
 
-THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS “AS IS” AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

cloudbuild.yaml

@@ -0,0 +1,8 @@
+steps:
+- name: 'gcr.io/cloud-builders/docker'
+  script: |
+    docker build -f docker/x86_64/Dockerfile \
+                 -t 'us-docker.pkg.dev/$PROJECT_ID/self/self-x86_64:$REF_NAME'
+  automapSubstitutions: true
+images:
+- 'us-docker.pkg.dev/$PROJECT_ID/self/self-x86_64:$REF_NAME'

docker/x86_64/Dockerfile

@@ -0,0 +1,75 @@
+# Build stage with Spack pre-installed and ready to be used
+FROM spack/ubuntu-jammy:develop AS builder
+
+
+# What we want to install and how we want to install it
+# is specified in a manifest file (spack.yaml)
+RUN mkdir -p /opt/spack-environment && \
+set -o noclobber \
+&&  (echo spack: \
+&&   echo '  specs:' \
+&&   echo '  - cmake@3.30.2' \
+&&   echo '  - feq-parse@2.2.2' \
+&&   echo '  - openmpi@5.0.2+static' \
+&&   echo '  - hdf5@1.14.3 +fortran +mpi' \
+&&   echo '  concretizer:' \
+&&   echo '    unify: true' \
+&&   echo '  config:' \
+&&   echo '    install_tree: /opt/software' \
+&&   echo '  view: /opt/views/view') > /opt/spack-environment/spack.yaml
+
+# Install the software, remove unnecessary deps
+RUN cd /opt/spack-environment && spack env activate . && spack install --fail-fast && spack gc -y
+COPY . .
+
+RUN spack env activate -d /opt/spack-environment &&\
+    mkdir build && cd build && \
+    cmake -DCMAKE_BUILD_TYPE=release  \
+          -DSELF_ENABLE_MULTITHREADING=ON \
+          -DCMAKE_INSTALL_PREFIX=/opt/views/view \
+          -DSELF_ENABLE_TESTS=OFF \
+          -DSELF_ENABLE_EXAMPLES=ON \
+          -DSELF_MULTITHREADING_NTHREADS=4 \
+          ../ && \
+    make VERBOSE=1 && \
+    make install 
+
+# # # Strip all the binaries
+# # RUN find -L /opt/views/view/* -type f -exec readlink -f '{}' \; | \
+# #     xargs file -i | \
+# #     grep 'charset=binary' | \
+# #     grep 'x-executable\|x-archive\|x-sharedlib' | \
+# #     awk -F: '{print $1}' | xargs strip
+
+# # Modifications to the environment that are necessary to run
+RUN cd /opt/spack-environment && \
+    spack env activate --sh -d . > activate.sh
+
+
+# # Bare OS image to run the installed executables
+# FROM ubuntu:22.04
+
+# COPY --from=builder /opt/spack-environment /opt/spack-environment
+# COPY --from=builder /opt/software /opt/software
+
+# # paths.view is a symlink, so copy the parent to avoid dereferencing and duplicating it
+# COPY --from=builder /opt/views /opt/views
+
+RUN { \
+      echo '#!/bin/sh' \
+      && echo '.' /opt/spack-environment/activate.sh \
+      && echo 'exec "$@"'; \
+    } > /entrypoint.sh \
+&& chmod a+x /entrypoint.sh \
+&& ln -s /opt/views/view /opt/view
+
+
+LABEL "app"="self"
+LABEL "mpi"="openmpi@5.0.2"
+LABEL "platform"="x86_64"
+LABEL "gpu"="none"
+LABEL "hdf5"="1.14.3"
+LABEL "feqparse"="2.2.2"
+ENTRYPOINT [ "/entrypoint.sh" ]
+CMD [ "/bin/bash" ]
+

docker/x86_64/spack.yaml

@@ -0,0 +1,26 @@
+spack:
+  specs:
+  - cmake@3.30.2
+  - feq-parse@2.2.2
+  - openmpi@5.0.2
+  - hdf5@1.14.3 +fortran +mpi
+
+  container:
+    # Select the format of the recipe e.g. docker,
+    # singularity or anything else that is currently supported
+    format: docker
+
+    # Sets the base images for the stages where Spack builds the
+    # software or where the software gets installed after being built..
+    images:
+      os: "ubuntu:22.04 "
+      spack: develop
+
+    # Labels for the image
+    labels:
+      app: "self"
+      mpi: "openmpi@5.0.2"
+      platform: "x86_64"
+      gpu: "none"
+      hdf5: "1.14.3"
+      feqparse: "2.2.2"

docs/GettingStarted/docker.md

@@ -0,0 +1,129 @@
+# SELF Docker Images
+
+## Fluid Numerics Artifact Registry
+Fluid Numerics maintains a registry of Docker images on Google Cloud. We provide access to this registry through a subscription to the [Fluid Numerics Higher Order Methods Lab (homlab)](https://www.fluidnumerics.com/shop/p/higher-order-methods-lab). Once you have a [homlab subscription](https://www.fluidnumerics.com/shop/p/higher-order-methods-lab), or if you are a [collaborator](https://opencollective.com/opensource-fluidnumerics/projects/spectral-element-library-in-fo) you will have the ability to pull Docker images that we maintain and test regularly.
+
+### Available Images
+| Image           | compiler | MPI flavor | GPU Software | Target GPU | Target CPU |
+| --------------- | -------- | ------------- | --- | ----| ------ |
+|**`self-x86_64`**| gfortran | openmpi@5.0.2 | N/A | N/A | x86_64 |
+|**`self-x86_64-gfx90a_rocm6.2.1`**| gfortran | openmpi@5.0.2 | rocm@6.0.2 | gfx90a (MI200) | x86_64 |
+|**`self-x86_64-gfx942_rocm6.2.1`**| gfortran | openmpi@5.0.2 | rocm@6.0.2 | gfx942 (MI300) | x86_64 |
+|**`self-x86_64-sm72_cuda12.1`**| gfortran | openmpi@5.0.2 | cuda@12.1 | sm72 (V100) | x86_64 |
+|**`self-x86_64-sm90_cuda12.1`**| gfortran | openmpi@5.0.2 | cuda@12.1 | sm90 (H100) | x86_64 |
+
+
+This guide provides instructions for pulling our Docker images hosted on Google Cloud Artifact Registry using **Docker** and **Singularity/Apptainer**.
+
+
+### **Prerequisites**
+
+#### General Requirements
+- Ensure you have access credentials for the Google Cloud project hosting the Docker image.
+
+#### Docker-Specific Requirements
+- [Docker](https://www.docker.com/) installed on your system (version 20.10 or later recommended).
+- A Google Cloud service account or personal account with permissions to access the Artifact Registry.
+
+#### Singularity/Apptainer-Specific Requirements
+- [Singularity](https://sylabs.io/singularity/) or [Apptainer](https://apptainer.org/) installed on your system (version 3.8 or later recommended).
+- Docker CLI available to pull images before converting them for use with Singularity/Apptainer.
+
+
+### Pulling the Docker Image with Docker
+
+1. **Authenticate with Google Cloud Artifact Registry**  
+   Run the following command to authenticate Docker with Google Cloud:
+   ```bash
+   gcloud auth configure-docker us-docker.pkg.dev
+   ```
+   This configures Docker to use your Google Cloud credentials for accessing private images.
+
+2. **Pull the Docker Image**  
+   Use the `docker pull` command to fetch the image:
+   ```bash
+   docker pull us-docker.pkg.dev/fluidnumerics-research/self/self-x86_64:latest
+   ```
+   Replace `latest` with the desired tag if applicable.
+
+3. **Verify the Image**  
+   Confirm the image has been pulled successfully by listing it:
+   ```bash
+   docker images
+   ```
+
+
+### Pulling and Using the Image with Singularity/Apptainer
+
+#### Option 1: Direct Pull Using `singularity pull`
+
+Singularity/Apptainer can directly pull the image and convert it into a `.sif` file.
+
+1. **Pull the Image**  
+   Use the `singularity pull` or `apptainer pull` command:
+   ```bash
+   singularity pull docker://us-docker.pkg.dev/fluidnumerics-research/self/self-x86_64:latest
+   ```
+   This will fetch the image and save it as `self-x86_64_latest.sif` in your current directory.
+
+2. **Verify the SIF File**  
+   Check that the file was created:
+   ```bash
+   ls -lh self-x86_64_latest.sif
+   ```
+
+3. **Run the Image**  
+   Execute commands using the Singularity container:
+   ```bash
+   singularity exec self-x86_64_latest.sif <your-command>
+   ```
+
+#### Option 2: Pull with Docker and Convert Locally
+
+If you prefer to use Docker first and then convert the image for Singularity/Apptainer:
+
+1. **Pull the Docker Image**  
+   Follow the Docker instructions above to pull the image.
+
+2. **Save the Docker Image as a `.tar` File**  
+   Export the Docker image to a tarball:
+   ```bash
+   docker save us-docker.pkg.dev/fluidnumerics-research/self/self-x86_64:latest -o self-x86_64.tar
+   ```
+
+3. **Convert to a Singularity SIF File**  
+   Use `singularity build` or `apptainer build` to create a SIF file:
+   ```bash
+   singularity build self-x86_64.sif docker-archive://self-x86_64.tar
+   ```
+
+4. **Run the Image**  
+   Use the `singularity exec` command:
+   ```bash
+   singularity exec self-x86_64.sif <your-command>
+   ```
+
+
+## Build your own images
+The SELF repository comes with docker recipes for CPU-only, ROCm, and CUDA platforms. Each recipe is organized under the `docker/` subdirectory:
+
+* `docker/x86_64` - CPU only, MPI enabled, multithreaded
+* `docker/x86_64_rocm` - MPI+HIP enabled, multithreaded
+* `docker/x86_64_cuda` - MPI+CUDA enabled, multithreaded
+
+Each subdirectory contains a `spack.yaml` and `Dockerfile`. The `spack.yaml` file is used to generate the Dockerfile using `spack containerize`. The `spack.yaml` files are retained for development purposes and are often not used by end-users. 
+
+### CPU-only platforms
+To build a Docker image for CPU only platforms :
+
+1. Clone the SELF repository
+
+```shell
+git clone https://github.com/fluidnumerics/self ~/self/
+cd ~/self/
+```
+
+2. Build the image with `docker build`. This process installs all of SELF's dependencies and SELF and usually takes about 30 minutes to complete.
+```
+docker build -f docker/x86_64/Dockerfile -t self-x86_64:latest .
+```