S_Harko: Complete Technical Reference Manual

Program Name: S_Harko (derived from Swarm Harker)[cite: 1] • Core Architecture: Asynchronous FFT Patterson Engine + Buerger Superposition + WebGPU Parallel PSO • Symmetry Database: 230 Space Groups (cctbx_space_groups_all_settings_v6.json)

1. Theoretical Background & The Phase Problem

In X-ray crystallographic analyses, experimentally measured diffraction intensities $I(h,k,l)$ are directly proportional to the squared structure factor magnitudes $|F(\mathbf{h})|^2$. However, phase information $\phi(\mathbf{h})$ is inherently lost during measurement. S_Harko bypasses the direct phase requirement by synthesizing the 3D Patterson function, which represents the real-space autocorrelation of crystal electron density[cite: 2]:

where $\mathbf{u} = (u,v,w)$ are fractional Patterson coordinates and $V$ represents the real-space unit cell volume[cite: 2].

Physical Properties of the Patterson Map

• Interatomic Vector Representation: Patterson map peaks do not directly correspond to atomic locations $\mathbf{x}_i$. Instead, each peak located at $\mathbf{u}$ represents an interatomic displacement vector $\mathbf{u}_{ij} = \mathbf{x}_i - \mathbf{x}_j$ between atoms $i$ and $j$[cite: 2].
• Weighting Factor: Peak heights scale proportionally with the product of the atomic numbers of the interacting pair ($Z_i Z_j$). As a consequence, heavy atoms generate dominant peaks that stand out clearly against lighter organic matrices[cite: 2].
• Origin Peak: The point at $(0,0,0)$ corresponds to all self-vectors ($\mathbf{x}_i - \mathbf{x}_i = \mathbf{0}$) with total integrated power $\sum Z_k^2$. S_Harko automatically masks a spherical volume around the origin to prevent scalar distortion in peak finding and colour map rendering[cite: 2].
• Centrosymmetry: Regardless of whether the space group is non-centrosymmetric, the Patterson function is strictly centrosymmetric ($P(\mathbf{u}) = P(-\mathbf{u})$)[cite: 2].

Harker Sections

Symmetry elements within space groups generate interatomic vectors constrained to specialized planes or lines termed Harker sections. For a general space group operation $\mathbf{S}\mathbf{x} = \mathbf{R}\mathbf{x} + \mathbf{t}$, symmetry-equivalent atoms generate Harker vectors defined by:

By evaluating peak maxima on these constrained planes, S_Harko extracts discrete fractional atomic coordinates directly from one-dimensional and two-dimensional searches.

2. Program Architecture

S_Harko isolates computational workloads across thread boundaries to guarantee smooth UI interaction at high animation frame rates.

Multi-Threaded System Map

2.2 Web Worker Pipeline

When data files are uploaded, S_Harko triggers a background worker thread via a single CALCULATE execution message:

STAGE 1: ASYNCHRONOUS FFT PATTERSON SYNTHESIS
  ├─ Expand unique reflections across full Friedel sphere using space group symmetry operators
  ├─ Grid determination: N = next_power_of_two( max(requested_grid, 2*h_max + 1) )
  ├─ Populate complex grid array with intensity values I(h,k,l)
  ├─ Execute 3D Radix-2 Cooley-Tukey Inverse FFT
  ├─ Map normalization: P(u,v,w) = Real(FFT) / Volume
  └─ Extract metadata: d_min resolution limit, calculated peak width σ = max(0.26 * d_min, 0.7 * dx)

STAGE 2: 3D LOCAL MAXIMA PEAK DETECTION & SUPERPOSITION
  ├─ Generate origin mask: exclude all grid points within 1.1 Å radius of (0,0,0)
  ├─ Calculate map statistics (mean, sigma) over non-origin voxels
  ├─ Find top non-origin vector peak u_top = (u,v,w)
  ├─ Compute Buerger Minimum Superposition Map: M(u) = min(P(u), P(u - u_top))
  └─ Extract peaks from the supermap as initial consolidated structural candidate sites
                

3. Data Input & Intensity Correction

3.1 File Formats

S_Harko reads ASCII data exports generated by powder diffraction profile refinement tools (such as Powder5, FullProf, TOPAS, or GSAS-II).

3.2 Intensity Classification Hierarchy

To calculate an accurate Patterson map, S_Harko requires $|F(h,k,l)|^2$ magnitudes[cite: 1]. S_Harko automatically classifies input columns using priority tiers from direct $|F_o|$ values to uncorrected raw areas.

4. Patterson Map Synthesis

4.1 FFT Synthesis Engine & Least-Squares Scaling

S_Harko uses a 3D Radix-2 Fast Fourier Transform to calculate maps ($O(N^3 \log N)$), accelerating calculations by over 300 times compared to direct summations. Trial maps are scaled to observed data using least-squares scaling over non-origin voxels.

