Logging and progress¶

Calculation log¶

During a real calculation, gmx_MMPBSA.log is created in the working directory. In an MPI run, rank 0 owns this master log; non-master ranks do not truncate or append to it. A non-master rank creates a rank-specific diagnostic log only if it emits an error.

The log uses a compact format:

[INFO   ] Complex completed: 10 frames in 00:01 (9.99 frame/s)

The file contains DEBUG records as well as normal lifecycle, warning, and error records. Terminal output remains at INFO level so it stays readable. --help, --version, and other command-line parsing actions do not create or replace a previous calculation log. A real calculation or --rewrite-output starts a fresh log, so concurrent runs should use separate working directories.

Monitor a batch job with:

tail -f gmx_MMPBSA.log

The final summary reports warning and error records counted directly by the logging system. Multiline messages count as one record. Fatal exceptions terminate the run; a nonfatal error record does not change the exit status.

Preparation timers¶

Existing preparation steps use the same basic elapsed-time feedback in gmx_MMPBSA and amber_MMPBSA, regardless of the selected energy method. This covers structure loading and validation, residue mapping, topology reading/selection/conversion, trajectory cleanup, and dASA preparation when applicable.

This can take a while; please wait... [|] 12s

Updates start after one second. On a terminal, carriage returns redraw the same line; no ANSI terminal features are required for direct terminal output. MPI forwarding uses the same line-buffered redraw handling as calculation progress, keeping the timer on one line while flushing live updates. Ordinary redirected output uses newline-terminated updates. Short steps may finish before the first update. Each timed step logs its completion or interruption duration; animated updates are not written to gmx_MMPBSA.log.

Topology preparation is performed by the master MPI rank. The calculation progress styles below control the energy-calculation monitor separately; they do not disable these preparation timers. No additional input option is needed for preparation feedback.

Progress display modes¶

Select a mode with --progress-style:

Rich and classic renderers do not write animated bars or ANSI control sequences to the calculation log. Progress checkpoints use MPI-rank terminology and are emitted at bounded percentage milestones. If an external calculation stops producing frames for the default five-minute stall interval, the log emits a rate-limited waiting notice rather than repeating a warning on every poll.

Rich progress through Open MPI 5¶

Open MPI 5 can buffer rank output into complete lines. When output is forwarded through a pipe, gmx_MMPBSA terminates each Rich redraw with a newline and compensates for the added cursor movement on the next redraw. This lets the live bar update without special launcher options. Automatic selection uses Rich even when MPI hides the terminal; TERM=dumb or an unavailable Rich installation retains the classic fallback. The classic bar uses the same forwarding protection. Direct terminal output uses each renderer's native redraws.

For older gmx_MMPBSA installations whose Rich bar appears only after a calculation contribution finishes, pass --output :raw to the Open MPI 5 launcher:

mpirun --output :raw -np 8 gmx_MMPBSA -O -i mmpbsa.in -cs com.tpr -cp topol.top \
    -ci index.ndx -cg 1 13 -ct com_traj.xtc --progress-style rich

The package-level forwarding and this launcher option were verified with Open MPI 5.0.8. The launcher option must be supplied before gmx_MMPBSA starts. For other MPI implementations, check their output-forwarding options. --progress-style plain provides newline-terminated milestones when live redraws cannot be forwarded.

Warnings and errors¶

Warnings are reserved for conditions that may affect interpretation, accuracy, performance, compatibility, or requested behavior. Expected automatic actions—such as assigning QM charges, preparing GBNSR6 topology copies, or assigning missing chain IDs—are informational records. Scientific approximations, fallback paths, incomplete convergence, and user-value mismatches remain warnings.

Fatal input and setup errors are recorded once with a concise message. Unexpected internal exceptions include traceback context in the log. By default, a failed gmx_MMPBSA or amber_MMPBSA calculation creates a diagnostic zip bundle and records its path so the archive can be attached to a bug report. The bundle can contain logs, input and setup files, generated intermediates, and samples of up to five trajectory frames; review its contents before sharing it.

Use --no-error-bundle to disable automatic bundle creation, for example when input coordinates must not be copied into an archive:

gmx_MMPBSA --no-error-bundle -O -i mmpbsa.in ...

The same option is accepted by amber_MMPBSA. It affects only diagnostic bundle creation after a failure; normal logging and the calculation exit status are unchanged.

Message text is intended for people, not as a stable machine-readable interface. Scripts should use result files and exit status rather than parsing logging wording.