HMA

Documentation/source/guides/hma.rst

@@ -0,0 +1,42 @@
+.. highlight:: none
+
+.. _ch:hma:
+
+Harmonically Mapped Averaging (HMA)
+===================================
+
+.. _sec:hma:
+
+Background
+----------
+
+Harmonically mapped averaging (HMA) is a technique that improves the precision
+of measured themodynamic properites of crystalline systems.  Beyond precision,
+other benefits include smaller potential-truncation effects, finite-size
+effects, faster equilibration and shorter decorrelation time.
+
+Limitations
+-----------
+
+HMA can only be used in the NVT ensemble and when the atoms only vibrate around
+their lattice sites (without diffusing).  HMA can be used in Cassandra with any
+pair potential, but not with Ewald summation.
+
+Truncation
+----------
+
+In order to supress property fluctuations due to atoms moving into and out of
+the truncation radius, the potential in Cassandra is truncated based on the
+lattice site distance instead of the distance between the atoms.  This will lead
+to a small difference in the measured properties, but the difference will
+disappear in the limit of long truncation.
+
+Example
+-------
+
+An simuation that uses HMA is included in `Examples/NVT/HMA/ <https://github.com/MaginnGroup/Cassandra/tree/master/Examples/NVT/HMA>`_ in the source tree.  The example simulation runs a Lennard-Jones FCC crystal near its melting point.  Energy and pressure are computed using both conventional and HMA and reported in the property output.
+
+References
+----------
+
+Sabry G. Moustafa, Andrew J. Schultz, and David A. Kofke, Very fast averaging of thermal properties of crystals by molecular simulation, `Phys. Rev. E [92], 043303 (2015) <https://dx.doi.org/10.1103/PhysRevE.92.043303>`_

Documentation/source/guides/input_files.rst

@@ -1353,6 +1353,8 @@ Additional supported keywords are:
 * ``nmols``: Number of molecules of each species
 * ``density``: Density of each species in Å\ :sup:`3`
 * ``mass_density``: Density of the system in kg/m\ :sup:`3`
+* ``energy_HMA``: Energy of the system measured with :ref:`HMA <ch:hma>`
+* ``pressure_HMA``: Pressure of the system measured with :ref:`HMA <ch:hma>`, in bar.  The harmonic pressure must be provided as a second argument on this line.
 
 For example, if you would like total energy, volume and pressure of a one box
 system to be written, you may specify the following:

Documentation/source/index.rst

@@ -24,6 +24,7 @@ Cassandra Monte Carlo Software
    guides/input_files
    guides/utilities
    guides/solids
+   guides/hma
 
 .. toctree::
    :hidden:

Examples/NVT/HMA/README

@@ -0,0 +1,19 @@
+This directory contains example HMA input files to run a 500-atom FCC
+simulation using harmonically mapped averaging (HMA) with a Lennard-Jones
+potential.
+
+More information about HMA is available in these publications:
+
+A. J. Schultz, D. A. Kofke, “Comprehensive high-precision high-accuracy
+equation of state and coexistence properties for classical Lennard-Jones
+crystals and low-temperature fluid phases”, J. Chem. Phys. 149, 204508 (2018)
+https://doi.org/10.1063/1.5053714
+
+S. G. Moustafa, A. J. Schultz, D. A. Kofke, “Harmonically Assisted Methods for
+Computing the Free Energy of Classical Crystals by Molecular Simulation: A
+Comparative Study”, J. Chem. Theory Comput. 13, 825-834 (2017)
+https://doi.org/10.1021/acs.jctc.6b01082
+
+S. G. Moustafa, A. J. Schultz, D. A. Kofke, “Very fast averaging of thermal
+properties of crystals by molecular simulation”, Phys. Rev. E 92, 043303 (2015)
+https://doi.org/10.1103/PhysRevE.92.043303

Examples/NVT/HMA/inp500_1.0

