Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Tutorial 4 - Lattice-Boltzmann #3893

Merged
merged 19 commits into from
Oct 8, 2020
Merged

Tutorial 4 - Lattice-Boltzmann #3893

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
19 commits
Select commit Hold shift + click to select a range
808e94f
Tutorial 04: Spell check and grammar check
jngrad Sep 11, 2020
bed58d9
python: Document LB parameters
jngrad Sep 11, 2020
c1aed23
tutorial 04: part 1: Update text
jngrad Sep 11, 2020
4dfbd96
tutorial 04: part 2: Simplify code
jngrad Sep 11, 2020
a9a94cf
tutorial 04: part 2: Provide solutions
jngrad Sep 11, 2020
32c410f
docs: Fix documentation
jngrad Sep 19, 2020
216a2fe
tutorial 04: part 3: Move solution to the notebook
jngrad Sep 19, 2020
20882e4
tutorial 04: part 3: Provide solutions
jngrad Sep 20, 2020
4595490
Merge branch 'python' into tutorial_04_summer_school_2020
jngrad Sep 26, 2020
7094cb0
Merge branch 'python' into tutorial_04_summer_school_2020
jngrad Oct 1, 2020
15956f9
tutorial 04: part 3: Proper error analysis
jngrad Oct 4, 2020
7d43fd6
tutorial 04: part 3: Green-Kubo diffusion coefficient
jngrad Oct 6, 2020
02e102f
tutorial 04: Add tutor notes
jngrad Oct 6, 2020
f7cd6ab
tutorial 04: part 4: Switch exercise
jngrad Oct 7, 2020
59984d1
tutorial 04: Create solution cells
jngrad Oct 7, 2020
b71581d
tutorial 04: part 1: Update text, add links
jngrad Oct 7, 2020
c7d42c8
tutorial 04: Polymer diffusion with implicit solvent
jngrad Oct 7, 2020
8469df0
tutorial 04: Remove mentions of LB
jngrad Oct 7, 2020
446fd10
Merge branch 'python' into tutorial_04_summer_school_2020
RudolfWeeber Oct 8, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
58 changes: 29 additions & 29 deletions doc/tutorials/04-lattice_boltzmann/04-lattice_boltzmann_part1.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,11 +9,12 @@
"#### Before you start:\n",
jngrad marked this conversation as resolved.
Show resolved Hide resolved
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I guess the equation should read 

\begin{align}
 \rho &= \sum_i f_i \
 \vec{j} = \rho \\
 \vec{u} &= \sum_i f_i \vec{c_i} \\
 \Pi^{\alpha \beta} &= \sum_i f_i \vec{c_i}^{\alpha}\vec{c_i}^{\beta}
 \label{eq:fields}
\end{align}

for better readability?


Reply via ReviewNB

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ReviewNB's support for LaTeX seems incomplete, the original equation looks good in Jupyter, with one equation per line

jngrad marked this conversation as resolved.
Show resolved Hide resolved
jngrad marked this conversation as resolved.
Show resolved Hide resolved
jngrad marked this conversation as resolved.
Show resolved Hide resolved
jngrad marked this conversation as resolved.
Show resolved Hide resolved
"\n",
"With this tutorial you can get started using the lattice-Boltzmann method\n",
"for scientific applications. We give a brief introduction about the theory\n",
"for hydrodynamics. We give a brief introduction about the theory\n",
"and how to use the method in **ESPResSo**. We have selected two interesting problems for\n",
"which LB can be applied and which are well understood. You can start with any of them.\n",
"\n",
"The tutorial is relatively long and working through it carefully is work for at least a full day. You can however get a glimpse of different aspects by starting to work on the tasks.\n",
"The tutorial is relatively long and working through it carefully will take at least a full day.\n",
"You can however get a glimpse of different aspects by starting to work on the tasks.\n",
"\n",
"Note: LB cannot be used as a black box. It is unavoidable to spend time\n",
"learning the theory and gaining practical experience."
Expand All @@ -28,14 +29,9 @@
"In this tutorial, you will learn the basics of the lattice-Boltzmann method (LBM) with\n",
"special focus on the application on soft matter simulations or more precisely on how to\n",
"apply it in combination with molecular dynamics to take into account hydrodynamic\n",
"solvent effects without the need to introduce thousands of solvent particles.\n",
"\n",
"The LBM – its theory as well as its applications – is still a very active field of research.\n",
"After almost 20 years of development there are many cases in which the LBM has proven\n",
"to be fruitful, in other cases the LBM is considered promising, and in some cases it has\n",
"not been of any help. We encourage you to contribute to the scientific discussion of\n",
"the LBM because there is still a lot that is unknown or only vaguely known about this\n",
"fascinating method.\n",
"solvent effects without the need to introduce thousands of solvent particles. The LBM\n",
"– its theory as well as its applications – is a very active field of research with\n",
"more than 30 years of development.\n",
"\n",
"### Tutorial Outline\n",
"\n",
Expand All @@ -46,7 +42,7 @@
"\n",
"* **Polymer diffusion.** We analyze the length dependence of the diffusion of polymers.\n",
"\n",
"* **Poiseuille flow.** We reproduce the flow profile between two walls.\n",
"* **Poiseuille flow.** We reproduce the flow profile of a fluid moving through a pipe under a homogeneous force density.\n",
"\n",
"### Notes on the **ESPResSo** version you will need\n",
"\n",
Expand All @@ -55,6 +51,7 @@
"\n",
"For the tutorial you will have to compile in the following features:\n",
"```c++\n",
"#define LB_BOUNDARIES\n",
"#define LB_BOUNDARIES_GPU\n",
"#define LENNARD_JONES\n",
"```\n",
Expand Down Expand Up @@ -96,7 +93,7 @@
"\n",
"The LBM discretizes the Boltzmann equation not only in real space (the lattice!) and\n",
"time, but also the velocity space is discretized. A surprisingly small number of velocities,\n",
"in 3D usually 19, is sufficient to describe incompressible, viscous flow correctly. Mostly\n",
"usually 19 in 3D, is sufficient to describe incompressible, viscous flow correctly. Mostly\n",
"we will refer to the three-dimensional model with a discrete set of 19 velocities, which is\n",
"conventionally called D3Q19. These velocities, $\\vec{c_i}$ , are chosen such that they correspond to\n",
"the movement from one lattice node to another in one time step. A two step scheme is\n",
Expand Down Expand Up @@ -149,7 +146,7 @@
"why the mode space is helpful. A 19 dimensional matrix that\n",
"conserves the first 4 modes (with the eigenvalue 1) is diagonal in the\n",
"first four rows and columns.\n",
"Some struggling with lattice symmetries shows that four independent\n",
"By symmetry consideration one finds that only four independent\n",
"variables are enough to characterize the linear relaxation\n",
"process so that all symmetries of the lattice are obeyed. \n",
"Two of them are closely related to \n",
Expand All @@ -171,9 +168,7 @@
"In other words: each mode is relaxed towards\n",
"its equilibrium value with a relaxation rate $\\gamma_i$.\n",
"The conserved modes are not relaxed, i.e. their relaxation rate is 1.\n",
"\n",
"By symmetry consideration one finds that only four independent\n",
"relaxation rates are allowed. We summarize them here.\n",
"We summarize them here:\n",
"\n",
"\\begin{align*}\n",
" m^\\star_i &= \\gamma_i m_i \\\\\n",
Expand All @@ -188,7 +183,8 @@
"random fluctuations are added to the nonconserved modes $5\\dots 19$ on every LB node so that\n",
"the LB fluid temperature is well defined and the corresponding\n",
"fluctuation formula holds, according to the fluctuation dissipation theorem.\n",
"An extensive discussion of this topic is found in [3]."
"An extensive discussion of this topic is found in [3].\n",
"Thermalization of the fluid is optional in **ESPResSo**."
]
},
{
Expand All @@ -197,7 +193,7 @@
"source": [
"### Particle coupling\n",
"\n",
"In **ESPResSo** particles are coupled to the LB fluid via the so called the force coupling method:\n",
"In **ESPResSo** particles are coupled to the LB fluid via the so-called force coupling method:\n",
"the fluid velocity $\\vec{u}$ at the position of a particle is calculated \n",
"via trilinear interpolation and a force is applied on the particle\n",
"that is proportional to the velocity difference between particle and fluid:\n",
Expand All @@ -224,8 +220,12 @@
"source": [
"## 3 The LB interface in ESPResSo\n",
"\n",
"**ESPResSo** features two virtually independent implementations of LB. One implementation uses CPUs and one uses a GPU to perform the computational work. For this, we provide two actor classes <tt>LBFluid</tt> and <tt>LBFluidGPU</tt> in the module <tt>espressomd.lb</tt>,\n",
"as well as the optional <tt>LBBoundary</tt> class found in <tt>espressomd.lbboundaries</tt>.\n",
"**ESPResSo** features two virtually independent implementations of LB. One implementation uses CPUs and one uses a GPU to perform the computational work. For this, we provide two actor classes\n",
"[<tt>LBFluid</tt>](http://espressomd.org/html/doc/espressomd.html#espressomd.lb.LBFluid) and\n",
"[<tt>LBFluidGPU</tt>](http://espressomd.org/html/doc/espressomd.html#espressomd.lb.LBFluidGPU) in the module\n",
"[<tt>espressomd.lb</tt>](http://espressomd.org/html/doc/espressomd.html#module-espressomd.lb), as well as the optional\n",
"[<tt>LBBoundary</tt>](http://espressomd.org/html/doc/espressomd.html#espressomd.lbboundaries.LBBoundary) class found in\n",
"[<tt>espressomd.lbboundaries</tt>](http://espressomd.org/html/doc/espressomd.html#module-espressomd.lbboundaries).\n",
"\n",
"The LB lattice is a cubic lattice, with a lattice constant <tt>agrid</tt> that\n",
"is the same in all spatial directions. The chosen box length must be an integer multiple\n",
Expand Down Expand Up @@ -268,9 +268,11 @@
"+ <tt>agrid</tt>: The lattice constant of the fluid. It is used to determine the number of LB nodes per direction from <tt>box_l</tt>. *They have to be compatible.*\n",
"+ <tt>visc</tt>: The kinematic viscosity\n",
"+ <tt>tau</tt>: The time step of LB. It has to be an integer multiple of <tt>System.time_step</tt>.\n",
"+ <tt>kT</tt>: Thermal energy of the simulated heat bath for thermalized fluids, use 0 to deactivate thermalization.\n",
"+ <tt>seed</tt>: The random number generator seed, only relevant for thermalized fluids (i.e. <tt>kT</tt> \\> 0).\n",
"+ <tt>ext_force_density</tt>: An external force density applied to every node. This is given as a list, tuple or array with three components.\n",
"\n",
"Using these arguments, one can initialize an <tt>LBFluid</tt> object. This object then needs to be added to the system's actor list. The code below provides a minimum example.\n",
"Using these arguments, one can initialize an <tt>LBFluid</tt> object. This object then needs to be added to the system's actor list. The code below provides a minimal example.\n",
"\n",
"```python\n",
"import espressomd\n",
Expand All @@ -281,7 +283,7 @@
"system.time_step = 0.01\n",
"system.cell_system.skin = 0.4\n",
"\n",
"# Initialize and LBFluid with the minimum set of valid parameters.\n",
"# Initialize an LBFluid with the minimum set of valid parameters.\n",
"lbf = lb.LBFluidGPU(agrid=1, dens=10, visc=.1, tau=0.01)\n",
"# Activate the LB by adding it to the System's actor list.\n",
"system.actors.add(lbf)\n",
Expand Down Expand Up @@ -313,15 +315,13 @@
"source": [
"### The <tt>LBBoundary</tt> class\n",
"\n",
"The <tt>LBBoundary</tt> class represents a boundary on the <tt>LBFluid</tt>\n",
"lattice. It depends on the classes of the module <tt>espressomd.shapes</tt> as it derives its geometry from them. For the initialization, the arguments <tt>shape</tt> and <tt>velocity</tt> are supported. The <tt>shape</tt> argument takes an object from the <tt>shapes</tt> module and the <tt>velocity</tt> argument expects a list, tuple or array containing 3 floats. Setting the <tt>velocity</tt> will results in a slip boundary condition.\n",
"The [<tt>LBBoundary</tt>](http://espressomd.org/html/doc/espressomd.html#espressomd.lbboundaries.LBBoundary) class represents a boundary on the\n",
"[<tt>LBFluid</tt>](http://espressomd.org/html/doc/espressomd.html#espressomd.lb.LBFluid) lattice.\n",
"It depends on the classes of the module <tt>espressomd.shapes</tt> as it derives its geometry from them. For the initialization, the arguments <tt>shape</tt> and <tt>velocity</tt> are supported. The <tt>shape</tt> argument takes an object from the <tt>shapes</tt> module and the <tt>velocity</tt> argument expects a list, tuple or array containing 3 floats. Setting the <tt>velocity</tt> will result in a slip boundary condition.\n",
"\n",
"Note that the boundaries are not constructed through the periodic boundary. If, for example, one would set a sphere with its center in one of the corner of the boxes, a sphere fragment will be generated. To avoid this, make sure the sphere, or any other boundary, fits inside the central box.\n",
"\n",
"This part of the LB implementation is still experimental, so please tell us about your experience with it. In general even the simple case of no-slip\n",
"boundary is still an important research topic in the LB community and in combination with point particle coupling not much experience exists. This means: do research on that topic, play around with parameters and figure out what happens.\n",
"\n",
"Boundaries are initialized by passing a shape object to the <tt>LBBoundary</tt> class. One way to initialize a wall is:\n",
"Boundaries are instantiated by passing a shape object to the <tt>LBBoundary</tt> class. Here is one way to construct a wall and add it to an existing `system` instance:\n",
"\n",
"```python\n",
"import espressomd.lbboundaries\n",
Expand All @@ -332,7 +332,7 @@
"system.lbboundaries.add(wall)\n",
"```\n",
"\n",
"Note that all used variables are inherited from previous examples. This will create a wall with a surface normal of $(1, 0, 0)$ at a distance of 1 from the origin of the coordinate system in direction of the normal vector. The wall exhibits a slip boundary condition with a velocity of $(0, 0, 0.01)$. For a no-slip boundary condition, leave out the velocity argument or set it to zero. Please refer to the user guide for a complete list of constraints.\n",
"This will create a wall with a surface normal of $(1, 0, 0)$ at a distance of 1 from the origin of the coordinate system in direction of the normal vector. The wall exhibits a slip boundary condition with a velocity of $(0, 0, 0.01)$. For a no-slip boundary condition, leave out the velocity argument or set it to zero. Please refer to the user guide for a complete list of constraints.\n",
"\n",
"In **ESPResSo** the so-called *link bounce back* method is implemented, where the effective hydrodynamic boundary is located midway between boundary and fluid node."
]
Expand Down
Loading