Metadata-Version: 2.4
Name: MonitorOLive
Version: 0.1.0
Summary: Parse, split, and monitor ORCA output files, with optional gnuplot convergence plots.
Author: AzuleneG
Project-URL: Homepage, https://github.com/AzuleneG/MonitorOLive
Project-URL: Repository, https://github.com/AzuleneG/MonitorOLive.git
Keywords: computational-chemistry,orca
Classifier: Environment :: Console
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file
Requires-External: gnuplot

# 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](https://github.com/patonlab/goodvibes).
- Remove vibrational-frequency data for analysis using [Avogadro 2](https://avogadro.cc/index.html).

## Installation

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

```bash
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](https://sourceforge.net/projects/gnuplot/files/gnuplot/)

## Quick Start

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

```bash
MonitorOLive <file> --scf
```

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

```bash
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

```text
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

```text
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
