Restructure sphinx documentation

This is a suggestion for a new structure of the sphinx documentation.

Main changes are:

Improved order
Dump special methods in new chapter 'Advanced methods'
Purely physical explanations (MMM, MEMD...) in appendix
Split large interaction chapter

For a quick overview, here is the first level:

Introduction
Getting, compiling and running ESPResSo
Setting up the system
Setting up particles
Running the simulation
Non-bonded interactions
Bonded interactions
Electrostatics
Magnetostatics
Global particle manipulation
Constraints
Lattice-Boltzmann
Analysis
Input / Output
Online-Visualization
Advanced Methods
Under the hood
Getting involved
Appendix

Some flags mark the issues I saw while running through: \U Update \E Extend \P Missing interface/python doc \R Remove?

And here the full tree:

Introduction
- Guiding principles
- Basic program structure
- Basic python simulation script
- Tutorials
- Sample scripts
- On units
- Available simulation methods \U
Getting, compiling and running ESPResSo
- Requirements
  - Ubuntu 16.04 LTS
  - Mac OS X
  - Python dependencies
- Quick installation
- Configuring
  - myconfig.hpp: Activating and deactivating features
  - Features \U
    - General features
    - Fluid dynamics and fluid structure interaction
    - Interactions
    - DNA Model (Fyta DNA)
    - Miscellaneous
    - Debug messages
  - cmake
  - ccmake
    - Options and Variables
- make: Compiling, testing and installing
- Running ESPResSo
- Debugging ESPResSo
Setting up the system
- Global variables in Python
  - Accessing module states
- The cell system
  - Global properties
  - Domain decomposition
  - N-squared
  - Layered cell system
- Thermostat
  - Langevin thermostat
  - GHMC thermostat \P
  - Dissipative Particle Dynamics (DPD)
  - Isotropic NPT thermostat
- CUDA
  - GPU Acceleration with CUDA
    - List available CUDA devices
    - Selection of CUDA device
Setting up particles
- Overview of the relevant Python classes
- Adding particles
- Accessing particle properties
  - Vectorial properties
- Interacting with groups of particles
- Deleting particles
- Iterating over particles and pairs of particles
- Exclusions
- Create particular particle configurations
  - polymer: Setting up polymer chains
  - diamond: Setting up diamond polymer networks
  - icosaeder: Setting up an icosaeder \P
  - crosslink: Cross-linking polymers \P
- Virtual sites
  - Rigid arrangements of particles
  - Virtual sites in the center of mass of a molecule \P
  - Additional features \R
- Grand canonical feature
- Self-propelled swimmers
- Langevin swimmers
  - Lattice-Boltzmann (LB) swimmers
Running the simulation
- Integrator
- Run steepest descent minimization
- Changing the box volume
- Stopping particles
- Multi-timestepping
- Integrating rotational degrees of freedom
Non-bonded interactions
- Isotropic non-bonded interactions
  - Tabulated interaction
  - Lennard-Jones interaction
  - Generic Lennard-Jones interaction
  - Lennard-Jones cosine interaction
  - Smooth step interaction
  - BMHTF potential
  - Morse interaction
  - Buckingham interaction
  - Soft-sphere interaction
  - Membrane-collision interaction \P
  - Hat interaction
  - Hertzian interaction
  - Gaussian
  - DPD interaction
- Anisotropic non-bonded interactions
  - Directional Lennard-Jones interaction \P
  - Gay-Berne interaction
  - Affinity interaction \P
Bonded interactions
- Distance dependent bonds
  - FENE bond
  - Harmonic bond
  - Harmonic Dumbbell Bond
  - Quartic bond \P
  - Bonded coulomb \P
  - Subtracted Lennard-Jones bond \P
  - Rigid bonds
  - Tabulated bond interactions
    - Calculation of the force and energy
  - Virtual bonds
- Bond-angle interactions
- Dihedral interactions \E
Electrostatics
- 3D Methods
  - Coulomb P3M \E
    - Tuning Coulomb P3M
    - Coulomb P3M on GPU
  - Coulomb Ewald GPU
    - Tuning Ewald GPU
    - Tuning Alpha Ewald GPU \P
  - Debye-Hückel potential
  - Dielectric interfaces with the ICC⋆ algorithm
  - Maxwell Equation Molecular Dynamics (MEMD) \P
    - Spatially varying dielectrics with MEMD
    - Adaptive permittivity with MEMD
- 2D Methods
  - MMM2D
  - Electrostatic Layer Correction (ELC)
- 1D Methods
  - MMM1D
- Dipolar interactions \P
  - Dipolar P3M
    - Tuning dipolar P3M
  - Dipolar Layer Correction (DLC)
  - Dipolar all-with-all and no replicas (DAWAANR)
