Robinson Group Classical Monte Carlo Molecular Simulator (legacy version)
©2012, Lewis E. Johnson
Created by Lewis E. Johnson and Robin Barnes, Robinson Group, Department of Chemistry, University of Washington
http://courses.washington.edu/bhrchem/
Released under the University of Illinois/NCSA Open Source License. See LICENSE.txt


INSTALLATION:
This software requires modification of source to configure individual simulations, and must be compiled for each simulation. A standard makefile is included, and the compiler and options can be set in makefile.choices. To build, type 'make'. To delete object files, type 'make clean'.


USAGE:
This code is provided without a detailed manual. All parameters needed for simulation configuration are located in main.cpp and are heavily commented. For example configurations, see the examples provided with the code (MCmain0.cpp to MCmain5.cpp, located in the EXAMPLES directory). Parameters and results can also be found in the following papers:

Johnson, L. E.; Barnes, R.; Draxler, T. W.; Eichinger, B. E.; Robinson, B. H., Dielectric Constants of Simple Liquids: Stockmayer and Ellipsoidal Fluids. Journal of Physical Chemistry B 2010, 114 (25), 8431-8440.

Benight, S. J.; Johnson, L. E.; Barnes, R.; Olbricht, B. C.; Bale, D. H.; Reid, P. J.; Eichinger, B. E.; Dalton, L. R.; Sullivan, P. A.; Robinson, B. H., Reduced Dimensionality in Organic Electro-Optic Materials: Theory and Defined Order. Journal of Physical Chemistry B 2010, 114 (37), 11949-11956.

Olbricht, B. C.; Sullivan, P. A.; Dennis, P. C.; Hurst, J. T.; Johnson, L. E.; Benight, S. J.; Davies, J. A.; Chen, A.; Eichinger, B. E.; Reid, P. J.; Dalton, L. R.; Robinson, B. H., Measuring Order in Contact-Poled Organic Electrooptic Materials with Variable-Angle Polarization-Referenced Absorption Spectroscopy (VAPRAS). Journal of Physical Chemistry B 2011, 115 (2), 231-241.


IMPORTANT NOTES:
1. For production simulations, UNLOCK the random number generator by setting test=0 in main.cpp. Otherwise, the simulations will always start from the same random number seed. The RNG lock is intended only for testing and validation.

2. The coordinate output (*coords.dat) consists of the atom number, atom type, position, and rotation matrix between the lab and molecule frame. Coordinates are saved at the end by default (*chkfinalcoords.dat), and if saving intermediate coordinates is enabled, they are saved every 100 cycles (outer loops) by default. Documentation about the coordinate output file format can be found at http://courses.washington.edu/bhrchem/visualizer.php

3. The extended output generated if doxm=1 consists of [cos(theta)_x, cos(theta)_y, cos(theta)_z] and a matrix of second moments from cos^2(theta)_xx to cos^2(theta)_zz. If enabled, the default sampling frequency is after every 100 sampling cycles (outer loops). If binary_average is on, additional files for type a and b particles only will be generated. The general xdata file includes whichever types are specified to be averaged over in MCmain.cpp

4. The correlation functions generated if dogr=1 are as follows
gr - g(r), the standard radial distribution function, output as processed data
ga - g_mu(r), the first-order dipole correlation function, output as a raw histogram of counts
gas - g_mu(r), the second-order dipole correlation function, output as a raw histogram of counts
gh - angular distribution histogram for nearest-neighbor shell
gn - cos(gamma)[cos(alpha)], Angular distribution as a function of position around a central molecule

5. The coordinate read functions should be used with CAUTION. While they should work, I have had problems with crashes when compiling with icc using interprocedural optimization.

6. The normalized order parameter from the console output is M^2/(N*mu)^2, or the ratio of the square of the current total dipole moment of the system to the square of the maximum possible dipole moment. This should to be confused with cos(theta)_z or any of the order parameters saved to the .dat files.

7. Output for each cycle along with averages is contained in a .dat file with the same name as the job. As these files are long, a machine-readable summary file is also generated. The format is shown below:

---------------------------------------------------------------------------------
SUMMARY FILE FORMAT, LEJ 02/17/10

Summary file opened at %time.

#SIMULATION SUMMARY
NFILES				//number of files in set
MOL1	n	mu	mueff	//mueff only matters if using Ons. polarizability
MOL2	n	mu	mueff
RHO	numdens			//in A^-3
T	temp
N2	n^2			//optical dielectric constant
Y	y			//reduced dipole density

FILENUM				//number for this particular file
COSN	cos^1	cos^2	cos^3	//wrt z axis
M	Mx	My	Mz	//total dipole moment (D)
M2	M2			//<M^2>
GK	short	full		//short uses M2, full uses Var(M)
EFIELD	int	ext		//int is E0, ext is E
EPSILON	mat	rf		//mat is simulated eps, rf. is rxn field
U/NKT	totalU	varU		//dimensionless
ACCEPT	rnd	prq	eq	//percentages
RUNTIME	runtime	randtime	//in seconds

(repeat for each simulation in batch)

#END
-------------------------------------------------------------------------------


UNITS:
Units used internally by code:
Distance - angstroms
Angles - radians
Density - angstroms^(-3)
Energy - pico-ergs
Temperature - Kelvin
Dipole moment - Debye
Electric field - pico-ergs/Debye

Note that energies reported in the log file are often reported dimensionlessly as U/kT, and will be listed as such. Final averages may also be reported in SI units, and reported as such.


SOURCE LIST:
VecMat.cpp/h (linear algebra functions)
MCmain.cpp (main function, configurable variables)
setup.cpp/h (setup functions to prepare for run)
evolve_system.ccp/h (core function for an individual simulation)
utility_functions.cpp/h (global functions such as RNG and text I/O)
output_data.cpp/h (data output to file)
Vmu2body.cpp/h (dipole-dipole interactions)
VLJ.cpp/h (Lennard-Jones interactions)
TotalV.cpp/h (functions related to calculating total energy)
Vmu3.cpp/h (dipole-field interactions)
OneStep.cpp/h (core function for potential energy calculations)
get_rs_mus.cpp/h (functions for calculating distances and dipole moments)
newtouch.cpp/h (Perram & Wertheim ellipsoid closest contact algorithm)
get_means.cpp/h (functions used for calculating average properties)
Cnsts.h/cpp (storage class for constants and other commonly used stuff)
Molecule.cpp/h (core class for molecules, which are made of ellipsoids)
Ellipse.cpp/h (class for properties of individual ellipsoids)
Latticeoids3d.cpp/h (class & functions for generating a box of molecules)
get_positions.cpp/h (output coordinates to file)
gofr.cpp/h (functions for calculating correlation functions)


ACKNOWLEDGEMENTS:
This code is based on prior simulation code written in MATLAB by Prof. Bruce Robinson and other members of the Robinson group. Thanks to Andreas Tillack for continuing developing a more powerful and configurable successor to the C++ MC code, as well as for debugging assistance. Development of this code was funded by the NSF STC-MDITR (DMR 0120967).


LEJ 05/17/2012