5. Peak Finding & Harker Analysis

5.1 3D Local Maxima Search

S_Harko identifies peak vectors by scanning non-masked voxels using a 26-neighbor 3D local maximum search with periodic boundary wrapping.

5.2 Harker Section Deconvolution

Peaks located on Harker sections are mapped to candidate fractional atomic coordinates $(x,y,z)$ using space-group-specific analytical expressions.

5.3 Multi-Section Site Combination

Partial site positions obtained from isolated Harker sections are cross-referenced across planes to form preliminary consolidated sites.

5.4 Buerger Minimum Superposition Map (Supermap)

To overcome the limitations of isolated Harker section analysis, S_Harko implements an automated Buerger Minimum Superposition Function. Rather than relying solely on individual symmetry planes, the worker extracts the strongest non-origin vector peak $\mathbf{u}_{top} = (u, v, w)$ from the 3D local maxima search and computes a superposition map across the entire unit cell:

By taking the minimum value between the original Patterson map $P(\mathbf{u})$ and its shifted copy $P(\mathbf{u} - \mathbf{u}_{top})$, series termination ripples and background noise are heavily suppressed, highlighting true atomic positions. Users can directly inspect this map by selecting Superposition from the map type dropdown in the 2D Patterson slice visualizer. Peaks extracted from this supermap provide robust starting candidate positions for global optimization.

6. WebGPU Swarm Optimization

6.1 Particle Swarm Dynamics

S_Harko optimizes candidate atomic positions within the asymmetric unit using Particle Swarm Optimization (PSO) on the GPU. The position vector $\mathbf{X}_i$ and velocity vector $\mathbf{V}_i$ for particle $i$ update each generation according to:

6.2 Vector Fitness & Anti-Bump Penalties

S_Harko evaluates structural fitness by calculating the atomic-number-weighted average of observed Patterson map intensities at all predicted interatomic vector positions, minus a steric collision penalty.

6.3 Multi-Restart PSO & Hardware Safety Limits

Multi-restart searches run fresh randomized swarms to escape local minima, with particle numbers dynamically bounded by hardware limits (`maxStorageBufferBindingSize`).

6.4 Minimum Contact Distance Filter & Zero Floor

S_Harko calculates pair contact cutoffs using user-defined distances or van der Waals radius sums. To allow independent atoms of the same element to dynamically merge onto special positions, **the absolute hard limit has been removed and replaced with a zero floor ($0.00\text{ \AA}$)**. Both the CPU audit and the WGSL shader (`ABSOLUTE_MIN_CONTACT = 0.0`) allow close approaches when evaluating overlapping special positions, preventing artificial collision penalties from blocking structural convergence.

6.5 PSO Hyperparameter Tuning ($w, c_1, c_2$)

S_Harko exposes three core PSO control sliders in the UI, letting users adapt search behavior to noisy or rippled maps:

• Inertia ($w$, default: $0.50$): Controls how much previous velocity momentum a particle retains. Tuning tip: Increase $w$ (e.g., $0.70 - 0.80$) to help particles roll over high-frequency ripples without getting trapped; lower $w$ (e.g., $0.40$) for friction when fine-tuning smoothed peaks.
• Cognitive Factor ($c_1$, default: $1.50$): Dictates the particle's pull toward its own personal best-found position ($\mathbf{P}_{best}$). Tuning tip: Higher values encourage individual exploration of local neighborhoods.
• Social Factor ($c_2$, default: $1.50$): Dictates the particle's pull toward the swarm's global best position ($\mathbf{G}_{best}$). Tuning tip: Crank up $c_2$ when working with smoothed or superposition maps to rapidly pull all particles toward the consensus solution.

7. Visualisation & Data Export

7.1 Map Viewer & 3D Structure Viewer

Includes support for Observed, Calculated, Difference, and Superposition maps in the 2D slice visualizer. The Three.js 3D viewer renders unit cells, fractional axes, and CPK-colored atomic spheres with real-time coordinate editing.

7.2 Export Formats

Supports CIF, VESTA GRD density volumes, CSV peak lists, and publication-ready PDF summary reports.

8. Step-by-Step Workflows

8.1 Automated Superposition & Swarm Optimization

1. Upload your diffraction data file. S_Harko automatically computes the FFT Patterson map and the automated Buerger Superposition Map.
2. Inspect the superposition map by selecting Superposition under the Map dropdown.
3. Review consolidated sites generated from the supermap in the Peaks tab.
4. Switch to the Swarm tab, input asymmetric unit atoms, tune parameters ($w, c_1, c_2$), and click Initialize & Run Swarm.
5. Inspect the final model and export your CIF file.

9. Reference Tables & Specifications

9.1 Supported Atomic Tabular Data (`ATOM_DATA`)

10. Troubleshooting & Technical FAQ