feat: add APBS electrostatic surface demo (#2)

* feat: add APBS electrostatic surface demo

Render a vacuum electrostatic potential surface for 2ewn (E. coli biotin
repressor) using util.protein_vacuum_esp (protein contact potential mode),
mirroring the existing surface demo's structure prep. Adds scripts/demos/
apbs.pml, the rendered assets/demo_apbs.png, and a README section.

* feat: render APBS demo with the real APBS solver

Replace the vacuum-ESP approximation with a true Poisson-Boltzmann
electrostatics pipeline:

- scripts/apbs/prepare_apbs.sh: pdb2pqr (AMBER charges/radii) -> apbs
  (linearised PBE, 0.150 M NaCl) -> potential map (.dx, kT/e) for 2ewn
  chain A.
- scripts/demos/apbs.pml: load the .pqr + .dx and colour the molecular
  surface by potential over -5..+5 kT/e (ramp_new/surface_color), mirroring
  the mdpp examples/apbs viz scripts.
- CI: install apbs + pdb2pqr and run prepare_apbs.sh before rendering.
- gitignore generated APBS artifacts (.pqr/.dx/.in/.pdb) and the apbs
  solver scratch file io.mc.

* feat: match APBS demo camera to the surface demo

Replace orient with the explicit set_view matrix copied from
scripts/demos/surface.pml so both demos share the same viewpoint
(orient on the pqr atom set diverged: added hydrogens, no ligand).

Author: FridrichMethod

.github/workflows/render-demos.yml

@@ -7,6 +7,7 @@ on:
       - "configs/.pymolrc"
       - "configs/.pymolrc.py"
       - "scripts/demos/*.pml"
+      - "scripts/apbs/prepare_apbs.sh"
   workflow_dispatch:
 
 jobs:
@@ -32,9 +33,13 @@ jobs:
           channels: conda-forge,defaults
           use-mamba: true
 
-      - name: Install PyMOL
+      - name: Install PyMOL, APBS and PDB2PQR
         run: |
-          conda install -y pymol-open-source
+          conda install -y pymol-open-source apbs pdb2pqr
+
+      - name: Generate APBS electrostatics
+        run: |
+          bash scripts/apbs/prepare_apbs.sh 2ewn A
 
       - name: Render demos
         env:

.gitignore

@@ -160,3 +160,12 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# APBS demo generated artifacts (regenerated by scripts/apbs/prepare_apbs.sh)
+scripts/apbs/*.pdb
+scripts/apbs/*.pqr
+scripts/apbs/*.dx
+scripts/apbs/*.in
+
+# APBS solver scratch
+io.mc

README.md

@@ -22,6 +22,10 @@ You may also view and edit these rc files in `PyMOL -> File -> Edit pymolrc`.
 
 ![Surface Demo](assets/demo_surface.png)
 
+### APBS (Electrostatic Surface)
+
+![APBS Demo](assets/demo_apbs.png)
+
 ### Nucleic Acids
 
 ![Nucleic Acids Demo](assets/demo_na.png)

assets/demo_apbs.png

@@ -0,0 +1,50 @@
+#!/usr/bin/env bash
+#
+# Generate the APBS electrostatic potential map for the APBS surface demo.
+#
+# Pipeline (real Poisson-Boltzmann electrostatics):
+#   1. download the PDB entry
+#   2. isolate a single protein chain
+#   3. pdb2pqr -> per-atom charges/radii (.pqr) + a template APBS input (.in)
+#   4. apbs    -> electrostatic potential map (.dx, units kT/e)
+#
+# Requires `pdb2pqr30` (or `pdb2pqr`) and `apbs` on PATH.
+# Outputs <id>.pqr and <id>.dx next to this script; scripts/demos/apbs.pml
+# loads those two files to render assets/demo_apbs.png.
+#
+# Usage: bash scripts/apbs/prepare_apbs.sh [PDB_ID] [CHAIN]
+set -euo pipefail
+
+PDB_ID="${1:-2ewn}"
+CHAIN="${2:-A}"
+HERE="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+cd "$HERE"
+
+pdb2pqr_bin="$(command -v pdb2pqr30 || command -v pdb2pqr)"
+
+echo "[apbs-prep] downloading ${PDB_ID}..."
+curl -sSL -o "${PDB_ID}.pdb" "https://files.rcsb.org/download/${PDB_ID^^}.pdb"
+
+echo "[apbs-prep] isolating chain ${CHAIN} (protein atoms only)..."
+awk -v ch="$CHAIN" 'substr($0,1,4)=="ATOM" && substr($0,22,1)==ch' \
+    "${PDB_ID}.pdb" > "${PDB_ID}_chain.pdb"
+
+echo "[apbs-prep] assigning charges/radii with pdb2pqr (AMBER force field)..."
+"$pdb2pqr_bin" --ff=AMBER --whitespace --drop-water \
+    --apbs-input "${PDB_ID}.in" "${PDB_ID}_chain.pdb" "${PDB_ID}.pqr"
+
+echo "[apbs-prep] configuring APBS input (write potential map, 0.150 M NaCl)..."
+# Name the output map after the stem (-> <id>.dx) and add physiological salt.
+sed -i "s#write pot dx ${PDB_ID}.pqr#write pot dx ${PDB_ID}#" "${PDB_ID}.in"
+sed -i "s#^    lpbe#    ion charge +1 conc 0.150 radius 2.0\n    ion charge -1 conc 0.150 radius 2.0\n    lpbe#" \
+    "${PDB_ID}.in"
+
+echo "[apbs-prep] running APBS (linearised Poisson-Boltzmann)..."
+apbs "${PDB_ID}.in"
+
+# APBS appends a -PE0 processor tag for mg-auto runs; normalise the name.
+if [[ -f "${PDB_ID}-PE0.dx" ]]; then
+    mv -f "${PDB_ID}-PE0.dx" "${PDB_ID}.dx"
+fi
+
+echo "[apbs-prep] done -> ${HERE}/${PDB_ID}.pqr , ${HERE}/${PDB_ID}.dx"

scripts/apbs/prepare_apbs.sh

@@ -0,0 +1,27 @@
+# Real APBS electrostatics demo.
+# Inputs are produced by scripts/apbs/prepare_apbs.sh (pdb2pqr + apbs):
+#   scripts/apbs/2ewn.pqr  per-atom charges/radii
+#   scripts/apbs/2ewn.dx   Poisson-Boltzmann potential map (kT/e)
+
+# load the APBS-derived structure and potential map
+load scripts/apbs/2ewn.pqr, 2ewn
+load scripts/apbs/2ewn.dx, 2ewn_potential
+
+# molecular surface coloured by electrostatic potential (-5 .. +5 kT/e)
+show surface, 2ewn
+ramp_new 2ewn_esp, 2ewn_potential, [-5, 0, 5], [red, white, blue]
+set surface_color, 2ewn_esp, 2ewn
+
+# set the view (same camera as scripts/demos/surface.pml)
+set_view (\
+    -0.278456718,    0.878569365,    0.388043523,\
+    -0.570280433,    0.173850223,   -0.802842677,\
+    -0.772814512,   -0.444850624,    0.452621192,\
+    -0.000000000,    0.000000000, -208.479782104,\
+     3.418830872,   47.872474670,  -38.216609955,\
+   164.367050171,  252.592514038,   20.000000000 )
+
+# render & save
+ray 1920, 1080
+png assets/demo_apbs.png
+quit