Quickstart Guide¶
The following assumes you have MoSDeF Cassandra installed. If not, please refer to our installation guide. More details of the core MoSDeF Cassandra functionality can be found under the Guides section of the documentation.
Let’s start by setting up an NVT Monte Carlo simulation of OPLS-AA
methane. We will use the mbuild
and foyer
packages to create
the methane molecule, and mosdef_cassandra
to run the Monte Carlo
simulation. We begin with the required imports:
import mbuild
import foyer
import unyt as u
import mosdef_cassandra as mc
Next, we create an all-atom methane molecule from a SMILES string:
methane = mbuild.load("C", smiles=True)
methane
is a single all-atom methane molecule. It is an
mbuild.Compound
. methane
contains particles for each
element (C, H, H, H) in the molecule, coordinates associated
with each particle, and the bonds that describe the particle
connectivity. However, there are no forcefield parameters
associated with methane
.
To add forcefield parameters to methane
, we first load the OPLS-AA
forcefield from foyer. The OPLS-AA forcefield is distributed with foyer.
Be aware that not all atomtypes are currently defined.
oplsaa = foyer.forcefields.load_OPLSAA()
We then apply the forcefield using foyer:
methane_ff = oplsaa.apply(methane)
methane_ff
is a parmed.Structure
that contains all the
forcefield parameters for our methane molecule.
Now that we have a molecule with forcefield parameters, the next step is
to define our simulation box. Since Cassandra can add molecules to a
simulation box before the start of a simulation, we can begin with an
empty simulation box. We will define an mbuild.Box
with the box
lengths specified in nanometers:
box = mbuild.Box([3.0, 3.0, 3.0])
Warning
Even though most quantities in MoSDeF Cassandra must be
specified with the unyt package,
the mbuild.Box
object is specified
in nanometers without using unyt
. This is because
mbuild
does not currently support unyt
.
Next, we create the System
object. It has two required arguments and
two optional arguments, depending on your system. The box_list
and
species_list
are always specified. The box_list
is simply a list
of the simulation boxes in the system. In this case, since we are performing
an NVT simulation there is only our single box
. The species_list
is a
list of the unique chemical species in our system. Here we only have methane.
The two system-dependent arguments are mols_in_boxes
and mols_to_add
.
Here we have an empty initial box, so we don’t need to specify
mols_in_boxes
. Finally, mols_to_add
specifies the
number of molecules that we wish to add to each box prior to beginning
the simulation in Cassandra. We will add 50 methane molecules for this example.
box_list = [box]
species_list = [methane_ff]
mols_to_add = [[50]]
Note
mols_in_boxes
and mols_to_add
are lists with one entry
for each box. Each entry is itself a list, with one entry for
each species in the species_list
.
We now combine the four components created above into a System
:
system = mc.System(box_list, species_list, mols_to_add=mols_to_add)
Note
mols_in_boxes
and mols_to_add
are optional arguments when creating
the System
object. If not provided, the values are taken as zero for
all species in all boxes.
Note
Each item in the species_list
must be a parmed.Structure
object with
the associated forcefield parameters. For example, species_list =
[methane]
would not work because unlike methane_ff
, methane
is
a mbuild.Compound
and does not contain forcefield parameters.
Now we create our MoveSet
. The MoveSet
contains all selections
related to the MC moves that will be performed during the simulation.
In addition to the probability of performing different types of MC moves,
the MoveSet
contains the maximum move sizes (e.g., maximum translation distance),
whether each species is insertable, and more. To create the MoveSet
, we
specify the ensemble in which we wish to perform the MC simulation and provide
the species_list
.
ensemble = 'nvt'
moveset = mc.MoveSet(ensemble, species_list)
Some attributes of the MoveSet
can be edited after it is created. This
allows complete control over all the move-related selections in Cassandra. To
view the current selections, use moveset.print()
.
The final step is to run the simulation. The run
function requires
five arguments: the System
, MoveSet
object, a selection of
"equilibration"
or "production"
(run_type
), the simulation length
(run_length
), and the desired temperature. Note that since the temperature
is a physical quantity it must be specified with
units attached.
mc.run(
system=system,
moveset=moveset,
run_type="equilibration",
run_length=10000,
temperature=300.0 * u.K
)
A large number of additional keyword arguments can be provided inline or as part
of a keyword dictionary. See mc.print_valid_kwargs()
for a complete list of
the available keyword arguments.