.. _user-guide-pyvisa: .. role:: header :class: h4 The |pyvisa| application ======================== .. raw:: html
Formic acid water-cluster structure used for ChemiTrees path analysis ChemiTrees decision tree generated from trajectory descriptors
ChemiTrees use PyVisA-style post-analysis to connect molecular trajectory descriptors to interpretable reaction-path rules. Source: Roet, Daub and Riccardi, J. Chem. Theory Comput. 17, 6193-6202 (2021).
H-NS binding to AT-rich DNA and hydrogen-bond descriptors PyVisA density-map plot for H-NS DNA-binding trajectories
H-NS binding to AT-rich DNA pairs structural descriptors with density-map views of the sampled path ensemble. Source: Riccardi et al., PLoS Comput. Biol. 15, e1006845 (2019), CC BY.
|pyvisa| is the analysis and visualization tool for |pyretis| simulations. It consists of two components: * A **compressor** that reads raw simulation output, checks consistency, and stores the data in ``pyvisa_compressed_data.hdf5.zip``. * A **visualizer** (GUI) that loads compressed or raw data and produces interactive plots, cluster analyses, and PCA results. The GUI has additional optional requirements, which must be installed separately (see :ref:`installation `). The compressor and recalculation tools can run without a graphical environment. This is useful on remote clusters and other machines where Qt or an X display is not available. A common workflow is to prepare the compact |pyvisa| data on the remote machine and inspect it later on a local workstation with the GUI. ChemiTrees and post-analysis ---------------------------- ChemiTrees are a post-analysis workflow for converting path-sampling trajectories into chemically interpretable decision trees. Instead of selecting a mechanism only by visual inspection, trajectory descriptors are classified into reactive and unreactive paths and the resulting tree identifies the geometric conditions that separate the two classes. In the |pyvisa| workflow this belongs after compression and, when needed, recalculation of order parameters or collective variables: create the compact HDF5 data set, add the descriptors that matter for the system, and then use the statistical-analysis routines to build decision-tree, clustering or PCA views of the trajectory ensemble. The current API entry point for the tree analysis is ``pyretis.pyvisa.statistical_methods.decision_tree``. The ChemiTrees publication is listed in :ref:`our-results`. The corresponding reproduction input files are not yet mirrored on this website; they should be added there once the original data package has been recovered. The general syntax is: .. code-block:: pyretis pyvisa [-h] [-i INPUT] [-V] [-cmp] [-data DATA] [-recalculate] [-oo] [-p] [-w N] where the arguments are described in :numref:`tableappargument_pyvisa`. Flags can be freely combined: ``-recalculate`` and ``-cmp`` may be given together to run recalculation followed by compression in one step. If neither is set, the GUI is launched. Choosing a workflow ------------------- The most common |pyvisa| workflows are: * **Remote or headless use:** run the compressor and, if needed, recalculation from the command line. This only writes files and does not open the GUI. * **Local GUI use:** install the GUI requirements and open either the compressed |pyvisa| file or the original simulation input file. * **Remote GUI use:** install the GUI requirements on the remote machine and run |pyvisa| through an environment that can show graphical applications, such as X11 forwarding or a remote desktop session. Remote or headless usage ------------------------ On a remote machine, first go to the completed simulation directory. This is the directory containing the original |pyretis| input file and the numbered ensemble folders such as ``000``, ``001``, and ``002``. To compress the simulation output without opening the GUI, run: .. code-block:: pyretis pyvisa -i retis.rst -cmp This creates ``pyvisa_compressed_data.hdf5.zip`` in the current directory. The original simulation output is not modified. If the remote machine should only package order parameter data, use: .. code-block:: pyretis pyvisa -i retis.rst -cmp -oo The ``-oo`` option skips the energy files and can be useful when only the order parameter and collective variable data are needed. To recalculate order parameters or collective variables after changing ``retis.rst`` or ``orderp.py``, run: .. code-block:: pyretis pyvisa -i retis.rst -recalculate The recalculation uses the trajectory files found in the simulation directory and writes updated ``order.txt`` data. To limit the recalculation to one trajectory file or a directory of trajectory files, use ``-data``: .. code-block:: pyretis pyvisa -i retis.rst -recalculate -data path/to/traj.xyz pyvisa -i retis.rst -recalculate -data path/to/trajectory_folder After recalculation, run the compressor again if you want a new compact file for transfer or later visualization: .. code-block:: pyretis pyvisa -i retis.rst -cmp The remote environment needs the Python packages required to read the trajectory files and execute the order parameter code used by the simulation. The GUI dependencies are only needed when a |pyvisa| window will be opened. Local GUI usage --------------- Copy the compressed file from the remote machine to a local workstation where the |pyvisa| GUI requirements are installed: .. code-block:: pyretis scp user@remote.host:/path/to/simulation/pyvisa_compressed_data.hdf5.zip . Then open it locally: .. code-block:: pyretis pyvisa -i pyvisa_compressed_data.hdf5.zip You can also open the GUI directly from a simulation directory: .. code-block:: pyretis pyvisa -i retis.rst or load a specific ensemble or data source: .. code-block:: pyretis pyvisa -i retis.rst -data 000 Direct remote GUI usage ----------------------- Direct remote GUI usage is possible when the remote environment can show graphical applications. Install the GUI requirements on the remote machine, connect with display forwarding or a remote desktop session, and run |pyvisa| from the simulation directory: .. code-block:: pyretis pyvisa -i retis.rst For large simulations this can be slower than the headless workflow, because the GUI must read the simulation data interactively over the remote session. Compressing remotely and opening the compressed file locally is usually the simpler workflow. Example use ----------- **Compressor** * Compress raw simulation output into ``pyvisa_compressed_data.hdf5.zip``: .. code-block:: pyretis pyvisa -i out.rst -cmp * Compress using only order parameter files (faster, smaller output): .. code-block:: pyretis pyvisa -i out.rst -cmp -oo **Recalculate** * Recalculate order parameters and collective variables: .. code-block:: pyretis pyvisa -i retis.rst -recalculate * Recalculate for a single ensemble only: .. code-block:: pyretis pyvisa -i retis.rst -recalculate -data 000 * Recalculate with a progress bar and 4 parallel workers: .. code-block:: pyretis pyvisa -i retis.rst -recalculate -p -w 4 **Combined flags** * Recalculate and then compress in one step: .. code-block:: pyretis pyvisa -i out.rst -recalculate -cmp * Recalculate a single ensemble, then compress with order files only: .. code-block:: pyretis pyvisa -i out.rst -recalculate -data 000 -cmp -oo **Visualization GUI** * Open the visualization GUI from a compressed file: .. code-block:: pyretis pyvisa -i pyvisa_compressed_data.hdf5.zip * Open the GUI from the original input file, loading a specific ensemble: .. code-block:: pyretis pyvisa -i out.rst -data 000 * Open the GUI loading all data with order files only (faster): .. code-block:: pyretis pyvisa -i out.rst -oo For a guided walkthrough of these features, see :ref:`examples-pyvisa` and :ref:`examples-pyvisa-analysis`. Input arguments --------------- .. _tableappargument_pyvisa: .. list-table:: Description of input arguments for |pyvisa|. :class: table-striped table-hover :header-rows: 1 :widths: 40 60 * - Argument - Description * - ``-h, --help`` - Show the help message and exit. * - ``-i INPUT, --input INPUT`` - Location of the input file (``.rst``, ``.hdf5``, or ``.hdf5.zip``). * - ``-V, --version`` - Show the version number and exit. * - ``-cmp, --pyvisa_compressor`` - Run the compressor tool to generate ``pyvisa_compressed_data.hdf5.zip`` from raw simulation output. * - ``-data DATA, --pyvisa-data DATA`` - Select a subset of data to load. Use ``all`` for all data, or a folder name (e.g. ``000``) for a single ensemble. * - ``-recalculate, --pyvisa-recalculate`` - Recalculate order parameter and collective variable data using the current ``orderp.py``. * - ``-oo, --only_order`` - Use only data from ``order.txt`` files when compressing (faster, skips energy data). * - ``-p, --progress`` - Show progress bars during recalculation. * - ``-w N, --workers N`` - Number of parallel worker processes for recalculation (default: all CPU cores). Visualisation and Analysis with PyVisA -------------------------------------- .. container:: row .. container:: col-lg-4 col-md-4 col-sm-4 col-xs-6 thumbnail thumbnail2 .. image:: /_static/img/examples/thumbnails/contour-400x400.png :width: 100% :class: img-responsive :target: ../examples/examples-pyvisa.html .. container:: caption :header:`PyVisA` Compress, inspect and visualise path-sampling trajectories from the tutorial suite. `Tutorial source `__ .. container:: col-lg-4 col-md-4 col-sm-4 col-xs-6 thumbnail thumbnail2 .. image:: /_static/img/examples/thumbnails/corr_mat.png :width: 100% :class: img-responsive :target: ../examples/examples-pyvisa-analysis.html .. container:: caption :header:`PyVisA analysis` Add collective variables, run PCA and cluster trajectories from the methane-hydrate example. `Tutorial source `__ .. container:: col-lg-4 col-md-4 col-sm-4 col-xs-6 thumbnail thumbnail2 .. image:: /_static/img/pyvisa/chemitree-formic-water.png :width: 100% :class: img-responsive :target: https://doi.org/10.1021/acs.jctc.1c00458 .. container:: caption :header:`ChemiTrees` Use decision-tree post-analysis to identify molecular descriptors that distinguish reactive and unreactive path-sampling trajectories. `Paper `__