- Scafacos Electrostatics
Magnetostatics
- Magnetic Dipolar Direct Sum (MDDS) on CPU \P
- Dipolar direct sum on gpu
- Scafacos Magnetostatics
Global particle manipulation
- Fixing the center of mass \P
- Capping the force during warmups
- Galilei Transform and Particle Velocity Manipulation
  - Particle motion and rotation
  - Forces and torques acting on the particles
  - The centre of mass of the system
  - The centre-of-mass velocity
  - The Galilei transform
Constraints
- Shape-based constraints
  - Adding a shape-based constraint
  - Deleting a constraint
  - Getting the currently defined constraints
  - Getting the force on a constraint
  - Getting the minimal distance to a constraint \P
- harmonic_well: Creating a harmonic trap \P
- Homogeneous Magnetic Field \E
Lattice-Boltzmann
- Setting up a LB fluid
- Checkpointing
- LB as a thermostat
- The Shan Chen bicomponent fluid \P
  - SC as a thermostat
  - SC component-dependent interactions between particles
- Reading and setting properties of single lattice nodes
- Removing total fluid momentum
- Visualization
- Setting up boundary conditions
- Choosing between the GPU and CPU implementations
- Electrohydrodynamics
- Using shapes as Lattice-Boltzmann Boundary
  - Adding shape based Lattice-Boltzmann Boundary
  - Usage example
Analysis
- Observables
  - Introduction
  - Creating an observable
  - Available observables overview
  - Available observables
    - Minimal distances between particles
    - Particles in the neighbourhood \E
    - Particle distribution
    - Radial density map \P
    - Cylindrical Average
    - Vkappa
    - Radial distribution function
    - Structure factor
    - Van-Hove autocorrelation function G(r,t) \P
    - Center of mass
    - Moment of inertia matrix
    - Gyration tensor
    - Aggregation \P
    - Finding holes \P
    - Temperature of the LB fluid \P
    - Momentum of the System
    - Energies
    - Pressure
    - Stress Tensor
    - Local Stress Tensor
    - Chains
      - End-to-end distance
      - Radius of gyration
      - Hydrodynamic radius
      - Internal distances \P
      - Internal distances II (specific monomer) \P
      - Bond lengths \P
      - Form factor \P
      - Chain radial distribution function
- Correlations
  - Introduction
  - Creating a correlation
  - Example: Calculating a particle’s diffusion coefficient
  - The correlation algorithm: multiple tau correlator \P \E
Input / Output
- No generic checkpointing!
- (Almost) generic checkpointing in Python
- Writing H5MD-files
- Writing VTF files
  - writevsf: Writing the topology \P
  - writevcf: Writing the coordinates \P
  - vtfpid: Translating particles ids to VMD particle ids \P
- Writing various formats using MDAnalysis
Online-Visualization
- General usage
- Common methods for openGL and mayavi
- Mayavi visualizer
- OpenGL visualizer
  - Colors and Materials
  - Controls
  - Dragging particles
- Visualization example scripts
Advanced Methods
- Creating bonds when particles collide
- Catalytic Reactions
- nemd: Setting up non-equilibrium MD \P
- Lees-Edwards boundary condition: Setting up a shear flow
- Immersed Boundary Method for soft elastic objects \P
- Object-in-fluid \P
  - Membranes
  - Parameters
  - Geometry
  - Available commands
    - Initialisation
    - Information about object-in-fluid structures
    - Templates for objects
    - Elastic objects
    - Mesh analysis
    - Output information about specific object
    - Descriptive information about specific object
    - Setting properties for specific object
  - Object-in-fluid interactions
    - OIF local forces
      - Stretching
      - Bending
      - Local area conservation
    - OIF global forces
      - Global area conservation
      - Volume conservation
    - Out direction
- Electrokinetics \P
  - Electrokinetic Equations
  - Setup
    - Initialization
    - Diffusive Species
    - Boundaries
  - Output
    - Fields
    - Local Quantities
  - Checkpointing
  - Catalytic Reaction
    - Concept
    - Initialization and Geometry Definition
    - Parsing PDB Files
Under the hood \E
- Internal particle organization
Getting involved
- Community support and mailing lists
- Contributing your own code
- Developers’ guide
- User’s guide
Appendix
- The MMM family of algorithms
  - Introduction
  - MMM2D
    - Dielectric contrast
  - MMM1D
  - ELC
  - Errors
- Maxwell Equations Molecular Dynamics (MEMD)
  - Equations of motion
  - Discretization
  - Initialization of the algorithm
  - Time integrator
  - Self–energy
  - For which systems to use the algorithm
- Reaction Ensemble
  - Converting tabulated reaction constants to internal units in Espresso
  - Wang-Landau Reaction Ensemble
  - Constant pH simulation using the Reaction Ensemble
  - Grand canonical ensemble simulation using the Reaction Ensemble

espressomd / espresso

Restructure sphinx documentation #1778