stormm::energy::LayeredPotentialMetrics Class Reference

Collect the details needed to formulate a layered potential, including the length of each layer's cutoff (for direct particle-particle interactions), expected size of the unit cell (if applicable), mixing rule or Coulomb's constant, and the primary exponential coefficients for fitting successive smoothing functions. More...

#include <layered_potential_metrics.h>

Public Member Functions
	LayeredPotentialMetrics (DecomposablePotential form_in=DecomposablePotential::ELECTROSTATIC, BoundaryCondition boundaries_in=BoundaryCondition::ISOLATED, double coulomb_in=amber_ancient_bioq, VdwCombiningRule mixing_rule_in=VdwCombiningRule::GEOMETRIC, const std::vector< double > &exponent_c_in={ 1.0, 1.5, 2.0 }, double particle_particle_cutoff=5.0, double range_multiplier_in=2.0, double range_limit_in=1000.0, double vdw_transition_midpoint_in=hail_default_vdw_xtn_midpoint, double vdw_transition_intensity_in=hail_default_vdw_xtn_intensity, double ewald_coefficient_in=hail_default_ewald_coefficient, const std::vector< double > &box_vectors_in={ 50.0, 0.0, 0.0, 0.0, 50.0, 0.0, 0.0, 0.0, 50.0 })
	The constructor takes input for all member variables, but various modifier functions can set them one at a time for clarity.
DecomposablePotential	getForm () const
	Get the requested potential form.
BoundaryCondition	getBoundaryCondition () const
	Get the expected boundary conditions.
int	getLayerCount () const
	Get the number of layers by which the potential is split.
double	getCutoff (int layer_index) const
	Get the cutoff value for one of the layers. The cutoff for one layer is the handoff point for the next layer up.
double	getCoulombConstant () const
	Get the value of Coulomb's constant to use in preparing potentials. This will raise an exception if the form of the potential is not electrostatic.
VdwCombiningRule	getMixingRule () const
	Get the mixing rule applicable to dispersion interactions. Specific Lennard-Jones parameters are not needed at this stage–they will play a role when constructing the LayeredPotential object based on the parameters in this preparatory class.
double	getExponentFactor (int factor_index, int layer_index=1) const
	Get one of the three baseline exponential coefficients. The strategy with Layered Interpolation in Real Space is to split the potential at a given range Rh using a softening function of the form:
double	getRangeCompounding () const
	Get the general scaling factor for the handoff points between successive layers. Two is a natural choice, doubling the effective range of the potential in each layer, but intermediate values such as 1.5 are also possible. This, the particle-particle interaction cutoff, and the stencil size (which is set for the simulation, outside of the LayeredPotential) are the primary tunable parameters determining the accuracy of the approximation. The exponential factors are more minor parameters, in the sense that they can make the approximation worse but there are generally "best" settings given the choice of the particle-particle cutoff.
double	getMaximumRange () const
	Get the maximum range for calculated interactions, applicable to systems with isolated boundary conditions.
double	getVdwTransitionMidpoint () const
	Get the dispersion interaction switching midpoint, at which point whatever applicable interaction is mixed 50:50 with the interaction expected for a geometric combining rule.
double	getVdwTransitionIntensity () const
	Get the intensity with which the dispersion interaction switches between its native form and the interaction expected for a geometric combining rule. The switching function turns off the native potential by S(r) = 1 / (exp(p (r - r0)) + 1), where p is the intensity returned by this function and r0 is the midpoint returned by getVdwTransitionMidpoint() above.
double	getEwaldCoefficient () const
	Get the Ewald coefficient for decomposition of a PME direct space interaction.
const std::vector< double > &	getUnitCellVectors () const
	Get the rough unit cell dimensions, expressed as a 3 x 3 matrix whose columns are the Cartesian X, Y, and Z coordinates of each unit cell vector (it is identical to the inverse transformation matrix for taking fractional coordinates into real space).
void	setForm (DecomposablePotential form_in)
	Set the form of the potential that will be expressed.
void	setBoundaryCondition (BoundaryCondition boundary_in)
	Set the boundary conditions to use.
void	setCutoff (double cutoff_in)
	Set the cutoff for particle-particle interactions.
void	setCoulombConstant (double coulomb_in)
	Set the value of Coulomb's constant.
void	setMixingRule (VdwCombiningRule mixing_rule_in)
	Set the mixing rule to apply to Lennard-Jones parameter pairs. This will determine the forms of particle-particle interactions and the first grid layer potential.
void	setRangeCompounding (double range_multiplier_in)
	Set the range compounding factor.
