Simulation State

Overview

The State class holds all data pertaining to a given simulation. This includes atoms, connectivity information, simulation box size, thermodynamic information, recorded data, and more. State has many member variables and functions which help you to prepare your simulation for running.

Basic Usage

The following is an example which shows basic preparation of the simulation state with detailed explanation of each command

#Initializing the simulation state variable
state = State()

#Set simulation box
#Vector is a DASH-specific class which allows for easy vector math
state.bounds = Bounds(state, lo=Vector(0, 0, 0), hi=Vector(20, 20, 20))

#The box can be changed at any time
state.bounds.lo = Vector(-10, -10, 0)

#Now add a new atom type - atomParams stores atom type information
state.atomParams.addSpecies(handle='species1', mass=1)

#Now we create a fix to apply Lennard-Jones forces
#the fix gets a handle (name), which is useful for restarting simulations
nonbond = FixLJCut(state, handle='myLJCut')

#sets species1-species1 sigma and epsilon to 0.5 and 2, respectively
nonbond.setParameter('sig', 'species1', 'species1', 0.5)
nonbond.setParameter('eps', 'species1', 'species1', 2)

#turn on the fix
state.activateFix(nonbond)

#create some atoms on a lattice
lo = state.bounds.lo
hi = state.bounds.hi
for x in range(lo[0], hi[0]):
    for y in range(lo[1], hi[1]):
        for z in range(lo[2], hi[2]):
            state.addAtom(handle='species1', pos=Vector(x, y, z))

#give the atoms a temperature
InitializeAtoms.initTemp(groupHandle='all', temp=1.0)

#create a Nose-Hoover thermostat
#other
fixNVT = FixNoseHoover(state, handle='myThermostat', groupHandle='all', temp=1.0, timeConstant=0.5)

#then activate it like other fixes
state.activateFix(fixNVT)

#create an integrator - this is a standard langevin integrator,
#though other options are available.

integrator = IntegratorVerlet(state)

#set the timestep
state.dt = 0.005
#run for 10000 turns
integrator.run(10000)

Python Member Functions

Adding and removing atoms

state.addAtom(handle='...', pos=Vector(...), q=0)

handle

Species handle

pos

Position of atom

q

Charge of atom

anAtom = state.atoms[3]
#deletes all bonds, dihedrals, etc as well
state.deleteAtom(anAtom)

Atoms also provides tools for initializing groups of atoms.

Python members

Current turn

turn = state.turn
#reset current turn to 0
state.turn = 0

Simulation timestep

#Setting simulation timestep
#This will be in femptoseconds or LJ time units
#depending on the current units
state.dt = 2

Cutoff radius

Cutoff distance for non-bonded forces, except for charge forces which have their cutoff specially set

state.rCut = 10.0

Neighborlist padding

Distant past rCut for which neighborlists are built. This parameter can be manipulated to optimize performance. Suggested values are 0.5 in Lennard-Jones units and 2.0 Angstroms in real units

state.padding = 2.0

Groups and Molecules

Creating groups of atoms

state.createGroup(handle='...' atoms=[...])

handle

Name of group

atoms

List of atom ids to be in group. Optional argument

state.addToGroup(handle='...' atoms=[...])

handle

Name of group

atoms

List of atom ids to be in group. Optional argument

state.deleteGroup(handle='...')

handle

Name of group to delete

One can easily select all atoms in a group as follows:

atomsInGroup = [a for a in state.atoms if state.atomInGroup(a, 'myGroup')]

Creating molecules

See Molecules.

Setting special neighbor coefficients

Most force fields scale down forces for atoms which are topologically nearby. The 1-2, 1-3, and 1-4 neighbor coefficients can be set as follows:

#1-2, 1-3, 1-4 neighbor coefficients
state.setSpecialNeighborCoefs(0, 0, 0.5)

Note: When using the :doc:’CHARMM</ljcharmm>’ potential, the 1-4 coefficient must be different than 1-2 and 1-3.

Managing fixes, configuration writers, and python operations

Activating fixes

#turns on the fix
state.activateFix(myFix)

#turns off the fix
state.deactivateFix(myFix)

Activating configuration writers

#turns on the writer
state.activateWriteConfig(myWriter)

#turns off the writer
state.deactivateWriteConfig(myWriter)

Activating python operations

#turns on the python operation
state.activatePythonOperation(myOp)

#turns off the writer
state.deactivatePythonOperation(myOp)

Converting particle id to index

currentIdx = state.idToIdx(id)
atom = state.atoms[currentIdx]

Setting periodicity

#0, 1, 2 -> x, y, z
state.setPeriodic(0, False)
isPeriodicZ = state.getPeriodic(2)

Selecting GPUs

At runtime, you can set which GPU to run on using

#set DASH to run on GPU index 0
state.deviceManager.setDevice(0)

#set DASH to run on GPU index 1
state.deviceManager.setDevice(1)

By default it will select device index nDevices-1. You can query the indeces of your devices by running nvidia-smi in the terminal.