Tighten project documentation

PQEnalyzer/__main__.py

@@ -1,11 +1,4 @@
-"""
-Application entrypoint for PQEnalyzer.
-
-The entrypoint reads one or more data files through a PQAnalysis-backed reader
-and then starts the graphical CustomTkinter application or the terminal
-dashboard. GUI imports stay inside main() so terminal mode can start without
-loading Tkinter.
-"""
+"""Command-line entry point for the GUI and TUI."""
 
 import sys
 import argparse
@@ -49,18 +42,18 @@ def _add_input_arguments(parser):
     input_group.add_argument("-q",
                              "--qmcfc",
                              action="store_true",
-                             help="Use the QMCFC output as input.")
+                             help="Force QMCFC energy input.")
     input_group.add_argument("--box",
                              action="store_true",
-                             help="Read PQ box files instead of energy files.")
+                             help="Force PQ box input.")
     input_group.add_argument("--opt",
                              action="store_true",
-                             help="Read PQ optimizer output files.")
+                             help="Force PQ optimizer output format.")
     parser.add_argument(
         "filenames",
-        metavar="filenames",
+        metavar="FILE",
         nargs="+",
-        help="The name of the files to read the data from.")
+        help="Input file(s).")
 
 
 def _input_format(args, parser):
@@ -95,7 +88,8 @@ def main():
     """
     parser = argparse.ArgumentParser(
         prog="pqenalyzer",
-        description="PQEnalyzer - MolarVerse",
+        description="Plot and monitor PQ simulation output.",
+        epilog="Pass files directly to open the GUI: pqenalyzer FILE [FILE ...]",
     )
     parser.add_argument("-v",
                         "--version",
@@ -107,7 +101,7 @@ def main():
         metavar="{gui,tui}",
         required=True,
     )
-    gui_parser = subparsers.add_parser("gui", help="Open the graphical app.")
+    gui_parser = subparsers.add_parser("gui", help="Open the GUI (default).")
     _add_input_arguments(gui_parser)
     tui_parser = subparsers.add_parser(
         "tui",

README.md

@@ -1,158 +1,141 @@
-<img src="https://raw.githubusercontent.com/MolarVerse/PQEnalyzer/main/PQEnalyzer/icons/icon.png" width="200">
+<img
+  src="https://raw.githubusercontent.com/MolarVerse/PQEnalyzer/main/PQEnalyzer/icons/icon.png"
+  alt="PQEnalyzer"
+  width="200"
+>
 
 [![CI](https://github.com/MolarVerse/PQEnalyzer/actions/workflows/ci.yml/badge.svg)](https://github.com/MolarVerse/PQEnalyzer/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/gh/MolarVerse/PQEnalyzer/graph/badge.svg?token=GMLrCKFfPA)](https://codecov.io/gh/MolarVerse/PQEnalyzer)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 
 # PQEnalyzer
-Energy, box, and optimizer-output analyzer for PQ simulations.
 
-## Installation
-
-Install with pip:
+Plot and monitor PQ energy, box, and optimizer output in a desktop or terminal
+interface.
+
+## Install
 
 ```bash
 pip install PQEnalyzer
 ```
 
-## Usage
+## Quick Start
 
-Open the GUI by passing one or more supported input files. GUI mode is the
-default, so the `gui` subcommand is optional:
+The GUI is the default:
 
 ```bash
 pqenalyzer examples/md-02.en
 ```
 
-Use the terminal dashboard when you want to monitor a simulation from the
-terminal:
+Use the terminal interface with the `tui` subcommand:
 
 ```bash
 pqenalyzer tui examples/md-02.en
 ```
 
-PQEnalyzer detects PQ energy files, QMCFC energy files, PQ box files, and PQ
-optimizer files automatically. Energy files are detected from the matching
-`.info` sidecar file. Box and optimizer files are detected by their conventional
-`.box` and `.opt` suffixes:
+PQEnalyzer detects the input format automatically. Use a format flag only when
+detection is ambiguous:
 
 ```bash
-pqenalyzer pq_output.en
-pqenalyzer qmcfc_output.en
-pqenalyzer examples/box-01.box
-pqenalyzer examples/optimization.opt
+pqenalyzer --pq pq-output.en
+pqenalyzer --qmcfc qmcfc-output.en
+pqenalyzer --box box-output.data
+pqenalyzer --opt optimization.data
 ```
 
-The input format can still be forced when needed. These examples open the GUI
-because GUI mode is the default:
+`pqenalyzer gui FILE` is equivalent to `pqenalyzer FILE`.
 
-```bash
-pqenalyzer --pq pq_output.en
-pqenalyzer --qmcfc qmcfc_output.en
-pqenalyzer --box box_output.data
-pqenalyzer --opt optimizer_output.data
-```
+## Input
+
+| Output | Conventional file | Detection |
+| --- | --- | --- |
+| PQ energy | `.en` with matching `.info` | `.info` layout |
+| QMCFC energy | `.en` with matching `.info` | `.info` layout |
+| PQ box | `.box` | suffix or file contents |
+| PQ optimizer | `.opt` | suffix |
+
+Energy, box, and optimizer parsing is provided by
+[`PQAnalysis`](https://github.com/MolarVerse/PQAnalysis).
+
+Energy files need a matching `.info` file in the same directory. PQ `.info`
+rows containing a single parameter column are supported.
+
+Box files contain `step x y z alpha beta gamma`. PQEnalyzer plots `BOX-X`,
+`BOX-Y`, `BOX-Z`, `ALPHA`, `BETA`, `GAMMA`, and `BOX-VOLUME`.
+
+Optimizer plots use the optimization step as the x-axis. They include energy
+changes, forces, convergence states, and limits. A convergence state of `-1`
+means not converged, `0` means disabled, and `1` means converged. The first row
+is PQ's initialization snapshot. Final completion status remains in the PQ log.
+
+## GUI
+
+| Control | Result |
+| --- | --- |
+| `Plot` | Open a time-series plot for the selected parameter |
+| `Histogram` | Open its distribution |
+| `Live Monitor` | Open one time-series panel per parameter |
+| `Auto-Refresh` | Watch loaded files and update open plots |
 
-Use the explicit `gui` subcommand only when you prefer that spelling:
+Double-click a Live Monitor panel to open its focused plot. Plot settings belong
+to that focused window, so each window can use different overlays.
+
+Auto-refresh starts with the GUI. If native file watching is unavailable,
+PQEnalyzer uses polling and shows `(polling)` in the status line.
+
+## TUI
 
 ```bash
-pqenalyzer gui pq_output.en
+pqenalyzer tui FILE [FILE ...]
 ```
 
-Multiple input files can be plotted together when they expose the same
-parameters and units:
+| Key | Action |
+| --- | --- |
+| `Up` / `k`, `Down` / `j` | Select a parameter |
+| `Enter` | Open the selected chart |
+| `Esc` | Return to the dashboard |
+| `r` | Refresh |
+| `w` | Pause or resume file watching |
+| `q` | Quit |
+
+## Plot Features
+
+The GUI and TUI use the same plot features:
+
+| Feature | Time series | Histogram | TUI key |
+| --- | --- | --- | --- |
+| Mean | yes | yes | `m` |
+| Median | yes | yes | `n` |
+| Cumulative Average | yes | no | `c` |
+| Self-Correlation Mean | yes | no | `s` |
+| Difference (1 - 2) | yes | no | `x` |
+| Running Average | yes | no | `a` |
+
+Self-Correlation Mean stays on the data's original scale; it is not normalized.
+
+## Multiple Files
 
 ```bash
 pqenalyzer md-01.en md-02.en md-03.en
 ```
 
-### GUI
-
-The GUI provides focused time-series plots, histograms, and a `Live Monitor`
-dashboard. `Plot` opens a selected parameter as a time series, `Histogram` opens
-the selected parameter as a distribution, and `Live Monitor` opens a raw
-overview with one panel per parameter.
-
-`Auto-Refresh` is enabled by default. It watches the loaded input files and
-refreshes open plots when new simulation output is written. Disable it to pause
-file watching. If the native file watcher is unavailable, PQEnalyzer falls back
-to polling and marks that mode in the GUI status. Plot controls apply to the
-selected focused plot, so different plot windows can use different statistics
-and overlays at the same time.
-
-Available statistics and overlays are:
-
-- `Mean`
-- `Median`
-- `Cumulative Average`
-- `Self-Correlation Mean`
-- `Difference (1 - 2)`
-- `Running Average`
-
-Double-click a `Live Monitor` panel to open a focused plot for that parameter.
-When `Difference (1 - 2)` is enabled, PQEnalyzer compares the first file against
-the second file and hides the raw data by default so the difference is easier to
-read.
-
-### TUI
-
-The `tui` mode opens a full-screen terminal dashboard with file status,
-per-parameter latest/mean/median/min/max values, compact trends, file-change
-watching, and focused terminal charts.
-
-Use `up`/`k` and `down`/`j` to select a parameter, `enter` to open its chart,
-`esc` to return to the dashboard, `q` to quit, `r` to refresh manually, and `w`
-to pause or resume watching.
-
-Focused charts use the same shared plot features as the GUI: `m` toggles mean,
-`n` toggles median, `c` toggles cumulative average, `s` toggles
-self-correlation mean, `x` toggles difference, and `a` toggles running average.
-
-## Input Files
-
-PQEnalyzer reads energy output through
-[`PQAnalysis`](https://github.com/MolarVerse/PQAnalysis). Each `.en` file is
-expected to have its matching `.info` sidecar file next to it. The `.info` file
-is also used for automatic PQ versus QMCFC energy-file detection. PQ `.info`
-rows with a single left-side parameter entry are supported.
-
-PQEnalyzer also reads PQ box files through `PQAnalysis`. Box files are expected
-to contain `step x y z alpha beta gamma` columns. The plotted parameters are
-`BOX-X`, `BOX-Y`, `BOX-Z`, `ALPHA`, `BETA`, `GAMMA`, and `BOX-VOLUME`.
-
-PQ optimizer `.opt` files are read through `PQAnalysis` and use optimization
-step as their x-axis. All twelve optimizer values are available in both the GUI
-and TUI: absolute and relative energy changes, maximum and RMS forces, their
-four convergence states, and their four limits. Convergence states retain PQ's
-values: `-1` means not converged, `0` means disabled, and `1` means converged.
-PQ writes its initialization snapshot as the first row, so PQEnalyzer preserves
-that row as part of the raw output. PQEnalyzer does not infer optimizer states
-that are absent from the file; use the matching PQ log for final completion
-status.
-
-When multiple files are supplied, common parameters are plotted together.
-Parameters that are present in only some files are still selectable and are
-plotted from the files that contain them. Shared parameters must use matching
-units; incompatible units are rejected before plotting.
-
-Difference plots require exactly two loaded files. Values are calculated as
-`file 1 - file 2` on shared simulation-time, simulation-step, or
-optimization-step values. PQEnalyzer does not interpolate, extrapolate, or
-concatenate difference data.
+Common parameters are plotted together. A parameter found in only some files
+is plotted from those files. Shared parameters must use the same unit.
 
-## Development
+Difference plotting requires exactly two files and calculates
+`file 1 - file 2`. Points are matched by simulation time, simulation step, or
+optimization step. PQEnalyzer does not interpolate, extrapolate, or concatenate
+difference data. Raw series are hidden when Difference is enabled.
 
-Install the package with test dependencies:
+## Development
 
 ```bash
 pip install -e ".[test]"
+python -m pytest -m "not benchmark and not e2e"
 ```
 
-Run the default test suite:
+Run the end-to-end suite separately:
 
 ```bash
-python -m pytest -q
+python -m pytest -m e2e
 ```
-
-Benchmark tests require `pytest-benchmark`. If it is not installed, benchmark
-tests are skipped by default.

pyproject.toml

@@ -10,7 +10,7 @@ authors = [
     {name="Leo Christanell", email="leochristanell@gmail.com"},
     {name="Jakob Gamper", email="97gamjak@gmail.com"}
 ]
-description = "A package that help analyze PQ energy and parameter output."
+description = "Plot and monitor PQ simulation output."
 readme = "README.md"
 license = "MIT"
 requires-python = ">=3.10"