README.rst 7.57 KB
Newer Older
1 2 3 4
.. image:: https://badges.gitter.im/Join%20Chat.svg
   :alt: Join the chat at https://gitter.im/anders-dc/sphere
   :target: https://gitter.im/anders-dc/sphere?utm_source=badge&utm_medium=badge&utm_campaign=pr-badge&utm_content=badge

Anders Damsgaard's avatar
Anders Damsgaard committed
5 6
=============
sphere readme
7
=============
8 9 10
``sphere`` is a 3D discrete element method algorithm utilizing CUDA. ``sphere``
allows for optional simulation of two-way coupled fluid flow using the
Navier-Stokes or Darcy formulations.
11

12
A powerful Nvidia GPU with proper support for double precision floating is
13 14
highly recommended. ``sphere`` has been tested with Nvidia Tesla GPUs, and has 
successfully been employed on the clusters `Grendel 
15
<https://www.cscaa.dk/grendel/hardware/>`_ (Aarhus University), `ICME 
16
<https://icme.stanford.edu/computer-resources/gpu-cluster>`_ (Stanford 
17
University), `Comet <https://www.sdsc.edu/services/hpc/hpc_systems.html#comet>`_ 
18 19 20 21
(San Diego Supercomputing Center),  `Bridges 
<https://psc.edu/index.php/resources/computing/bridges>`_ (Portland 
Supercomputing Center), and `Stampede <https://www.tacc.utexas.edu/stampede/>`_ 
(Texas Advanced Supercomputing Center).
22

23 24 25
License
-------
``sphere`` is licensed under the GNU General Public License, v.3.
26
See `LICENSE.txt <LICENSE.txt>`_ for more information.
27

28 29
Important release notes
-----------------------
30 31
2017-09-07: CUDA 8 comes with new requirements to the host CC/C++ compiler.  If 
GCC5 is not available on the system, run the following command before invoking 
32
`make`::
33 34

    export CC=$(which clang-3.8) && export CXX=$(which clang++-3.8) && cmake .
35

36 37
2016-08-16: Scale-invariant grain-contact model implemented based on Ergenzinger 
et al 2010 and Obermayr et al 2013.  To use specify a positive Young's modulus 
38 39 40
with ``setYoungsModulus(<value>)`` in the Python module.  This overrides any 
contact stiffnesses specified in ``k_n`` and ``k_t``.  This command should be 
used before the timestep length is determined in ``initTemporal(...)``.
41 42

2016-08-14: Dirichlet and von Neumann horizontal boundary conditions implemented 
43
in addition to horizontal periodicity for the Darcian fluid solver.
44

Anders Damsgaard's avatar
Anders Damsgaard committed
45 46 47
2015-09-06: A new flux boundary condition has been added to the Darcy fluid
solver.

48
2014-11-05: A Darcy solver has been added as an alternative to the Navier-Stokes
Anders Damsgaard's avatar
Anders Damsgaard committed
49 50
solver of the fluid phase. It can be selected with e.g. ``initFluid(cfd_solver =
1)`` in the Python module.
51

Anders Damsgaard's avatar
Anders Damsgaard committed
52
2014-07-28: Fluid flow is no longer simulated in a separate program. Use
Anders Damsgaard's avatar
Anders Damsgaard committed
53
``sphere`` with the command line argument ``-f`` or ``--fluid`` instead.
Anders Damsgaard's avatar
Anders Damsgaard committed
54

55 56
2014-07-05: Fluid phase now discretized on a staggered grid which increases
accuracy and stability.
57

58 59
2014-03-25: Fluid phase in ``master`` branch simulated by the full Navier-Stokes
equations.
60

61 62
2014-03-09: The ``writebin`` member function of the ``sim`` class is now
implicitly called when calling the ``run`` member function.
63

64 65 66
2014-03-09: The main sphere class (formerly ``spherebin``) has been renamed to
``sim``.

67 68 69
2014-01-20: Version fingerprints have been added to the input/output binary
files, and causes old files to be incompatible with either ``sphere`` or
``sphere.py``.
70

71 72
2014-01-25: The description of the installation procedure is moved to the
general documentation.
73

74
2013-03-13: Sphere has been updated to work with CUDA 5.0 or newer *only*.
75

76 77
Documentation
-------------
78 79
See the separate documentation for general reference and installation
instructions. The documentation is by default available in
80
the `html <doc/html/index.html>`_ and `pdf <doc/pdf/sphere.pdf>`_ formats.
81

82 83
Examples
--------
84
All examples are visualized using `ParaView <https://www.paraview.org>`_.
85 86

.. figure:: doc/sphinx/img/stokes.png
Anders Damsgaard's avatar
Anders Damsgaard committed
87
   :scale: 75%
88 89
   :alt: Particle falling through fluid grid

Anders Damsgaard's avatar
Anders Damsgaard committed
90
   A particle moving downwards through a fluid column causing fluid flow.
91 92 93 94 95

.. figure:: doc/sphinx/img/diff.png
   :scale: 100%
   :alt: Consolidation test

Anders Damsgaard's avatar
Anders Damsgaard committed
96
   Consolidation test of a particle/fluid assemblage.
97 98 99 100 101 102

.. figure:: doc/sphinx/img/shear.png
   :scale: 100%
   :alt: Shear test

   Shear of a dense particle assemblage. Top left: particles colored by initial
