1. Introduction

MDMC broadly provides two main functions, the MD (Molecular Dynamics) simulation and the MC (Monte Carlo or similar) refinement of force-field parameters:

1.1. Simulation

To run a refinement using MDMC it is first necessary to define the simulation setup for which the parameters will be refined. This includes defining a Universe, creating a configuration and specifying the topology, and defining the conditions of the Simulation. Descriptions of the relevant objects can be found in the section on Simulations, and there are several interactive (Jupyter notebook) Tutorials on topics relating to setting up a simulation.

MDMC uses external molecular dynamics packages to run the simulations. Currently LAMMPS is the only MD engine implemented. The code for MDMC is written such as to be extensible and we welcome requests of other MD packages to be added.

MDMC can be used to run simulations without refinement, and MDMC comces with a number of helper methods aimed at simplifing setting up simulations.

1.2. Refinement

To refine the parameters of a simulation, one or more experimental datasets must be provided and a minimiser must be selected. Here are the descriptions of the available experimental observables (the objects representing experimental datasets), the minimizers, and the Control class, which runs the refinement.

It is possible to refine all of the parameters, or to specify a subset to be refined, which is shown in the interactive tutorial Selecting Fitting Parameters.

For an explanation of the refinement steps, please see the tutorial Running a Refinement, and for a full demonstration of MDMC, including setting up a simulation and running a refinement, please see the .py files within ‘examples’.

1.3. Tutorials

There are a number of tutorials covering different aspects of MDMC located in doc/tutorials/. These tutorials provide a explanation of the main steps to creating a simulation and running a refinement. Major features are described in these tutorials, however the full Modules documentation can be used to get descriptions of all of the options available within MDMC.

Each of these tutorials is an interactive Jupyter notebook which can be modified and run by the user; this allows experimentation from an established starting point. The interactive tutorials can be accessed by installing Jupyter and running it within the tutorials folder:

pip install Jupyter
Jupyter notebook

Static copies of these tutorials can be viewed using the links in the sidebar.

1.4. Modules

The pages in the sidebar under the Modules heading provide documentation for every function, class and class method in MDMC, including descriptions of parameters (or options) which can be used in each of these cases. This documentation is also available when Python is run interactively using Python’s help() function. For example, to get the documentation for the Universe class:

from MDMC.MD.simulation import Universe
help(Universe)

and to get the documentation specific to the solvate method of the Universe class:

help(Universe.solvate)

It is also possible to get the same documentation by calling help on instantiated objects:

uni = Universe(10.)
help(uni)

will output the same documentation as the first example.