typo in comment when using Bfull in checkModelType.H

applications/solvers/cfdemSolverIB/cfdemSolverIB.C

@@ -54,7 +54,6 @@ Contributions
 #include "implicitCouple.H"
 
 #include "averagingModel.H"
-#include "regionModel.H"
 #include "voidFractionModel.H"
 
 #include "dynamicFvMesh.H"

applications/solvers/cfdemSolverPiso/cfdemSolverPiso.C

@@ -81,6 +81,7 @@ int main(int argc, char *argv[])
 
     // create cfdemCloud
     #include "readGravitationalAcceleration.H"
+    #include "checkImCoupleM.H"
     #if defined(anisotropicRotation)
         cfdemCloudRotation particleCloud(mesh);
     #elif defined(SUPERQUADRIC_ACTIVE_FLAG)
@@ -115,8 +116,7 @@ int main(int argc, char *argv[])
             particleCloud.smoothingM().smoothenAbsolutField(particleCloud.forceM(0).impParticleForces());
         }
     
-        Info << "update Ksl.internalField()" << endl;
-        Ksl = particleCloud.momCoupleM(0).impMomSource();
+        Ksl = particleCloud.momCoupleM(particleCloud.registryM().getProperty("implicitCouple_index")).impMomSource();
         Ksl.correctBoundaryConditions();
 
         surfaceScalarField voidfractionf = fvc::interpolate(voidfraction);

applications/solvers/cfdemSolverPisoSTM/cfdemSolverPisoSTM.C

@@ -74,6 +74,7 @@ int main(int argc, char *argv[])
 
     // create cfdemCloud
     #include "readGravitationalAcceleration.H"
+    #include "checkImCoupleM.H"
     #if defined(anisotropicRotation)
         cfdemCloudRotation particleCloud(mesh);
     #else
@@ -118,7 +119,7 @@ int main(int argc, char *argv[])
         }
     
         Info << "update Ksl.internalField()" << endl;
-        Ksl = particleCloud.momCoupleM(0).impMomSource();
+        Ksl = particleCloud.momCoupleM(particleCloud.registryM().getProperty("implicitCouple_index")).impMomSource();
         Ksl.correctBoundaryConditions();
 
         surfaceScalarField voidfractionf = fvc::interpolate(voidfraction);

applications/solvers/cfdemSolverPisoScalar/Make/options

@@ -10,6 +10,7 @@ EXE_INC = \
     -I$(LIB_SRC)/transportModels \
     -I$(LIB_SRC)/transportModels/incompressible/singlePhaseTransportModel \
     -I$(LIB_SRC)/finiteVolume/lnInclude \
+    -I$(LIB_SRC)/thermophysicalModels/radiation/lnInclude \
     -I$(LIB_SRC)/meshTools/lnInclude \
     -I$(CFDEM_SRC_DIR)/lagrangian/cfdemParticle/lnInclude \
     -I$(CFDEM_SRC_DIR)/lagrangian/cfdemParticle/cfdTools \
@@ -20,6 +21,7 @@ EXE_LIBS = \
     $(CFDEM_ADD_INCOMPTURBMOD_LIBS) \
     -lincompressibleTransportModels \
     -lfiniteVolume \
+    -lradiationModels \
     -lmeshTools \
     -l$(CFDEM_LIB_NAME) \
      $(CFDEM_ADD_LIB_PATHS) \

applications/solvers/cfdemSolverPisoScalar/cfdemSolverPisoScalar.C

@@ -44,6 +44,7 @@ Description
 #else
     #include "turbulenceModel.H"
 #endif
+#include "radiationModel.H"
 #include "fixedFluxPressureFvPatchScalarField.H"
 #include "cfdemCloud.H"
 #if defined(anisotropicRotation)
@@ -66,10 +67,12 @@ int main(int argc, char *argv[])
         #include "createTimeControls.H"
     #endif
     #include "createFields.H"
+    #include "createIncompressibleRadiationModel.H"
     #include "initContinuityErrs.H"
 
     // create cfdemCloud
     #include "readGravitationalAcceleration.H"
+    #include "checkImCoupleM.H"
     #if defined(anisotropicRotation)
         cfdemCloudRotation particleCloud(mesh);
     #else
@@ -104,7 +107,7 @@ int main(int argc, char *argv[])
         }
     
         Info << "update Ksl.internalField()" << endl;
-        Ksl = particleCloud.momCoupleM(0).impMomSource();
+        Ksl = particleCloud.momCoupleM(particleCloud.registryM().getProperty("implicitCouple_index")).impMomSource();
         Ksl.correctBoundaryConditions();
 
         surfaceScalarField voidfractionf = fvc::interpolate(voidfraction);
@@ -124,16 +127,23 @@ int main(int argc, char *argv[])
         particleCloud.forceM(1).commToDEM();
 
         // solve scalar transport equation
+        {
+        alphat = turbulence->nut()/Prt;
+        alphat.correctBoundaryConditions();
+        volScalarField alphaEff("alphaEff", turbulence->nu()/Pr + alphat);
         fvScalarMatrix TEqn
         (
            fvm::ddt(voidfraction,T) - fvm::Sp(fvc::ddt(voidfraction),T)
          + fvm::div(phi, T) - fvm::Sp(fvc::div(phi),T)
-         - fvm::laplacian(DT*voidfraction, T)
+         - fvm::laplacian(alphaEff*voidfraction, T)
          ==
            Tsource
+         + radiation->ST(rhoCpRef, T)
         );
         TEqn.relax();
         TEqn.solve();
+        radiation->correct();
+        }
 
         if(particleCloud.solveFlow())
         {

applications/solvers/cfdemSolverPisoScalar/createFields.H

@@ -92,7 +92,7 @@
 //========================
 // scalar field modelling
 //========================
-    Info<< "\nCreating dummy density field rho = 1\n" << endl;
+    Info<< "\nCreating T field\n" << endl;
     volScalarField T
     (
         IOobject
@@ -134,11 +134,27 @@
         )
     );
 
-    dimensionedScalar DT
+    // kinematic turbulent thermal thermal conductivity m2/s
+    Info<< "Reading field alphat\n" << endl;
+    volScalarField alphat
     (
-        transportProperties.lookup("DT")
+        IOobject
+        (
+            "alphat",
+            runTime.timeName(),
+            mesh,
+            IOobject::MUST_READ,
+            IOobject::AUTO_WRITE
+        ),
+        mesh
     );
 
+    // Laminar Prandtl number
+    dimensionedScalar Pr("Pr", dimless, transportProperties);
+
+    // Turbulent Prandtl number
+    dimensionedScalar Prt("Prt", dimless, transportProperties);
+
 //========================
 
 //#   include "createPhi.H"

applications/utilities/cfdemPostproc/cfdemPostproc.C

@@ -71,14 +71,14 @@ int main(int argc, char *argv[])
     int DEM_dump_Interval=1000;
     particleCloud.reAllocArrays();
 
-    double **positions_;
-    double **velocities_;
-    double **radii_;
-    double **voidfractions_;
-    double **particleWeights_;
-    double **particleVolumes_;
-    double **particleV_;
-    double **cellIDs_;
+    double **positions_(NULL);
+    double **velocities_(NULL);
+    double **radii_(NULL);
+    double **voidfractions_(NULL);
+    double **particleWeights_(NULL);
+    double **particleVolumes_(NULL);
+    double **particleV_(NULL);
+    double **cellIDs_(NULL);
     
     particleCloud.dataExchangeM().allocateArray(positions_,0.,3);
     particleCloud.dataExchangeM().allocateArray(velocities_,0.,3);

doc/.gitignore

