Treecode_RISM_PC_Forces: A Fortran repository from lwwilson1

!
! Author: Leighton W. Wilson (lwwilson@umich.edu)
! With thanks to Henry Boateng (boateng@umich.edu)
! Department of Mathematics
! University of Michigan, Ann Arbor
!
! Copyright (c) 2017. The Regents of the University of Michigan.
! All Rights Reserved.
!
! This file is the partial documentation for TREECODE_RISM_PC_Forces,
! Fortran90 subroutines for approximating the value of Coulombic forces
! on N target particles due to a grid of M sources. See the reference
! (Luchko, Gusarov, Roe, et. al. 2009), equation 7, for details.
! PC_TREECODE employs the particle-cluster method which is more efficient
! when the sources outnumber the targets.
!
! This version written in fortran for compatibility with AmberTools/RISM.
!
! This program is free software; you can redistribute it and/or modify
! it under the terms of the GNU General Public License as published by
! the Free Software Foundation; either version 3 of the License, or
! (at your option) any later version.
!
! This program is distributed in the hope that it will be useful,
! but WITHOUT ANY WARRANTY; without even the implied warranty of
! MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
! GNU General Public License for more details.
!
! You should have received a copy of the GNU General Public License
! along with this program; if not, <http://www.gnu.org/licenses/>.
!
!%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

README file

NOTE: Please include the following references in any work that
utilizes this code:

(1) Boateng. H. A., Krasny, R.: Comparison of Treecodes for
Computing Electrostatic Potentials in Charged Particle
Systems with Disjoint Targets and Sources.
J. Comput. Chem. (2013)

(2) Duan, Z.-H., Krasny, R.: An adaptive treecode for computing
nonbonded potential energy in classical molecular systems.
J. Comput. Chem. {\bf 22} (2001) 184-195

(3) Lindsay, K., Krasny, R.: A particle method and adaptive treecode
for vortex sheet motion in 3-D flow. J. Comput. Phys. {\bf 172}
(2001) 879-907

(4) Deng, Q., Driscoll, T. A: A Fast Treecode for Multiquadric
Interpolation with Varying Shape Parameters.
SIAM J. Sci. Comput. {\bf 34} (2012) A1126-A1140

Summary of files :
------------------

treedriver.f90 : Driver program for testing the treecode subroutines
tree_pc.f90 and tree_cp.f90

tree_pc.f90 : Subroutine for particle-cluster treecode

tree_cp.f90 : Subroutine for cluster-particle treecode

exact_coul.f90 : Program to compute the interactions directly. It should
be run first to generate the exact energies to which
the approximate energies from the treecode algorithms
are compared.

S*.txt : Files containing the charges and coordinates of the
source particles uniformly distributed in
[-0.5,0.5]x[-0.5,0.5]x[-0.5,0.5]. The files S10000.txt,
S100000.txt and S1000000.txt correspond to 10000,
100000, and 1000000 source particles respectively.

T*.txt : Files containing the coordinates of the target particles
uniformly distributed in [-0.5,0.5]x[-0.5,0.5]x[-0.5,0.5].
The files T10000.txt, T100000.txt and T1000000.txt
correspond to 10000, 100000, and 1000000 target particles
respectively.

input_ex.txt : Input file for the executable from compiling exact_coul.f90

input_pc.txt : Input file for the executable from compiling tree_pc.f90

input_cp.txt : Input file for the executable from compiling tree_cp.f90

run_direct : Bash script for running exact_coul for different M and N's.

run_pc : Bash script for running tree_pc for different M and N's.

run_cp : Bash script for running tree_cp for different M and N's.

Compiling and Testing the code
------------------------------

Compiling :
The source code is written in Fortran90. To compile
on an Intel Fortran compiler to generate an executable,
exact_coul, for the direct computation, use:

ifort -fast exact_coul.f90 -O3 -o exact_coul.

To generate an executable, tree_pc, for the
particle-cluster code use:

