hsidky / saphron

A lightweight C++11 Monte Carlo molecular simulation engine

SAPHRON

SAPHRON (Statistical Applied PHysics through Randomized On-the-fly Numerics) is a modern, open-source, light-weight C++11 based Monte Carlo physics package. It is designed to be easy to use, extendable and extremely versatile. As the name suggests, one of the primary features is the inclusion of various Density-of-States (DOS) sampling algorithms. SAPHRON is currently in early development, and as a result it currently lacks many basic features; this README is also likely to be out of date. In addition to the C++ application, a number of helper MATLAB scripts are included to assist with data analysis.

The documentation can be found here

Features

• A very simple API that is user and developer friendly
• Lattice and off-lattice simulations.
• Anisotropic potentials including Gay-Berne.
• Arbitrary ensembles defined by collections of moves.
• OpenMP parallelization for energy and neighbor list calculation.
• MPI large scale multi-walker density of states (DOS) flat-histogram sampling along many order parameters.
• Much more!

Check out the documentation for a more detailed list of features

https://hsidky.github.io/SAPHRON

Dependencies

SAPHRON requires some linear alegra routines to get going. It's easy enough to install the required packages. On any Debian-based distro simply type:

$ sudo apt-get install libblas3 liblapack3 libarmadillo-dev

BLAS and LAPACK are the default linear algebra providers, though SAPHRON supports the Intel MKL and searches for it. If found it will use it instead of LAPACK, so you don't need to do anything. Armadillo provides C++ headers for interfacing with the libraries.

To get SAPHRON to compile it is crucial that you perform the following step

By default, Armadillo assumes you want to link against its shared library. SAPHRON does not do this, but instead links directly to BLAS and LAPACK or MKL as mentioned above. To fix this, use your editor of choice (here we use vim) to modify the Armadillo config header

$ vim /usr/include/armadillo_bits/config.hpp

Simply comment out the line that says #define ARMA_USE_WRAPPER and you're good to go!

OpenMP

SAPHRON uses OpenMP to parallelize energy and neighbor list calculations. It relies on compilers that support the -fopenmp flag. Any recent C++11 compatible compiler should support this, including GCC 4.9.x at minimum (required for regex support) and Clang 3.4+.

Boost and MPI

SAPHRON uses Boost MPI to provide support for multi-walker density of states simulations. The requirement is for Boost >= 1.55 with the MPI and serialization modules. A requisite underlying MPI library is also required. On recent Debian based systems using OpenMPI, the requirement can be installed via:

$ sudo apt-get install libopenmpi-dev openmpi-bin libboost-all-dev

To run a multi-walker simulation, the number of threads per processes is specified by the OpenMP OMP_NUM_THREADS environment variable, and the number of walkers (processes) by mpirun. It is necessary to map by nodes to ensure proper distribution of processors to each walker. See the documentation for more information.

Additional information

If you wish to link SAPHRON against the static BLAS/LAPACK libraries you can install those instead. However, you will also need to install libgfortran and libquadmath. SAPHRON will look for and link against them as well.

Installation

The first step is to clone the repository locally.

$ git clone https://github.com/hsidky/SAPHRON.git

SAPHRON uses a CMake build system. To build on a UNIX-style platform enter the following commands

$ cd SAPHRON
$ mkdir build && cd build
$ cmake .. 
$ make
$ sudo make install

This will install a saphron binary into /usr/local/bin and a static library in /usr/local/lib/libsaphron.a.

Testing

SAPHRON uses the Google C++ Testing Framework for unit testing. It is downloaded as part of the build process. To run the unit tests after building, type

$ make test

Acknowledgements

SAPHRON utilizes the following packages:

