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']

.github/workflows/fprettify-lint.yml

@@ -50,12 +50,12 @@ jobs:
                     echo "test/ linting passed!"
                 fi   
 
-            - name: Check for formatting differences (example/)
+            - name: Check for formatting differences (examples/)
               run: |
-                if [[ $(fprettify  './example/' --config-file ./fprettify.config -d --recursive --case 1 1 1 1) ]]; then
-                    fprettify  './example/' --config-file ./fprettify.config -d --recursive --case 1 1 1 1
+                if [[ $(fprettify  './examples/' --config-file ./fprettify.config -d --recursive --case 1 1 1 1) ]]; then
+                    fprettify  './examples/' --config-file ./fprettify.config -d --recursive --case 1 1 1 1
                     exit 1
                 else
-                    echo "example/ linting passed!"
+                    echo "examples/ linting passed!"
                 fi   
 

CMakeLists.txt

@@ -28,6 +28,7 @@ cmake_policy(VERSION 3.21...3.27)
 
 option(SELF_ENABLE_MULTITHREADING "Option to enable CPU multithreading for `do concurrent` loop blocks."  OFF)
 option(SELF_ENABLE_TESTING "Option to enable build of tests. (Default On)"  ON)
+option(SELF_ENABLE_EXAMPLES "Option to enable build of examples. (Default On)"  ON)
 option(SELF_ENABLE_GPU "Option to enable GPU backend. Requires either CUDA or HIP. (Default Off)"  OFF)
 option(SELF_ENABLE_APU "Option to enable APU backend. Requires either CUDA or HIP. (Default Off)"  OFF)
 option(SELF_ENABLE_DOUBLE_PRECISION "Option to enable double precision for floating point arithmetic. (Default On)"  ON)
@@ -245,4 +246,14 @@ add_subdirectory(${CMAKE_SOURCE_DIR}/src)
 if(SELF_ENABLE_TESTING)
     enable_testing()
     add_subdirectory(${CMAKE_SOURCE_DIR}/test)
+    if(SELF_ENABLE_EXAMPLES)
+        add_subdirectory(${CMAKE_SOURCE_DIR}/examples)
+    endif()
+else()
+    if(SELF_ENABLE_EXAMPLES)
+        enable_testing()
+        add_subdirectory(${CMAKE_SOURCE_DIR}/examples)
+    endif()
 endif()
+
+

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.

README.md

