This package provides a Python front-end and efficient C-implementation of the key algorithms described in:
William M. Jacobs, Aleks Reinhardt and Daan Frenkel, "Theoretical prediction of free-energy landscapes for complex self-assembly," J. Chem. Phys. 142, 021101 (2015).
William M. Jacobs, Aleks Reinhardt and Daan Frenkel, "Rational design of self-assembly pathways for complex multicomponent structures," Proc. Natl. Acad. Sci. U.S.A. (2015).
A collection of example structures, including all structures described in the above papers, is provided in the examples directory.
Use of this package is permitted in accordance with the terms of the included LICENSE file.
This package uses the standard GNU autotools build system.
PLEASE NOTE: To obtain the release version (recommended for simple installation), please download and unpack the tarball from the release branch.
Before installing, please ensure that you have the following dependencies installed on your system:
- Python (version 3 and above)
- numpy for python3
- networkx for python3
- GSL (GNU scientific library)
Installation can usually be completed by running the following commands:
./configure
make
sudo make install
The installation target should install the pygtsa package in your Python
version's site-packages directory. See ./configure --help for
information on customization flags and influential environment variables.
To execute a calculation script, run e.g.
python3 -m pygtsa.calc_subgraphs input_edge_list
Currently, the available calculation scripts are:
- calc_subgraphs (for computing the fragment density of states)
- calc_energies (for computing the effective mean bond energies)
- calc_yield (for computing the on-pathway yield as a function of bond strength)
- calc_fe_profile (for computing a free-energy profile at a fixed bond strength)
- calc_barrier (for computing the nucleation barrier as a function of bond strength)
- calc_incidental (for computing off-pathway dimers at a fixed bond strength)
A detailed list of the required arguments for each command can be found by running e.g.
python3 -m pygtsa.calc_subgraphs --help
Input structure files can either list the graph edges, one per line, or use the graphviz DOT format. To convert between these two formats, use the pygtsa.structure utility. Example input structures (named edges.dat) and output files can be found in the examples directory.
As with any sampling-based tool, the performance and convergence of a calculation depends on the choice of a large number of parameters. The default parameters should work well for the structures provided in the examples directory. Key convergence parameters include:
- fmin (cgraph.pyx; convergence target for the Wang--Landau algorithm)
- flatness (cgraph.pyx; histogram flatness threshold for the Wang--Landau algorithm)
- nsteps (calc_subgraphs.py; number of Monte Carlo steps between samples)
- nsamples (calc_subgraphs.py; total number of samples)
See the source code for further information.
Changes can be made directly to the pure Python (.py) files and installed using make install. Changing the C source code or Python wrappers (.pyx,.pxd) requires running Cython on the .pyx files before running make. Adding or removing files to the package requires using GNU autotools.