Simulation State


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

#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
fixNVT = FixNoseHoover(state, handle='myThermostat', groupHandle='all', temp=1.0, timeConstant=0.5)

#then activate it like other fixes

#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

Python Member Functions

Adding and removing atoms

state.addAtom(handle='...', pos=Vector(...), q=0)
Species handle
Position of atom
Charge of atom
anAtom = state.atoms[3]
#deletes all bonds, dihedrals, etc as well

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=[...])
Name of group
List of atom ids to be in group. Optional argument
state.addToGroup(handle='...' atoms=[...])
Name of group
List of atom ids to be in group. Optional argument
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

#turns off the fix

Activating configuration writers

#turns on the writer

#turns off the writer

Activating python operations

#turns on the python operation

#turns off the writer

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

#set DASH to run on GPU index 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.