@@ -10,9 +10,16 @@ Copyright 2020-2023 Fluid Numerics LLC
 [![linux-amdflang-cmake](https://github.com/FluidNumerics/SELF/actions/workflows/linux-amdflang-cmake.yaml/badge.svg)](https://github.com/FluidNumerics/SELF/actions/workflows/linux-amdflang-cmake.yaml)
 
 ## Licensing
-SELF is licensed for use under a [non-commercial use visible-source license](./LICENSE). Fluid Numerics is a small family-owned business and wants to make SELF available to researchers for academic use. Under the license, you can use, modify, and redistribute SELF so long as attribution is given to Fluid Numerics. However, since we are interested in protecting our time-and-effort investment in SELF, sale and commercial-use of SELF is prohibited under the license.
+SELF is licensed for use under a [3 Clause BSD with attribution license](./LICENSE). [Fluid Numerics](https://www.fluidnumerics.com) is a small family-owned business. We want to make SELF available to folks who want to build conservation laws that run on a wide range of platforms. Under the license, you can use, modify, and redistribute SELF so long as attribution is given to Fluid Numerics. 
 
-If you are interested in commercial licensure and would like support from Fluid Numerics, reach out to support@fluidnumerics.com
+## How to support this repository
+Continued support of SELF relies on users and customers. Here's a few ways you can support this project:
+
+* Give this repository a star on Github
+* [Open an issue](https://github.com/FluidNumerics/SELF/issues/new/choose) if you have a question or want to report a problem. We want to help!
+* [Subscribe to Fluid Numerics on Youtube](https://www.youtube.com/@FluidNumerics?sub_confirmation=1)
+* [Sponsor this project on Open Collective](https://opencollective.com/opensource-fluidnumerics)
+* [Work with us](https://www.fluidnumerics.com/services)
 
 ## About
 SELF is an object-oriented Fortran library that support the implementation of Spectral Element Methods for solving partial differential equations.

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,71 @@
+# Build stage with Spack pre-installed and ready to be used
+FROM spack/rockylinux8: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.29.6' \
+&&   echo '  - feq-parse@2.2.2' \
+&&   echo '  - openmpi@5.0.2' \
+&&   echo '  - hdf5@1.14.3 +fortran +mpi' \
+&&   echo '  concretizer:' \
+&&   echo '    unify: when_possible' \
+&&   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 info openmpi && spack env activate . && spack install --fail-fast && spack gc -y
+
+# 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
+
+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 \
+          ../ && \
+    make VERBOSE=1 && \
+    make install 
+
+# Bare OS image to run the installed executables
+FROM docker.io/rockylinux:8
+
+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.29.6
+  - 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: "rockylinux:8"
+      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/Examples/BurgersEquation1D/TravelingShock.md

@@ -0,0 +1,174 @@
+# Traveling Shockwave Tutorial
+This tutorial will walk you through using an example program that uses the `SELF_Burgers1D` class to run a simulation with the viscous Burger's equation in 1-D. 
+
+## Problem statement
+In this example, we are solving the viscous Burger's equation, given by
+
+\begin{equation}
+u_t + \left( \frac{u^2}{2} \right)_x = \nu u_{xx}
+\end{equation}
+
+The physical domain is defined by $x \in [0, 1]$. The initial and boundary conditions are set using an exact solution,
+
+\begin{equation}
+u(x,t) = s - 0.5(u_l-u_r) \tanh\left( \frac{(x - st - x_0)(u_l-u_r)}{4\nu} \right)
+\end{equation}
+
+where $s = \frac{u_l + u_r}{2}$ is the shock speed. For the example problem, we let set the following parameters
+
+* $u_l = -1.0$
+* $u_r = 1.0$
+* $\nu = 0.01$
+* $x_0 = 0.1$
+
+When $t=0$, this defines a shock with characteristic length-scale $L = \frac{\nu}{U} = \frac{0.01}{1} = 0.01$ centered at $x=x_0=0.1$. The difference in the solution between upstream and downstream of the shock is $\Delta u = u_l - u_r = 1$
+
+<figure markdown>
+![Viscous shock initial condition](./img/u_t00.png){ align=left }
+  <figcaption>Initial condition for a viscous traveling shock</figcaption>
+</figure>
+
+<figure markdown>
+![Viscous shock initial condition](./img/shock1d.gif){ align=left }
+  <figcaption>A video of the evolution of the shockwave as it travels to the right at a speed of 0.5</figcaption>
+</figure>
+
+## How we implement this
+You can find the example file for this demo in the `examples/burgers1d_shock.f90` file. This file defines the `burgers1d_shock_model` module in addition to a program that runs the traveling shock simulation. 
+
+The `burgers1d_shock_model` module defines the `burgers1d_shock` class, which is a type extension of the `burgers1d` class that is provided by SELF. We make this type extension so that we can 
+* add parameters for the left and right state of the shock wave,
+* add a parameter for the initial center position of the shock, and
+* override the `hbc1d_Prescribed` and `pbc1d_Prescribed` type-bound procedures.
+
+This last component allows us to set the boundary conditions as the exact solution for the shock problem. The `hbc1d_Prescribed` boundary condition is used to set the external solution state on the boundaries; this external state is used in the *hyperbolic* fluxes. The `pbc1d_Prescribed` boundary condition is used to set the external state for the solution gradient on the boundaries; this is often used for the *parabolic* fluxes.
+
+
+For the boundary condition for the solution is set to
+\begin{equation}
+u(x,t) = s - 0.5(u_l-u_r) \tanh\left( \frac{(x - st - x_0)(u_l-u_r)}{4\nu} \right)
+\end{equation}
+
+and the boundary condition for the solution gradient is set to 
+
+For the boundary condition for the solution
+\begin{equation}
+\frac{∂ u}{∂ x}(x,t) = \frac{0.5 (u_l-u_r)^2}{4\nu}  \left[sech\left( \frac{(x - st - x_0)(u_l-u_r)}{4\nu} \right)\right]^2
+\end{equation}
+
+
+All of this is summarized in the `burgers1d_shock_model` module
+
+```fortran
+type, extends(burgers1D) :: burgers1d_shock
+  real(prec) :: ul = 1.0_prec
+  real(prec) :: ur = 0.0_prec
+  real(prec) :: x0 = 0.1_prec
+
+  contains
+
+  procedure :: hbc1d_Prescribed => hbc1d_Prescribed_burgers1d_shock ! override for the hyperbolic boundary conditions
+  procedure :: pbc1d_Prescribed => pbc1d_Prescribed_burgers1d_shock ! override for the parabolic boundary conditions
+
+endtype burgers1d_shock
+
+contains
+
+pure function hbc1d_Prescribed_burgers1d_shock(this,x,t) result(exts)
+class(burgers1d_shock),intent(in) :: this
+real(prec),intent(in) :: x
+real(prec),intent(in) :: t
+real(prec) :: exts(1:this%nvar)
+! Local
+real(prec) :: jump, s
+
+  jump = this%ul - this%ur
+  s = 0.5_prec*(this%ul + this%ur)
+  exts(1) = s - 0.5_prec*tanh( (x-s*t-this%x0)*jump/(4.0_prec*this%nu) )
+
+endfunction hbc1d_Prescribed_burgers1d_shock
+
+pure function pbc1d_Prescribed_burgers1d_shock(this,x,t) result(extDsdx)
+class(burgers1d_shock),intent(in) :: this
+real(prec),intent(in) :: x
+real(prec),intent(in) :: t
+real(prec) :: extDsdx(1:this%nvar)
+! Local
+real(prec) :: jump, s, r, drdx
+
+  jump = this%ul - this%ur
+  s = 0.5_prec*(this%ul + this%ur)
+  r = (x-s*t-this%x0)*jump/(4.0_prec*this%nu)
+  drdx = jump/(4.0_prec*this%nu)
+  extDsdx(1) = -0.5_prec*drdx*( sech( r ) )**2
+
+endfunction pbc1d_Prescribed_burgers1d_shock
+
+pure real(prec) function sech(x) result(fx)
+real(prec),intent(in) :: x
+fx = 2.0_prec/(exp(x)+exp(-x))
+endfunction
+
+``
+
+The main program for this example walks through standard procedures for running any simulation using SELF.
+
+First, the interpolant, mesh, and geometry are created. Here, we define the mesh using the `UniformBlockMesh` to create a mesh on a domain $ x ∈ [0,1] $. The left and right boundary conditions are set to the prescribed boundary condition (`SELF_BC_PRESCRIBED`). Then we create the interpolant using Legendre-Gauss quadrature. The geometry is then initialized, binding the interpolant to the geometry, and the metric terms are generated from the mesh information.
+
+```fortran
+call mesh%UniformBlockMesh(nGeo=1, &
+                               nElem=nelem, &
+                               x=(/0.0_prec,1.0_prec/))
+
+! Set the left and right boundary conditions to prescribed                               
+call mesh%ResetBoundaryConditionType(SELF_BC_PRESCRIBED,SELF_BC_PRESCRIBED)
+
+! Create an interpolant
+call interp%Init(N=controlDegree, &
+                  controlNodeType=GAUSS, &
+                  M=targetDegree, &
+                  targetNodeType=UNIFORM)
+
+! Generate geometry (metric terms) from the mesh elements
+call geometry%Init(interp,mesh%nElem)
+call geometry%GenerateFromMesh(mesh)
+```
+
+Following this, the `burgers1d_shock` model is initialized, associating the interpolant, geometry, and mesh to the model. We enable gradient calculations, so that we can calculate diffusive fluxes. We then set the initial conditions using the exact solution to the traveling shock problem.
+
+
+```fortran
+
+! Initialize the model
+call modelobj%Init(nvar,mesh,geometry)
+modelobj%gradient_enabled = .true.
+!Set the diffusivity
+modelobj%nu = nu
+
+! Set the initial condition
+jump = modelobj%ul - modelobj%ur
+s = 0.5_prec*(modelobj%ul + modelobj%ur)
+modelobj%solution%interior(:,:,1) = s - 0.5_prec*tanh( &
+  (geometry%x%interior(:,:,1)-modelobj%x0)*jump/(4.0_prec*modelobj%nu) )
+```
+
+Following this, we configure the time integrator and forward step the model. During forward stepping, both tecplot curve files and SELF's HDF5 pickup files are written at every `ioInterval`.
+
+```fortran
+call modelobj%SetTimeIntegrator(integrator)
+
+! forward step the model to `endtime` using a time step
+! of `dt` and outputing model data every `iointerval`
+call modelobj%ForwardStep(endtime,dt,iointerval)
+```
+
+At the end of the program, all of the objects are freed from memory. It's important to start with the model object and end with the interpolant so that the geometry, mesh, and interpolant can be cleanly dissociated.
+
+```fortran
+call modelobj%free()
+call mesh%free()
+call geometry%free()
+call interp%free()
+```
+
+