SoftMatterCalculator¶

Included in QATK.Calculators.ForceField

class SoftMatterCalculator(potential_builder, assign_atom_types=None, use_lennard_jones_pme=None, separate_nonbonding=None, use_configuration_charges=None, stress_type=None, gpu_precision=None)¶

Constructor for the SoftMatterCalculator.

Parameters:

potential_builder (PotentialBuilder based) – The potential builder used to define the potential
assign_atom_types (bool) – Whether to automatically assign atom types based on the forcefield.
Default: False
use_lennard_jones_pme (bool) – Use the particle mesh Ewald (PME) method to sum Lennard-Jones potentials. This is only supported for potentials that use Lorentz-Berthelot or Geometric combination rules.
Default: False
separate_nonbonding (bool) – Calculate and report electrostatic and Lennard-Jones potentials separately. This option is for potentials that use Lorentz-Berthelot combination rules, and cannot be combined with Lennard-Jones particle mesh Ewald.
Default: False
use_configuration_charges (bool) – Whether to use atomic partial charges from the configuration to model the electrostatic interactions. False will use the partial charges defined by the potential.
Default: False
stress_type (Isotropic | DiagonalOnly | Anisotropic) – The type of pressure to calculate when stress is requested. Isotropic calculates a single value for the stress tensor. DiagonalOnly calculates just the diagonal components of the stress tensor. Anisotropic calculates the full stress tensor.
Default: DiagonalOnly
gpu_precision (SinglePrecision | DoublePrecision | MixedPrecision) – Set the precision of the calculator when using the GPU. The flags SinglePrecision and DoublePrecision do all calculations at single and double precision respectively. Single precision is faster at the cost of accuracy. The flag MixedPrecisions selects doomg force calculations in single precision but dynamics integration in double precision. This gives better dynamics energy conservation at a small performance cost.
Default: MixedPrecision

assignAtomTypes()¶

Returns:: Whether the calculator automatically assigns atom types.
Return type:: bool

dynamicalMatrixParameters()¶

This method is deprecated.

Returns:: None always.
Return type:: None

gpuPrecision()¶

Returns:: The precision used for calculations run on a GPU.
Return type:: SinglePrecision | DoublePrecision | MixedPrecision

metatext()¶

Returns:: The metatext of the object or None if no metatext is present.
Return type:: str | None

nlinfo()¶

Get information about the calculator.

Returns:: A dictionary containing information about the calculator.
Return type:: dict

separateNonbonding()¶

Returns:: Whether electrostatic and Lennard-Jones potentials are calculated separately.
Return type:: bool

setMetatext(metatext)¶

Set a given metatext string on the object.

Parameters:: metatext (str | None) – The metatext string to set. Use “None” to remove current metatext.

stressType()¶

Returns:: The type of pressure and stress calculated by the calculator.
Return type:: Isotropic | DiagonalOnly | Anisotropic

uniqueString()¶: Return a unique string representing the state of the object.

upgrade(configuration)¶

Set up the calculator for the given configuration.

Parameters:: configuration (MoleculeConfiguration | BulkConfiguration) – The configuration to set the calculator up for.

useConfigurationCharges()¶

Returns:: Whether configuration charges are used for electrostatic interactions.
Return type:: bool

useLennardJonesPME()¶

Returns:: Whether the calculator uses PME for Lennard-Jones interactions.
Return type:: bool

Usage Examples¶

Calculate the total energy of a box of methanol molecules

calculator = SoftMatterCalculator(builder)
configuration.setCalculator(calculator)

energy = TotalEnergy(configuration)
print(f"The total energy of the configuration is {energy.evaluate()}")

methanol_box.hdf5 soft_matter_calculator_example.py

Perform a NVE molecular dynamics simulation on an equilibrated configuration of amorphous polypropylene.

# Create the soft matter calculator
builder = OPLSPotentialBuilder()
calculator = SoftMatterCalculator(builder)
configuration.setCalculator(calculator)

