Solvated Jellium (constant-potential electrochemistry)
Overview
The Solvated Jellium method (SJM) is a simple method for the simulation of electrochemical interfaces in DFT.
A full description of the approach can be found in [Kastlunger2018].
The method allows you to control the simulated electrode potential by varying the number of electrons in the simulation; calculations can be run in either constant-charge or constant-potential mode. By default, this electrode potential is probed as the topside work function of the slab, but it can also be probed as the inner potential of the electrode (see The electrode potential section) or a custom metric.
SJM is attached to a regular GPAW calculator as an extension—GPAW(..., extensions=[SJM(...)])—and the calculator is then used just like any other; it returns energy and forces, but can do so at a fixed potential.
The number of excess electrons and the electrode potential are returned alongside them, as the excess_electrons and electrode_potential properties.
(Please see the note below on the Legendre-transform of the energy.)
The potential is controlled by a simple iterative technique; in practice if you are running a trajectory (such as a relaxation or nudged elastic band) the first image will take longer than a conventional calculation as the potential equilibrates, but the computational cost is much less on subsequent images.
For a practical guide on the use of the method, please see the Solvated Jellium Method (SJM) tutorial.
Theoretical background
The philosophy of the solvated jellium method is to construct the simplest model that captures the physics of interest, without introducing spurious effects. The solvated jellium approach consists of two components: jellium and an implicit solvent. A schematic is shown below:
In this figure, the jellium is shown by the hatched region, while the implicit solvent is shown in the blue shaded region. Note that an explicit solvent (the water molecules) is also conventionally used in this approach, as the major purpose of the implicit solvent is not to simulate the solvation of individual species but rather to screen the net field. A more detailed discussion of both of these components follows.
The jellium slab: charging
In a periodic system we cannot have a net charge; therefore, any additional, fractional electrons that are added to the system must be compensated by an equal amount of counter charge.
SJM accomplishes this by adding a smeared-out background charge in a defined region of the simulation cell; in the figure above it is shown as the hatched region to the right of the atoms.
By default that region is a slab perpendicular to \(z\), controlled by the jelliumregion key described under Usage below.
The number of electrons in the simulation is increased by an amount equal to the total charge of that region.
When you run a simulation, you should see that these excess electrons localize on the \(+z\) side (the right side in these figures) of the metal atoms that simulate the electrode surface, and not on the \(-z\) (left) side, which simulates the bulk.
This is accomplished by only putting the jellium region on one side of the simulation, and employing a dipole correction (included by default when you run SJM) to electrostatically decouple the two sides of the cell.
The figure below shows the difference in two simulations, one run at 4.4 V and one run at 4.3 V. The orange curve shows where the potential drops off, and the blue curve shows where the electrons localize. Note that the steep potential dropoff at the bottom of the cell is only a consequence of the alignment of the electrostatic potential at the cell boundary, and is not a physical effect.
The jellium region is conventionally thought of as a region of smeared-out positive charge, accompanied by a positive number of electrons.
However, the signs can readily be reversed, making the jellium region a smeared-out negative region accompanied by a reduction in the total number of electrons.
In this way, the same tool can be used to perturb the electrons in either a positive or negative direction, and thus vary the potential in either direction in order to find its target.
Note also that the jellium region does not overlap with any atoms, separating this from approaches that employ a homogeneous background charge throughout the unit cell (in which spurious interactions can occur).
This is important to not distort the electronic structure of the atoms and molecules being simulated.
Additionally, note that the jellium is enclosed in a regular slab geometry in the figure above, but this need not be the case in general; other shapes—for example one following the cavity of the implicit solvent—are a planned extension of the jelliumregion key, though only the slab is available in this version (the legacy gpaw.solvation.sjm.SJM calculator, which only works in \(fd\) mode, does offer a cavity-shaped counter charge).
The solvation: screening
By itself, the excess electrons and the jellium counter charge would set up an artificially high potential field in the region of the reaction. To screen this large field, an implicit solvent is added to the simulation in the region above the explicit solvent, completely surrounding the jellium counter charge. For this purpose, the solvated jellium method employs the implicit solvation model of Held and Walter [Held2014], which changes the dielectric constant of the vacuum region. (You can learn more about the solvation method in the Continuum Solvent Model (CSM) tutorial.)
Here, the primary purpose of the implicit solvent is not to solvate the species reacting at the surface; explicit solvent (shown by the water molecules above) is typically employed in SJ simulations for this purpose. The implicit solvent is located above the explicit solvent (and therefore may provide some solvent stabilization to the explicit solvent molecules). This can be seen in the figure above, where the implicit solvent is shown as the blue shaded region. In this figure, the small amount of solvent that is apparent at a \(z\) coordinate corresponding to the water layer is just the result of the implicit solvent penetrating slightly into the cavity at the center of a hexagonal ice-like water structure. It is important that the implicit solvent not be present in the region of the reaction, as this would be “double”-solvating those parts. If this occurs, the implicit solvent can be actively removed through either adding “ghost” atoms or a plane of minimal \(z\) to be solvated. Other non-local models are planned for future versions of the SJM.
Generalized Poisson equation
In net, the SJ method is manifested as two changes to the generalized Poisson equation,
where \(\epsilon(\br)\) accounts for the solvation; that is, the dielectric constant is spatially variant, and the spatially-resolved charge density is modified by the presence of the \(\rho_\mathrm{jellium}(\br)\) term, which contains the smeared-out counter charge in a region away from all of the atoms (and electronic density) of the system. \(\rho_\mathrm{explicit} (\br)\) contains the standard charge density of the system; that is, due to the electrons and nuclei. Since the changes to the Poisson equation are relatively simple, it can be solved without relying on linearization.
When the electrode potential is defined as the work function, the generalized Poisson equation is solved with Neumann boundary conditions. When the inner potential is used to define the electrode potential, the generalized Poisson equation is solved with Dirichlet+Neumann boundary conditions as discussed in [Melander2024]. The Dirichlet boundary condition sets the electrostatic potential to zero at the top of the cell while Neumann boundary conditions set the electrostatic potential gradient to zero.
The electrode potential
The electrode potential can be defined in two ways: as the work function (wf) or as the electrode inner potential (CIP). The latter currently only works with the legacy gpaw.solvation.sjm.SJM calculator, but is planned to be implemented in the new SJM calculator in a future release.
Work function: This is SJM’s default way of computing the electrode potential. It is the Fermi-level energy \(\mu\) referenced to a point deep in the solvent, \(\Phi_\mathrm{w}\), where the whole charge on the electrode has been screened and no electric field is present. (This is equivalently the topside work function of the slab.) This is divided by the unit electronic charge \(e\) to convert from energy (typically in eV) to potential (typically in V) dimensions.
Note that this gives the potential with respect to vacuum; if you would like your potential on a reference electrode scale, such as SHE, please see the Solvated Jellium Method (SJM) tutorial.
Inner potential: This electrode potential scale uses the constant inner potential DFT (CIP-DFT) developed in [Melander2024]. CIP-DFT uses the electrode inner potential (\(\phi\)) as the electrode potential. This method is always used with the Dirichlet boundary condition. To use this method one needs to provide the Fermi-level (\(\mu^{PZC}_e\)) and the inner potential (\(\phi^{PZC}\)) of the uncharged simulation cell, corresponding to the potential of zero charge (PZC), that is, at zero surface charge (\(\sigma=0\)). The applied electrode potential with respect to PZC at a given surface charge is then given as
Legendre-transformed energy
The energy used in the analysis of electrode reactions is the grand-potential energy
Whereas \(E_\mathrm{tot}\) is consistent with the forces in traditional electronic structure calculations, the grand-potential energy \(\Omega\) is consistent with the forces in electronically grand-canonical (that is, constant-potential) simulations. This means that relaxations that follow forces will find local minima in \(\Omega\), and generally methods that rely on consistent force and energy information (such as BFGSLineSearch or NEB) will work fine as long as \(\Omega\) is employed. Thus, this calculator returns \(\Omega\) by default, rather than \(E_\mathrm{tot}\).
Potential control
The below figure shows both the localization of excess electrons and the local change in potential, when the total number of electrons in an example simulation is changed.
As mentioned above, the excess electrons localize only on the top side of the slab, which is meant to represent the electrode surface, and not on the bottom side, which is meant to represent the bulk. The potential drop is seen to localize in the Stern layer where the reaction takes place.
The electrostatic potential is only defined up to a constant, so the traces in the upper panel have to be aligned somewhere before they can be compared, and where they are aligned decides where the fanning appears. SJM itself references the potential deep in the solvent, at the top of the cell, which is where it reads off the electrode potential; the traces here are instead aligned at the vacuum behind the slab, on the bulk side, so that the difference between two charge states accumulates across the slab and the Stern layer. The fanning on the solvent side is therefore a consequence of that alignment, not a separate physical effect: it is the same information as a rigid shift of each curve, displayed so that the region where the potential drop develops is the region where the curves separate. Note that the backside vacuum is not the point \(z = 0\); the alignment is taken midway between the lower cell boundary and the lowest atom, and the sharp feature below \(z \approx 2\,\mathrm{\AA}\) is where each trace returns to the value SJM pins in the solvent.
Over reasonable deviations, the relationship between the number of excess electrons and the potential \(\phi\) is approximately linear:
Due to the simple relationship between the excess electrons and the potential, reaching a desired potential is typically a fast process.
If you are running a trajectory—for example, a relaxation, a molecular dynamics simulation, or a saddle-point search—the first image will often converge the SCF cycle a few times (that is, sequential constant-electron calculations) until the desired potential is reached.
Atoms typically move relatively little from image-to-image in a trajectory; therefore, subsequent images are often already at the target potential and no equilibration steps are necessary; when equilibration steps are required, the slope (of potential vs. number of electrons) is recalled from the last adjustment, and it often only takes a single equilibration step.
Typically, over the course of a full trajectory, the added computational cost of working in the constant-potential ensemble is small.
As described in the Solvated Jellium Method (SJM) tutorial, this can sometimes be further improved by simultaneously optimizing the potential with the atomic positions; set a loose tol together with always_adjust=True, which keeps stepping the number of excess electrons—on to the next image, without re-converging the current one—even once the potential is within tolerance.
The slope itself is regressed over the last slope_regression_depth attempts and damped with the previous estimate by mixer; slope sets the initial guess, which is otherwise taken from an apparent capacitance of 10 muF/cm^2.
All of this is done by the simulated Potentiostat, which SJM builds from its potentiostat dict.
The potentiostat is a general charging and potential equilibration class rather than an SJM-specific one: it independently defines how the counter charge enters the cell (the charging scheme, a jellium slab here), how the potential is read off the converged state (the potential probe, the topside work function as a default) and how the charge is stepped toward the target (the optimizer, the slope regression described above as default), and all these pieces are interchangeable.
Constant inner potential (CIP) DFT:
Note
CIP-DFT is implemented only in the legacy
gpaw.solvation.sjm.SJM calculator, so this section uses that
calculator and its sj dictionary throughout.
The SJM can also be ran in the constant inner potential mode where the average electrostatic potential within the electrode, i.e. the inner potential, is controlled (see The electrode potential section). The usage of CIP-DFT is similar to the standard work function-based SJM with a few key changes.
To use CIP-DFT mode, one needs to specify the potential reference scale and cip dict in the sj dict:
sj_cip = {'target_potential': pot, # potential on the absolute potential scale
'pot_ref': 'CIP',
'cip': {'autoinner': {'nlayers': 4},
'mu_pzc': mu_pzc, # Fermi level at zero charge
'phi_pzc': phi_pzc # inner potential at zero charge,
}
}
The autoinner part automatically finds the inner region, in this case a 4-layer metal slab. The target electrode potential is given with respect to the inner potential (phi_pzc) and Fermi level (mu_pzc) at the potential zero charge (PZC).
For instance, if the PZC is 4.44 vs vacuum, then mu_pzc=-4.44, and the targeted potential is 0.6 vs SHE, then target_potential=3.84. The needed mu_pzc and phi_pzc parameters are most easily obtained as follows:
sj_calib = {'excess_electrons':0,
'pot_ref': 'CIP',
'cip': {'autoinner': {'nlayers': 4,
'threshold': 0.01}
}}
calc = SJM(sj=sj_calib...)
atoms.calc = calc
atoms.get_potential_energy()
phi_pzc = calc.get_inner_potential(atoms)
mu_pzc = calc.get_fermi_level()
Usage
The SJM extension takes two
keywords: potentiostat, the SJM settings, and solvation, the
implicit-solvent model (cavity, dielectric and
interactions):
from gpaw import GPAW, PW
from gpaw.extensions import SJM
calc = GPAW(mode=PW(400.), ...,
extensions=[SJM(
potentiostat=dict(
target_potential=4.4, # absolute scale, V
excess_electrons=0.0, # initial guess
tol=0.005, # V
max_iters=10,
jelliumregion={'top': -1., 'bottom': -3.}),
solvation=dict(cavity=cavity,
dielectric=dielectric,
interactions=interactions))])
The two can also be given by position, potentiostat first, so
SJM({'target_potential': 4.4}) sets only the potentiostat.
Each of the two can also be given as an object instead of a dict: a
gpaw.solvation.Solvation and a
Potentiostat, or subclasses of
them. Leaving out solvation gives water: the parameters of
gpaw.solvation.get_HW14_water_kwargs(), with an
SJMPower12Potential that keeps the solvent from
behind the electrode. A solvation model without a dipole layer of its own
gets GaussianDerivativeDipole(zero_vacuum=True), which puts the
electrostatic potential to zero in the vacuum at the top of the cell. The
electrode potential is read off that vacuum level.
Leaving out target_potential gives a constant-charge calculation at
the given number of excess_electrons. The
jelliumregion key takes 'top', 'bottom',
'thickness' and 'fix_bottom'. A negative 'top'
is a distance below the upper cell boundary, whereas a negative
'bottom' is a distance above the highest atom, in which case the
region follows the atoms during a relaxation unless
fix_bottom=True. This is the default slab-shaped region; a
'shape' key selects a different kind. With
grand_output=False, the canonical rather than the grand-potential
energy is handed to ASE.
To change the settings, keep the SJM(...) object in a variable
and call its change(potentiostat={...}), which takes any key of the
potentiostat dict but the parts:
sjm = SJM(solvation=..., potentiostat={'target_potential': 4.4})
atoms.calc = GPAW(..., extensions=[sjm])
atoms.get_potential_energy()
sjm.change(potentiostat={'target_potential': 4.3})
atoms.get_potential_energy()
Before the first calculation this simply changes the settings the
calculation will be started with; afterwards it changes them without
throwing away the wave functions. This replaces the legacy
calc.set(sj={...}).
Parts of your own: the potentiostat is built from three parts, each
with a default: the charging scheme
(JelliumCharging), the optimizer
(DirectOptimizer) and the
potential probe
(WorkFunctionProbe). The keys
excess_electrons and jelliumregion configure the default charging
scheme, and target_potential, tol, slope, mixer,
slope_regression_depth, max_potential_stepsize, max_iters and
max_reruns the default optimizer, which holds the target, decides when
the potential is converged (PotentialOptimizer.converged()) and sets
the limits of the equilibration. To use a part of your own, subclass
ChargingScheme,
PotentialOptimizer or
PotentialProbe and give an
instance under the charging, optimizer or potentialprobe key:
sjm = SJM(solvation=...,
potentiostat={'optimizer': MyOptimizer(target_potential=4.4)})
Its settings then go to the part itself: the keys of the default part it
replaces raise a ValueError. A .gpw file records a part of your
own by its class name only, so reading the file back raises
ValueError: Unknown SJM part.
The same object also offers:
sjm.potentiostat, the potentiostat that runs in the calculation (calc.dft.potentiostatis the same object), andsjm.solvation. The settings are read off the potentiostat and its parts, as live values:sjm.potentiostat.optimizer.target_potential,sjm.potentiostat.optimizer.slope(the current estimate),sjm.potentiostat.optimizer.tolandsjm.potentiostat.charging.region.todict(), and so the.gpwfile, records these live values. Change them throughchange()rather than by assignment: onlychange()clears the results and recomputes the occupations, density and potential, which makes the nextget_potential_energy()run the SCF loop again.electrode_potential, the electrode potential of the last converged SCF loop, in V on the vacuum scale, as the potential probe reads it—the work function at the top of the cell for the defaultWorkFunctionProbe. It is the same number ascalc.results['electrode_potential'], and NaN until an SCF loop has converged.excess_electrons, the current number of excess electrons, as the potentiostat adjusts it. Like the settings, it is set throughchange().write_sjm_traces(path='sjm_traces', style='z', props=...), which writes the electrostatic potential (in eV, referenced to the Fermi level), the solvent cavity and the jellium counter charge (in e/Bohr^3, integrating to minus the excess electrons) into the directorypath.style='z'— the default — writes one<prop>.txtper quantity, averaged over \(x\) and \(y\) as a function of \(z\), whilestyle='cube'writes<prop>.cubeon the full 3-D grid.propspicks which of the three quantities to write. This one needs a calculation to have been run; calling it earlier raisesRuntimeError. It is collective: call it on all ranks.Note that a
'z'trace from the legacygpaw.solvation.sjm.SJMcalculator is shifted by one row relative to these: it writes no point at \(z\) = 0, so its first row is the point at one grid spacing and its row \(i\) is row \(i\) + 1 here. Line the two up on the \(z\) column rather than on the row index.Note also that
background_chargeis a charge density in e/Bohr^3 integrating to minus the excess electrons — not the 0/1 jellium mask that the legacygpaw.solvation.sjm.SJMcalculator writes under the same name. Scripts carried over from the legacy calculator have to be adjusted.
So a run that reports the potential and writes both kinds of trace looks like:
sjm = SJM(solvation=..., potentiostat={'target_potential': 4.4})
atoms.calc = GPAW(..., extensions=[sjm])
atoms.get_potential_energy() # both need a converged calculation
print(sjm.electrode_potential, sjm.excess_electrons)
sjm.write_sjm_traces() # sjm_traces/{potential,cavity,background_charge}.txt
sjm.write_sjm_traces(path='traces-3d', style='cube') # traces-3d/*.cube
The write_sjm_traces() calls are collective: run them on all ranks, as
you would any other calculator method.
After reading a .gpw file, the SJM object is
calc.params.extensions[0] again. The running parts of the calculation
are calc.dft.potentiostat and calc.dft.solvation.
References
G. Kastlunger, P. Lindgren, A. A. Peterson, Controlled-Potential Simulation of Elementary Electrochemical Reactions: Proton Discharge on Metal Surfaces, J. Phys. Chem. C 122 (24), 12771 (2018).
A. Held and M. Walter, Simplified continuum solvent model with a smooth cavity based on volumetric data, J. Chem. Phys. 141, 174108 (2014).
Marko M. Melander, Tongwei Wu, Timo Weckman, Karoliina Honkala, Constant inner potential DFT for modelling electrochemical systems under constant potential and bias, npj Computational Materials 10, 5 (2024).
Class documentation
- class gpaw.extensions.electrochemistry.SJM(potentiostat=None, solvation=None)[source]
Solvated jellium method.
Electronically grand-canonical calculations, typically for simulating electrochemical interfaces. A jellium counter charge is placed in the implicit solvent above the slab; the number of excess electrons can either be fixed (constant-charge mode) or adjusted until the electrode potential matches
target_potential(constant-potential mode).An SJM object, and the objects given to it, belong to one calculator: each calculation keeps its state in them. So give every calculator its own – every image of a NEB, for instance.
The two parameters can also be given by position, potentiostat first:
SJM({'target_potential': 4.2})sets only the potentiostat.- Parameters:
potentiostat (Potentiostat | dict | None) – The potential control, held as
sjm.potentiostat: aPotentiostat(or a subclass of it), or a dict of the keys under Other Parameters.None(the default) gives a constant-charge calculation with no excess electrons.solvation (Solvation | dict | None) – The solvation model, held as
sjm.solvation: agpaw.solvation.Solvation(or a subclass of it), or a dict of its keyword arguments (cavity,dielectric,interactionsanddipolelayer).None(the default) gives water as ingpaw.solvation.get_HW14_water_kwargs(), with its effective potential made anSJMPower12Potential, which keeps the solvent from behind the electrode (in PW mode ramping it to vacuum below the cell top). Without a dipole layer it getsGaussianDerivativeDipole(zero_vacuum=True), which puts the electrostatic potential to zero in the vacuum at the top of the cell. The electrode potential is read off that vacuum level, so a layer of your own works with eitherzero_vacuum.target_potential – Electrode potential to equilibrate to, in V on the vacuum scale (expressed as a work function).
None(the default) gives a constant-charge calculation based onexcess_electrons.excess_electrons – Number of excess electrons in the atomic system, and (with opposite sign) in the jellium region. Used as the initial guess in constant-potential mode.
jelliumregion – Shape of the counter-charge region, as a dict. The default is a slab (
SlabRegion), taking the keys'top','bottom','thickness'and'fix_bottom'. A'shape'key selects a different kind of region; seebuild_jellium_region().tol – Tolerance for the deviation of the target potential, in V. Default: 0.005 V.
max_iters – Limits of the equilibration; see
PotentialOptimizer. Defaults: 10, 2 V and 10.max_potential_stepsize – Limits of the equilibration; see
PotentialOptimizer. Defaults: 10, 2 V and 10.max_reruns – Limits of the equilibration; see
PotentialOptimizer. Defaults: 10, 2 V and 10.grand_output – Write the grand-potential energy (instead of the canonical energy) into the results dictionary handed to ASE, and thereby into trajectory files. Default: True.
always_adjust – Take one more step in the number of excess electrons even when the potential is already within
tol. The step is not re-converged – it is applied to the next geometry – so it costs no extra SCF cycles. Together with a loosetolthis lets a relaxation optimize the structure and the potential simultaneously. Withouttarget_potentialit does nothing, and warns. Default: False.slope – Initial guess of d(potential)/d(excess electrons), in V/electron; slopes regressed later are mixed into it by
mixer.None, or a value that is not negative, gives the slope of a 10 muF/cm^2 plate capacitor of the cell’s xy area.mixer – Damping of the slope estimate, because regressing a slope can be noisy:
new = mixer * old + (1 - mixer) * regressed. Set to 0 for no damping. Default: 0.2.slope_regression_depth – Number of previous attempts that the slope is regressed over. Default: 4.
charging – Parts of your own, in place of the default
JelliumCharging,DirectOptimizerandWorkFunctionProbe. The keys that configure a default part –excess_electronsandjelliumregion;target_potential,tol,slope,mixer,slope_regression_depth,max_potential_stepsize,max_itersandmax_reruns– cannot go together with one of your own: give those settings to your part instead.optimizer – Parts of your own, in place of the default
JelliumCharging,DirectOptimizerandWorkFunctionProbe. The keys that configure a default part –excess_electronsandjelliumregion;target_potential,tol,slope,mixer,slope_regression_depth,max_potential_stepsize,max_itersandmax_reruns– cannot go together with one of your own: give those settings to your part instead.potentialprobe – Parts of your own, in place of the default
JelliumCharging,DirectOptimizerandWorkFunctionProbe. The keys that configure a default part –excess_electronsandjelliumregion;target_potential,tol,slope,mixer,slope_regression_depth,max_potential_stepsize,max_itersandmax_reruns– cannot go together with one of your own: give those settings to your part instead.
- change(potentiostat)[source]
Change potentiostat settings, before or after a calculation.
Takes the keys of the
potentiostatdict ofSJM, with the same meaning – all but the parts, which are fixed when the SJM object is created. After a calculation the settings reach it right away, and the density and the wave functions are kept, so the nextget_potential_energy()continues the SCF loop from the current solution instead of starting over. So keep the SJM object in a variable and change the settings through it:sjm = SJM(...) atoms.calc = GPAW(..., extensions=[sjm]) atoms.get_potential_energy() sjm.change(potentiostat={'target_potential': 4.3}) atoms.get_potential_energy()
A new target drops a step staged by
always_adjust. After a converged calculation, and with a negative slope estimate, it also steps the excess electrons toward the new target, unlessexcess_electronsis given. A newslopeor jellium region makes the optimizer forget its attempts.The live values are read off the potentiostat and its parts:
sjm.excess_electrons,sjm.potentiostat.optimizer.target_potential, … Setting them there directly skips what this does on top: clearing the results and recomputing the occupations, density and potential, which makes the nextget_potential_energy()run the SCF loop again.Raises
ValueErrorfor an unknown key, or formixerandslope_regression_depthon an optimizer without them, andRuntimeErrorfor a jellium region on a built calculation that has not run yet.
- property electrode_potential: float
Electrode potential of the last converged SCF loop, in V.
As read by the potential probe; for the default
WorkFunctionProbeit is the work function at the top of the cell. The same ascalc.results['electrode_potential']; NaN until an SCF loop has converged.
- write_sjm_traces(path='sjm_traces', style='z', props=('potential', 'cavity', 'background_charge'))[source]
Write traces of the quantities in \(props\) to disk.
The electrostatic potential (
'potential'), the solvent cavity ('cavity') and the jellium counter charge ('background_charge') of the calculation are written into the directory \(path\), one file per quantity:<prop>.txtforstyle='z'(the default), averaged over x and y as a function of z, and<prop>.cubeon the full 3-D grid forstyle='cube':atoms.get_potential_energy() sjm.write_sjm_traces() # sjm_traces/*.txt sjm.write_sjm_traces(path='traces-3d', style='cube')
Note that
'potential'is the electrostatic potential referenced to the Fermi level, in eV, and that'background_charge'is the jellium counter-charge density in e/Bohr^3 – it integrates to minus the number of excess electrons.A
'z'trace has one row per point of the full mesh, so fd and plane-wave traces of the same cell line up row by row (see_write_trace_in_z()).This needs a calculation to have been run, and raises
RuntimeErrorbefore. It is collective: call it on all ranks.
- class gpaw.extensions.electrochemistry.Potentiostat(*, charging=None, optimizer=None, potentialprobe=None, always_adjust=False, grand_output=True)[source]
Holds a target electrode potential by adjusting an excess charge.
It is the GPAW extension of the potential control: it puts the charge into the density, moves it with the atoms and equilibrates after each SCF loop.
Composes three pluggable parts:
charging– aChargingScheme: how the excess charge is put into the cell (default:JelliumCharging, a jellium slab).optimizer– aPotentialOptimizer: the target potential and how the charge is stepped toward it (default:DirectOptimizer).target_potential=Nonegives constant charge; the optimizer is kept, so a mode switch keeps its settings and slope.potentialprobe– aPotentialProbe: how the potential is read off the converged SCF state (default:WorkFunctionProbe).
The potentiostat runs the equilibration and holds its state; the optimizer holds the settings that steer and limit it.
from_dict()builds one from thepotentiostatdict ofgpaw.extensions.electrochemistry.SJM.- Parameters:
charging (ChargingScheme | None) – The charging scheme.
optimizer (PotentialOptimizer | None) – The potential optimizer.
potentialprobe (PotentialProbe | None) – The potential probe.
always_adjust (bool) – Once the potential is converged, stage one more step in the charge anyway, to be applied to the next geometry by
new_geometry()instead of being re-converged. Default: False.grand_output (bool) – Report the grand-potential energy rather than the canonical energy in the results (see
write_results()). Default: True.
- equilibrate(ibzwfs, potential, nelectrons, occ_calc, mixer, log)[source]
One equilibration attempt, after the SCF criteria have passed.
potentialis what the probe read offibzwfs. ReturnsEquilibrationResult.convergedwhen the potential is within tolerance (or there is no target),steppedafter stepping the charge and re-running the occupations for another SCF pass, andrejectedafter halving a step that overshotmax_potential_stepsize.
- classmethod from_dict(dct)[source]
Build a potentiostat from SJM’s
potentiostatdict.Besides the settings, the dict takes the parts, as instances or as dicts written by
todict(), and the keywords of the default parts (seedefault_parts). Those keys configure the default class, so they cannot go together with an instance of a part.
- new_geometry()[source]
Start equilibrating a new geometry.
Applies excess electrons staged by
always_adjustand returns them, orNoneif there were none. The attempts are forgotten – the optimizer’s too, since a regression across the move would fit a line through two different systems – but the slope estimate is carried over.
- post_converged(dft)[source]
Finish a converged calculation.
Reads the electrode potential and the Fermi level off the converged state, reports the equilibration, Legendre-transforms the energies to the grand potential and writes the results (see
write_results()). The next calculation – the next step of a relaxation, say – then gets a fresh equilibration budget and a fresh record to report.
- class gpaw.extensions.electrochemistry.ChargingScheme[source]
Puts an excess charge into the cell.
It also reports the geometry of the electrode “plate” that the charge faces, which the potential optimizer needs for its first-guess slope.
- initialize(grid, pw, relpos_ac, *, cavity)[source]
Set the charge up for a new calculation.
gridis the fine grid,pwthe descriptor of the interpolated density andcavitythe solvation cavity. Returns the lower and upper limit of the charged region in Å, for the log.
- class gpaw.extensions.electrochemistry.JelliumCharging(*, excess_electrons=0.0, jelliumregion=None)[source]
A uniform jellium counter-charge filling a masked region.
The excess electrons of the atomic system are balanced by a jellium of the opposite sign, uniform over the region: a
SlabRegionby default, or anyJelliumRegion.initialize()puts the region on the grid of a calculation. The mask itself – normalizing it and putting the charge into the density – is handled bygpaw.extensions.jellium.JelliumExtension.
- class gpaw.extensions.electrochemistry.PotentialOptimizer[source]
Proposes the next excess-electron count for the target potential.
Its settings are class attributes, so that an optimizer of your own has them too;
Potentiostatreads them whatever the optimizer:- target_potential:
Electrode potential to equilibrate to, in V on the vacuum scale.
Nonegives a constant-charge calculation, which holds the charge where it is.- tol:
How close to the target the potential is converged, in V; see
converged(). Default: 0.005 V.- max_potential_stepsize:
A step that moves the potential by more than this many volts and ends further from the target is rejected: the step in excess electrons is halved and the SCF re-run, and the point neither counts as an attempt nor feeds the slope (see
EquilibrationResult.rejected). This keeps a bad slope from throwing the charge out of the linear region.Noneturns it off. Default: 2 V.- max_iters:
Maximum number of attempts to equilibrate the potential for one geometry before a
PotentialConvergenceErroris raised. Default: 10.- max_reruns:
How many times in a row a step may be rejected and halved before a
PotentialConvergenceErroris raised. Default: 10.
- converged(potential)[source]
Is the potential close enough to the target to stop?
By default, within
tolof it.tolis also what the log and the error messages quote, so keep it meaningful if you override this with a different criterion.
- last_attempt()[source]
The most recent (excess electrons, potential) attempt, if kept.
Nonefrom a method that records no attempts, which leaves the step clamp inPotentiostat.equilibrate()nothing to compare against, so it never rejects.
- next_excess_electrons(excess_electrons, potential, *, area)[source]
Number of excess electrons the method points at next.
The attempt must have been handed to
record_attempt()first; this only proposes the step and records nothing.
- record_attempt(excess_electrons, potential, *, area)[source]
Learn from an attempt, whether or not a step follows it.
- class gpaw.extensions.electrochemistry.DirectOptimizer(*, target_potential=None, slope=None, mixer=0.2, slope_regression_depth=4, tol=0.005, max_potential_stepsize=2, max_iters=10, max_reruns=10)[source]
Step the charge along a damped estimate of d(potential)/d(charge).
slope(V/electron) is the initial guess.None, or an estimate that is not negative, gives the slope of a 10 muF/cm^2 plate capacitor of the electrodearea. Once the lastslope_regression_depth(default 4, at least 2) attempts hold two distinct charges, every attempt updates the estimate, damped bymixer(default 0.2):new = mixer * old + (1 - mixer) * regressed.
- class gpaw.extensions.electrochemistry.PotentialProbe[source]
Reads the electrode potential off the converged SCF state.
- class gpaw.extensions.electrochemistry.WorkFunctionProbe[source]
Electrode potential as the work function: the vacuum level at the top of the cell minus the Fermi level.
- class gpaw.solvation.sjm.SJMPower12Potential(atomic_radii=None, u0=0.18, pbc_cutoff=1e-06, tiny=1e-10, H2O_layer=False, unsolv_backside=True, communicator=None)[source]
Inverse power-law potential. Inverse power law potential for SJM, inherited from the Power12Potential of gpaw.solvation. This is a 1/r^{12} repulsive potential taking the value u0 at the atomic radius. In SJM one also has the option of removing the solvent from the electrode backside and adding ghost plane/atoms to remove the solvent from the electrode-water interface.
Parameters:
- atomic_radii: function
Callable mapping an ase.Atoms object to an iterable of atomic radii in Angstroms. If not provided, defaults to van der Waals radii.
- u0: float
Strength of the potential at the atomic radius in eV. Defaults to 0.18 eV, the best-fit value for water from Held & Walter.
- pbc_cutoff: float
Cutoff in eV for including neighbor cells in a calculation with periodic boundary conditions.
- H2O_layer: dict
Dictionary to control the non-local part of solvation, i.e. (exclusion of solvent from the electrode-water interface). It has 4 keys:
- style: ‘ghost_atoms’ or ‘plane’
‘ghost_atoms’: Add ghost atoms below the water layer to exclude implicit solvent from the interface region. ‘plane’: Use a plane instead of ghost atoms for freeing the surface.
- nox: ‘all’ (default) or int
‘all’: Free the interface only between the lowest lying O and the electrode. int: Explicitly mention under which water molecule counter from the top the interface is cleaned from implicit solvent.
- ghosts_below_ox: bool
Only relevant if style is ‘ghost_atoms’. Add extra ghost atoms below the oxygen atoms of the water layer. [default: True]
- ghost_spacing: float
Only relevant if style is ‘ghost_atoms’. Spacing between ghost atoms in Angstroms. [default: 2/3 Bohr]. Note that the default is overly dense and leads to longer waiting times between SCF cycles. A spacing of 1.5 Bohr is likely sufficient.
- unsolv_backside: bool or (float, float)
Exclude implicit solvent from the region under the electrode. In z-periodic calculations (PW mode), the solvent is ramped smoothly to vacuum, as 0.5 * erfc((z - (L - depth)) / width), defaulting to (depth, width) = (1.0, 0.25) Angstroms; alternatively supply (depth, width).
The legacy calculator—SJM(sj={...}) from
gpaw.solvation.sjm—is still available, and is what the CIP-DFT
section above uses:
- class gpaw.solvation.sjm.SJM(*args, legacy_gpaw=True, **kwargs)[source]
The legacy SJM calculator (an
OldSJM).New GPAW uses
gpaw.extensions.electrochemistry.SJMinstead.