Skip to content
Projects

arm61/pylj has 31 GitHub stars and 22 forks. GitHot measured 0 stars in 24 hours. Last checked 2026-11-15 16:57 UTC. Last push 2026-10-14.

How these counts are measured

Measured star growth

in 24h
0
in 7 days
Update delayed
in 15 days
Update delayed
in 1 month
Update delayed

Net star changes over overlapping periods, not daily totals. Missing measurements are left blank. Stars measure attention, not software quality.

About

Teaching Utility for Classical Atomistic Simulation.

Learning

README.md

Original

JOSE PyPI DOI Documentation Build License: MIT

pylj runs molecular dynamics and Metropolis Monte Carlo simulations of atoms interacting through pair potentials, in two dimensions, and draws and animates the atoms. It is a teaching code, written in Python and NumPy.

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.

Example

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

import matplotlib.pyplot as plt

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)
for _ in range(2000):
    simulation.step()
    if simulation.steps % 50 == 0:
        simulation.rescale_velocities(300)
    simulation.sample()
simulation.view()
plt.show()

step() advances one timestep. sample() records the configuration in simulation.trajectory and 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

In a Jupyter notebook, simulation.animate() plays the recorded configurations as an animation. In a script, save simulation.animate().data to an .html file and open it in a web browser.

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)
for _ in range(5000):
    simulation.step()
    if simulation.steps % 10 == 0:
        simulation.sample()
simulation.view()
plt.show()

Custom pair potentials are subclasses of PairPotential with an energies method and a forces method. The documentation describes building, running and sampling a simulation, pictures and animations, custom potentials, units, 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.