The JeLLyFysh Python application implements the event-chain Monte Carlo algorithm (ECMC), an event-driven irreversible Markov-chain Monte Carlo algorithm for classical N-body simulations in statistical mechanics, biophysics and electrochemistry. The application's architecture closely mirrors the mathematical formulation of ECMC. For a detailed description of the design of this application, see [Hoellmer2019]. For a closely connected discussion of ECMC, see [Faulkner2018]. (See the References.bib file.)
The JeLLyFysh Python application can be executed with any Python implementation which supports Python version >= 3.5. It is tested with cPython and PyPy version >= 7. A limited amount of modules depends on non standard library Python packages. Take a look at our external dependencies to see which parts of JeLLyFysh can only be used after additional packages have been installed.
JeLLyFysh is readily installed just by cloning this repository.
To run the tests, simply enter the unittests directory and run run_tests.py
with your Python implementation. These tests may take a while.
The user interface for each run of the JeLLyFysh application consists in a configuration file that is an argument of the
run.py script, which is located in the src directory. Configuration files should follow the
INI-file format.
The run.py script expects the path to the configuration file as the first positional argument. The script also takes
optional arguments. These are:
-h,--help: Show the help message and exit.-V,--version: Show program's version number and exit.-v,--verbose: Increase verbosity of logging messages (multiple -v options increase the verbosity, the maximum is 2).-l LOGFILE,--logfile LOGFILE: Specify the logging file.
A configuration file is composed of sections that each correspond to a class of the JeLLyFysh application. The only required section for the run script is
[Run]
mediator = some_mediator
setting = some_settingsome_mediator corresponds the the used mediator in the run. The mediator serves as a central hub in the application
and also hosts the iteration loop over the legs of the continuous-time evolution of ECMC. The two possible mediators are
single_process_mediator, which runs the application in a single process,
and multi_process_mediator, which calculates the
events of ECMC in separate processes. Both are located in the src/mediator package. Currently we
recommend the single-process version.
setting specifies the NVT physical parameters of the run. The two possible settings are
hypercubic_setting and
hypercuboid_setting (both located in the src/setting package).
The following sections of the configuration file choose the parameters in the __init__ methods of the mediator and the
setting. Each section contains pairs of properties and values. The property corresponds to the name of the argument in
the __init__ method of the given class, and its value provides the arguments. Properties and values should be given in
snake_case, sections in CamelCase. For a detailed description of the JeLLyFysh factory, which parses the configuration
file and constructs the specified classes, see here. There, also a detailed example for the interplay
between the factory and a configuration file is given. All classes of JeLLyFysh are documented with docstrings to
clarify their usage. For a general overview of the parts of JeLLyFysh, see
[Hoellmer2019].
Some example configuration files are located in the
src/config_files/2018_JCP_149_064113 directory. They are described in detail in
the "Cookbook" section (Section 5) of [Hoellmer2019]. They
generate output in the src/output/2018_JCP_149_064113 directory.
Instances of the event-handler classes in the JeLLyFysh application compute candidate events. Hints on how to implement your own event handlers are given here (see [Hoellmer2019] for details).
As an open-source project, the JeLLyFysh organization solicits contributions from the community. Please read the contribution guideline for details.
If you find a bug, please raise an Issue here on GitHub to let us know.
Please note that this project is released with the Contributor Covenant code of conduct. By participating in this project you agree to abide by its terms. Report unacceptable behavior to werner.krauth@ens.fr.
Versioning of the JeLLyFysh project adopts two-to-four-field version numbers defined as Milestone.Feature.AddOn.Patch. The current version 1.0 represents the first development milestone which reproduces published data in [Faulkner2018]. Patches and bugfixes of this version will be given number 1.0.0.1, 1.0.0.2 etc. New configuration files and required extensions are expected to lead to versions 1.0.1, 1.0.2 etc. In JeLLyFysh development, two-field versions (2.0, 3.0, etc.) may introduce incompatible code, while three- and four-field version numbers are intended to be backward compatible.
Check the AUTHORS.md file to see who participated in this project.
This project is licensed under the GNU General Public License, version 3 (see the LICENCE file).
If you have questions regarding the JeLLyFysh application, just raise an issue here on GitHub. We are happy to help you!
If you use JeLLyFysh in published work, please cite the following reference (see [Hoellmer2019] in References.bib):
Philipp Höllmer, Liang Qin, Michael F. Faulkner, A. C. Maggs, Werner Krauth.
JeLLyFysh-Version1.0 -- a Python application for all-atom event-chain Monte Carlo,
arXiv e-prints: 1907.12502 (2019), https://arxiv.org/abs/1907.12502