Verified Commit 1a551667 authored by David W.H. Swenson's avatar David W.H. Swenson

Merge remote-tracking branch 'upstream/master' into wp1_module_organization

parents af3c1945 ba79e8f1
......@@ -9,9 +9,9 @@ This issue refers to Merge Request (insert MR reference)
- [ ] Is the module documentation sufficiently detailed?
- [ ] Is it mergeable? (i.e., there should be no merge conflicts)
- [ ] Are the build instructions sufficient? (If not the MR should be updated)
- [ ] Are the build instructions sufficient - source code locations, build instructions, etc.? (If not the MR should be updated)
- [ ] Did it pass the tests? (Are there unit/regression tests? Do they pass?)
- [ ] If it introduces new functionality, is it tested? (Unit tests?)
- [ ] Is it well formatted? (typos, line length, brackets,...)
- [ ] Is all new source code sufficiently documented? (functions, their arguments,...)
- [ ] Did it change any interfaces? Only additions are allowed without a major version increment (if >v1.0). Changing file formats also requires a major version number increment.
- [ ] Is there a description of any applications the module has? (This is a hard requirement for E-CAM PDRAs)
......@@ -26,7 +26,7 @@ Introduction
This is a collection of the modules that have been created by E-CAM_ community
within the area of Classical MD. This documentation is created using
ReStructured Text and the git repository for the documentation source files can
be found at https://gitlab.e-cam2020.eu/e-cam/Classical-MD-Modules which are
be found at https://gitlab.e-cam2020.eu/e-cam/E-CAM-Library which are
open to contributions from E-CAM members.
In the context of E-CAM, the definition of a software module is any piece of
......@@ -234,5 +234,6 @@ August 2017. The following modules have been produced:
:maxdepth: 1
./modules/OpenPathSampling/ops_spring_shooting/readme
./modules/OpenPathSampling/ops_sr_shooter/readme
.. _E-CAM: https://www.e-cam2020.eu/
.. _ops_sr_shooter:
########################################
OPS-based module: Shooting range shooter
########################################
.. 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)
[+Python (3.6)]
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:
This module implements the "shooting from the top" algorithm as detailed in `the paper "Transition path sampling of rare events by shooting from the top" <http://dx.doi.org/10.1063/1.4997378>`_.
Purpose of Module
_________________
The purpose of this algorithm is to increase the number of generated transitions in a transition path sampling simulation by exclusively shooting from the transition state ensemble (TSE)/the top of the barrier (hence the name). Naturally this only works if the approximate location of the TSE is already known and can be given as a function of the atomic coordinates. In this module any `openpathsampling.Volume`_ object can be used by the user to define the shooting range volume. This enables the user to define the shooting range for example as a function of one or more collective variables. See also the :ref:`tse_module` for finding the TSE.
The implementation in this module includes:
* A ``ShootingRangeSelector`` subclass of ``openpathsampling.ShootingPointSelector`` to pick shooting points only in the predefined shooting range volume.
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 and sr_shooter use the `nose`_ package.
.. IF YOUR MODULE IS IN A SEPARATE REPOSITORY
To test this module you need to first install OpenPathSampling, then download the source files for this package (see the ``Source Code`` section below) and install it using
``python setup.py install`` or ``pip install -e .`` from the root directory of the package.
In the root folder then type ``nosetests`` to test the module using the `nose`_ package.
Examples
________
| 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).
Source Code
___________
The source code for this module can be found in https://gitlab.e-cam2020.eu/hejung/sr_shooter.
.. CLOSING MATERIAL -------------------------------------------------------
.. Here are the URL references used
.. _nose: http://nose.readthedocs.io/en/latest/
.. _openpathsampling.Volume: http://openpathsampling.org/latest/volume.html
......@@ -25,7 +25,7 @@ Introduction
This is a collection of the modules that have been created by E-CAM community within the area of Electronic Structure. This documentation is created using ReStructured Text and the git repository for the documentation
source files can be found at
https://gitlab.e-cam2020.eu/e-cam/Electronic-Structure-Modules which are
https://gitlab.e-cam2020.eu/e-cam/E-CAM-Library which are
public and open to contributions.
In the context of E-CAM, the definition of a software module is any piece of software that could be of use to the E-CAM community and that encapsulates some additional functionality, enhanced performance or improved usability for people performing computational simulations in the domain areas of interest to us.
......
......@@ -27,7 +27,7 @@ This is a collection of the modules that have been created by E-CAM community
within the area of Meso- and Multi-scale Modelling. This documentation is
created using ReStructured Text and the git repository for the documentation
source files can be found at
https://gitlab.e-cam2020.eu/e-cam/Meso-Multi-Scale-Modelling-Modules which are
https://gitlab.e-cam2020.eu/e-cam/E-CAM-Library which are
public and open to contributions.
In the context of E-CAM, the definition of a software module is any piece of software that could be of use to the E-CAM community and that encapsulates some additional functionality, enhanced performance or improved usability for people performing computational simulations in the domain areas of interest to us.
......
......@@ -9,6 +9,7 @@
Quantum Dynamics Modules
************************
Introduction
============
......@@ -23,17 +24,17 @@ Introduction
:width: 30 %
:align: left
This is a collection of the modules that have been created by E-CAM community
within the area of Quantum Dynamics. This documentation is created using ReStructured Text and the git repository for the documentation
source files can be found at
This is a collection of the modules that have been created by the E-CAM community
within the area of Quantum Dynamics. This documentation is created using ReStructured Text and the git repository for the documentation.
Source files can be found at
https://gitlab.e-cam2020.eu/e-cam/E-CAM-Library which are open to contributions from E-CAM members.
In the context of E-CAM, the definition of a software module is any piece of software that could be of use to the E-CAM
community and that encapsulates some additional functionality, enhanced performance or improved usability for people
performing computational simulations in the domain areas of interest to us.
performing computational simulations in the domain areas of interest to the project.
This definition is deliberately broader than the traditional concept of a module as defined in the semantics of most
high-level programming languages and is intended to capture inter alia workflow scripts, analysis tools and test suites
high-level programming languages and is intended to capture internal workflow scripts, analysis tools and test suites
as well as traditional subroutines and functions. Because such E-CAM modules will form a heterogeneous collection we
prefer to refer to this as an E-CAM software repository rather than a library (since the word library carries a
particular meaning in the programming world). The modules do however share with the traditional computer science
......@@ -44,19 +45,21 @@ codes rather than being written entirely de novo.
Perhaps more important than exactly what a module is, is how it is written and used. A final E-CAM module adheres to
current best-practice programming style conventions, is well documented and comes with either regression or unit tests
(and any necessary associated data). E-CAM modules should be written in such a way that they can potentially take
advantage of anticipated hardware developments in the near future (and this is one of the training objectives of E-CAM).
advantage of anticipated hardware developments in the near future (this is one of the training objectives of E-CAM).
Objectives of E-CAM WP3 Quantum Dynamics
========================================
Software development in quantum dynamics has so far been less systematic than in other fields of modelling,
such as classical molecular dynamics or electronic structure. Although some packages have been developed to
implement specific methods, e.g. Quantics_ for dynamics with MCTDH, or subroutines added to electronic structure
implement specific methods, e.g. `Quantics <http://chemb125.chem.ucl.ac.uk/worthgrp/quantics/doc/index.html>`_
for wave packet dynamics, or subroutines added to electronic structure
packages, e.g. Surface Hopping and Ehrenfest in CPMD_, these efforts are not the standard.
One of the goals of E-CAM's WP3 is then to provide an environment to stimulate the transition from in-house
codes, often developed and used by single groups, to the development of modular, well documented community-based
software packages capable of multiple functionalities and adopting the common set of standards and benchmarks.
software packages capable of multiple functionalities and adopting a common set of standards and benchmarks.
To foster this development, we have initiated five parallel activities:
......@@ -70,12 +73,24 @@ To foster this development, we have initiated five parallel activities:
* Training young code developers.
.. _Quantics: http://chemb125.chem.ucl.ac.uk/worthgrp/quantics/doc/index.html
.. _CPMD: http://www.cpmd.org/
Pilot Projects
==============
One of primary activity of E-CAM is to engage with pilot projects with industrial partners. These projects are conceived
together with the partner and typically are to facilitate or improve the scope of computational simulation within the
partner. The related code development for the pilot projects are open source (where the licence of the underlying
software allows this) and are described in the modules associated with the pilot projects.
The `pilot project <https://www.e-cam2020.eu/pilot-project-ibm/>`_ of the WP3 in collaboration with IBM_ is
related to quantum computing and improvements of the quantum computer technology.
One of our main topic was development of software for construction of control pulses necessary for operating quantum logical gates
between qubits in a universal quantum computer using the Local Control Theory. [PLCT]_
More information can be found on the `pilot project <https://www.e-cam2020.eu/pilot-project-ibm/>`_ web site.
Below are listed the pilot project modules created so far:
.. toctree::
:glob:
:maxdepth: 1
......@@ -91,12 +106,8 @@ Pilot Projects
./modules/OpenQubit/readme
**OpenQubit** is an extension to the LocConQubit code for the construction of controlled pulses in a more realistic environment with
disipating effects.
dissipating effects.
One of primary activity of E-CAM is to engage with pilot projects with industrial partners. These projects are conceived
together with the partner and typically are to facilitate or improve the scope of computational simulation within the
partner. The related code development for the pilot projects are open source (where the licence of the underlying
software allows this) and are described in the modules associated with the pilot projects.
Extended Software Development Workshops
=======================================
......@@ -105,7 +116,7 @@ ESDW Maison de la Simulation (Paris 2016)
-----------------------------------------
The first Quantum Dynamics ESDW was held in June-July 2016 at the `Maison de la Simulation`_ near Paris. 10 students
and 6 tutors, including Dr. Ivano Tavernelli representing the industrial partner of the WP3, IBM, worked to develop
and 6 tutors, including Dr. Ivano Tavernelli representing the industrial partner of the WP3, IBM_, worked to develop
software modules in the following areas:
- Exact quantum propagation methods for low dimensional systems to be used to provide benchmarks for approximate schemes
......@@ -122,7 +133,7 @@ centered on presentations made by the students and the senior participants. The
development, including the Git repository, and tools for the documentation (Doxygen) and performance analysis
were presented by E-CAM staff members and participants were instructed on their use via tutorials.
The program was further enriched by the interactions with experts on software and hardware development working
at La Maison de la Simulation who gave talks on topics such as architectures and programming paradigms and the
at Maison de la Simulation who gave talks on topics such as architectures and programming paradigms and the
use of advanced visualization tools such as the Image wall hosted by the Maison de la Simulation.
.. _Maison de la Simulation: http://www.maisondelasimulation.fr/en/index.php?a
......@@ -130,7 +141,36 @@ use of advanced visualization tools such as the Image wall hosted by the Maison
ESDW University College Dublin (2017)
-------------------------------------
The second Quantum Dynamics ESDW was held in July 2017 at the University College Dublin.
The second Quantum Dynamics ESDW was held in July 2017 (first part) and March 2018 (wrap up meeting) at
`University College Dublin <http://www.ucd.ie/>`_. 21 participants, including the representative of WP3’s
current industrial partner IBM_, worked to develop and upload on the E-CAM repositories software
modules in the following areas:
- Calculation of approximate quantum time correlation functions via the PaPIM code;
- Mixed quantum-classical algorithms, with specific reference to Surface Hopping and Wigner-Liouville methods;
- Implementation of the factorization scheme for quantum dynamics in CPMD_;
- Interfacing of quantum codes with electronic structure codes;
- Grid based exact propagation schemes;
- Design and optimization of qubit control pulses.
Teams of coders assisted by senior tutors, E-CAM’s Software Manager, Dr. Alan O’Cais, and WP3 Software
Developer, Dr. Liang Liang, performed the work.
Specific discussions on optimal parallelization strategies for the E-CAM’s quantum dynamical codes
(PaPIM and Quantics) were also initiated and implemented.
The coding work was accompanied by scientific presentations on the themes of the workshops and by
the instruction from E-CAM personnel on the CoE’s tools for software production, testing, documentation
and maintaining.
The participants benefitted also from the proximity of software and hardware experts from the
`ICHEC <https://www.ichec.ie/>`_ supercomputing center that offered, in particular, a set of
lectures and tutorials on OpenMP parallelization.
.. _IBM: https://www.zurich.ibm.com/
List of available Modules
=========================
......@@ -142,7 +182,7 @@ List of available Modules
./modules/SODLIB/sod_readme
The **SodLib** module provides exact wavefunction propagation using the second-order differencing (SOD) integrator
scheme to solve the time-dependent Schroedinger equation. This routine has been implemented and tested as an added
scheme to solve the time-dependent Schrödinger equation. This routine has been implemented and tested as an added
functionality within the Quantics_ quantum dynamics package.
.. toctree::
......@@ -163,19 +203,28 @@ routine has been implemented and tested as an added functionality within the Qu
The **PhysConst** enables the use of physical constants and the correct isotopic masses.
.. toctree::
:glob:
:maxdepth: 1
./modules/QuantumModelLib/readme
The **QuantumModelLib** use potential energy surfaces extracted from the literature and can be linked to quantum dynamics codes.
PaPIM
-----
PaPIM is a code for calculation of equilibrated system properties (observables). Some properties can be directly obtained from
the sampled system distribution function, while properties that depends on the exact dynamics of the system, such as the structure
factor, [Mon2]_ infrared spectrum [Beu]_ or reaction rates, can be easily obtained from corresponding correlation functions.
PaPIM code samples either the quantum (Wigner) or classical (Boltzmann) density functions and calculates the corresponding correlation
functions. The code is highly parallelized which makes it suitable for use on large HPC machines.
The code's modular structure enables an easy update/change of any of its modules as well as that the coded functionalities
can be used independently of each other.
the distribution function of the system, while properties that depends on the exact dynamics of the system, such as the structure
factor, [Mon2]_ infrared spectrum [Beu]_ or reaction rates, can be obtained from the evolution of appropriate time correlation functions.
PaPIM samples either the quantum (Wigner) or classical (Boltzmann) density functions and computes approximate quantum and
classical correlation functions.
The code is highly parallelized and suitable for use on large HPC machines.
The code's modular structure enables an easy update/change of any of its modules.
Furthermore the coded functionalities can be used independently of each other.
The code is specifically design with simplicity and readability in mind to enable any user to easily implement its own functionalities.
The code has been extensively used for the calculation of the infrared spectrum of the :math:`\text{CH}_{5}^{+}` cation in gas phase,
while recently new calculations on water dimer, and protonated water dimer systems were started.
while recently new calculations on the water dimer, and protonated water dimer systems were started.
.. toctree::
......@@ -184,11 +233,13 @@ while recently new calculations on water dimer, and protonated water dimer syste
./modules/PaPIM/readme
**PaPIM** is the current version of the code with all included functionalities.
**PaPIM** is the current version of the code, including all available functionalities.
The following modules make up the PaPIM code and can be used as stand-alone software libraries for e.g. sampling of the Wigner distribution,
sampling of the classical Boltzmann distribution, or building MPI parallelized Fortran codes. Such libraries are rarely available to the community in a Fortran program format.
Some of the functionalities coded within the code are specifically design for computation of infrared spectra, and serve as a template
The following modules make up the PaPIM code and can be used as stand-alone software libraries for e.g.
sampling of the Wigner distribution, sampling of the classical Boltzmann distribution, or building MPI
parallelized Fortran codes.
Such libraries are rarely available to the community in a Fortran program format.
Some of the functionalities within the code are specifically designed for computation of infrared spectra, and serve as a template
for the user to implement its own functionalities.
......@@ -198,8 +249,8 @@ for the user to implement its own functionalities.
./modules/PIM_wd/readme
**PIM_wd** samples, via the Phase Integration Method, [Mon1]_ the system's quantum Wigner density distribution function. The distribution is
given in the phase-space representation and is the basis for any further calculation of system's quantum observables.
**PIM_wd** samples, via the Phase Integration Method, [Mon1]_ the system's quantum Wigner density function.
The function is given in the phase-space representation and is the basis for any further calculation of system's quantum observables.
.. toctree::
......@@ -231,7 +282,9 @@ Results obtained from classical sampling can be used to assess the relevance of
**PotMod** is a library of potential energy functions and interfaces for external potential energy calculation codes.
Currently available in the library are the harmonic and Morse potentials (different molecular systems can be simulated depending on parameters
provided by the user); empirical potential of the ground state of :math:`\text{CH}_{5}^{+}` based on high level
electronic structure calculations [Jin]_, and interface to the ab initio CP2K_ code.
electronic structure calculations [RJin]_.
.. , and interface to the ab initio `CP2K code <https://www.cp2k.org/>`_.
.. _CP2K: https://www.cp2k.org/
......@@ -253,20 +306,22 @@ It also contains a library of adapted MPI subroutines for easier programming of
./modules/Openmpbeads/readme
**Openmpbeads** is a patch to the PaPIM code which enables parallelization of the sampling of the
polyer chains within the PIM algorithm.
polymer chains within the PIM algorithm, improving efficiency in sampling of the Wigner density.
References
==========
.. [Mon1] M. Monteferrante, S. Bonella, G. Ciccotti `Linearized symmetrized quantum time correlation functions calculation via phase pre-averaging`_ *Mol. Phys.* **109** (2011) 3015
.. [Mon2] M. Monteferrante, S. Bonella, G. Ciccotti `Quantum dynamical structure factor of liquid neon via a quasiclassical symmetrized method`_ *J. Chem. Phys.* **138** (2013) 054118
.. [Beu] J. Beutier, M. Monteferrante, S. Bonella, R. Vuilleumier, G. Ciccotti `Gas phase infrared spectra via the phase integration quasi-classical method`_ *Mol. Sim.* **40** (2014) 196
.. [Jin] Jin, Braams, Bowman `An ab Initio Based Global Potential Energy Surface Describing :math:'\text{CH}_{5}^{+} \rightarrow \text{CH}_{3}^{+} + \text{H}_{2}'`_ *J. Phys. Chem. A* **110** (2006) 1569
.. _Linearized symmetrized quantum time correlation functions calculation via phase pre-averaging: http://dx.doi.org/10.1080/00268976.2011.619506
.. _Quantum dynamical structure factor of liquid neon via a quasiclassical symmetrized method: http://dx.doi.org/10.1063/1.4789760
.. _Gas phase infrared spectra via the phase integration quasi-classical method: http://dx.doi.org/10.1080/08927022.2013.843776
.. _An ab Initio Based Global Potential Energy Surface Describing :math:'\text{CH}_{5}^{+} \rightarrow \text{CH}_{3}^{+} + \text{H}_{2}': pubs.acs.org/doi/abs/10.1021/jp053848o
.. Jin, Braams, Bowman `An ab Initio Based Global Potential Energy Surface Describing :math:'\text{CH}_{5}^{+} \rightarrow \text{CH}_{3}^{+} + \text{H}_{2}'`_ *J. Phys. Chem. A* **110** (2006) 15
.. _E-CAM: https://www.e-cam2020.eu/
.. [PLCT] B. F. E. Curchod, T. J. Penfold, U. Rothlisberger, I. Tavernelli *Phys. Rev. A*
**84** (2012) 042507 `DOI: 10.1103/PhysRevA.84.042507
<https://journals.aps.org/pra/abstract/10.1103/PhysRevA.84.042507>`_
.. [Mon1] M. Monteferrante, S. Bonella, G. Ciccotti *Mol. Phys.* **109** (2011) 3015 `DOI: 10.1080/00268976.2011.619506
<http://dx.doi.org/10.1080/00268976.2011.619506>`_
.. [Mon2] M. Monteferrante, S. Bonella, G. Ciccotti *J. Chem. Phys.* **138** (2013) 054118 `DOI: 10.1063/1.4789760
<http://dx.doi.org/10.1063/1.4789760>`_
.. [Beu] J. Beutier, M. Monteferrante, S. Bonella, R. Vuilleumier, G. Ciccotti *Mol. Sim.* **40** (2014) 196 `DOI:
10.1080/08927022.2013.843776 <http://dx.doi.org/10.1080/08927022.2013.843776>`_
.. [RJin] Z. Jin, B. Braams, J. Bowman *J. Phys. Chem. A* **110** (2006) 1569 `DOI: 10.1021/jp053848o
<https://pubs.acs.org/doi/abs/10.1021/jp053848o>`_
.. _auxmod:
####################
AuxMod module
####################
######
AuxMod
######
.. sidebar:: Software Technical Information
......@@ -22,13 +22,13 @@ Purpose of Module
_________________
Module **AuxMod** contains a set of subroutines which can be used for an easier construction of any program
input file reader subroutines potentially encountered when building a new Fortran code,
input file reader,
and a library of common MPI commands adapted for easier implementation when programming a Fortran MPI parallel code.
The module consists of an input parser design to read any formatted file
The module consists of an input parser designed to read any formatted file
with the possibility to find a specific set of user pre-defined keywords
and examine whether the read in variable types are consistent with the required before passing them further.
and examine whether the read in variable types are consistent with the code requirments.
The library of parallel subroutines contains a number of MPI commands for communicating information between all or
a pair of processor cores, and are adapted in a way for easier user implementation into his/her own code.
a pair of processor cores, and are adapted for easier user implementation into his/her own code.
The provided subroutines/libraries can also be considered as a Fortran template which the user can adapt or
update depending on his/her specific requirements.
......@@ -36,8 +36,9 @@ update depending on his/her specific requirements.
Applications of the Module
__________________________
The AuxMod module was used to construct the input parser for the PaPIM code, while its modified MPI commands to
parallelize the PaPIM code and the ClassMC module. Following these example, the AuxMod provides a pre-constructed
The AuxMod module was used to construct the input parser for the PaPIM code, while its modified MPI commands enable to
parallelize the PaPIM code and the ClassMC module.
Based on these example, the AuxMod provides a pre-constructed
input reader and adapted MPI library for any future Fortran code development.
......@@ -54,17 +55,14 @@ Execute command ``make`` in the ``./source`` sub-directory to generate the ``Aux
make
For AuxMod test purposes the ``numdiff`` package should be made available before running the tests.
In case numdiff is not available on the system the ``diff`` command will be automatically used instead.
The user is advised to download and install numdiff from here_ to ensure that numerical
differences are ignored in the module tests.
.. _here: http://www.nongnu.org/numdiff/
Testing
_______
For AuxMod test purposes the ``numdiff`` package is used for automatic comparison purposes and should be made
available before running the tests, otherwise the ``diff`` command will be used automatically instead but the user
is warned that the test might fail due to numerical differences.
The user is advised to download and install ``numdiff`` from `here <http://www.nongnu.org/numdiff/>`_.
The module is accompanied with an example input file ``TESTINPUT`` located in the ``tests`` sub-directory
together with the reference output in sub-directory ``REFERENCE_OUTPUT``:
......@@ -74,16 +72,13 @@ together with the reference output in sub-directory ``REFERENCE_OUTPUT``:
../source/AuxModRun.exe < TESTINPUT
Before running the test the numdiff package used for comparison purposes should be made available,
otherwise the diff command will be used instead but the user is warned that the test might fail
due to numerical differences.
The user is also advised to test the code manually by changing the values in the ``TESTINPUT`` input file.
Source Code
___________
The source code is given at https://gitlab.e-cam2020.eu/Quantum-Dynamics/PIM/tree/AuxMod/source.
The source code is given at https://gitlab.e-cam2020.eu/Quantum-Dynamics/PIM/tree/AuxMod.
The file ``parser.F90`` contains all the subroutines for the within-one-line data type recognition,
while the ``auxmod.F90`` contains the direct subroutines for input file reading,
and can be considered as a template for further modification.
......@@ -93,8 +88,8 @@ The ``prl.F90`` contains the adapted MPI commands.
Source Code Documentation
_________________________
The source code documentation is given at https://gitlab.e-cam2020.eu:10443/Quantum-Dynamics/PIM/tree/AuxMod/doc .
The documentation files (html and latex format) are obtained by executing the ``make`` command in the ./doc sub-directory:
The source code documentation is given at https://gitlab.e-cam2020.eu:10443/Quantum-Dynamics/PIM/tree/AuxMod/doc.
The documentation files (html and latex format) are obtained by executing the ``make`` command in the ``./doc`` sub-directory:
::
......
......@@ -17,21 +17,11 @@ ClassMC
.. contents:: :local:
.. This is an example of what a *module* for E-CAM looks like. Please add to this template any additional items that are
.. straightforward to fill out in the general case. You are free add any level of complexity you wish (within the bounds of
.. what ReST_ can do).
.. To add your module, fork this GitLab repository to your account on GitLab. Clone your repository, make a feature branch
.. and add a directory that will contain your module information. Copy this :download:`readme.rst` file there. Push your
.. changes back to GitLab and immediately open a merge request from your feature branch against our repository. We can
.. discuss your module in the merge request and help you get it accepted.
.. Add technical info as a sidebar and allow text below to wrap around it
Purpose of Module
_________________
Module ClassMC samples the system phase space using the classical Boltzmann distribution function and calculates the
Module **ClassMC** samples the system phase space using the classical Boltzmann distribution function and calculates the
time correlation functions from the sampled initial conditions.
The sampling is achieved by the Monte Carlo Metropolis algorithm.
The corresponding system properties can be calculated from the sampled phase space with appropriate operators.
......@@ -39,10 +29,10 @@ The sampled phase space points can be propagated in time using classical molecul
evolution of the system and calculate the corresponding correlation functions.
Currently the electric dipole moment operator is implemented for the calculation of electric dipole moment autocorrelation
functions from which system IR spectra can be directly obtained.
The system potential energy and electric dipole moment are calculated using external subroutines provided by the user.
Example external subroutines are provided for the :math:`\text{OH}` and :math:`\text{CH}_{4}` systems, respectively, whose corresponding
potential energies are described by the harmonic potential,
while the electric dipole moments by point charge approximation. An external subroutines for calculation of
The system potential energy is calculated using external subroutines provided by the user.
Example external subroutines are provided for the :math:`\text{OH}` and :math:`\text{CH}_{4}` systems, with
potential energies are described by an harmonic potential,
and the electric dipole moments by point charge approximation. An external subroutines for calculation of
:math:`\text{CH}_{5}^{+}` system potential energy and electric dipole moment, based on fitted values, is also given.
......@@ -60,8 +50,8 @@ redshift of C-H stretching bands and the overall shape of the infrared spectrum.
Compiling
_________
Fortran compiler with a MPI wrapper together with lapack libraries have to be available to successfully compile the code.
The user is advise to examine the Makefile in the ``./source``` sub-directory prior to code compilation in order to
Fortran compiler with a MPI wrapper together with ``lapack`` libraries have to be available to successfully compile the code.
The user is advised to examine the ``Makefile`` in the ``./source``` sub-directory prior to code compilation in order to
select an appropriate compiler and to check or adapt the compiler options to his local environment, or to generally
modify the compiler options to his requirements.
Upon adapting the ``Makefile``, the code compilation is executed by command ``make`` in the ``./source`` sub-directory:
......@@ -73,24 +63,19 @@ Upon adapting the ``Makefile``, the code compilation is executed by command ``ma
make
An executable ``ClassMCRun.exe`` is created upon successful compilation.
For ClassMC test purposes the ``numdiff`` package should be made available before running the tests.
In case the numdiff is not available on the system the ``diff`` command will be automatically used instead.
The user is advise to download and install numdiff from here_.
The ClassMC documentation is obtained by executing the ``make`` command in the ./doc directory.
.. _here: http://www.nongnu.org/numdiff/
Testing
_______
For ClassMC test purposes the ``numdiff`` package is used for automatic comparison purposes and should be made
available before running the tests, otherwise the ``diff`` command will be used automatically instead but the user
is warned that the test might fail due to numerical differences.
The user is advised to download and install ``numdiff`` from `here <http://www.nongnu.org/numdiff/>`_.
Tests and corresponding reference values are located in sub-directories ``./tests/xxx/CLASSICAL``, where ``xxx`` stands
for ``oh``, ``ch4``, and ``ch5`` systems.
Before running the tests the module ClassMC has to be properly compiled by running the ``make`` command in the
``./source`` sub-directory.
The numdiff package is used for comparison purposes and should be made available before running the tests,
otherwise the diff command will be used automatically instead but the user is warned that the test might fail
due to numerical differences.
Tests can be executed automatically by running the command ``./test.sh`` in the ``./tests`` sub-directory
for all three systems, or separately for each system by running the command ``./test.sh`` within the corresponding
system ``CLASSICAL`` sub-directory:
......@@ -101,25 +86,27 @@ system ``CLASSICAL`` sub-directory:
./test.sh [number of cores]
Tests are by default executed on two processor cores and this can be changed by setting the value of required
Tests are by default executed on two processor cores.
This can be changed by setting the value of required
cores as an integer number after the command ``./test.sh`` (example ``./test.sh 20``, for the use of 20 processor
cores in the test). The number of processor cores should not exceed 50.
cores in the test).
The number of processor cores should not exceed 50.
Due to small numerical discrepancies between generated outputs and reference values which can cause the tests to fail,
the user is advise to manually examine the numerical differences between generated output and the corresponding
the user is advised to manually examine the numerical differences between generated output and the corresponding
reference values in case the tests fail.
Source Code
___________
The ClassMC module source code is located at: https://gitlab.e-cam2020.eu/Quantum-Dynamics/PIM/tree/ClassMC/source.
The ClassMC module source code is located at: https://gitlab.e-cam2020.eu/Quantum-Dynamics/PIM/tree/ClassMC.
Source Code Documentation
_________________________
The source code documentation is given at https://gitlab.e-cam2020.eu/Quantum-Dynamics/PIM/tree/ClassMC/doc.
The documentation files (html and latex format) are obtained by executing the ``make`` command in the ./doc directory:
The documentation files (html and latex format) are obtained by executing the ``make`` command in the ``./doc`` directory:
::
......
......@@ -17,21 +17,11 @@ LocConQubit
.. contents:: :local:
.. This is an example of what a *module* for E-CAM looks like. Please add to this template any additional items that are
.. straightforward to fill out in the general case. You are free add any level of complexity you wish (within the bounds of
.. what ReST_ can do).
.. To add your module, fork this GitLab repository to your account on GitLab. Clone your repository, make a feature branch
.. and add a directory that will contain your module information. Copy this :download:`readme.rst` file there. Push your
.. changes back to GitLab and immediately open a merge request from your feature branch against our repository. We can
.. discuss your module in the merge request and help you get it accepted.
.. Add technical info as a sidebar and allow text below to wrap around it
Purpose of Module
_________________
LocConQubit is a code for constructing controlled pulses on isolated qubit systems that can either drive the population
**LocConQubit** is a code for constructing controlled pulses on isolated qubit systems that can either drive the population
between specific qubit states or work as a logical gates between qubits.
LocConQubit implements the Local Control Theory (LCT) which generates the required pulses on-the-fly.
The generated pulses can be further post-processed with a variety of tools accompanying the LocConQubit module in order
......@@ -42,7 +32,7 @@ Local Control Theory (LCT)
______________________________
In general Local Control Theory is an on-the-fly procedure for updating the time-dependent Hamiltonian (:math:`\hat{H}(t)`) to achieve
a population transfer from some initial quantum state to a designated quantum target state (:math:`| \psi \rangle`). [LCT1]_ [LCT2]_
population transfer from some initial quantum state to a designated quantum target state (:math:`| \psi \rangle`). [LCT1]_ [LCT2]_
LCT achieves its full capacity if the time-dependent component of the full system Hamiltonian :math:`\hat{H}(t)` can be decomposed as an external perturbation
(:math:`V^{\prime}(t) \times \hat{H}^{\prime}`) acting on a system with a time-independent Hamiltonian (:math:`\hat{H}_{0}`),
......@@ -58,7 +48,7 @@ LCT in this case constructs a time-dependent perturbation :math:`V^{\prime}(t)`
which will achieve the required population transfer from any initial state to the :math:`| \psi \rangle` target state.
The new time-dependent potential component :math:`V^{\prime}(t)` updates the time-dependent component of the full Hamiltonian
describing the evolution of the system with the time-dependent Schrödinger equation
describing the evolution of the system via the time-dependent Schrödinger equation
:math:`i \frac{\partial}{\partial t} |\Psi(t)\rangle = \hat{H}(t) |\Psi(t) \rangle`.
......@@ -74,24 +64,22 @@ The schematic below illustrates the LCT procedure.
Applications of the Module
__________________________
Application of the LCT module can be found at the `pilot project web page <https://www.e-cam2020.eu/pilot-project-ibm/>`_ .
Application of the LCT module can be found at the `pilot project web page <https://www.e-cam2020.eu/pilot-project-ibm/>`_.