How Do You Initialize an MD Simulation Without Biasing the Result?

Note: This is an early draft page for the executable kUPS MD tutorial series. It is intentionally hidden from site navigation while the simulations, notebooks, figures, and review artifacts mature. The source repository is sungsoo-ahn/kups-md-tutorials; corrections and replication issues should be tracked against that repository.

Introduction

Molecular dynamics papers often begin after the most consequential choices have already been made. The system has a cell, atom positions, velocities, a target temperature, a seed, maybe a minimization stage, maybe a warmup stage, and usually some center-of-mass cleanup. These details look procedural, but they define the distribution from which the trajectory starts.

For ML researchers who already know the equation of motion,

the practical question is different: what exactly did we initialize, and can someone else reproduce it? If the answer is vague, later claims about thermostats, equilibration, free energies, or MLIP stability are already on weak ground.

This draft demonstrates the first reproducible slice of the series using FCC argon smoke and full profiles. The smoke profile is for fast CPU verification; the full profile is the current source for the diagnostic figure.

• smoke configuration
• full configuration
• initialization notebook
• smoke summary
• full summary
• full provenance manifest
• self-review note

What Must Be Fixed?

An initial state is not only coordinates. For this tutorial, the committed configuration fixes:

The smoke case remains useful because it exposes the bookkeeping quickly. A later trajectory should not merely say “argon at 94.4 K.” It should say which density, which seed, which velocity distribution, whether exact temperature rescaling was used, whether center-of-mass motion was removed, and which code revision produced the state.

Velocities Are Samples

The current profile samples momenta from the Maxwell-Boltzmann distribution and does not force the instantaneous kinetic temperature to equal the target temperature. That is intentional. In a finite system, the kinetic temperature of one velocity draw fluctuates. Forcing it to match exactly can be useful for some workflows, but it changes the draw.

This distinction matters for later posts. Thermostat validation, equilibration diagnostics, and uncertainty estimates all depend on remembering which quantities were sampled and which were constrained by construction.

Reproduction

The current executable path is:

git clone https://github.com/sungsoo-ahn/kups-md-tutorials
cd kups-md-tutorials
uv sync
uv run kups-tutorial run 01 --profile smoke
uv run kups-tutorial verify 01 --profile smoke
uv run kups-tutorial run 01 --profile full
uv run kups-tutorial verify 01 --profile full
uv run jupyter execute notebooks/post-01-initialization.ipynb --inplace

The notebook is deliberately not the source of reusable logic. It imports the configuration loader, initializer, provenance helper, and figure generator from src/kups_md_tutorials/. That separation keeps the article readable while making the numerical outputs testable.

Current Status

This page is not the final article. The implemented pieces are:

• CPU smoke initialization workflow
• committed compact smoke and full outputs
• executable notebook
• generated SVG/PNG figure and snapshot review
• self-review note covering code, science, and figure feedback

The missing pieces are:

• final article prose
• rendered desktop and mobile page snapshots
• broader connection to minimization and warmup choices

The rule for this series is simple: a result is not ready because the code ran. It is ready only after the code, data, figure, prose, and rendered page have all been reviewed against the same reproducibility contract.

References

• Frenkel, D. & Smit, B. (2001). Understanding Molecular Simulation: From Algorithms to Applications. Academic Press.
• Tuckerman, M. E. (2010). Statistical Mechanics: Theory and Molecular Simulation. Oxford University Press.