void	setMaximumRange (double range_limit_in)
	Set the maximum range for the layered potential cutoffs. This will provide an upper bound on the interactions in the case of isolated boundary conditions.
void	setVdwTransitionMidpoint (double midpoint_in)
	Set the dispersion interaction switching midpoint, at which point whatever applicable interaction is mixed 50:50 with the interaction expected for a geometric combining rule.
void	setVdwTransitionIntensity (double intensity_in)
	Set the intensity with which the dispersion interaction switches between its native form and the interaction expected for a geometric combining rule. See the associated accessor for details of the transition functional form..
void	setEwaldCoefficient (double ewald_coefficient_in)
	Set the Ewald coefficient for decomposition of a PME direct space interaction.
void	setUnitCellVectors (const std::vector< double > &box_vectors_in)
	Set the unit cell vectors. This will provide an upper bound on the interactions in the case of periodic boundary conditions.
	LayeredPotentialMetrics (const LayeredPotentialMetrics &original)=default
	Using Standard Template Library objects for anything that is not a scalar value, and with no const members, the default copy and move constructors as well as copy and move assignment operators apply.
	LayeredPotentialMetrics (LayeredPotentialMetrics &&original)=default
LayeredPotentialMetrics &	operator= (const LayeredPotentialMetrics &other)=default
LayeredPotentialMetrics &	operator= (LayeredPotentialMetrics &&other)=default
void	setExponentFactor (int factor_index, double exp_c_in)
	Set one of the baseline exponential factors. These apply to the first smoothed potential, the first layer involving a mesh after the particle-particle interactions. Subsequent layers' exponential factors are scaled with each cutoff.
void	setExponentFactor (const std::vector< double > &exp_c_in)
void	setExponentFactor (const double3 exp_c_in)

Detailed Description

Collect the details needed to formulate a layered potential, including the length of each layer's cutoff (for direct particle-particle interactions), expected size of the unit cell (if applicable), mixing rule or Coulomb's constant, and the primary exponential coefficients for fitting successive smoothing functions.

Constructor & Destructor Documentation

LayeredPotentialMetrics()

stormm::energy::LayeredPotentialMetrics::LayeredPotentialMetrics	(	DecomposablePotential	form_in = DecomposablePotential::ELECTROSTATIC,
		BoundaryCondition	boundaries_in = BoundaryCondition::ISOLATED,
		double	coulomb_in = amber_ancient_bioq,
		VdwCombiningRule	mixing_rule_in = VdwCombiningRule::GEOMETRIC,
		const std::vector< double > &	exponent_c_in = { 1.0, 1.5, 2.0 },
		double	particle_particle_cutoff = 5.0,
		double	range_multiplier_in = 2.0,
		double	range_limit_in = 1000.0,
		double	vdw_transition_midpoint_in = hail_default_vdw_xtn_midpoint,
		double	vdw_transition_intensity_in = hail_default_vdw_xtn_intensity,
		double	ewald_coefficient_in = hail_default_ewald_coefficient,
		const std::vector< double > &	box_vectors_in = { 50.0, 0.0, 0.0, 0.0, 50.0, 0.0, 0.0, 0.0, 50.0 } )

The constructor takes input for all member variables, but various modifier functions can set them one at a time for clarity.

Parameters

particle_particle_cutoff

The cutoff that will be applied to interactions at the lowest level of the potential, where there is no mesh and all calculations are done with pairwise calculations between particles

Member Function Documentation

getCutoff()

double stormm::energy::LayeredPotentialMetrics::getCutoff

(

int

layer_index

)

const

Get the cutoff value for one of the layers. The cutoff for one layer is the handoff point for the next layer up.

Parameters

layer_index

Index of the layer of interest

getExponentFactor()

double stormm::energy::LayeredPotentialMetrics::getExponentFactor	(	int	factor_index,
		int	layer_index = 1 ) const

Get one of the three baseline exponential coefficients. The strategy with Layered Interpolation in Real Space is to split the potential at a given range Rh using a softening function of the form:

U(r) = A exp(c1 * (r - Rh)) + B exp(c2 * (r - Rh)) + C exp(c3 * (r - Rh)) + D

Here, Rh is the "handoff" distance and is equal to the cutoff of the next lower layer of the interaction, the lowest layer having the shortest cutoff and all interactions being direct particle-particle pairs. Potentials at all levels go to zero exactly, with zero derivative, second derivative, and third derivative, at their own cutoff range which coincides with handoff point Rh for the next layer. The exponential coefficients c1, c2, and c3 are parameters of the model which tune the rate at which the smoothing potential moderates the original form. {1.0, 1.5, 2.0} or {1.25, 1.75, 2.25} are good choices for the electrostatic function and a handoff point of about 5.0 Angstroms.