Armadillo (http://arma.sourceforge.net/)

JSONCpp (https://github.com/open-source-parsers/jsoncpp)

Sitmo Random Number Generator (http://www.sitmo.com/article/multi-threaded-random-number-generation-in-c11/)

SAPHRON would also not be possible without the support and expertise of Eliseo Marin-Rimoldi, developer of Cassandra.

Contributing

Feel free to fork this project on GitHub. Any pull-requests, feature requests or other form of contributions are welcome.

saphron's Issues

Particle children composition in world needs robust tracking.

Currently, world composition updates are needed on:
particle->AddChild()
Particle->RemoveChild()

Perhaps firing an event with World as observer similar to identity?

When ParticleList is provided to Forcefield manager, energy is double counted.

There is no mechanism in EvaluateHamiltonian in ForceFieldManager to avoid double counting energy for a ParticleList containing particles that would result in energy double counting.

NeighborListUpdate does not clear previous entries.

Title says it all.

End-of-run json

Dump EOR data to json file.

Create event observers for changes in particle properties.

Implement event handlers/observers for changes in particle properties. Example of this would be if there is a connectivity (DLSAConnectivity) that maintains an active list of particle directors, it would be nice if it can be called and updated if the director of a particle changes.

Typically, a change in a particle property is followed by a Hamiltonian evaluation, which is fine in this case. But a more robust method would be to implement as suggested above.

World should have a primitive particle list

World should have a list of primitive particles for moves that perform manipulations on exclusively primitive types (atoms/spins).

Responsibility for deleting Particle*

Need to clearly define responsibilities for deleting particle pointers. There should be an additional method in World that is called EraseParticle which deletes it.

If a move "removes" a particle from the box, the best approach would be to collect them in a vector/stack and delete in destructor.

Move by move acceptance ratio

Incorporate move by move acceptance ratio in Ensemble and make available to observers/visitors.

Electrostatics and forcefields

(Assigned to bsikora)

Debye-Huckel

Reaction Field

Ewald Sum

Create test case for electrostatics Intra and inter.

List of improvements for Release 0.1

This is a list of specific improvements to be made for release 0.1:

• Eliminate ensemble acceptance map. Get directly from move manager.
• Reduce (elimininate?) use of std::map. Switch to sorted vector + binary search.
• Eliminate string-based lookups throughout the code.
• Remove ensemble name?
• Convert Position and Director to arma::vec and combine them.
• Create IncrementEnergy/Pressure method in world.
• See if DOSOrderParameter dependence on Histogram can be eliminated.

Copy constructor for Particle

Copy constructor for particle should handle bonded interactions and cloning children appropriately to maintain same hierarchy for the new object.

Config file load DOS bias

Allow users to specify a bias in the configuration file for DOS ensmebles. This also enables end of run dumps containing this information.

Convert Director to Position type

Convert Director from typedef vector to Position

File includes in json

Allow "@include" syntax in json to include external files.

Switch PushMove to pointers

Change PushMove from taking Move& to Move*.

ParticleEvent should contain prev configuration.

Title says it all. ParticlEvent should contain previous and new data. Update ElasticCoeffOP to utilize this implementation.

Exclude selected particles from random draw

Add list to allow user to exclude select particles from the random draw in a world.

Config file support for granular connectivity.

The JSON config file schema should support adding constraints to individual particles. Not necessarily as part of a molecule. Maybe fit this under connectivities?

Remove Neighbor object and store pointers in NeighborList

As above. Not sure why I created the wrapper in the first place. Perhaps to cache distances or something. But it has become a nuisance. Remove it and replace it with a list of Particle pointers. Also add member to Particle RemoveNeighbor(Particle* p) which can be facilitated with this change.

Energy breakdown. Bonded, non-bonded.

Implement energy breakdown for systems and add to SimEvent/SimFlags.

Add ClearNeighbors function.

Clearneighbors to particles for obvious reasons. Should be called in World->UpdateNieghborList.

Evaluate nonbonded interactions for particles in the same molecule.

Title says it all. This needs to be performed in the ForceFieldManager since the neighbor lists do not contain particles that are in the same molecule. This is omitted from the neighborlist on purpose to prevent a headache of identifying double counting scenarios.

Exception-safe file handling

Both ConsoleObserver and JSONObserver should have robust exception-safe file handling.

Primary objectives for 0.1 release

As SAPHRON is being geared up for 0.1 release, here is a list of big picture milestones that need to be accomplished. Each large milestone may have details which, if needed, will be broken out into other issues.

Since redesigning the move interface, many other components need to be brought up to speed. These include:

• Gibbs ensemble and tests.
• FENE forcefield.
• Species swap move.
• JSON, CSV and console observers.
• DOS ensembles and new move interface.
• Particle selector system that can be applied to moves / DOS.
• Molecule rotations. Verify against NIST benchmark data?
• Real space electrostatics a la Fennell & Gezelter.
• Update JSON builders/schema to match up with new features.
• Additional potentials (connectivities & nonbonded).
• Get/set particle mass. add to JSON.

These tasks are primarily enhancements (but necessary):

• Unify code interface (enforce constness, pointer v. ref use, etc...)
• Re-write ForceFieldManager (clean up)
• Get rid of composite Particle, make it just 1 deep.
• Remove unused files/methods.

These tasks may make it into 0.1 but are not not critical:

• Python bindings to simbuilder.
• Parallel neighbour list generation.
• Multiple walker DOS.
• Built in property average aggregators w/ custom options.

This list will be updated as time evolves.

Particle swap needs to update tail correction

Removing/inserting a particle requires the re-evaluation of the tail correction terms. This should be done as part of the FFManager rewrite.

IdentityChangeMove Redo Constructor Option

IdentityChange move should take in a list of species identities to perform swapping, both integers and strings. It should also check if particle is a primitive and perform swaps only on those.

On particle remove, clean up neighborlists as well.

Neighbor lists are not cleaned up when a particle is removed. This is pretty crucial or else there will be a null ptr error. Check particle(s) neigbhor lists before removing a particle from world.

Checkpoint File Writer General Problems

1. The observer type JSON incorrectly writes the restart for a system. It includes a "species" flag in particles with no children, which SAPHRON does not currently allow.

2. When writing the world object to JSON "components" dictate how "particles" should be listed, but "particles" are not written to match "components" causing problems reading the JSON file in SAPHRON.

MoveManager weighted probabilities

MoveManager should allow the addition of moves with weighted probabilities.

Add PBC option to SimEvents/Flags and World Properties.

Directional periodic boundary conditions in world. Should be accessible via observers as well.

Molecule Test case

Create a test case for two polyatomic molecule in a system to test bond stretching (FENE) and non-bonded interactions.

Widom insertion tail corrections

Widom insertion mu tail corrections are different form normal tail corrections. Need to account for this.
energytail is 2*energytail when calculating mutail

Restricted rotation on a sphere.

Augment Unit vector sphere move to allow for restricted rotation, for higher acceptance ratio.