polyphys.simulate.log#

LAMMPS log files — polyphys.simulate.log#

The log module reads a LAMMPS log file into pandas DataFrames: the thermodynamic output of every run, the summary LAMMPS prints at the end of each run, and the total wall time.

A log holds one run per run or minimize command. Each run starts with the line Per MPI rank memory allocation ... (Memory usage per processor ... in old versions), continues with the thermo table, and ends with the line Loop time of ..., after which comes the run summary. The log ends with Total wall time: H:MM:SS. Every marker is matched at the start of a line only, because the log also echoes the input script, whose comments may contain the same words.

Added in version 0.6.0.

Contents#

read_log() reads a file and parse_log() reads text; both return a LogFile. BrokenLogError, a LammpsFormatError, reports a log that is cut off or does not follow the format.

Thermo styles#

  • one and custom: a header line of keywords, then one row of values per output step, separated by spaces.

  • multi: one section per output step, opened by a line ------------ Step N ----- CPU = t (sec) ------------- and followed by Keyword = value pairs, three per line.

  • yaml: ---, keywords: [...], data:, one `` - […]`` line per output step, and ....

WARNING lines and the Fix halt condition ... message may appear inside a table, and recent versions follow each with a For more information see ... line; all three are skipped, and the first two are logged. Blank lines are skipped. Any other line inside a table that is not data raises BrokenLogError.

Complexity#

Time and memory are \(O(L)\) in the length \(L\) of the log: the file is read once and each line is visited a bounded number of times.

References

The formats follow the LAMMPS documentation of thermo_style, thermo_modify, and run, and these output statements in the LAMMPS source, release stable_30Sep2026:

Dependencies#

  • Python standard library: dataclasses, enum, logging, pathlib, re

  • Third-party: pandas

  • PolyPhys: polyphys.simulate.core

Functions

parse_log(text[, path])

Parse the text of a LAMMPS log.

read_log(path)

Read a LAMMPS log file.

Classes

LogFile(path, lammps_version, thermo, ...)

The parsed contents of one LAMMPS log.

Exceptions

BrokenLogError

A LAMMPS log is cut off or does not follow the log format.

exception polyphys.simulate.log.BrokenLogError[source]#

Bases: polyphys.simulate.core.LammpsFormatError

A LAMMPS log is cut off or does not follow the log format.

Examples

A log killed during its first run has no Loop time of line:

>>> text = '''LAMMPS (22 Jul 2025 - Update 4)
... Per MPI rank memory allocation (min/avg/max) = 4.9 | 4.9 | 4.9 Mbytes
...    Step          Temp
...          0   1
...        100   0.5
... '''
>>> try:
...     parse_log(text)
... except BrokenLogError as err:
...     print(err)
Run 0 (line 2) has no 'Loop time of' line; the log may be cut off.
class polyphys.simulate.log.LogFile(path, lammps_version, thermo, run_stats, wall_time)[source]#

Bases: object

The parsed contents of one LAMMPS log.

The DataFrames can still be changed in place; copy one before editing it.

Variables:
  • path (pathlib.Path or None) – The log file, or None when the log was parsed from text.

  • lammps_version (str or None) – The version on the first line of the log, such as '22 Jul 2025 - Update 4', or None if the first line is not LAMMPS (<version>).

  • thermo (pandas.DataFrame) – One row per thermo output step of every run, in log order. Column run (int64) is the position of the run in the log, from 0; the other columns are the thermo keywords exactly as LAMMPS prints them, such as Step, Temp, or c_gyr[1]. Step is int64 and every other keyword float64. A keyword absent from a run is NaN in that run’s rows. The first row of each run repeats the step at which it starts, so a run that follows another without reset_timestep repeats the previous run’s last step.

  • run_stats (pandas.DataFrame) –

    One row per run, from its summary:

    • run: position of the run in the log, from 0.

    • loop_time: wall time of the run, in seconds.

    • n_cores: processes times OpenMP threads.

    • loop_timesteps: number of timesteps of the run.

    • n_atoms: number of atoms at the end of the run.

    • perf_per_day, perf_unit, timesteps_per_s: simulated time per day of wall time, its unit ('tau/day', 'fs/day', or 'ns/day'), and timesteps per second of wall time.

    • cpu_use: CPU use, in percent.

    • mpi_task: number of MPI tasks.

    • openmp_threads: OpenMP threads per task, 0 for a build without OpenMP.

    • <section>_avg_time and <section>_total_pct: average time, in seconds, and percent of the loop time spent in each section of the MPI task timing breakdown, such as Pair_avg_time.

    • dangerous_builds: dangerous neighbor-list builds.

    A field the run does not report is NaN: LAMMPS prints no performance line after minimize or in cgs and si units, and no count of dangerous builds when neighbor checks are off.

  • wall_time (pandas.DataFrame) – One row: wall_time_s (int64, seconds) and wall_time_hr (float64, hours) from the Total wall time line, and n_cores and n_atoms from the summary of the last run.

