PB
PB
PB is a software for numerically solving the one-dimensional PoissonBoltzmann equation for different boundary conditions and symmetries
Version 2.4.1
Documentation update June 2015
Per Linse
Division of Physical Chemistry
Department of Chemistry
Lund University, P.O. Box 124
S-221 00 Lund, SWEDEN
This document can be downloaded from www.physchem.lu.se/sm
1
PB
Copyright 1982-2015 by Per Linse. All rights reserved.
The software PB may not be redistributed or modified, with the exception of the routines in source
file pbuser.F90, without the written consent of the copyright owner. The copyright owner does not
take any responsibility for any software in the code or its documentation.
We hope that the software will be useful for you and request a proper reference (PB, Version 2.4.1,
P. Linse, Lund University, Lund, Sweden 2015) when using it.
2
PB
Preface
This documentation describes the software PB. After a short introduction, information of how to
install the software, to set up an environment for a user, and to run it is provided. Thereafter, an
explanation of all input variables divided into subsections is given, and the namelist technique used
is explained in an appendix. The remaining chapters deal with user-provided routines and more
technical aspects important for a more advanced use of the software.
Only the use of the software is given in the documentation. It is assumed that the user has a general
understanding of the relevant theory. Very few references are provided here; however, further
references are given in the source code, often at the top of the routines.
The software PB is written in Fortran 95. It can be run interactively or in a batch environment. The
connection between external units and files is made in a command file.
3
PB
Table of contents
1. Introduction ...................................................................................................................................... 5 2. Installation ....................................................................................................................................... 6 3. Getting started .................................................................................................................................. 7 4. Input ................................................................................................................................................. 8 4.1. Namelists .................................................................................................................................. 8 4.2. Input variables........................................................................................................................... 8 4.2.1. nmlSystem ......................................................................................................................... 8 4.2.2. nmlIteration ...................................................................................................................... 10 5. User-provided routines .................................................................................................................. 12 6. Distributed files.............................................................................................................................. 13 7. External units ................................................................................................................................. 14 8. Routines ......................................................................................................................................... 15 8.1. pb.f90 ...................................................................................................................................... 15 8.2. pblib.f90 .................................................................................................................................. 15 8.3. pbuser.f90 ............................................................................................................................... 16 9. Appendix A. Namelist ................................................................................................................... 17 10. Appendix B. Suggestions or problems? ....................................................................................... 18
4
PB
1. Introduction
PB
is a software for numerically solving the one-dimensional Poisson-Boltzmann equation. The
equation describes the electrostatic potential and the distribution of mobile small ions near a charged
impenetrable surface in contact with a solution.
Five different geometries are supported: (i) inverse sphere, (ii) inverse cylinder, (iii) plane, (iv)
cylinder, and (v) sphere. In the two first cases, the systems are obviously of finite extension, whereas
in the three later ones either a finite (cell model) or a semi-infinite extension can be selected.
Throughout, either the Poisson-Boltzmann equation or its linearized version can be chosen. The
solution may contain counterions only, or include added salt. For many conditions the option fixed
surface charge density or fixed surface potential can be selected.
The main results provided by the software are (i) thermodynamic properties, (ii) electrostatic
potential, (iii) electrostatic field, and (iv) concentration profiles. Analytic solutions to the PoissonBoltzmann equation are also provided in those cases where such exist.
The numerical solution of the Poisson-Boltzmann equation is obtained by iteratively improving the
ion concentration(s) (cell model) or a prefactor of the potential (infinite extension) far away from the
charged surface until self-consistency within a given tolerance is achieved. This is performed by a
Newton-Raphson procedure. The differential equation is solved by an adaptive Runge-Kutta method.
The initial ion concentration(s) or the potential prefactor can be selected from (i) built-in standard
guesses, (ii) the input file, and (iii) a previous calculation. Most often, a standard guess is sufficient.
It is easy to add user-provided routines to the software to enhance the capability of it. These
routines may, e.g., perform additional analyses or facilitate sequential calculations. The userprovided routines are collected in the file pbuser and do not belong to the supported software. An
existing input variable controls the calls of these routines.
The specification of input variables characterizing the model and controlling the calculation is
given in an input file. That makes it easy to make sequential calculations with only minor differences
in the specification. Both names and values of the variables are given in input file using the Namelist
protocol, making it easy to read and prepare input files. Blocks of input data are collected into
separate groups.
5
PB
2. Installation
This chapter describes how to install the software PB on a Unix(Linux)-based workstation after
obtaining the installation file pb.xxx.tar.gz, where xxx should be replaced by three digits (version
number).
In the following, your top directory is referred to as $(HOME). The installation involves the following
steps:
–
–
–
–
Create the directory PB in the directory $(HOME)
Copy the file pb.xxx.tar.gz to the directory PB
Go to file directory PB
Type 'tar -zxf pb.xxx.tar.gz'
The tar command (i) creates the subdirectory Src, which in the following is referred to as the source
directory, and (ii) places the source files into the source directory. The name and content of the
distributed files are given in chapter 6.
– Go to directory Src
– Open the makefile and if necessary edit it for appropriate compiler
– Type 'make'
The make command starts compilation and linking. After completion, (i) additional files have been
created in the source directory, (ii) a subdirectory Bin has been created and now contains the
executable pb.exe, and (iii) the file pb has been copied from the source directory to $(HOME)/bin.
Note, the environmental variable PATH has to contain $(HOME)/bin for the software to function.
– The installation file pb.xxx.tar.gz in directory PB can now be removed
The installation of the software is now completed.
6
PB
3. Getting started
This chapter describes how to execute the software.
– Create a work subdirectory, in which corresponding input and result files will reside
This directory will in the following be referred to as the work directory. The location of the work
directory is arbitrary.
– Copy an input file, here referred to as job.in, to the work directory
An input file could, e.g., be retrieved from www.physchem.lu.se/sm. At this moment we will not
consider the content and the meaning of the variables in the input file. The input variables are the
subject of the next chapter.
– Type 'pb job'
After execution the output file job.out have been created in the work directory.
The content of the output file should be essentially the same as that obtained by execution trough
www.physchem.lu.se/sm. If not, probably some error has occurred in the transfer of the code or
during the installation.
7
PB
4. Input
All input data read from the file FIN are done with the namelist procedure. Each namelist contains
related input variables. Further information on the namelist procedure is given in Appendix A.
4.1. Namelists
The program uses the following namelists in the order given below.
nmlSystem
Variables describing the physical system
Variables describing the numerical solution
nmlIteration
4.2. Input variables
This subsection contains all input variables that are used for reading data from file FIN. The variables
are grouped together and listed below their namelist name. The first line contains the name, the type,
the dimension, and, if any, the default value of the variable. The following lines briefly explain the
use of the variable. If the variable only can attain a limited number of values, these are listed. If
description about writing data is given, the output is made on file FOUT (if nothing else is stated).
A practical point. Often there is a need of reading a variable conditionally, i.e. if some condition is
true the variable is assigned a value and used later. If the condition is false, the presence of the
variable in the input file does no harm; thus it has not to be deleted. In the latter case the input file
contains redundant data.
4.2.1. nmlSystem
The namelist nmlSystem contains variables that describe the physical system.
txTitle
character(80)
User-provided title.
txUser
character(15)
For user-provided routines.
txSymmetry
'inverse sphere'
'inverse cylinder'
'plane'
'cylinder'
'sphere'
character(16)
Mobile ions inside a charged sphere.
Mobile ions inside a charged and infinitely long cylinder.
Mobile ions outside a charged and infinitely large plane.
Mobile ions outside a charged and infinitely long cylinder.
Mobile ions outside a charged sphere.
txBoundCond
'cell_fix'
'cell_equ'
character(8)
/'cell_fix'/
Cell model. Fixed salt concentration of the cell specified by ConcSalt.
Cell model. Salt is required. Equilibrium with bulk salt solution specified by
ConcSalt.
Semi-infinite system. Salt is required. Only for txSymmetry = 'plane',
'cylinder', or 'sphere'.
'infinite'
txEquation
'nonlinear'
character(9)
Nonlinear PB equation.
/'plane'/
/'nonlinear'/
8
PB
'linear'
Linear PB equation.
txSurface
'charge'
'potential'
character(8)
Fixed surface charge density.
Fixed surface potential. Requires salt and txBound /= 'cell_fix').
Temp
real
Temperature (K).
EpsiR
real
Relative permittivity.
R0
real
Location of the cell boundary (Angstrom) (txBoundCond = 'cell_fix' and
txBoundCond = 'cell_equ')
Location where the numerical solution is started (txBoundCond = 'infinite') for
txSymmetry = 'plane', 'cylinder', or 'sphere'.
R1
real
Location of charged surface (Angstrom).
SurfCharge
real
Surface charge density (C/m2).
SurfPot
real
Surface potential (V).
nSpec
integer
Number of different species. Species 1 should be the counterions to the
charged surface.
ChargeIn
real
(1:mnSpec)
Valence of the different ions.
ConcSalt
real
(1:2)
/2*0/
Mean salt concentration of the cell (txBoundCond = 'cell_fix')
Bulk salt concentration (txBoundCond = 'cell_equ' or 'infinite' )
Salt concentration (M). ConcSalt(1) involves species 1 and 2, whereas
ConcSalt(2) involves species 3 and 2.
iTest
0
>0
integer
Nothing.
Flag for test output. This possibility is for maintenance purposes.
/0/
iShow
0
>0
integer
Nothing.
Calculated functions are listed at every iShow bin. Compact list.
/0/
9
/' charge'/
PB
iPlot
0
>0
integer
Nothing.
Calculated functions are plotted.
iList
0
>0
integer
/0/
Nothing.
Calculated functions are listed at every iList bin on file FLIST. Extended list.
/0/
4.2.2. nmlIteration
The namelist nmlIteration contains variables that describe the numerical solution.
txIter
'standard'
'new'
'old'
character(8)
/'standard'/
Initial Conc0 equal to mean concentration (txBoundCond='cell_fix')
Initial RedPot0 equal to -sign(One, Charge(1)) (txBoundCond='cell_equ')
Initial PreFac equal to -sign(One, Charge(1)) (txBoundCond='infinite').
Initial Conc0 read from FIN (txBoundCond='cell_fix').
Initial RedPot0 read from FIN (txBoundCond='cell_equ')
Initial PreFac read from FIN (txBoundCond='infinite').
Initial Conc0 read from FAUX (txBoundCond='cell_fix').
Initial RedPot0 read from FAUX (txBoundCond='cell_equ')
Initial PreFac read from FAUX (txBoundCond='infinite').
Conc0
real
(1:mnSpec)
Start: initial boundary concentration (txBoundCond='cell_fix').
End: final boundary concentration (txBoundCond='cell_fix').
Species 1 is should be the counterion to the charged surface.
RedPot0
real
Start: initial reduced potential at R0 relative to bulk (txBoundCond='cell_
equ').
End: final reduced potential at R0 relative to bulk (txBoundCond='cell_ equ').
PreFac
real
Start: initial potential prefactor (txBoundCond='infinite').
End: final potential prefactor (txBoundCond='infinite').
Potential = PreFac*exp(-Kappa/r) (txSymmetry='plane').
Potential = PreFac*exp(-Kappa/r)/sqrt(r) (txSymmetry='cylinder').
Potential = PreFac*exp(-Kappa/r)/r (txSymmetry='sphere').
DampNR
real
Damping factor in NR-iteration.
TolNR
real
Required tolerance in NR-iteration.
nInterNR
integer
/0.0/
/1e-6/
/10/
10
PB
Maximal
number
of
NR-iterations
in
obtaining
Conc0
(txBoundCond='cell_fix'), RedPot0 (txBoundCond='cell_equ'), or PreFac
(txBoundCond='infinite').
TolRK
real
Required tolerance in RK-iteration of x(nStep).
11
/1e-6/
PB
5. User-provided routines
The file pbuser.f90 contains routines that are conditionally called and which might be modified by
the user. This allows the software to be extended without having to modify the core of it.
The existing code in the distributed file pbuser.f90 reflects the current use of it. The procedure to
insert a new routine is as follows:
– At the appropriate position in driver pbuser, extend the test of txUser and write the appropriate
call to the new subroutine
– Add your new subroutine in pbuser.f90
– Compile
12
PB
6. Distributed files
This chapter contains a complete list of the distributed source files.
pb.f90
pblib.f90
pbuser.f90
pb.ver
pb
makefile
archive
Main code of PB
Library routines
User-provided routines
Description of version changes
Command file for execution
Makefile for compilation and linking
Command file for filing
13
PB
7. External units
A file is specified by its name and type, which are separated by a dot. The file types are used in a
predetermined way to describe the use of the file and leaves file name to label the project.
File type
in
out
aux
list
user
Generic name Content
Input data
FIN
Output data
FOUT
Iteration variables
FAUX
List data
FLIST
Avail for the user
FUSER
Flow chart of the use of external files. Bold arrows denote files that are always required or
generated, while thin arrows denote files that might be required or generated, depending on input
variables.
FIN
FAUX
FOUT
FAUX
PB
FLIST
FUSER
FUSER
14
PB
8. Routines
This chapter lists the routines in the software. The routines are listed according to the Fortran files
they are located in and in the order they appear in the files.
8.1. pb.f90
main module of PB
main routine of PB
PB
perform i/o on system variables
IOSystem
perform i/o variables describing the iterative numerical solution
IOIteration
perform the analyses
Analyse
calculate volume, concentration profiles, and mean concentrations
CalcConc
calculate the surface charge density from the species
CheckSurfaceCharge
CheckContactTheorem check the contact theorem for planar symmetry
calculate energy from Conc0, Conc1, etc
CheckEnergy
return the volume
Volume
return the largest common divisor of two integers
LargestDevisor
exact solution: PB equation, planar sym, cell geometry, counterions only
PlaneCell
exact solution: PB equation, planar sym, infinite system, z:z electrolyte
PlaneInfinite
exact solution: PB equation, planar sym, infinite system, linearized
PlaneInfiniteLin
exact solution: PB equation, reverse cyl sym, counterions only
RevCylCell
exact solution: PB equation, sphere, infinite system, linearized
SphInfiniteLin
iterate to correct Conc0(j) using NR procedure
NewRapCellFix
iterate to correct RedPot0 using NR procedure
NewRapCellEqu
iterate to correct PreFac using NR procedure
NewRapCellInfinite
driver of RKStep
RKDrive
calculate the derivatives
Derivatives
PBModule
8.2. pblib.f90
TrapNe
MatInv
NewRap
RKStep
RK4
WriteHead
LinInter
WriteDateTime
CpuTot
Second
Warn
Stop
LowerCase
UpperCase
Plot
integration by the trapezoidal rule with varying step length
matrix inversion with solution of linear equations
perform a Newton-Raphson iteration
fifth-order Runge-Kutta with adjustable step size
routine called by RKStep integrating from x to x+h
write a heading
linear interpolation between (x0,y0) and (x1,y1)
write date and time
write total cpu time elapsed since start
return cpu time used since start (in seconds)
write a warning message
write a warning message and stop the process
change a string to lower case
change a string to upper case
plot a function
15
PB
8.3. pbuser.f90
PBUser
LoopPB
ChargeEffective
Diffusion
CalcDiffusion
driver of user-provided routines
control the loops over complete calculations
first loop: nonlinear pb
calculate the reduced diffusion coefficient in a spherical cell
calculate the reduced diffusion coefficient in a spherical cell
16
PB
Appendix A. Namelist
– A namelist consists of (i) one start statement, (ii) one end statement, and (iii) a list (possibly
empty) between the start and end statements.
– The start statement consists of an ampersand (&) followed by the name of the namelist.
– The end statement consists of a slash (/).
– The list is composed of variables and their values separated with either by commas.
– The order of the variables and their assignments is normally irrelevant.
– However, if a variable is assigned values more than once, the last one takes place.
– Arrays are allocated either element by element, consecutively by listing values separated by
commas, or by a combination of these to ways.
– A value, say 5, appearing r times may be expressed as r*5.
– Note the order Fortran stores arrays elements: the left most index is running fastest and the right
most slowest.
– Comments are allowed and should proceed by an exclamation sign (!).
– Generally, if a program reads several namelists, they have to occur in the inputfile in the same
order as they are read from the program. Here, this is relaxed; the order of the namelist is
arbitrary.
– A namelist with no list (empty namelist) has to be specified.
– Namelists that are not read by the program do no harm.
Example: Consider the following declarations
character(4) :: title
integer(4) :: m, n
real(8) :: ARR1(1:3), ARR2(1:2,1:2), ARR3(1:2,1:2)
The namelist nmlSystem below illustrates an element-by-element array assignment
&nmlSystem
title = 'head',
n = 10, m = 10,
n = 20,
arr1(1) = 1.5, arr1(2) = 2.5, arr1(3) = 2.5,
arr2(1,1) = 1.0, arr2(2,1) = 2.0, arr2(1,2) = 3.0, arr2(2,2) = 4.0,
arr3(1,1) = 1.0, arr3(2,1) = 2.0, arr3(1,2) = 3.0, arr3(2,2) = 4.0,
/
which could, for example, be shortened to
&nmlSystem
title = 'head',
n = 20,
m = 10,
arr1 = 1.5, 2*2.5,
arr2 = 1.0, 2.0, 3.0, 4.0,
arr3(1,1) = 1.0, 2.0, arr2(1,2) = 3.0, 4.0,
/
17
PB
9. Appendix B. Suggestions or problems?
I would be happy to hear from you if you have any suggestions or problems with the PB software or
with this documentation. If so, send
–
–
–
–
–
–
Date
Name
E-mail address
PB version number
Host computer (name and configuration)
Suggestion or problem in as much detail as possible
to: [email protected]
18