Release 1.0.0

.coveragerc

@@ -0,0 +1,14 @@
+[run]
+source =
+    scine_heron
+[report]
+omit =
+    */python?.?/*
+    */site-packages/nose/*
+    # ignore _version.py and versioneer.py
+    .*version.*
+    *_version.py
+    */tests/*
+
+exclude_lines =
+    if __name__ == '__main__':

.gitignore

@@ -0,0 +1,56 @@
+**/__pycache__
+openhaptics/build/
+openhaptics/scine_heron_haptic.*
+.hypothesis
+launch.sh
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# Distribution / packaging
+build/
+venv/
+*.egg-info/
+*.egg
+*whl
+
+# Unit test / coverage reports
+.coverage
+.coverage.*
+.cache
+coverage.xml
+pytest_report.xml
+htmlcov
+
+# Sphinx documentation
+docs/build/
+docs/source/generated/
+
+# pytest
+.pytest_cache/
+
+# Editor files
+#mac
+.DS_Store
+*~
+
+#vim
+*.swp
+*.swo
+
+#pycharm
+.idea/
+
+#VSCode
+.vscode/
+
+#conda
+spec-file.txt
+
+mongo*
+Wired*
+*.wt
+*.tar.gz
+*.bson

CHANGELOG.rst

@@ -0,0 +1,33 @@
+Changelog
+=========
+
+Release 1.0.0
+-------------
+
+Initial Features:
+^^^^^^^^^^^^^^^^^
+
+- Main Molecular Viewer
+    - Real-time calculations of energies and forces (using SCINE Sparrow)
+    - Haptic device support
+    - Real-time energy plot
+    - Basic molecular building/editing
+    - Isosurface plots of orbitals and densities
+- Reaction Network Viewer
+    - Excerpt view of Aggregates and Reactions
+    - Basic filtering options based on reaction energies
+    - Navigation around a single centered Aggregate
+    - (Shortest) path searches based on Aggregate IDs
+    - Expansion tab for Aggregates (showing contained Structures)
+    - Expansion tab for Reactions (showing contained Elementary Steps)
+    - SVG export of all graph views
+- SCINE Database Statistics
+    - Database content statistics
+    - Calculation status statistics
+    - Runtime histogram
+- SCINE Database Browser
+    - Listing, searching and displaying of individual database entries
+       - Reaction and Elementary Steps
+       - Compounds and single-molecule Structures
+       - Flasks and multi-molecule complexes (also Structures)
+

CONTRIBUTING.rst

@@ -0,0 +1,30 @@
+Contributing to SCINE Heron
+===========================
+
+Contribution Process
+--------------------
+
+The development for this code is done in a private repository maintained by the 
+Reiher Research Group. GitHub is only used for the official releases.
+
+If you would like to contribute a larger change, please write to scine@phys.chem.ethz.ch.
+For smaller changes, you can create a pull request on GitHub. If we agree with
+the changes, a member of the Reiher Research Group will include them in our
+development code. Of course, we will give proper acknowledgment for any external
+contribution (see below for a list of all contributors). As soon as these changes 
+are available in an official release, we will close the corresponding pull requests 
+and/or issues on GitHub.
+
+Please note that contributing a small change does in no way mean that you will
+be added to the author list of a future paper and/or Zenodo entry!
+
+Main Contributors
+-----------------
+
+Almost all contributions to SCINE in general and this repository in specific come 
+from members of the Reiher research group.
+
+Further Contributors
+--------------------
+
+So far, no one else has contributed to this repository.

LICENSE.txt

@@ -0,0 +1,26 @@
+Copyright ETH Zurich, Laboratory of Physical Chemistry, Reiher Group
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+this list of conditions and the following disclaimer in the documentation and/or
+other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its contributors
+may be used to endorse or promote products derived from this software without
+specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+OF THE POSSIBILITY OF SUCH DAMAGE.

MANIFEST.in

@@ -0,0 +1,12 @@
+include LICENSE
+include README.rst
+include CHANGELOG.rst
+include requirements.txt
+
+recursive-exclude * __pycache__
+recursive-exclude * *.py[co]
+
+include scine_heron/_version.py
+
+# If including data files in the package, add them like:
+include scine_heron/resources

README.rst

