# Intro to surfacefun

An interactive introduction to
[surfacefun](https://github.com/danfortunato/surfacefun) — a package for
numerically computing with functions on surfaces, and solving PDEs on them, with
high-order accuracy. Everything here runs in your browser through
[numbl](https://numbl.org): pick a script on the left and click **Run**. Each
script is self-contained and draws one or more figures (use the figure tabs).

Every script begins with

```matlab
mip load --install flatironinstitute/flatironinstitute/surfacefun
```

which fetches surfacefun (and its dependency, Chebfun) on first use.

## 1. Surface meshes

A `surfacemesh` is a collection of high-order quadrilateral patches whose union
defines a surface in 3-D.

- [`mesh_single_patch.m`](mesh_single_patch.m) — build a surface from one
  high-order Chebyshev patch.
- [`mesh_sphere.m`](mesh_sphere.m) — the built-in "cubed sphere", plus mesh
  queries (patches, order, area, volume, bounding box).
- [`mesh_blob.m`](mesh_blob.m) — a smooth random "blob".
- [`mesh_torus.m`](mesh_torus.m) — a genus-1 torus.
- [`mesh_twisted_torus.m`](mesh_twisted_torus.m) — patches need not join
  smoothly.
- [`mesh_mobius.m`](mesh_mobius.m) — surfaces need not be orientable.
- [`mesh_refine.m`](mesh_refine.m) — change the order (`resample`) or split
  patches (`refine`).

## 2. Scalar functions

A `surfacefun` is a scalar field on a `surfacemesh`, built from a handle of the
Cartesian coordinates `(x,y,z)`.

- [`fun_plot.m`](fun_plot.m) — define and plot a function on the sphere.
- [`fun_arithmetic.m`](fun_arithmetic.m) — overloaded `+`, `*`, `abs`, ...
- [`fun_contour.m`](fun_contour.m) — contour (level-set) plot on the surface.
- [`fun_gradient.m`](fun_gradient.m) — the surface gradient `grad(f)`.
- [`fun_laplacian.m`](fun_laplacian.m) — the surface Laplacian `lap(f)`.
- [`fun_integral_norm.m`](fun_integral_norm.m) — `integral`, `mean`, and norms.

## 3. Vector fields

A `surfacefunv` is a three-component vector field over a `surfacemesh`.

- [`vec_normals.m`](vec_normals.m) — the unit normal field, as a quiver plot.
- [`vec_gradient.m`](vec_gradient.m) — `grad(f)` is tangent to the surface.
- [`vec_mean_curvature.m`](vec_mean_curvature.m) — mean curvature from
  `div(n)/2`.
- [`vec_curl.m`](vec_curl.m) — the surface curl of a vector field.

## 4. Solving PDEs

`surfaceop` is a fast direct solver for second-order linear elliptic PDEs on
surfaces.

- [`pde_laplace_beltrami.m`](pde_laplace_beltrami.m) — a Laplace-Beltrami
  problem on the sphere, checked against an exact spherical-harmonic solution.
- [`pde_helmholtz.m`](pde_helmholtz.m) — a variable-coefficient Helmholtz
  problem on a stellarator.
- [`pde_open_surface.m`](pde_open_surface.m) — an open surface with Dirichlet
  boundary data, reusing one factorization for several right-hand sides.

## 5. Worked examples

- [`ex_hodge.m`](ex_hodge.m) — the Hodge decomposition of a tangential vector
  field into curl-free, divergence-free, and harmonic parts.
- [`ex_reaction_diffusion.m`](ex_reaction_diffusion.m) — the complex
  Ginzburg-Landau equation, integrated in time with a reused implicit solver.

## Notes

The scripts keep the polynomial order and refinement modest so they run quickly
in the browser. Raise `p` and `nref` for higher accuracy and smoother pictures.
The numerics follow the surfacefun documentation at
<https://surfacefun.readthedocs.io>.

## How it's deployed

On every push to `main`, the workflow in
[`.github/workflows/deploy.yml`](.github/workflows/deploy.yml) bundles these
files with the numbl browser IDE and publishes the result to GitHub Pages.
Edit `numbl-project.json` to change the title or which file opens first.