@@ -1,3 +1,7 @@
+#ignore .rst build files
+*.rst
+_tmp/*
+
 # C++.gitignore from github
 # Compiled Object files
 *.slo

doc/CFDEMcoupling_Manual.txt

@@ -1,7 +1,7 @@
-"CFDEM(R)project WWW Site"_lws :c
+"CFDEM®project WWW Site"_lws :c
 
 :line
-CFDEM(R)coupling Documentation :h2,c
+CFDEM®coupling Documentation :h2,c
 :line
 :c,image(Portfolio_CFDEMcoupling.png)
 :line
@@ -9,13 +9,13 @@ CFDEM(R)coupling Documentation :h2,c
 :link(lws,http://www.cfdem.com)
 :link(lc,CFDEMcoupling_Manual.html#comm)
 :link(of,http://www.openfoam.com)
-:link(lig,http://www.cfdem.com)
+:link(lig,https://www.cfdem.com/liggghtsr-open-source-discrete-element-method-particle-simulation-code)
 
 1. Contents :h3
 
-The CFDEM(R)coupling documentation is organized into the following sections. If you find any errors or omissions in this manual or have suggestions for useful information to add, please send an email to the developers so the CFDEM(R)coupling documentation can be improved.
+The CFDEM®coupling documentation is organized into the following sections. If you find any errors or omissions in this manual or have suggestions for useful information to add, please send an email to the developers so the CFDEM®coupling documentation can be improved.
 
-1.1 "About CFDEM(R)coupling"_#1_1
+1.1 "About CFDEM®coupling"_#1_1
 1.2 "Installation"_#1_2
 1.3 "Tutorials"_#1_3
 1.4 "couplingProperties dictionary"_#1_4
@@ -24,9 +24,9 @@ The CFDEM(R)coupling documentation is organized into the following sections. If
 
 :line
 
-1.1 About CFDEM(R)coupling :link(1_1),h4
+1.1 About CFDEM®coupling :link(1_1),h4
 
-CFDEM(R)coupling provides an open source parallel coupled CFD-DEM framework combining the strengths of "LIGGGHTS(R)"_lig DEM code and the Open Source CFD package "OpenFOAM(R)(*)"_of. The CFDEM(R)coupling toolbox allows to expand standard CFD solvers of "OpenFOAM(R)(*)"_of to include a coupling to the DEM code "LIGGGHTS(R)"_lig. In this toolbox the particle representation within the CFD solver is organized by "cloud" classes. Key functionalities are organised in sub-models (e.g. force models, data exchange models, etc.) which can easily be selected and combined by dictionary settings.
+CFDEM®coupling provides an open source parallel coupled CFD-DEM framework combining the strengths of "LIGGGHTS®"_lig DEM code and the Open Source CFD package "OpenFOAM®(*)"_of. The CFDEM®coupling toolbox allows to expand standard CFD solvers of "OpenFOAM®(*)"_of to include a coupling to the DEM code "LIGGGHTS®"_lig. In this toolbox the particle representation within the CFD solver is organized by "cloud" classes. Key functionalities are organised in sub-models (e.g. force models, data exchange models, etc.) which can easily be selected and combined by dictionary settings.
 
 The coupled solvers run fully parallel on distributed-memory clusters. Features are:
 
@@ -39,22 +39,46 @@ basic documentation is provided :l
 
 The file structure:
 
-{src} directory including the source files of the coupling toolbox and models :ulb,l
-{applications} directory including the solver files for coupled CFD-DEM simulations :l
-{doc} directory including the documentation of CFDEM(R)coupling :l
+{src} directory contains the source-code files of the CFDEM®coupling toolbox library and models :ulb,l
+{applications} directory contains the solver source files for coupled CFD-DEM simulations :l
+{doc} directory including the documentation of CFDEM®coupling :l
 {tutorials} directory including basic tutorial cases showing the functionality  :l
 :ule
 
-Details on installation are given on the "CFDEM(R)project WWW Site"_lws .
-The functionality of this CFD-DEM framework is described via "tutorial cases"_#_1_2 showing how to use different solvers and models.
+The functionality of this CFD-DEM framework is described via "tutorial cases"_#1_3 showing how to use different solvers and models.
 
-CFDEM(R)coupling stands for Computational Fluid Dynamics (CFD) -Discrete Element Method (DEM) coupling.
+CFDEM®coupling stands for Computational Fluid Dynamics (CFD) -Discrete Element Method (DEM) coupling.
 
-CFDEM(R)coupling is an open-source code, distributed freely under the terms of the GNU Public License (GPL).
+CFDEM®coupling is an open-source code, distributed freely under the terms of the GNU Public License (GPL).
 
-Core development of CFDEM(R)coupling is done by Christoph Goniva and Christoph Kloss, both at DCS Computing GmbH, 2012
+Core development of CFDEM®coupling is done by Christoph Goniva and Christoph Kloss, both at DCS Computing GmbH, 2012
 
-This documentation was written by Christoph Goniva, DCS Computing GmbH, 2012
+This documentation was written by DCS Computing GmbH, 2017
+
+:line
+How CFDEM®coupling works, a short description:
+
+The launched applications are CFDEM®coupling solvers, e.g. cfdemSolverPiso. Its job is to solve the Navier-Stokes equations with a solid phase present.
+A general formulation with a solid phase:
+
+:c,image(Eqs/NavierStokesLiquSoli.png)
+
+In general "l" denotes liquid and "s" solid properties. AlphaL is the fluid (liquid) content of a calculation-cell, the voidfraction. "rhoL" is the fluid (liquid) density, uL the fluid (liquid) velocity, p the pressure, Ksl the implicit momentum exchange term between solid and liquid phase, us the solid velocity, tau the liquid-stress-tensor, g the gravity vector and t the time. "f" is a general explicit term which can be used to explicitely exchange momentum from the solid to the liquid phase.
+
+All cfdemSolvers use a "cfdemCloud" object, which takes care of many things. The most important are:
+
+Control and communicate with the LIGGGHTS® library object. (liggghtsCommandModel and dataExchangeModel)
+Find the cell ID of a certain position, e.g. the particle center. (locateModel)
+Calculate the voidfraction field from particle positions, particle volumes and cell volumes. (voidFractionModel)
+Calculate the forces on the CFD field and the particle forces. These may be assembled by various forceModels, e.g. buyoancy and a drag-law. (forceModel and forceSubModel)
+Calculate the implicit and if necessary explicit source terms from the force fields for the Navier-Stokes-Equations, the solver needs to solve. (momCoupleModel)
+Calculate the "Us" field from particle data, map the particle data to the CFD-field. (averagingModel) :ul
+
+In the standard setting the momentum coupling model takes the calculated forces of forceModels and produces the implicit momentum source term Ksl with
+
+:c,image(Eqs/Ksl.png)
+
+More advanced solvers have also an explicit source term field f which is assembled from those forces which have the treatForceExplicit=true flag (see forceSubModels).  
 
 :line
 (*) This offering is not approved or endorsed by OpenCFD Limited, the producer of the OpenFOAM software and owner of the OPENFOAM®  and OpenCFD®  trade marks.
@@ -63,16 +87,308 @@ This documentation was written by Christoph Goniva, DCS Computing GmbH, 2012
 
 1.2 Installation :link(1_2),h4
 
-Please follow the installation routine provided at www.cfdem.com.
-In order to get the latest code version, please use the git repository at http://github.com ("githubAccess"_githubAccess_public.html). 
+:link(github,http://github.com/)
+:link(gitHelp,http://help.github.com/linux-set-up-git)
+:link(gitCFDEM,http://github.com/CFDEMproject)
+:link(gitscm,http://git-scm.com/downloads)
+:link(compOF,https://github.com/CFDEMproject/CFDEMcoupling-PUBLIC/blob/master/src/lagrangian/cfdemParticle/cfdTools/versionInfo.H)
+:link(bashrc,https://github.com/CFDEMproject/CFDEMcoupling-PUBLIC/blob/master/src/lagrangian/cfdemParticle/etc/bashrc)
+:link(downOF,https://openfoam.org/download/source/)
+:link(vtklink,http://www.vtk.org/)
+:link(ParaViewlink,https://www.paraview.org/)
 
 :line
 
+This section describes how to download repositories of the CFDEM®project from "github.com"_github .
+After setting some environment variables, LIGGGHTS® and CFDEM®coupling can be compiled.
+
+
+[Procedure:]
+
+Short summary:
+
+"Install git"_#install_1
+"Download CFDEM®project software"_#install_2
+"Download the correct OpenFOAM® version"_#install_3
+"Setup prerequisites"_#install_4
+"Setup and compile OpenFOAM®"_#install_5
+"Set environment variables and paths"_#install_6
+"Compile LIGGGHTS® and CFDEM®coupling"_#install_7
+"Additional information"_additionalInstall
+"Run your own cases"_#install_8 :ul
+
+:line
+[Install git:] :link(install_1) 
+This step is optional, but recommended. Git allows you to update the source code very easily with the git pull command.
+On debian based systems you can run
+
+sudo apt-get install git-core :pre
+
+Similar packages are available on other systems too:
+
+sudo zypper install git-core
+sudo yum install git :pre
+
+NOTE: In this tutorial the git protocol is used to transfer files. If port 9418 is closed for internet connections, please switch to "https://" instead of "git://" for git clone commands.
+
+:line
+[Download CFDEMproject software:] :link(install_2)
+With git you can clone git repositories from "github"_github . The following terminal commands will download the CFDEM®project software to your machine in the typical folder structure. The download of the post-processing tool LPP is optional and requires python-numpy.
+
+cd $HOME
+mkdir CFDEM
+cd CFDEM
+git clone git://github.com/CFDEMproject/CFDEMcoupling-PUBLIC.git
+cd $HOME
+mkdir LIGGGHTS
+cd LIGGGHTS
+git clone git://github.com/CFDEMproject/LIGGGHTS-PUBLIC.git
+git clone git://github.com/CFDEMproject/LPP.git lpp :pre
+
+If you do not have git, you can use the download buttons after visiting a repository in the "CFDEMproject project page"_gitCFDEM and unzip the archives to the proper locations. Typically github tags the folders with "-master", please rename them with
+
+cd $HOME/CFDEM
+mv CFDEMcoupling-PUBLIC-master CFDEMcoupling-PUBLIC
+cd $HOME/LIGGGHTS
+mv LIGGGHTS-PUBLIC-master LIGGGHTS-PUBLIC
+mv LPP-master lpp :pre
+
+:line
+[Download the correct OpenFOAM® version:] :link(install_3)
+All mentions of OpenFOAM® refer to "this"_footnotes . It is strongly recommended to compile OpenFOAM® yourself with the latest compatible version.
+The latest compatible OpenFOAM®-version can be found in  the in your local copy of CFDEM®coupling in src/lagrangian/cfdemParticle/cfdTools/versionInfo.H, or directly at "github"_compOF .
+Look for the git commit hashtag in the following line:
+
+word OFversion="<OF-Release>-commit-<commitHashtag>";
+e.g. word OFversion="3.0.x-commit-ac3f6c67e02f0aac3777c27f9fb7558fc3536e37"; :pre
+
+With git you can use the following recipe to get the correct version:
+
+cd $HOME
+mkdir OpenFOAM
+cd OpenFOAM
+git clone git://github.com/OpenFOAM/OpenFOAM-<OF-Release>.git
+git clone git://github.com/OpenFOAM/ThirdParty-<OF-Release>.git
+cd OpenFOAM-<OF-Release>
+git checkout <commitHashtag> :pre
+
+Without git you can visit git://github.com/OpenFOAM/OpenFOAM-<OF-Release>/tree/<commitHashtag> and use the download button.
+
+Other OpenFOAM® versions can be used for compilation, but aren't officially supported. The list includes 4.x, 2.4.x, 1612+, 1606+ and extend-3.2
+
+:line
+[Setup prerequisites for CFDEM®project:] :link(install_4)
+Prerequisites for OpenFOAM® can be found "here"_downOF .
+On an Ubuntu system (14.04+), you can use the following
+
+sudo apt-get install build-essential flex bison cmake zlib1g-dev libboost-system-dev libboost-thread-dev libopenmpi-dev openmpi-bin gnuplot libreadline-dev libncurses-dev libxt-dev libscotch-dev libptscotch-dev :pre
+
+CFDEM®project requires OpenFOAM® with a working MPI version.
+Optional, but strongly recommended is the use of "VTK"_vtklink . VTK is used to directly write data in vtk format, which is readable by "ParaView"_ParaViewlink . The minimum version is VTK 5.8, recommended is 6.3. On debian-based systems it is sufficient to run
+
+sudo apt-get install libvtk6-dev :pre
+
+For manual VTK compilation, please read the "additional installation hints"_additionalInstall .
+
+The post-processing tool lpp requires the python numpy package.
+
+sudo apt-get install python-numpy :pre
+
+:line
+[Setup and compile OpenFOAM®] :link(install_5)
+You can follow the OpenFOAM® git compilation "instructions"_downOF , with a small number of exceptions:
+CFDEM®coupling requires the WM_LABEL_SIZE=32 , which is the standard setting.
+
+On an Ubuntu system (14.04+), you can use the following steps to install OpenFOAM®:
+
+gedit ~/.bashrc 
+add the following two lines in the end, where <NofProcs> is the integer number of the processors you want to compile with. Save and exit gedit.
+"export WM_NCOMPPROCS=<NofProcs>"
+"source $HOME/OpenFOAM/OpenFOAM-<OF-Release>/etc/bashrc"
+now again in the terminal:
+source ~/.bashrc
+cd $WM_PROJECT_DIR
+foamSystemCheck
+./Allwmake :pre
+
+Additional OpenFOAM® installation hints can be found "here"_additionalInstall .
+
+:line
+[Set environment variables and paths] :link(install_6)
+Typically the CFDEM®coupling folder is tagged with the OpenFOAM® version number. To do this, perform the following steps:
+
+cd $HOME/CFDEM
+mv CFDEMcoupling-PUBLIC CFDEMcoupling-PUBLIC-$WM_PROJECT_VERSION :pre
+
+You need to set some environment variables in ~/.bashrc (if you use c-shell, manipulate ~/.cshrc accordingly). Open your .bashrc and the CFDEM®coupling bashrc file.
+
+gedit ~/.bashrc $HOME/CFDEM/CFDEMcoupling-PUBLIC-$WM_PROJECT_VERSION/src/lagrangian/cfdemParticle/etc/bashrc :pre
+
+Add the STANDARD block to the end of your bashrc and modify entries if necessary. Make sure the statements are not comments; remove the "#". Similar to:
+
+#================================================#
+#- source cfdem env vars
+export CFDEM_VERSION=PUBLIC
+export CFDEM_PROJECT_DIR=$HOME/CFDEM/CFDEMcoupling-$CFDEM_VERSION-$WM_PROJECT_VERSION
+export CFDEM_PROJECT_USER_DIR=$HOME/CFDEM/$LOGNAME-$CFDEM_VERSION-$WM_PROJECT_VERSION
+export CFDEM_bashrc=$CFDEM_PROJECT_DIR/src/lagrangian/cfdemParticle/etc/bashrc
+export CFDEM_LIGGGHTS_SRC_DIR=$HOME/LIGGGHTS/LIGGGHTS-PUBLIC/src
+export CFDEM_LIGGGHTS_MAKEFILE_NAME=auto
+export CFDEM_LPP_DIR=$HOME/LIGGGHTS/lpp/src
+. $CFDEM_bashrc
+#================================================# :pre
+
+You may insert the EXTENDED block above ". $CFDEM_bashrc" for further customization.
+The detailed description for allowed entries can be found "here"_additionalInstall .
+
+To load and check the environment you can run now
+
+source ~/.bashrc
+cfdemSysTest :pre
+
+NOTE: Many useful aliases are set with sourcing of the CFDEMcoupling bashrc, e.g. cfdemEtc . Make use of them!
+
+:line
+[Compile LIGGGHTS® and CFDEM®coupling] :link(install_7)
+To compile CFDEM®project open a new terminal and run
+
+cfdemCompCFDEMall :pre
+
+It compiles the LIGGGHTS® executable, LIGGGHTS® as a shared library, the CFDEM®coupling libraries, CFDEM®coupling solvers and CFDEM®coupling utilities. The compilation will stop, if build errors occur. Having a previous manually compiled LIGGGHTS® is not enough, it needs to be compiled as shared library with the cfdemCompLIG command. 
+
+As step by step compilation of only specific parts, the following commands are available:
+
+cfdemCompLIG
+cfdemCompCFDEMsrc
+cfdemCompCFDEmsol
+cfdenCompCFDEMuti :pre
+
+The compilation is automatically logged and the logs can be found in:
+
+$CFDEM_SRC_DIR/lagrangian/cfdemParticle/etc/log :pre
+
+In case questions concerning the installation arise, please feel free to contact our forum at "www.cfdem.com"_lws .
+
+:line
+[Run your own cases] :link(install_8)
+
+If you want to run your own cases, please do so in {$CFDEM_PROJECT_USER_DIR/run} which is automatically being generated. E.g. copy one of the tutorial cases there, adapt it to your needs.
+Changes in $CFDEM_TUT_DIR might be lost after every {git stash}.
+
+You can run all the tutorial cases by executing the alias cfdemTestTUT.
+Alternatively you can run each tutorial using the {Allrun.sh} scripts in the tutorial directories.
+
+:line
+[Backwards Compatibility:]
+
+Basically CFDEM®coupling supports one OpenFOAM® version therefore all settings are prepared for that. Nevertheless we try to maintain backwards compatibility as long as it works with reasonable effort.
+
+The supported OpenFOAM® and LIGGGHTS® versions are stated in:
+src/lagrangian/cfdemParticle/cfdTools/versionInfo.H
+
+For using other versions you can manipulate:
+src/lagrangian/cfdemParticle/etc/OFversion/OFversion.H
+(still not all functionality might work then!)
+
+:link(VTK63,http://www.vtk.org/files/release/6.3/VTK-6.3.0.zip)
+:link(VTKinst,http://www.vtk.org/Wiki/VTK/Configure_and_Build#On_Unix-like_systems)
+
+:line
+[Installation, additional information] :link(additionalInstall)
+:line
+
+[Procedure:]
+
+"Setup prerequisites"_#ainstall_4
+"Setup and compile OpenFOAM®"_#ainstall_5
+"Set environment variables and paths"_#ainstall_6
+"Compile LIGGGHTS® and CFDEM®coupling"_#ainstall_7 :ul
+
+:line
+
+[Setup prerequisites for CFDEM®project:] :link(ainstall_4)
+
+If you need to compile VTK on your machine yourself, we recommend version 6.3, which is available "here"_VTK63 . The installation guide is available "here"_VTKinst .
+
+Please note the VTK components necessary need cmake, MPI and some X11 libraries on your machine. Compilation using ccmake is recommended. In the standard configuration MPI related packages are disabled. Enable Parallel / MPI packages during configuration. For VTK-6.3 set VTK_Group_MPI:BOOL=ON .
+
+:line
+[Setup and compile OpenFOAM®] :link(ainstall_5)
+All mentions of OpenFOAM® refer to "this"_afootnotes .
+
+Often problems arise configuring OpenFOAM® to work with a specific MPI installation on a cluster. However it has built-in capability to work with nearly any MPI implementation.
+Set the following variable in the OpenFOAM® bashrc:
+
+export WM_MPLIB=SYSTEMMPI :pre
+
+Defining the following variables in your ~/.bashrc BEFORE the sourcing of OpenFOAM® will take care of the rest. This is an example for older MVAPICH installations where there is no libmpi.so, only libmpich.so :
+
+export MPI_ROOT=<path/to/mpi/installation>
+export MPI_ARCH_PATH=$MPI_ROOT
+export MPI_ARCH_FLAGS="-DMPICH_SKIP_MPICXX"
+export MPI_ARCH_INC="-I$MPI_ARCH_PATH/include"
+export MPI_ARCH_LIBS='-L$(MPI_ARCH_PATH)/lib -lmpich -lmpichcxx -lmpl -lopa -lrt' :pre
+
+:line
+[Set environment variables and paths] :link(ainstall_6)
+Detailed description of the environment variables:
+
+standard block:
+
+CFDEM_VERSION, CFDEMcoupling branch name; e.g. PUBLIC
+CFDEM_PROJECT_DIR, path to the installation directory of CFDEM®coupling
+CFDEM_PROJECT_USER_DIR, path to the user directory; used to store users simulation cases and source-code
+CFDEM_bashrc, location of the CFDEM®coupling bashrc (or cshrc)\, which sets up the environment
+CFDEM_LIGGGHTS_SRC_DIR, path to the LIGGGHTS src directory
+CFDEM_LIGGGHTS_MAKEFILE_NAME, Name of the LIGGGHTS® Makefile which defines how to compile LIGGGHTS®; more information on which Makefile to select is within the LIGGGHTS® documentation; standard is auto
+CFDEM_LPP_DIR path, to the src directory of the local lpp installation :tb
+
+extended block may be inserted above ". $CFDEM_bashrc":
+
+CFDEM_SRC_DIR, can be used to use alternative src directory
+CFDEM_SOLVER_DIR, can be used to use alternative solver directory
+CFDEM_DOC_DIR, can be used to use alternative doc directory
+CFDEM_UT_DIR, can be used to use alternative utilities directory
+CFDEM_TUT_DIR, can be used to use alternative tutorials directory
+CFDEM_LIGGGHTS_MAKEFILE_POSTIFX, if you wish to compile LIGGGHTS® to CFDEM®coupling with a postfix auto Makefile; for more information on postfixes please read the LIGGGHTS® documentation
+CFDEM_VERBOSE, if set to false\, standard output of environment variables is suppressed :tb
+
+:line
+additionalLibs:
+
+The additionalLibs are used as a centralized system for adding libraries and paths to CFDEM®coupling compilations. There is and automated detection of your OpenFOAM® version, which should select the proper additionalLibs file.
+If the automated selection of the additionalLibs fails or if you wish to set it manually to a specific file, you may set the following environment variables above ". $CFDEM_bashrc":
+
+CFDEM_ADD_LIBS_DIR, path containing the user-defined additionalLibs file
+CFDEM_ADD_LIBS_NAME, filename of the user-defined additionalLibs file :tb
+
+even further customization with variables:
+
+CFDEM_LAMMPS_LIB_DIR, alternative path to LIGGGHTS® lib folder containing additional LIGGGHTS® packages; e.g. ASPHERE
+CFDEM_LIGGGHTS_LIB_PATH, path to compiled LIGGGHTS® library; useful if the compiled LIGGGHTS® library has manually been moved from the LIGGGHTS® src path to an alternative location
+CFDEM_LIB_DIR, alternative target directory for CFDEM®coupling libraries
+CFDEM_USER_LIB_DIR, alternative target directory for CFDEM®coupling user-libraries
+CFDEM_APP_DIR, alternative target directory for CFDEMcoupling executables
+CFDEM_USER_APP_DIR, alternative target directory for CFDEM®coupling user-executables :tb
+
+:line
+[Compile LIGGGHTS® and CFDEM®coupling] :link(ainstall_7)
+
+LIGGGHTS® needs to be compiled as library with the cfdemCompLIG command. You can compile LIGGGHTS® manually as a shared library with "make -f Makefile.shlib <Makefilename>" within your LIGGGHTS® src directory.
+LIGGGHTS® is included into CFDEM®coupling by the creation of a symbolic link in $CFDEM_LIB_DIR to the LIGGGHTS shared library. This link is automatically created during the compilation of the CFDEM®coupling lagrangian library at the beginning of the make phase. This means even if you compile the lagrangian library manually with "wmake libso", the link is created.
+
+
+:line
+[Footnotes:] :link(footnotes)
+
+OPENFOAM®  is a registered trade mark of OpenCFD Limited, producer and distributor of the OpenFOAM software via wwww.openfoam.com.
+
+:line
 1.3 Tutorials :link(1_3),h4
 
 [General:]
 
-Each solver of the CFDEM(R)coupling comes with at least one tutorial example, showing its functionality and correct usage. Provided that the installation is correct, the tutorials can be run via "Allrun.sh" shell scripts. These scripts perform all necessary steps (preprocessing, run, postprocessing, visualization).
+Each solver of the CFDEM®coupling comes with at least one tutorial example, showing its functionality and correct usage. Provided that the installation is correct, the tutorials can be run via "Allrun.sh" shell scripts. These scripts perform all necessary steps (preprocessing, run, postprocessing, visualization).
 
 [Location:]
 
@@ -86,15 +402,23 @@ Each case is structured in a directory called "CFD" covering the CFD relevant se
 
 Provided that the installation is correct, the tutorials can be run via "Allrun.sh" shell script, executed by typing "./Allrun.sh". The successful run of the script might need some third party software (e.g. octave, evince, etc.).
 
+A typical Allrun.sh script executes the following steps:
+
+DEM: LIGGGHTS init run 
+CFD: mesh generation (blockMesh)
+CFD: mesh decomposition (decomposePar)
+CFDEM: parallel CFDEM run; mpirun -np X cfdemSolverXXX -parallel
+post-processing :ul
+
 [Settings:]
 
 The main settings of a simulation are done via dictionaries:
 
-The DEM setup of each case is defined by a "LIGGGHTS(R)"_lig input file located in $caseDir/DEM (e.g. in.liggghts_init). For details on the "LIGGGHTS(R)"_lig setup, please have a look at the "LIGGGHTS(R)"_lig manual.
+The DEM setup of each case is defined by a "LIGGGHTS®"_lig input file located in $caseDir/DEM (e.g. in.liggghts_init). For details on the "LIGGGHTS®"_lig setup, please have a look at the "LIGGGHTS®"_lig manual.
 
-Standard CFD settings are defined in $caseDir/CFD/constant (e.g. transportProperties, RASproperties, etc.) and $caseDir/CFD/system (e.g. fvSchemes, controlDict). You can find more information on that in "OpenFOAM(R)(*)"_of documentations (www.openFoam.com)(*).
+Standard CFD settings are defined in $caseDir/CFD/constant (e.g. transportProperties, RASproperties, etc.) and $caseDir/CFD/system (e.g. fvSchemes, controlDict). For settings related to the solver such as discretization schemes, solution settings for the equations and solver control (e.g. corrector or non-orthogonal corrector steps for non-orthogonal meshes) you can find more information in "OpenFOAM®(*)"_of documentations (www.openFoam.com)(*).
 
-Settings of the coupling routines are defined in $caseDir/CFD/constant/"couplingProperies"_#1_3 (e.g. force models, data exchange model, etc.) and $caseDir/CFD/constant/"liggghtsCommands"_#1_3 (allows to execute a LIGGGHTS(R) command during a coupled simulation).
+Settings of the coupling routines are defined in $caseDir/CFD/constant/"couplingProperies"_#1_4 (e.g. force models, data exchange model, etc.) and $caseDir/CFD/constant/"liggghtsCommands"_#1_5 (allows to execute a LIGGGHTS® command during a coupled simulation).
 
 :line
 
@@ -112,19 +436,20 @@ The dictionary is divided into two parts, "sub-models & settings" and "sub-model
 
 In "sub-models & settings" the following routines must be specified:
 
-modelType :ulb,l
-couplingInterval :l
-voidFractionModel :l
-locateModel :l
-meshMotionModel :l
-regionModel :l
-IOModel :l
-dataExchangeModel :l
-averagingModel :l
-forceModels :l
-momCoupleModels :l
-turbulenceModelType :l
-:ule
+modelType
+couplingInterval
+voidFractionModel
+locateModel
+meshMotionModel
+IOModel
+probeModel
+dataExchangeModel
+averagingModel
+clockModel
+smoothingModel
+forceModels
+momCoupleModels
+turbulenceModelType :ul
 
 In "sub-model properties" sub-dictionaries might be defined to specify model specific parameters.
 
@@ -141,11 +466,13 @@ couplingInterval :pre
 The coupling interval determines the time passing between two CFD-DEM data exchanges.
 
 A useful procedure would be:
-1) Set the DEM timestep in the in.xxx file according to the needs of the pure DEM problem.
-2) Set the "couplingInterval", which refers to the DEM timesteps. Depending on the problem you will need to have a close (small couplingInterval) or loose coupling.
-3) Choose the CFD timestep in the controlDict. It must be equal to or smaller than the coupling time, otherwise you will get the error: "Error - TS bigger than coupling interval!".
 
-Example: DEMts=0.00001s, couplingInterval=10 exchange data (=couple) will happen every 0.0001s.
+Set the DEM timestep in the in.xxx file according to the needs of the pure DEM problem.
+Set the "couplingInterval", which refers to the DEM timesteps. Depending on the problem you will need to have a close (small couplingInterval) or loose coupling.
+Choose the CFD timestep in the controlDict. It must be equal to or smaller than the coupling time, otherwise you will get the error: "Error - TS bigger than coupling interval!".
+To ensure a synchronous run, the coupling time should be a multiple of the CFD timestep, or you'll get a warning "Warning - Coupling time (= DEM time step * coupling interval) is not a multiple of  CFD time-step!" :ol
+
+Example: DEMts=1.0e-5s, couplingInterval=10 exchange data (=couple) will happen every 1.0e-4s.
 
 :line
 
@@ -153,7 +480,9 @@ Example: DEMts=0.00001s, couplingInterval=10 exchange data (=couple) will happen
 
 [General:]
 
-In the "liggghtsCommands" dictionary LIGGGHTS(R) commands being executed during a coupled CFD-DEM simulation are specified.
+In the "liggghtsCommands" dictionary LIGGGHTS® commands being executed during a coupled CFD-DEM simulation are specified.
+The most important command is the "run" command. After the start-up read of the LIGGGHTS®-input-script it is fed by CFDEM®coupling
+with commands. User-defined commands may be added.
 
 [Location:] $caseDir/CFD/constant
 
@@ -170,10 +499,6 @@ Reasonable example settings for the "liggghtsCommands" dictionary are given in t
 
 
 
-
-
-
-
 1.6 Models/Solvers :h4,link(cmd_5),link(comm)
 
 This section lists all CFDEMcoupling sub-models and solvers alphabetically, with a separate
@@ -245,8 +570,6 @@ listing below of styles within certain commands.
 "probeModel"_probeModel.html,
 "probeModel_noProbe"_probeModel_noProbe.html,
 "probeModel_particleProbe"_probeModel_particleProbe.html,
-"regionModel"_regionModel.html,
-"regionModel_allRegion"_regionModel_allRegion.html,
 "scalarTransportModel"_scalarTransportModel.html,
 "scalarTransportModel_generalManual"_scalarTransportModel_generalManual.html,
 "smoothingModel"_smoothingModel.html,

doc/IOModel.txt

@@ -19,11 +19,11 @@ model = name of IO-model to be applied :ul
 
 IOModel "off";
 
-Note: This examples list might not be complete - please look for other models (IOModel_XY) in this documentation.
+NOTE: This examples list might not be complete - please look for other models (IOModel_XY) in this documentation.
 
 [Description:]
 
-The IO-model is the base class to write data (e.g. particle properties) to files.
+The IO-model is the base class to write data (e.g. particle properties) to files within the CFD file-structure.
 
 [Restrictions:]
 
@@ -31,6 +31,6 @@ none.
 
 [Related commands:]
 
-Note: This examples list may be incomplete - please look for other models (IOModel_XY) in this documentation.
+"basicIO"_IOModel_basicIO.html, "noIO"_IOModel_noIO.html, "sophIO"_IOModel_sophIO.html, "trackIO"_IOModel_trackIO.html
 
 [Default:] none.

doc/_build/html/CFDEMcoupling_Manual.html

@@ -8,7 +8,7 @@
   
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   
-  <title>CFDEM(R)coupling Documentation &mdash; CFDEMcoupling v3.X documentation</title>
+  <title>CFDEM®coupling Documentation &mdash; CFDEMcoupling v3.X documentation</title>
   
 
   
@@ -82,9 +82,9 @@
             
                 <!-- Local TOC -->
                 <div class="local-toc"><ul>
-<li><a class="reference internal" href="#">CFDEM(R)coupling Documentation</a><ul>
+<li><a class="reference internal" href="#">CFDEM®coupling Documentation</a><ul>
 <li><a class="reference internal" href="#contents">Contents</a><ul>
-<li><a class="reference internal" href="#about-cfdem-r-coupling">About CFDEM(R)coupling</a></li>
+<li><a class="reference internal" href="#about-cfdemcoupling">About CFDEM®coupling</a></li>
 <li><a class="reference internal" href="#installation">Installation</a></li>
 <li><a class="reference internal" href="#tutorials">Tutorials</a></li>
 <li><a class="reference internal" href="#couplingproperties-dictionary">&#8220;couplingProperties&#8221; dictionary</a></li>
@@ -124,7 +124,7 @@
   <ul class="wy-breadcrumbs">
     <li><a href="#">Docs</a> &raquo;</li>
       
-    <li>CFDEM(R)coupling Documentation</li>
+    <li>CFDEM®coupling Documentation</li>
     <li class="wy-breadcrumbs-aside">
       
         
@@ -139,16 +139,16 @@
           <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
            <div itemprop="articleBody">
             
-  <div class="section" id="cfdem-r-coupling-documentation">
-<h1>CFDEM(R)coupling Documentation<a class="headerlink" href="#cfdem-r-coupling-documentation" title="Permalink to this headline">¶</a></h1>
+  <div class="section" id="cfdemcoupling-documentation">
+<h1>CFDEM®coupling Documentation<a class="headerlink" href="#cfdemcoupling-documentation" title="Permalink to this headline">¶</a></h1>
 <hr class="docutils" />
 <img alt="_images/Portfolio_CFDEMcoupling.png" class="align-center" src="_images/Portfolio_CFDEMcoupling.png" />
 <hr class="docutils" />
 <div class="section" id="contents">
 <h2>Contents<a class="headerlink" href="#contents" title="Permalink to this headline">¶</a></h2>
-<p>The CFDEM(R)coupling documentation is organized into the following sections. If you find any errors or omissions in this manual or have suggestions for useful information to add, please send an email to the developers so the CFDEM(R)coupling documentation can be improved.</p>
+<p>The CFDEM®coupling documentation is organized into the following sections. If you find any errors or omissions in this manual or have suggestions for useful information to add, please send an email to the developers so the CFDEM®coupling documentation can be improved.</p>
 <div class="line-block">
-<div class="line">1.1 <a class="reference internal" href="#id1"><em>About CFDEM(R)coupling</em></a></div>
+<div class="line">1.1 <a class="reference internal" href="#id1"><em>About CFDEM®coupling</em></a></div>
 <div class="line">1.2 <a class="reference internal" href="#id2"><em>Installation</em></a></div>
 <div class="line">1.3 <a class="reference internal" href="#id3"><em>Tutorials</em></a></div>
 <div class="line">1.4 <a class="reference internal" href="#id4"><em>couplingProperties dictionary</em></a></div>
@@ -157,9 +157,9 @@
 <div class="line"><br /></div>
 </div>
 <hr class="docutils" />
-<div class="section" id="about-cfdem-r-coupling">
-<span id="id1"></span><h3>About CFDEM(R)coupling<a class="headerlink" href="#about-cfdem-r-coupling" title="Permalink to this headline">¶</a></h3>
-<p>CFDEM(R)coupling provides an open source parallel coupled CFD-DEM framework combining the strengths of <a class="reference external" href="http://www.cfdem.com">LIGGGHTS(R)</a> DEM code and the Open Source CFD package <a class="reference external" href="http://www.openfoam.com">OpenFOAM(R)(*)</a>. The CFDEM(R)coupling toolbox allows to expand standard CFD solvers of <a class="reference external" href="http://www.openfoam.com">OpenFOAM(R)(*)</a> to include a coupling to the DEM code <a class="reference external" href="http://www.cfdem.com">LIGGGHTS(R)</a>. In this toolbox the particle representation within the CFD solver is organized by &#8220;cloud&#8221; classes. Key functionalities are organised in sub-models (e.g. force models, data exchange models, etc.) which can easily be selected and combined by dictionary settings.</p>
+<div class="section" id="about-cfdemcoupling">
+<span id="id1"></span><h3>About CFDEM®coupling<a class="headerlink" href="#about-cfdemcoupling" title="Permalink to this headline">¶</a></h3>
+<p>CFDEM®coupling provides an open source parallel coupled CFD-DEM framework combining the strengths of <a class="reference external" href="https://www.cfdem.com/liggghtsr-open-source-discrete-element-method-particle-simulation-code">LIGGGHTS®</a> DEM code and the Open Source CFD package <a class="reference external" href="http://www.openfoam.com">OpenFOAM®(*)</a>. The CFDEM®coupling toolbox allows to expand standard CFD solvers of <a class="reference external" href="http://www.openfoam.com">OpenFOAM®(*)</a> to include a coupling to the DEM code <a class="reference external" href="https://www.cfdem.com/liggghtsr-open-source-discrete-element-method-particle-simulation-code">LIGGGHTS®</a>. In this toolbox the particle representation within the CFD solver is organized by &#8220;cloud&#8221; classes. Key functionalities are organised in sub-models (e.g. force models, data exchange models, etc.) which can easily be selected and combined by dictionary settings.</p>
 <p>The coupled solvers run fully parallel on distributed-memory clusters. Features are:</p>
 <ul class="simple">
 <li>its modular approach allows users to easily implement new models</li>
@@ -170,42 +170,404 @@
 </ul>
 <p>The file structure:</p>
 <ul class="simple">
-<li><em>src</em> directory including the source files of the coupling toolbox and models</li>
-<li><em>applications</em> directory including the solver files for coupled CFD-DEM simulations</li>
-<li><em>doc</em> directory including the documentation of CFDEM(R)coupling</li>
+<li><em>src</em> directory contains the source-code files of the CFDEM®coupling toolbox library and models</li>
+<li><em>applications</em> directory contains the solver source files for coupled CFD-DEM simulations</li>
+<li><em>doc</em> directory including the documentation of CFDEM®coupling</li>
 <li><em>tutorials</em> directory including basic tutorial cases showing the functionality</li>
 </ul>
-<p>Details on installation are given on the <a class="reference external" href="http://www.cfdem.com">CFDEM(R)project WWW Site</a> .
-The functionality of this CFD-DEM framework is described via <em class="xref std std-ref">tutorial cases</em> showing how to use different solvers and models.</p>
-<p>CFDEM(R)coupling stands for Computational Fluid Dynamics (CFD) -Discrete Element Method (DEM) coupling.</p>
-<p>CFDEM(R)coupling is an open-source code, distributed freely under the terms of the GNU Public License (GPL).</p>
-<p>Core development of CFDEM(R)coupling is done by Christoph Goniva and Christoph Kloss, both at DCS Computing GmbH, 2012</p>
-<p>This documentation was written by Christoph Goniva, DCS Computing GmbH, 2012</p>
+<p>The functionality of this CFD-DEM framework is described via <a class="reference internal" href="#id3"><em>tutorial cases</em></a> showing how to use different solvers and models.</p>
+<p>CFDEM®coupling stands for Computational Fluid Dynamics (CFD) -Discrete Element Method (DEM) coupling.</p>
+<p>CFDEM®coupling is an open-source code, distributed freely under the terms of the GNU Public License (GPL).</p>
+<p>Core development of CFDEM®coupling is done by Christoph Goniva and Christoph Kloss, both at DCS Computing GmbH, 2012</p>
+<p>This documentation was written by DCS Computing GmbH, 2017</p>
+<hr class="docutils" />
+<p>How CFDEM®coupling works, a short description:</p>
+<p>The launched applications are CFDEM®coupling solvers, e.g. cfdemSolverPiso. Its job is to solve the Navier-Stokes equations with a solid phase present.
+A general formulation with a solid phase:</p>
+<img alt="_images/NavierStokesLiquSoli.png" class="align-center" src="_images/NavierStokesLiquSoli.png" />
+<p>In general &#8220;l&#8221; denotes liquid and &#8220;s&#8221; solid properties. AlphaL is the fluid (liquid) content of a calculation-cell, the voidfraction. &#8220;rhoL&#8221; is the fluid (liquid) density, uL the fluid (liquid) velocity, p the pressure, Ksl the implicit momentum exchange term between solid and liquid phase, us the solid velocity, tau the liquid-stress-tensor, g the gravity vector and t the time. &#8220;f&#8221; is a general explicit term which can be used to explicitely exchange momentum from the solid to the liquid phase.</p>
+<p>All cfdemSolvers use a &#8220;cfdemCloud&#8221; object, which takes care of many things. The most important are:</p>
+<ul class="simple">
+<li>Control and communicate with the LIGGGHTS® library object. (liggghtsCommandModel and dataExchangeModel)</li>
+<li>Find the cell ID of a certain position, e.g. the particle center. (locateModel)</li>
+<li>Calculate the voidfraction field from particle positions, particle volumes and cell volumes. (voidFractionModel)</li>
+<li>Calculate the forces on the CFD field and the particle forces. These may be assembled by various forceModels, e.g. buyoancy and a drag-law. (forceModel and forceSubModel)</li>
+<li>Calculate the implicit and if necessary explicit source terms from the force fields for the Navier-Stokes-Equations, the solver needs to solve. (momCoupleModel)</li>
+<li>Calculate the &#8220;Us&#8221; field from particle data, map the particle data to the CFD-field. (averagingModel)</li>
+</ul>
+<p>In the standard setting the momentum coupling model takes the calculated forces of forceModels and produces the implicit momentum source term Ksl with</p>
+<img alt="_images/Ksl.png" class="align-center" src="_images/Ksl.png" />
+<p>More advanced solvers have also an explicit source term field f which is assembled from those forces which have the treatForceExplicit=true flag (see forceSubModels).</p>
 <hr class="docutils" />
 <p>(*) This offering is not approved or endorsed by OpenCFD Limited, the producer of the OpenFOAM software and owner of the OPENFOAM®  and OpenCFD®  trade marks.</p>
 <hr class="docutils" />
 </div>
 <div class="section" id="installation">
 <span id="id2"></span><h3>Installation<a class="headerlink" href="#installation" title="Permalink to this headline">¶</a></h3>
-<p>Please follow the installation routine provided at www.cfdem.com.
-In order to get the latest code version, please use the git repository at <a class="reference external" href="http://github.com">http://github.com</a> (<a class="reference internal" href="githubAccess_public.html"><em>githubAccess</em></a>).</p>
+<hr class="docutils" />
+<p>This section describes how to download repositories of the CFDEM®project from <a class="reference external" href="http://github.com/">github.com</a> .
+After setting some environment variables, LIGGGHTS® and CFDEM®coupling can be compiled.</p>
+<p><strong>Procedure:</strong></p>
+<p>Short summary:</p>
+<ul class="simple">
+<li><a class="reference internal" href="#install-1"><em>Install git</em></a></li>
+<li><a class="reference internal" href="#install-2"><em>Download CFDEM®project software</em></a></li>
+<li><a class="reference internal" href="#install-3"><em>Download the correct OpenFOAM® version</em></a></li>
+<li><a class="reference internal" href="#install-4"><em>Setup prerequisites</em></a></li>
+<li><a class="reference internal" href="#install-5"><em>Setup and compile OpenFOAM®</em></a></li>
+<li><a class="reference internal" href="#install-6"><em>Set environment variables and paths</em></a></li>
+<li><a class="reference internal" href="#install-7"><em>Compile LIGGGHTS® and CFDEM®coupling</em></a></li>
+<li><a class="reference internal" href="#additionalinstall"><em>Additional information</em></a></li>
+<li><a class="reference internal" href="#install-8"><em>Run your own cases</em></a></li>
+</ul>
+<hr class="docutils" />
+<p id="install-1"><strong>Install git:</strong></p>
+<p>This step is optional, but recommended. Git allows you to update the source code very easily with the git pull command.
+On debian based systems you can run</p>
+<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install git-core
+</pre></div>
+</div>
+<p>Similar packages are available on other systems too:</p>
+<div class="highlight-python"><div class="highlight"><pre>sudo zypper install git-core
+sudo yum install git
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">In this tutorial the git protocol is used to transfer files. If port 9418 is closed for internet connections, please switch to &#8220;<a class="reference external" href="https://">https://</a>&#8221; instead of &#8220;git://&#8221; for git clone commands.</p>
+</div>
+<hr class="docutils" />
+<p id="install-2"><strong>Download CFDEMproject software:</strong></p>
+<p>With git you can clone git repositories from <a class="reference external" href="http://github.com/">github</a> . The following terminal commands will download the CFDEM®project software to your machine in the typical folder structure. The download of the post-processing tool LPP is optional and requires python-numpy.</p>
+<div class="highlight-python"><div class="highlight"><pre>cd $HOME
+mkdir CFDEM
+cd CFDEM
+git clone git://github.com/CFDEMproject/CFDEMcoupling-PUBLIC.git
+cd $HOME
+mkdir LIGGGHTS
+cd LIGGGHTS
+git clone git://github.com/CFDEMproject/LIGGGHTS-PUBLIC.git
+git clone git://github.com/CFDEMproject/LPP.git lpp
+</pre></div>
+</div>
+<p>If you do not have git, you can use the download buttons after visiting a repository in the <a class="reference external" href="http://github.com/CFDEMproject">CFDEMproject project page</a> and unzip the archives to the proper locations. Typically github tags the folders with &#8220;-master&#8221;, please rename them with</p>
+<div class="highlight-python"><div class="highlight"><pre>cd $HOME/CFDEM
+mv CFDEMcoupling-PUBLIC-master CFDEMcoupling-PUBLIC
+cd $HOME/LIGGGHTS
+mv LIGGGHTS-PUBLIC-master LIGGGHTS-PUBLIC
+mv LPP-master lpp
+</pre></div>
+</div>
+<hr class="docutils" />
+<p id="install-3"><strong>Download the correct OpenFOAM® version:</strong></p>
+<p>All mentions of OpenFOAM® refer to <a class="reference internal" href="#footnotes"><em>this</em></a> . It is strongly recommended to compile OpenFOAM® yourself with the latest compatible version.
+The latest compatible OpenFOAM®-version can be found in  the in your local copy of CFDEM®coupling in src/lagrangian/cfdemParticle/cfdTools/versionInfo.H, or directly at <a class="reference external" href="https://github.com/CFDEMproject/CFDEMcoupling-PUBLIC/blob/master/src/lagrangian/cfdemParticle/cfdTools/versionInfo.H">github</a> .
+Look for the git commit hashtag in the following line:</p>
+<div class="highlight-python"><div class="highlight"><pre>word OFversion=&quot;&lt;OF-Release&gt;-commit-&lt;commitHashtag&gt;&quot;;
+e.g. word OFversion=&quot;3.0.x-commit-ac3f6c67e02f0aac3777c27f9fb7558fc3536e37&quot;;
+</pre></div>
+</div>
+<p>With git you can use the following recipe to get the correct version:</p>
+<div class="highlight-python"><div class="highlight"><pre>cd $HOME
+mkdir OpenFOAM
+cd OpenFOAM
+git clone git://github.com/OpenFOAM/OpenFOAM-&lt;OF-Release&gt;.git
+git clone git://github.com/OpenFOAM/ThirdParty-&lt;OF-Release&gt;.git
+cd OpenFOAM-&lt;OF-Release&gt;
+git checkout &lt;commitHashtag&gt;
+</pre></div>
+</div>
+<p>Without git you can visit git://github.com/OpenFOAM/OpenFOAM-&lt;OF-Release&gt;/tree/&lt;commitHashtag&gt; and use the download button.</p>
+<p>Other OpenFOAM® versions can be used for compilation, but aren&#8217;t officially supported. The list includes 4.x, 2.4.x, 1612+, 1606+ and extend-3.2</p>
+<hr class="docutils" />
+<p id="install-4"><strong>Setup prerequisites for CFDEM®project:</strong></p>
+<p>Prerequisites for OpenFOAM® can be found <a class="reference external" href="https://openfoam.org/download/source/">here</a> .
+On an Ubuntu system (14.04+), you can use the following</p>
+<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install build-essential flex bison cmake zlib1g-dev libboost-system-dev libboost-thread-dev libopenmpi-dev openmpi-bin gnuplot libreadline-dev libncurses-dev libxt-dev libscotch-dev libptscotch-dev
+</pre></div>
+</div>
+<p>CFDEM®project requires OpenFOAM® with a working MPI version.
+Optional, but strongly recommended is the use of <a class="reference external" href="http://www.vtk.org/">VTK</a> . VTK is used to directly write data in vtk format, which is readable by <a class="reference external" href="https://www.paraview.org/">ParaView</a> . The minimum version is VTK 5.8, recommended is 6.3. On debian-based systems it is sufficient to run</p>
+<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install libvtk6-dev
+</pre></div>
+</div>
+<p>For manual VTK compilation, please read the <a class="reference internal" href="#additionalinstall"><em>additional installation hints</em></a> .</p>
+<p>The post-processing tool lpp requires the python numpy package.</p>
+<div class="highlight-python"><div class="highlight"><pre>sudo apt-get install python-numpy
+</pre></div>
+</div>
+<hr class="docutils" />
+<p id="install-5"><strong>Setup and compile OpenFOAM®</strong></p>
+<p>You can follow the OpenFOAM® git compilation <a class="reference external" href="https://openfoam.org/download/source/">instructions</a> , with a small number of exceptions:
+CFDEM®coupling requires the WM_LABEL_SIZE=32 , which is the standard setting.</p>
+<p>On an Ubuntu system (14.04+), you can use the following steps to install OpenFOAM®:</p>
+<div class="highlight-python"><div class="highlight"><pre>gedit ~/.bashrc
+add the following two lines in the end, where &lt;NofProcs&gt; is the integer number of the processors you want to compile with. Save and exit gedit.
+&quot;export WM_NCOMPPROCS=&lt;NofProcs&gt;&quot;
+&quot;source $HOME/OpenFOAM/OpenFOAM-&lt;OF-Release&gt;/etc/bashrc&quot;
+now again in the terminal:
+source ~/.bashrc
+cd $WM_PROJECT_DIR
+foamSystemCheck
+./Allwmake
+</pre></div>
+</div>
+<p>Additional OpenFOAM® installation hints can be found <a class="reference internal" href="#additionalinstall"><em>here</em></a> .</p>
+<hr class="docutils" />
+<p id="install-6"><strong>Set environment variables and paths</strong></p>
+<p>Typically the CFDEM®coupling folder is tagged with the OpenFOAM® version number. To do this, perform the following steps:</p>
+<div class="highlight-python"><div class="highlight"><pre>cd $HOME/CFDEM
+mv CFDEMcoupling-PUBLIC CFDEMcoupling-PUBLIC-$WM_PROJECT_VERSION
+</pre></div>
+</div>
+<p>You need to set some environment variables in ~/.bashrc (if you use c-shell, manipulate ~/.cshrc accordingly). Open your .bashrc and the CFDEM®coupling bashrc file.</p>
+<div class="highlight-python"><div class="highlight"><pre>gedit ~/.bashrc $HOME/CFDEM/CFDEMcoupling-PUBLIC-$WM_PROJECT_VERSION/src/lagrangian/cfdemParticle/etc/bashrc
+</pre></div>
+</div>
+<p>Add the STANDARD block to the end of your bashrc and modify entries if necessary. Make sure the statements are not comments; remove the &#8220;#&#8221;. Similar to:</p>
+<div class="highlight-python"><div class="highlight"><pre>#================================================#
+#- source cfdem env vars
+export CFDEM_VERSION=PUBLIC
+export CFDEM_PROJECT_DIR=$HOME/CFDEM/CFDEMcoupling-$CFDEM_VERSION-$WM_PROJECT_VERSION
+export CFDEM_PROJECT_USER_DIR=$HOME/CFDEM/$LOGNAME-$CFDEM_VERSION-$WM_PROJECT_VERSION
+export CFDEM_bashrc=$CFDEM_PROJECT_DIR/src/lagrangian/cfdemParticle/etc/bashrc
+export CFDEM_LIGGGHTS_SRC_DIR=$HOME/LIGGGHTS/LIGGGHTS-PUBLIC/src
+export CFDEM_LIGGGHTS_MAKEFILE_NAME=auto
+export CFDEM_LPP_DIR=$HOME/LIGGGHTS/lpp/src
+. $CFDEM_bashrc
+#================================================#
+</pre></div>
+</div>
+<p>You may insert the EXTENDED block above &#8221;. $CFDEM_bashrc&#8221; for further customization.
+The detailed description for allowed entries can be found <a class="reference internal" href="#additionalinstall"><em>here</em></a> .</p>
+<p>To load and check the environment you can run now</p>
+<div class="highlight-python"><div class="highlight"><pre>source ~/.bashrc
+cfdemSysTest
+</pre></div>
+</div>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">Many useful aliases are set with sourcing of the CFDEMcoupling bashrc, e.g. cfdemEtc . Make use of them!</p>
+</div>
+<hr class="docutils" />
+<p id="install-7"><strong>Compile LIGGGHTS® and CFDEM®coupling</strong></p>
+<p>To compile CFDEM®project open a new terminal and run</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">cfdemCompCFDEMall</span>
+</pre></div>
+</div>
+<p>It compiles the LIGGGHTS® executable, LIGGGHTS® as a shared library, the CFDEM®coupling libraries, CFDEM®coupling solvers and CFDEM®coupling utilities. The compilation will stop, if build errors occur. Having a previous manually compiled LIGGGHTS® is not enough, it needs to be compiled as shared library with the cfdemCompLIG command.</p>
+<p>As step by step compilation of only specific parts, the following commands are available:</p>
+<div class="highlight-python"><div class="highlight"><pre><span class="n">cfdemCompLIG</span>
+<span class="n">cfdemCompCFDEMsrc</span>
+<span class="n">cfdemCompCFDEmsol</span>
+<span class="n">cfdenCompCFDEMuti</span>
+</pre></div>
+</div>
+<p>The compilation is automatically logged and the logs can be found in:</p>
+<div class="highlight-python"><div class="highlight"><pre>$CFDEM_SRC_DIR/lagrangian/cfdemParticle/etc/log
+</pre></div>
+</div>
+<p>In case questions concerning the installation arise, please feel free to contact our forum at <a class="reference external" href="http://www.cfdem.com">www.cfdem.com</a> .</p>
+<hr class="docutils" />
+<p id="install-8"><strong>Run your own cases</strong></p>
+<p>If you want to run your own cases, please do so in <em>$CFDEM_PROJECT_USER_DIR/run</em> which is automatically being generated. E.g. copy one of the tutorial cases there, adapt it to your needs.
+Changes in $CFDEM_TUT_DIR might be lost after every <em>git stash</em>.</p>
+<p>You can run all the tutorial cases by executing the alias cfdemTestTUT.
+Alternatively you can run each tutorial using the <em>Allrun.sh</em> scripts in the tutorial directories.</p>
+<hr class="docutils" />
+<p><strong>Backwards Compatibility:</strong></p>
+<p>Basically CFDEM®coupling supports one OpenFOAM® version therefore all settings are prepared for that. Nevertheless we try to maintain backwards compatibility as long as it works with reasonable effort.</p>
+<p>The supported OpenFOAM® and LIGGGHTS® versions are stated in:
+src/lagrangian/cfdemParticle/cfdTools/versionInfo.H</p>
+<p>For using other versions you can manipulate:
+src/lagrangian/cfdemParticle/etc/OFversion/OFversion.H
+(still not all functionality might work then!)</p>
+<hr class="docutils" />
+<p id="additionalinstall"><strong>Installation, additional information</strong></p>
+<hr class="docutils" />
+<p><strong>Procedure:</strong></p>
+<ul class="simple">
+<li><a class="reference internal" href="#ainstall-4"><em>Setup prerequisites</em></a></li>
+<li><a class="reference internal" href="#ainstall-5"><em>Setup and compile OpenFOAM®</em></a></li>
+<li><a class="reference internal" href="#ainstall-6"><em>Set environment variables and paths</em></a></li>
+<li><a class="reference internal" href="#ainstall-7"><em>Compile LIGGGHTS® and CFDEM®coupling</em></a></li>
+</ul>
+<hr class="docutils" />
+<p id="ainstall-4"><strong>Setup prerequisites for CFDEM®project:</strong></p>
+<p>If you need to compile VTK on your machine yourself, we recommend version 6.3, which is available <a class="reference external" href="http://www.vtk.org/files/release/6.3/VTK-6.3.0.zip">here</a> . The installation guide is available <a class="reference external" href="http://www.vtk.org/Wiki/VTK/Configure_and_Build#On_Unix-like_systems">here</a> .</p>
+<p>Please note the VTK components necessary need cmake, MPI and some X11 libraries on your machine. Compilation using ccmake is recommended. In the standard configuration MPI related packages are disabled. Enable Parallel / MPI packages during configuration. For VTK-6.3 set VTK_Group_MPI:BOOL=ON .</p>
+<hr class="docutils" />
+<p id="ainstall-5"><strong>Setup and compile OpenFOAM®</strong></p>
+<p>All mentions of OpenFOAM® refer to <a class="reference external" href="afootnotes">this</a> .</p>
+<p>Often problems arise configuring OpenFOAM® to work with a specific MPI installation on a cluster. However it has built-in capability to work with nearly any MPI implementation.
+Set the following variable in the OpenFOAM® bashrc:</p>
+<div class="highlight-python"><div class="highlight"><pre>export WM_MPLIB=SYSTEMMPI
+</pre></div>
+</div>
+<p>Defining the following variables in your ~/.bashrc BEFORE the sourcing of OpenFOAM® will take care of the rest. This is an example for older MVAPICH installations where there is no libmpi.so, only libmpich.so :</p>
+<div class="highlight-python"><div class="highlight"><pre>export MPI_ROOT=&lt;path/to/mpi/installation&gt;
+export MPI_ARCH_PATH=$MPI_ROOT
+export MPI_ARCH_FLAGS=&quot;-DMPICH_SKIP_MPICXX&quot;
+export MPI_ARCH_INC=&quot;-I$MPI_ARCH_PATH/include&quot;
+export MPI_ARCH_LIBS=&#39;-L$(MPI_ARCH_PATH)/lib -lmpich -lmpichcxx -lmpl -lopa -lrt&#39;
+</pre></div>
+</div>
+<hr class="docutils" />
+<p id="ainstall-6"><strong>Set environment variables and paths</strong></p>
+<p>Detailed description of the environment variables:</p>
+<p>standard block:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="13%" />
+<col width="74%" />
+<col width="13%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>CFDEM_VERSION</td>
+<td>CFDEMcoupling branch name; e.g. PUBLIC</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-even"><td>CFDEM_PROJECT_DIR</td>
+<td>path to the installation directory of CFDEM®coupling</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-odd"><td>CFDEM_PROJECT_USER_DIR</td>
+<td>path to the user directory; used to store users simulation cases and source-code</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-even"><td>CFDEM_bashrc</td>
+<td>location of the CFDEM®coupling bashrc (or cshrc)</td>
+<td>which sets up the environment</td>
+</tr>
+<tr class="row-odd"><td>CFDEM_LIGGGHTS_SRC_DIR</td>
+<td>path to the LIGGGHTS src directory</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-even"><td>CFDEM_LIGGGHTS_MAKEFILE_NAME</td>
+<td>Name of the LIGGGHTS® Makefile which defines how to compile LIGGGHTS®; more information on which Makefile to select is within the LIGGGHTS® documentation; standard is auto</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-odd"><td>CFDEM_LPP_DIR path</td>
+<td>to the src directory of the local lpp installation</td>
+<td>&nbsp;</td>
+</tr>
+</tbody>
+</table>
+<p>extended block may be inserted above &#8221;. $CFDEM_bashrc&#8221;:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="13%" />
+<col width="64%" />
+<col width="23%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>CFDEM_SRC_DIR</td>
+<td>can be used to use alternative src directory</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-even"><td>CFDEM_SOLVER_DIR</td>
+<td>can be used to use alternative solver directory</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-odd"><td>CFDEM_DOC_DIR</td>
+<td>can be used to use alternative doc directory</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-even"><td>CFDEM_UT_DIR</td>
+<td>can be used to use alternative utilities directory</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-odd"><td>CFDEM_TUT_DIR</td>
+<td>can be used to use alternative tutorials directory</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-even"><td>CFDEM_LIGGGHTS_MAKEFILE_POSTIFX</td>
+<td>if you wish to compile LIGGGHTS® to CFDEM®coupling with a postfix auto Makefile; for more information on postfixes please read the LIGGGHTS® documentation</td>
+<td>&nbsp;</td>
+</tr>
+<tr class="row-odd"><td>CFDEM_VERBOSE</td>
+<td>if set to false</td>
+<td>standard output of environment variables is suppressed</td>
+</tr>
+</tbody>
+</table>
+<hr class="docutils" />
+<p>additionalLibs:</p>
+<p>The additionalLibs are used as a centralized system for adding libraries and paths to CFDEM®coupling compilations. There is and automated detection of your OpenFOAM® version, which should select the proper additionalLibs file.
+If the automated selection of the additionalLibs fails or if you wish to set it manually to a specific file, you may set the following environment variables above &#8221;. $CFDEM_bashrc&#8221;:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="28%" />
+<col width="72%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>CFDEM_ADD_LIBS_DIR</td>
+<td>path containing the user-defined additionalLibs file</td>
+</tr>
+<tr class="row-even"><td>CFDEM_ADD_LIBS_NAME</td>
+<td>filename of the user-defined additionalLibs file</td>
+</tr>
+</tbody>
+</table>
+<p>even further customization with variables:</p>
+<table border="1" class="docutils">
+<colgroup>
+<col width="14%" />
+<col width="86%" />
+</colgroup>
+<tbody valign="top">
+<tr class="row-odd"><td>CFDEM_LAMMPS_LIB_DIR</td>
+<td>alternative path to LIGGGHTS® lib folder containing additional LIGGGHTS® packages; e.g. ASPHERE</td>
+</tr>
+<tr class="row-even"><td>CFDEM_LIGGGHTS_LIB_PATH</td>
+<td>path to compiled LIGGGHTS® library; useful if the compiled LIGGGHTS® library has manually been moved from the LIGGGHTS® src path to an alternative location</td>
+</tr>
+<tr class="row-odd"><td>CFDEM_LIB_DIR</td>
+<td>alternative target directory for CFDEM®coupling libraries</td>
+</tr>
+<tr class="row-even"><td>CFDEM_USER_LIB_DIR</td>
+<td>alternative target directory for CFDEM®coupling user-libraries</td>
+</tr>
+<tr class="row-odd"><td>CFDEM_APP_DIR</td>
+<td>alternative target directory for CFDEMcoupling executables</td>
+</tr>
+<tr class="row-even"><td>CFDEM_USER_APP_DIR</td>
+<td>alternative target directory for CFDEM®coupling user-executables</td>
+</tr>
+</tbody>
+</table>
+<hr class="docutils" />
+<p id="ainstall-7"><strong>Compile LIGGGHTS® and CFDEM®coupling</strong></p>
+<p>LIGGGHTS® needs to be compiled as library with the cfdemCompLIG command. You can compile LIGGGHTS® manually as a shared library with &#8220;make -f Makefile.shlib &lt;Makefilename&gt;&#8221; within your LIGGGHTS® src directory.
+LIGGGHTS® is included into CFDEM®coupling by the creation of a symbolic link in $CFDEM_LIB_DIR to the LIGGGHTS shared library. This link is automatically created during the compilation of the CFDEM®coupling lagrangian library at the beginning of the make phase. This means even if you compile the lagrangian library manually with &#8220;wmake libso&#8221;, the link is created.</p>
+<hr class="docutils" />
+<p id="footnotes"><strong>Footnotes:</strong></p>
+<p>OPENFOAM®  is a registered trade mark of OpenCFD Limited, producer and distributor of the OpenFOAM software via wwww.openfoam.com.</p>
 <hr class="docutils" />
 </div>
 <div class="section" id="tutorials">
 <span id="id3"></span><h3>Tutorials<a class="headerlink" href="#tutorials" title="Permalink to this headline">¶</a></h3>
 <p><strong>General:</strong></p>
-<p>Each solver of the CFDEM(R)coupling comes with at least one tutorial example, showing its functionality and correct usage. Provided that the installation is correct, the tutorials can be run via &#8220;Allrun.sh&#8221; shell scripts. These scripts perform all necessary steps (preprocessing, run, postprocessing, visualization).</p>
+<p>Each solver of the CFDEM®coupling comes with at least one tutorial example, showing its functionality and correct usage. Provided that the installation is correct, the tutorials can be run via &#8220;Allrun.sh&#8221; shell scripts. These scripts perform all necessary steps (preprocessing, run, postprocessing, visualization).</p>
 <p><strong>Location:</strong></p>
 <p>The tutorials can be found in the directory $CFDEM_PROJECT_DIR/tutorials, which can be reached by typing &#8220;cfdemTut&#8221;</p>
 <p><strong>Structure:</strong></p>
 <p>Each case is structured in a directory called &#8220;CFD&#8221; covering the CFD relevant settings and data, and a dirctory called &#8220;DEM&#8221; covering the DEM relevant settings and data. This allows to easily expand a pure CFD or DEM simulation case to a coupled case.</p>
 <p><strong>Usage:</strong></p>
 <p>Provided that the installation is correct, the tutorials can be run via &#8220;Allrun.sh&#8221; shell script, executed by typing &#8221;./Allrun.sh&#8221;. The successful run of the script might need some third party software (e.g. octave, evince, etc.).</p>
+<p>A typical Allrun.sh script executes the following steps:</p>
+<ul class="simple">
+<li>DEM: LIGGGHTS init run</li>
+<li>CFD: mesh generation (blockMesh)</li>
+<li>CFD: mesh decomposition (decomposePar)</li>
+<li>CFDEM: parallel CFDEM run; mpirun -np X cfdemSolverXXX -parallel</li>
+<li>post-processing</li>
+</ul>
 <p><strong>Settings:</strong></p>
 <p>The main settings of a simulation are done via dictionaries:</p>
-<p>The DEM setup of each case is defined by a <a class="reference external" href="http://www.cfdem.com">LIGGGHTS(R)</a> input file located in $caseDir/DEM (e.g. in.liggghts_init). For details on the <a class="reference external" href="http://www.cfdem.com">LIGGGHTS(R)</a> setup, please have a look at the <a class="reference external" href="http://www.cfdem.com">LIGGGHTS(R)</a> manual.</p>
-<p>Standard CFD settings are defined in $caseDir/CFD/constant (e.g. transportProperties, RASproperties, etc.) and $caseDir/CFD/system (e.g. fvSchemes, controlDict). You can find more information on that in <a class="reference external" href="http://www.openfoam.com">OpenFOAM(R)(*)</a> documentations (www.openFoam.com)(*).</p>
-<p>Settings of the coupling routines are defined in $caseDir/CFD/constant/<a class="reference internal" href="#id3"><em>couplingProperies</em></a> (e.g. force models, data exchange model, etc.) and $caseDir/CFD/constant/<a class="reference internal" href="#id3"><em>liggghtsCommands</em></a> (allows to execute a LIGGGHTS(R) command during a coupled simulation).</p>
+<p>The DEM setup of each case is defined by a <a class="reference external" href="https://www.cfdem.com/liggghtsr-open-source-discrete-element-method-particle-simulation-code">LIGGGHTS®</a> input file located in $caseDir/DEM (e.g. in.liggghts_init). For details on the <a class="reference external" href="https://www.cfdem.com/liggghtsr-open-source-discrete-element-method-particle-simulation-code">LIGGGHTS®</a> setup, please have a look at the <a class="reference external" href="https://www.cfdem.com/liggghtsr-open-source-discrete-element-method-particle-simulation-code">LIGGGHTS®</a> manual.</p>
+<p>Standard CFD settings are defined in $caseDir/CFD/constant (e.g. transportProperties, RASproperties, etc.) and $caseDir/CFD/system (e.g. fvSchemes, controlDict). For settings related to the solver such as discretization schemes, solution settings for the equations and solver control (e.g. corrector or non-orthogonal corrector steps for non-orthogonal meshes) you can find more information in <a class="reference external" href="http://www.openfoam.com">OpenFOAM®(*)</a> documentations (www.openFoam.com)(*).</p>
+<p>Settings of the coupling routines are defined in $caseDir/CFD/constant/<a class="reference internal" href="#id4"><em>couplingProperies</em></a> (e.g. force models, data exchange model, etc.) and $caseDir/CFD/constant/<a class="reference internal" href="#id5"><em>liggghtsCommands</em></a> (allows to execute a LIGGGHTS® command during a coupled simulation).</p>
 <hr class="docutils" />
 </div>
 <div class="section" id="couplingproperties-dictionary">
@@ -222,10 +584,12 @@ In order to get the latest code version, please use the git repository at <a cla
 <li>voidFractionModel</li>
 <li>locateModel</li>
 <li>meshMotionModel</li>
-<li>regionModel</li>
 <li>IOModel</li>
+<li>probeModel</li>
 <li>dataExchangeModel</li>
 <li>averagingModel</li>
+<li>clockModel</li>
+<li>smoothingModel</li>
 <li>forceModels</li>
 <li>momCoupleModels</li>
 <li>turbulenceModelType</li>
@@ -241,17 +605,22 @@ In order to get the latest code version, please use the git repository at <a cla
 </pre></div>
 </div>
 <p>The coupling interval determines the time passing between two CFD-DEM data exchanges.</p>
-<p>A useful procedure would be:
-1) Set the DEM timestep in the in.xxx file according to the needs of the pure DEM problem.
-2) Set the &#8220;couplingInterval&#8221;, which refers to the DEM timesteps. Depending on the problem you will need to have a close (small couplingInterval) or loose coupling.
-3) Choose the CFD timestep in the controlDict. It must be equal to or smaller than the coupling time, otherwise you will get the error: &#8220;Error - TS bigger than coupling interval!&#8221;.</p>
-<p>Example: DEMts=0.00001s, couplingInterval=10 exchange data (=couple) will happen every 0.0001s.</p>
+<p>A useful procedure would be:</p>
+<ol class="arabic simple">
+<li>Set the DEM timestep in the in.xxx file according to the needs of the pure DEM problem.</li>
+<li>Set the &#8220;couplingInterval&#8221;, which refers to the DEM timesteps. Depending on the problem you will need to have a close (small couplingInterval) or loose coupling.</li>
+<li>Choose the CFD timestep in the controlDict. It must be equal to or smaller than the coupling time, otherwise you will get the error: &#8220;Error - TS bigger than coupling interval!&#8221;.</li>
+<li>To ensure a synchronous run, the coupling time should be a multiple of the CFD timestep, or you&#8217;ll get a warning &#8220;Warning - Coupling time (= DEM time step * coupling interval) is not a multiple of  CFD time-step!&#8221;</li>
+</ol>
+<p>Example: DEMts=1.0e-5s, couplingInterval=10 exchange data (=couple) will happen every 1.0e-4s.</p>
 <hr class="docutils" />
 </div>
 <div class="section" id="liggghtscommands-dictionary">
 <span id="id5"></span><h3>&#8220;liggghtsCommands&#8221; dictionary<a class="headerlink" href="#liggghtscommands-dictionary" title="Permalink to this headline">¶</a></h3>
 <p><strong>General:</strong></p>
-<p>In the &#8220;liggghtsCommands&#8221; dictionary LIGGGHTS(R) commands being executed during a coupled CFD-DEM simulation are specified.</p>
+<p>In the &#8220;liggghtsCommands&#8221; dictionary LIGGGHTS® commands being executed during a coupled CFD-DEM simulation are specified.
+The most important command is the &#8220;run&#8221; command. After the start-up read of the LIGGGHTS®-input-script it is fed by CFDEM®coupling
+with commands. User-defined commands may be added.</p>
 <p><strong>Location:</strong> $caseDir/CFD/constant</p>
 <p><strong>Structure:</strong></p>
 <p>The dictionary is divided into two parts, first a list of &#8220;liggghtsCommandModels&#8221; is defined, then the settings for each model must be specified.</p>
@@ -366,27 +735,24 @@ listing below of styles within certain commands.</p>
 <td><a class="reference internal" href="probeModel_noProbe.html"><em>probeModel_noProbe</em></a></td>
 </tr>
 <tr class="row-odd"><td><a class="reference internal" href="probeModel_particleProbe.html"><em>probeModel_particleProbe</em></a></td>
-<td><a class="reference internal" href="regionModel.html"><em>regionModel</em></a></td>
-</tr>
-<tr class="row-even"><td><a class="reference internal" href="regionModel_allRegion.html"><em>regionModel_allRegion</em></a></td>
 <td><a class="reference internal" href="scalarTransportModel.html"><em>scalarTransportModel</em></a></td>
 </tr>
-<tr class="row-odd"><td><a class="reference internal" href="scalarTransportModel_generalManual.html"><em>scalarTransportModel_generalManual</em></a></td>
+<tr class="row-even"><td><a class="reference internal" href="scalarTransportModel_generalManual.html"><em>scalarTransportModel_generalManual</em></a></td>
 <td><a class="reference internal" href="smoothingModel.html"><em>smoothingModel</em></a></td>
 </tr>
-<tr class="row-even"><td><a class="reference internal" href="smoothingModel_constDiffSmoothing.html"><em>smoothingModel_constDiffSmoothing</em></a></td>
+<tr class="row-odd"><td><a class="reference internal" href="smoothingModel_constDiffSmoothing.html"><em>smoothingModel_constDiffSmoothing</em></a></td>
 <td><a class="reference internal" href="smoothingModel_noSmoothing.html"><em>smoothingModel_noSmoothing</em></a></td>
 </tr>
-<tr class="row-odd"><td><a class="reference internal" href="voidFractionModel.html"><em>voidfractionModel</em></a></td>
+<tr class="row-even"><td><a class="reference internal" href="voidFractionModel.html"><em>voidfractionModel</em></a></td>
 <td><a class="reference internal" href="voidFractionModel_GaussVoidFraction.html"><em>voidfractionModel_GaussVoidFraction</em></a></td>
 </tr>
-<tr class="row-even"><td><a class="reference internal" href="voidFractionModel_IBVoidFraction.html"><em>voidfractionModel_IBVoidFraction</em></a></td>
+<tr class="row-odd"><td><a class="reference internal" href="voidFractionModel_IBVoidFraction.html"><em>voidfractionModel_IBVoidFraction</em></a></td>
 <td><a class="reference internal" href="voidFractionModel_bigParticleVoidFraction.html"><em>voidfractionModel_bigParticleVoidFraction</em></a></td>
 </tr>
-<tr class="row-odd"><td><a class="reference internal" href="voidFractionModel_centreVoidFraction.html"><em>voidfractionModel_centreVoidFraction</em></a></td>
+<tr class="row-even"><td><a class="reference internal" href="voidFractionModel_centreVoidFraction.html"><em>voidfractionModel_centreVoidFraction</em></a></td>
 <td><a class="reference internal" href="voidFractionModel_dividedVoidFraction.html"><em>voidfractionModel_dividedVoidFraction</em></a></td>
 </tr>
-<tr class="row-even"><td><a class="reference internal" href="voidFractionModel_noVoidFraction.html"><em>voidfractionModel_noVoidFractionVoidFraction</em></a></td>
+<tr class="row-odd"><td><a class="reference internal" href="voidFractionModel_noVoidFraction.html"><em>voidfractionModel_noVoidFractionVoidFraction</em></a></td>
 <td><a class="reference internal" href="voidFractionModel_trilinearVoidFraction.html"><em>voidfractionModel_trilinearVoidFraction</em></a></td>
 </tr>
 </tbody>

doc/_build/html/IOModel.html

@@ -150,11 +150,14 @@
 <div class="section" id="examples">
 <h2>Examples<a class="headerlink" href="#examples" title="Permalink to this headline">¶</a></h2>
 <p>IOModel &#8220;off&#8221;;</p>
-<p>Note: This examples list might not be complete - please look for other models (IOModel_XY) in this documentation.</p>
+<div class="admonition note">
+<p class="first admonition-title">Note</p>
+<p class="last">This examples list might not be complete - please look for other models (IOModel_XY) in this documentation.</p>
+</div>
 </div>
 <div class="section" id="description">
 <h2>Description<a class="headerlink" href="#description" title="Permalink to this headline">¶</a></h2>
-<p>The IO-model is the base class to write data (e.g. particle properties) to files.</p>
+<p>The IO-model is the base class to write data (e.g. particle properties) to files within the CFD file-structure.</p>
 </div>
 <div class="section" id="restrictions">
 <h2>Restrictions<a class="headerlink" href="#restrictions" title="Permalink to this headline">¶</a></h2>
@@ -162,7 +165,7 @@
 </div>
 <div class="section" id="related-commands">
 <h2>Related commands<a class="headerlink" href="#related-commands" title="Permalink to this headline">¶</a></h2>
-<p>Note: This examples list may be incomplete - please look for other models (IOModel_XY) in this documentation.</p>
+<p><a class="reference internal" href="IOModel_basicIO.html"><em>basicIO</em></a>, <a class="reference internal" href="IOModel_noIO.html"><em>noIO</em></a>, <a class="reference internal" href="IOModel_sophIO.html"><em>sophIO</em></a>, <a class="reference internal" href="IOModel_trackIO.html"><em>trackIO</em></a></p>
 <p><strong>Default:</strong> none.</p>
 </div>
 </div>

doc/_build/html/_sources/CFDEMcoupling_Manual.txt

@@ -1,5 +1,5 @@
-CFDEM(R)coupling Documentation
-******************************
+CFDEM®coupling Documentation
+****************************
 
 
 ----------
@@ -24,16 +24,16 @@ CFDEM(R)coupling Documentation
 
 
 
-.. _lig: http://www.cfdem.com
+.. _lig: https://www.cfdem.com/liggghtsr-open-source-discrete-element-method-particle-simulation-code
 
 
 
 Contents
 ========
 
-The CFDEM(R)coupling documentation is organized into the following sections. If you find any errors or omissions in this manual or have suggestions for useful information to add, please send an email to the developers so the CFDEM(R)coupling documentation can be improved.
+The CFDEM®coupling documentation is organized into the following sections. If you find any errors or omissions in this manual or have suggestions for useful information to add, please send an email to the developers so the CFDEM®coupling documentation can be improved.
 
-| 1.1 :ref:`About CFDEM(R)coupling <1_1>`
+| 1.1 :ref:`About CFDEM®coupling <1_1>`
 | 1.2 :ref:`Installation <1_2>`
 | 1.3 :ref:`Tutorials <1_3>`
 | 1.4 :ref:`couplingProperties dictionary <1_4>`
@@ -47,10 +47,10 @@ The CFDEM(R)coupling documentation is organized into the following sections. If
 
 .. _1_1:
 
-About CFDEM(R)coupling
-----------------------
+About CFDEM®coupling
+--------------------
 
-CFDEM(R)coupling provides an open source parallel coupled CFD-DEM framework combining the strengths of `LIGGGHTS(R) <lig_>`_ DEM code and the Open Source CFD package `OpenFOAM(R)(*) <of_>`_. The CFDEM(R)coupling toolbox allows to expand standard CFD solvers of `OpenFOAM(R)(*) <of_>`_ to include a coupling to the DEM code `LIGGGHTS(R) <lig_>`_. In this toolbox the particle representation within the CFD solver is organized by "cloud" classes. Key functionalities are organised in sub-models (e.g. force models, data exchange models, etc.) which can easily be selected and combined by dictionary settings.
+CFDEM®coupling provides an open source parallel coupled CFD-DEM framework combining the strengths of `LIGGGHTS® <lig_>`_ DEM code and the Open Source CFD package `OpenFOAM®(*) <of_>`_. The CFDEM®coupling toolbox allows to expand standard CFD solvers of `OpenFOAM®(*) <of_>`_ to include a coupling to the DEM code `LIGGGHTS® <lig_>`_. In this toolbox the particle representation within the CFD solver is organized by "cloud" classes. Key functionalities are organised in sub-models (e.g. force models, data exchange models, etc.) which can easily be selected and combined by dictionary settings.
 
 The coupled solvers run fully parallel on distributed-memory clusters. Features are:
 
@@ -63,22 +63,51 @@ The coupled solvers run fully parallel on distributed-memory clusters. Features
 
 The file structure:
 
-* *src* directory including the source files of the coupling toolbox and models
-* *applications* directory including the solver files for coupled CFD-DEM simulations
-* *doc* directory including the documentation of CFDEM(R)coupling
+* *src* directory contains the source-code files of the CFDEM®coupling toolbox library and models
+* *applications* directory contains the solver source files for coupled CFD-DEM simulations
+* *doc* directory including the documentation of CFDEM®coupling
 * *tutorials* directory including basic tutorial cases showing the functionality
 
 
-Details on installation are given on the `CFDEM(R)project WWW Site <lws_>`_ .
-The functionality of this CFD-DEM framework is described via :ref:`tutorial cases <_1_2>` showing how to use different solvers and models.
+The functionality of this CFD-DEM framework is described via :ref:`tutorial cases <1_3>` showing how to use different solvers and models.
 
-CFDEM(R)coupling stands for Computational Fluid Dynamics (CFD) -Discrete Element Method (DEM) coupling.
+CFDEM®coupling stands for Computational Fluid Dynamics (CFD) -Discrete Element Method (DEM) coupling.
 
-CFDEM(R)coupling is an open-source code, distributed freely under the terms of the GNU Public License (GPL).
+CFDEM®coupling is an open-source code, distributed freely under the terms of the GNU Public License (GPL).
 
-Core development of CFDEM(R)coupling is done by Christoph Goniva and Christoph Kloss, both at DCS Computing GmbH, 2012
+Core development of CFDEM®coupling is done by Christoph Goniva and Christoph Kloss, both at DCS Computing GmbH, 2012
 
-This documentation was written by Christoph Goniva, DCS Computing GmbH, 2012
+This documentation was written by DCS Computing GmbH, 2017
+
+
+----------
+
+
+How CFDEM®coupling works, a short description:
+
+The launched applications are CFDEM®coupling solvers, e.g. cfdemSolverPiso. Its job is to solve the Navier-Stokes equations with a solid phase present.
+A general formulation with a solid phase:
+
+.. image:: Eqs/NavierStokesLiquSoli.png
+   :align: center
+
+In general "l" denotes liquid and "s" solid properties. AlphaL is the fluid (liquid) content of a calculation-cell, the voidfraction. "rhoL" is the fluid (liquid) density, uL the fluid (liquid) velocity, p the pressure, Ksl the implicit momentum exchange term between solid and liquid phase, us the solid velocity, tau the liquid-stress-tensor, g the gravity vector and t the time. "f" is a general explicit term which can be used to explicitely exchange momentum from the solid to the liquid phase.
+
+All cfdemSolvers use a "cfdemCloud" object, which takes care of many things. The most important are:
+
+* Control and communicate with the LIGGGHTS® library object. (liggghtsCommandModel and dataExchangeModel)
+* Find the cell ID of a certain position, e.g. the particle center. (locateModel)
+* Calculate the voidfraction field from particle positions, particle volumes and cell volumes. (voidFractionModel)
+* Calculate the forces on the CFD field and the particle forces. These may be assembled by various forceModels, e.g. buyoancy and a drag-law. (forceModel and forceSubModel)
+* Calculate the implicit and if necessary explicit source terms from the force fields for the Navier-Stokes-Equations, the solver needs to solve. (momCoupleModel)
+* Calculate the "Us" field from particle data, map the particle data to the CFD-field. (averagingModel)
+
+In the standard setting the momentum coupling model takes the calculated forces of forceModels and produces the implicit momentum source term Ksl with
+
+.. image:: Eqs/Ksl.png
+   :align: center
+
+More advanced solvers have also an explicit source term field f which is assembled from those forces which have the treatForceExplicit=true flag (see forceSubModels).
 
 
 ----------
@@ -95,8 +124,487 @@ This documentation was written by Christoph Goniva, DCS Computing GmbH, 2012
 Installation
 ------------
 
-Please follow the installation routine provided at www.cfdem.com.
-In order to get the latest code version, please use the git repository at http://github.com (:doc:`githubAccess <githubAccess_public>`).
+.. _github: http://github.com/
+
+
+
+.. _gitHelp: http://help.github.com/linux-set-up-git
+
+
+
+.. _gitCFDEM: http://github.com/CFDEMproject
+
+
+
+.. _gitscm: http://git-scm.com/downloads
+
+
+
+.. _compOF: https://github.com/CFDEMproject/CFDEMcoupling-PUBLIC/blob/master/src/lagrangian/cfdemParticle/cfdTools/versionInfo.H
+
+
+
+.. _bashrc: https://github.com/CFDEMproject/CFDEMcoupling-PUBLIC/blob/master/src/lagrangian/cfdemParticle/etc/bashrc
+
+
+
+.. _downOF: https://openfoam.org/download/source/
+
+
+
+.. _vtklink: http://www.vtk.org/
+
+
+
+.. _ParaViewlink: https://www.paraview.org/
+
+
+
+
+----------
+
+
+This section describes how to download repositories of the CFDEM®project from `github.com <github_>`_ .
+After setting some environment variables, LIGGGHTS® and CFDEM®coupling can be compiled.
+
+**Procedure:**
+
+Short summary:
+
+* :ref:`Install git <install_1>`
+* :ref:`Download CFDEM®project software <install_2>`
+* :ref:`Download the correct OpenFOAM® version <install_3>`
+* :ref:`Setup prerequisites <install_4>`
+* :ref:`Setup and compile OpenFOAM® <install_5>`
+* :ref:`Set environment variables and paths <install_6>`
+* :ref:`Compile LIGGGHTS® and CFDEM®coupling <install_7>`
+* :ref:`Additional information <additionalInstall>`
+* :ref:`Run your own cases <install_8>`
+
+
+----------
+
+
+.. _install_1:
+
+**Install git:** 
+
+This step is optional, but recommended. Git allows you to update the source code very easily with the git pull command.
+On debian based systems you can run
+
+.. parsed-literal::
+
+   sudo apt-get install git-core
+
+Similar packages are available on other systems too:
+
+.. parsed-literal::
+
+   sudo zypper install git-core
+   sudo yum install git
+
+.. note::
+
+   In this tutorial the git protocol is used to transfer files. If port 9418 is closed for internet connections, please switch to "https://" instead of "git://" for git clone commands.
+
+
+----------
+
+
+.. _install_2:
+
+**Download CFDEMproject software:** 
+
+With git you can clone git repositories from `github <github_>`_ . The following terminal commands will download the CFDEM®project software to your machine in the typical folder structure. The download of the post-processing tool LPP is optional and requires python-numpy.
+
+.. parsed-literal::
+
+   cd $HOME
+   mkdir CFDEM
+   cd CFDEM
+   git clone git://github.com/CFDEMproject/CFDEMcoupling-PUBLIC.git
+   cd $HOME
+   mkdir LIGGGHTS
+   cd LIGGGHTS
+   git clone git://github.com/CFDEMproject/LIGGGHTS-PUBLIC.git
+   git clone git://github.com/CFDEMproject/LPP.git lpp
+
+If you do not have git, you can use the download buttons after visiting a repository in the `CFDEMproject project page <gitCFDEM_>`_ and unzip the archives to the proper locations. Typically github tags the folders with "-master", please rename them with
+
+.. parsed-literal::
+
+   cd $HOME/CFDEM
+   mv CFDEMcoupling-PUBLIC-master CFDEMcoupling-PUBLIC
+   cd $HOME/LIGGGHTS
+   mv LIGGGHTS-PUBLIC-master LIGGGHTS-PUBLIC
+   mv LPP-master lpp
+
+
+----------
+
+
+.. _install_3:
+
+**Download the correct OpenFOAM® version:** 
+
+All mentions of OpenFOAM® refer to :ref:`this <footnotes>` . It is strongly recommended to compile OpenFOAM® yourself with the latest compatible version.
+The latest compatible OpenFOAM®-version can be found in  the in your local copy of CFDEM®coupling in src/lagrangian/cfdemParticle/cfdTools/versionInfo.H, or directly at `github <compOF_>`_ .
+Look for the git commit hashtag in the following line:
+
+.. parsed-literal::
+
+   word OFversion="<OF-Release>-commit-<commitHashtag>";
+   e.g. word OFversion="3.0.x-commit-ac3f6c67e02f0aac3777c27f9fb7558fc3536e37";
+
+With git you can use the following recipe to get the correct version:
+
+.. parsed-literal::
+
+   cd $HOME
+   mkdir OpenFOAM
+   cd OpenFOAM
+   git clone git://github.com/OpenFOAM/OpenFOAM-<OF-Release>.git
+   git clone git://github.com/OpenFOAM/ThirdParty-<OF-Release>.git
+   cd OpenFOAM-<OF-Release>
+   git checkout <commitHashtag>
+
+Without git you can visit git://github.com/OpenFOAM/OpenFOAM-<OF-Release>/tree/<commitHashtag> and use the download button.
+
+Other OpenFOAM® versions can be used for compilation, but aren't officially supported. The list includes 4.x, 2.4.x, 1612+, 1606+ and extend-3.2
+
+
+----------
+
+
+.. _install_4:
+
+**Setup prerequisites for CFDEM®project:** 
+
+Prerequisites for OpenFOAM® can be found `here <downOF_>`_ .
+On an Ubuntu system (14.04+), you can use the following
+
+.. parsed-literal::
+
+   sudo apt-get install build-essential flex bison cmake zlib1g-dev libboost-system-dev libboost-thread-dev libopenmpi-dev openmpi-bin gnuplot libreadline-dev libncurses-dev libxt-dev libscotch-dev libptscotch-dev
+
+CFDEM®project requires OpenFOAM® with a working MPI version.
+Optional, but strongly recommended is the use of `VTK <vtklink_>`_ . VTK is used to directly write data in vtk format, which is readable by `ParaView <ParaViewlink_>`_ . The minimum version is VTK 5.8, recommended is 6.3. On debian-based systems it is sufficient to run
+
+.. parsed-literal::
+
+   sudo apt-get install libvtk6-dev
+
+For manual VTK compilation, please read the :ref:`additional installation hints <additionalInstall>` .
+
+The post-processing tool lpp requires the python numpy package.
+
+.. parsed-literal::
+
+   sudo apt-get install python-numpy
+
+
+----------
+
+
+.. _install_5:
+
+**Setup and compile OpenFOAM®** 
+
+You can follow the OpenFOAM® git compilation `instructions <downOF_>`_ , with a small number of exceptions:
+CFDEM®coupling requires the WM_LABEL_SIZE=32 , which is the standard setting.
+
+On an Ubuntu system (14.04+), you can use the following steps to install OpenFOAM®:
+
+.. parsed-literal::
+
+   gedit ~/.bashrc 
+   add the following two lines in the end, where <NofProcs> is the integer number of the processors you want to compile with. Save and exit gedit.
+   "export WM_NCOMPPROCS=<NofProcs>"
+   "source $HOME/OpenFOAM/OpenFOAM-<OF-Release>/etc/bashrc"
+   now again in the terminal:
+   source ~/.bashrc
+   cd $WM_PROJECT_DIR
+   foamSystemCheck
+   ./Allwmake
+
+Additional OpenFOAM® installation hints can be found :ref:`here <additionalInstall>` .
+
+
+----------
+
+
+.. _install_6:
+
+**Set environment variables and paths** 
+
+Typically the CFDEM®coupling folder is tagged with the OpenFOAM® version number. To do this, perform the following steps:
+
+.. parsed-literal::
+
+   cd $HOME/CFDEM
+   mv CFDEMcoupling-PUBLIC CFDEMcoupling-PUBLIC-$WM_PROJECT_VERSION
+
+You need to set some environment variables in ~/.bashrc (if you use c-shell, manipulate ~/.cshrc accordingly). Open your .bashrc and the CFDEM®coupling bashrc file.
+
+.. parsed-literal::
+
+   gedit ~/.bashrc $HOME/CFDEM/CFDEMcoupling-PUBLIC-$WM_PROJECT_VERSION/src/lagrangian/cfdemParticle/etc/bashrc
+
+Add the STANDARD block to the end of your bashrc and modify entries if necessary. Make sure the statements are not comments; remove the "#". Similar to:
+
+.. parsed-literal::
+
+   #================================================#
+   #- source cfdem env vars
+   export CFDEM_VERSION=PUBLIC
+   export CFDEM_PROJECT_DIR=$HOME/CFDEM/CFDEMcoupling-$CFDEM_VERSION-$WM_PROJECT_VERSION
+   export CFDEM_PROJECT_USER_DIR=$HOME/CFDEM/$LOGNAME-$CFDEM_VERSION-$WM_PROJECT_VERSION
+   export CFDEM_bashrc=$CFDEM_PROJECT_DIR/src/lagrangian/cfdemParticle/etc/bashrc
+   export CFDEM_LIGGGHTS_SRC_DIR=$HOME/LIGGGHTS/LIGGGHTS-PUBLIC/src
+   export CFDEM_LIGGGHTS_MAKEFILE_NAME=auto
+   export CFDEM_LPP_DIR=$HOME/LIGGGHTS/lpp/src
+   . $CFDEM_bashrc
+   #================================================#
+
+You may insert the EXTENDED block above ". $CFDEM_bashrc" for further customization.
+The detailed description for allowed entries can be found :ref:`here <additionalInstall>` .
+
+To load and check the environment you can run now
+
+.. parsed-literal::
+
+   source ~/.bashrc
+   cfdemSysTest
+
+.. note::
+
+   Many useful aliases are set with sourcing of the CFDEMcoupling bashrc, e.g. cfdemEtc . Make use of them!
+
+
+----------
+
+
+.. _install_7:
+
+**Compile LIGGGHTS® and CFDEM®coupling** 
+
+To compile CFDEM®project open a new terminal and run
+
+.. parsed-literal::
+
+   cfdemCompCFDEMall
+
+It compiles the LIGGGHTS® executable, LIGGGHTS® as a shared library, the CFDEM®coupling libraries, CFDEM®coupling solvers and CFDEM®coupling utilities. The compilation will stop, if build errors occur. Having a previous manually compiled LIGGGHTS® is not enough, it needs to be compiled as shared library with the cfdemCompLIG command.
+
+As step by step compilation of only specific parts, the following commands are available:
+
+.. parsed-literal::
+
+   cfdemCompLIG
+   cfdemCompCFDEMsrc
+   cfdemCompCFDEmsol
+   cfdenCompCFDEMuti
+
+The compilation is automatically logged and the logs can be found in:
+
+.. parsed-literal::
+
+   $CFDEM_SRC_DIR/lagrangian/cfdemParticle/etc/log
+
+In case questions concerning the installation arise, please feel free to contact our forum at `www.cfdem.com <lws_>`_ .
+
+
+----------
+
+
+.. _install_8:
+
+**Run your own cases** 
+
+If you want to run your own cases, please do so in *$CFDEM_PROJECT_USER_DIR/run* which is automatically being generated. E.g. copy one of the tutorial cases there, adapt it to your needs.
+Changes in $CFDEM_TUT_DIR might be lost after every *git stash*.
+
+You can run all the tutorial cases by executing the alias cfdemTestTUT.
+Alternatively you can run each tutorial using the *Allrun.sh* scripts in the tutorial directories.
+
+
+----------
+
+
+**Backwards Compatibility:**
+
+Basically CFDEM®coupling supports one OpenFOAM® version therefore all settings are prepared for that. Nevertheless we try to maintain backwards compatibility as long as it works with reasonable effort.
+
+The supported OpenFOAM® and LIGGGHTS® versions are stated in:
+src/lagrangian/cfdemParticle/cfdTools/versionInfo.H
+
+For using other versions you can manipulate:
+src/lagrangian/cfdemParticle/etc/OFversion/OFversion.H
+(still not all functionality might work then!)
+
+.. _VTK63: http://www.vtk.org/files/release/6.3/VTK-6.3.0.zip
+
+
+
+.. _VTKinst: http://www.vtk.org/Wiki/VTK/Configure_and_Build#On_Unix-like_systems
+
+
+
+
+----------
+
+
+.. _additionalInstall:
+
+**Installation, additional information** 
+
+
+----------
+
+
+**Procedure:**
+
+* :ref:`Setup prerequisites <ainstall_4>`
+* :ref:`Setup and compile OpenFOAM® <ainstall_5>`
+* :ref:`Set environment variables and paths <ainstall_6>`
+* :ref:`Compile LIGGGHTS® and CFDEM®coupling <ainstall_7>`
+
+
+----------
+
+
+.. _ainstall_4:
+
+**Setup prerequisites for CFDEM®project:** 
+
+If you need to compile VTK on your machine yourself, we recommend version 6.3, which is available `here <VTK63_>`_ . The installation guide is available `here <VTKinst_>`_ .
+
+Please note the VTK components necessary need cmake, MPI and some X11 libraries on your machine. Compilation using ccmake is recommended. In the standard configuration MPI related packages are disabled. Enable Parallel / MPI packages during configuration. For VTK-6.3 set VTK_Group_MPI:BOOL=ON .
+
+
+----------
+
+
+.. _ainstall_5:
+
+**Setup and compile OpenFOAM®** 
+
+All mentions of OpenFOAM® refer to `this <afootnotes>`_ .
+
+Often problems arise configuring OpenFOAM® to work with a specific MPI installation on a cluster. However it has built-in capability to work with nearly any MPI implementation.
+Set the following variable in the OpenFOAM® bashrc:
+
+.. parsed-literal::
+
+   export WM_MPLIB=SYSTEMMPI
+
+Defining the following variables in your ~/.bashrc BEFORE the sourcing of OpenFOAM® will take care of the rest. This is an example for older MVAPICH installations where there is no libmpi.so, only libmpich.so :
+
+.. parsed-literal::
+
+   export MPI_ROOT=<path/to/mpi/installation>
+   export MPI_ARCH_PATH=$MPI_ROOT
+   export MPI_ARCH_FLAGS="-DMPICH_SKIP_MPICXX"
+   export MPI_ARCH_INC="-I$MPI_ARCH_PATH/include"
+   export MPI_ARCH_LIBS='-L$(MPI_ARCH_PATH)/lib -lmpich -lmpichcxx -lmpl -lopa -lrt'
+
+
+----------
+
+
+.. _ainstall_6:
+
+**Set environment variables and paths** 
+
+Detailed description of the environment variables:
+
+standard block:
+
++------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------+
+| CFDEM_VERSION                | CFDEMcoupling branch name; e.g. PUBLIC                                                                                                                                      |                               |
++------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------+
+| CFDEM_PROJECT_DIR            | path to the installation directory of CFDEM®coupling                                                                                                                        |                               |
++------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------+
+| CFDEM_PROJECT_USER_DIR       | path to the user directory; used to store users simulation cases and source-code                                                                                            |                               |
++------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------+
+| CFDEM_bashrc                 | location of the CFDEM®coupling bashrc (or cshrc)\                                                                                                                           | which sets up the environment |
++------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------+
+| CFDEM_LIGGGHTS_SRC_DIR       | path to the LIGGGHTS src directory                                                                                                                                          |                               |
++------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------+
+| CFDEM_LIGGGHTS_MAKEFILE_NAME | Name of the LIGGGHTS® Makefile which defines how to compile LIGGGHTS®; more information on which Makefile to select is within the LIGGGHTS® documentation; standard is auto |                               |
++------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------+
+| CFDEM_LPP_DIR path           | to the src directory of the local lpp installation                                                                                                                          |                               |
++------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------+-------------------------------+
+
+extended block may be inserted above ". $CFDEM_bashrc":
+
++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
+| CFDEM_SRC_DIR                   | can be used to use alternative src directory                                                                                                               |                                                        |
++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
+| CFDEM_SOLVER_DIR                | can be used to use alternative solver directory                                                                                                            |                                                        |
++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
+| CFDEM_DOC_DIR                   | can be used to use alternative doc directory                                                                                                               |                                                        |
++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
+| CFDEM_UT_DIR                    | can be used to use alternative utilities directory                                                                                                         |                                                        |
++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
+| CFDEM_TUT_DIR                   | can be used to use alternative tutorials directory                                                                                                         |                                                        |
++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
+| CFDEM_LIGGGHTS_MAKEFILE_POSTIFX | if you wish to compile LIGGGHTS® to CFDEM®coupling with a postfix auto Makefile; for more information on postfixes please read the LIGGGHTS® documentation |                                                        |
++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
+| CFDEM_VERBOSE                   | if set to false\                                                                                                                                           | standard output of environment variables is suppressed |
++---------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------+
+
+
+----------
+
+
+additionalLibs:
+
+The additionalLibs are used as a centralized system for adding libraries and paths to CFDEM®coupling compilations. There is and automated detection of your OpenFOAM® version, which should select the proper additionalLibs file.
+If the automated selection of the additionalLibs fails or if you wish to set it manually to a specific file, you may set the following environment variables above ". $CFDEM_bashrc":
+
++---------------------+------------------------------------------------------+
+| CFDEM_ADD_LIBS_DIR  | path containing the user-defined additionalLibs file |
++---------------------+------------------------------------------------------+
+| CFDEM_ADD_LIBS_NAME | filename of the user-defined additionalLibs file     |
++---------------------+------------------------------------------------------+
+
+even further customization with variables:
+
++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| CFDEM_LAMMPS_LIB_DIR    | alternative path to LIGGGHTS® lib folder containing additional LIGGGHTS® packages; e.g. ASPHERE                                                             |
++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| CFDEM_LIGGGHTS_LIB_PATH | path to compiled LIGGGHTS® library; useful if the compiled LIGGGHTS® library has manually been moved from the LIGGGHTS® src path to an alternative location |
++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| CFDEM_LIB_DIR           | alternative target directory for CFDEM®coupling libraries                                                                                                   |
++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| CFDEM_USER_LIB_DIR      | alternative target directory for CFDEM®coupling user-libraries                                                                                              |
++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| CFDEM_APP_DIR           | alternative target directory for CFDEMcoupling executables                                                                                                  |
++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
+| CFDEM_USER_APP_DIR      | alternative target directory for CFDEM®coupling user-executables                                                                                            |
++-------------------------+-------------------------------------------------------------------------------------------------------------------------------------------------------------+
+
+
+----------
+
+
+.. _ainstall_7:
+
+**Compile LIGGGHTS® and CFDEM®coupling** 
+
+LIGGGHTS® needs to be compiled as library with the cfdemCompLIG command. You can compile LIGGGHTS® manually as a shared library with "make -f Makefile.shlib <Makefilename>" within your LIGGGHTS® src directory.
+LIGGGHTS® is included into CFDEM®coupling by the creation of a symbolic link in $CFDEM_LIB_DIR to the LIGGGHTS shared library. This link is automatically created during the compilation of the CFDEM®coupling lagrangian library at the beginning of the make phase. This means even if you compile the lagrangian library manually with "wmake libso", the link is created.
+
+
+----------
+
+
+.. _footnotes:
+
+**Footnotes:** 
+
+OPENFOAM®  is a registered trade mark of OpenCFD Limited, producer and distributor of the OpenFOAM software via wwww.openfoam.com.
 
 
 ----------
@@ -109,7 +617,7 @@ Tutorials
 
 **General:**
 
-Each solver of the CFDEM(R)coupling comes with at least one tutorial example, showing its functionality and correct usage. Provided that the installation is correct, the tutorials can be run via "Allrun.sh" shell scripts. These scripts perform all necessary steps (preprocessing, run, postprocessing, visualization).
+Each solver of the CFDEM®coupling comes with at least one tutorial example, showing its functionality and correct usage. Provided that the installation is correct, the tutorials can be run via "Allrun.sh" shell scripts. These scripts perform all necessary steps (preprocessing, run, postprocessing, visualization).
 
 **Location:**
 
@@ -123,15 +631,23 @@ Each case is structured in a directory called "CFD" covering the CFD relevant se
 
 Provided that the installation is correct, the tutorials can be run via "Allrun.sh" shell script, executed by typing "./Allrun.sh". The successful run of the script might need some third party software (e.g. octave, evince, etc.).
 
+A typical Allrun.sh script executes the following steps:
+
+* DEM: LIGGGHTS init run
+* CFD: mesh generation (blockMesh)
+* CFD: mesh decomposition (decomposePar)
+* CFDEM: parallel CFDEM run; mpirun -np X cfdemSolverXXX -parallel
+* post-processing
+
 **Settings:**
 
 The main settings of a simulation are done via dictionaries:
 
-The DEM setup of each case is defined by a `LIGGGHTS(R) <lig_>`_ input file located in $caseDir/DEM (e.g. in.liggghts_init). For details on the `LIGGGHTS(R) <lig_>`_ setup, please have a look at the `LIGGGHTS(R) <lig_>`_ manual.
+The DEM setup of each case is defined by a `LIGGGHTS® <lig_>`_ input file located in $caseDir/DEM (e.g. in.liggghts_init). For details on the `LIGGGHTS® <lig_>`_ setup, please have a look at the `LIGGGHTS® <lig_>`_ manual.
 
-Standard CFD settings are defined in $caseDir/CFD/constant (e.g. transportProperties, RASproperties, etc.) and $caseDir/CFD/system (e.g. fvSchemes, controlDict). You can find more information on that in `OpenFOAM(R)(*) <of_>`_ documentations (www.openFoam.com)(*).
+Standard CFD settings are defined in $caseDir/CFD/constant (e.g. transportProperties, RASproperties, etc.) and $caseDir/CFD/system (e.g. fvSchemes, controlDict). For settings related to the solver such as discretization schemes, solution settings for the equations and solver control (e.g. corrector or non-orthogonal corrector steps for non-orthogonal meshes) you can find more information in `OpenFOAM®(*) <of_>`_ documentations (www.openFoam.com)(*).
 
-Settings of the coupling routines are defined in $caseDir/CFD/constant/:ref:`couplingProperies <1_3>` (e.g. force models, data exchange model, etc.) and $caseDir/CFD/constant/:ref:`liggghtsCommands <1_3>` (allows to execute a LIGGGHTS(R) command during a coupled simulation).
+Settings of the coupling routines are defined in $caseDir/CFD/constant/:ref:`couplingProperies <1_4>` (e.g. force models, data exchange model, etc.) and $caseDir/CFD/constant/:ref:`liggghtsCommands <1_5>` (allows to execute a LIGGGHTS® command during a coupled simulation).
 
 
 ----------
@@ -159,15 +675,16 @@ In "sub-models & settings" the following routines must be specified:
 * voidFractionModel
 * locateModel
 * meshMotionModel
-* regionModel
 * IOModel
+* probeModel
 * dataExchangeModel
 * averagingModel
+* clockModel
+* smoothingModel
 * forceModels
 * momCoupleModels
 * turbulenceModelType
 
-
 In "sub-model properties" sub-dictionaries might be defined to specify model specific parameters.
 
 **Settings:**
@@ -187,11 +704,13 @@ Reasonable example settings for the "couplingProperties" dictionary are given in
 The coupling interval determines the time passing between two CFD-DEM data exchanges.
 
 A useful procedure would be:
-1) Set the DEM timestep in the in.xxx file according to the needs of the pure DEM problem.
-2) Set the "couplingInterval", which refers to the DEM timesteps. Depending on the problem you will need to have a close (small couplingInterval) or loose coupling.
-3) Choose the CFD timestep in the controlDict. It must be equal to or smaller than the coupling time, otherwise you will get the error: "Error - TS bigger than coupling interval!".
 
-Example: DEMts=0.00001s, couplingInterval=10 exchange data (=couple) will happen every 0.0001s.
+1. Set the DEM timestep in the in.xxx file according to the needs of the pure DEM problem.
+2. Set the "couplingInterval", which refers to the DEM timesteps. Depending on the problem you will need to have a close (small couplingInterval) or loose coupling.
+3. Choose the CFD timestep in the controlDict. It must be equal to or smaller than the coupling time, otherwise you will get the error: "Error - TS bigger than coupling interval!".
+4. To ensure a synchronous run, the coupling time should be a multiple of the CFD timestep, or you'll get a warning "Warning - Coupling time (= DEM time step * coupling interval) is not a multiple of  CFD time-step!"
+
+Example: DEMts=1.0e-5s, couplingInterval=10 exchange data (=couple) will happen every 1.0e-4s.
 
 
 ----------
@@ -204,7 +723,9 @@ Example: DEMts=0.00001s, couplingInterval=10 exchange data (=couple) will happen
 
 **General:**
 
-In the "liggghtsCommands" dictionary LIGGGHTS(R) commands being executed during a coupled CFD-DEM simulation are specified.
+In the "liggghtsCommands" dictionary LIGGGHTS® commands being executed during a coupled CFD-DEM simulation are specified.
+The most important command is the "run" command. After the start-up read of the LIGGGHTS®-input-script it is fed by CFDEM®coupling
+with commands. User-defined commands may be added.
 
 **Location:** $caseDir/CFD/constant
 
@@ -295,9 +816,7 @@ listing below of styles within certain commands.
 +----------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+
 | :doc:`probeModel <probeModel>`                                                         | :doc:`probeModel_noProbe <probeModel_noProbe>`                                               |
 +----------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+
-| :doc:`probeModel_particleProbe <probeModel_particleProbe>`                             | :doc:`regionModel <regionModel>`                                                             |
-+----------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+
-| :doc:`regionModel_allRegion <regionModel_allRegion>`                                   | :doc:`scalarTransportModel <scalarTransportModel>`                                           |
+| :doc:`probeModel_particleProbe <probeModel_particleProbe>`                             | :doc:`scalarTransportModel <scalarTransportModel>`                                           |
 +----------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+
 | :doc:`scalarTransportModel_generalManual <scalarTransportModel_generalManual>`         | :doc:`smoothingModel <smoothingModel>`                                                       |
 +----------------------------------------------------------------------------------------+----------------------------------------------------------------------------------------------+

doc/_build/html/_sources/IOModel.txt

@@ -19,12 +19,14 @@ Examples
 
 IOModel "off";
 
-Note: This examples list might not be complete - please look for other models (IOModel_XY) in this documentation.
+.. note::
+
+   This examples list might not be complete - please look for other models (IOModel_XY) in this documentation.
 
 Description
 """""""""""
 
-The IO-model is the base class to write data (e.g. particle properties) to files.
+The IO-model is the base class to write data (e.g. particle properties) to files within the CFD file-structure.
 
 Restrictions
 """"""""""""
@@ -35,7 +37,7 @@ none.
 Related commands
 """"""""""""""""
 
-Note: This examples list may be incomplete - please look for other models (IOModel_XY) in this documentation.
+:doc:`basicIO <IOModel_basicIO>`, :doc:`noIO <IOModel_noIO>`, :doc:`sophIO <IOModel_sophIO>`, :doc:`trackIO <IOModel_trackIO>`
 
 **Default:** none.
 

doc/_build/html/_sources/_tmp/sphinx_rtd_theme/README.txt

@@ -0,0 +1,207 @@
+.. _readthedocs.org: http://www.readthedocs.org
+.. _bower: http://www.bower.io
+.. _sphinx: http://www.sphinx-doc.org
+.. _compass: http://www.compass-style.org
+.. _sass: http://www.sass-lang.com
+.. _wyrm: http://www.github.com/snide/wyrm/
+.. _grunt: http://www.gruntjs.com
+.. _node: http://www.nodejs.com
+.. _demo: http://docs.readthedocs.org
+.. _hidden: http://sphinx-doc.org/markup/toctree.html
+
+**************************
+Read the Docs Sphinx Theme
+**************************
+
+.. contents:: 
+
+View a working demo_ over on readthedocs.org_.
+
+This is a mobile-friendly sphinx_ theme I made for readthedocs.org_. It's
+currently in development there and includes some rtd variable checks that can be ignored
+if you're just trying to use it on your project outside of that site.
+
+**This repo also exists as a submodule within the readthedocs itself**, so please make your edits to
+the SASS files here, rather than the .css files on RTD.
+
+.. image:: screen_mobile.png
+    :width: 100%
+
+Installation
+============
+
+Via package
+-----------
+
+Download the package or add it to your ``requirements.txt`` file:
+
+.. code:: bash
+
+    $ pip install sphinx_rtd_theme
+
+In your ``conf.py`` file:
+
+.. code:: python
+
+    import sphinx_rtd_theme
+
+    html_theme = "sphinx_rtd_theme"
+
+    html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+Via git or download
+-------------------
+
+Symlink or subtree the ``sphinx_rtd_theme/sphinx_rtd_theme`` repository into your documentation at
+``docs/_themes/sphinx_rtd_theme`` then add the following two settings to your Sphinx
+conf.py file:
+
+.. code:: python
+
+    html_theme = "sphinx_rtd_theme"
+    html_theme_path = ["_themes", ]
+
+Changelog
+=========
+
+v0.1.9
+------
+
+* Intermittent scrollbar visibility bug fixed. This change introduces a
+  backwards incompatible change to the theme's layout HTML. This should only be
+  a problem for derivative themes that have overridden styling of nav elements
+  using direct decendant selectors. See `#215`_ for more information.
+* Safari overscroll bug fixed
+* Version added to the nav header
+* Revision id was added to the documentation footer if you are using RTD
+* An extra block, ``extrafooter`` was added to allow extra content in the
+  document footer block
+* Fixed modernizr URL
+* Small display style changes on code blocks, figure captions, and nav elements
+
+.. _#215: https://github.com/snide/sphinx_rtd_theme/pull/215
+
+v0.1.8
+------
+
+* Start keeping changelog :)
+* Support for third and fourth level headers in the sidebar
+* Add support for Sphinx 1.3
+* Add sidebar headers for :caption: in Sphinx toctree
+* Clean up sidebar scrolling behavior so it never scrolls out of view
+
+How the Table of Contents builds
+================================
+
+Currently the left menu will build based upon any ``toctree(s)`` defined in your index.rst file.
+It outputs 2 levels of depth, which should give your visitors a high level of access to your
+docs. If no toctrees are set the theme reverts to sphinx's usual local toctree.
+
+It's important to note that if you don't follow the same styling for your rST headers across
+your documents, the toctree will misbuild, and the resulting menu might not show the correct
+depth when it renders.
+
+Also note that the table of contents is set with ``includehidden=true``. This allows you
+to set a hidden toc in your index file with the hidden_ property that will allow you
+to build a toc without it rendering in your index.
+
+By default, the navigation will "stick" to the screen as you scroll. However if your toc
+is vertically too large, it will revert to static positioning. To disable the sticky nav
+altogether change the setting in ``conf.py``.
+
+Contributing or modifying the theme
+===================================
+
+The sphinx_rtd_theme is primarily a sass_ project that requires a few other sass libraries. I'm
+using bower_ to manage these dependencies and sass_ to build the css. The good news is
+I have a very nice set of grunt_ operations that will not only load these dependencies, but watch
+for changes, rebuild the sphinx demo docs and build a distributable version of the theme.
+The bad news is this means you'll need to set up your environment similar to that
+of a front-end developer (vs. that of a python developer). That means installing node and ruby.
+
+Set up your environment
+-----------------------
+
+1. Install sphinx_ into a virtual environment.
+
+.. code::
+
+    pip install sphinx
+
+2. Install sass
+
+.. code::
+
+    gem install sass
+
+2. Install node, bower and grunt.
+
+.. code::
+
+    // Install node
+    brew install node
+
+    // Install bower and grunt
+    npm install -g bower grunt-cli
+
+    // Now that everything is installed, let's install the theme dependecies.
+    npm install
+
+Now that our environment is set up, make sure you're in your virtual environment, go to
+this repository in your terminal and run grunt:
+
+.. code::
+
+    grunt
+
+This default task will do the following **very cool things that make it worth the trouble**.
+
+1. It'll install and update any bower dependencies.
+2. It'll run sphinx and build new docs.
+3. It'll watch for changes to the sass files and build css from the changes.
+4. It'll rebuild the sphinx docs anytime it notices a change to .rst, .html, .js
+   or .css files.
+
+
+Before you create an issue
+--------------------------
+
+I don't have a lot of time to maintain this project due to other responsibilities.
+I know there are a lot of Python engineers out there that can't code sass / css and
+are unable to submit pull requests. That said, submitting random style bugs without
+at least providing sample documentation that replicates your problem is a good
+way for me to ignore your request. RST unfortunately can spit out a lot of things
+in a lot of ways. I don't have time to research your problem for you, but I do
+have time to fix the actual styling issue if you can replicate the problem for me.
+
+
+Before you send a Pull Request
+------------------------------
+
+When you're done with your edits, you can run ``grunt build`` to clean out the old
+files and rebuild a new distribution, compressing the css and cleaning out
+extraneous files. Please do this before you send in a PR.
+
+Using this theme locally, then building on Read the Docs?
+==========================================================
+
+Currently if you import sphinx_rtd_theme in your local sphinx build, then pass
+that same config to Read the Docs, it will fail, since RTD gets confused. If
+you want to run this theme locally and then also have it build on RTD, then
+you can add something like this to your config. Thanks to Daniel Oaks for this.
+
+.. code:: python
+
+    # on_rtd is whether we are on readthedocs.org, this line of code grabbed from docs.readthedocs.org
+    on_rtd = os.environ.get('READTHEDOCS', None) == 'True'
+
+    if not on_rtd:  # only import and set the theme if we're building docs locally
+        import sphinx_rtd_theme
+        html_theme = 'sphinx_rtd_theme'
+        html_theme_path = [sphinx_rtd_theme.get_html_theme_path()]
+
+    # otherwise, readthedocs.org uses their theme by default, so no need to specify it
+
+TODO
+====
+* Separate some sass variables at the theme level so you can overwrite some basic colors.

doc/_build/html/_sources/_tmp/sphinx_rtd_theme/demo_docs/source/api.txt

@@ -0,0 +1,7 @@
+:mod:`test_py_module`
+=====================
+
+.. automodule:: test_py_module.test
+    :members:
+    :private-members:
+    :special-members:

doc/_build/html/_sources/_tmp/sphinx_rtd_theme/demo_docs/source/demo.txt

@@ -0,0 +1,577 @@
+.. This is a comment. Note how any initial comments are moved by
+   transforms to after the document title, subtitle, and docinfo.
+
+================================
+ reStructuredText Demonstration
+================================
+
+.. Above is the document title, and below is the subtitle.
+   They are transformed from section titles after parsing.
+
+--------------------------------
+ Examples of Syntax Constructs
+--------------------------------
+
+.. bibliographic fields (which also require a transform):
+
+:Author: David Goodger
+:Address: 123 Example Street
+          Example, EX  Canada
+          A1B 2C3
+:Contact: docutils-develop@lists.sourceforge.net
+:Authors: Me; Myself; I
+:organization: humankind
+:date: $Date: 2012-01-03 19:23:53 +0000 (Tue, 03 Jan 2012) $
+:status: This is a "work in progress"
+:revision: $Revision: 7302 $
+:version: 1
+:copyright: This document has been placed in the public domain. You
+            may do with it as you wish. You may copy, modify,
+            redistribute, reattribute, sell, buy, rent, lease,
+            destroy, or improve it, quote it at length, excerpt,
+            incorporate, collate, fold, staple, or mutilate it, or do
+            anything else to it that your or anyone else's heart
+            desires.
+:field name: This is a generic bibliographic field.
+:field name 2:
+    Generic bibliographic fields may contain multiple body elements.
+
+    Like this.
+
+:Dedication:
+
+    For Docutils users & co-developers.
+
+:abstract:
+
+    This document is a demonstration of the reStructuredText markup
+    language, containing examples of all basic reStructuredText
+    constructs and many advanced constructs.
+
+.. meta::
+   :keywords: reStructuredText, demonstration, demo, parser
+   :description lang=en: A demonstration of the reStructuredText
+       markup language, containing examples of all basic
+       constructs and many advanced constructs.
+
+.. contents:: Table of Contents
+.. section-numbering::
+
+
+Structural Elements
+===================
+
+Section Title
+-------------
+
+That's it, the text just above this line.
+
+Transitions
+-----------
+
+Here's a transition:
+
+---------
+
+It divides the section.
+
+Body Elements
+=============
+
+Paragraphs
+----------
+
+A paragraph.
+
+Inline Markup
+`````````````
+
+Paragraphs contain text and may contain inline markup: *emphasis*,
+**strong emphasis**, ``inline literals``, standalone hyperlinks
+(http://www.python.org), external hyperlinks (Python_), internal
+cross-references (example_), external hyperlinks with embedded URIs
+(`Python web site <http://www.python.org>`__), footnote references
+(manually numbered [1]_, anonymous auto-numbered [#]_, labeled
+auto-numbered [#label]_, or symbolic [*]_), citation references
+([CIT2002]_), substitution references (|example|), and _`inline
+hyperlink targets` (see Targets_ below for a reference back to here).
+Character-level inline markup is also possible (although exceedingly
+ugly!) in *re*\ ``Structured``\ *Text*.  Problems are indicated by
+|problematic| text (generated by processing errors; this one is
+intentional).
+
+The default role for interpreted text is `Title Reference`.  Here are
+some explicit interpreted text roles: a PEP reference (:PEP:`287`); an
+RFC reference (:RFC:`2822`); a :sub:`subscript`; a :sup:`superscript`;
+and explicit roles for :emphasis:`standard` :strong:`inline`
+:literal:`markup`.
+
+.. DO NOT RE-WRAP THE FOLLOWING PARAGRAPH!
+
+Let's test wrapping and whitespace significance in inline literals:
+``This is an example of --inline-literal --text, --including some--
+strangely--hyphenated-words.  Adjust-the-width-of-your-browser-window
+to see how the text is wrapped.  -- ---- --------  Now note    the
+spacing    between the    words of    this sentence    (words
+should    be grouped    in pairs).``
+
+If the ``--pep-references`` option was supplied, there should be a
+live link to PEP 258 here.
+
+Bullet Lists
+------------
+
+- A bullet list
+
+  + Nested bullet list.
+  + Nested item 2.
+
+- Item 2.
+
+  Paragraph 2 of item 2.
+
+  * Nested bullet list.
+  * Nested item 2.
+
+    - Third level.
+    - Item 2.
+
+  * Nested item 3.
+
+Enumerated Lists
+----------------
+
+1. Arabic numerals.
+
+   a) lower alpha)
+
+      (i) (lower roman)
+
+          A. upper alpha.
+
+             I) upper roman)
+
+2. Lists that don't start at 1:
+
+   3. Three
+
+   4. Four
+
+   C. C
+
+   D. D
+
+   iii. iii
+
+   iv. iv
+
+#. List items may also be auto-enumerated.
+
+Definition Lists
+----------------
+
+Term
+    Definition
+Term : classifier
+    Definition paragraph 1.
+
+    Definition paragraph 2.
+Term
+    Definition
+
+Field Lists
+-----------
+
+:what: Field lists map field names to field bodies, like database
+       records.  They are often part of an extension syntax.  They are
+       an unambiguous variant of RFC 2822 fields.
+
+:how arg1 arg2:
+
+    The field marker is a colon, the field name, and a colon.
+
+    The field body may contain one or more body elements, indented
+    relative to the field marker.
+
+Option Lists
+------------
+
+For listing command-line options:
+
+-a            command-line option "a"
+-b file       options can have arguments
+              and long descriptions
+--long        options can be long also
+--input=file  long options can also have
+              arguments
+
+--very-long-option
+              The description can also start on the next line.
+
+              The description may contain multiple body elements,
+              regardless of where it starts.
+
+-x, -y, -z    Multiple options are an "option group".
+-v, --verbose  Commonly-seen: short & long options.
+-1 file, --one=file, --two file
+              Multiple options with arguments.
+/V            DOS/VMS-style options too
+
+There must be at least two spaces between the option and the
+description.
+
+Literal Blocks
+--------------
+
+Literal blocks are indicated with a double-colon ("::") at the end of
+the preceding paragraph (over there ``-->``).  They can be indented::
+
+    if literal_block:
+        text = 'is left as-is'
+        spaces_and_linebreaks = 'are preserved'
+        markup_processing = None
+
+Or they can be quoted without indentation::
+
+>> Great idea!
+>
+> Why didn't I think of that?
+
+Line Blocks
+-----------
+
+| This is a line block.  It ends with a blank line.
+|     Each new line begins with a vertical bar ("|").
+|     Line breaks and initial indents are preserved.
+| Continuation lines are wrapped portions of long lines;
+  they begin with a space in place of the vertical bar.
+|     The left edge of a continuation line need not be aligned with
+  the left edge of the text above it.
+
+| This is a second line block.
+|
+| Blank lines are permitted internally, but they must begin with a "|".
+
+Take it away, Eric the Orchestra Leader!
+
+    | A one, two, a one two three four
+    |
+    | Half a bee, philosophically,
+    |     must, *ipso facto*, half not be.
+    | But half the bee has got to be,
+    |     *vis a vis* its entity.  D'you see?
+    |
+    | But can a bee be said to be
+    |     or not to be an entire bee,
+    |         when half the bee is not a bee,
+    |             due to some ancient injury?
+    |
+    | Singing...
+
+Block Quotes
+------------
+
+Block quotes consist of indented body elements:
+
+    My theory by A. Elk.  Brackets Miss, brackets.  This theory goes
+    as follows and begins now.  All brontosauruses are thin at one
+    end, much much thicker in the middle and then thin again at the
+    far end.  That is my theory, it is mine, and belongs to me and I
+    own it, and what it is too.
+
+    -- Anne Elk (Miss)
+
+Doctest Blocks
+--------------
+
+>>> print 'Python-specific usage examples; begun with ">>>"'
+Python-specific usage examples; begun with ">>>"
+>>> print '(cut and pasted from interactive Python sessions)'
+(cut and pasted from interactive Python sessions)
+
+Tables
+------
+
+Here's a grid table followed by a simple table:
+
++------------------------+------------+----------+----------+
+| Header row, column 1   | Header 2   | Header 3 | Header 4 |
+| (header rows optional) |            |          |          |
++========================+============+==========+==========+
+| body row 1, column 1   | column 2   | column 3 | column 4 |
++------------------------+------------+----------+----------+
+| body row 2             | Cells may span columns.          |
++------------------------+------------+---------------------+
+| body row 3             | Cells may  | - Table cells       |
++------------------------+ span rows. | - contain           |
+| body row 4             |            | - body elements.    |
++------------------------+------------+----------+----------+
+| body row 5             | Cells may also be     |          |
+|                        | empty: ``-->``        |          |
++------------------------+-----------------------+----------+
+
+=====  =====  ======
+   Inputs     Output
+------------  ------
+  A      B    A or B
+=====  =====  ======
+False  False  False
+True   False  True
+False  True   True
+True   True   True
+=====  =====  ======
+
+Footnotes
+---------
+
+.. [1] A footnote contains body elements, consistently indented by at
+   least 3 spaces.
+
+   This is the footnote's second paragraph.
+
+.. [#label] Footnotes may be numbered, either manually (as in [1]_) or
+   automatically using a "#"-prefixed label.  This footnote has a
+   label so it can be referred to from multiple places, both as a
+   footnote reference ([#label]_) and as a hyperlink reference
+   (label_).
+
+.. [#] This footnote is numbered automatically and anonymously using a
+   label of "#" only.
+
+.. [*] Footnotes may also use symbols, specified with a "*" label.
+   Here's a reference to the next footnote: [*]_.
+
+.. [*] This footnote shows the next symbol in the sequence.
+
+.. [4] Here's an unreferenced footnote, with a reference to a
+   nonexistent footnote: [5]_.
+
+Citations
+---------
+
+.. [CIT2002] Citations are text-labeled footnotes. They may be
+   rendered separately and differently from footnotes.
+
+Here's a reference to the above, [CIT2002]_, and a [nonexistent]_
+citation.
+
+Targets
+-------
+
+.. _example:
+
+This paragraph is pointed to by the explicit "example" target. A
+reference can be found under `Inline Markup`_, above. `Inline
+hyperlink targets`_ are also possible.
+
+Section headers are implicit targets, referred to by name. See
+Targets_, which is a subsection of `Body Elements`_.
+
+Explicit external targets are interpolated into references such as
+"Python_".
+
+.. _Python: http://www.python.org/
+
+Targets may be indirect and anonymous.  Thus `this phrase`__ may also
+refer to the Targets_ section.
+
+__ Targets_
+
+Here's a `hyperlink reference without a target`_, which generates an
+error.
+
+Duplicate Target Names
+``````````````````````
+
+Duplicate names in section headers or other implicit targets will
+generate "info" (level-1) system messages.  Duplicate names in
+explicit targets will generate "warning" (level-2) system messages.
+
+Duplicate Target Names
+``````````````````````
+
+Since there are two "Duplicate Target Names" section headers, we
+cannot uniquely refer to either of them by name.  If we try to (like
+this: `Duplicate Target Names`_), an error is generated.
+
+Directives
+----------
+
+.. contents:: :local:
+
+These are just a sample of the many reStructuredText Directives.  For
+others, please see
+http://docutils.sourceforge.net/docs/ref/rst/directives.html.
+
+Document Parts
+``````````````
+
+An example of the "contents" directive can be seen above this section
+(a local, untitled table of contents_) and at the beginning of the
+document (a document-wide `table of contents`_).
+
+Images
+``````
+
+An image directive (also clickable -- a hyperlink reference):
+
+.. image:: images/title.png
+   :target: directives_
+
+A figure directive:
+
+.. figure:: images/title.png
+   :alt: reStructuredText, the markup syntax
+
+   A figure is an image with a caption and/or a legend:
+
+   +------------+-----------------------------------------------+
+   | re         | Revised, revisited, based on 're' module.     |
+   +------------+-----------------------------------------------+
+   | Structured | Structure-enhanced text, structuredtext.      |
+   +------------+-----------------------------------------------+
+   | Text       | Well it is, isn't it?                         |
+   +------------+-----------------------------------------------+
+
+   This paragraph is also part of the legend.
+
+A figure directive with center alignment
+
+.. figure:: images/title.png
+   :align: center
+   :width: 300
+
+Admonitions
+```````````
+
+.. Attention:: Directives at large.
+
+.. Caution::
+
+   Don't take any wooden nickels.
+
+.. DANGER:: Mad scientist at work!
+
+.. Error:: Does not compute.
+
+.. Hint:: It's bigger than a bread box.
+
+.. Important::
+   - Wash behind your ears.
+   - Clean up your room.
+   - Call your mother.
+   - Back up your data.
+
+.. Note:: This is a note.
+
+.. Tip:: 15% if the service is good.
+
+.. WARNING:: Strong prose may provoke extreme mental exertion.
+   Reader discretion is strongly advised.
+
+.. admonition:: And, by the way...
+
+   You can make up your own admonition too.
+
+Topics, Sidebars, and Rubrics
+`````````````````````````````
+
+.. sidebar:: Sidebar Title
+   :subtitle: Optional Subtitle
+
+   This is a sidebar.  It is for text outside the flow of the main
+   text.
+
+   .. rubric:: This is a rubric inside a sidebar
+
+   Sidebars often appears beside the main text with a border and
+   background color.
+
+.. topic:: Topic Title
+
+   This is a topic.
+
+.. rubric:: This is a rubric
+
+Target Footnotes
+````````````````
+
+.. target-notes::
+
+Replacement Text
+````````````````
+
+I recommend you try |Python|_.
+
+.. |Python| replace:: Python, *the* best language around
+
+Compound Paragraph
+``````````````````
+
+.. compound::
+
+   This paragraph contains a literal block::
+
+       Connecting... OK
+       Transmitting data... OK
+       Disconnecting... OK
+
+   and thus consists of a simple paragraph, a literal block, and
+   another simple paragraph.  Nonetheless it is semantically *one*
+   paragraph.
+
+This construct is called a *compound paragraph* and can be produced
+with the "compound" directive.
+
+Substitution Definitions
+------------------------
+
+An inline image (|example|) example:
+
+.. |EXAMPLE| image:: images/biohazard.png
+
+(Substitution definitions are not visible in the HTML source.)
+
+Comments
+--------
+
+Here's one:
+
+.. Comments begin with two dots and a space. Anything may
+   follow, except for the syntax of footnotes, hyperlink
+   targets, directives, or substitution definitions.
+
+   Double-dashes -- "--" -- must be escaped somehow in HTML output.
+
+(View the HTML source to see the comment.)
+
+Field Lists
+===========
+
+:Field List:
+    Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do
+    eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad
+    minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip
+    ex ea commodo consequat.
+
+    Duis aute irure dolor in reprehenderit in voluptate velit esse cillum
+    dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non
+    proident, sunt in culpa qui officia deserunt mollit anim id est laborum.
+
+some text
+
+:Field List 2: Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do eiusmod tempor
+
+Error Handling
+==============
+
+Any errors caught during processing will generate system messages.
+
+|*** Expect 6 errors (including this one). ***|
+
+There should be six messages in the following, auto-generated
+section, "Docutils System Messages":
+
+.. section should be added by Docutils automatically
+
+demo.rst from: http://docutils.sourceforge.net/docs/user/rst/demo.txt

doc/_build/html/_sources/_tmp/sphinx_rtd_theme/demo_docs/source/index.txt

@@ -0,0 +1,240 @@
+.. Sphinx RTD theme demo documentation master file, created by
+   sphinx-quickstart on Sun Nov  3 11:56:36 2013.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+=================================================
+Demo Docs
+=================================================
+
+:Page Status: Incomplete
+:Last Reviewed: 2013-10-29
+
+Contents:
+
+.. toctree::
+    :maxdepth: 2
+    :caption: Sweet Docs
+
+    demo
+    list
+
+.. toctree::
+    :titlesonly:
+
+    toc
+
+.. toctree::
+    :maxdepth: 2
+    :caption: This is an incredibly long caption for a long menu
+
+    long
+    api
+
+Maaaaath!
+=========
+
+This is a test.  Here is an equation:
+:math:`X_{0:5} = (X_0, X_1, X_2, X_3, X_4)`.
+Here is another:
+
+.. math::
+
+    \nabla^2 f =
+    \frac{1}{r^2} \frac{\partial}{\partial r}
+    \left( r^2 \frac{\partial f}{\partial r} \right) +
+    \frac{1}{r^2 \sin \theta} \frac{\partial f}{\partial \theta}
+    \left( \sin \theta \, \frac{\partial f}{\partial \theta} \right) +
+    \frac{1}{r^2 \sin^2\theta} \frac{\partial^2 f}{\partial \phi^2}
+
+
+Giant tables
+============
+
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+| Header 1   | Header 2   | Header 3  | Header 1   | Header 2   | Header 3  | Header 1   | Header 2   | Header 3  | Header 1   | Header 2   | Header 3  |
++============+============+===========+============+============+===========+============+============+===========+============+============+===========+
+| body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  |
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+| body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  |
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+| body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  |
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+| body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  | body row 1 | column 2   | column 3  |
++------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+------------+------------+-----------+
+
+Optional parameter args
+-----------------------
+
+At this point optional parameters `cannot be generated from code`_.
+However, some projects will manually do it, like so:
+
+This example comes from `django-payments module docs`_.
+
+.. class:: payments.dotpay.DotpayProvider(seller_id, pin[, channel=0[, lock=False], lang='pl'])
+
+   This backend implements payments using a popular Polish gateway, `Dotpay.pl <http://www.dotpay.pl>`_.
+
+   Due to API limitations there is no support for transferring purchased items.
+
+
+   :param seller_id: Seller ID assigned by Dotpay
+   :param pin: PIN assigned by Dotpay
+   :param channel: Default payment channel (consult reference guide)
+   :param lang: UI language
+   :param lock: Whether to disable channels other than the default selected above
+
+.. _cannot be generated from code: https://groups.google.com/forum/#!topic/sphinx-users/_qfsVT5Vxpw
+.. _django-payments module docs: http://django-payments.readthedocs.org/en/latest/modules.html#payments.authorizenet.AuthorizeNetProvider
+
+Code test
+=========
+
+.. parsed-literal::
+
+    # parsed-literal test
+    curl -O http://someurl/release-|version|.tar-gz
+
+
+.. code-block:: json
+
+    {
+    "windows": [
+        {
+        "panes": [
+            {
+            "shell_command": [
+                "echo 'did you know'",
+                "echo 'you can inline'"
+            ]
+            },
+            {
+            "shell_command": "echo 'single commands'"
+            },
+            "echo 'for panes'"
+        ],
+        "window_name": "long form"
+        }
+    ],
+    "session_name": "shorthands"
+    }
+
+Sidebar
+=======
+
+.. sidebar:: Ch'ien / The Creative
+
+    .. image:: static/yi_jing_01_chien.jpg
+
+    *Above* CH'IEN THE CREATIVE, HEAVEN
+
+    *Below* CH'IEN THE CREATIVE, HEAVEN
+
+The first hexagram is made up of six unbroken lines. These unbroken lines stand for the primal power, which is light-giving, active, strong, and of the spirit. The hexagram is consistently strong in character, and since it is without weakness, its essence is power or energy. Its image is heaven. Its energy is represented as unrestricted by any fixed conditions in space and is therefore conceived of as motion. Time is regarded as the basis of this motion. Thus the hexagram includes also the power of time and the power of persisting in time, that is, duration.
+
+The power represented by the hexagram is to be interpreted in a dual sense in terms of its action on the universe and of its action on the world of men. In relation to the universe, the hexagram expresses the strong, creative action of the Deity. In relation to the human world, it denotes the creative action of the holy man or sage, of the ruler or leader of men, who through his power awakens and develops their higher nature.
+
+Code with Sidebar
+=================
+
+.. sidebar:: A code example
+
+    With a sidebar on the right.
+
+.. literalinclude:: test_py_module/test.py
+    :language: python
+    :linenos:
+    :lines: 1-40
+
+Boxes
+=====
+
+.. tip::
+    Equations within a note
+    :math:`G_{\mu\nu} = 8 \pi G (T_{\mu\nu}  + \rho_\Lambda g_{\mu\nu})`.
+
+.. note::
+    Equations within a note
+    :math:`G_{\mu\nu} = 8 \pi G (T_{\mu\nu}  + \rho_\Lambda g_{\mu\nu})`.
+
+.. danger::
+    Equations within a note
+    :math:`G_{\mu\nu} = 8 \pi G (T_{\mu\nu}  + \rho_\Lambda g_{\mu\nu})`.
+
+.. warning::
+    Equations within a note
+    :math:`G_{\mu\nu} = 8 \pi G (T_{\mu\nu}  + \rho_\Lambda g_{\mu\nu})`.
+
+
+Inline code and references
+==========================
+
+`reStructuredText`_ is a markup language. It can use roles and
+declarations to turn reST into HTML.
+
+In reST, ``*hello world*`` becomes ``<em>hello world</em>``. This is
+because a library called `Docutils`_ was able to parse the reST and use a
+``Writer`` to output it that way.
+
+If I type ````an inline literal```` it will wrap it in ``<tt>``. You can
+see more details on the `Inline Markup`_ on the Docutils homepage.
+
+Also with ``sphinx.ext.autodoc``, which I use in the demo, I can link to
+:class:`test_py_module.test.Foo`. It will link you right my code
+documentation for it.
+
+.. _reStructuredText: http://docutils.sourceforge.net/rst.html
+.. _Docutils: http://docutils.sourceforge.net/
+.. _Inline Markup: http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-markup
+
+.. note:: Every other line in this table will have white text on a white background.
+            This is bad.
+
+    +---------+
+    | Example |
+    +=========+
+    | Thing1  |
+    +---------+
+    | Thing2  |
+    +---------+
+    | Thing3  |
+    +---------+
+
+Emphasized lines with line numbers
+==================================
+
+.. code-block:: python
+   :linenos:
+   :emphasize-lines: 3,5
+
+   def some_function():
+       interesting = False
+       print 'This line is highlighted.'
+       print 'This one is not...'
+       print '...but this one is.'
+
+
+Citation
+========
+
+Here I am making a citation [1]_, another [2]_ and another [3]_
+
+.. [1] This is the citation I made, let's make this extremely long so that we can tell that it doesn't follow the normal responsive table stuff.
+
+.. [2] This citation has some ``code blocks`` in it, maybe some **bold** and
+       *italics* too. Heck, lets put a link to a meta citation [3]_ too.
+
+.. [3] This citation will have two backlinks.
+
+======
+Images
+======
+
+.. figure:: static/yi_jing_01_chien.jpg
+
+    This is a caption for a figure.
+
+Download links
+==============
+
+:download:`This long long long long long long long long long long long long long long long download link should be blue with icon, and should wrap white-spaces <static/yi_jing_01_chien.jpg>`

doc/_build/html/_sources/_tmp/sphinx_rtd_theme/demo_docs/source/list.txt

@@ -0,0 +1,69 @@
+.. important::
+
+    wanna play a game?
+
+    - inside
+    - this
+
+      - list
+      - ``in the world``
+
+        - hi
+        - his
+
+          hi
+
+
+
+A list
+======
+
+- here
+  - is
+  - some
+    - list
+    - items
+    - `yahoo <http://www.yahoo.com>`_
+    - ``huh``
+- how
+- ``inline literall``
+- ``inline literall``
+- ``inline literall``
+
+Second list level
+-----------------
+
+- here is a list in a second-level section.
+- `yahoo <http://www.yahoo.com>`_
+- `yahoo <http://www.yahoo.com>`_
+
+  - `yahoo <http://www.yahoo.com>`_
+  - here is an inner bullet ``oh``
+
+    - one more ``with an inline literally``. `yahoo <http://www.yahoo.com>`_
+      
+      heh heh. child. try to beat this embed:
+
+      .. literalinclude:: test_py_module/test.py
+          :language: python
+          :linenos:
+          :lines: 1-10
+  - and another. `yahoo <http://www.yahoo.com>`_
+  - `yahoo <http://www.yahoo.com>`_
+  - ``hi``
+- and hehe
+
+But deeper down the rabbit hole
+"""""""""""""""""""""""""""""""
+
+- I kept saying that, "deeper down the rabbit hole". `yahoo <http://www.yahoo.com>`_
+
+  - I cackle at night `yahoo <http://www.yahoo.com>`_.
+- I'm so lonely here in GZ ``guangzhou``
+- A man of python destiny, hopes and dreams. `yahoo <http://www.yahoo.com>`_
+
+  - `yahoo <http://www.yahoo.com>`_
+
+    - `yahoo <http://www.yahoo.com>`_ ``hi``
+    - ``destiny``
+

doc/_build/html/_sources/_tmp/sphinx_rtd_theme/demo_docs/source/long.txt

@@ -0,0 +1,209 @@
+Long Sticky Nav
+===============
+
+This section demonstrates how the 'sticky_navigation' setting behaves when the menu is very long.  When this section is selected, it will make the menu and the main area scroll when you are at the top of the page.
+
+
+Example Menu 1
+--------------
+
+Just a place holder...
+
+
+Example Menu 2
+--------------
+
+Just a place holder...
+
+
+Example Menu 3
+--------------
+
+Just a place holder...
+
+
+Example Menu 4
+--------------
+
+Just a place holder...
+
+
+Example Menu 5
+--------------
+
+Just a place holder...
+
+
+Example Menu 6
+--------------
+
+Just a place holder...
+
+
+Example Menu 7
+--------------
+
+Just a place holder...
+
+
+Example Menu 8
+--------------
+
+Just a place holder...
+
+
+Example Menu 9
+--------------
+
+Just a place holder...
+
+
+Example Menu 10
+---------------
+
+Just a place holder...
+
+
+Example Menu 11
+---------------
+
+Just a place holder...
+
+
+Example Menu 12
+---------------
+
+Just a place holder...
+
+
+Example Menu 13
+---------------
+
+Just a place holder...
+
+
+Example Menu 14
+---------------
+
+Just a place holder...
+
+
+Example Menu 15
+---------------
+
+Just a place holder...
+
+
+Example Menu 16
+---------------
+
+Just a place holder...
+
+
+Example Menu 17
+---------------
+
+Just a place holder...
+
+
+Example Menu 18
+---------------
+
+Just a place holder...
+
+
+Example Menu 19
+---------------
+
+Just a place holder...
+
+
+Example Menu 20
+---------------
+
+Just a place holder...
+
+Example Submenu 1
+-----------------
+
+Just a place holder...
+
+Submenu 1
+~~~~~~~~~
+
+Just a place holder...
+
+Subsubmenu 1
+````````````
+
+Just a place holder...
+
+Subsubmenu 2
+````````````
+
+Just a place holder...
+
+Submenu 2
+~~~~~~~~~
+
+Just a place holder...
+
+Subsubmenu 1
+````````````
+
+Just a place holder...
+
+Submenu 3
+~~~~~~~~~
+
+Just a place holder...
+
+Submenu 4
+~~~~~~~~~
+
+Just a place holder...
+
+Submenu 5
+~~~~~~~~~
+
+Just a place holder...
+
+Example Submenu 2
+-----------------
+
+Just a place holder...
+
+Submenu 1
+~~~~~~~~~
+
+Just a place holder...
+
+Subsubmenu 1
+````````````
+
+Just a place holder...
+
+Submenu 2
+~~~~~~~~~
+
+Just a place holder...
+
+Subsubmenu 1
+````````````
+
+Just a place holder...
+
+Submenu 3
+~~~~~~~~~
+
+Just a place holder...
+
+Submenu 4
+~~~~~~~~~
+
+Just a place holder...
+
+Submenu 5
+~~~~~~~~~
+
+Just a place holder...

doc/_build/html/_sources/_tmp/sphinx_rtd_theme/demo_docs/source/toc.txt

@@ -0,0 +1,12 @@
+=========
+TOC Tests
+=========
+
+One
+===
+
+Two
+---
+
+Three
+`````

doc/_build/html/_sources/averagingModel.txt

@@ -22,7 +22,9 @@ Examples
    averagingModel dense;
    averagingModel dilute;
 
-Note: This examples list might not be complete - please have a look for other averaging models (averagingModel_XY) in this documentation.
+.. note::
+
+   This examples list might not be complete - please have a look for other averaging models (averagingModel_XY) in this documentation.
 
 Description
 """""""""""

doc/_build/html/_sources/cfdemSolverIB.txt

@@ -7,7 +7,7 @@ Description
 """""""""""
 
 "cfdemSolverIB" is a coupled CFD-DEM solver using CFDEMcoupling, an open source parallel coupled CFD-DEM framework, for calculating
-the dynamics between immersed bodies and the surrounding fluid. Being an implementation of an immersed boundary method it allows tackling problems where the body diameter exceeds the maximal size of a fluid cell. Using the toolbox of OpenFOAM(R)(*) the governing equations of the fluid are computed and the corrections of velocity and pressure field with respect to the body-movement information, gained from LIGGGHTS, are incorporated.
+the dynamics between immersed bodies and the surrounding fluid. Being an implementation of an immersed boundary method it allows tackling problems where the body diameter exceeds the maximal size of a fluid cell. Using the toolbox of OpenFOAM®(*) the governing equations of the fluid are computed and the corrections of velocity and pressure field with respect to the body-movement information, gained from LIGGGHTS, are incorporated.
 
 Code of this solver contributions by Alice Hager, JKU.
 

doc/_build/html/_sources/cfdemSolverPiso.txt

@@ -6,7 +6,7 @@ cfdemSolverPiso command
 Description
 """""""""""
 
-"cfdemSolverPiso" is a coupled CFD-DEM solver using CFDEMcoupling, an open source parallel coupled CFD-DEM framework. Based on pisoFoam(R)(*), a finite volume based solver for turbulent Navier-Stokes equations applying the PISO algorithm, "cfdemSolverPiso" has additional functionality for a coupling to the DEM code "LIGGGHTS". The volume averaged Navier-Stokes Equations are solved accounting for momentum exchange and volume displacement of discrete particles whose trajectories are calculated in the DEM code LIGGGHTS.
+"cfdemSolverPiso" is a coupled CFD-DEM solver using CFDEMcoupling, an open source parallel coupled CFD-DEM framework. Based on pisoFoam®(*), a finite volume based solver for turbulent Navier-Stokes equations applying the PISO algorithm, "cfdemSolverPiso" has additional functionality for a coupling to the DEM code "LIGGGHTS". The volume averaged Navier-Stokes Equations are solved accounting for momentum exchange and volume displacement of discrete particles whose trajectories are calculated in the DEM code LIGGGHTS.
 
 see:
 

doc/_build/html/_sources/cfdemSolverPisoSTM.txt

@@ -6,7 +6,7 @@ cfdemSolverPisoSTM command
 Description
 """""""""""
 
-"cfdemSolverPisoSTM" is a coupled CFD-DEM solver using CFDEMcoupling, an open source parallel coupled CFD-DEM framework. Based on pisoFoam(R)(*), a finite volume based solver for turbulent Navier-Stokes equations applying PISO algorithm, "cfdemSolverPisoSTM" has additional functionality for a coupling to the DEM code "LIGGGHTS" as well as a scalar transport equation. The volume averaged Navier-Stokes Equations are solved accounting for momentum exchange and volume displacement of discrete particles, whose trajectories are calculated in the DEM code LIGGGHTS. Scalar transport equations coupled to scalar properties of the particle phase, (e.g. convective heat transfer) in a fluid granular system can be modeled with "cfdemSolverPisoSTM".
+"cfdemSolverPisoSTM" is a coupled CFD-DEM solver using CFDEMcoupling, an open source parallel coupled CFD-DEM framework. Based on pisoFoam®(*), a finite volume based solver for turbulent Navier-Stokes equations applying PISO algorithm, "cfdemSolverPisoSTM" has additional functionality for a coupling to the DEM code "LIGGGHTS" as well as a scalar transport equation. The volume averaged Navier-Stokes Equations are solved accounting for momentum exchange and volume displacement of discrete particles, whose trajectories are calculated in the DEM code LIGGGHTS. Scalar transport equations coupled to scalar properties of the particle phase, (e.g. convective heat transfer) in a fluid granular system can be modeled with "cfdemSolverPisoSTM".
 
 see:
 

doc/_build/html/_sources/cfdemSolverPisoScalar.txt

@@ -6,7 +6,33 @@ cfdemSolverPisoScalar command
 Description
 """""""""""
 
-"cfdemSolverPisoScalar" is a coupled CFD-DEM solver using CFDEMcoupling, an open source parallel coupled CFD-DEM framework. Based on pisoFoam(R)(*), a finite volume based solver for turbulent Navier-Stokes equations applying PISO algorithm, "cfdemSolverPisoScalar" has additional functionality for a coupling to the DEM code "LIGGGHTS" as well as a scalar transport equation. The volume averaged Navier-Stokes Equations are solved accounting for momentum exchange and volume displacement of discrete particles, whose trajectories are calculated in the DEM code LIGGGHTS. The scalar transport equation is coupled to scalar properties of the particle phase, thus convective heat transfer in a fluid granular system can be modeled with "cfdemSolverPisoScalar".
+"cfdemSolverPisoScalar" is a coupled CFD-DEM solver using CFDEMcoupling, an open source parallel coupled CFD-DEM framework. Based on pisoFoam®(*), a finite volume based solver for turbulent Navier-Stokes equations applying PISO algorithm, "cfdemSolverPisoScalar" has additional functionality for a coupling to the DEM code "LIGGGHTS" as well as a scalar transport equation. The volume averaged Navier-Stokes Equations are solved accounting for momentum exchange and volume displacement of discrete particles, whose trajectories are calculated in the DEM code LIGGGHTS. The scalar transport equation is coupled to scalar properties of the particle phase, thus convective heat transfer in a fluid granular system can be modeled with "cfdemSolverPisoScalar".
+
+The transport equation uses a field "alphat" to calculate local kinematic turbulent thermal conductivities based on the laminar and turbulent Prandtl numbers. There can be source terms with the field Tsource and radiation.
+
+Necessary additional input is:
+
++---------+---------------------+--------------+------+
+| name    | location            | type         | unit |
++---------+---------------------+--------------+------+
+| T       | 0                   | scalar field | K    |
++---------+---------------------+--------------+------+
+| Tsource | 0                   | scalar field | K/s  |
++---------+---------------------+--------------+------+
+| alphat  | 0                   | scalar field | m²/s |
++---------+---------------------+--------------+------+
+| Pr      | transportProperties | scalar       | 1    |
++---------+---------------------+--------------+------+
+| Prt     | transportProperties | scalar       | 1    |
++---------+---------------------+--------------+------+
+
+The transport equation is:
+
+alphat = nut/Prt
+
+alphaEff = nu/Pr + alphat
+
+d(voidfraction*T)/dt + div(phi*T) - div(alphaEff*voidfraction grad(T)) = Tsource + SourceRadiation
 
 see:
 

doc/_build/html/_sources/clockModel.txt

@@ -21,7 +21,9 @@ Examples
 
    clockModel standardClock;
 
-Note: This examples list might not be complete - please look for other models (clockModel_XY) in this documentation.
+.. note::
+
+   This examples list might not be complete - please look for other models (clockModel_XY) in this documentation.
 
 Description
 """""""""""

doc/_build/html/_sources/dataExchangeModel.txt

@@ -22,12 +22,16 @@ Examples
    dataExchangeModel twoWayFiles;
    dataExchangeModel twoWayMPI;
 
-Note: This examples list might not be complete - please look for other models (dataExchangeModel_XY) in this documentation.
+.. note::
+
+   This examples list might not be complete - please look for other models (dataExchangeModel_XY) in this documentation.
 
 Description
 """""""""""
 
-The data exchange model performs the data exchange between the DEM code and the CFD code.
+The data exchange model performs the data exchange between LIGGGHTS® and the cfdemCloud within CFDEM®coupling toolbox. The exchanged data at least consits of positions, radii, velocities and forces.
+
+The twoWayMPI model is considered as the standard model, whereas the file-exchange is much slower and its purpose is debugging.
 
 Restrictions
 """"""""""""

doc/_build/html/_sources/fix_couple_cfd_force.txt

@@ -19,10 +19,18 @@ Examples
 fix	cfd  all couple/cfd couple_every 100 mpi
 fix cfd2 all couple/cfd/force
 
+fix cfd  all couple/cfd couple_every 100 mpi
+fix cfd2 all couple/cfd/force/implicit transfer_type yes
+
+fix cfd  all couple/cfd couple_every 100 mpi
+fix cfd2 all couple/cfd/force/implicit transfer_property name color type scalar-atom
+
 Description
 """""""""""
 
-The command couple/cfd/force can only be used in combination with :doc:`fix_couple_cfd <fix_couple_cfd>`. This model transfers the force that the fluid exceeds on each particle to the DEM calculation. At every coupling time step the force term, which contains contributions from all force models active in the CFD calculation, is passed on to LIGGGHTS(R). This (constant) term is then used in the particle calculations at every DEM time step until the next coupling takes place.
+The command couple/cfd/force can only be used in combination with :doc:`fix_couple_cfd <fix_couple_cfd>`. This model transfers the force that the fluid exceeds on each particle to the DEM calculation. At every coupling time step the force term, which contains contributions from all force models active in the CFD calculation, is passed on to LIGGGHTS®. This (constant) term is then used in the particle calculations at every DEM time step until the next coupling takes place.
+
+Additional information, as the LIGGGHTS® atom_type can be transferred to the CFDEMcoupling environment with the keywork transfer_type yes. Similar keywords are transfer_density, transfer_torque and the more general transfer_property. The syntax is transfer_property name "name" type "data-type". The data-type can be scalar-atom or vector-atom and this needs to be a per atom property previously defined.
 
 Restrictions
 """"""""""""