...
 
Commits (380)
_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 #
#######################
*~
......@@ -3,7 +3,7 @@ image: cloudcompass/docker-rtdsphinx
spelling:
script:
- pip3 install codespell
- codespell --skip=".git,_static,_build,Diff*,*.patch" --quiet-level=2 --ignore-words-list="adress"
- codespell --skip=".git,_static,_build,Diff*,*.patch,*.f90" --quiet-level=2 --ignore-words-list="adress,catalogue,noe"
only:
- master
- merge_requests
......@@ -13,7 +13,7 @@ orphans:
# 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 "1" ]; then $(exit 1); else $(exit 0); fi
- if [ $(find ./ -name "*.rst"|xargs -i grep -H orphan {}|wc -l) -gt "2" ]; then $(exit 1); else $(exit 0); fi
only:
- master
......@@ -22,9 +22,10 @@ pages:
- apt-get -y install dvipng
- pip3 install pygments --upgrade
- pip3 install Sphinx --upgrade
- pip3 install sphinx-bootstrap-theme --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
......
......@@ -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,13 +173,16 @@ 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
......@@ -187,9 +190,9 @@ The modules that are based on OPS, but remain separate, are:
./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
......@@ -212,7 +215,7 @@ 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
......@@ -220,8 +223,8 @@ The following modules were developed specifically for the Classical MD pilot pro
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::
......@@ -233,7 +236,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::
......@@ -244,5 +247,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/
.. _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
________
......
......@@ -11,7 +11,7 @@ Transition State Ensemble in OpenPathSampling
sections.
Language
Python (2.7)
Python (3.7)
Documentation Tool
Sphinx, numpydoc format (ReST)
......
.. _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
......
.. sidebar:: Software Technical Information
Name
pyscal
Language
Python (2.7, 3.4, 3.5, 3.6)
Licence
`GNU General Public License v3.0 <https://www.gnu.org/licenses/gpl-3.0.en.html>`_
Documentation Tool
Sphinx/RST
Application Documentation
https://pyscal.readthedocs.io/en/latest/
Relevant Training Material
https://mybinder.org/v2/gh/srmnitc/pyscal/master?filepath=examples%2F
Software Module Developed by
Sarath Menon
Grisell Díaz Leines
Jutta Rogal
######
pyscal
######
.. contents:: :local:
**pyscal** is a python module for the calculation of local atomic structural environments including Steinhardt's bond orientational order parameters [1]_ during post-processing
of atomistic simulation data. The core functionality of pyscal is written in C++ with python wrappers using
`pybind11 <https://pybind11.readthedocs.io/en/stable/intro.html>`_ which allows for fast calculations and
easy extensions in python.
Purpose of Module
_________________
Steinhardt's order parameters are widely used for the identification of crystal structures [3]_. They are also used to distinguish
if an atom is in a solid or liquid environment [4]_. pyscal is inspired by the
`BondOrderAnalysis <https://homepage.univie.ac.at/wolfgang.lechner/bondorderparameter.html>`_ code,
but has since incorporated many additional features and modifications. The pyscal module includes the following functionalities:
* calculation of Steinhardt's order parameters and their averaged version [2]_.
* links with the `Voro++ <http://math.lbl.gov/voro++/>`_ code, for the calculation of Steinhardt parameters weighted using the face areas of Voronoi polyhedra [3]_.
* classification of atoms as solid or liquid [4]_.
* clustering of particles based on a user defined property.
* methods for calculating radial distribution functions, Voronoi volumes of particles, number of vertices and face area of Voronoi polyhedra, and coordination numbers.
Background Information
______________________
See the `application documentation <https://pyscal.readthedocs.io/en/latest/>`_ for full details.
The utilisation of Dask within the project came about as a result of the `E-CAM High Throughput Computing ESDW <https://www.e-cam2020.eu/event/4424/?instance_id=71>`_ held in Turin in 2018 and 2019.
Building and Testing
____________________
**Installation**
pyscal can be installed directly using `Conda <https://docs.conda.io/en/latest/>`_ by the following statement-
.. code:: console
conda install -c pyscal pyscal
pyscal can be built from the repository by-
.. code:: console
git clone https://github.com/srmnitc/pyscal.git
cd pyscal
python setup.py install --user
**Testing**
pyscal contains automated tests which
use the `pytest <https://docs.pytest.org/en/latest/>`_ python library, which can be installed by ``pip install pytest``.
The tests can be run by executing the command ``pytest tests/`` from the main code directory.
**Examples**
Examples using pyscal can be found `here <https://pyscal.readthedocs.io/en/latest/examples.html>`_.
An `interactive notebook <https://mybinder.org/v2/gh/srmnitc/pyscal/master?filepath=examples%2F>`_
using binder is also available.
Source Code
___________
The `source code <https://github.com/srmnitc/pyscal>`_. of the module can be found on GitHub.
.. [1] `Steinhardt, P. J., Nelson, D. R., & Ronchetti, M. (1983). Physical Review B, 28 <https://journals.aps.org/prb/abstract/10.1103/PhysRevB.28.784>`_.
.. [2] `Lechner, W., & Dellago, C. (2008). The Journal of Chemical Physics, 129 <https://aip.scitation.org/doi/full/10.1063/1.2977970>`_.
.. [3] `Mickel, W., Kapfer, S. C., Schröder-Turk, G. E., & Mecke, K. (2013). The Journal of Chemical Physics, 138 <https://aip.scitation.org/doi/full/10.1063/1.4774084>`_.
.. [4] `Auer, S., & Frenkel, D. (2005). Advances in Polymer Science, 173 <https://link.springer.com/chapter/10.1007/b99429>`_.
......@@ -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_electronic_structure:
****************************
......@@ -12,14 +19,7 @@ Electronic Structure Modules
Introduction
============
.. sidebar:: General Information
.. contents:: :depth: 2
* :ref:`contributing`
* :ref:`search`
.. figure:: ./images/wake_nova-rgb.png
.. figure:: ./images/protein-metal-cluster.png
:figwidth: 25 %
:align: left
......@@ -76,6 +76,29 @@ The ESDW in San Sebastian in September 2016 was the starting point for the modul
./modules/Use_WS_Distance/readme
./modules/Test-Suite-Travis-CI-Integration/readme
ESDW Lausanne 2018
------------------
The ESDW in Lausanne in February 2018 was the starting point for the modules below.
.. toctree::
:glob:
:maxdepth: 1
./modules/esl-bundle/readme
./modules/ELPA_easyblock/readme
ESDW Dublin 2019
-----------------
The ESDW in Dublin in January 2019 was the starting point for the modules below.
.. toctree::
:glob:
:maxdepth: 1
./modules/esl-easyconfigs/readme
Other Modules
-------------
......@@ -86,7 +109,6 @@ Modules not coming from ESDWs
:glob:
:maxdepth: 1
./modules/SCDM_WFs/readme
./modules/flook/readme
./modules/MatrixSwitchDBCSR/readme
......@@ -107,11 +129,15 @@ Below is a list of the modules developed directly within the context of the pilo
./modules/Geomoltools/readme
./modules/GRASP_Sampling/readme
./modules/GROMACS_interface/README
./modules/Gaussian_interface/README
./modules/Selectively-Localized-Wannier-Functions/readme
./modules/Gaussian_interface/README
./modules/Differential_Evolution/README
./modules/Gaussian_interface/README
./modules/WLRR/README
./modules/SCDM_WFs/readme
./modules/W90_solution_booklet/readme
./modules/FFTXlib/readme
./modules/W90_cube_format_non-orthogonal/readme
.. _E-CAM: https://www.e-cam2020.eu/
.. sidebar:: Software Technical Information
Name
EasyBuild
Language
Python
Licence
`GPL-2.0 <https://opensource.org/licenses/GPL-2.0>`_
Documentation Tool
ReST_
Application Documentation
https://easybuild.readthedocs.io
Relevant Training Material
See documentation
Software Module Developed by
Micael Oliveira
.. 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).
.. _elpa_easyblock:
###############################
Add ELPA easyblock to EasyBuild
###############################
.. 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."
EasyBuild is used by a number of large HPC sites and integrating targeted support for ELPA ensures that those sites
use optimally built versions of ELPA.
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
Automate the selection of appropriate configuration flags for ELPA within EasyBuild depending on the type of CPU and available features.
Include additional options as appropriate. Build single and double precision versions of ELPA and also ensure it is linked against the expected version of the linear algebra libraries.
Background Information
______________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
EasyBuild is a software build and installation framework that allows you to manage (scientific) software on High
Performance Computing (HPC) systems in an efficient way. Full details on can be found in the
`EasyBuild documentation <https://easybuild.readthedocs.io/en/latest/>`_.
EasyBuild already had limited support for ELPA, this module allows for automated hardware specific configuration and optimisations.
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
To build the software requires EasyBuild (see
`installation instructions for EasyBuild here <https://easybuild.readthedocs.io/en/latest/Installation.html>`_) and an
example build command would be:
::
eb ELPA-2018.11.001-intel-2019a.eb
Source Code
___________
.. Notice the syntax of a URL reference below `Text <URL>`_ the backticks matter!
There are two relevant Pull Requests in the main EasyBuild repositories:
* https://github.com/easybuilders/easybuild-easyblocks/pull/1621
* https://github.com/easybuilders/easybuild-easyconfigs/pull/8360
.. Here are the URL references used (which is alternative method to the one described above)
.. _ReST: http://www.sphinx-doc.org/en/stable/rest.html
.. _Sphinx: http://www.sphinx-doc.org/en/stable/markup/index.html
########
FFTXlib
########
.. sidebar:: Software Technical Information
Language
Fortran 1995
Documentation Tool
Sphinx, ReStructuredText
Application Documentation
`Doc mirror <https://gitlab.com/kucukben/fftxlib-esl-ecam/tree/master/doc>`_
Relevant Training Material
See usage examples in the ``examples`` directory of the source code.
Licence
GNU Lesser General Public License v3.0
Author of Module
Emine Kucukbenli
.. contents:: :local:
Purpose of Module
_________________
FFTXlib module is a collection of driver routines for complex 3D fast Fourier transform (FFT) libraries
to be used within planewave-based electronic structure calculation software.
Generally speaking, FFT algorithm requires a data array to act on, a clear description of the
input-output sequence and transform domains.
In the context of planewave based electronic structure calculations, the data array may hold elements such as
electronic wavefunction :math:`\psi` or charge density :math:`\rho` or their functions.
The transform domains are direct (real) and reciprocal space,
the discretization in real space is represented as a uniform grid of the unit cell and
the discretization of the reciprocal space is in the basis of planewaves whose wavevectors
are multiples of reciprocal space vectors :math:`(\mathbf G)` .
To understand the main motivation behind FFTXlib routines we need to clarify the differences between the representation
of wavefunction and charge density in planewave based codes:
In these codes, the expansion of wavefunction in planewave basis is
truncated at a cut-off wave-vector :math:`\mathbf G_{max}`.
Since density is the norm-square of the wavefunction, the expansion that is consistent with
the one of wavefunctions requires a cut-off wavevector twice that of wavefunctions: :math:`2 \mathbf G_{max}`.
Meanwhile, the real space FFT domain is often only defined by one uniform grid of the unit cell,
so the array sizes of both :math:`\rho` and :math:`\psi` in their real space representation are the same.
Therefore, to boost optimization and to reduce numerical noise, the library implements two possible options while performing FFT:
in one ( 'Wave') the wavevectors beyond :math:`\mathbf G_{max}` are ignored,
in the other ( 'Rho' ) no such assumption is made.
Another crucial feature of FFTXlib is that some approximations in the electronic structure calculations
(such as usage of non-normconserving pseudopotentials) require that density is not just
norm-square of wavefunctions, but has spatially localized extra components. In that case,
these localized contributions may require higher G-vector components than the ones needed for density
(:math:`> 2 \mathbf G_{max}`).
Hence, in such systems, the density array in reciprocal space has more elements
than the norm-conserving case (in other words a finer resolution or a denser grid is needed in real space)
while the resolution needed to represent wavefunctions are left unchanged.
To accommodate for these different requirements of grid size, and to be able to make Fourier transforms back and forth between them,
the FFTXlib routines explicitly require descriptor arguments which define the grids to be used. For example,
if potential is obtained from density, the FFT operations on it should use the denser grid;
while FFT on wavefunctions should use the smoother grid (corresponding to :math:`2\mathbf G_{max}` as defined before).
When the Hamiltonian's action on wavefunctions are being calculated, the potential should be
brought from dense to smooth grid.
But when the density is being calculated, wavefunction normsquare should be carried from smooth to dense grid.
A final important feature of FFTXlib is the index mapping. In the simple case of no parallelization,
as a choice, the reciprocal space arrays are ordered in increasing order of :math:`|G|^2`
while the real space arrays are sorted in column major order.
Therefore for FFT to be performed, a map between these two orders must be known.
This index map is created and preserved by the FFTXlib.
In summary, FFTXlib allows the user to perform complex 3D fast Fourier transform (FFT) in the context of
plane wave based electronic structure software. It contains routines to initialize the array structures,
to calculate the desired grid shapes. It imposes underlying size assumptions and provides
correspondence maps for indices between the two transform domains.
Once this data structure is constructed, forward or inverse in-place FFT can be performed.
For this purpose FFTXlib can either use a local copy of an earlier version of FFTW (a commonly used open source FFT library),
or it can also serve as a wrapper to external FFT libraries via conditional compilition using pre-processor directives.
It supports both MPI and OpenMP parallelization technologies.
FFTXlib is currently employed within Quantum Espresso package, a widely used suite of codes
for electronic structure calculations and materials modeling in the nanoscale, based on
planewave and pseudopotentials. FFTXlib is also interfaced with "miniPWPP" module
that solves the Kohn Sham equations in the basis of planewaves and soon to be released as a part of E-CAM Electronic Structure Library.
Background Information
______________________
FFTXlib is mainly a rewrite and optimization of earlier versions of FFT related routines inside Quantum ESPRESSO pre-v6;
and finally their replacement.
This may shed light on some of the variable name choices, as well as the default of :math:`2\mathbf G_{max}` cut-off
for the expansion of the smooth part of the charge density, and the required format for lattice parameters in order to build the
FFT domain descriptor.
Despite many similarities, current version of FFTXlib dramatically changes the FFT strategy in the parallel execution,
from 1D+2D FFT performed in QE pre v6
to a 1D+1D+1D one; to allow for greater flexibility in parallelization.
Building and Testing
______________________________
A stable version of the module can be downloaded using `this link <https://gitlab.com/kucukben/fftxlib-esl-ecam>`_
.. when fftxlib has its own repo, this link can be moved there.
Current installation and testing are done with gfortran compiler, version 4.4.7.
The configuration uses GNU Autoconf 2.69.
The commands for installation are::
$ ./configure
$ make libfftx
As a result, the library archive "libfftx.a" is produced in src directory,
and symbolicly linked to a "lib" directory.
.. To test whether the library is working as expected, run::
.. $ make FFTXtest
.. Besides the PASS/FAIL status of the test, by changing the bash script in the tests directory, you can perform your custom tests. Read the README.test documentation in the tests subdirectory for further details about the tests.
To see how the library works in a realistic case scenario of an electronic structure calculation, run::
$make FFTXexamples
.. Besides the PASS/FAIL status of the example, by changing the bash script in the examples directory, you can create your custom examples.
A mini-app will be compiled in src directory and will be symbolicly copied into ``bin`` directory.
The mini-app simulates an FFT scenario with a test unit cell, and plane wave expansion cutoff.
It creates the FFT structures and tests forward and backward transform on sample array and reports timings.
Read the README.examples documentation in the examples subdirectory for further details.
Source Code
____________
The FFTXlib bundle corresponding to the stable release can be downloaded from this `link <https://gitlab.com/kucukben/fftxlib-esl-ecam>`_
The source code itself can be found under the subdirectory ``src``.
The development is ongoing.
The version that corresponds to the one of examples and tests can be obtained with SHA 31a6f4ecbb7ce474b0c87702c716713758f99a0a. This will soon be replaced with a version tag.
Further Information
____________________
This documentation can be found inside the ``docs`` subdirectory.
The FFTXlib is developed with the contributions of C. Cavazzoni, S. de Gironcoli,
P. Giannozzi, F. Affinito, P. Bonfa', Martin Hilgemans, Guido Roma, Pascal Thibaudeau,
Stephane Lefranc, Nicolas Lacorne, Filippo Spiga, Nicola Varini, Jason Wood, Emine Kucukbenli.
......@@ -51,7 +51,7 @@ _________________
.. Give a brief overview of why the module is/was being created, explaining a little of the scientific background and how
.. figure:: ./images/Cobalt_selection.png
:figwidth: 55 %
:scale: 50 %
:align: left
This module is part of bundle to extend the capabilities of the Wannier90 code [1]_. In particular, here we have implemented the
......
##############################
W90_cube_format_non-orthogonal
##############################
.. sidebar:: Software Technical Information
Name
Cube format files for non-orthogonal cells
Language
Fortran90
Licence
`GPL <https://opensource.org/licenses/gpl-license>`_
Documentation Tool
`Ford <http://fortranwiki.org/fortran/show/FORD>`_ online link to different Wannier90 source files `<http://www.wannier.org/ford/>`_
Application Documentation
Wannier90 `User guide pdf <https://github.com/wannier-developers/wannier90/raw/v3.0.0/doc/compiled_docs/user_guide.pdf>`_ and `Tutorial pdf <https://github.com/wannier-developers/wannier90/raw/v3.0.0/doc/compiled_docs/tutorial.pdf>`_ and `Solution booklet pdf <https://github.com/wannier-developers/wannier90/raw/v3.0.0/doc/compiled_docs/solution_booklet.pdf>`_
Relevant Training Material
Training material is accessible via tests and examples as well as a tutorial and its solutions.
Software Module Developed by
Valerio Vitale
.. 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).
.. _Cube_format_files_for_cells_with_non-orthogonal_lattice_vectors:
.. 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."
For many applications that rely on the detail of the electronic structure of solids, it is crucial to inspect the symmetries, centres and shapes of the Wannier functions. To this end, one needs to use a visualisation program such as VESTA [1]_ or VMD [2]_. One of the most popular format to encode volumetric data is the GAUSSIAN CUBE format, which is supported by almost all molecular visualization programs. This module extends the cability of Wannier90 in generating output files in the CUBE format for periodic calculations with non-orthogonal unit cells.
.. [1] J. Appl. Crystallogr **44**, 1272-1276 (2011)
.. [2] J. Molec. Graphics **14**, 33-38 (1996)
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
.. Give a brief overview of why the module is/was being created, explaining a little of the scientific background and how
.. figure:: ./images/gaas_00003_cellsize3_vesta.png
:scale: 25 %
:align: left
This modules allows the User to output volumetric data, e.g. the Wannier functions on a real space grid, in the GAUSSIAN CUBE format even when the unit cell lattice vectors of the periodic calculation are non-orthogonal. The User can activate this feature by inserting the following two lines in the input file:
`wannier_plot = .true.`
`wannier_plot_format = cube`
In addition, one can also specify the cut-off radius for the Wannier functions, i.e. the radius of the sphere that must fit inside the parallelepiped in which the Wannier function is plotted, via the `wannier_plot_radius` keyword. The number of atoms to plot with the volumetric data can be implicitly defined by the `wannier_plot_scale` keyword.
This module is part of the Wannier90 code [3]_. The name of the subroutine that implements it is `internal_cube_format` and can be found in the `plot.F90` file within the `src` folder.
.. [3] Comput. Phys. Commun. **185**, 2309 (2014)
Background Information
______________________
.. Keep the helper text below around in your module by just adding ".. " in front of it, which turns it into a comment
Wannier90 source code is available from the official repository on Git-hub `<http://github.com/wannier-developers/wannier90>`_. Documentation of the source code is done via the FORD program, an online version of this documentation is available `online <http://www.wannier.org/ford/>`_. Instructions on how to install Wannier90 on a variety of architectures may be found in the `user guide <https://github.com/wannier-developers/wannier90/raw/v3.0.0/doc/compiled_docs/user_guide.pdf>`_.
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
For building the module one "simply" has to compile the Wannier90 code as explained in the online documentation. This will produce the executable ``wannier90.x``, which contains the module. The source code can be found in the src folder within the plot.F90 module.
Source Code
___________
.. Notice the syntax of a URL reference below `Text <URL>`_ the backticks matter!
* `Link to a merge request containing my source code changes
<https://github.com/wannier-developers/wannier90/pull/162>`_
#######################################
W90_solution_booklet
#######################################
.. sidebar:: Software Technical Information
Name
Wannier90 Solution Booklet
Language
LaTeX
Licence
`GPL <https://opensource.org/licenses/gpl-license>`_
Documentation Tool
Application Documentation
`Solution booklet pdf <https://github.com/wannier-developers/wannier90/raw/v3.0.0/doc/compiled_docs/solution_booklet.pdf>`_
Relevant Training Material
'Not currently available.'
Software Module Developed by
Valerio Vitale
.. 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).
.. _W90_Solution_booklet: