yvan-sraka / samos Goto Github PK

 * ***************************************************************************
 *
 *  Copyright (C) 2013-2016 University of Dundee
 *  All rights reserved. 
 *
 *  This file is part of SAMoS (Soft Active Matter on Surfaces) program.
 *
 *  SAMoS 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 2 of the License, or
 *  (at your option) any later version.
 *
 *  SAMoS 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, see <http://www.gnu.org/licenses/>.
 *
 * ****************************************************************************


1. OS

The code has been developed and tested under Linux and Mac OS X. 
In principle it should be possible to build and run the code on 
a Windows machine. However, this would require modifying the CMake
build scripts. This has not been tested. 

2. TUTORIALS

A detailed tutorial on how to setup a simulation in SAMoS can be found in 
samos/doc/tutorial/tutorial.html

3. REQUIREMENTS

SAMoS code is written in C++ using C++98 standard. Data analysis and initial configuration 
building tools are written in Python 2.7 and require NumPy to run.

* Modern C++ compiler, such as g++ 4.4 or newer (code uses the C++98 standard)
* Boost libraries (1.48 or newer, in particular Spirit parser)
* GNU Scientific Library (GSL) - version 1.13 or newer 
* CMake (2.8 or newer) - it is recommended to install ccmake GUI
* Doxygen - optional but recommended (LaTeX support for building the PDF reference manual
* VTK library (version 5 or 6)
* CGAL library (version 4.3 or newer). NOTE: Code will fail to compile with CGAL 4.2 or older

NOTE: On Mac OS X, it is suggested to use Mac Ports to install all necessary libraries.

NOTE: SAMoS is able to generate VTP files as its output. We suggest installing and using ParaView 
to visualise the results. 

4. COMPILING 

a). Clone the code from the GitHub repository
b) cd samos (or the name of the directory you chose to download the code into)
c) mkdir build 
d) cd build
e) ccmake ../
f) Use the CMake's GUI to chose appropriate settings
g) Press 'c' key several times to configure
h) If all libraries have been found, CMake will allow you to create a Makefile. If not, please exit CMake GUI and install missing libraries.
i) Press 'g' to create Make files. This will terminate CMake's GUI is return you to the shell
j) Type 'make -j 8' (-j option tells make how many parallel threads to use to compile; on a 4-core machine one can typically use 8 threads). NOTE:
Some Linux distributions with newer C++ compilers may have problems with running 8 parallel threads and can cause the machine to crash. If this 
happens, use '-j 2', which is likely not to cause any problems on most modern computers. 
k) If the compilation is successful, an executable 'samos' should appear in the build directory. NOTE: SAMoS uses many templated libraries in Boost. 
Compiling it may take several minutes even on a very fast machine.

NOTE: Depending on the compiler, you may get a number of warning messages. Those are harmless and you may safely ignore them.  
NOTE: If you are compiling with gcc 6.x you need to explicitly state that you are using the C++98 standard. This is done by adding -std=c++98 to the
CMAKE_CXX_FLAGS variable. SAMoS will fail to compile using the C++11 standard! 

WARNING: Some Mac users have reported problems with compiling SAMoS on Sierra and High Sierra using packages installed with 'brew'. Switching to 
the 'MacPorts' seems to solve the problem.   


5. RUNNING SAMoS

The code requires two files to run:

   1. conf file containing simulation parameters, force field, integrator type, etc.
   2. data file containing initial position of particles (see configurations directory for a number of examples)

NOTE: Format of the configuration and data files can be found in the 'configurations' directory.

code is executed with 

./samos conf_file.conf

6. DIRECTORY STRUCTURE

samos 
   /FormerAnalysis   - some earlier versions of scripts for data analysis
   /analysis         - current set of tools for analysing simulation results 
   /build            - build directory (contains the executable)
   /configurations   - contains set of directories with examples of different systems that can be studies with SAMoS. Some directories 
                       contain Python scripts for generating initial configurations. 
   /doc              - Doxygen files for generating documentation
   /utils            - Several additional utilities for building initial configuration 
   /src              - Source code 
      \aligner       - Implementations of different alignment interactions that control particle orientation 
         \pair       - Pairwise aligners (alignments between pairs of particles)
         \external   - Single particle aligners (such as alignment to the extrenal field)
      /constraints   - Implementations of constraints to different curved surfaces 
      /dump          - Handles output of the simulation data (it supports several standard formats, plain text, VTP, mol2, dcd, etc.)
      /integrators   - Implements several integrators of the equations of motion
      /log           - Handles logging of the simulation state (e.g., current time step, total energy, etc.)
      /messenger     - Handles info, warning and error messages produced by the code, as well as generating metadata (JSON of XML format)
      /parser        - Set of Boost Spirit parsers for parsing configuration files
      /population    - Handles 'population' control (e.g., cell division and death, particle type change, particle removal and addition, etc.)
      /potential     - Implements various interactions (some of them may not be actual potential)
         /angle      - Angle potentials for filament simulations
         /bond       - Bond potentials for filament simulations 
         /external   - Potentials (and forces) acting on a single particle (such as external field)
         /pair       - Pair (or multibody) forces acting as the result of interparticle interactions (e.g., Lennard-Jones)
      /system        - Definition of the base classes that define the system (particles, simulation box, mesh, etc.)
      /utils         - Several utility functions (e.g., random number generator classes)


7. CREDITS

Lead developer:

Rastko Sknepnek (University of Dundee, UK) 

Major contrubutors to the code:

Silke Henkes (University of Aberdeen, UK)   - many tools for building inital configurations and analysis tools
Daniel Barton (University of Dundee, UK)    - tools for building and analysing tissue mechanics simulations 
Amit Das (National Institute for Biological Sciences, India)  - tools for building and analysing actomyosin simulations