introduction.rst - sphere - GPU-based 3D discrete element method algorithm with optional fluid coupling
  HTML git clone git://src.adamsgaard.dk/sphere
   DIR Log
   DIR Files
   DIR Refs
   DIR LICENSE
       ---
       introduction.rst (1873B)
       ---
            1 Introduction
            2 ============
            3 
            4 ``sphere`` is used for three-dimensional DEM particle simulations with optional
            5 two-way coupled fluid flow. Simulation setup and post-processing are usually
            6 performed through the bundled Python API, while the compiled ``sphere`` binary
            7 executes the time integration.
            8 
            9 The source code can be built for either a CUDA GPU or an OpenMP CPU. See
           10 :doc:`quickstart` for current build requirements and commands.
           11 
           12 The ultimate aim of the ``sphere`` software is to simulate soft-bedded subglacial
           13 conditions, while retaining the flexibility to perform simulations of granular
           14 material in other environments.
           15 
           16 The purpose of this documentation is to provide the user with a walk-through of
           17 the workflow, data-analysis and visualization methods of ``sphere``. In
           18 addition, the ``sphere`` internals are exposed to provide a way to understand the
           19 numerical routines used by the discrete element method implementation.
           20 
           21 .. note:: Command examples in this document starting with the symbol ``$`` are
           22    meant to be executed in the shell of the operating system, and ``>>>`` means
           23    execution in Python. `IPython <http://ipython.org>`_ is an excellent,
           24    interactive Python shell.
           25 
           26 All numerical values in this document, the source code, and the configuration
           27 files are typeset with strict respect to the SI unit system.
           28 
           29 Workflow
           30 --------
           31 
           32 A typical simulation workflow is:
           33 
           34 #. Create a ``sphere.sim`` object in Python and write an input binary.
           35 #. Run ``./sphere`` on the input file, optionally with ``--fluid``.
           36 #. Read output binaries in Python for analysis, visualization, or export.
           37 
           38 Updating sphere
           39 ---------------
           40 
           41 To update your local version, type the following commands in the ``sphere`` root
           42 directory::
           43 
           44    git pull
           45    cmake -DSPHERE_GPU=OFF .
           46    make
           47 
           48 Use the CUDA default build by omitting ``-DSPHERE_GPU=OFF`` when CUDA is the
           49 intended backend.