Parameters:

Examples

>>> text = '''LAMMPS (22 Jul 2025 - Update 4)
... Per MPI rank memory allocation (min/avg/max) = 4.9 | 4.9 | 4.9 Mbytes
...    Step          Temp
...          0   1
...        100   0.5
... Loop time of 0.01 on 1 procs for 100 steps with 20 atoms
...
... Per MPI rank memory allocation (min/avg/max) = 4.9 | 4.9 | 4.9 Mbytes
...    Step          Temp
...        100   0.5
...        200   0.25
... Loop time of 0.02 on 1 procs for 100 steps with 20 atoms
...
... Total wall time: 0:00:01
... '''
>>> log = parse_log(text)
>>> log.thermo
   run  Step  Temp
0    0     0  1.00
1    0   100  0.50
2    1   100  0.50
3    1   200  0.25

Keep the second run only:

>>> log.thermo[log.thermo["run"] == 1]["Temp"].tolist()
[0.5, 0.25]
>>> log.run_stats[["run", "loop_time", "loop_timesteps"]]
   run  loop_time  loop_timesteps
0    0       0.01             100
1    1       0.02             100
lammps_version: str | None#
path: pathlib.Path | None#
run_stats: pandas.DataFrame#
thermo: pandas.DataFrame#
wall_time: pandas.DataFrame#
polyphys.simulate.log.parse_log(text, path=None)[source]#

Parse the text of a LAMMPS log.

Parameters:
  • text (str) – The whole log.

  • path (pathlib.Path | None) – The file the text came from, stored in the result.

Returns:

The parsed log.

Return type:

polyphys.simulate.log.LogFile

Raises:

BrokenLogError – If the log has no run; a run has no Loop time of line, as after a walltime kill, or one of another form than Loop time of <t> on <n>     procs for <steps> steps with <atoms> atoms; an ERROR line appears; a thermo header repeats a keyword; a thermo table holds a line that is neither data nor a skipped message; or the log has no Total wall time line.

Notes

Time and memory are \(O(L)\) in the length \(L\) of text.

Examples

>>> text = '''LAMMPS (22 Jul 2025 - Update 4)
... Per MPI rank memory allocation (min/avg/max) = 4.9 | 4.9 | 4.9 Mbytes
...    Step          Temp          c_rg[1]
...          0   1                 nan
... WARNING: Lost atoms: original 20 current 19 (src/thermo.cpp:532)
... For more information see https://docs.lammps.org/err0008
...        100   0.5               2.5
... Loop time of 0.01 on 1 procs for 100 steps with 19 atoms
...
... Total wall time: 0:00:01
... '''
>>> log = parse_log(text)
>>> log.lammps_version
'22 Jul 2025 - Update 4'
>>> log.thermo
   run  Step  Temp  c_rg[1]
0    0     0   1.0      NaN
1    0   100   0.5      2.5
polyphys.simulate.log.read_log(path)[source]#

Read a LAMMPS log file.

Parameters:

path (str | pathlib.Path) – The log file, read as UTF-8; an undecodable byte becomes U+FFFD. A name ending in .gz is read through gzip.

Returns:

The parsed log, with path set to path as a pathlib.Path.

Return type:

polyphys.simulate.log.LogFile

Raises:

BrokenLogError – If the log is cut off or does not follow the format; see parse_log().

Notes

Time and memory are \(O(L)\) in the length \(L\) of the file.

Examples

>>> import tempfile
>>> text = '''LAMMPS (22 Jul 2025 - Update 4)
... Per MPI rank memory allocation (min/avg/max) = 4.9 | 4.9 | 4.9 Mbytes
...    Step          Temp
...          0   1
...        100   0.5
... Loop time of 0.01 on 1 procs for 100 steps with 20 atoms
...
... Total wall time: 0:01:05
... '''
>>> with tempfile.TemporaryDirectory() as tmp:
...     path = Path(tmp) / "log.lammps"
...     _ = path.write_text(text)
...     log = read_log(path)
>>> log.path.name
'log.lammps'
>>> log.wall_time[["wall_time_s", "n_atoms"]]
   wall_time_s  n_atoms
0           65       20