molecular-dynamics-toy 0.3.1

Interactive molecular dynamics simulation for educational purposes

molecular-dynamics-toy

An interactive molecular dynamics simulation GUI.

This app lets you run a real molecular dynamics simulation on your laptop or home computer. It includes interactive features like clicking to add new atoms, changing the temperature and simulation cell size live, and loading preset atomic configurations.

It uses a pre-trained universal machine learning interatomic potential (MatterSim) with a molecular dynamics integrator from the Atomic Simulation Environment to do the physics, then provides the graphical user interface using pygame.

Physical limitations of this simulation are those of the chosen interatomic potential. Specifically, MatterSim is optimised for bulk materials (i.e. things which fill the whole unit cell) and not for molecules or chemical reactivity. While the physics engine is science-grade, this app is intended for demonstration purposes, and no warranty is given for the accuracy of any results.

Installation

Standalone Executable

Go to Releases and download the file corresponding to your operating system. MacOS has two builds: an app (which you click on like normal apps), and an executable inside a directory. The app build is easier to use, although the executable provides a debug window.

Unzip/unarchive/extract the file (attempting to open it will usually do this).

Enter the MDToy directory then click on/open MDToy.

Your computer will likely flag this as an untrusted app from an unknown publisher. On MacOS, right-click on the file then click Open, then click Open in the pop-up. On Windows, select More info in the pop-up then Open anyway.

Then you're done! The molecular dynamics toy will be running. The first time it runs, it requires an internet connection to download the MatterSim interatomic potential. It will do this to $HOME/.local/mattersim, and should require only 17 MB.

Python installation

Set up a virtual Python environment, such as with Conda.

After installing Conda, you can create a Conda environment in the command line with

conda env create -n mdtoy "python=3.13"
conda activate mdtoy

(You can replace "mdtoy" with a name of your choice.)

Then, install the app with

pip install molecular-dynamics-toy

or, if you want the latest in-development version, with

pip install git+https://github.com/bfield1/molecular-dynamics-toy

Note that the MatterSim dependency requires a C++ compiler; it should tell you where to find one when you attempt to pip install if you don't already have one.

Finally, run the app with

python -m molecular_dynamics_toy

It will automatically download the pre-trained Mattersim model the first time you run it.

(You will need to have the virtual environment you created earlier active, so if you open a new terminal run conda activate mdtoy again.)