pylj 2.0.0b1

pylj runs molecular dynamics and Metropolis Monte Carlo simulations of atoms interacting through pair potentials, in two dimensions, and draws them as they run. It is a teaching code, written in Python and NumPy. Its viewers redraw in a Jupyter notebook; in a script, a viewer's fig is a matplotlib figure that can be saved.

Installation

pip install --pre pylj

pylj 2.0 is a beta release, so pip needs --pre to install it. Without --pre, pip installs the previous release, 1.5.2.

pylj needs Python 3.12 or later. To watch the figures redraw you need a Jupyter notebook; pip install jupyterlab provides one. Start each notebook with %matplotlib inline.

Example

Twenty-five argon atoms at 300 K, run with molecular dynamics and drawn as they go:

from pylj import sample
from pylj.md import MDSimulation
from pylj.model import Model
from pylj.potentials import LennardJones, Species

argon = Species(mass=39.948, name="argon")
lj = LennardJones(epsilon=0.9497, sigma=3.372)
model = Model.single(argon, lj)
simulation = MDSimulation.initialise(model, number_of_atoms=25, temperature=300, box=40, seed=1)
viewer = sample.Interactions(simulation)
for _ in range(2000):
    simulation.step()
    simulation.heat_bath(300)
    simulation.sample()
    if simulation.steps % 100 == 0:
        viewer.update(simulation)

step() advances one timestep, heat_bath() holds the temperature, and sample() records the temperature, pressure and energies in simulation.samples as NumPy arrays:

simulation.samples.temperature.mean()  # K
simulation.samples.pressure.mean()     # kJ/mol/Angstrom^2, the two-dimensional pressure

The same model runs under Monte Carlo:

from pylj.mc import MCSimulation

simulation = MCSimulation.initialise(model, number_of_atoms=25, temperature=300, box=40, seed=1)
viewer = sample.Energy(simulation)
for _ in range(5000):
    simulation.step()
    if simulation.steps % 10 == 0:
        simulation.sample()
    if simulation.steps % 500 == 0:
        viewer.update(simulation)

Custom pair potentials are subclasses of PairPotential with an energies method and a forces method; custom plots are panes composed into a Viewer. The documentation describes the simulation classes, custom potentials, the viewers, and every module.

Contributing

Bug reports and pull requests are welcome on GitHub. CONTRIBUTING.md describes the development setup and the checks a pull request needs to pass.

Citing pylj

McCluskey, A. R., Morgan, B. J., Edler, K. J., and Parker, S. C. (2018). pylj: A teaching tool for classical atomistic simulation. Journal of Open Source Education, 1(2), 19. https://doi.org/10.21105/jose.00019

pylj.__cite__() opens the paper in a browser.