🚀 v1.2.1 is out

[alexjilkin]

v1.2.1 adds async simulation callbacks that allow JavaScript to control when LAMMPS advances to the next step.

The main new API is: runScriptAsync(script, callback, { every, ... })
It works for both run N and minimize.

The callback can return a Promise. If it does, LAMMPS waits until the Promise resolves before continuing. This means JS directly gates simulation progress.

How it works

1. JS calls runScriptAsync(...).
2. The wrapper registers a callback bridge and injects fix js/async if needed.
3. LAMMPS executes the script.
4. The custom fix hooks into END_OF_STEP and MIN_POST_FORCE.
5. On each hook, C++ calls the JS callback.
6. If the callback returns a Promise, C++ waits until it resolves.
7. Only then does the simulation continue.

Callback data

Callbacks can receive:

• particles
• bonds
• box
• compute scalars (optional)

Speed control

Simulation speed can be controlled in two ways:

• every: how often the callback runs
• Promise resolution time: how long each step is paused

The current Three.js example runs a single long run and controls speed via Promise delay.

Other fixes in this release

• Proper cleanup on synchronous callback errors
• Fix reuse and frequency update handling
• Correct unfix ordering during script parsing
• Minimize path supported in the async fix

Tests

• All Vitest tests passing (21/21)
• Covers run, minimize, injection, callback cleanup, and compute scalars

GitHub release:
https://github.com/lammps/lammps.js/releases/tag/v1.2.0

npm:
https://www.npmjs.com/package/lammps.js