Action surface tension

README.md

@@ -195,6 +195,9 @@ Enhancements to entropy calculation in original Action\_Gist.
 * Amit Roy (University of Utah, UT)
 Code for the CUDA version of the 'closest' Action.
 
+* Nathan D. Levinzon (University of Utah, UT)
+Action\surftension.
+
 * Andrew Simmonett (National Institutes of Health)
 Code for the reciprocal part of the particle mesh Ewald calculation (electrostatic and Lennard-Jones).
 

doc/ChangeLog.surftension.md

@@ -0,0 +1,110 @@
+# Changelog: `surftension` Action
+
+Branch: `action-surface_tension`
+Started: 2026-08-31
+Target version: V7.11.0
+Author: Nathan D Levinzon <ndlevinzon@gmail.com>
+
+Working log for the capillary-wave surface-tension Action.
+
+---
+
+## ChangeLog.v7.md (landed)
+
+New command `surftension` added under New Commands. Internal version `V7.11.0`.
+
+```
+surftension [<name>] <mask> [mask2 <mask2>] temp <T>
+  [normal {x|y|z}] [nsurf {1|2}] [side {upper|lower}]
+  [interface {willard|itim}]
+  [gridspacing <d>] [dz <d> | dnormal <d>]
+  [sigmaxy <d>] [sigmaz <d> | sigmanormal <d>]
+  [bulkhalfwidth <d>] [threshold <frac>]
+  [qmin <q>] [qmax <q>] [lx <Lx>] [ly <Ly>] [lz <Lz>]
+  [nblock <frames>] [dt <ps>] [blocktime <ps>]
+  [out <file> | spectrumout <file>] [roughout <file>] [blockout <file>]
+  [summaryout <file>]
+  [spectrumagr <file>] [roughagr <file>] [blockagr <file>]
+  [spectrumgnu <file>] [roughgnu <file>] [blockgnu <file>]
+```
+
+---
+
+## Files changed
+
+| File | Change |
+|------|--------|
+| `src/Action_SurfaceTension.h` | New Action class; MPI `SyncAction` / `trajComm_` |
+| `src/Action_SurfaceTension.cpp` | Init / Setup / DoAction / Print / SyncAction + helpers |
+| `src/Command.cpp` | `#include` and `AddCmd(..., "surftension")` |
+| `src/cpptrajfiles` | `Action_SurfaceTension.cpp` in `COMMON_SOURCES` |
+| `src/cpptrajheaders` | Install header for libcpptraj |
+| `src/Version.h` | `V7.10.0` → `V7.11.0` |
+| `doc/ChangeLog.v7.md` | New Commands entry |
+| `test/Test_SurfTension/RunTest.sh` | Help + smoke test |
+| `test/Makefile` | `test.surftension` target |
+
+---
+
+## Development log
+
+### 2026-08-31
+
+- Created this changelog on branch `action-surface_tension` before any Action source.
+- Implemented `Action_SurfaceTension`: z-slab capillary-wave γ from Gaussian-smoothed
+  density interfaces, 2D DFT height spectrum, q-shell averaging, optional `*out` files.
+- Wired `surftension` in `Command.cpp` and `cpptrajfiles`.
+- Bumped version to V7.11.0; documented in `ChangeLog.v7.md`.
+- Added `test/Test_SurfTension` smoke test (help + 1-frame Init/Setup).
+- NVT (fixed Lx, Ly). No plots.
+- MPI `SyncAction`: packed `ReduceMaster` SUM of the three |h_q|² spectra
+  (Radial-style). Frame counts / leftover `nblock` frames AllReduce SUM;
+  nx, ny, |q|, Lx, Ly AllReduce/ReduceMaster MAX so empty ranks (zeros) do
+  not clobber. Roughness and block DataSets keep default concat sync.
+  `nblock` is per-rank. Print block SEM uses `block_gamma_->Size()` after
+  DataSet sync, not the master's local `n_blocks_`.
+- `interface {willard|itim}`: default Willard-Chandler is the existing Gaussian
+  density isosurface. `itim` is per-column min/max of `<mask>`, split at Lz/2
+  after circular recenter (empty half-column skips the frame). `dz` / Gaussian
+  / `threshold` apply only to Willard-Chandler.
+- OpenMP on the 2-D DFT (`ST_HeightPower`): flattened (kx, ky) loop with
+  `schedule(dynamic)`, same style as `radial` / `rms2d` (no `collapse()`).
+- OpenMP on the 3-D Gaussian filter: one parallel region, three separable
+  passes; each 1-D line is an independent `omp for` with thread-local buffers.
+- Grace (xmgrace) and gnuplot DataFile writers: `*out` uses the extension
+  (`.agr`/`.xmgr`, `.gnu`); `spectrumagr`/`spectrumgnu` (and rough/block)
+  force the format. Spectrum meshes get xlabel `q (Ang^-1)`.
+- Bending modulus κ: Helfrich linear fit of `1/(q² S)` vs `q²` on `[qmin,qmax]`
+  (≥ 3 shells). Reports κ in kT (and J); `kappaq` / `kappaqtop` / `kappaqbot`
+  vs q; `bkappa` with `nblock`. Plateau γ is unchanged (Python).
+- `normal {x|y|z}` (default z): permute Cartesian coordinates into
+  (lateral 1, lateral 2, normal) before wrap / circular recenter / Willard /
+  ITIM / DFT. Freeze lateral lengths only (NVT). Area = Lt1×Lt2.
+  `lx`/`ly`/`lz` override Cartesian box lengths. `dnormal` ≡ `dz`,
+  `sigmanormal` ≡ `sigmaz` (error if both given and they differ).
+  Init/Print report e.g. `Slab normal: z (interface plane x-y)`. Warns on
+  non-orthogonal boxes.
+-   Height-field 2-D FFT uses cpptraj `PubFFT` (row-column 1-D FFTs), then
+  divides by `nx*ny` (numpy `fft2` convention). Same `S(q)` as the old
+  direct DFT. Per-block γ/κ print in `Print()`, not during the frame loop.
+- Default `qmin` is the smallest fundamental wavevector from the unit-cell
+  laterals, `2π/max(Lt1,Lt2)`, set on the first good frame. Both `2π/Lt1`
+  and `2π/Lt2` are printed. `summaryout` writes a parseable key/value file
+  (γ, κ, roughness, q window, box, frames). Skip-frame warnings are capped
+  at 5. `blocktime` (ps) with `dt` (analyzed-frame spacing) sets `nblock`.
+  Output directories are not created; the user must give existing paths.
+- `nsurf {1|2}` (default 2, vacuum or a second phase on both sides of the
+  film). `nsurf 1` with `side {upper|lower}` uses one interface. `mask2`
+  is a second mask for the lower surface (leaflet / liquid–liquid); the
+  upper surface then comes from `<mask>` with no mid-box split. Both
+  masks share one circular recenter so the film is not split apart.
+- `out` is an alias for `spectrumout`. Init now errors if an `*out` path
+  names a directory that does not exist (DataFiles are opened only after
+  `run`, which previously lost a full trajectory write).
+
+---
+
+## Not in this change
+
+- ITIM probe-sphere radius (min/max is the probe → 0 limit)
+- Numeric regression vs a water-slab trajectory (no slab traj in the test suite yet)