@@ -0,0 +1,138 @@
+.. image:: scine_heron/resources/heron_logo.png
+   :alt: SCINE Heron
+
+.. inclusion-marker-do-not-remove
+
+Introduction
+------------
+
+SCINE Heron is the graphical user interface for all other SCINE modules. It has two main ways of operation.
+
+First, one can explore chemical reactivity immersively and interactively based on first principles. 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.
+
+Second, 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.
+
+License and Copyright Information
+---------------------------------
+
+For license and copyright information, see the file ``LICENSE.txt`` in this
+directory.
+
+Installation
+------------
+
+Prerequisites
+.............
+
+The application requires several third-party and SCINE related Python packages to run.
+These packages can be installed using the following command::
+
+    pip install -r requirements.txt
+
+You may want to create and activate a virtual environment first.
+
+Additional third party packages are used for testing, type checking, and formatting.
+See ``requirements-dev.txt`` and pypi.org for more information.
+Again, the packages can be installed using::
+
+    pip install -r requirements-dev.txt
+
+
+Installation
+............
+
+Heron can be installed using pip (pip3) once the repository has been cloned:
+
+.. code-block:: bash
+
+   git clone <heron-repo>
+   pip install ./heron
+
+A non super user can install the package using a virtual environment, or
+the ``--user`` flag.
+
+Usage
+------
+
+Starting the Application
+........................
+
+The application can be started by the command::
+
+    python3 -m scine_heron
+
+To open a file with molecule directly from the command line, you can use the ``--file`` option::
+
+    python3 -m scine_heron --file examples/xyz_files/pyridine.xyz
+
+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
+
+
+Shortcuts
+.........
+
+The application features a range of shortcuts, a few 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
+
+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)
+
+All Network Views:
+  - Copy ID of Focussed Node: Ctrl + C
+
+
+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 <https://s3.amazonaws.com/dl.3dsystems.com/binaries/Sensable/Linux/TouchDriver2019_2_15_Linux.tar.xz>`_
+for it and install according to the `instructions <https://s3.amazonaws.com/dl.3dsystems.com/binaries/Sensable/Linux/Installation+Instructions.pdf>`_.
+Read the `official webpage <https://support.3dsystems.com/s/article/OpenHaptics-for-Linux-Developer-Edition-v34?language=en_US>`_ for more information.
+
+Install `OpenHaptics SDK <https://s3.amazonaws.com/dl.3dsystems.com/binaries/support/downloads/KB+Files/Open+Haptics/openhaptics_3.4-0-developer-edition-amd64.tar.gz>`_.
+Read the `Programmers Guide <https://s3.amazonaws.com/dl.3dsystems.com/binaries/support/downloads/KB+Files/Open+Haptics/OpenHaptics_ProgGuide.pdf>`_
+and `API Reference Guide <https://s3.amazonaws.com/dl.3dsystems.com/binaries/support/downloads/KB+Files/Open+Haptics/OpenHaptics_RefGuide.pdf>`_
+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 <https://zenodo.org>`_ (please use the DOI of
+the respective release).
+
+Support and Contact
+-------------------
+
+In case you should encounter problems or bugs, please write a short message
+to scine@phys.chem.ethz.ch.

conanfile.txt

@@ -0,0 +1,15 @@
+
+[requires]
+scine_utilities/[>=4.0.0]@
+scine_sparrow/[>=3.0.0]@
+scine_database/[>=1.0.0]@
+scine_molassembler/[>=1.2.0]@
+
+[options]
+scine_utilities:python=True
+scine_sparrow:python=True
+scine_database:python=True
+scine_molassembler:python=True
+
+[generators]
+virtualenv_python

examples/database/generate.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+# -*- coding: utf-8 -*-
+__copyright__ = """ This code is licensed under the 3-clause BSD license.
+Copyright ETH Zurich, Laboratory of Physical Chemistry, Reiher Group.
+See LICENSE.txt for details.
+"""
+import scine_database as db
+from scine_chemoton.tests import test_database_setup as db_setup
+
+"""
+This script generates a small 'fake' reaction network database
+on the 'localhost', with port 27017 and name 'many_reactions'.
+All structures in the database will be the same water molecule.
+The database generated is very shallow and unphysical.
+It is mainly used for unit tests and debugging purposes.
+"""
+
+if __name__ == '__main__':
+    n_compounds = 50
+    n_reactions = 3000
+    max_r_per_c = 300
+    max_n_products_per_r = 2
+    max_n_educts_per_r = 2
+    max_s_per_c = 1
+    max_steps_per_r = 1
+    barrier_limits = (0.1, 2000.0)
+    n_inserts = 1
+    n_flasks = 100
+    manager = db_setup.get_random_db(
+        n_compounds,
+        n_flasks,
+        n_reactions,
+        max_r_per_c,
+        "many_reactions",
+        max_n_products_per_r,
+        max_n_educts_per_r,
+        max_s_per_c,
+        max_steps_per_r,
+        barrier_limits,
+        n_inserts,
+    )
+