ifort -fast treedriver.f tree_pc.f90 -O3 -o tree_pc

and for an executable, tree_cp, for the cluster-particle
code, use:

ifort -fast treedriver.f tree_cp.f90 -O3 -o tree_cp

Testing :

Make the files run_* executable by invoking 'chmod +x run_direct',
'chmod +x run_pc', and 'chmod +x run_cp'. Then execute
'./run_direct >out1.txt &' to generate the exact energies and
time for direct summations for different sources and targets.
The output for 10^4 sources and 10^5 targets is labeled ex_s4_t5.txt .
In general, the output for 10^n sources and 10^m targets is labeled
ex_sn_tm.txt . The outputs are input files for tree_pc and tree_cp .

Execute './run_pc>out2.txt &' and './run_cp>out3.txt &' to approximate
the interactions using particle-cluster and cluster-particle
respectively with different orders of multipole approximation.

Input for the treedriver.f90 :
-------------------------------

Treedriver is written to work with both tree_pc.f90 and tree_cp.f90.
Treedriver will prompt the user for the following:

SAMPIN1 : Name of input file containing coordinates
and charges of sources.

SAMPIN2 : (CHARACTER) Name of input files containing coordinates
of targets.

SAMPIN3 : (CHARACTER) Name of input file containing the exact
energy at of each target and the cpu time for direct
summation.

SAMPOUT : (CHARACTER) Name of output file

NUMPARSS : (INTEGER) Number of sources particles

NUMPARST : (INTEGER) Number of targets

THETA : (REAL*8) The multipole acceptance criterion.

ORDER : (INTEGER) Order of the Taylor expansions used for the
approximation if the MAC is accepted.

IFLAGS : (INTEGER) Flag determining how source tree division terminates:

IFLAGS=0 : Divide till number of particles in a leaf is less
or equal to a given number.
IFLAGS=1 : Divide till number of levels in a tree is equal to
a given number.

IFLAGT : (INTEGER) Flag determining how target tree division terminates:

IFLAGT=0 : Divide till number of particles in a leaf is less
or equal to a given number.
IFLAGT=1 : Divide till number of levels in a tree is equal to
a given number.

MAXPARNODES : (INTEGER) If IFLAGS=0, then division of a cluster terminates if
the number of particles in the cluster is less or equal to
MAXPARNODES.

MAXPARNODET : (INTEGER) If IFLAGT=0, then division of a cluster terminates if
the number of particles in the cluster is less or equal to
MAXPARNODET.

TREELEVELS : (INTEGER) If IFLAGS=1, then division of a source cluster
terminates if the cluster is at level=TREELEVELS.

TREELEVELT : (INTEGER) If IFLAGT=1, then division of a target cluster
terminates if the cluster is at level=TREELEVELT.

SHRINKS : (INTEGER) Adaptive switch used in the construction of the
source tree. If SHRINKS=1, then the bounds of a cluster
are taken to be that of the minimal box that contains all
the particles in the cluster. Else, each cluster is
divided into 8 child clusters of equal volume determined
by the midpoints in the x, y, z directions.

SHRINKT : (INTEGER) Adaptive switch used in the construction of the
target tree. If SHRINKT=1, then the bounds of a cluster
are taken to be that of the minimal box that contains all
the particles in the cluster. Else, each cluster is
divided into 8 child clusters of equal volume determined
by the midpoints in the x, y, z directions.

Output for the treedriver.f90 :
-------------------------------

The output file prints out two lines of data for each realization. The first line is
a printout of the inputs:

NUMPARSS,NUMPARST,IFLAGS,IFLAGT,MAXPARNODES,MAXPARNODET,TREELEVELS,TREELEVELT,ORDER,THETA .

The second line is a printout of:
Relative error in total energy, root mean square error, cpu time for direct summation,
and cput time for the treecode approximation.

lwwilson1/Treecode_RISM_PC_Forces