MonitorOLive 0.1.0

Parse, split, and monitor ORCA output files, with optional gnuplot convergence plots.

MonitorOLive

MonitorOLive is a python module handling ORCA output files, including two functions: MonitorO provides tools for automatically parsing and editing ORCA output files, simplifying analysis and enabling visualization of calculation convergence. MonitorOLive provides live visualization of convergence for running ORCA jobs.

Features

• Visualize convergence for SCF, geometry optimization (Opt, OptTS), and NEB-TS calculations using gnuplot.
• Write parsed SCF, geometry-optimization, and NEB-TS convergence variables to CSV files.
• Split ORCA output files by geometry-optimization cycle, vibrational analysis, and compound-job step.
• Append a normal-termination marker for analysis using GoodVibes.
• Remove vibrational-frequency data for analysis using Avogadro 2.

Installation

MonitorOLive requires Python 3.10 or later. gnuplot is required for the visualization features.

python3 -m pip install MonitorOLive

Install gnuplot with:

• Ubuntu or Debian: sudo apt install gnuplot
• macOS: brew install gnuplot
• Windows: download it from the SourceForge gnuplot project

Quick Start

To monitor the SCF convergence of an ORCA job, use:

MonitorOLive <file> --scf

To monitor the geometry convergence of an ORCA job, use:

MonitorOLive <file> --geom

CLI Reference

The package installs two commands:

• MonitorO parses an ORCA output file, writes derived files and CSV data, and creates one-time convergence plots.
• MonitorOLive continually rereads an active ORCA output file and refreshes one or more gnuplot windows.

gnuplot is required for plotting and monitoring, but not for the CSV and file-manipulation features of MonitorO.

MonitorO

Usage

MonitorO PATH [OPTIONS]

PATH is the ORCA output file to read.

General plotting options

Option	Default	Description
-h, --help	—	Show the command help and exit.
--image-type {svg,png}	svg	Select the format used for saved gnuplot images.
--monitor-scf	Off	Open an SCF convergence plot in a gnuplot window. May be combined with --scf-round.
--monitor-geom	Off	Open a geometry-convergence plot in a gnuplot window.
--monitor-neb	Off	Open a CI-NEB convergence plot in a gnuplot window.

SCF options

Option	Value	Description
--scf-convergence-csv FILE	Output path	Write the latest parsed SCF convergence tolerances to a CSV file.
--scf-csv FILE	Output path	Write parsed DIIS, SOSCF, and TRAH rows to a CSV file.
--scf-gnuplot-prefix PREFIX	Output prefix	Save one SCF convergence image per selected SCF chunk.
--scf-round ROUND	1-based integer	Restrict --scf-gnuplot-prefix or --monitor-scf to one SCF chunk.

Geometry and file-manipulation options

Option	Value/default	Description
--split-geom-cycles	Off	Write one ORCA output file per geometry-optimization cycle. By default, files are placed in <input-stem>.frames.MonitorO/.
--vbr-only	Off	With --split-geom-cycles, retain only cycles containing a VIBRATIONAL FREQUENCIES section.
--write-round INDEX	Regular integer index	With --split-geom-cycles, write only the indexed cycle beside the input file. 0 selects the first cycle and -1 the last. With --vbr-only, filtering occurs before the index is applied.
--novib	Off	Write <input-stem>.novib.out, removing Vibrational Frequencies data through the IR Spectrum section.
--split-compound-jobs	Off	Write one output file per numbered compound job.
--fake-normal-termination	Off	Write <input-stem>.fake-normal-termination.out with an ORCA normal-termination marker appended.
--geom-csv FILE	Output path	Write parsed geometry-convergence values to a CSV file.
--gnuplot-output PATH	Output path or prefix	Save a geometry-convergence plot. Its suffix is changed to match --image-type.
--gnuplot-script FILE	geom_convergence.gnuplot	Set the generated geometry gnuplot script path. The data file uses the same path with a .dat suffix.

--vbr-only and --write-round require --split-geom-cycles.

CI-NEB options

Option	Value/default	Description
--neb-ci-csv FILE	Output path	Write parsed CI-NEB iteration values to a CSV file.
--neb-ci-gnuplot-output PATH	Output path or prefix	Save a CI-NEB convergence plot. Its suffix is changed to match --image-type.
--neb-ci-gnuplot-script FILE	neb_ci_convergence.gnuplot	Set the generated CI-NEB gnuplot script path. The data file uses the same path with a .dat suffix.

MonitorOLive

Usage

MonitorOLive FILE [--scf] [--geom] [--neb] [OPTIONS]

FILE is the active ORCA output file to monitor. At least one of --scf, --geom, or --neb is required; the modes may be combined.

Option	Default	Description
-h, --help	—	Show the command help and exit.
-s, --scf	Off	Continuously refresh SCF convergence in a gnuplot window.
-r ROUND, --scf-round ROUND	latest	Monitor a positive, 1-based SCF round or the most recent round with latest. A non-default value requires --scf.
-g, --geom	Off	Continuously refresh geometry convergence in a gnuplot window.
-n, --neb	Off	Continuously refresh CI-NEB convergence in a gnuplot window.
-t TIME[s|m|h], --time TIME[s|m|h]	1s	Set the positive refresh interval. Accepts seconds, minutes, or hours, such as 0.5s, 2m, or 1h. A value without a suffix is interpreted as seconds.
-q KEY, --quit-key KEY	q	Set the single terminal key used to stop live monitoring.

Citation

Neese, F. (2012). The ORCA program system. Wiley Interdisciplinary Reviews: Computational Molecular Science, 2(1), 73-78.

Williams, T., & Kelley, C. (2024). Gnuplot (Version 6.0). gnuplot.info