doc/ChangeLog.v7.md

@@ -13,6 +13,38 @@ New Commands
 
 - `desc` - DEBUG: describe a selection in the same manner as leap.
 
+- `surftension` - Calculate capillary-wave surface tension of a liquid slab.
+  Builds Gaussian-smoothed instantaneous upper and lower interfaces from a number-density
+  field, Fourier-transforms height fluctuations, and reports γ in mN/m from the small-q
+  plateau of q²⟨|h_q|²⟩. κ (kT) is the Helfrich slope of 1/(q² S) vs q².
+  `normal {x|y|z}` selects the slab normal (default z). `interface {willard|itim}`
+  selects a Willard-Chandler density isosurface (default) or ITIM per-column min/max.
+  Default is two interfaces (e.g. a water slab with vacuum at +z and −z). `nsurf 1`
+  with `side {upper|lower}` is a single interface. `mask2` supplies a second atom
+  set for the lower surface (leaflet / liquid–liquid). Lateral lengths come from
+  the unit cell unless `lx`/`ly`/`lz` are set. If `qmin` is omitted it is
+  2π/max(Lt1,Lt2) from the first frame. `blocktime` (ps) with `dt` sets `nblock`.
+  Optional outputs (`spectrumout`, `roughout`, `blockout`, `summaryout`) follow
+  the filename extension (`.agr`/`.xmgr` = xmgrace, `.gnu` = gnuplot). Dedicated
+  `*agr`/`*gnu` keywords force Grace or gnuplot. `fprefix` is prepended to each
+  of those file names. Parent directories must already exist. MPI-parallel
+  (packed spectral SUM to the master). Assumes NVT (fixed lateral box lengths).
+
+```
+surftension [<name>] <mask> [mask2 <mask2>] temp <T>
+  [normal {x|y|z}] [nsurf {1|2}] [side {upper|lower}]
+  [interface {willard|itim}]
+  [gridspacing <d>] [dz <d> | dnormal <d>]
+  [sigmaxy <d>] [sigmaz <d> | sigmanormal <d>]
+  [bulkhalfwidth <d>] [threshold <frac>]
+  [qmin <q>] [qmax <q>] [lx <Lx>] [ly <Ly>] [lz <Lz>]
+  [nblock <frames>] [dt <ps>] [blocktime <ps>] [fprefix <prefix>]
+  [out <file> | spectrumout <file>] [roughout <file>] [blockout <file>]
+  [summaryout <file>]
+  [spectrumagr <file>] [roughagr <file>] [blockagr <file>]
+  [spectrumgnu <file>] [roughgnu <file>] [blockgnu <file>]
+```
+
 New functionality
 =================
 - Read topology/coordinates with the 'readdata' command.