# Create simulation
method = NVEDynamics(initial_velocity=ConfigurationVelocities())
simulation = SoftMatterDynamicsSimulation(configuration, method)
simulation.setLogging(1000)
simulation.setTrajectory(10000, "pp_trajectory.hdf5")

# Run the simulation
simulation.simulate(100000)

equilibrated_pp.hdf5 soft_matter_dynamics_example.py

Notes¶

The SoftMatterCalculator implements an empirical forcefield that is suited to calculations of organic soft matter, such as polymers or chemicals in solvents. In comparison to the TremoloXCalculator it is optimized specifically for these types of systems at the cost of losing generality to many-body types of potentials such as Stillinger-Weber that are used in inorganic materials. The SoftMatterCalculator is also highly optimized for GPUs, making larger and longer simulations feasible.

To create a SoftMatterCalculator a potential builder, such as the OPLSPotentialBuilder or DreidingPotentialBuilder is required. This potential builder determines the type of forcefield implemented in the calculator. It also contains some quality settings, such as nonbonded cutoff distances. The potential builders also allow adding new atom types and potentials which are then included in the calculator. Once the calculator is created it is attached to the configuration as with other calculators. The SoftMatterCalculator supports the +calculation of energy, force and stress, and it is optimized to performing dynamics simulations with the SoftMatterDynamicsSimulation object. On the contrary, it is not recommended to use the:class:~.SoftMatterCalculator with the MolecularDynamics() function.

In addition to the potential builder, a number of optional arguments can be given to set some properties of the calculator. The option assign_atom_types uses the potential builder auto-typing to add appropriate, force-field-specific atom types to the configuration when a calculation is performed. If this option is not set and the configuration does not have suitable types assigned, an error will be raised. For periodic systems Particle-Mesh Ewald (PME) can be used to augment the dispersion potential with long-range contributions, using the argument use_lennard_jones_pme. This is a more accurate way of summing the dispersion potential that lowers the truncation error in using a specific cutoff. If enabled, the accuracy of the summation is taken from the electrostatic accuracy set in the potential builder. By default the charges defined by the given forcefield are used for calculating the electrostatic potential. Alternatively, the charges can also be set by enabling the use_configuration_charges option. Setting this to True results in the electrostatic potential being evaluated using the charges set on the configuration. When using the DreidingPotentialBuilder, UFFPotentialBuilder, or OPLSMinPotentialBuilder charges from the configuration should be used as these forcefields do not have standard atomic charges. A simple way to set charges is to use the QEq method implemented in the QEqAtomicCharges object. Charges based on DFT can also be assigned use the RepeatESPPartialCharges analysis object.

The type of stress calculated is controlled with the option stress_type. This only effects stress calculations done with the Stress analysis object. The type of stress calculated in dynamics is controlled through other settings. It should be noted that in the SoftMatterCalculator stress is calculated through numerical derivatives in each direction. By default only the diagonal components of the stress tensor are calculated.

Finally the precision used in GPU calculations is set with the gpu_precision option. Single precision is generally faster, but has increased problems with numerical accuracy. By default forces are calculated in single precision while dynamics are calculated in double precision. This tries to find an optimal balance between speed and accuracy. All single or all double precision can be requested with the SinglePrecision and DoublePrecision flags respectively.

Calculations can be run on GPU by enabling QuantumATK GPU acceleration. The default way to activate GPU acceleration is by checking the “Enable proprietary GPU acceleration” option in the Job Manager or by using the atkpython_gpu command instead of atkpython, as described in the technical notes. Depending on the drivers available on your computing environment, the GPU driver compatibility mode may need to be selected. This option enables the code to run on computers with GPU drivers compatible with CUDA development kits 12.2 to 12.8. The SoftMatterCalculator is also capable of using multiple GPUs on the same node, if available. The calculator does not support MPI, and therefore cannot use GPUs across different nodes.