This is BROWNPAK. It can perform the following kinds of simulations:
The source code is written in F2008 compliant fortran. 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 using git. Of course, this requires git to be
installed on your system. If you do not want to clone, it is possible to
download a zip file containing the source. Let's say you want to clone.
Create a directory where you want the files to live. Say this directory is foo.
mkdir foo
cd foo
Then clone the repo from GitHub thus:
git clone https://github.com/saridut/BROWNPAK.git .
That's it.
The directory structure is as follows:
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_config: This file specifies 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.-rlx in their names will be
produced. The file fn_config-rlx.cfg contains the minimized configuration,
and the file fn_config-rlx.txt contains the same configuration in LAMMPS data
format for visualization in Ovito.There is a makefile in build. In the makefile, the DEBUG flag should be set
to false for production builds. For testing purposes, set DEBUG = true.
The compiler name is specified via the variable FC. e.g. for intel it will be
appropriate to use FC = ifort. I use fortran95 wrappers to MKL as well. If one
is using a non-Intel compiler, these wrappers need to be built (see the MKL
documentation on how to do this). Anyways, since I am using gfortran, I specify the location of the
wrappers through the variable MKL_INTRFC. Furthermore, MKLROOT is the root
directory of the MKL installation. For an Intel compiler, MKL_INTRFC is not
necessary, but MKLROOT must be specified. It may be helpful to use the Intel
Link Line Advisor
for looking up appropriate flags. Appropriate compilation flags must be
specified via FCFLAGS. The current flags pertain to gfortran. For debug
builds, the flags should turn off optimization, raise all warnings, check
bounds, etc.; for production builds do turn on necessary optimization (without
being too aggressive), loop unrolling, interprocedural optimizations, inlining,
etc.
make
To clean all .o and .mod files, do
make clean
To remove all .o, .mod, and the executable, do
make clobber
To run, the simplest way is to go to bin and
./brownpak fn_control=controlfile.txt job_tag=some_number
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.
Note that once compiled, if you change the source files a recompilation is necessary. Unlike some codes that you may be familiar with, changing input files do not require recompilation.
Here is a sample control file. It is called `control.txt.
sim_style 2 use_verlet_tab F rcutoff 5.25D0 tskin 2.1D0 use_cell_list T excluded_atoms 1 lvdw T lhdia F mob_fctr KRYL lelectrostatics F tim_stp 1.0D-2 nts_md 100 nts_eql 0.0D0 nts_eql_samp 10 nts_sim 2.0D3 nts_samp 10 nts_dump 10 nts_log 10 fn_cfg sample.cfg fn_revive revive.bin fn_stats stats.txt fn_traj traj.bin lrevive F read_seed F write_seed T write_eql_stats T write_traj T traj_frmcmp 1 0 0 1 traj_wmpcd F
As you can see, it lists a number of keywords and their corresponding values separated by whitespace. The maximum length of a line is as specified in m_globals.
Each of the keywords in the control file is a variable listed in m_globals. Please look up the detailed description and possible set of allowed values there.
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.
I will elaborate 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.KRYL is
not the same a kryl.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. mts_md is not a long int because it does not make
sense for it to be a large number, else the simulation will never complete.traj_frmcmp: See m_globals for details. Each element of the
sequence can be either 0 or 1 (separated by whitespaces), e.g. 1 1 1 1 or 1 0 0 1.
All four being zero is allowed, but makes no sense.nts_dump <= nts_samp is a good idea, but do not dump too frequently
either.The trajectory file is a binary file, i.e. it is a stream of bytes. The byte
order is native. It can be read back in python (using struct to unpack), in
fortran (opening the file with form='unformatted, access='stream'), or in any
other language.
If traj_wmpcd = T in the control file, the trajectory file can be
extremely large. Explicit data for the position and velocities of MPCD atoms are
rarely needed. MPCD atoms do not have forces or charge on them.
I will call the trajectory file as traj.bin. It contains a header, followed by
a sequence of frames. The structure of the header is:
traj_frmcmp in the control file.During creation of a trajectory, num_atoms and num_mpcd_atoms are given
to m_trajectory. Depending on m_globals, it is
possible for an MPCD simulation to not write any MPCD data to traj.bin. This
should be the commonly used case. For BD/energy-minimization the value of
m_globals does not matter.
Following the header, there is a sequence of frame data, written according to m_globals and m_globals.
The revive file is a binary dump. It contains enough information to restart the
simulation if lrevive = T in the control file. To see what gets dumped, please
examine the source for m_config_io.
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 m_ia_bond. The number of required parameters depend on the chosen style. The maximum number of parameters is m_globals. 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 m_ia_angle. 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 m_ia_dihedral.
Tethers
Tethers are pointwise restraints on one or more atoms. There can be multiple tethers, see m_ia_tether.
Pairwise: See m_ia_vdw 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, please modify the module m_ia_external to your choice, while keeping the interface intact. I assume you are a competent Fortran programmer, so that you will immediately get it when you look at m_ia_external. 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.
Here is an extremely basic config file for a bunch of MPCD atoms.
Sample SIMBOX 20 0.0 0.0 0.0 20 0.0 0.0 0.0 20 IMCON 1 ATOM_TYPES 0 MPCD_ATOMS 40000 5 ATOMS 0 MOLECULE_TYPES 0 MOLECULES 0
Please see the other examples in utils/models. It is best to use the python scripts to generate your config files. These scripts are self-explanatory.
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.
Create an intial configuration. Say it is in file sample.cfg.
Run the programme with sim_style = 0.
Monitor fn_stats, here the output energies will be written. The minimized
configuration will be written to sample-rlx.cfg. Moreover sample-rlx.txt
(in LAMMPS data format) will be created, which you can visualize in Ovito. If
necessary, rerun by setting nts_sim to a higher value.
Create an initial configuration.
Minimize energy if you think this will be useful. It is usually useful. Use the minimized configuration as the stating configuration for BD/MPCD simulation.
Set sim_style = 1(for BD) or sim_style = 2(for MPCD) and run.
Rerun if necessary.
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