what is pylj?

pylj is an open-source Python library to facilitate student interaction with classical atomistic simulation. It is designed to operate within the Jupyter notebook framework, making it easy to implement in the classroom, or computer lab. pylj has been published in the Journal of Open-Source Education, this paper is a great place to find out more.

what does pylj offer?

Currently pylj can perform the simulation of a 2D argon system by molecular dynamics, with both NVE and NVT ensembles available and making use of a Velocity-Verlet integrator, as well as Metropolis Monte-Carlo simulations. A series of sampling classes exist (found in the sample module), such as the Interactions (MD), Scattering (MD), and Energy classes. However, it is straightforward to build a custom sampling class either from scratch or using the sampling class building tools.


Examples of the Monte-Carlo and molecular dynamics interfaces can be found at the following links. This is running on mybinder, which is not a resource that we control. As a result it may take a few attempts to build the resource.

Some examples of possible teaching laboratory exercises making use of pylj are discussed in the Usage section of the paper

how to get pylj?

If you are interested in using pylj, in any sense, fork the code at github.com/arm61/pylj or install via pip. If you have any trouble email Andrew (arm61 ‘at’ bath.ac.uk).

is there documentation?

Full API level documentation is available at pylj.rtfd.io. For something more high-level, the paper is a great place to start.


To run pylj locally we recommend installing the Anaconda, which gives access to Jupyter notebook framework and the necessary packages. It is also it is desirable to have a C++ compiler, most macOS or Linux machines should already have this, on Windows it is best to install the Visual C++ package.

contributing and feature requests

Information about contributing can be found here.

how to cite pylj

Thank you for using pylj. If you use this code in a teaching laboratory or a publication we would greatly appreciate if you would cite both the JOSE paper and the Zenodo DOI appropriate to your particular version of pylj (use the function pylj.util.__cite__() to get the appropriate DOI).