Skip to content

Runnning calculations

Jump to bottom
Milan Kočí edited this page Feb 21, 2024 · 11 revisions

Variants of the programs/libraries

FireCore can be generally used in two ways:

Currently there are multiple version of both the program and the library with gradually increasing complexity and added features. Nevertheless, all these variants mostly use class MMFFsp3_loc to solve bonding interactions, and NBFF to solve no-bonding interactions. In addition classes MMFFBuilder and MMFFparams are used to automatically build and manipulate molecular topology and to assign atomic types and force-field parameters.

  • Small molecules in vacuum: Simplest version can relax just free standing molecules in vacuum () use class MolWorld_sp3_simple and can be used trough python interface pyBall/MMFFsp3.py as shown in example directory tests/tMMFFsp3. It is intended mostly for rapid generation of small molecules and testing. It lacks paralezization, substrate etc.
  • Molecules on substrate: full featured CPU based version of the program is using class MolWorld_sp3 which can be run either using GUI tests/tMolGUIapp or through python interface tests/tMMFF which is implemented in pyBall/MMFF.py. The main modification with respect to previous version is
    • Description of substrate (e.g. surface of ionic crystal) by grid-projected forcefied (GridFF)
    • OpenMP paraleziation (using just CPU)
  • GPU parallelized configuration samling The last version MolWorld_sp3_multi is using OpenCL to run multiple replicas (tens-hunderts) of molecule on substrate simultanously to efficiently exploti massively parallel computationl power of modern GPUs with thousands of small procesors. The point is that our systems of interest are typically rather small molecules (<100 atoms) which cannot be efficiently paraleized on so many threads (using more than one processor per atom does not make much sense). However we can run in parallel mutiple versions of the molecule each in different geometric configuration in order to efficiently map the potential energy surface and map the configuration space. This version of the software can be run using GUI in directory tests/tMolGUIapp_multi or through python interface in tests/tMMFFmulti. (NOTE: development of python interface slightly lack behind development of the GUI which is used for esier debugging, therefore we recommand try GUI version first)

Running Standalone GUI program

As shown in tests/tMolGUIapp/run.sh the programs MolGUIapp and MolGUIapp_multi accepts set of command line arguments to modify their mehaviour and setup the system. For complete list of the accepted arugmnes please look inside the code by following the links. Nevertheless, the most importiant parameters are following:

  • -x common_resources/polydiacetylene_OH set input molecular structure in .xyz format.
    • NOTE: lattice vector is expected to be inside the .xyz file in the 2nd (comment) line in format like lvs 13.0 0.0 0.0 0.0 5.0 0.0 0.0 0.0 20.0, make sure that lvs starts at the 1st character of the line.
  • -g common_resources/NaCl_1x1_L2 set input substrate structure in .xyz format
  • -c 10 constrain position of certain atom (10) in cartesian space
  • -b BB.HNH-h.NHO-hh.hbonds bond-constrains between cerain pairs of atoms (e.g. to make sure hydrogen-bonds does not break during the relaxation)
  • -n 141 multiply periodic cell by integer number of copies in each direction (currently only one-digit numbers are possible)
  • -dlvec modify lattice vector just after initialization of molecular forcefied (usefull e.g. if you want to deform the molecule (press or pull) while using topology of undeformed molecule)
  • -EachAngle - bond-angle forcefield parameters (equlibirum angle and stiffness) can differ per each angle (by default we assume angular parameters are the same for each atom)
  • -torsions - use normal torsion angle terms rather than sigma-pi and pi-pi used in original formulation of MMFFsp3_loc force-field. This is (currently experimental).
  • -m 40 - run 40 replicas of the system in parallel (available only in /MolGUIapp_multi)

For example a polydiacetylene polymer on NaCL substrate can be run like this:

./MolGUIapp -x common_resources/polydiacetylene -g common_resources/NaCl_1x1_L2

Or using using GPU acclerated MolGUIapp_multi we can run 40 replicas of PTCDA molecules self assebled on NaCl substrare:

#./MolGUIapp_multi -m 50 -x common_resources/PTCDA_SAM -g common_resources/NaCl_1x1_L2

Running Python library

Python interface is designed to provide rather low-level access to functions C/C++ function and transparent interface to internal data-arrays which are cast as pointers into numpy arrays. An example of usage can be found e.g. in tests/tMMFF/run.py

# --- Import python modules
import sys, os
sys.path.append("../../")                # to make sure pyBall is in $PYTHON_PATH
from pyBall import MMFF        as mmff   # import MMFF.py

# --- initialize
mmff.setVerbosity( verbosity=1, idebug=0 )                            # (optional) set how much debugging information should be printed to stdout from MMFF lib  
mmff.init( xyz_name="data/pyridine", surf_name="data/NaCl_1x1_L2" )   # initialize using data/pyridine.xyz for molecule and surf_name="data/NaCl_1x1_L2.xyz for substrate (lattice vectors assumed to be inside the .xyz files)

# --- setup outpus (optional)
mmff.setTrjName( "relax_trj.xyz", nPBC=(2,2,1), savePerNsteps=100 )  # geometry will be stored into  "relax_trj.xyz" every 100 steps, the periodic cell will be mutiplicated 2x2 along a,b, lattice vectors in order to better visualize which atoms ar neibhors in perodic images
# make numpy arrays to store evolution of energy and force during relaxation
import numpy as np
nstepMax=10000
outE = np.zeros(nstepMax)
outF = np.zeros(nstepMax)

# --- Run
mmff.run(nstepMax=nstepMax, dt=-1, Fconv=1e-4, ialg=2, outE=outE, outF=outF, omp=True)   # run relaxation from maximum number of 10000 steps, with force convergence trashold 1e-4 [ev/A], using FIRE relaxation algorithm (ialg=2), OpenMP acceleration will be used, force and energy evolution will be stored in prepared arrays

# --- plot relaxation (optional)
import matplotlib.pyplot as plt
plt.plot( outE )
plt.plot( outF )
plt.yscale('log')
Clone this wiki locally