Iterative Bilayer Bending with Grid-Based External Potentials VMD +
Python + NAMD Workflow
=====================================================================

OVERVIEW

This tutorial provides a reproducible and modular pipeline to generate
progressively bent lipid bilayers using external grid-based potentials
in NAMD.
The workflow consists of: 1) Rebuilding and solvating a system in VMD 2)
Writing explicit grid metadata 3) Generating
flat and curved grid potentials using Python 4) Producing iterative NAMD
input files for gradual curvature control

Architecture:
    VMD (geometry authority)
            ↓
    grid-meta.txt (explicit grid definition)
            ↓
    Python grid generators (null / flat / bent)
            ↓
    NAMD templates (min + eq-X)

DIRECTORY STRUCTURE
Expected files in tutorial directory:
    min.namd
    eq-x.namd
    z-make-system.tcl
    grid_utils.py
    z-write-nullgrid.py
    z-generate-cuboid.py
    z-generate-cuboid-bend.py
    z-make-system-and-grid.sh

REQUIREMENTS
1)  VMD (Required) Tested with VMD 1.9.4a43 (Linux) Required packages:
    -   solvate
    -   autoionize
    IMPORTANT: Aliases do NOT work inside scripts.
    If VMD is not on PATH: VMD=/full/path/to/vmd
    ./z-make-system-and-grid.sh …
    Or add to PATH: export PATH=/path/to/vmd/bin:$PATH

2)  Python (3.6+) Required packages: numpy gridDataFormats
    Install via: pip install numpy gridDataFormats
    or: conda install numpy pip install gridDataFormats

3)  NAMD 2.14, or NAMD 3.0 in CPU-only or GPU-offload mode.
    Grid forces work in GPU-offload mode, which is what NAMD 3 GPU builds
    use unless "GPUresident on" is set (the grid force itself is computed
    on the CPU). Grid forces are NOT supported in GPU-resident mode, so
    do not add "GPUresident on" to the templates.
    Run with:  namd2 +pN file.namd
           or: namd3 +pN +devices 0 file.namd

WORKFLOW DETAILS

Step 1 — System Rebuild (VMD)
z-make-system.tcl: - Loads input PSF + trajectory/PDB - Recenters
solute - Solvates with padding - Adds ions - Computes bilayer
thickness - Writes: fin.psf / fin.pdb grid-lipid-tails.pdb grid-meta.txt
grid-size.txt (legacy)

Step 2 — Explicit Grid Geometry
grid-meta.txt defines: NX NY NZ DX DY DZ ORIGIN CELL FULL CUBOID

Step 3 — Grid Generation
Null Grid: box-zeroed.dx
Flat Cuboid: cuboid.dx
Iterative Bending: bend-1.dx bend-2.dx …
Curvature relation: R = (dt^2 + (L/2)^2) / (2dt)
Where: dt = cumulative edge displacement L = cuboid length R = resulting
radius of curvature

BEFORE YOU BEGIN

User MUST edit: z-make-system.tcl
Specifically: 
selname - Atoms that will FEEL the gridforce (beta=1.0 in grid-lipid-tails.pdb)
bilayer - Atoms used to estimate bilayer midplane and thickness (typically headgroup atoms)
grid_thickness_pad - padding term to adjust the width of the grid potential that can emcompasses all tail atoms
salt_conc - ion concentration in solvent (mol/L)
cation - supported cations SOD MG POT CES CAL ZN2
anion - supported anions  CLA
Users MUST edit: min.namd eq-x.namd
Specifically: - Parameter/topology file paths - CHARMM toppar streams
Placeholders automatically filled: CELL_X CELL_Y CELL_Z TEMP
Check individual files for further information

RUNNING THE PIPELINE

Example:
    ./z-make-system-and-grid.sh -R 150 -p system.psf -t eq.dcd -o run_bend_R150 -d 2 -T 310
Options:
    -R   Target radius (Å)
    -p   Input PSF
    -t   Input DCD or PDB
    -o   Output directory
    -d   Per-iteration dt (Å)
    -T   Temperature (K)

OUTPUT STRUCTURE

Inside output folder:
    fin.psf
    fin.pdb
    grid-meta.txt
    grid-lipid-tails.pdb
    box-zeroed.dx
    cuboid.dx
    bend-1.dx
    bend-2.dx
    ...
    eq-0.namd
    eq-1.namd
    ...
    run_all_namd

DESIGN DECISIONS

Explicit Grid Metadata: NX/NY/NZ written explicitly delta written
explicitly origin written explicitly Eliminates ambiguity
Independent NX / NY / NZ: Grid matches box dimensions independently in
X, Y, Z
Memory Efficient Grid Construction: Python avoids large meshgrid
allocations

PERFORMANCE CONSIDERATIONS

Memory usage scales as: NX × NY × NZ × 4 bytes
Examples: 200^3 grid ≈ 32 MB 300^3 grid ≈ 108 MB

COMMON ERRORS & FIXES

VMD not found: VMD=/path/to/vmd ./script …
- Python SyntaxError: Ensure Python 3.6+
- Missing gridDataFormats: pip install gridDataFormats
- NAMD gridforce error: Use NAMD 2.14, or NAMD 3 without "GPUresident on" (GPU-offload or CPU-only mode)
- Periodic boundary too small: ensure enough padding (pad) in z-make-system.tcl
- Bilayer distorting due to too thick or too thin grid potential: optimize grid height padding (grid_thickness_pad) in z-make-system.tcl,
ensure correct atoms are used for bilayer thickness calculations (bilayer) z-make-system.tcl
- Lipid atom flying into the solution or edges of the micelle is distorting during bending: reduce -d (Per-iteration dt (Å)) to 1

SCIENTIFIC APPLICATIONS

This workflow can be used to: - Study curvature-induced lipid sorting -
Examine protein curvature sensing - Model viral membrane budding -
Analyze bilayer mechanical response - Test curvature thresholds for pore
formation

LIMITATIONS

    - Assumes bilayer geometry roughly rectangular and planar
    - Assumes symmetric bending from the center
    - Does not automatically relax system between steps
    - Gridforce is artificial and not a physical membrane model
    - Does not apply generating vesicles. The script assumes reasonable curvature for the given size from the user.

REPRODUCIBILITY

All geometric definitions are explicitly written in: grid-meta.txt

END OF README
