Particle Map

As first demonstrated by McCarty2019 it is possible to simulate an identical model in both field-theoretic simulations and molecular dynamics.

To make the conversion simple, OpenFTS can automatically write LAMMPS or HOOMD input files using the parameters specified in an OpenFTS input file. There are two ways to do this.

  1. “map_to_particle” Python Function

  2. ParticleMap Driver

Examples of both methods can be found in the OpenFTS/test/integration-tests/pytest/particlemap/ModelMeltChiAB directory.

“map_to_particle” Python Function

To use this function, simply append the following to an exising OpenFTS python input script.:

import openfts
fts = openfts.OpenFTS()
...
# for LAMMPS
fts.map_to_particle(simulation_type="lammps",file_prefix="polymer")

# for HOOMD
fts.map_to_particle(simulation_type="hoomd",file_prefix="polymer")
...

The fts.map_to_particle command can be combined with fts.run to both generate

ParticleMap Driver

In this case you will modify the fts.driver() line of your input script:

import openfts
fts = openfts.OpenFTS()
...
# for LAMMPS
fts.driver(type='ParticleMap',simulation_type='lammps',file_prefix="polymer")

# for HOOMD
fts.driver(type='ParticleMap',simulation_type='hoomd',file_prefix="polymer")
...
fts.run()

If running OpenFTS as a C++ executable, you can add the following to the json input file

"driver": {
  "file_prefix": "polymer",
  "simulation_type": "lammps"
  "type": "ParticleMap"
},

Arguments

  • file_prefix (string) - file prefix to use for generated MD input files. Default: polymer.

  • simulation_type (string) - type of MD simulation to initialize. Either lammps or hoomd.

    • simulation_type=”lammps” generates:

      • polymer.xyz - xyz coordinates of particles, not used by LAMMPS but can be helpful for initial visualization

      • polymer.psf - topology of generated configuration

      • polymer.data - a LAMMPS read_data file containing particle positions, bonds and box dimensions

      • polymer.coeff - interaction styles and coefficients for easy import into LAMMPS script using include command

      • in.lammps - a LAMMPS input script for actually running a simulation.

    • simulation_type=”hoomd” generates:

      • polymer.gsd - gsd file that contains coordinates and topology of initial configuration

      • polymer.json - json file with coefficients for easy import into a python/HOOMD input script

      • run-hoomd3.py - a HOOMD input script for actually running a simulation

  • seed (int) - random seed used to generate particle coordinates. If unspecified, one is generated randomly using hardware entropy source (i.e., std::random_device)

  • rcut (float) - pair cutoff to write to MD input files.

  • rcut_units (str) - units of provided rcut. Can either be b or Rg.

    Note

    Prior versions of the code used rcut in units of a, the smearing length of the model in units of b. If you have old input files that used this prior convention, you will need to convert to the new convention. If your old rcut was given by X, then your new rcut arguments will be rcut=X*atilde, rcut_units=”Rg” where atilde is the smearing length in units of Rg. The old code also defaulted to \(X=4.5\sqrt{2}\) (Yes, this is a very odd default value. There is a reason the current code only accepts rcut in units of b or Rg).

  • alpha_ewald (float) - \(\alpha_E\) parameter used to separate real and reciprocal space solutions of Coulombic interactions with Ewald sumations or PPPM. Units are given in \(1/b_{ref}\) (where at the moment \(b_{ref}\) must = 1). See Deserno and Holm for many considerations in setting this parameter. Note, this parameter should only be specified for models with charged interactions.

  • table_exponent (float) - exponent used for tabulated pair potentials. Total table length is \(2^X\). Typically only used for Coulombic interactions to compatibilize the regularized Coulomb pair potentials with the default Ewald/PPPM solvers in LAMMPS/HOOMD. See Kiss2013/McCarty2019 for more details.

  • widom_insertions (int) - generate specified number of random configurations that can be used for widom insertions to calculate the chemical potential. If input argument is not zero, these configurations are written to <file_prefix>_molX.dat where X is the molecule index. Default: 0 (do not generate any insertions).

    • run-hoomd3-widom.py - a HOOMD input script that is optionally generated if !=0 and simulation_type=”hoomd”. This script can be used to calculate the chemical potential using widom insertions into an existing HOOMD trajectory. See script internals for details.