doc/DocumentChecksums.txt

@@ -1,3 +1,3 @@
 f6f8cb1a79951d80a9d2656fd9c30f55  CpptrajDevelopmentGuide.lyx
-8ba86aca8b37cdcb5b01ef05141e5dce  cpptraj.lyx
+f7837faf109fc9c36db4e0274ff6d92f  cpptraj.lyx
 5d9b5b5ed47a3ded57b6464df99b3585  CpptrajManual.lyx

doc/cpptraj.bib

@@ -470,3 +470,54 @@ @article{Noe2016
 doi = {10.1021/acs.jctc.6b00762},
 URL = { https://doi.org/10.1021/acs.jctc.6b00762 },
 }
+
+@Article{Willard10,
+  author = {Willard, A. P. and Chandler, D.},
+  title = {{Instantaneous Liquid Interfaces}},
+  journal = {J. Phys. Chem. B},
+  volume = {114},
+  pages = {1954-1958},
+  year = {2010},
+  doi = {10.1021/jp909219k}
+}
+
+@Article{Partay08,
+  author = {P{\'a}rtay, L. B. and Hantal, G. and Jedlovszky, P. and Vincze, {\'A}. and Horvai, G.},
+  title = {{A new method for determining the interfacial molecules and characterizing the surface roughness in computer simulations.
+ Application to the liquid--vapor interface of water}},
+  journal = {J. Comput. Chem.},
+  volume = {29},
+  pages = {945-956},
+  year = {2008},
+  doi = {10.1002/jcc.20852}
+}
+
+@Article{Buff65,
+  author = {Buff, F. P. and Lovett, R. A. and Stillinger, F. H.},
+  title = {{Interfacial Density Profile for Fluids in the Critical Region}},
+  journal = {Phys. Rev. Lett.},
+  volume = {15},
+  pages = {621-623},
+  year = {1965},
+  doi = {10.1103/PhysRevLett.15.621}
+}
+
+@Article{Sides99,
+  author = {Sides, S. W. and Grest, G. S. and Lacasse, M.-D.},
+  title = {{Capillary waves at liquid-vapor interfaces: A molecular dynamics simulation}},
+  journal = {Phys. Rev. E},
+  volume = {60},
+  pages = {6708-6713},
+  year = {1999},
+  doi = {10.1103/PhysRevE.60.6708}
+}
+
+@Article{Helfrich73,
+  author = {Helfrich, W.},
+  title = {{Elastic Properties of Lipid Bilayers: Theory and Possible Experiments}},
+  journal = {Z. Naturforsch. C},
+  volume = {28},
+  pages = {693-703},
+  year = {1973},
+  doi = {10.1515/znc-1973-11-1209}
+}