The source code is written in Fortran compliant with the 2008 standard. There is a dependency on the Intel Math Kernel Library (MKL). I have compiled the code with gfortran-8.3 compiler and MKL 2019 Update 4.
The simplest way is to clone the repo from GitHub.
git clone https://github.com/saridut/brownpak.git brownpak
This will download the source files in the directory brownpak. Otherwise a zip archive containing the source can also be downloaded directly from the GitHub repo.
The directory structure is as follows:
The makefile build/Makefile can be used to compile and install the executable brownpak in the bin directory. Be aware that the libray nitsol.a may need to be compiled separately and put in lib. The variables MKLROOT and MKL_INTRFC may need to be changed depending on the machine. Some of the programs in utilies have separate makefiles and also need to be compiled.
Run the executable thus:
brownpak fn_control=<str> job_tag=<int>
Both the arguments fn_control and job_tag are optional.
If you do not specify the name of the control file, it will be assumed to be
control.txt. The job_tag argument is there to help running array jobs on a
cluster. For example, with SGE job scheduler I can request array jobs numbered
from 1-16 and specify job_tag=$SGE_TASK_ID. Then all output files will have
the numbers 1-16 appended to their file names, like traj.bin.1, traj.bin.2, etc.
Instead to running the executable from bin, you can run it from some other directory as
path_to_bin/brownpak fn_control=controlfile.txt job_tag=some_number
The above is more convenient with running multiple jobs on a cluster.
brownpak reads several input files and produces several output files. The input files are:
fn_control: This file contains various directives on what simulation to
run, time steps, etc. The directives are provided as a list of key-value
pairs. The default name for this file is control.txt.fn_cfg: This is specified in fn_control. This file contains the
configuration of the system of be simulated, i.e. atom positions,
interactions, etc. The extension for this file is .cfg, though it is not
mandatory.The output files are:
fn_traj: This is a binary file containing the trajectory data. These have
extension of .bin, though not mandatory.fn_stats: This is a text file containing a minimal set of statistics.
Further statistics may be obtained by post processing fn_traj. During
equilibration, the statistics will be written to a file called fn_stats.eq.Here is a sample control file. It is called `control.txt.
# Global cutoff
rcutoff 2.245D0
# Verlet skin thickness
tskin 2.1D0
# Pairlist generation method: 'VER' | 'CL' | 'AABBT' | 'N2'
# 'VER': Verlet list, 'CL': Cell list, 'AABBT': AABB tree, 'N2': Direct N^2
mth_ptgen VER
# Switch off electrostatics? {T, F}. Not implemented.
lelst F
# Switch off pairwise interactions? {T, F}
lvdw T
# Switch off hydrodynamics interactions? {T, F}
lhdia T
# Exclude nearest bonded atoms? 1: bonds, 2: angles, 3: dihedrals
excluded_atoms 1
# Factorization method for mobility matrix. {'CHOL': Cholesky, 'LANC': Krylov}
mob_fctr CHOL
# For KSP-based method, maximum number of iterations. Must be present if `mth = 'LANC'`.
lanc_mxitr 1
# For KSP-based method, desired tolerance Must be present if `mth = 'LANC'`.
lanc_tol 1.0D-3
# Integrator for SDE: {'SE': Semi-implicit euler 'EE': Explicit euler}
bdintg SE
# For semi-implicit euler, maximum number of nonlinear iterations. Must be present if
# `bdintg = 'SE'`.
se_nlmxitr 200
# Semi-implicit euler: Maximum Krylov subspace dimension when GMRES is used
se_kdmax 25
# Tolerance for semi-implicit euler
se_tol 1.0D-6 1.0D-14
# Binsize for statistics
stats_binsize 1 1
# Step size
tim_stp 5.0D-3
# Number of simulation steps
nts_sim 2.0D4
# Mobility tensor sampling frequency
nts_mobsam 1
# Frequency of dumping trajectory
nts_dump 200
# Frequency of sampling statistics
nts_samp 200
# Frequency of logging
nts_log 200
# {T, F}. Whether the simulation is restarted.
lrevive F
# {T, F}. Whether to initialize the random number generator by reading
# a seed from a file. If `read_seed` == T, the seed will be read from
# a file 'random_seed.txt'
read_seed F
# {T, F}. Whether to write the random number generator seed. If
# `write_seed` == T the seed will be written to a file named
# 'random_seed.txt'
write_seed F
# Should the trajectory be written to file? {T, F}
write_traj T
# Name of the file containing the initial configuration
fn_cfg bb-120-0.cfg
# Name of the revive file
fn_revive revive.bin
# Name of the statistics file
fn_stats stats.txt
# Name of the trajectory file
fn_traj traj.bin
Warning
There are no checks performed on the consistency of the values provided in the control file. If you use unphysical values, your results may be incorrect or the program may crash.
There can be blank lines between the keywords. Comments begin with #. If the
# character is found on any line the rest of the line after # will be
discarded. The keywords and the values must be separated by one or more whitespaces.
On some specific aspects of the value format:
*.D* fortran format. For
example, a value of 2.1 is single precision; instead specify it at 2.1D0.
Other exponents are similar, e.g., 1.0D-2 for 0.01.nts except nts_md are long ints. For
convenience these values may be given in *.D* format. Internally they will
be cast as long ints. nts_dump <= nts_samp is a good idea, but do not dump too frequently
either.The following kinds of interactions are available (or can be made available with minimal effort):
Bonds
All bonds have a type called bond_type. bond_types are assigned by the user. For example, in a A-B diblock polymer, the user may choose A-A bonds as type 1, B-B bonds as type 2, and the A-B bond as type 3.
Each bond_type is completely determined by a style, called bond_style, and a set of parameters, called bond_params. bond_styles are chosen from the list of available styles, as specified in ia_bond_m. The number of required parameters depend on the chosen style. The maximum number of parameters is mxparam. For example, in our A-B diblock, the A-A bonds can be of type 1, with style 3 (corresponding to Kremer-Grest bond), and a set of four parameters; the B-B bonds can be of type 2, and also of style 3, with a set of four parameters, same as or different from the parameters of A-A bonds.
Angles
Similar to bonds, angles have types and styles as well. See ia_angle_m. Only one non-trivial style is available, as this is the most commonly used style for polymers. However, more styles can be added if necessary.
Dihedrals
Dihedrals are not typically used in the kind of polymer models I deal with. So, only the trivial style is present. In case you need a dihedral, add the appropriate routines to ia_dihedral_m.
Tethers
Tethers are pointwise restraints on one or more atoms. There can be multiple tethers, see ia_tether_m.
Pairwise
See ia_vdw_m for a list.
External
There is no working implementation of external interactions. The idea is this: I do not know what kind of external interactions you need, but I do not want to restrict you into a set of predefined interactions. So, modify the module ia_external_m to your choice, while keeping the interface intact. A guiding principle is that external interactions are generally fields that act on all the atoms in the sytem, but in some sense this covers everything. Remember to update the stress as you add external interactions.
To restart a simulation, set nts_sim to a higher value in the control file
and start the simulations. Note that an unusual situation may happen if you are
restarting after your job got killed/you deliberately killed it. In this case,
it is possible that the data written in fn_stats and fn_traj are a few time
steps ahead of what is in fn_dump. This is most annoying; to get rid of such
unwanted annoyances, I have written a small python script called sync.py that
lives at utils/sync. This script basically compares both fn_traj and
fn_stats with fn_dump and shaves off the extra records. You can run it
before resubmitting a killed job. Use it with care, you may lose data.
API documentation (Fortran files) is generated using FORD. As required by FORD, the documentation is written in Markdown. All versions of Markdown may not be supported, please experiment to see what works. Whole of GFM definitely doesn't.
FORD also processes a User's Guide page, also written in Markdown. The source
for this is index.md in docs/pages. This may change in future, as I would
prefer this to be in reStructuredText.
The html pages generated by FORD is hosted on GitHub Pages for this repository. For a number of reasons, pushing newly generated html pages is not straightforward. These pages are pushed to the gh-pages branch, not to master.
Assume that you have cloned the repo as usual, worked on it, and now you wish to update the documentation. This will be done via git worktree, as discussed by Sangsoo Nam.
Commit your current work and push. From the root of the repo, first create a linked worktree as follows:
cd docs
git worktree add html gh-pages
cd html
This will create a linked worktree in the directory docs/html and enter it. If
you do
git branch
now, you will see the current branch to be gh-pages.
docs/html is where the html pages will finally live. Now, clean it. git rm -rf .
.nojekyll. This prevents Jekyll from fiddling
with stuff inside html.touch .nojekyll
docs.cd ../docs
docs/tmp. FORD will generate the html
files here, which will be copied to docs/html. This is necessary because
FORD deletes everything inside its output directory, including .git.mkdir tmp
html. Delete tmp.ford -o tmp brownpak.md
mv tmp/* html/
rm -r tmp
html, add, commit, and push to gh-pages.cd html
git add --all
git commit -a --allow-empty-message -m ''
git push origin gh-pages
docs. Then get rid of the worktree.cd ../docs
git worktree remove html