...
 
Commits (762)
_build
_templates
# compiled python files
*.pyc
*.DS_Store
# sphinx build folder
_build
# OS generated files #
######################
.DS_Store?
ehthumbs.db
Icon?
Thumbs.db
# Editor backup files #
#######################
*~
image: umbrellium/sphinx-doc
image: cloudcompass/docker-rtdsphinx
spelling:
script:
- pip3 install codespell
- codespell --skip=".git,_static,_build,Diff*,*.patch,*.f90" --quiet-level=2 --ignore-words-list="adress,catalogue,noe"
only:
- master
- merge_requests
orphans:
script:
# Report all the orphans but ignore the exit code
- find ./ -name "*.rst"|xargs -i grep -H orphan {} || true
# Now handle the error code
- if [ $(find ./ -name "*.rst"|xargs -i grep -H orphan {}|wc -l) -gt "2" ]; then $(exit 1); else $(exit 0); fi
only:
- master
pages:
script:
- apt-get update
- apt-get -y install dvipng
- pip3 install pygments --upgrade
- pip3 install Sphinx --upgrade
- pip3 install sphinx-rtd-theme --upgrade
- READTHEDOCS=True sphinx-build -nWT -b html . _build/html
- mv _build/html/ public/
- echo -e "\n\n\e[1mYou can find your build of this documentation at \n\t\e[32m${CI_PAGES_URL}\e[0m\n\n"
artifacts:
paths:
- public
only:
- master
- merge_requests
Add a brief description briefly here (which replaces this sentence), a line or two is usually enough.
## Module verification checklist (for reviewers)
*Checklist when the module is first submitted*
- [ ] Have the relevant labels been added to the MR
- [ ] If submitted on someone elses behalf, has the software author been referenced (if they have a GitLab account)
*Checklist when module is no longer "WIP"*
- [ ] Is the module documentation sufficiently detailed?
- [ ] Is it mergeable? (i.e., there should be no merge conflicts)
- [ ] Are the build instructions sufficient - source code locations, build instructions, etc.? (If not the MR should be updated)
- [ ] Did it pass the tests that were described? (Are there unit/regression tests? Do they pass?)
- [ ] Are the tests sufficient?
- [ ] If the module introduces new functionality, is it tested? (Unit/regression tests?)
- [ ] Is the associated source code well formatted? (typos, line length, brackets,...it should be consistent with existing source)
- [ ] Is all new source code sufficiently documented? (functions, their arguments,...)
- [ ] Is there a description of any applications the module has? (This is a hard requirement for E-CAM PDRAs)
*After Merging*
- [ ] Make sure the module appears in a toctree
- [ ] Add a link to the final result on https://e-cam.readthedocs.io
......@@ -3,6 +3,13 @@
You can adapt this file completely to your liking, but it should at least
contain the root `toctree` directive.
.. sidebar:: General Information
.. contents:: :depth: 2
* :ref:`contributing`
* :ref:`search`
.. _readme_classical_md:
********************
......@@ -12,13 +19,6 @@ Classical MD Modules
Introduction
============
.. sidebar:: General Information
.. contents:: :depth: 2
* :ref:`contributing`
* :ref:`search`
.. image:: ./images/lipid.jpg
:width: 15 %
:align: left
......@@ -148,14 +148,14 @@ to enumerate -- both academics and industry will benefit greatly from having
software for these methods.
The modules listed here deal with software to perform path sampling methods,
as well as other approaches to rare events.
as well as other approaches to rare events.
OpenPathSampling
================
Several modules were developed based on
`OpenPathSampling (OPS) <http://openpathsampling.org>`_. These include modules
that have been incorporated into the core of OPS, as well as some that remain
Several modules were developed based on
`OpenPathSampling (OPS) <http://openpathsampling.org>`_. These include modules
that have been incorporated into the core of OPS, as well as some that remain
separate projects. The modules that were incorporated into the core are:
.. toctree::
......@@ -173,19 +173,26 @@ separate projects. The modules that were incorporated into the core are:
./modules/OpenPathSampling/ops_channel_analysis/readme
./modules/OpenPathSampling/ops_new_tis_analysis/readme
./modules/OpenPathSampling/ops_resampling_statistics/readme
./modules/OpenPathSampling/ops_gromacs_engine/readme
./modules/OpenPathSampling/ops_visit_all_states/readme
./modules/OpenPathSampling/ops_interface_shooting/readme
The modules that are based on OPS, but remain separate, are:
.. toctree::
:glob:
:maxdepth: 1
./modules/annotated_trajectories/readme
./modules/ops_piggybacker/readme
./modules/contact_maps/readme
./modules/contact_maps_parallelization/readme
./modules/dw_dimer_testsystem/readme
./modules/lammps_ops/readme
Nine of these modules were part of
Nine of these modules were part of
`E-CAM Deliverable 1.2 <https://www.e-cam2020.eu/deliverables/>`_. Those modules
provided improvements and new features in software for trajectory sampling and
provided improvements and new features in software for trajectory sampling and
for studying the thermodynamics and kinetics of rare events.
Pilot Projects
......@@ -208,14 +215,17 @@ The following modules were developed specifically for the Classical MD pilot pro
:maxdepth: 1
./modules/contact_maps/readme
./modules/contact_maps_parallelization/readme
./modules/contact_maps_parallelization/readme
./modules/contact_concurrences/readme
./modules/PIcore/readme
./modules/PIhydration/readme
Extended Software Development Workshops (ESDWs)
===============================================
The first ESDW for the Classical MD workpackage was held in Traunkirchen,
Austria, in November 2016, with a follow-up to be held in Vienna in April 2017.
The first ESDW for the Classical MD workpackage was held in Traunkirchen,
Austria, in November 2016, with a follow-up to be held in Vienna in April 2017.
The following modules have been produced:
.. toctree::
......@@ -227,7 +237,7 @@ The following modules have been produced:
./modules/OpenPathSampling/ops_maxlikelihood/readme
./modules/OpenPathSampling/ops_interface_optimization/readme
The second ESDW for the Classical MD workpackage was held in Leiden, Holland, in
The second ESDW for the Classical MD workpackage was held in Leiden, Holland, in
August 2017. The following modules have been produced:
.. toctree::
......@@ -238,5 +248,16 @@ August 2017. The following modules have been produced:
./modules/OpenPathSampling/ops_sr_shooter/readme
./modules/OpenPathSampling/ops_web_throwing/readme
./modules/OpenPathSampling/ops_plumed_wrapper/readme
./modules/OpenPathSampling/ops_s_shooting/readme
The third ESDW for the Classical MD workpackage was held in Turin, Italy in July
2018. The following have been produced as a result:
.. toctree::
:glob:
:maxdepth: 1
./modules/HTC/decorators/readme
./modules/pyscal/readme
.. _E-CAM: https://www.e-cam2020.eu/
.. In ReStructured Text (ReST) indentation and spacing are very important (it is how ReST knows what to do with your
document). For ReST to understand what you intend and to render it correctly please to keep the structure of this
template. Make sure that any time you use ReST syntax (such as for ".. sidebar::" below), it needs to be preceded
and followed by white space (if you see warnings when this file is built they this is a common origin for problems).
.. Firstly, let's add technical info as a sidebar and allow text below to wrap around it. This list is a work in
progress, please help us improve it. We use *definition lists* of ReST_ to make this readable.
.. sidebar:: Software Technical Information
Name
``jobqueue_features``
Language
Python
Licence
`MIT <https://opensource.org/licenses/mit-license>`_
Documentation Tool
In-source documentation
Application Documentation
Not currently available.. Example usage provided.
Relevant Training Material
Not currently available.
Software Module Developed by
Adam Włodarczyk (Wrocław Centre of Networking and Supercomputing),
Alan O'Cais (Juelich Supercomputing Centre)
.. In the next line you have the name of how this module will be referenced in the main documentation (which you can
reference, in this case, as ":ref:`example`"). You *MUST* change the reference below from "example" to something
unique otherwise you will cause cross-referencing errors. The reference must come right before the heading for the
reference to work (so don't insert a comment between).
.. _htc:
#######################################
E-CAM High Throughput Computing Library
#######################################
.. Let's add a local table of contents to help people navigate the page
.. contents:: :local:
.. Add an abstract for a *general* audience here. Write a few lines that explains the "helicopter view" of why you are
creating this module. For example, you might say that "This module is a stepping stone to incorporating XXXX effects
into YYYY process, which in turn should allow ZZZZ to be simulated. If successful, this could make it possible to
produce compound AAAA while avoiding expensive process BBBB and CCCC."
E-CAM is interested in the challenge
of bridging timescales. To study molecular dynamics with atomistic detail, timesteps must be used on
the order of a femtosecond. Many problems in biological chemistry, materials science, and other
fields involve events that only spontaneously occur after a millisecond or longer (for example,
biomolecular conformational changes, or nucleation processes). That means that around :math:`10^{12}` time
steps would be needed to see a single millisecond-scale event. This is the problem of "rare
events" in theoretical and computational chemistry.
Modern supercomputers are beginning to make it
possible to obtain trajectories long enough to observe some of these processes, but to fully
characterize a transition with proper statistics, many examples are needed. In order to obtain many
examples the same application must be run many thousands of times with varying inputs. To manage
this kind of computation a task scheduling high throughput computing (HTC) library is needed. The main elements of mentioned
scheduling library are: task definition, task scheduling and task execution.
While traditionally an HTC workload is looked down upon in the HPC
space, the scientific use case for extreme-scale resources exists and algorithms that require a
coordinated approach make efficient libraries that implement
this approach increasingly important in the HPC space. The 5 Petaflop booster technology of `JURECA <http://www.fz-juelich.de/ias/jsc/EN/Expertise/Supercomputers/JURECA/JURECA_node.html>`_
is an interesting concept with respect to this approach since the offloading approach of heavy
computation marries perfectly to the concept outlined here.
Purpose of Module
_________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
This module is the first in a sequence that will form the overall capabilities of the library. In particular this module
deals with creating a set of decorators to wrap around the `Dask-Jobqueue <https://jobqueue.dask.org/en/latest/>`_
Python library, which aspires to make the development time cost of leveraging it lower for our use cases.
Background Information
______________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
The initial motivation for this library is driven by the ensemble-type calculations that are required in many scientific
fields, and in particular in the materials science domain in which the E-CAM Centre of Excellence operates. The scope
for parallelisation is best contextualised by the `Dask <https://dask.org/>`_ documentation:
A common approach to parallel execution in user-space is task scheduling. In task scheduling we break our program
into many medium-sized tasks or units of computation, often a function call on a non-trivial amount of data. We
represent these tasks as nodes in a graph with edges between nodes if one task depends on data produced by another.
We call upon a task scheduler to execute this graph in a way that respects these data dependencies and leverages
parallelism where possible, multiple independent tasks can be run simultaneously.
Many solutions exist. This is a common approach in parallel execution frameworks. Often task scheduling logic hides
within other larger frameworks (Luigi, Storm, Spark, IPython Parallel, and so on) and so is often reinvented.
Dask is a specification that encodes task schedules with minimal incidental complexity using terms common to all
Python projects, namely dicts, tuples, and callables. Ideally this minimum solution is easy to adopt and understand
by a broad community.
While we were attracted by this approach, Dask did not support *task-level* parallelisation (in particular
multi-node tasks). We researched other options (including Celery, PyCOMPSs, IPyParallel and others) and organised a
workshop that explored some of these (see https://www.cecam.org/workshop-0-1650.html for further details).
Building and Testing
____________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
The library is a Python module and can be installed with
::
python setup.py install
More details about how to install a Python package can be found at, for example, `Install Python packages on the
research computing systems at IU <https://kb.iu.edu/d/acey>`_
To run the tests for the decorators within the library, you need the ``pytest`` Python package. You can run all the
relevant tests from the ``jobqueue_features`` directory with
::
pytest tests/test_decorators.py
Examples of usage can be found in the ``examples`` directory.
Source Code
___________
The latest version of the library is available on the `jobqueue_features GitHub repository
<https://github.com/E-CAM/jobqueue_features>`_, the file specific to this module
is `decorators.py <https://github.com/E-CAM/jobqueue_features/blob/master/jobqueue_features/decorators.py>`_.
(The code that was originally created for this module can be seen in the specific commit `4590a0e427112f
<https://gitlab.e-cam2020.eu/adam/jobqueue_features/tree/4590a0e427112fbf51edff6116e34c90e765baf0>`_
which can be found in the original private repository of the code.)
.. _ops_gromacs_engine:
##################################
Gromacs engine in OpenPathSampling
##################################
.. sidebar:: Software Technical Information
The information in this section describes OpenPathSampling as a whole.
Information specific to the additions in this module are in subsequent
sections.
Language
Python (2.7, 3.6, 3.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
Application Documentation
http://openpathsampling.org
Relevant Training Material
http://openpathsampling.org/latest/examples/
Licence
LGPL, v. 2.1 or later
Authors
David W.H. Swenson
.. contents:: :local:
This module adds support for Gromacs as an engine for OpenPathSampling.
Purpose of Module
_________________
.. Give a brief overview of why the module is/was being created.
Different molecular dynamics (MD) codes have developed to serve different
communities. Gromacs is one of the major MD codes for the biomolecular
community, and even though much of its functionality can be reproduced by
other MD codes, such as OpenMM, there are still some extensions that are
built on top of Gromacs that haven't been ported to other codes. For
example, the MARTINI coarse-grained model is not available other codes such
as OpenMM.
Additionally, people who are familiar with a given MD package will prefer to
continue to work with that. Therefore codes that wrap around MD packages, as
OpenPathSampling does, can expand their reach by adding ways to interface
with other MD packages.
This module adds the Gromacs engine for OpenPathSampling. It is the first
practical test of the external engine API of OPS.
Specific functionality in this module includes:
* ``GromacsEngine``: the OPS dynamics engine, based on the
``ExternalEngine``, that runs Gromacs as an external tool. Option on
initialization allow the user to customize the path to the Gromacs
executable.
* ``ExternalMDSnapshot``: an OPS snapshot for external MD engines, which
contains coordinates, velocities, and box vectors. Requires that the
engine implement a ``read_frame_data`` method to load from a specific MD
trajectory.
* ``snapshot_from_gro``: a function that creates an OPS snapshot from a
Gromacs ``.gro`` file.
Background Information
______________________
This module builds on OpenPathSampling, a Python package for path sampling
simulations. To learn more about OpenPathSampling, you might be interested in
reading:
* OPS documentation: http://openpathsampling.org
* OPS source code: http://github.com/openpathsampling/openpathsampling
Testing
_______
.. IF YOUR MODULE IS IN OPS CORE:
.. This module has been included in the OpenPathSampling core. Its tests can
.. be run by setting up a developer install of OpenPathSampling and running
.. the command ``py.test`` from the root directory of the repository.
This module is in a development branch of OpenPathSampling. If you have
conda installed, this branch of OPS can be installed by downloading the
``conda_ops_dev_install.sh`` script and running it with the command:
.. code:: bash
source conda_ops_dev_install.sh dwhswenson gromacs_engine
This will download a new copy of the OPS git repository, select the
``gromacs_engine`` branch from the ``dwhswenson`` fork, install the
requirements, and create an editable install of OPS. If you would like to do
this in a new conda environment, set the environment variable ``OPS_ENV``,
and it will install in a new environment with the name ``$OPS_ENV``.
To run tests, you may need ``pytest``, which can be installed with ``conda
install pytest``.
The entire OPS test suite can be run with run with ``py.test --pyargs
openpathsampling``. Tests specific to the Gromacs engine can be run with
``py.test --pyargs openpathsampling.tests.test_gromacs_engine``.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
.. The tests for this module can be run by downloading its source code,
.. installing its requirements, and running the command ``nosetests`` from the
.. root directory of the repository.
Examples
________
* An example can be found here: https://github.com/dwhswenson/openpathsampling/tree/gromacs_engine/examples/gromacs
Source Code
___________
.. link the source code
.. IF YOUR MODULE IS IN OPS CORE
.. This module has been merged into OpenPathSampling. It is composed of the
.. following pull requests:
This module is contained in the following pull request:
* https://github.com/openpathsampling/openpathsampling/pull/819
.. IF YOUR MODULE IS A SEPARATE REPOSITORY
.. The source code for this module can be found in: URL.
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
.. _ops_interface_shooting:
##################################################
Interface-Constrained Shooting in OpenPathSampling
##################################################
.. sidebar:: Software Technical Information
The information in this section describes OpenPathSampling as a whole.
Information specific to the additions in this module are in subsequent
sections.
Language
Python
Documentation Tool
Sphinx, numpydoc format (ReST)
Application Documentation
http://openpathsampling.org
Relevant Training Material
http://openpathsampling.org/latest/examples/
Licence
LGPL, v. 2.1 or later
Software module developed by
Peter G. Bolhuis and David W.H. Swenson
.. contents:: :local:
This module adds interface-constrained shooting to OpenPathSampling.
Interface-constrained shooting is a technique that can improve the
efficiency of transition interface sampling.
Purpose of Module
_________________
In transition interface sampling (TIS), one defines stable states (volumes in
phase space) and interfaces (surfaces in phase space). For a trajectory to
be accepted in TIS, it must begin with exactly one frame in a given initial
state, cross the interface, and end with exactly one frame in any state
volume (including the initial state).
New trajectories are generated with the shooting move, which selects a point
along an initial trajectory from which new frames can be made. In one-way
shooting, the dynamics only needs to run in one direction (with the
stochastic nature of the dynamics ensuring that a new trajectory is
generated).
However, if the interfaces are far from the initial state and if all frames
are equally likely to be used for shooting, it can be very likely for the
shooting point to come before the trajectory has crossed the interface. This
can then lead to shooting moves that usually generate trajectories that
don't cross the interface, and therefore must be rejected. This uses a lot
of simulation effort without generating useful new trajectories.
Interface-constrained shooting (also called "constrained interface
shooting") [1]_ is an approach to solve this problem. Instead of selecting
from anywhere along the trajectory, only the first point after crossing the
interface is allowed as a shooting point. This ensures that every
trajectory that is generated will be valid (will cross the interface). In
addition, because the first crossing is still the first crossing in the new
trajectory, this leads to the Metropolis acceptance probability also being
1. Therefore, every trial trajectory is accepted.
In practice, this must be combined with the path reversal move in order to
sample all of trajectory space. The result is an approach with very high
acceptance, although decorrelation of the trajectory is a little slower.
This module implements interface-constrained shooting using:
* ``ForwardShootingStrategy``: An OPS ``MoveStrategy`` to do forward-only
shooting. The interface-constrained shooting approach uses forward-only
stochastic dynamics, counting on path reversal to handle the backward-time
dynamics.
* ``InterfaceConstrainedSelector``: A ``ShootingPointSelector`` that selects
the first point outside the given volume (the boundary of which defines
the interface).
.. [1] Bolhuis, P. G. (2008). Rare events via multiple reaction channels
sampled by path replica exchange. The Journal of Chemical Physics,
129(11), 114108. https://doi.org/10.1063/1.2976011
Background Information
______________________
This module builds on OpenPathSampling, a Python package for path sampling
simulations. To learn more about OpenPathSampling, you might be interested in
reading:
* OPS documentation: http://openpathsampling.org
* OPS source code: http://github.com/openpathsampling/openpathsampling
Testing
_______
Tests in OpenPathSampling use `pytest`_.
.. IF YOUR MODULE IS IN OPS CORE:
This module has been included in the OpenPathSampling core. Its tests can
be run by installing pytest and OPS (with commit ``c340818``, which will be
part of release 0.9.6 and later), and running the command ``py.test
--pyargs openpathsampling``.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
.. The tests for this module can be run by downloading its source code,
.. installing its requirements, and running the command ``py.test`` from the
.. root directory of the repository.
Examples
________
An example of this is in the following notebook:
* https://github.com/openpathsampling/openpathsampling/blob/7e157661dd8633690ebfcae4a8265fc14e31c5b9/examples/toy_model_mstis/toy_mstis_A4_constrained_shooting.ipynb
Source Code
___________
.. link the source code
.. IF YOUR MODULE IS IN OPS CORE
This module has been merged into OpenPathSampling. It is composed of the
following pull requests:
* https://github.com/openpathsampling/openpathsampling/pull/788
* https://github.com/openpathsampling/openpathsampling/pull/790
* https://github.com/openpathsampling/openpathsampling/pull/800
.. IF YOUR MODULE IS A SEPARATE REPOSITORY
.. The source code for this module can be found in: URL.
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _pytest: http://pytest.org/
......@@ -25,9 +25,10 @@ OPS-based modules
Licence
LGPL, v. 2.1 or later
.. contents:: :local:
Software module developed by
YOUR NAME(S) HERE
Authors: Alan O'Cais
.. contents:: :local:
This is the template for an E-CAM *module* based on OpenPathSampling (OPS). Several
sections are already pre-filled with the details of OPS. Please fill out the
......@@ -66,18 +67,19 @@ reading:
Testing
_______
Tests in OpenPathSampling use the `nose`_ package.
Tests in OpenPathSampling use `pytest`_.
.. IF YOUR MODULE IS IN OPS CORE:
.. This module has been included in the OpenPathSampling core. Its tests can
.. be run by setting up a developer install of OpenPathSampling and running
.. the command ``nosetests`` from the root directory of the repository.
.. be run by installing pytest and OPS (with commit ????????, which will be
.. part of release ??? and later), and running the command ``py.test
.. --pyargs openpathsampling``.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
.. The tests for this module can be run by downloading its source code,
.. installing its requirements, and running the command ``nosetests`` from the
.. installing its requirements, and running the command ``py.test`` from the
.. root directory of the repository.
Examples
......@@ -105,5 +107,5 @@ ___________
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
.. _pytest: http://pytest.org/
......@@ -99,7 +99,7 @@ This module supports (as listed in PLUMED documentation):
``UNITS``).
* CV Documentation: all CVs are created by calling ``PLUMEDCV(name,
PLUMEDInterface, definition)``. The returned function can be appied
PLUMEDInterface, definition)``. The returned function can be applied
to a ``Trajectory``. CVs with components should specify the
``components=["c1", "c2", "c3", ...]`` keyword and the corresponding
PLUMED keywords in the ``definition``.
......
.. _ost_s_shooting:
##############################
S-shooting in OpenPathSampling
##############################
.. sidebar:: Software Technical Information
The information in this section describes OpenPathSampling as a whole.
Information specific to the additions in this module are in subsequent
sections.
Language
Python (2.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
Application Documentation
http://openpathsampling.org
Relevant Training Material
http://openpathsampling.org/latest/examples/
Licence
LGPL, v. 2.1 or later
.. contents:: :local:
Authors: Andreas Singraber
This module implements the S-shooting method [1]_ in OpenPathSampling.
Purpose of Module
_________________
S-shooting [1]_ is a recently developed method to determine rate constants of
rare events. It is similar in spirit to the reactive flux method but its
relaxed requirements help to overcome practical problems. The method is based
on a simple shooting algorithm where trajectories are propagated forward and
backward in time for a fixed number of timesteps. The starting points need to
be provided and must lie in the saddle point region. This so-called S region
(hence the name S-shooting) is defined via a suitable reaction coordinate and
must to separate the stable states A and B in such a way that no trajectory can
connect A with B without visiting S. In contrast to the reactive flux method
the time derivative of the reaction coordinate is not required, which makes
this approach applicable to systems exhibiting diffusive dynamics along the
reaction coordinate. The S-shooting method can also be applied if the initial
shooting points are taken from a biased simulation. Thus, it is a natural
follow-up to free energy calculations like umbrella sampling and, in
combination with free energy curves, allows the computation of rate constants.
The implementation of the S-shooting method in OpenPathSampling (OPS) is split
into two main parts:
- Forward and backward trajectories started from initial snapshots are
harvested and glued together calling the ``SShootingSimulation`` class. The
user needs to provide the initial snapshots, a suitable definition of the
S region and the desired trajectory length.
- The S-shooting analysis is performed upon calling the ``SShootingAnalysis``
class. Mandatory arguments include the definition of the stable states (A and
B) and of the S region. In case the initial snapshots are taken from a biased
simulation a bias function may be provided as an optional argument.
This module comes also with an IPython example notebook demonstrating the
method by applying it to a one-dimensional system (a brownian walker in a
double-well potential).
.. [1] Menzl, G., Singraber, A. & Dellago, C. S-shooting: a Bennett–Chandler-like method for the computation of rate constants from committor trajectories. Faraday Discuss. 195, 345–364 (2017), https://doi.org/10.1039/C6FD00124F
Background Information
______________________
This module builds on OpenPathSampling, a Python package for path sampling
simulations. To learn more about OpenPathSampling, you might be interested in
reading:
* OPS documentation: http://openpathsampling.org
* OPS source code: http://github.com/openpathsampling/openpathsampling
Testing
_______
Follow these steps to test the module:
1. Download and install OpenPathSampling (see http://openpathsampling.org/latest/install.html).
.. caution::
This module has been developed alongside a specific OPS version available at
that time. If incompatibilities arise as OPS is further enhanced, please use
version 0.9.5 available here:
https://github.com/openpathsampling/openpathsampling/releases/tag/v0.9.5 .
2. Install the `nose`_ package.
3. Download the source files of the module (see the `Source Code`_ section below).
4. Install the module: change to the ``S-Shooting`` directory and run ``python setup.py install``.
5. Run the tests: execute ``nosetests`` in the ``S-Shooting`` directory.
.. IF YOUR MODULE IS IN OPS CORE:
.. This module has been included in the OpenPathSampling core. Its tests can
.. be run by setting up a developer install of OpenPathSampling and running
.. the command ``nosetests`` from the root directory of the repository.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
.. The tests for this module can be run by downloading its source code,
.. installing its requirements, and running the command ``nosetests`` from the
.. root directory of the repository.
Examples
________
See the ``sshooting-example.ipynb`` IPython notebook in the source directory, here is the direct link: https://gitlab.e-cam2020.eu/singraber/S-Shooting/blob/master/ops_s_shooting/sshooting-example.ipynb
To run the example execute ``jupyter notebook sshooting-example.ipynb`` in your terminal.
Source Code
___________
.. link the source code
.. IF YOUR MODULE IS IN OPS CORE
.. This module has been merged into OpenPathSampling. It is composed of the
.. following pull requests:
.. * link PRs
.. IF YOUR MODULE IS A SEPARATE REPOSITORY
.. The source code for this module can be found in: URL.
The source code for this module is located here:
https://gitlab.e-cam2020.eu/singraber/S-Shooting
.. tip::
Ultimately, this module will be merged into the official OPS code. Check
the status of the corresponding pull request here:
https://github.com/openpathsampling/openpathsampling/pull/787 .
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
......@@ -11,7 +11,7 @@ Spring Shooting in OpenPathSampling
sections.
Language
Python (2.7, 3.5, 3.6)
Python (2.7, 3.6, 3.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
......@@ -127,7 +127,7 @@ reading:
Testing
_______
Tests in OpenPathSampling use the `nose`_ package.
.. Tests in OpenPathSampling use the `nose`_ package.
.. IF YOUR MODULE IS IN OPS CORE:
......@@ -140,8 +140,8 @@ Tests in OpenPathSampling use the `nose`_ package.
The tests for this module can be run by downloading its source code (see the
``Source Code`` section below), installing its requirements and installing it
by running ``python setup.py install`` from the root directory of the package.
Test this module by running the command ``nosetests`` from the root directory of the
repository.
Test this module with the `nose`_ package, by running the command ``nosetests``
from the root directory of the repository.
Examples
________
......
......@@ -70,7 +70,7 @@ ________
| There are two `example jupyter notebooks <https://gitlab.e-cam2020.eu/hejung/sr_shooter/tree/master/examples>`_ in the example directory of the repository:
| One shows the `general setup of a two way shooting transition path sampling with a shooting range on a toy system <https://gitlab.e-cam2020.eu/hejung/sr_shooter/blob/master/examples/toy_example.ipynb>`_.
| The other is a `comparison between one way shooting and two way shooting from the shooting range <https://gitlab.e-cam2020.eu/hejung/sr_shooter/blob/master/examples/OneWayShooting_vs_TwoWayShooting.ipynb>`_ and shows that path space is explored faster with two way shooting when using a (well placed) shooting range. The reason beeing that the shots initiated at the barrier top have a high probability of success and two way shooting decorrelates faster (if using randomized velocities even faster).
| The other is a `comparison between one way shooting and two way shooting from the shooting range <https://gitlab.e-cam2020.eu/hejung/sr_shooter/blob/master/examples/OneWayShooting_vs_TwoWayShooting.ipynb>`_ and shows that path space is explored faster with two way shooting when using a (well placed) shooting range. The reason being that the shots initiated at the barrier top have a high probability of success and two way shooting decorrelates faster (if using randomized velocities even faster).
Source Code
___________
......
......@@ -11,7 +11,7 @@ Transition State Ensemble in OpenPathSampling
sections.
Language
Python (2.7)
Python (3.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
......@@ -49,7 +49,7 @@ This module tries to efficiently find a single transition state frame from each
trajectory. This is done by bisection of the trajectory, depending on the
current committor. For example, if the current committor is to high (to much
ends up in state B) the next index is selected halfway towards the left edge
and the current index is set as the new right edge. This is repeated untill a
and the current index is set as the new right edge. This is repeated until a
committor within a given range is reached or no new frame can be selected.
In the end this module returns a dictionary of shape ``{snapshot: comittor
......
.. _ops_visit_all_states:
#############################
OPS Visit All States Ensemble
#############################
.. sidebar:: Software Technical Information
The information in this section describes OpenPathSampling as a whole.
Information specific to the additions in this module are in subsequent
sections.
Language
Python (2.7, 3.6, 3.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
Application Documentation
http://openpathsampling.org
Relevant Training Material
http://openpathsampling.org/latest/examples/
Licence
LGPL, v. 2.1 or later
Software module developed by
David W.H. Swenson
.. contents:: :local:
This module adds a convenient new OpenPathSampling ensemble that allows
trajectories to continue until they have visited all the states in the
system. In addition, it provides real-time reporting about the progress.
Purpose of Module
_________________
.. Give a brief overview of why the module is/was being created.
One of the ways to get initial trajectories for path sampling is to use
dynamics that aren't physical for the ensemble of interest, such as using an
increased temperature. If a trajectory has a frame in every state, then it
must have subtrajectories that connect from each state to another one, and
therefore it has all the information to start a MSTIS simulation. The
ensemble definition tools in OPS make it easy to create such custom
sequential ensembles [1]_.
However, users often want to do simulation setup in an interactive mode,
such as in a Jupyter notebook, or at a minimum want to have a sense of the
progress made on a long trajectory such as this. The default OPS ensemble
gives no output and therefore no sense of how much progress has been made.
This module provides a custom OPS ensemble that gives such output during its
simulation. It outputs the length of the trajectory so far, as well as the
states that have and have not already been visited. This gives a much better
sense of how long the simulation will take to run.
This module includes:
* ``default_state_progress_report``: A function to create the progress
report string. This can be replaced by another function to customize the
output.
* ``VisitAllStatesEnsemble``: A class that wraps an OPS
``SequentialEnsemble``. The ``can_append`` method, called while generating
the dynamics, can output information about the progress. The behavior of
this output can be set with the initialization variable ``progress``,
which can take the values of ``default`` for the default output,
``silent`` for no output, or can take a 2-tuple of callables where the
first determines what to write, and the second determined how to emit the
information.
.. [1] D.W.H. Swenson, J.-H. Prinz, F. Noe, J.D. Chodera, and P.G. Bolhuis.
J. Chem. Theory Comput. **15**, 837 (2019);
http://doi.org/10.1021/acs.jctc.8b00627
Background Information
______________________
This module builds on OpenPathSampling, a Python package for path sampling
simulations. To learn more about OpenPathSampling, you might be interested in
reading:
* OPS documentation: http://openpathsampling.org
* OPS source code: http://github.com/openpathsampling/openpathsampling
Testing
_______
Tests in OpenPathSampling use `pytest`_.
.. IF YOUR MODULE IS IN OPS CORE:
This module has been included in the OpenPathSampling core. Its tests can
be run by installing pytest and OPS (with commit 8e767872, which will be
part of release 1.0 and later), and running the command ``py.test --pyargs
openpathsampling``.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
.. The tests for this module can be run by downloading its source code,
.. installing its requirements, and running the command ``py.test`` from the
.. root directory of the repository.
Examples
________
This module is used in the OPS `alanine dipeptide MSTIS example <https://github.com/openpathsampling/openpathsampling/blob/master/examples/alanine_dipeptide_mstis/AD_mstis_1_setup.ipynb>`_, during the creation of initial trajectories.
Source Code
___________
.. link the source code
.. IF YOUR MODULE IS IN OPS CORE
This module has been merged into OpenPathSampling. It is composed of the
following pull requests:
* https://github.com/openpathsampling/openpathsampling/pull/826
.. IF YOUR MODULE IS A SEPARATE REPOSITORY
.. The source code for this module can be found in: URL.
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _pytest: http://pytest.org/
......@@ -11,7 +11,7 @@ Web Throwing in OpenPathSampling
sections.
Language
Python (2.7)
Python (2.7, 3.6, 3.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
......@@ -122,7 +122,7 @@ reading:
Testing
_______
Tests in OpenPathSampling use the `nose`_ package.
.. Tests in OpenPathSampling use the `nose`_ package.
.. IF YOUR MODULE IS IN OPS CORE:
......@@ -136,8 +136,8 @@ The tests for this module can be run by installing `OpenPathSampling`_,
downloading source code for the module (see the ``Source Code``
section below), and installing it by running by running
``python setup.py install`` from the root directory of the package.
Test this module by running the command ``nosetests`` from the root directory of
the repository.
Test this module with the `nose`_ package, by running the command ``nosetests``
from the root directory of the repository.
Examples
......
.. _Particle_Insertion_core:
#######################
Particle Insertion Core
#######################
.. sidebar:: Software Technical Information
This is the core module for the particle insertion suite of codes
Languages
C, Python 2.7, LAMMPS Scripting language
Licence
MIT -however note that LAMMPS is now changing from GPL to LGPL so when used togetherwith LAMMPS LGPL applies
Documentation Tool
All source code should be documented so please indicate what tool has been used for documentation. We can help you
with Doxygen and ReST but if you use other tools it might be harder for us to help if there are problems.
Application Documentation
See `PIcore repository <https://gitlab.e-cam2020.eu/mackernan/particle_insertion/tree/master/PIcore>`_
Relevant Training Material
None
.. contents:: :local:
.. Add technical info as a sidebar and allow text below to wrap around it
Purpose of the Module
_____________________
This software module computes the change in free energy associated with the insertion or deletion of Lennard Jones particles in dilute or dense
conditions in a variety of Thermodynamic Ensembles, where statistical sampling through molecular dynamics is performed under `LAMMPS <https://lammps.sandia.gov/>`_ but
will be extended to other molecular dynamics engines at a later date. Lennard-Jones type interactions are the key source of
difficulty associated with particle insertion or deletion, which is why this module is a core module, as other interactions including
Coulombic and bond, angle and dihedral interactions will be added in a second module. It differs from the main community approach used to
date to compute such changes as it does not use soft-core potentials. Its key advantages over soft-core potentials are: (a) electrostatic interactions
can in principle be performed simultaneously
with particle insertion (this and other functionalities will be added in a new module); and, (b) essentially exact long-range dispersive interactions
using `dispersion Particle Mesh Ewald <https://doi.org/10.1063/1.4764089>`_ (PMME) or EWALD if desired can be selected at runtime by the user.
Background Information
______________________
Particle insertion can be used to compute the free energy associated with hydration/drying, the insertion of cavities in fluids/crystals,
changes in salt levels, changes in solvent mixtures, and alchemical changes such as the mutation of amino-acids. in crystals. It can also
be used to compute the free energy of solvent mixtures and the addition of salts, which is used in the purification processing
industrially, for instance in the purification of pharmaceutical active ingredients. Particle insertion can in principle also be
used to compute the free energy associated with changes in the pH, that is the proton transfer from a titratable site to the bulk,
for example in water.
Our approach consists of rescaling the effective size of inserted atoms through a parameter :math:`\lambda` so that all interactions between
nserted atoms and interactions between inserted atoms and atoms already present in the system are zero when :math:`\lambda = 0`, creating at most an
integrable singularity which we can safely handle. In the context of Lennard-Jones type pair potentials,
our approach at a mathematical level is similar to Simonson, who investigated the mathematical conditions required to `avoid the
singularity of insertion <https://doi.org/10.1080/00268979300102371>`_. It turns out that a non-linear dependence of the
interaction on :math: '\\lambda' between inserted
atoms and those already present is required (i.e. a simple linear dependence on :math: '\lambda' necessarily introduces a singularity).
This module and upcoming modules include computing the free energy changes associated with the following applications
(a) hydration and drying;
(b) the addition of multiple molecules into a condenses environment;
(c) residue mutation and alchemy;
(d) constant pH simulations, this also will also exploit modules created in E-CAM work package 3 (quantum dynamics); and,
(e) free energy changes in chemical potentials associated with changes in solvent mixtures.
General Formulation
___________________
Consider a system consisting of :math:`N+M` degrees of freedom and the Hamiltonian
.. math::
H(r,p,\lambda) =&H_0 + KE_{insert} + \Delta V(r, \lambda)
where :math:`H_0` corresponds to an unperturbed Hamiltonian, and the perturbation :math:`\Delta V(r, \lambda)` depends
nonlinearly on a control parameter :math:`\lambda`. The first set of N degrees of freedom is denoted by A and the second
set of M degrees of freedom is denoted by B. To explore equilibrium properties of the system, thermostats, and barostats
are used to sample either the NVT (canonical) ensemble or the NPT (Gibbs) ensemble. The perturbation is devised so that
when :math:`\lambda = 0`, :math:`\Delta V(r, \lambda) = 0`, B is in purely virtual. When :math:`\lambda = 1`, B
corresponds to a fully physical augmentation of the original system.
In the present software module, we consider only interaction Lennard Jones atoms.
.. math::
\Delta V(r,\lambda) = V_{lj}(r,\lambda)
where for each inserted atom i
.. math::
\hat{\sigma}( \lambda)_i &= \lambda \sigma_i \\
\hat{\epsilon}( \lambda)_i &= \lambda \epsilon_i \\
and the mixing rule for Van der Waals diameters and binding energy between different atoms uses the geometric mean.
The dependence of :math:`\sigma` on :math:`\lambda` has the consequence that the mean
:math:`\sigma` between a pair of inserted atoms scales as :math:`\lambda`, but scales as :math:`\sqrt{\lambda}` when one atom in the pair is
inserted and the other is already present. These choices of perturbations guarantees that the particle insertion and deletion catastrophes are avoided.
Algorithms
__________
At the core of the PI core module there are four functions/codes. The first written in python generates the interpolation points which are
the zero's of suitably transformed Chebyshev functions.
The second code written ln LAMMPS scripting language performs the simulation in user-defined ensembles at the selected
interpolation values of :math:'lambda', at a user-specified frequency, computing two-point central difference estimates of derivatives of the
potential energy needed for thermodynamic integration, computing the energy
functions for all values of :math:'lambda' in the context of MBAR. The user also specifies the locations of the inserted particles.
The user also specifies whether
Particle Mesh Ewald or EWALD should be used for dispersive interactions.
The third code written in python takes the output data from LAMMPS, prepares it so that free energy differences in the
selected ensemble can be computed using MBAR provided by the pymbar suite of python codes of the Chodera group.
The fourth code, also written in python take the LAMMPS output and performs the thermodynamic integration.
.. image:: ./flowchart1.png
Source Code
___________
All files can be found in the ``PIcore`` subdirectory of the `particle_insertion git repository <https://gitlab.e-cam2020.eu/mackernan/particle_insertion>`_.
Compilation and Linking
_______________________
See `PIcore README <https://gitlab.e-cam2020.eu/mackernan/particle_insertion/tree/master/PIcore/README.rst>`_ for full details.
Scaling and Performance
________________________
As the module uses LAMMPS, the performance and scaling of this module should essentially be the same, provided data for thermodynamic integration and
MBAR are not generated too often, as is demonstated below. In the case of thermodynamic integration, this is due to the central difference approximation of derivatives, and in the case
of MBAR, it is due to the fact that many virtual moves are made which can be extremely costly if the number of interpolating points is large. Also, when using
PMME, the initial setup cost is computationally expensive, and should, therefore, be done as infrequently as possible. A future module in preparation will
circumvent the use of central difference approximations of derivatives. The scaling performance of PI-CORE was tested on Jureca multi node.
The results for weak scaling (where the number of core and the system size are doubled from 4 to 768 core) are as follows.
Weak Scaling:
================== ===========
Number of MPI Core timesteps/s
================== ===========
4 1664.793
8 1534.013
16 1458.936
24 1454.075
48 1350.257
96 1301.325
192 1263.402
384 1212.539
768 1108.306
================== ===========
and for the strong scaling (where the number of core are doubled from 4 to 384 but the system size is fixed equal to 768 times the original system
size considered for one core/processor for weak scaling) Strong Scaling:
================== =============
Number of MPI Core timesteps/s
================== =============
4 9.197
8 17.447
16 34.641
24 53.345
48 104.504
96 204.434
192 369.178
384 634.022
================== =============
This diff is collapsed.
This diff is collapsed.
.. In ReStructured Text (ReST) indentation and spacing are very important (it is how ReST knows what to do with your
document). For ReST to understand what you intend and to render it correctly please to keep the structure of this
template. Make sure that any time you use ReST syntax (such as for ".. sidebar::" below), it needs to be preceded
and followed by white space (if you see warnings when this file is built they this is a common origin for problems).
.. Firstly, let's add technical info as a sidebar and allow text below to wrap around it. This list is a work in
progress, please help us improve it. We use *definition lists* of ReST_ to make this readable.
.. sidebar:: Software Technical Information
This module extends the contact_maps project.
Name
contact_maps
Language
Python 2.7, 3.5, 3.6
Licence
LGPL 2.1+
Documentation Tool
Sphinx/RST
Application Documentation
http://contact-map.readthedocs.io/
Relevant Training Material
TODO
Software Module Developed by
David W.H. Swenson
.. _contact_concurrences:
####################
Contact Concurrences
####################
.. Let's add a local table of contents to help people navigate the page
.. contents:: :local:
.. Add an abstract for a *general* audience here. Write a few lines that
explains the "helicopter view" of why you are creating this module. For
example, you might say that "This module is a stepping stone to
incorporating XXXX effects into YYYY process, which in turn should allow
ZZZZ to be simulated. If successful, this could make it possible to
produce compound AAAA while avoiding expensive process BBBB and CCCC."
This module deals with the analysis of contacts between parts of
biomolecules based on "contact concurrences," i.e., what contacts occur
simultaneously during a trajectory. This is useful when using contacts as a
definition of a metastable state in a trajectory.
Purpose of Module
_________________
Contact frequencies, as developed in the module :ref:`contact-map`, are a
useful tool for studying biomolecular systems, such as binding/unbinding of
a ligand from a protein. However, they suffer from one problem when trying
to use them to define metastable states: since they are averaged over time,
they don't show time-dependent behavior. To identify a stable state,
time-dependent behavior must be considered.
For example, a particular contact pair might have a frequency of 0.1 during
a 100ns trajectory. But this could be achieved in several ways. If the
contact events are randomly distributed through time, this contact probably
isn't characteristic of a metastable state. On the other hand, if the
contact is constantly present during the last 10 ns (and not otherwise
present), it might represent a metastable state. More importantly, there
might be multiple contacts that are *all* present during those last 10 ns.
Those concurrent contacts could be used to define a metastable state. This
module helps identify and analyze those concurrent contacts by providing a
tool to visualize them.
.. figure:: concurrences.png
:alt: Output of contact concurrence visualization
:figwidth: 50 %
:align: right
The figure shows the output of the contact concurrence visualization for the
contacts between an inhibitor (labelled YYG) and various residues of the
protein GSK3B. The plot shows when each contact occurred. The x-axis is
time. Each dot represents that a specific contact pair is present at that
time. The contact pairs are separated along the vertical axis.
This trajectory shows two groups of stable contacts between the protein and
the ligand; i.e. there is a change in the stable state. This allows us to
visually identify the contacts involved in each state. Both states involve
the ligand being in contact with Phe33, but the earlier state includes
contacts with Ile28, Gly29, etc., while the later state includes contacts
with Ser32 and Gly168.
This is an important tool for identifying stable states based on long-lived
groups of contacts, and is being used as part of the `E-CAM pilot project on
binding kinetics <https://www.e-cam2020.eu/pilot-project-biki/>`_. It has
also been used a part of a bachelor's thesis project to develop an automated
approach to identifying metastable intermediates during binding/unbinding
processes.
Classes implemented in this module include:
* ``Concurrence``: Superclass for contact concurrence objects, enabling
future custom concurrence types.
* ``AtomContactConcurrence``: Contact concurrences for atom-atom contacts.
* ``ResidueContactConcurrence``: Contact concurrences for residue-residue
contacts (based on minimum distance between constituent atoms).
* ``ConcurrencePlotter`` and ``plot_concurrences``: Class and convenience
function (respectively) for making plots of contact concurrence.
* ``ContactsDict``: Dict-like object giving access to atom or residue
contacts based on string keys. Also added ``ContactObject.contacts``
property, which returns a ``ContactsDict`` object for the
``ContactObject``.
.. * Who will use the module? in what area(s) and in what context?
.. * What kind of problems can be solved by the code?
.. * Are there any real-world applications for it?
.. * Has the module been interfaced with other packages?
.. * Was it used in a thesis, a scientific collaboration, or was it cited in
.. a publication?
.. * If there are published results obtained using this code, describe them
briefly in terms readable for non-expert users. If you have few
pictures/graphs illustrating the power or utility of the module, please
include them with corresponding explanatory captions.
Background Information
______________________
This module is part of the `contact_map
<http://contact-map.readthedocs.io>`_ project, which builds on tools from
`MDTraj <http://mdtraj.org>`_.
Building and Testing
____________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
This module will be included in the 0.4 release of ``contact_map``. After
that release, it can be easily installed with ``conda``, using ``conda
install -c conda-forge contact_map``, or ``conda install -c conda-forge
contact_map==0.4.0`` for the first version that includes this module. To see
the current release, go to https://pypi.org/project/contact-map/#history.
Until the release, this module can only be installed through a developer
install of ``contact_map``. This involves downloading the ``contact_map``
repository, installing the requirements, and then installing the
``contact_map`` package from source. Instructions can be found on the
`installation page
<http://contact-map.readthedocs.io/en/latest/installing.html#developer-installation>`_
of the ``contact_map`` documentation.
Once installed, tests are run using pytest. To check that the code has been
correctly installed, run ``python -c "import contact_map"`` from the command
line. To run the tests, install pytest and run the command ``py.test
--pyargs contact_map``.
Examples
--------
An example can be found in the documentation to the ``contact_map`` paper:
[`docs <https://contact-map.readthedocs.io/en/latest/examples/nb/concurrences.html>`_ | `GitHub <https://github.com/dwhswenson/contact_map/blob/master/examples/concurrences.ipynb>`_]
Source Code
___________
.. Notice the syntax of a URL reference below `Text <URL>`_ the backticks matter!
The source code for this module is contained in the following pull requests
in the ``contact_map`` repository:
* https://github.com/dwhswenson/contact_map/pull/28
* https://github.com/dwhswenson/contact_map/pull/47
......@@ -63,7 +63,7 @@ Testing
_______
This module can be installed with conda, using ``conda install -c
conda-forge contact_map``. To intall the specific version associated with
conda-forge contact_map``. To install the specific version associated with
this module, use ``conda install -c conda-forge contact_map==0.2.0``
Tests for this module can be run with pytest. Install pytest with ``pip
......
.. In ReStructured Text (ReST) indentation and spacing are very important (it is how ReST knows what to do with your
document). For ReST to understand what you intend and to render it correctly please to keep the structure of this
template. Make sure that any time you use ReST syntax (such as for ".. sidebar::" below), it needs to be preceded
and followed by white space (if you see warnings when this file is built they this is a common origin for problems).
.. Firstly, let's add technical info as a sidebar and allow text below to wrap around it. This list is a work in
progress, please help us improve it. We use *definition lists* of ReST_ to make this readable.
.. sidebar:: Software Technical Information
Name