Synchronizing Fields with Singularities

This code is associated to our paper

Natalia Pacheco-Tallaj, Mattéo Couplet, Edward Chien, and David Palmer. Synchronizing Fields with Singularities. SIGGRAPH ’26 Conference Papers (July 2026). doi: 10.1145/3799902.3811225.

synchfields requires the following MATLAB libraries:

• gptoolbox for general geometry processing support.
• minsec for direction fields and covariant operators.
• manopt for optimization on manifolds.
• MATLAB add-on svdecon (thin SVD).

The package includes the implementation of the core synchronization solvers in core, along with examples of various downstream applications as detailed in our paper.

stripes/surface_pattern.m compares surface patterns computed by spectral relaxation and SDP relaxation:

surface_pattern(mesh_data, degree, freq, bdry_cond)

where mesh_data is the output of process_surface in minsec; degree is 2 for stripes or 4 for quads; freq is the frequency of the pattern; and bdry_cond specifies whether to impose strict boundary conditions on the symchronization problem (currently only for stripes). See Figures 4, 6, and 8 in our paper.

stripes/volumetric_stripes.m computes volumetric stripe patterns on a tet mesh by spectral and SDP methods with boundary conditions (Figures 1 and 3 in our paper):

function [u1_eig, u1_sdp, omega, info_eig, info_sdp, Y, Lw, u_harmonic] = ...
    volumetric_stripes(tet_mesh, stripe_frequency_multiplier, make_figures, v_top, v_bottom, v_mid, u)

The tet_mesh is the output of generate_tet_mesh in util/generate_tet_mesh.m. Turning on make_figures will plot figures for debugging purposes. v_top, v_bottom, and v_mid specify subsets of vertices whose phase values get constrained during optimization. u specifies the input vector field (if not specified, this will be the gradient of a harmonic function interpolating the top = 1 and bottom = 0 boundary conditions). Output: omega is the connection derived from the vector field, and u1_eig and u1_sdp are complex phase fields computed by spectral and SDP relaxations, respectively.

After computing a phase field u1 on the tet mesh, it can be interpolated at sub-tet resolution onto a regular grid for visualization, export, and further processing:

function [density_interp, angles_interp] = ...
    volumetric_stripes_to_voxels(tet_mesh, u1, omega, gridRes, make_figures)

The connection omega is used to interpolate at sub-tet resolution without aliasing, as in the original surface stripe patterns work of Knöppel et al. (2015). A Python script, util/mat2vdb.py, is provided to extract gridded data from a .mat file to VDB format, e.g., for rendering in Blender.

clebsch/singular_clebsch_sweep.m computes singular Clebsch maps for the trefoil vortex fluid flow in the original Smoke Rings from Smoke paper by Weißmann et al. (2014). It compares spectral and SDP relaxations at several values of the "resolution" parameter hbar. It also compares best-of-500 randomized rounding to SVD-based rounding. See Figure 5 in our paper.

Spherical Clebsch map regression is implemented in clebsch/clebsch.m. Currently fixed velocity fields are specified for 2D (Figure 7 of our paper, matching Figure 2 of Chern et al. (2017)) and 3D.

function [psi, Y, cand_rank] = ...
    clebsch(grid_dim, side_len, n_x, hbar, rand_round, plot_vel)

Here grid_dim is the spatial dimension, side_len is the grid side length, n_x is the number of voxels along a side, and hbar is the vorticity quantization scale. rand_round = true turns on randomized rounding, and plot_vel turns on plotting the input velocity field in the 2D case.

psi is the resulting $S^3$-valued Clebsch map. To visualize it, use

imshow(texture_from_clebsch(psi, texture));

where texture is a spherical texture image encoded with a simple equirectangular (spherical coordinates) map projection, e.g., one of the high-resolution earth images from Natural Earth. The Clebsch map can be optionally upscaled first using

psi = upscale_sphere_map(psi, scale_factor);

clebsch/clebsch_anim.m gives an example of downstream processing, animating a continuous family of singular Clebsch maps from a single spherical Clebsch map. clebsch/clebsch_anim_S15.m, in turn, animates a continuous family of spherical Clebsch maps from one $S^{15}$-valued Clebsch map, e.g., derived from the pre-rounding SDP factor Y output from clebsch at rank 4.

The dataset directory contains scripts for computing directional fields by spectral relaxation, SDP relaxation, and MBO on a dataset of surfaces (Figure 9 in our paper). dataset_experiment does all the computations and dumps the results in an output directory. dataset_statistics computes summary statistics, and dataset_figures renders images.