pyDelPhi is a high-performance, Python-based reimplementation and extension of the classic DelPhi electrostatics solver. It provides accurate and efficient solutions to the Poisson–Boltzmann (PB) equation for biomolecular systems, with both CPU and GPU (CUDA) acceleration.
-
Methodologically Consistent Reimplementation
- Fully compatible with DelPhi 8.5 reference outputs.
- Validated across protein, nucleic-acid, and viral capsid benchmarks.
-
High-Performance Backends
- CPU parallelization via
Numbaandprange. - GPU acceleration through CUDA kernels.
- CPU parallelization via
-
Model Support
- Linear and nonlinear PB formulations.
- Classical and Regularized PB formalisms.
- Traditional two-dielectric and Gaussian dielectric models.
- Cubic and cuboidal grid geometries with automatic padding control.
-
Precision and Solvers
- Single / double precision arithmetic.
- Successive Over-Relaxation (SOR) and Newton-like (NWT) iterative solvers.
-
Modular and Extensible Architecture
- Designed for scientific transparency, benchmarking, and reproducibility.
- Python = 3.12
- CUDA Toolkit ≥ 12.0 (optional for GPU backend)
Core dependencies:
numpy >= 2.2.2,<2.3
numba >= 0.61.2,<0.62Optional (profiling / plots):
scipy
pandas
matplotlib
seaborn
psutilTo ensure stable operation and avoid dependency conflicts, it is strongly recommended to install pyDelPhi inside a dedicated Conda or Miniconda environment.
Use a versioned environment name for clarity and reproducibility, for example:
conda create -n py312_pydelphi_v0_2_0 python=3.12
conda activate py312_pydelphi_v0_2_0git clone https://github.com/delphi001/pyDelPhi.git
cd pyDelPhi
pip install .Verify installation:
python -m pydelphi --versionpyDelPhi provides three primary executables:
| Command | Purpose |
|---|---|
pydelphi-static |
Run a single Poisson–Boltzmann (PB) electrostatics calculation |
pydelphi-test |
Execute regression and consistency tests |
pydelphi-help |
Access built-in documentation and parameter reference |
Run the solver on a biomolecular system:
pydelphi-static --param-file params.inp --platform cuda --precision double --threads 32Usage
usage: pydelphi_static.py [-h] [-V] [-P {cpu,cuda}] [-p {single,double}]
[-t THREADS] [-d DEVICE_ID] [-f PARAM_FILE]
[-v {critical,error,notice,warning,info,debug,trace}]
[-l LABEL] [-o OUTFILE] [-O] [-S]
| Flag | Description | Default |
|---|---|---|
-h, --help |
Show help and exit | — |
-V, --version |
Print version and exit | — |
-P, --platform {cpu,cuda} |
Compute platform | cpu |
-p, --precision {single,double} |
Real precision | double |
-t, --threads |
Number of CPU threads | 1 |
-d, --device-id |
GPU device ID | 0 |
-f, --param-file |
Input parameter file (required) | — |
-v, --verbosity |
Output verbosity (critical→trace) |
info |
-l, --label |
Label for run | pdbid |
-o, --outfile |
Output CSV filename | outputs.csv |
-O, --overwrite |
Overwrite output file | False |
-S, --setup-timing |
Print setup timing | False |
Example:
pydelphi-static -f examples/1CRN_params.inp -P cuda -p double -t 64 -l 1CRNRun automated regression tests to verify consistency and numerical accuracy.
pydelphi-test --helpUsage
usage: pydelphi-test [-h] [--no-cuda] [--no-parallel] [--no-single] [--no-double]
| Flag | Description |
|---|---|
-h, --help |
Show help and exit |
--no-cuda |
Skip tests involving CUDA platforms |
--no-parallel |
Skip tests with more than one thread |
--no-single |
Skip tests using single precision |
--no-double |
Skip tests using double precision |
Example:
pydelphi-test --no-cuda --no-parallelUse these flags to suppress specific test categories when certain platforms or configurations (e.g., GPU hardware) are unavailable.
This ensures clean, reproducible regression runs across heterogeneous environments.
Interactive access to parameter definitions, defaults, and references.
pydelphi-help -hUsage
usage: pydelphi-help [-g group] [-n param_name]
| Flag | Description |
|---|---|
-g, --group |
Print help for all parameters in a group |
-n, --param-name |
Show detailed help for one parameter (supports aliases) |
-h, --help |
Show this message and exit |
Examples:
pydelphi-help -g grid
pydelphi-help -n surfmethodSample Output
full_name: surface_method
long_name: surfacemethod
short_name: surfmethod
unit:
data_type: SurfaceMethod
options:
VDW : Van der Waals surface. (Rocchia et al. 2001, JCC https://doi.org/10.1002/jcc.1161)
GAUSSIAN : Gaussian smoothed surface. (Panday et al. 2024, JCC https://doi.org/10.1002/jcc.27496)
GAUSSIANCUTOFF: Cutoff-based Gaussian surface (vacuum). (Chakravorty et al. 2018, JCTC https://doi.org/10.1021/acs.jctc.7b00756)
GCS : Gaussian Convolution Surface for RPBE. (Wang et al. 2021, MBE https://doi.org/10.3934/mbe.2021072)
default: SurfaceMethod.VDW
description: Method for defining solute and solvent regions:
choices {"GCS","GAUSSIAN","VDW"} (default: GAUSSIAN)
This command enumerates valid parameter names & aliases, data types, default values, and key references—serving as an in-terminal manual for all pyDelPhi inputs.
While end users typically run pyDelPhi via the command-line interface (pydelphi-static),
developers and advanced users can invoke the solver directly through the DelphiApp API.
This mirrors the same flow as the CLI driver — parsing parameters, configuring runtime,
and executing the solver under a specified platform and precision context.
Example:
from pydelphi.app.delphi import DelphiApp
from pydelphi.foundation.platforms import Platform
from pydelphi.foundation.enums import Precision
# --- Configure platform and precision ---
platform = Platform("cuda", debug=False)
platform.activate("cuda", threads=64, device_id=0)
platform.set_precision(Precision.DOUBLE)
# --- Initialize and run DelphiApp ---
app = DelphiApp(param_file="examples/1CRN_params.inp", platform=platform)
energies = app.run(outfile="outputs.csv", label="1CRN", overwrite=True)
print(f"Reaction Field Energy (kT): {energies['E_rxn_kT_tot']:.6f}")This entry point allows pyDelPhi to be embedded in Python workflows —
for instance, within MD post-processing pipelines, automated electrostatics scans,
or large-scale benchmarking scripts — while maintaining full compatibility
with CLI-based parameterization.
Comprehensive benchmarking of pyDelPhi — including accuracy validation,
runtime scaling, and memory efficiency across datasets pm74, pp46, pd66,
and viral capsid systems — is detailed in the accompanying publication:
Pandey, S. K. et al. (2025)
Accurate and Scalable Continuum Electrostatics for Large Biomolecular Systems: The pyDelPhi Poisson--Boltzmann Framework
(manuscript in preparation)
The benchmarks compare pyDelPhi against the original DelPhi (C++) implementation,
demonstrating numerical equivalence and substantial acceleration on both CPU and GPU platforms.
pydelphi/
├── app/ # High-level API (DelPhiApp entry point)
├── config/ # Global runtime configuration and logging
├── constants/ # Physical constants, elements, and residue data
├── data/ # Reference datasets and test examples (1he8, 5tif, sphere, etc.)
├── energy/ # Energy term calculators (Coulombic, Reaction Field, Nonpolar)
├── foundation/ # Core enums, context management, and platform abstractions
├── scripts/ # CLI tools (pydelphi-static, pydelphi-help)
├── site/ # Site generation and file writing utilities
├── solver/ # PB solvers (linear, nonlinear, SOR, NWT, RPBE)
├── space/ # Dielectric and grid-space generation (VDW, SAS, Gaussian)
├── tests/ # Regression and unit test suite
└── utils/ # Supporting utilities (I/O, precision, CUDA helpers)
Ancillary files:
├── LICENSE # GNU AGPLv3 license
├── pyproject.toml # Build and dependency metadata
├── PKG-INFO # Distribution metadata (auto-generated)
└── README.md # Documentation file (this document)
pyDelPhi follows a modular, layered architecture designed for both clarity and extensibility:
CLI Entry (scripts/)
↓
Runtime Configuration (config/, foundation/)
↓
Compute Backend (Platform, Precision, Verbosity)
↓
Application Layer (app/DelphiApp)
↓
Numerical Solvers (solver/, space/, energy/)
This structure enables reproducible command-line execution while allowing developers to extend components independently — for example, adding new solvers, backends, or dielectric models without modifying user-facing tools.
The main entry point for static PB calculations is defined in
pydelphi/scripts/pydelphi_static.py.
Simplified execution flow:
def main():
# 1. Parse command-line arguments
args = parse_arguments()
# 2. Handle version or input validation
if args.version:
print_pydelphi_version_info(); exit(1)
if not args.param_file:
print("Error: Parameter file required."); exit(1)
# 3. Configure output and runtime
check_output_file(args.outfile, args.overwrite)
platform = Platform(args.platform, debug=False)
platform.activate(args.platform, args.threads, args.device_id)
platform.set_precision(Precision[args.precision.upper()])
set_precision(platform.precision)
set_verbosity_level(str_to_verbosity(args.verbosity))
# 4. Initialize and run application
from pydelphi.app.delphi import DelphiApp
app = DelphiApp(args.param_file, platform, user_inputs=None)
energies = app.run(args.outfile, args.label, args.overwrite)Key principles:
- Single entry point: CLI handles argument parsing and safety checks only.
- Explicit configuration: Platform, precision, and verbosity are globally set before solver execution.
- Encapsulation: All computational logic resides inside
DelphiApp. - Reproducibility: Every calculation is parameter-driven and version-logged.
| Area | Module Path | Description |
|---|---|---|
| New solvers | pydelphi/solver/ |
Add new iterative schemes or nonlinear models. |
| Surface / dielectric models | pydelphi/space/core/ |
Implement Gaussian or hybrid boundary schemes. |
| Energy components | pydelphi/energy/ |
Add analytical or empirical energy terms. |
| Platform abstraction | pydelphi/foundation/platforms.py |
Extend to new backends or accelerators. |
| Configuration system | pydelphi/utils/io/inproc_helpers/param_definitions/ |
Define new .prm keywords with aliases and validation. |
Each component is self-contained and unit-tested, ensuring that scientific accuracy and reproducibility are preserved during extension.
-
Run validation suite locally:
pydelphi-test --no-cuda
(use
--no-doubleor--no-singleto isolate precision tests) -
Profile a new feature:
python -m pydelphi.app.delphi my_params.prm
-
Inspect runtime configuration:
pydelphi-help -n <param_name>
-
Benchmark changes:
Compare solver time and energy RMSD against DelPhi reference TSVs in
pydelphi/data/test_examples/.
“Accuracy is physics; performance is engineering.”
pyDelPhi separates physical formulation (solver & dielectric model)
from computational engineering (platform, precision, threading) —
ensuring transparent, scientifically rigorous, and performance-portable implementations.
If you use pyDelPhi in your work, please cite:
Pandey, S. K. et al. (2025)
Accurate and Scalable Continuum Electrostatics for Large Biomolecular Systems: The pyDelPhi Poisson--Boltzmann Framework
(manuscript in preparation)
Contributions are welcome — see CONTRIBUTING.md for style, testing, and PR guidelines.
Bug reports and enhancement requests can be submitted via GitHub Issues.
pyDelPhi is released under the
GNU Affero General Public License v3 (AGPL-3.0).
This file is part of pyDelPhi.
pyDelPhi is free software: you can redistribute it and/or modify it under the terms of the GNU Affero General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
pyDelPhi is distributed in the hope that it will be useful, but without any warranty; without even the implied warranty of merchantability or fitness for a particular purpose.
See the full license text inLICENSEor visit https://www.gnu.org/licenses/.
- DelPhi (C++) developers for foundational algorithms
- Numba and CUDA Python communities for enabling hybrid acceleration
- Computational resources provided by the Clemson Palmetto HPC Cluster
“Accuracy is physics; performance is engineering — pyDelPhi unites both.”