From 7cee15809b923dd16425e49e6ac1a8576c4a776d Mon Sep 17 00:00:00 2001 From: Andrew Jewett Date: Wed, 25 Sep 2019 03:44:42 -0700 Subject: [PATCH] cleaned up documentation and updated "err.hpp" --- README.md | 16 +-- doc/doc_ndmansfield.md | 164 +++++++++++++++++++++++++ doc/docs_ndmansfield.txt | 121 ------------------ src/Makefile | 1 - src/analysis.cpp | 2 +- src/analysis.h | 2 +- src/{err_report.h => err.hpp} | 4 +- src/hamiltonian.cpp | 4 +- src/{hamiltonian.h => hamiltonian.hpp} | 5 +- src/main.cpp | 9 +- src/ndmansfield.cpp | 7 +- src/{ndmansfield.h => ndmansfield.hpp} | 2 +- 12 files changed, 193 insertions(+), 144 deletions(-) create mode 100644 doc/doc_ndmansfield.md delete mode 100644 doc/docs_ndmansfield.txt rename src/{err_report.h => err.hpp} (83%) rename src/{hamiltonian.h => hamiltonian.hpp} (93%) rename src/{ndmansfield.h => ndmansfield.hpp} (99%) diff --git a/README.md b/README.md index dbc805a..404b111 100644 --- a/README.md +++ b/README.md @@ -20,7 +20,7 @@ generates random self-avoiding space-filling curves (also called "lattice Hamiltonian paths") in an arbitrary number of dimensions using the algorithm developed by Marc L. Mansfield: - (Mansfield, M.L., J. Chem Phys, 2006, 125(15):154103) +*(Mansfield, M.L., J. Chem Phys, 2006, 125(15):154103)* The program runs a Monte-Carlo simulation which generates a series of curves. As the simulation progresses, the curves become increasingly random and independent of the starting shape. @@ -36,9 +36,11 @@ using the "-bend-energy" and "-twist-energy" arguments: ![color varies over length from blue to red](./doc/images/increasing_stiffness_50x50x125.gif) For more details, including a complete list of options, see the -"docs_ndmansfield.txt" file in the "doc" subdirectory. -(The move-set used during the Monte-Carlo procedure is explained in the file - "doc/images/Mansfield_monte-carlo_move_JCP2006_Fig1.png", +[doc_ndmansfield.md file](doc/doc_ndmansfield.md). +(The move-set used during the Monte-Carlo procedure is explained + [here](doc/images/Mansfield_monte-carlo_move_JCP2006_Fig1.png), + and + [here](doc/readme_motivation_and_introduction.pdf), as well as in the Mansfield paper.) NOTE: The initial shape of the curve is included in the file generated by this @@ -78,12 +80,12 @@ and were generated in a few minutes. ## Windows 10: -Install the Windows Subsystem for Linux (WSL) and run +Install HyperV (with linux), or the Windows Subsystem for Linux (WSL) and run sudo apt-get install build-essential -and then follow the instructions above for linux. -(Older windows users can install Cygwin or MinGW.) +and then follow the instructions above. +(Older windows users can install Cygwin or MinGW, or linux via virtualbox.) ## Dimensionality: diff --git a/doc/doc_ndmansfield.md b/doc/doc_ndmansfield.md new file mode 100644 index 0000000..11ee655 --- /dev/null +++ b/doc/doc_ndmansfield.md @@ -0,0 +1,164 @@ +ndmansfield +=========== + +Usage: +``` +ndmansfield -box xsize ysize zsize -tsave tsave [options] > traj.raw +``` +Example: +``` +ndmansfield -box 10 10 10 -tsave 2000 -tstop 20000 | tail -n 1001 > traj.raw +``` + +The "ndmansfield" program generates a file containing the coordinates of a +random path(s) which visits every site in a lattice inside a rectangular box. +(These paths have been used to model the conformations of coarse-grained +biopolymers, for example.) + +The "ndmansfield" program is an implementation of +"Unbiased sampling of lattice Hamilton path ensembles" +Marc L. Mansfield, J. Chem Phys, 2006 +The +[move-set used in each Monte-Carlo iteration](images/Mansfield_monte-carlo_move_JCP2006_Fig1.png) +is the same as the +["BACKBITE" move from the Mansfield J. Chem Phys 1982 paper (figure 1c).](images/Mansfield_monte-carlo_move_JCP1982_Fig1.png) + +Each step in the path corresponds to a location in the lattice, and the +the coordinates of each step in the path is saved as 3 integers on a separate +line of the file. (...Assuming your lattice is 3 dimensional. See below.) +This file is written to the standard output. + +This program uses a Monte-Carlo procedure to to generate many such paths. +Each of these paths is saved to the output file. Different paths are delimited +by blank lines in the output file. + +This code works in an arbitrary number of dimensions, and with arbitrary box +sizes. All of this code successfully compiles using g++ 4.8.4 (tested 2016-1-14) + + +# Usage Syntax: +``` +ndmansfield -box xsize ysize zsize -tsave tsave [options] > trajectory.raw +``` + +# Required Arguments + +## -box xsize ysize zsize + +How big is the box that the path lives in? +(xsize ysize and zsize are positive integers) + +*(Note: The number of numeric arguments following +the "-box" command determines the number of +dimensions the polymer will live in. For a 2-D +simulation, you would omit the "zsize" argument, +for example.)* + +## -tsave tsave + +After a certain number of iterations, save the +coordinates of the path in a file using +.RAW format (see below). +### Cyclic paths: +If cyclic paths are requested (see below), then +the simulation will iterate until a cyclic path +conformation discovered. In that case, cyclic +paths which were discovered less than tsave +iterations ago are discarded + + +# Optional Arguments: + +## -tstop tstop + +Specify how many iterations of Monte-Carlo to run +before halting the simulation. If specified, then +the simulation is halted when the iteration count +reaches tstop (an integer). +(By default tstop=infinity) + + +## -tstart tstart + +Start running the simulation with the iteration +count set to tstart. This is only potentially +useful if you are continuing a simulation you +stopped earlier and you want to keep track of +how many total iterations have ellapsed. +(By default, tstart=0.) + + +## -startcrd init_crd.raw + +Supply a .RAW file xyz(...) coordinate file +with the starting coordinates of your path. +Each line in the file should contains a list of +integers corresponding to the coordinates in +step in the path. +The number of lines in the file should match +the number of steps in the path, which should +match the number of lattice sites in the box. +By default, the initial path is a simple "zig-zag" +shape which fills the box. +Each line in the file should have g_dim integers +(...where "g_dim" is the number of dimensions +of the lattice and is usually 3.) + + +## -seed n + +Select the seed for the random number generator. + + +## -cyclic yes/no + +Limit results to cyclic paths? +*(Warning: Cyclic paths which do not cross periodic +boundaries are only possible in boxes +which contain an even number of +lattice sites.)* + + +## -cyclic-direction d + +Limit yourself to paths whose starting and ending +points lie on opposite sides of the box along +direction d. For example, if d=0, then the path's +starting and ending points must lie on opposite +sides of the box along the x direction. IE they +have the lowest and highest possible x coordinate, +and the remaining coordinates must be identical. +If d=1, then the two ends must lie in opposite +sides of the box along the y direction +d=2 ... z direction, etc... + + + +# Optional Arguments that effect physical properties of the chain: + +(By default all Monte-Carlo moves will be accepted. +If you start adding energetic bias to some shapes over others, +then Monte-Carlo moves that increase chain energy are more likely to +be rejected. All energies are in units of reduced temperature, kB*T) + +## -bend-energy E + +If specified, then 90-degree bends in the chain +will increase the energy of the chain by E. + +## -twist-energy E + +If specified, then right-handed torsions in +the chain backbone will increase the energy +of the chain by E. Similarly, left-handed +torsions in the chain will reduce the energy by E. +Formally, a right-handed torsion occurs any time +the vector triple product ((v1 x v2) . v3) between +three successive bonds in the chain backbone +(vectors v1, v2, and v3) is positive (+1). +A left-handed torsion occurs whenever the +tripple-product ((v1 x v2) . v3) is negative (-1). +(Possible values for the triple product are -1,0,1) + +*(Warning: This command line argument only makes +sense for simulations in 3-dimensions.)* diff --git a/doc/docs_ndmansfield.txt b/doc/docs_ndmansfield.txt deleted file mode 100644 index 0d55af5..0000000 --- a/doc/docs_ndmansfield.txt +++ /dev/null @@ -1,121 +0,0 @@ -The "ndmansfield" program generates a file containing the coordinates of a -random path(s) which visits every site in a lattice inside a rectangular box. -(These paths have been used to model the conformations of coarse-grained -biopolymers, for example.) - -The "ndmansfield" program is an implementation of -"Unbiased sampling of lattice Hamilton path ensembles" -Marc L. Mansfield, J. Chem Phys, 2006 -The move-set used in each Monte-Carlo iteration appears to be the same as the -"BACKBITE" move from the Mansfield J. Chem Phys 1982 paper (figure 1c). - -Each step in the path corresponds to a location in the lattice, and the -the coordinates of each step in the path is saved as 3 integers on a separate -line of the file. (...Assuming your lattice is 3 dimensional. See below.) -This file is written to the standard output. - -This program uses a Monte-Carlo procedure to to generate many such paths. -Each of these paths is saved to the output file. Different paths are delimited -by blank lines in the output file. - -This code works in an arbitrary number of dimensions, and with arbitrary box -sizes. All of this code successfully compiles using g++ 4.8.4 (tested 2016-1-14) - - -Usage Syntax: - - ndmansfield -box xsize ysize zsize -tsave tsave [options] > trajectory.raw - - -tsave tsave After a certain number of intervals, save the - coordinates of the path in a file using - .RAW format (see below). - Cyclic paths: - If cyclic paths are requested (see below), then - the simulation will iterate until a cyclic path - conformation discovered. In that case, cyclic - paths which were discovered less than tsave - iterations ago are discarded - - -box xsize ysize zsize How big is the box that the path lives in? - (xsize ysize and zsize are positive integers) - - NOTE: The number of numeric arguments following - the "-box" command determines the number of - dimensions the polymer will live in. For a 2-D - simulation, you would omit the "zsize" argument, - for example. (There is no limit to the number - of dimensions the polymer can occupy, however, - higher dimensional lattices occupy more memory.) - - Optional Arguments: - - -tstop tstop Specify how many iterations of Monte-Carlo to run - before halting the simulation. If specified, then - the simulation is halted when the iteration count - reaches tstop (an integer). - (By default tstop=infinity) - - -tstart tstart Start running the simulation with the iteration - count set to tstart. This is only potentially - useful if you are continuing a simulation you - stopped earlier and you want to keep track of - how many total iterations have ellapsed. - (By default, tstart=0.) - - -startcrd init_crd.raw Supply a .RAW file xyz(...) coordinate file - with the starting coordinates of your path. - Each line in the file should contains a list of - integers corresponding to the coordinates in - step in the path. - The number of lines in the file should match - the number of steps in the path, which should - match the number of lattice sites in the box. - By default, the initial path is a simple "zig-zag" - shape which fills the box. - Each line in the file should have g_dim integers - (...where "g_dim" is the number of dimensions - of the lattice and is usually 3.) - - -seed n Select the seed for the random number generator. - - -cyclic yes/no Limit results to cyclic paths? - (Warning: Cyclic paths which do not cross periodic - boundaries are only possible in boxes - which contain an even number of - lattice sites.) - - -cyclic-direction d Limit yourself to paths whose starting and ending - points lie on opposite sides of the box along - direction d. For example, if d=0, then the path's - starting and ending points must lie on opposite - sides of the box along the x direction. IE they - have the lowest and highest possible x coordinate, - and the remaining coordinates must be identical. - If d=1, then the two ends must lie in opposite - sides of the box along the y direction - d=2 ... z direction, etc... - - Optional Arguments that effect physical properties of the chain: - - (By default all Monte-Carlo moves will be accepted. - If you start adding energetic bias to some shapes over others, - then Monte-Carlo moves that increase chain energy are more likely to - be rejected. All energies are in units of reduced temperature, kB*T) - - -bend-energy E If specified, then 90-degree bends in the chain - will increase the energy of the chain by E. - - -twist-energy E If specified, then right-handed torsions in - the chain backbone will increase the energy - of the chain by E. Similarly, left-handed - torsions in the chain will reduce the energy by E. - Formally, a right-handed torsion occurs any time - the vector triple product ((v1 x v2) . v3) between - three successive bonds in the chain backbone - (vectors v1, v2, and v3) is positive (+1). - A left-handed torsion occurs whenever the - tripple-product ((v1 x v2) . v3) is negative (-1). - (Possible values for the triple product are -1,0,1) - WARNING: This command line argument only makes - sense for simulations in 3-dimensions. - diff --git a/src/Makefile b/src/Makefile index 64ac1c9..aa7bf85 100644 --- a/src/Makefile +++ b/src/Makefile @@ -63,7 +63,6 @@ GENERATED_FILES = *.o *.a core ndmansfield install: $(MAKE) ANSI_C="$(ANSI_C)" ANSI_CPP="$(ANSI_CPP)" L_COMP="$(L_COMP)" CFLAGS="$(CFLAGS)" LFLAGS="$(LFLAGS)" INSTALL_PATH="$(INSTALL_PATH)" ndmansfield cp -f ndmansfield $(INSTALL_PATH) - cp -f docs_ndmansfield.txt $(INSTALL_PATH) clean: rm -f $(GENERATED_FILES) diff --git a/src/analysis.cpp b/src/analysis.cpp index aec871b..9a976ce 100644 --- a/src/analysis.cpp +++ b/src/analysis.cpp @@ -1,6 +1,6 @@ #include #include -#include "ndmansfield.h" +#include "ndmansfield.hpp" #include "analysis.h" using namespace std; diff --git a/src/analysis.h b/src/analysis.h index 49f7408..bbe052b 100644 --- a/src/analysis.h +++ b/src/analysis.h @@ -1,7 +1,7 @@ #ifndef _ANALYSIS_H #define _ANALYSIS_H -#include "ndmansfield.h" +#include "ndmansfield.hpp" void CountBondDirections(long *aBondCountPlusXYZ, diff --git a/src/err_report.h b/src/err.hpp similarity index 83% rename from src/err_report.h rename to src/err.hpp index 6a42b7e..d2e3f73 100644 --- a/src/err_report.h +++ b/src/err.hpp @@ -4,12 +4,14 @@ #include using namespace std; -class InputErr { +class InputErr : public std::exception { +protected: string msg; public: InputErr(const char *description):msg(description) {} InputErr(string description):msg(description) {} virtual const char *what() const throw() { return msg.c_str(); } + virtual ~InputErr() throw (){} }; #endif //#ifndef _ERR_REPORT_H diff --git a/src/hamiltonian.cpp b/src/hamiltonian.cpp index 2248935..e6b7b7a 100644 --- a/src/hamiltonian.cpp +++ b/src/hamiltonian.cpp @@ -1,6 +1,6 @@ #include -#include "ndmansfield.h" -#include "hamiltonian.h" +#include "ndmansfield.hpp" +#include "hamiltonian.hpp" // Right now the hamiltonian does nothing (yet) diff --git a/src/hamiltonian.h b/src/hamiltonian.hpp similarity index 93% rename from src/hamiltonian.h rename to src/hamiltonian.hpp index b5f5959..617018b 100644 --- a/src/hamiltonian.h +++ b/src/hamiltonian.hpp @@ -1,9 +1,10 @@ #ifndef _HAMILTONIAN_H #define _HAMILTONIAN_H -#include "ndmansfield.h" //(defines NDmansfield) - +#include "ndmansfield.hpp" // Contains a description of the NDmansfield data + // structure we will be using to store the state + // of our system as the simulation evolves. diff --git a/src/main.cpp b/src/main.cpp index 0834cd3..c1ad178 100644 --- a/src/main.cpp +++ b/src/main.cpp @@ -18,15 +18,16 @@ #include // defines strcmp() using namespace std; -#include "ndmansfield.h" // Contains a description of the NDmansfield data structure - // we will be using to store the state of our system. +#include "ndmansfield.hpp" // Contains a description of the NDmansfield data + // structure we will be using to store the state + // of our system as the simulation evolves. #include "random_gen.h" // Some random number generators. This file defines // the functions RANDOM_REAL_0_1() and INIT_RANDOM() -#include "hamiltonian.h" // The object that will calculate the energy. +#include "hamiltonian.hpp" // The object that will calculate the energy. -#include "analysis.h" // Diagnostics to report while running the simulation. +#include "analysis.h" // Diagnostics to report while running the simulation diff --git a/src/ndmansfield.cpp b/src/ndmansfield.cpp index 9c7a37f..23e98ea 100644 --- a/src/ndmansfield.cpp +++ b/src/ndmansfield.cpp @@ -8,10 +8,11 @@ using namespace std; #include "random_gen.h" -#include "ndmansfield.h" // Contains a description of the NDmansfield data structure - // we will be using to store the state of our system. +#include "ndmansfield.hpp" // Contains a description of the NDmansfield data + // structure we will be using to store the state + // of our system as the simulation evolves. -#include "hamiltonian.h" // The object that will calculate the energy. +#include "hamiltonian.hpp" // The object that will calculate the energy. // NDmansfield::MonteCarloStep() diff --git a/src/ndmansfield.h b/src/ndmansfield.hpp similarity index 99% rename from src/ndmansfield.h rename to src/ndmansfield.hpp index 3e259cc..0f4fd2b 100644 --- a/src/ndmansfield.h +++ b/src/ndmansfield.hpp @@ -16,7 +16,7 @@ // You can ask me what this does if you want. // Strictly speaking you don't need to use assert()s // in the code, but they are helpful for debugging. -#include "err_report.h" +#include "err.hpp" #include "globals.h"