Introduction¶
SCINE Heron is the graphical user interface for all other SCINE modules. It has six main ways of operation:
1) One can explore chemical reactivity immersively and interactively based on first principles in real-time. The graphical user interface of SCINE Heron displays a three-dimensional molecular structure and allows users to interact with it. They can induce structural changes with a computer mouse or a haptic device and perceive the effect of their manipulations immediately through visual and/or haptic feedback. For fast electronic structure calculations, we employ currently different semi-empirical methods, which can deliver properties in the millisecond timescale, while providing a qualitatively correct description of the potential energy surface.
2) One can construct a system-focused atomistic model (SFAM), i.e., a force field parametrized on Hessian calculations on the specific system. SFAM force fields can be employed in the interactive setting either as a stand-alone or in a hybrid QM/MM model. The hybrid model can also be constructed within the graphical user interface either by our automated QM region selection algorithm or by manual selection of the QM region by clicking on the QM atoms.
3) One can launch individual energy calculations and optimization routines, such as transition state searches, with any backend program supported in SCINE, in the ReaDuct tab. The input structures can be read-in from file or stem directly from Interactive or an explored reaction network.
4) One can automaticaly determine the active space for multi-configurational calculations with autoCAS. Based on orbital entanglement measures derived from an approximate DMRG wave function, autoCAS identifies all strongly correlated orbitals to be included in the active space of a final, converged calculation.
5) One can interact with explorations done by SCINE Chemoton. One can visualize the chemical reaction network without drowning in too much information. For example, one can selectively display reactions with a barrier lower than a certain, user-specified threshold. Furthermore, one can analyze all compounds and reactions discovered, e.g., for reactions, one can visualize the trajectory and study the energy along it. It is also possible to search and visualize all pathways between two given compounds. Any compound discovered by Chemoton can be transferred to the interactive part of the GUI, allowing it to be further studied.
6) One can carry out reaction explorations directly in the graphical user interface by either constructing individual Chemoton engines, or by relying on the Steering Wheel mechanism that lets one guide the automated exploration more closely. The exploration can be constrained by additional aggregate and reactive site filters that can also be constructed in the graphical user interface. Almost all of the exploration guidances in Heron support I/O operations which allow to save and reuse individual parts for other explorations or restarts.
License and Copyright Information¶
For license and copyright information, see the file LICENSE.txt in the source
directory.
Installation¶
Preliminary Remark¶
The application requires several third-party and SCINE Python packages to run. Due to the modular nature of SCINE, we do not enforce all individual modules to be installed in order to launch Heron. Depending on the installed software packages some features are available or missing. We provide easy installs for all possible combinations of requirements.
The hard requirements for Heron are:
SCINE Sparrow
SCINE ReaDuct
SCINE Utilities
The optional requirements are:
SCINE Chemoton
SCINE Database
SCINE Art
SCINE Molassembler
SCINE Swoose
SCINE autoCAS
Additional optional requirements are modules that add further backend programs to our framework, which are:
SCINE xtb_wrapper
SCINE serenity_wrapper
From PyPI¶
Heron can be installed from PyPI with the command:
pip install scine-heron
This will install only the hard requirements (see above), and hence only a minimal version of Heron will be available. To install all dependencies, run:
pip install scine-heron[all]
If you want to install only selected dependencies, you can run a command such as:
pip install scine-heron[autocas]
On PyPI, we also support any possible combination of optional dependencies combined with a + such as:
pip install scine-heron[autocas+chemoton]
From Source¶
Heron can be installed using pip (pip3) once the repository has been cloned:
git clone https://github.com/qcscine/heron.git
cd heron
pip install -r requirements.txt
pip install .
A non super user can install the package using a virtual environment, or the --user flag.
Only the hard requirements (see above) are included in requirements.txt. If all optional
requirements are wanted, one can install them after cloning with:
pip install -r requirements-all.txt
If one wants to install only certain optional requirements, one can install the specific requirements file such as:
pip install -r requirements-autocas.txt
Usage¶
Starting the Application¶
The application can be started by the command:
python3 -m scine_heron
To open a file with a molecule directly from the command line, you can use the --file option:
python3 -m scine_heron --file examples/xyz_files/pyridine.xyz
To specify a certain method family and/or program for interactive calculations directly from the command line, you can use the --method-family
and --program options:
python3 -m scine_heron --method-family DFTB3 --program Sparrow
Hybrid models can be specified by combining two method families and programs with a / character, such as:
python3 -m scine_heron --method-family DFTB3/SFAM --program Sparrow/Swoose
To specify a database connection directly from the command line, you can use the --name, --ip, and --port options
and optionally try to connect with the database upon launch with the --connect flag:
python3 -m scine_heron --name test_database --ip localhost --port 27017 --connect
The application is per default in dark mode. If light mode is preferred, you can use the --mode option:
python3 -m scine_heron --mode light
A summary of all command line arguments and short forms is given by:
python3 -m scine_heron --help
Shortcuts¶
The application features a range of shortcuts. The most important ones are given here.
- General:
Scrolling Vertically: Mouse Wheel
Scrolling Vertically: Shift + Mouse Wheel
Zooming: Ctrl + Mouse Wheel (in the main molecular viewer also without Ctrl modifier)
Open Database Connection Dialogue: Ctrl + D
Open Reaction Template database: Ctrl + T
- Main Molecular Viewer:
Open File: Ctrl + O
Save Molecule: Ctrl + S
Save Trajectory: Ctrl + Shift + S
Start Real Time Calculation: Ctrl + F (if calculator is available and molecule loaded)
Select multiple atoms: s + Right Click
Undo changes in the interactive setting: Ctrl + Z
Move the current structure to ReaDuct: Ctrl + R
- All Network Views:
Copy ID of Focussed Node: Ctrl + C
Existing shortcuts are usually given in the mouse-over tooltip of the particular buttons in Heron.
AutoCAS¶
In order to set up/analyze an AutoCAS project, the scine-autocas module must be installed, see prerequisites.
Since the autoCAS project is still under development, it could be that a newer version of autoCAS may break this
version of SCINE Heron.
In order to use the autoCAS GUI here, ensure that you use the exact autoCAS version v2.1.0.
In order to use autoCAS you need to have Molcas installed.
Please see the autoCAS readme for installation instructions.
Database and Chemoton¶
The SCINE Database and automated exploration with SCINE Chemoton is built around the general MongoDB database. MongoDB is a document-based database format, which allows one to store heterogeneous data. SCINE database defines a database schema and offers C++ and Python functionalities to query relevant information. To run a SCINE Database one first needs to install the MongoDB client, which is freely available and installable with most package managers. Detailled instructions are given in the MongoDB documentation.
Haptic Device¶
SCINE Heron supports the usage of a haptic device. It allows the user to feel force feedback when manipulating molecules in the main molecular viewer. In order to install and connect a haptic device to SCINE Heron please read the instructions and referenced manuals below.
Haptic Device Install¶
Connect your haptic device. Download drivers for it and install according to the instructions. Read the official webpage for more information.
Install OpenHaptics SDK. Read the Programmers Guide and API Reference Guide for more information.
Then install the scine_heron_haptic module (see the instructions in the haptics/ subfolder).
How to Cite¶
When publishing results obtained with Heron, please cite the corresponding release as archived on Zenodo (please use the DOI of the respective release) and the following paper:
C. H. Müller, M. Steiner, J. P. Unsleber, T. Weymuth, M. Bensberg, K.-S. Csizi, M. Mörchen, P. L. Türtscher, M. Reiher, “Heron: Visualizing and Controlling Chemical Reaction Explorations and Networks”, 2024, arXiv:2406.09541 [physics.chem-ph] (DOI: 10.48550/arXiv.2406.09541).
Specific features which are implemented in or accessible via Heron are described in their own papers. We kindly ask you to cite these papers when appropriate.
Additionally, we kindly request you to cite the corresponding software releases of the underlying SCINE modules as archived on Zenodo.
Furthermore, when publishing results obtained with any SCINE module, please cite the following paper:
T. Weymuth, J. P. Unsleber, P. L. Türtscher, M. Steiner, J.-G. Sobez, C. H. Müller, M. Mörchen, V. Klasovita, S. A. Grimmel, M. Eckhoff, K.-S. Csizi, F. Bosia, M. Bensberg, M. Reiher, “SCINE—Software for chemical interaction networks”, J. Chem. Phys., 2024, 160, 222501 (DOI 10.1063/5.0206974).
Known Issues¶
The selection of nuclei is broken for vtk>=9.1, we therefore encourage to stay with version 9.0. This version is not available for python>=3.9 on PyPI and requires a manual install.
Old versions of qt-material may cause overlapping text boxes for newer operating systems such as Ubuntu 22.04.
An install of PySide2 via PyPI may not be sufficient to have a working Qt installation depending on your system. In this case, it is recommend to first install PySide2 with a package manager (such as apt) before installing it with pip.
Some PySide2 packages might require additional installs related to pulseaudio such as libpulse-mainloop-glib0
The start of a steered exploration can become quite slow (~10 seconds) once the protocol gets large (> 20 steps) and issues can occur if you add a new step and immediately start the exploration or start the exploration and immediately click other buttons. Please do not click anything shortly after progressing the protocol. We hope to resolve this by the next release.
Support and Contact¶
In case you should encounter problems or bugs, please write a short message to scine@phys.chem.ethz.ch.