1# Intro to surfacefun
3An interactive introduction to
4[surfacefun](https://github.com/danfortunato/surfacefun) — a package for
5numerically computing with functions on surfaces, and solving PDEs on them, with
6high-order accuracy. Everything here runs in your browser through
7[numbl](https://numbl.org): pick a script on the left and click **Run**. Each
8script is self-contained and draws one or more figures (use the figure tabs).
10Every script begins with
12```matlab
13mip load --install flatironinstitute/flatironinstitute/surfacefun
14```
16which fetches surfacefun (and its dependency, Chebfun) on first use.
18## 1. Surface meshes
20A `surfacemesh` is a collection of high-order quadrilateral patches whose union
21defines a surface in 3-D.
23- [`mesh_single_patch.m`](mesh_single_patch.m) — build a surface from one
24 high-order Chebyshev patch.
25- [`mesh_sphere.m`](mesh_sphere.m) — the built-in "cubed sphere", plus mesh
26 queries (patches, order, area, volume, bounding box).
27- [`mesh_blob.m`](mesh_blob.m) — a smooth random "blob".
28- [`mesh_torus.m`](mesh_torus.m) — a genus-1 torus.
29- [`mesh_twisted_torus.m`](mesh_twisted_torus.m) — patches need not join
30 smoothly.
31- [`mesh_mobius.m`](mesh_mobius.m) — surfaces need not be orientable.
32- [`mesh_refine.m`](mesh_refine.m) — change the order (`resample`) or split
33 patches (`refine`).
35## 2. Scalar functions
37A `surfacefun` is a scalar field on a `surfacemesh`, built from a handle of the
38Cartesian coordinates `(x,y,z)`.
40- [`fun_plot.m`](fun_plot.m) — define and plot a function on the sphere.
41- [`fun_arithmetic.m`](fun_arithmetic.m) — overloaded `+`, `*`, `abs`, ...
42- [`fun_contour.m`](fun_contour.m) — contour (level-set) plot on the surface.
43- [`fun_gradient.m`](fun_gradient.m) — the surface gradient `grad(f)`.
44- [`fun_laplacian.m`](fun_laplacian.m) — the surface Laplacian `lap(f)`.
45- [`fun_integral_norm.m`](fun_integral_norm.m) — `integral`, `mean`, and norms.
47## 3. Vector fields
49A `surfacefunv` is a three-component vector field over a `surfacemesh`.
51- [`vec_normals.m`](vec_normals.m) — the unit normal field, as a quiver plot.
52- [`vec_gradient.m`](vec_gradient.m) — `grad(f)` is tangent to the surface.
53- [`vec_mean_curvature.m`](vec_mean_curvature.m) — mean curvature from
54 `div(n)/2`.
55- [`vec_curl.m`](vec_curl.m) — the surface curl of a vector field.
57## 4. Solving PDEs
59`surfaceop` is a fast direct solver for second-order linear elliptic PDEs on
60surfaces.
62- [`pde_laplace_beltrami.m`](pde_laplace_beltrami.m) — a Laplace-Beltrami
63 problem on the sphere, checked against an exact spherical-harmonic solution.
64- [`pde_helmholtz.m`](pde_helmholtz.m) — a variable-coefficient Helmholtz
65 problem on a stellarator.
66- [`pde_open_surface.m`](pde_open_surface.m) — an open surface with Dirichlet
67 boundary data, reusing one factorization for several right-hand sides.
69## 5. Worked examples
71- [`ex_hodge.m`](ex_hodge.m) — the Hodge decomposition of a tangential vector
72 field into curl-free, divergence-free, and harmonic parts.
73- [`ex_reaction_diffusion.m`](ex_reaction_diffusion.m) — the complex
74 Ginzburg-Landau equation, integrated in time with a reused implicit solver.
76## Notes
78The scripts keep the polynomial order and refinement modest so they run quickly
79in the browser. Raise `p` and `nref` for higher accuracy and smoother pictures.
80The numerics follow the surfacefun documentation at
81<https://surfacefun.readthedocs.io>.
83## How it's deployed
85On every push to `main`, the workflow in
86[`.github/workflows/deploy.yml`](.github/workflows/deploy.yml) bundles these
87files with the numbl browser IDE and publishes the result to GitHub Pages.
88Edit `numbl-project.json` to change the title or which file opens first.