@@ -0,0 +1,79 @@
+# Run_Name
+out500
+!------------------------------------------------------------------------------
+
+# Sim_Type
+nvt
+!------------------------------------------------------------------------------
+
+# Nbr_Species
+1
+!------------------------------------------------------------------------------
+
+# Molecule_Files
+lj.mcf 500
+!------------------------------------------------------------------------------
+
+# Box_Info
+1
+cubic
+7.937005259840997
+!------------------------------------------------------------------------------
+
+# VDW_Style
+lj cut 3.
+!---------------------------------------------------------one line for each box
+
+# Temperature_Info
+1.
+!---------------------------------------------------one entry/line for each box
+
+# Move_Probability_Info
+
+# Prob_Translation
+100.
+0.1
+
+# Done_Probability_Info
+!---------------------one line for each box and one entry/line for each species
+
+# Start_Type
+read_config 500 fcc500.xyz
+!---------------------one line for each species and one entry/line for each box
+
+# Run_Type
+production   50000 100
+!------------------------------------------------------------------------------
+
+# Simulation_Length_Info
+units        sweeps
+prop_freq    10
+coord_freq   200
+run          2000
+!------------------------------------------------------------------------------
+
+# Property_Info 1 
+energy_total
+energy_HMA
+pressure
+pressure_HMA 1311.62
+!------------------------------------------------------------------------------
+
+# CBMC_Info
+kappa_ins 12
+rcut_cbmc 6.5
+!------------------------------------------------------------------------------
+
+# Rcutoff_Low
+0.8
+!------------------------------------------------------------------------------
+
+# Pair_Energy
+true
+!------------------------------------------------------------------------------
+
+# Seed_Info
+9799807 23445206
+!------------------------------------------------------------------------------
+
+END

Examples/NVT/HMA/lj.mcf

@@ -0,0 +1,34 @@
+!*******************************************************************************
+!Molecular connectivity file for n2.pdb
+!*******************************************************************************
+!Atom Format
+!index type element mass charge vdw_type parameters
+!vdw_type="LJ", parms=epsilon sigma
+!vdw_type="Mie", parms=epsilon sigma repulsion_exponent dispersion_exponent
+
+# Atom_Info
+1
+1     A       A     1.000   0.000  LJ     1.000     1.000
+
+!Bond Format
+!index i j type parameters
+!type="fixed", parms=bondLength
+
+# Bond_Info
+0
+
+!Angle Format
+!index i j k type parameters
+!type="fixed", parms=equilibrium_angle
+!type="harmonic", parms=force_constant equilibrium_angle
+
+# Angle_Info
+0
+
+# Dihedral_Info
+0
+
+# Improper_Info
+0
+
+END

Src/accumulate.f90

@@ -115,6 +115,16 @@ SUBROUTINE Accumulate(ibox)
   mass_density = mass_density / box_list(ibox)%volume
   ac_mass_density(ibox,iblock) = ac_mass_density(ibox,iblock) + mass_density
 
+  IF (need_HMA) THEN
+     IF (energy_HMA(ibox)%last_calc /= i_mcstep) THEN
+        energy_HMA(ibox)%last_calc = i_mcstep
+        pressure_HMA(ibox)%last_calc = i_mcstep
+        CALL Compute_HMA(ibox)
+     END IF
+     ac_energy_HMA(ibox,iblock) = ac_energy_HMA(ibox,iblock) + energy_HMA(ibox)%total
+     ac_pressure_HMA(ibox,iblock) = ac_pressure_HMA(ibox,iblock) + pressure_HMA(ibox)%total
+  END IF
+
   IF (MOD(i_mcstep,block_avg_freq) == 0) THEN
      ac_energy(ibox,iblock)%total      = ac_energy(ibox,iblock)%total      / data_points_per_block
      ac_energy(ibox,iblock)%intra      = ac_energy(ibox,iblock)%intra      / data_points_per_block
@@ -138,5 +148,6 @@ SUBROUTINE Accumulate(ibox)
         ac_density(is,ibox,iblock)     = ac_density(is,ibox,iblock)        / data_points_per_block
         ac_nmols(is,ibox,iblock)       = ac_nmols(is,ibox,iblock)          / data_points_per_block
      END DO
+     ac_energy_HMA(ibox,iblock)        = ac_energy_HMA(ibox,iblock)        / data_points_per_block
   END IF 
 END SUBROUTINE Accumulate