At successive layers of the potential, the exponential scaling factors are scaled down as a proportion of the handoff point. This does more than merely allow a single set of coefficients to control the entire series. It also helps maintain a consistent stencil for mapping the finite potentials to meshes at a given level of accuracy.

Parameters

factor_index	Specify the index for c1, c2, or c3. Values outside [0, 2] raise exceptions.
layer_index	The layer of interest. The lowet layer (index 0) is for direct particle-particle interactions and has no exponential series. Requesting such parameters will return 0.0.

setBoundaryCondition()

void stormm::energy::LayeredPotentialMetrics::setBoundaryCondition

(

BoundaryCondition

boundary_in

)

Set the boundary conditions to use.

Parameters

boundary_in

setCoulombConstant()

void stormm::energy::LayeredPotentialMetrics::setCoulombConstant

(

double

coulomb_in

)

Set the value of Coulomb's constant.

Parameters

coulomb_in

The chosen value

setCutoff()

void stormm::energy::LayeredPotentialMetrics::setCutoff

(

double

cutoff_in

)

Set the cutoff for particle-particle interactions.

Parameters

cutoff_in

The chosen cutoff

setEwaldCoefficient()

void stormm::energy::LayeredPotentialMetrics::setEwaldCoefficient

(

double

ewald_coefficient_in

)

Set the Ewald coefficient for decomposition of a PME direct space interaction.

Parameters

ewald_coefficient_in

The chose Ewald coefficient, equal to 1/(2g) where g is the width of the Gaussian density smoothing form in the Ewald approximation

setExponentFactor()

void stormm::energy::LayeredPotentialMetrics::setExponentFactor	(	int	factor_index,
		double	exp_c_in )

Set one of the baseline exponential factors. These apply to the first smoothed potential, the first layer involving a mesh after the particle-particle interactions. Subsequent layers' exponential factors are scaled with each cutoff.

Overloaded:

• Provide exponent factors one at a time, with term indices in each case
• Provide three exponent factors as a standard Template Library vector
• Provide three exponent factors as a double-precision tuple

Parameters

factor_index	Specify the index for c1, c2, or c3. Values outside [0, 2] raise exceptions.
exp_c_in	The exponential multiplier

setForm()

void stormm::energy::LayeredPotentialMetrics::setForm

(

DecomposablePotential

form_in

)

Set the form of the potential that will be expressed.

Parameters

form_in

The potential to subdivide into layers

setMaximumRange()

void stormm::energy::LayeredPotentialMetrics::setMaximumRange

(

double

range_limit_in

)

Set the maximum range for the layered potential cutoffs. This will provide an upper bound on the interactions in the case of isolated boundary conditions.

Parameters

range_limit_in

The maximum range for interactions by any of the smoothed potentials

setMixingRule()

void stormm::energy::LayeredPotentialMetrics::setMixingRule

(

VdwCombiningRule

mixing_rule_in

)

Set the mixing rule to apply to Lennard-Jones parameter pairs. This will determine the forms of particle-particle interactions and the first grid layer potential.

Parameters

mixing_rule_in

The Lennard-Jones combination rule to apply

setRangeCompounding()

void stormm::energy::LayeredPotentialMetrics::setRangeCompounding

(

double

range_multiplier_in

)

Set the range compounding factor.

Parameters

range_multiplier_in

The compounding factor determining how much the cutoff increases from one layer of the approximation to the next

setUnitCellVectors()

void stormm::energy::LayeredPotentialMetrics::setUnitCellVectors

(

const std::vector< double > &

box_vectors_in

)

Set the unit cell vectors. This will provide an upper bound on the interactions in the case of periodic boundary conditions.

Parameters

box_vectors_in

The inverse transformation matrix taking particles from unit cell fractional space back to real space

setVdwTransitionIntensity()

void stormm::energy::LayeredPotentialMetrics::setVdwTransitionIntensity

(

double

intensity_in

)

Set the intensity with which the dispersion interaction switches between its native form and the interaction expected for a geometric combining rule. See the associated accessor for details of the transition functional form..

Parameters

intensity_in

The transition intensity to set

setVdwTransitionMidpoint()

void stormm::energy::LayeredPotentialMetrics::setVdwTransitionMidpoint

(

double

midpoint_in

)

Set the dispersion interaction switching midpoint, at which point whatever applicable interaction is mixed 50:50 with the interaction expected for a geometric combining rule.

Parameters

midpoint_in

The transition midpoint to set

---

The documentation for this class was generated from the following files:

• src/Potential/layered_potential_metrics.h
• src/Potential/layered_potential_metrics.cpp