Anders Damsgaard's avatar
Anders Damsgaard committed
103
   positions, top center: particles colored by horizontal velocity, top right:
104 105 106
   particles colored by pressure. Bottom left: fluid pressures, bottom center:
   porosities, bottom right: porosity changes.

Anders Damsgaard's avatar
Anders Damsgaard committed
107 108 109
Publications
------------
``sphere`` has been used to produce results in the following scientific
Anders Damsgaard's avatar
Anders Damsgaard committed
110
publications and presentations:
Anders Damsgaard's avatar
Anders Damsgaard committed
111

112 113 114 115 116
- Damsgaard, A., J. Suckale, J. A. Piotrowski, M. Houssais, M. R. Siegfried, H.
  A. Fricker (2017), Sediment behavior controls equilibrium width of subglacial
  channels, Journal of Glaciology, 
  `doi:10.1017/jog.2017.71 
  <https://doi.org/10.1017/jog.2017.71>`_.
117 118 119 120
- Damsgaard, A., A. Cabrales-Vargas, J. Suckale, and L. Goren (2017), The 
  coupled dynamics of meltwater percolation and granular deformation in the 
  sediment layer underlying parts of the big ice sheets, Poromechanics VI, 
  `doi:10.1061/9780784480779.024 
121
  <https://doi.org/10.1061/9780784480779.024>`_.
122 123 124
- Damsgaard, A., D.L. Egholm, L.H. Beem, S. Tulaczyk, N.K. Larsen, J.A.  
  Piotrowski, and M.R. Siegfried (2016), Ice flow dynamics forced by water 
  pressure variations in subglacial granular beds, Geophysical Research Letters, 
125
  43, `doi:10.1002/2016GL071579 <https://doi.org/10.1002/2016GL071579>`_.
Anders Damsgaard's avatar
Anders Damsgaard committed
126 127
- Damsgaard, A., D.L. Egholm, J.A. Piotrowski, S. Tulaczyk, N.K. Larsen, and
  C.F. Brædstrup (2015), A new methodology to simulate subglacial deformation of
Anders Damsgaard's avatar
Anders Damsgaard committed
128
  water-saturated granular material, The Cryosphere, 9, 2183-2200,
129
  `doi:10.5194/tc-9-2183-2015 <https://doi.org/10.5194/tc-9-2183-2015>`_.
130 131 132 133 134
- Damsgaard, A., D.L. Egholm, J.A. Piotrowski, S. Tulaczyk, N.K. Larsen, and
  C.F. Brædstrup (2014), Numerical modeling of particle-fluid mixtures in a
  subglacial setting. `Poster at Americal Geophysical Union Fall Meeting
  <https://cs.au.dk/~adc/files/AGU2014-Poster.pdf>`_.
- Damsgaard, A., D.L. Egholm, J.A. Piotrowski, S. Tulaczyk, N.K. Larsen, and
Anders Damsgaard's avatar
Anders Damsgaard committed
135 136
  K. Tylmann (2013), Discrete element modeling of subglacial sediment
  deformation, J. Geophys. Res. Earth Surf., 118, 2230–2242,
137
  `doi:10.1002/2013JF002830 <https://doi.org/10.1002/2013JF002830>`_.
138 139 140 141 142 143 144 145 146 147 148 149 150 151
- Damsgaard, A., D.L. Egholm, J.A. Piotrowski, S. Tulaczyk, and N.K. Larsen
  (2013), Discrete element modeling of subglacial sediment deformation.
  Talk at American Geophysical Fall Meeting 2013.
- Damsgaard, A., D.L. Egholm, J.A. Piotrowski, S. Tulaczyk, and N.K. Larsen
  (2013), Numerical modelling of granular subglacial deformation using the
  discrete element method. `Poster at European Geosciences Union General
  Assembly 2013
  <https://cs.au.dk/~adc/files/EGU2013-Poster.pdf>`_.
- Damsgaard, A., D.L. Egholm, J.A. Piotrowski, and S. Tulaczyk
  (2012), Discrete element modelling of subglacial sediment deformation.
  `Poster at European Geosciences Union General Assembly 2012
  <https://cs.au.dk/~adc/files/EGU2012-Poster.pdf>`_.
- Damsgaard, A., D.L. Egholm, and J.A. Piotrowski
  (2011), Numerical modelling of sediment deformation by glacial stress.
Anders Damsgaard's avatar
Anders Damsgaard committed
152
  `Poster at International Union for Quaternary Research Congress 2011
153 154 155 156 157
  <https://cs.au.dk/~adc/files/INQUA2011-Poster.pdf>`_.
- Damsgaard, A., D.L. Egholm, and J.A. Piotrowski
  (2011), Numerical modelling of subglacial sediment deformation.
  `Poster at European Geosciences Union General Assembly 2011
  <https://cs.au.dk/~adc/files/EGU2011-Poster.pdf>`_.
Anders Damsgaard's avatar
Anders Damsgaard committed
158

159 160 161 162
If you use `sphere` for scientific publications, please get in touch to add your
entry to the above list. It would be appreciated if the `sphere` development is
acknowledged by citing one of the above *Damsgaard et al.* publications.

163 164
Author
------
165 166
Anders Damsgaard, `andersd@princeton.edu <mailto:andersd@princeton.edu>`_,
`webpage <https://adamsgaard.dk>`_.