CLI Tools Reference

In addition to the main ensemble_analyzer driver, the package provides a suite of command-line interface (CLI) tools to assist with setup, pre-processing configuration, and post-processing analysis.

1. Installation Check (enan_check)

A diagnostic tool to verify the installation of python dependencies and the linkage to external QM software (ORCA/Gaussian).

Usage:

enan_check

Checks performed:

  • Presence of core Python libraries (numpy, ase, scipy, etc.).

  • Availability of the orca executable in the system `PATH.

  • Correct configuration of the ORCAVERSION environment variable.

  • Availability of Gaussian executables (g16 or g09).

2. Protocol Wizard (enan_protocol_wizard)

An interactive Text User Interface (TUI) to generate the protocol.json file. It guides the user through the creation of computational steps without needing to manually edit JSON files.

Usage

enan_protocol_wizard

Features:

  • Three Configuration Levels:

    • Basic: Essential parameters only.

    • Intermediate: Adds constraints and internal coordinate monitoring.

    • Advanced: Full control over energetic thresholds (thrG, thrB, etc.) and pruning settings.

  • Fuzzy Search: Quickly find functionals and basis sets from the internal database (for ORCA).

The basic and Intermediate levels allow to less-expert users to create from scratch a protocol file, using the default values of some configuration.

3. Spectra Regrapher (enan_regraph)

Regenerates spectral plots (IR, VCD, UV, ECD) without re-running the quantum calculations. This is useful when you want to adjust convolution parameters (FWHM, Shift) or change the plotting units (nm vs eV) after the main run.

Usage:

enan_regraph [protocol_ids ...] [options]

Arguments:

  • protocol_ids: (Required) List of protocol numbers to regraph (e.g., 0 1 2).

Options:

  • -rb, --read-boltz <int>: Use Boltzmann populations from a specific protocol step instead of recalculating them.

  • -no-nm: Do not save graphs with nanometer (nm) x-axis (saves only default units).

  • -w, --weight: Overlay the weighting function used for comparison on the plot.

  • --disable-color: Disable colored terminal output.

Example: Recalculate spectra for step 1 using new settings in settings.json:

enan_regraph 1

4. Average Energy Analyzer (enan_get_energies)

Calculates weighted average energies (E, H, G) for the ensemble at a specific temperature. It allows for thermodynamic recalculations (different T or P) and arithmetic operations between protocol steps.

Usage:

enan_get_energies [options]

Core Options:

  • -T, --temp <float>: Temperature in Kelvin for recalculation (default: 298.15 K).

  • -o, --output <file>: Output log filename.

  • --pressure <float>: Pressure in kPa (default: 101.325).

Thermo Parameters:

  • --cut-off <float>: qRRHO cut-off frequency in cm⁻¹ (default: 100.0).

  • --alpha <int>: qRRHO damping factor (default: 4).

  • --linear: Treat molecules as linear rigid rotors.

Math Operations:

  • --sub <p1> <p2>: Calculate difference Avg(Protocol 1) - Avg(Protocol 2).

  • --add <p1> <p2>: Calculate sum Avg(Protocol 1) + Avg(Protocol 2).

Example: Compare energies between protocol 2 and 1 at 310K:

enan_get_energies -T 310 --sub 2 1

5. Graph Editor (enan_graph_editor)

A tool to modify the appearance of the generated Matplotlib plots (saved as .pickle files). It supports both an interactive TUI and a batch mode for automated editing.

Usage:

enan_graph_editor <pickle_file> [options]

Interactive Mode (TUI)

Simply run without arguments to enter the interactive menu:

enan_graph_editor IR_comparison.pickle

Allows renaming labels, changing colors, line styles, widths, and transparency.

Batch Mode

Use the –batch flag to apply changes via command line arguments.

Options:

  • --list, -l: List current legend labels and exit.

  • --rename, -r <old> <new>: Rename a legend label.

  • --color, -c <label> <color> : Change line color.

  • --linestyle, -ls <label> <style>: Change line style (e.g., -, –, : ).

  • --format, -f: Output format (png, pdf, svg, pickle).

Example: Rename a protocol and change its color to red, saving as PNG:

enan_graph_editor IR_comparison.pickle --batch \
            --rename "Protocol 1" "B97-3c" \
            --color "B97-3c" "red" \
            --format png